@intomind/sdk 0.0.0-stage → 1.4.1

package/dist/protocol.d.ts

@@ -0,0 +1,1433 @@
+/**
+ * The IntoMind BLE protocol, version 1.0.
+ *
+ * This module is the wire and nothing else. It has no device in it, no
+ * transport, no state, and no opinion about what a caller does with a
+ * message. Every function takes bytes and returns what the contract says
+ * those bytes mean, or throws a `ProtocolError` saying why they are not a
+ * message.
+ *
+ * It is held to `contract/conformance.json`, which the firmware emits from
+ * the codec it runs. Every message here decodes those vectors to the stated
+ * fields and refuses the malformed ones for the stated reason, so this
+ * implementation and the device cannot drift apart without a test failing.
+ *
+ * Three things are worth knowing before reading further.
+ *
+ * **Capabilities are the device's answer.** What a device can do is in the
+ * bits it reports, never in a table of hardware here. A device that does not
+ * claim a capability is not asked for it.
+ *
+ * **The timeline is never silently repaired.** A forward step in the sample
+ * index is a loss with an exact count. A step that is not forward is a break
+ * whose extent is not a number, and this module says so rather than
+ * returning a count that would be a fiction.
+ *
+ * **Nothing is assumed about width.** The number of channels, the converter
+ * resolution, the reference voltage, and the tick rate all come from the
+ * device, and the scaling helper takes them as arguments.
+ */
+export { Crc32, crc32, sha256 } from "./digest.ts";
+/** The protocol version this module implements, major and minor. */
+export declare const VERSION: readonly [number, number];
+/** The full identifier for one characteristic. */
+export declare function uuid(fill: number): string;
+/**
+ * The sixteen bit fill each characteristic sits at. A notification is
+ * routed by this rather than by its full identifier, so nothing downstream
+ * has to format or compare strings.
+ */
+export declare const FILL: {
+    readonly SERVICE: 1;
+    readonly DEVICE_INFO: 2;
+    readonly CONTROL: 3;
+    readonly CONTROL_RESPONSE: 4;
+    readonly EEG_DATA: 5;
+    readonly STATUS: 6;
+    /** Held by an earlier development firmware. Never reused. */
+    readonly RESERVED_0007: 7;
+    readonly UPDATE_CONTROL: 8;
+    readonly UPDATE_DATA: 9;
+    readonly PREDICTIONS: 10;
+    /** 1.2: the encoder's output for each window. */
+    readonly EMBEDDINGS: 11;
+};
+/** The service's full identifier, advertised by every device. */
+export declare const SERVICE: string;
+/** Device Info's full identifier. */
+export declare const DEVICE_INFO: string;
+/** Control Point's full identifier. */
+export declare const CONTROL: string;
+/** Control Response's full identifier. */
+export declare const CONTROL_RESPONSE: string;
+/** EEG Data's full identifier. */
+export declare const EEG_DATA: string;
+/** Status's full identifier. */
+export declare const STATUS: string;
+/** Update Control's full identifier. */
+export declare const UPDATE_CONTROL: string;
+/** Update Data's full identifier. */
+export declare const UPDATE_DATA: string;
+/** Predictions' full identifier. */
+export declare const PREDICTIONS: string;
+/** Embeddings' full identifier. */
+export declare const EMBEDDINGS: string;
+/** The name a device advertises under, before its own identifier. */
+export declare const NAME_PREFIX = "IntoMind-";
+/**
+ * 1.3: the product name a composed device name ends with. A 1.3 device
+ * advertises `[name's] [adjective] IntoMind One`; a 1.2 device advertised
+ * `IntoMind-` and four hex digits.
+ */
+export declare const PRODUCT_NAME = "IntoMind One";
+/** Why bytes are not a message. The contract distinguishes these three. */
+export type Refusal = "truncated" | "invalid" | "reserved";
+/** Bytes that are not a message, with the reason they are not. */
+export declare class ProtocolError extends Error {
+    /** Which of the three reasons this is. */
+    readonly reason: Refusal;
+    /** Build one with its reason and message. A decoder throws one of the three subclasses. */
+    constructor(reason: Refusal, message: string);
+}
+/** The message ends before the fields it promises. */
+export declare class Truncated extends ProtocolError {
+    /** Build one with the message saying what is missing. */
+    constructor(message: string);
+}
+/** A field holds a value the contract does not define. */
+export declare class Invalid extends ProtocolError {
+    /** Build one with the message saying what is wrong. */
+    constructor(message: string);
+}
+/**
+ * A number the contract reserves. A device answers these unsupported rather
+ * than treating them as malformed, and so does a host.
+ */
+export declare class Reserved extends ProtocolError {
+    /** Build one with the message naming the reserved number. */
+    constructor(message: string);
+}
+declare function hex(b: Uint8Array): string;
+/** Bytes from a hex string, for tests and for anything that logs one. */
+export declare function fromHex(s: string): Uint8Array;
+export { hex as toHex };
+/** Every control point opcode this contract defines, by name. */
+export declare const OPCODES: {
+    readonly start_stream: 1;
+    readonly stop_stream: 2;
+    readonly set_rate: 16;
+    readonly set_gain: 17;
+    readonly set_mode: 32;
+    readonly set_leadoff: 48;
+    readonly time_sync: 64;
+    readonly set_samples_per_packet: 65;
+    readonly get_battery: 66;
+    readonly get_boot_info: 67;
+    readonly reset_epoch: 80;
+    readonly clear_bonds: 83;
+    readonly set_predictions: 128;
+    readonly select_head: 129;
+    readonly list_heads: 130;
+    readonly remove_head: 131;
+    readonly get_model_info: 132;
+    readonly set_prediction_input: 133;
+    readonly get_prediction_input: 134;
+    readonly set_bias: 50;
+    readonly get_bias_diagnostic: 51;
+    readonly get_pipeline_catalog: 144;
+    readonly get_pipeline: 145;
+    readonly set_pipeline: 146;
+    readonly clear_pipeline: 147;
+    readonly restore_pipeline_default: 148;
+    readonly get_converter_registers: 52;
+    readonly get_indicator: 68;
+    readonly set_indicator: 69;
+    readonly identify: 70;
+    readonly set_embeddings: 135;
+    readonly set_model_interval: 136;
+    readonly get_model_interval: 137;
+    readonly get_name: 71;
+    readonly set_name: 72;
+    readonly list_head_encoders: 138;
+    readonly soft_reset: 240;
+};
+/** The name of any opcode `OPCODES` defines. */
+export type OpcodeName = keyof typeof OPCODES;
+/** Opcode names by their number, the reverse of `OPCODES`. */
+export declare const NAME_BY_OPCODE: ReadonlyMap<number, OpcodeName>;
+/** Opcodes that take one argument byte, and require it. */
+export declare const TAKES_ARG: ReadonlySet<OpcodeName>;
+/**
+ * Opcodes new in 1.1 that carry a payload after the opcode byte, laid out
+ * as the processing section below says. The only requests longer than two
+ * bytes.
+ */
+export declare const TAKES_PAYLOAD: ReadonlySet<OpcodeName>;
+/**
+ * Opcodes a 1.0 device does not know. A host sends one only to a device
+ * whose Device Info claims the capability behind it.
+ */
+export declare const NEW_IN_1_1: ReadonlySet<OpcodeName>;
+/** Opcodes a 1.1 device does not know, likewise gated on a capability. */
+export declare const NEW_IN_1_2: ReadonlySet<OpcodeName>;
+/** Opcodes a 1.2 device does not know: the model's cadence and the device's name. */
+export declare const NEW_IN_1_3: ReadonlySet<OpcodeName>;
+/**
+ * Numbers an earlier development firmware used, and numbers the contract
+ * keeps for factory and bench builds. Never reused for anything else.
+ */
+export declare const RESERVED_OPCODES: ReadonlySet<number>;
+/** A control response's status byte, in words. */
+export declare const STATUS_CODES: Readonly<Record<number, string>>;
+/** The gain a `gain_code` of 0 to 6 selects. */
+export declare const GAIN_BY_CODE: readonly number[];
+/** The code for a gain, the reverse of `GAIN_BY_CODE`. */
+export declare const CODE_BY_GAIN: ReadonlyMap<number, number>;
+/** The rate in samples per second a `rate_code` selects. */
+export declare const RATE_BY_CODE: Readonly<Record<number, number>>;
+/** The code for a rate, the reverse of `RATE_BY_CODE`. */
+export declare const CODE_BY_RATE: ReadonlyMap<number, number>;
+/** The bit in Device Info's rate mask that stands for each rate. */
+export declare const RATE_BY_INFO_BIT: Readonly<Record<number, number>>;
+/** 1.3 adds synthetic: the converter is not driven and the device generates the signal, on a device that claims it. */
+export declare const MODES: {
+    readonly normal: 0;
+    readonly test: 1;
+    readonly short: 2;
+    readonly synthetic: 3;
+};
+/** The name of any mode `MODES` defines. */
+export type ModeName = keyof typeof MODES;
+/** Mode names by their code, the reverse of `MODES`. */
+export declare const MODE_BY_CODE: Readonly<Record<number, ModeName>>;
+/** What a charger state code means. */
+export declare const CHARGER_STATES: Readonly<Record<number, string>>;
+/** Why the device last booted, by `boot_reason` code. */
+export declare const BOOT_REASONS: Readonly<Record<number, string>>;
+/**
+ * One control point write.
+ *
+ * `opcode` is a name or a number. An opcode that takes an argument requires
+ * one, and one that does not takes none, because the device refuses either
+ * mistake and a host should not make it.
+ */
+export declare function encodeRequest(opcode: OpcodeName | number, arg?: number | Uint8Array | null): Uint8Array;
+/** One control point write, as `decodeRequest` reads it. */
+export interface Request {
+    /** The raw opcode byte, even one this contract does not define. */
+    readonly opcode: number;
+    /** The opcode's name. */
+    readonly name: OpcodeName;
+    /** The one argument byte, for an opcode that takes one. */
+    readonly arg: number | null;
+    /** The bytes after the opcode, for an opcode that takes a payload. */
+    readonly payload: Uint8Array | null;
+}
+/**
+ * A control point write, as the device reads it. For tests and for anything
+ * that has to speak both sides of the contract.
+ */
+export declare function decodeRequest(data: Uint8Array): Request;
+/** One control response, as `decodeResponse` reads it. */
+export interface Response {
+    /** The opcode this answers, echoed back even when it is not one this contract defines. */
+    readonly opcode: number;
+    /** Null for a number this contract does not define, which is echoed back. */
+    readonly name: OpcodeName | null;
+    /** The status byte, 0 for success. */
+    readonly status: number;
+    /** `status` in words, from `STATUS_CODES`. */
+    readonly statusName: string;
+    /** Whether `status` is 0. */
+    readonly ok: boolean;
+    /** The bytes after the opcode and status, specific to what was asked. */
+    readonly payload: Uint8Array;
+}
+/** One control response, as the device sends it. */
+export declare function decodeResponse(data: Uint8Array): Response;
+/**
+ * One control response. The opcode is a number rather than a name because a
+ * device echoes back whatever it was sent, including a reserved number.
+ */
+export declare function encodeResponse(opcode: number, status: number, payload?: Uint8Array): Uint8Array;
+/** The device's own time, from the answer to a time request. */
+export declare function decodeTimeSync(payload: Uint8Array): bigint;
+/** What a device can do, as the bits it reports. */
+export declare const CAPABILITIES: {
+    readonly battery_voltage: number;
+    readonly battery_low_flag: number;
+    readonly leadoff: number;
+    readonly test_signal: number;
+    readonly dcdc_mode: number;
+    readonly input_short: number;
+    readonly update: number;
+    readonly model: number;
+    readonly model_ready: number;
+    readonly heads: number;
+    readonly pipeline: number;
+    readonly bias_drive: number;
+    readonly embeddings: number;
+    readonly indicator: number;
+    readonly converter_registers: number;
+    readonly model_cadence: number;
+};
+/** The name of any capability bit `CAPABILITIES` defines. */
+export type CapabilityName = keyof typeof CAPABILITIES;
+/** 1.3: capability bits 16 and up, the second word of Device Info at offset 76. Bit 16 of the contract is bit 0 here. */
+export declare const CAPABILITIES_HIGH: {
+    readonly synthetic: number;
+    readonly device_name: number;
+};
+/** The name of any capability bit `CAPABILITIES_HIGH` defines. */
+export type CapabilityHighName = keyof typeof CAPABILITIES_HIGH;
+/** Length of the v0.1 prefix, which 1.0 left where it was. */
+export declare const INFO_V01_LEN = 27;
+/** Length of the 1.0 layout. */
+export declare const INFO_LEN_1_0 = 76;
+/** 1.3: the 1.0 layout with a second capability word appended. */
+export declare const INFO_LEN = 80;
+/** What a device with no battery telemetry reports instead of a percent. */
+export declare const BATTERY_UNKNOWN = 255;
+/** What `DeviceInfo`'s constructor takes. The optional fields default to zero or null. */
+export interface DeviceInfoFields {
+    /** Protocol major and minor. */
+    protocol: readonly [number, number];
+    /** Firmware major, minor, and patch. */
+    firmware: readonly [number, number, number];
+    /** Channel count. */
+    channels: number;
+    /** Converter resolution, in bits. */
+    adcBits: number;
+    /** Device time ticks per second. */
+    tickHz: number;
+    /** Converter reference voltage, in microvolts. */
+    vrefUv: number;
+    /** The sixteen bit capability mask. */
+    capabilities: number;
+    /** Which rates the device supports, as a bit mask. */
+    supportedRates: number;
+    /** The device's stable per-unit identifier, as hex. */
+    deviceId: string;
+    /** Hardware major, minor, and patch, when the device reports the 1.0 extension. */
+    hardware?: readonly [number, number, number] | null;
+    /** The exact firmware build, when reported. */
+    buildId?: string | null;
+    /** The model's embedding width, zero for no model runtime. */
+    modelEmbedDim?: number;
+    /** The model's native sample rate. */
+    modelNativeSps?: number;
+    /** Samples per prediction window at the model's native rate. */
+    modelWindowSamples?: number;
+    /** User head slots. */
+    headSlots?: number;
+    /** The largest `out_dim` a head may have. */
+    headMaxOutputs?: number;
+    /** Capacity of one head slot, in bytes. */
+    headSlotBytes?: number;
+    /** The largest Update Data write the device accepts. */
+    updateChunkMax?: number;
+    /** Capacity of one application slot, including its header. */
+    appSlotBytes?: number;
+    /** Capacity of the weights image, including its header. */
+    weightsImageBytes?: number;
+    /** 1.3: capability bits 16 and up. Zero on a device whose info ends at 76 bytes. */
+    capabilitiesHigh?: number;
+}
+/** Everything a device says about itself, and nothing a host assumed. */
+export declare class DeviceInfo {
+    /** Protocol major and minor. */
+    readonly protocol: readonly [number, number];
+    /** Firmware major, minor, and patch. */
+    readonly firmware: readonly [number, number, number];
+    /** Channel count. */
+    readonly channels: number;
+    /** Converter resolution, in bits. */
+    readonly adcBits: number;
+    /** Device time ticks per second. */
+    readonly tickHz: number;
+    /** Converter reference voltage, in microvolts. */
+    readonly vrefUv: number;
+    /** The sixteen bit capability mask, bits 0 to 15. `can` is how to read it. */
+    readonly capabilities: number;
+    /** Which rates the device supports, as a bit mask. `rates` is how to read it. */
+    readonly supportedRates: number;
+    /** The device's stable per-unit identifier, as hex. */
+    readonly deviceId: string;
+    /** Present on a device that reports the 1.0 layout. */
+    readonly hardware: readonly [number, number, number] | null;
+    /** The exact firmware build, or null when the device reports no extension. */
+    readonly buildId: string | null;
+    /** The model's embedding width, zero for no model runtime. */
+    readonly modelEmbedDim: number;
+    /** The model's native sample rate. */
+    readonly modelNativeSps: number;
+    /** Samples per prediction window at the model's native rate. */
+    readonly modelWindowSamples: number;
+    /** User head slots. */
+    readonly headSlots: number;
+    /** The largest `out_dim` a head may have. */
+    readonly headMaxOutputs: number;
+    /** Capacity of one head slot, in bytes. */
+    readonly headSlotBytes: number;
+    /** The largest Update Data write the device accepts. */
+    readonly updateChunkMax: number;
+    /** Capacity of one application slot, including its header. */
+    readonly appSlotBytes: number;
+    /** Capacity of the weights image, including its header. */
+    readonly weightsImageBytes: number;
+    /** The second capability word, bits 16 and up (1.3). Zero on a device whose info ends at 76 bytes. */
+    readonly capabilitiesHigh: number;
+    /** Build from the fields `decodeDeviceInfo` read, or assembled by hand. */
+    constructor(f: DeviceInfoFields);
+    /**
+     * Whether the device claims a capability. Unknown names are false rather
+     * than an error, so a host written against a later version of this
+     * contract still runs.
+     */
+    can(capability: CapabilityName | CapabilityHighName | string): boolean;
+    /** Whether the device reported the 1.0 extension. */
+    get extensionPresent(): boolean;
+    /** The rates the device declares, from its own mask. */
+    get rates(): number[];
+    /** `protocol` as `major.minor`. */
+    get protocolString(): string;
+    /** `firmware` as `major.minor.patch`. */
+    get firmwareString(): string;
+    /** `hardware` as `major.minor.patch`, or null when the device reports no extension. */
+    get hardwareString(): string | null;
+    /** One count, in microvolts, at a gain. From the device's own reference and width. */
+    microvoltsPerCount(gain: number): number;
+}
+/** Device Info, as the device sends it. */
+export declare function decodeDeviceInfo(data: Uint8Array): DeviceInfo;
+/**
+ * Device info as a device reports it. A device that has no extension to
+ * report encodes the v0.1 prefix, which is what an older one sends.
+ */
+export declare function encodeDeviceInfo(info: DeviceInfo): Uint8Array;
+/** The length of a Status message, in bytes. */
+export declare const STATUS_LEN = 12;
+/** The bits of Status's flags byte. */
+export declare const STATUS_FLAGS: {
+    readonly usb_present: number;
+    readonly buffer_high_watermark: number;
+};
+/** Status, decoded, read or notified. */
+export interface Status {
+    /** 0 idle, 1 streaming. */
+    readonly state: number;
+    /** Whether `state` is streaming. */
+    readonly streaming: boolean;
+    /** The mode code in force. See `MODES`. */
+    readonly mode: number;
+    /** `mode` in words. */
+    readonly modeName: string;
+    /** The gain code in force. */
+    readonly gainCode: number;
+    /** `gainCode` as a gain, or null for a code this contract does not define. */
+    readonly gain: number | null;
+    /** The rate code in force. */
+    readonly rateCode: number;
+    /** `rateCode` as samples per second, or null for a code this contract does not define. */
+    readonly sps: number | null;
+    /** The charger state code. */
+    readonly chargerState: number;
+    /** `chargerState` in words. */
+    readonly chargerName: string;
+    /** Null when the device has no battery telemetry, never 255 percent. */
+    readonly batteryPercent: number | null;
+    /** The raw byte: 0xFF for unknown, rather than null. */
+    readonly batteryPercentRaw: number;
+    /** Lead-off status latched with the most recently acquired sample. Bit n is channel n+1. */
+    readonly loffStatp: number;
+    /** Whether USB power is present (1.4). */
+    readonly usbPresent: boolean;
+    /** Whether the device's buffer is at or above three quarters full. */
+    readonly bufferHighWatermark: boolean;
+    /** Telemetry. The account of what a host missed is the sample index. */
+    readonly droppedTotal: number;
+    /** Samples currently buffered on the device. */
+    readonly bufferFill: number;
+}
+/** Status, as the device sends it. */
+export declare function decodeStatus(data: Uint8Array): Status;
+/** What `encodeStatus` takes. */
+export interface StatusFields {
+    /** 0 idle, 1 streaming. */
+    state: number;
+    /** The mode code in force. */
+    mode: number;
+    /** The gain code in force. */
+    gainCode: number;
+    /** The rate code in force. */
+    rateCode: number;
+    /** The charger state code. */
+    chargerState: number;
+    /** Null for a device with no battery telemetry. */
+    batteryPercent: number | null;
+    /** Lead-off status latched with the most recently acquired sample. */
+    loffStatp: number;
+    /** Whether USB power is present. */
+    usbPresent?: boolean;
+    /** Whether the device's buffer is at or above three quarters full. */
+    bufferHighWatermark?: boolean;
+    /** Samples acquired but never delivered since power on. */
+    droppedTotal: number;
+    /** Samples currently buffered on the device. */
+    bufferFill: number;
+}
+/** Status, as the device sends it. */
+export declare function encodeStatus(s: StatusFields): Uint8Array;
+/** The EEG data packet type. */
+export declare const PACKET_EEG = 1;
+/** The prediction packet type. */
+export declare const PACKET_PREDICTION = 2;
+/** 1.3: samples the device generated with its converter off, in exactly the layout of `PACKET_EEG`. */
+export declare const PACKET_SYNTHETIC = 4;
+/** The length of an EEG data packet's header, before the samples. */
+export declare const DATA_HEADER_LEN = 20;
+/** The single bit flags of an EEG data packet's flags byte. Mode occupies the other two, via `MODE_SHIFT` and `MODE_MASK`. */
+export declare const DATA_FLAGS: {
+    readonly discontinuity: number;
+    readonly leadoff_active: number;
+    readonly usb_present: number;
+};
+/** Where the mode bits sit in an EEG data packet's flags byte. */
+export declare const MODE_SHIFT = 2;
+/** The mode bits of an EEG data packet's flags byte, before shifting. */
+export declare const MODE_MASK: number;
+/** `samples_lost_before` saturates here. The sample index is authoritative. */
+export declare const LOST_SATURATED = 65535;
+/**
+ * One notification of samples, decoded but not scaled.
+ *
+ * `counts` is one row per sample across the channels, in converter counts.
+ * Scaling is the caller's, with the device's own reference and width,
+ * because this module assumes nothing about either.
+ */
+export interface Packet {
+    /** 0x01 for a measured sample, 0x04 for one the device generated (1.3). */
+    readonly packetType: number;
+    /** Whether a break precedes this packet. */
+    readonly discontinuity: boolean;
+    /** Whether lead-off was active when this packet was built. */
+    readonly leadoffActive: boolean;
+    /** The mode code the samples were taken in. */
+    readonly mode: number;
+    /** `mode` in words. */
+    readonly modeName: string;
+    /** Whether USB power was present (1.4). */
+    readonly usbPresent: boolean;
+    /** A convenience count of samples lost before this packet, saturating at `LOST_SATURATED`. `index` continuity is authoritative. */
+    readonly samplesLostBefore: number;
+    /** The first sample's index, monotonic and wrapping at 2^32. */
+    readonly index: number;
+    /** The first sample's device time, in the device's ticks. */
+    readonly deviceTime: bigint;
+    /** Samples carried in this packet. */
+    readonly nSamples: number;
+    /** Lead-off status latched with the packet's last sample. */
+    readonly loffStatp: number;
+    /** The gain code the samples were taken at. */
+    readonly gainCode: number;
+    /** `gainCode` as a gain. */
+    readonly gain: number;
+    /** The rate code the samples were taken at. */
+    readonly rateCode: number;
+    /** `rateCode` as samples per second, or null for a code this contract does not define. */
+    readonly sps: number | null;
+    /** One row per sample, each row one converter count per channel. */
+    readonly counts: number[][];
+    /** 1.3: the samples were generated by the device, not measured (packet type 0x04). Never store one as a measurement. */
+    readonly synthetic: boolean;
+}
+/** One EEG notification. `channels` comes from the device. */
+export declare function decodePacket(data: Uint8Array, channels: number): Packet;
+/** What `encodePacket` takes. */
+export interface PacketFields {
+    /** The first sample's index. */
+    index: number;
+    /** The first sample's device time, in the device's ticks. */
+    deviceTime: bigint;
+    /** The gain code the samples were taken at. */
+    gainCode: number;
+    /** The rate code the samples were taken at. */
+    rateCode: number;
+    /** One row per sample, each row one value per channel, in counts. */
+    counts: ReadonlyArray<ArrayLike<number>>;
+    /** Whether a break precedes this packet. */
+    discontinuity?: boolean;
+    /** Whether lead-off was active. */
+    leadoffActive?: boolean;
+    /** The mode code the samples were taken in. */
+    mode?: number;
+    /** Whether USB power was present. */
+    usbPresent?: boolean;
+    /** A convenience count of samples lost before this packet. */
+    samplesLostBefore?: number;
+    /** Lead-off status latched with the packet's last sample. */
+    loffStatp?: number;
+    /** 1.3: write the packet as synthetic samples, type 0x04. */
+    synthetic?: boolean;
+}
+/**
+ * One EEG notification, as the device sends it. The payload is converter
+ * order, big endian, which is why the device copies its bytes out without
+ * swapping any of them.
+ */
+export declare function encodePacket(p: PacketFields): Uint8Array;
+/** One big endian, two's complement int24, sign extended. */
+export declare function int24(b: Uint8Array, at?: number): number;
+/**
+ * One count in microvolts. Every term comes from the device: its reference,
+ * the gain the packet was taken at, and the converter's width.
+ */
+export declare function microvolts(raw: number, vrefUv: number, gain: number, adcBits: number): number;
+/** What one packet's indexing says happened since the one before it. */
+export interface Continuity {
+    /** The contract's own words for the three cases. */
+    readonly verdict: "continuous" | "gap" | "break";
+    /** Samples missing. Null for a break, whose extent is not a number. */
+    readonly lost: number | null;
+    /** Whether this is a gap or a break rather than continuous. */
+    readonly broken: boolean;
+}
+/**
+ * Judge two packets by the contract's own rule.
+ *
+ * The subtraction is signed, so the index's own wrap at two to the thirty
+ * second is exact. A step that is not forward is a break in the timeline
+ * rather than a loss, and reporting the unsigned difference there claims a
+ * loss of four billion samples that never happened.
+ */
+export declare function continuity(previousIndex: number, previousN: number, index: number, discontinuity: boolean): Continuity;
+/** The length of a prediction packet's header, before the outputs. */
+export declare const PREDICTION_HEADER_LEN = 28;
+/** The bits of a prediction packet's flags byte. */
+export declare const PREDICTION_FLAGS: {
+    readonly gap_in_window: number;
+    readonly duty_reduced: number;
+    readonly leadoff_in_window: number;
+};
+/** One prediction notification, decoded. */
+export interface Prediction {
+    /** 0x02 for a prediction. */
+    readonly packetType: number;
+    /** The slot of the head that produced this. */
+    readonly headSlot: number;
+    /** The identity of the head that produced this. */
+    readonly headId: string;
+    /** The window's first sample's index. */
+    readonly index: number;
+    /** The window's first sample's device time. */
+    readonly deviceTime: bigint;
+    /** The window's length, in raw samples at the current rate. */
+    readonly windowSamples: number;
+    /** Whether a gap fell inside the window. */
+    readonly gapInWindow: boolean;
+    /** Whether the device skipped windows to stay within its compute budget. */
+    readonly dutyReduced: boolean;
+    /** Whether an electrode was off at some point in the window. */
+    readonly leadoffInWindow: boolean;
+    /** The head's outputs for this window. */
+    readonly outputs: number[];
+    /**
+     * 1.1: what the window was taken from, an `INPUT_SOURCES` value: the
+     * stream, the natural signal, or the model's own chain. A 1.0 device
+     * says the stream.
+     */
+    readonly inputSource: number;
+}
+/** One prediction notification, as the device sends it. */
+export declare function decodePrediction(data: Uint8Array): Prediction;
+/** What `encodePrediction` takes. */
+export interface PredictionFields {
+    /** The slot of the head that produced this. */
+    headSlot: number;
+    /** The identity of the head that produced this. */
+    headId: string;
+    /** The window's first sample's index. */
+    index: number;
+    /** The window's first sample's device time. */
+    deviceTime: bigint;
+    /** The window's length, in raw samples. */
+    windowSamples: number;
+    /** The head's outputs for this window. */
+    outputs: ArrayLike<number>;
+    /** Whether a gap fell inside the window. */
+    gapInWindow?: boolean;
+    /** Whether the device skipped windows to stay within its compute budget. */
+    dutyReduced?: boolean;
+    /** Whether an electrode was off at some point in the window. */
+    leadoffInWindow?: boolean;
+    /** What the window was taken from, an `INPUT_SOURCES` value. */
+    inputSource?: number;
+}
+/** One prediction notification, as the device sends it. */
+export declare function encodePrediction(p: PredictionFields): Uint8Array;
+/** GET_BATTERY's answer. */
+export interface Battery {
+    /** The measured pack voltage, in millivolts. */
+    readonly millivolts: number;
+    /** A state of charge estimate, or null when the device has no battery telemetry. */
+    readonly percent: number | null;
+    /** The charger state code. */
+    readonly chargerState: number;
+    /** `chargerState` in words. */
+    readonly chargerName: string;
+}
+/** GET_BATTERY's answer, as the device sends it. */
+export declare function decodeBattery(payload: Uint8Array): Battery;
+/** GET_BATTERY's answer, as the device sends it. */
+export declare function encodeBattery(b: {
+    millivolts: number;
+    percent: number | null;
+    chargerState: number;
+}): Uint8Array;
+/** GET_BOOT_INFO's answer. */
+export interface BootInfo {
+    /** Which application slot is running: 0 A, 1 B. */
+    readonly activeSlot: number;
+    /** The boot reason code. */
+    readonly bootReason: number;
+    /** `bootReason` in words. */
+    readonly bootReasonName: string;
+    /** 0 trial, the running image has not yet confirmed itself. 1 confirmed. */
+    readonly slotState: number;
+    /** A slot on trial has not yet been confirmed by the firmware in it. */
+    readonly confirmed: boolean;
+    /** Boots of this unit since manufacture. */
+    readonly bootCount: number;
+}
+/** GET_BOOT_INFO's answer, as the device sends it. */
+export declare function decodeBootInfo(payload: Uint8Array): BootInfo;
+/** GET_BOOT_INFO's answer, as the device sends it. */
+export declare function encodeBootInfo(b: {
+    activeSlot: number;
+    bootReason: number;
+    slotState: number;
+    bootCount: number;
+}): Uint8Array;
+/** A head slot's state, in words, by its `state` code. */
+export declare const HEAD_STATES: Readonly<Record<number, string>>;
+/** The model runtime's state, in words, by its `model_state` code. */
+export declare const MODEL_STATES: Readonly<Record<number, string>>;
+/** An encoder id a head that does not name its encoder carries. */
+export declare const NO_ENCODER_ID = "0000000000000000";
+/** The slot byte meaning no head is selected. */
+export declare const NO_HEAD = 255;
+/** The length of one LIST_HEADS record, in bytes. */
+export declare const HEAD_ENTRY_LEN = 30;
+/** One LIST_HEADS record: one head slot. */
+export interface HeadEntry {
+    /** 0 for the built-in head, 1 and up for user slots. */
+    readonly slot: number;
+    /** The slot's state code. See `HEAD_STATES`. */
+    readonly state: number;
+    /** `state` in words. */
+    readonly stateName: string;
+    /** The head's output count. */
+    readonly outDim: number;
+    /** The head's identity, the first eight bytes of its SHA-256. Zero when empty. */
+    readonly headId: string;
+    /** The head's name. */
+    readonly name: string;
+    /** Whether `state` is valid. */
+    readonly usable: boolean;
+    /**
+     * 1.3: the encoder the head was trained beside, as its file recorded it; `NO_ENCODER_ID` when it did not say.
+     * From 1.4 the list carries none: `decodeHeadEncoders` reads them, and `withEncoders` puts them here.
+     */
+    readonly encoderId: string;
+}
+/** LIST_HEADS's answer: the head slots, and which one is selected. */
+export interface HeadList {
+    /** Null means no head is selected. */
+    readonly activeSlot: number | null;
+    /** The slots, in the order the device reports them. */
+    readonly heads: HeadEntry[];
+}
+/** The head slots, and which one is selected. */
+export declare function decodeHeads(payload: Uint8Array): HeadList;
+/** A LIST_HEADS payload as a device sends it: the records and nothing after them. */
+export declare function encodeHeads(activeSlot: number | null, heads: ReadonlyArray<{
+    slot: number;
+    state: number;
+    outDim: number;
+    headId: string;
+    name: string;
+}>): Uint8Array;
+/** One LIST_HEAD_ENCODERS record (1.4): a slot and the encoder id its head names. */
+export declare const HEAD_ENCODER_LEN = 9;
+/**
+ * 1.4: the encoder each head names, by slot, from LIST_HEAD_ENCODERS: `NO_ENCODER_ID` for an empty slot or a head
+ * that does not say.
+ */
+export declare function decodeHeadEncoders(payload: Uint8Array): ReadonlyMap<number, string>;
+/** A LIST_HEAD_ENCODERS payload: one record for each head, in the order given. */
+export declare function encodeHeadEncoders(heads: ReadonlyArray<{
+    slot: number;
+    encoderId: string;
+}>): Uint8Array;
+/** The heads, each with the encoder `encoders` says it names. A slot it does not mention keeps what it had. */
+export declare function withEncoders(list: HeadList, encoders: ReadonlyMap<number, string>): HeadList;
+/** GET_MODEL_INFO's answer. */
+export interface ModelInfo {
+    /** The model runtime's state code. See `MODEL_STATES`. */
+    readonly modelState: number;
+    /** `modelState` in words. */
+    readonly modelStateName: string;
+    /** Whether `modelState` is ready, so predictions can be enabled. */
+    readonly ready: boolean;
+    /** Null means no head is selected. */
+    readonly activeHead: number | null;
+    /** Whether predictions are enabled. */
+    readonly predictionsOn: boolean;
+    /** The loaded weights' identity. Zero unless ready. */
+    readonly encoderId: string;
+    /** The loaded weights' major, minor, and patch. */
+    readonly weightsVersion: readonly [number, number, number];
+    /**
+     * 1.1: the signal classes the loaded model declares it takes, as
+     * `INPUT_CLASSES` bits. A 1.0 device sends zero, which reads as the time
+     * domain.
+     */
+    readonly inputClasses: number;
+    /**
+     * 1.2: tokens the loaded model produces per channel per window, the shape
+     * of the token form of embeddings. A 1.1 device's message ends before this
+     * byte and reads as zero: it sends no tokens.
+     */
+    readonly tokensPerChannel: number;
+    /** 1.3: the time one pass of the encoder takes on the device, milliseconds; zero before the first pass. */
+    readonly passMs: number;
+    /** 1.3: the interval between described windows in force, seconds; zero is every window the device can. */
+    readonly intervalS: number;
+    /** 1.3: whether the device holds a generator, so it can offer the synthetic signal. */
+    readonly generator: boolean;
+}
+/** GET_MODEL_INFO's answer, as the device sends it. */
+export declare function decodeModelInfo(payload: Uint8Array): ModelInfo;
+/** GET_MODEL_INFO's answer, as the device sends it. */
+export declare function encodeModelInfo(m: {
+    modelState: number;
+    activeHead: number | null;
+    predictionsOn: boolean;
+    encoderId: string;
+    weightsVersion: readonly [number, number, number];
+    inputClasses?: number;
+    /** 1.2: when given, the message is seventeen bytes. */
+    tokensPerChannel?: number | undefined;
+    /** 1.3: when given, the message is twenty two bytes. */
+    passMs?: number | undefined;
+    intervalS?: number | undefined;
+    generator?: boolean | undefined;
+}): Uint8Array;
+/** GET_MODEL_INTERVAL's answer: the interval in force and the least the device keeps, seconds. */
+export interface ModelInterval {
+    /** The interval in force, seconds. 0 is every window the device can. */
+    readonly intervalS: number;
+    /** The least interval the device keeps, seconds. */
+    readonly minimumS: number;
+}
+/** GET_MODEL_INTERVAL's answer, as the device sends it. */
+export declare function decodeModelInterval(payload: Uint8Array): ModelInterval;
+/** SET_MODEL_INTERVAL's payload: the seconds, little endian. Zero is every window the device can. */
+export declare function encodeModelInterval(seconds: number): Uint8Array;
+/** The most a composed name may be, in bytes: what a scan response carries. The same limit bounds each part. */
+export declare const NAME_MAX_COMPOSED = 29;
+/** A name or an adjective: UTF-8 of at most 29 bytes, no control characters, no leading or trailing space. Empty is allowed. */
+export declare function namePartOk(part: string): boolean;
+/** The device's name as it composes it: `name's adjective product`, the possessive only with a name, the adjective only when given. */
+export declare function composeName(name: string, adjective: string, product?: string): string;
+/** Whether the composition fits the air, so the device will accept it. */
+export declare function nameFits(name: string, adjective: string, product?: string): boolean;
+/** SET_NAME's payload and GET_NAME's answer: each part as a length and its UTF-8 bytes. */
+export declare function encodeNameParts(name: string, adjective: string): Uint8Array;
+/** GET_NAME's answer or SET_NAME's request, as the device reads or sends it: the name and the adjective. */
+export declare function decodeNameParts(payload: Uint8Array): {
+    name: string;
+    adjective: string;
+};
+/**
+ * Labels for a list a person picks devices from, in the list's order: each
+ * device's own name, and when two in the list share one, a number after the
+ * later ones (`Ada's Blue IntoMind One 2`). The number is the host's and
+ * lasts as long as the list. The device knows nothing of it, since two
+ * devices cannot agree on which is second without a host that sees them
+ * both. A device heard before its name arrived is labeled with the product
+ * name.
+ */
+export declare function displayNames(names: ReadonlyArray<string | null | undefined>): string[];
+/** The processing stage kinds this version defines, by name. */
+export declare const STAGE_KINDS: {
+    readonly highpass: 1;
+    readonly lowpass: 2;
+    readonly notch: 3;
+};
+/** The name of any stage kind `STAGE_KINDS` defines. */
+export type StageKindName = keyof typeof STAGE_KINDS;
+/** Stage kind names by their number, the reverse of `STAGE_KINDS`. */
+export declare const KIND_NAMES: Readonly<Record<number, StageKindName>>;
+/** The classes a stage kind belongs to: map, representation, or detector. */
+export declare const STAGE_CLASSES: {
+    readonly map: 0;
+    readonly representation: 1;
+    readonly detector: 2;
+};
+/** Stage class names by their number, the reverse of `STAGE_CLASSES`. */
+export declare const CLASS_NAMES: Readonly<Record<number, string>>;
+/** 1.3 adds synthetic: reported by a device generating its signal, never requested. */
+export declare const INPUT_SOURCES: {
+    readonly stream: 0;
+    readonly natural: 1;
+    readonly own_chain: 2;
+    readonly synthetic: 3;
+};
+/** The name of any source `INPUT_SOURCES` defines. */
+export type InputSourceName = keyof typeof INPUT_SOURCES;
+/** Input source names by their number, the reverse of `INPUT_SOURCES`. */
+export declare const INPUT_SOURCE_NAMES: Readonly<Record<number, InputSourceName>>;
+/** The signal classes a model declares it takes, as bits of `inputClasses`. */
+export declare const INPUT_CLASSES: {
+    readonly time_domain: number;
+    readonly representation: number;
+};
+/** Whether the chain in force is the device's default or one a host set. */
+export declare const PIPELINE_ORIGINS: {
+    readonly default: 0;
+    readonly host: 1;
+};
+/** The name of any origin `PIPELINE_ORIGINS` defines. */
+export type OriginName = keyof typeof PIPELINE_ORIGINS;
+/** Origin names by their number, the reverse of `PIPELINE_ORIGINS`. */
+export declare const ORIGIN_NAMES: Readonly<Record<number, OriginName>>;
+/** The bias drive's modes: off, on, or loop open. */
+export declare const BIAS_MODES: {
+    readonly off: 0;
+    readonly on: 1;
+    readonly loop_open: 2;
+};
+/** The name of any mode `BIAS_MODES` defines. */
+export type BiasModeName = keyof typeof BIAS_MODES;
+/** The most stages one chain may hold. */
+export declare const MAX_STAGES = 12;
+/** The most parameters one stage may hold. */
+export declare const MAX_PARAMS = 4;
+/** The most notch stages one chain may hold. */
+export declare const MAX_NOTCHES = 8;
+/** The device's default high-pass corner, in tenths of a hertz. */
+export declare const DEFAULT_HIGH_PASS_DHZ = 5;
+/** Both mains fundamentals, second and third harmonics, four hertz wide: the device's default until a region is chosen. */
+export declare const DEFAULT_MAINS_BANDS_DHZ: ReadonlyArray<readonly [number, number]>;
+/** One stage of a chain: a kind and its parameters, in tenths of a hertz for every kind this version defines. */
+export interface Stage {
+    /** A `STAGE_KINDS` value. */
+    readonly kind: number;
+    /** The stage's parameters, in tenths of a hertz for every kind this version defines. */
+    readonly params: readonly number[];
+}
+/** `kind` in words, from `KIND_NAMES`. */
+export declare function stageName(s: Stage): string;
+/** A high-pass at a corner, at least 0.1 Hz. */
+export declare function highpass(cornerHz: number): Stage;
+/** A low-pass at a corner, or the automatic corner at four tenths of the sample rate when none is given. */
+export declare function lowpass(cornerHz?: number): Stage;
+/** A notch over the band between two edges. Any band. */
+export declare function notch(lowHz: number, highHz: number): Stage;
+/** `u8 n_stages`, then per stage `u8 kind, u8 n_params, u16[n_params]`. */
+export declare function encodeChain(stages: readonly Stage[]): Uint8Array;
+/** A chain descriptor that is the whole of `data`. */
+export declare function decodeChain(data: Uint8Array): Stage[];
+/** One kind a device runs: its number, class, parameter count, how many instances a chain may hold, and its name. */
+export interface CatalogEntry {
+    /** The stage kind's number. */
+    readonly kind: number;
+    /** The stage class's number. See `STAGE_CLASSES`. */
+    readonly cls: number;
+    /** `cls` in words. */
+    readonly className: string;
+    /** Parameters this kind takes. */
+    readonly nParams: number;
+    /** The most instances of this kind a chain may hold. */
+    readonly maxInstances: number;
+    /** The kind's name, as the device's catalog states it. */
+    readonly name: string;
+}
+/**
+ * The kinds this version of the contract defines, with their limits. A
+ * device's own catalog is the authority; this is what a host checks against
+ * when it has not read one.
+ */
+export declare const CONTRACT_CATALOG: readonly CatalogEntry[];
+/** The length of one catalog record, in bytes. */
+export declare const CATALOG_ENTRY_LEN = 12;
+/** GET_PIPELINE_CATALOG: `u8 n_kinds`, then records of twelve bytes. */
+export declare function decodeCatalog(payload: Uint8Array): CatalogEntry[];
+/** GET_PIPELINE_CATALOG's answer, as the device sends it. */
+export declare function encodeCatalog(entries: readonly CatalogEntry[]): Uint8Array;
+/** The chain in force, and whether it is the device's own default for its current rate or one a host set. */
+export interface PipelineState {
+    /** A `PIPELINE_ORIGINS` value. */
+    readonly origin: number;
+    /** `origin` in words. */
+    readonly originName: OriginName;
+    /** The chain in force. */
+    readonly stages: Stage[];
+}
+/** GET_PIPELINE's answer, as the device sends it. */
+export declare function decodePipelineState(payload: Uint8Array): PipelineState;
+/** GET_PIPELINE's answer, as the device sends it. */
+export declare function encodePipelineState(origin: number, stages: readonly Stage[]): Uint8Array;
+/**
+ * Where the model's input comes from: the stream as it is, the natural
+ * signal, or a chain of the model's own. In an answer the stages are the
+ * chain in effect for the model.
+ */
+export interface PredictionInput {
+    /** An `INPUT_SOURCES` value. */
+    readonly source: number;
+    /** `source` in words. */
+    readonly sourceName: InputSourceName;
+    /** The chain in effect for the model, when `source` is the model's own. */
+    readonly stages: Stage[];
+}
+/** SET_PREDICTION_INPUT's request, as the device reads it. */
+export declare function encodePredictionInput(source: number | InputSourceName, stages?: readonly Stage[]): Uint8Array;
+/** GET_PREDICTION_INPUT's answer, as the device sends it. */
+export declare function decodePredictionInput(payload: Uint8Array): PredictionInput;
+/** The bias output over the device's own window, in millivolts. */
+export interface BiasDiagnostic {
+    /** Mean bias output, in millivolts. */
+    readonly meanMv: number;
+    /** Standard deviation of the bias output, in millivolts. */
+    readonly sdMv: number;
+    /** Minimum bias output, in millivolts. */
+    readonly minMv: number;
+    /** Maximum bias output, in millivolts. */
+    readonly maxMv: number;
+}
+/** GET_BIAS_DIAGNOSTIC's answer, as the device sends it. */
+export declare function decodeBiasDiagnostic(payload: Uint8Array): BiasDiagnostic;
+/** GET_BIAS_DIAGNOSTIC's answer, as the device sends it. */
+export declare function encodeBiasDiagnostic(d: BiasDiagnostic): Uint8Array;
+/** The status lamp's verbosity levels: silent, reserved, or verbose. */
+export declare const INDICATOR_LEVELS: {
+    readonly silent: 0;
+    readonly reserved: 1;
+    readonly verbose: 2;
+};
+/** The name of any level `INDICATOR_LEVELS` defines. */
+export type IndicatorLevelName = keyof typeof INDICATOR_LEVELS;
+/** Indicator level names by their number, the reverse of `INDICATOR_LEVELS`. */
+export declare const INDICATOR_LEVEL_NAMES: Readonly<Record<number, IndicatorLevelName>>;
+/** What each level shows, most important first. */
+export declare const INDICATOR_SHOWS: Readonly<Record<IndicatorLevelName, readonly string[]>>;
+/** Low battery begins below this percent of the device's own estimate and ends above the clear percent, or on external power. */
+export declare const LOW_BATTERY_PERCENT = 20;
+/** Low battery clears once the device's own estimate rises back above this percent. */
+export declare const LOW_BATTERY_CLEAR_PERCENT = 25;
+/** The most seconds one identify request may run. */
+export declare const IDENTIFY_MAX_SECONDS = 30;
+/** Which chip family a converter register file belongs to, by its `family` code. */
+export declare const CONVERTER_FAMILIES: Readonly<Record<number, string>>;
+/** GET_CONVERTER_REGISTERS's answer. */
+export interface ConverterRegisters {
+    /** Which chip family the registers belong to. See `CONVERTER_FAMILIES`. */
+    readonly family: number;
+    /** `family` in words. */
+    readonly familyName: string;
+    /** Address of the first register carried. */
+    readonly first: number;
+    /** The registers themselves, consecutive addresses starting at `first`. */
+    readonly values: Uint8Array;
+}
+/** GET_CONVERTER_REGISTERS's answer, as the device sends it. */
+export declare function decodeConverterRegisters(payload: Uint8Array): ConverterRegisters;
+/** GET_CONVERTER_REGISTERS's answer, as the device sends it. */
+export declare function encodeConverterRegisters(r: {
+    family: number;
+    first: number;
+    values: Uint8Array;
+}): Uint8Array;
+/**
+ * An ADS1299 family register file in words, from address 0: the identity,
+ * the data rate, the test signal, the reference and bias settings, lead-off
+ * detection, each channel's gain and input, and the bias and lead-off sense
+ * masks. Every field is the datasheet's (Texas Instruments SBAS499C). A
+ * file shorter than 24 bytes is described as far as it goes.
+ */
+export declare function describeAds1299Registers(values: Uint8Array): Record<string, unknown>;
+/** The embedding packet type. */
+export declare const PACKET_EMBEDDING = 3;
+/** The length of an embedding notification's header, before its values. */
+export declare const EMBEDDING_HEADER_LEN = 28;
+/** The `token` byte meaning this is the window embedding, not one token. */
+export declare const WINDOW_TOKEN = 255;
+/** Which embeddings a device streams: off, window, tokens, or both. */
+export declare const EMBEDDING_FORMS: {
+    readonly off: 0;
+    readonly window: 1;
+    readonly tokens: 2;
+    readonly both: 3;
+};
+/** The name of any form `EMBEDDING_FORMS` defines. */
+export type EmbeddingFormName = keyof typeof EMBEDDING_FORMS;
+/** The bits of an embedding notification's flags byte. */
+export declare const EMBEDDING_FLAGS: {
+    readonly gap_in_window: number;
+    readonly duty_reduced: number;
+    readonly leadoff_in_window: number;
+    readonly more_parts: number;
+};
+/** One embedding notification, decoded: the whole vector, or the part carried here. */
+export interface Embedding {
+    /** 0x03 for an embedding. */
+    readonly packetType: number;
+    /** The window's first sample's index. */
+    readonly index: number;
+    /** The window's first sample's device time. */
+    readonly deviceTime: bigint;
+    /** The window's length, in raw samples at the current rate. */
+    readonly windowSamples: number;
+    /** The encoder that produced this, as `GET_MODEL_INFO` reports it. */
+    readonly encoderId: string;
+    /** An `INPUT_SOURCES` value. */
+    readonly inputSource: number;
+    /** Values in the whole vector. */
+    readonly embedDim: number;
+    /** Index of the first value carried here. */
+    readonly first: number;
+    /** Null for the window embedding; otherwise the token's index, channel-major over all channels. */
+    readonly token: number | null;
+    /** Whether another notification carries the rest of this vector. */
+    readonly moreParts: boolean;
+    /** Whether a gap fell inside the window. */
+    readonly gapInWindow: boolean;
+    /** Whether the device skipped windows to stay within its compute budget. */
+    readonly dutyReduced: boolean;
+    /** Whether an electrode was off at some point in the window. */
+    readonly leadoffInWindow: boolean;
+    /** Quantized values: the encoder's output times 4096. */
+    readonly values: number[];
+}
+/** One embedding notification, as the device sends it. */
+export declare function decodeEmbedding(data: Uint8Array): Embedding;
+/** What `encodeEmbedding` takes. */
+export interface EmbeddingFields {
+    /** The window's first sample's index. */
+    index: number;
+    /** The window's first sample's device time. */
+    deviceTime: bigint;
+    /** The window's length, in raw samples. */
+    windowSamples: number;
+    /** The encoder that produced this. */
+    encoderId: string;
+    /** An `INPUT_SOURCES` value. */
+    inputSource?: number;
+    /** Values in the whole embedding. */
+    embedDim: number;
+    /** Index of the first value carried here. */
+    first?: number;
+    /** Null for the window embedding, otherwise the token's index. */
+    token?: number | null;
+    /** Whether another notification carries the rest of this vector. */
+    moreParts?: boolean;
+    /** Whether a gap fell inside the window. */
+    gapInWindow?: boolean;
+    /** Whether the device skipped windows to stay within its compute budget. */
+    dutyReduced?: boolean;
+    /** Whether an electrode was off at some point in the window. */
+    leadoffInWindow?: boolean;
+    /** The values carried in this notification. */
+    values: ArrayLike<number>;
+}
+/** One embedding notification, as the device sends it. */
+export declare function encodeEmbedding(e: EmbeddingFields): Uint8Array;
+/** One window's embeddings, whole. */
+export interface EmbeddingWindow {
+    /** The window's first sample's index. */
+    readonly index: number;
+    /** The window's first sample's device time. */
+    readonly deviceTime: bigint;
+    /** The window's length, in raw samples. */
+    readonly windowSamples: number;
+    /** The encoder that produced this. */
+    readonly encoderId: string;
+    /** An `INPUT_SOURCES` value. */
+    readonly inputSource: number;
+    /** Values in the whole embedding. */
+    readonly embedDim: number;
+    /** Whether a gap fell inside the window. */
+    readonly gapInWindow: boolean;
+    /** Whether the device skipped windows to stay within its compute budget. */
+    readonly dutyReduced: boolean;
+    /** Whether an electrode was off at some point in the window. */
+    readonly leadoffInWindow: boolean;
+    /** The window embedding, quantized, when asked for. */
+    readonly embedding: number[] | null;
+    /** The tokens, quantized, `channels × tokensPerChannel` vectors of `embedDim`, channel-major, when asked for. */
+    readonly tokens: number[][] | null;
+}
+/**
+ * Puts notifications back together into whole windows. Built for a device's
+ * channel count, the model's tokens per channel, and the form asked for;
+ * `feed` takes each decoded notification and returns the window when its
+ * last piece arrives. Windows older than the two most recent that never
+ * completed are dropped and counted in `incomplete`.
+ */
+export declare class EmbeddingAssembler {
+    #private;
+    /** The device's channel count, as built. */
+    readonly channels: number;
+    /** Tokens per channel per window, as built. */
+    readonly tokensPerChannel: number;
+    /** Which form this was built for. */
+    readonly form: EmbeddingFormName;
+    /** Windows dropped before their last piece arrived. */
+    incomplete: number;
+    /** Build one for a device's channel count, the model's tokens per channel, and the form asked for. */
+    constructor(channels: number, tokensPerChannel: number, form?: EmbeddingFormName);
+    /** Tokens expected per window: `channels` times `tokensPerChannel`. */
+    get nTokens(): number;
+    /** Feed one decoded notification in. Returns the window once its last piece has arrived, else null. */
+    feed(e: Embedding): EmbeddingWindow | null;
+}
+/** The automatic low-pass corner for a rate, in tenths of a hertz. */
+export declare function lowPassAutoDhz(rateSps: number): number;
+/** The first corner a rate refuses, in tenths of a hertz: nine tenths of Nyquist. */
+export declare function cornerLimitDhz(rateSps: number): number;
+/** Whether a chain can run at a rate. Throws `Invalid` saying why not. */
+export declare function checkChain(stages: readonly Stage[], rateSps: number, catalog?: readonly CatalogEntry[]): void;
+/** The device's own default for a rate: a 0.5 Hz high-pass, the mains bands the rate can represent, the automatic low-pass. */
+export declare function defaultChain(rateSps: number): Stage[];
+/**
+ * The notch stages for a region's mains: the fundamental, its second and its third harmonic, four hertz wide.
+ * Given a rate, only the bands that rate can represent: at 250 samples a second the device refuses the higher harmonics.
+ */
+export declare function mainsBands(mainsHz: number, rateSps?: number): Stage[];
+/** The class of signal a chain produces: the time domain unless a stage is a representation change. */
+export declare function outputClass(stages: readonly Stage[], catalog?: readonly CatalogEntry[]): "time_domain" | "representation";
+/** A chain in words, for a manifest, a header, or a person. */
+export declare function describeChain(stages: readonly Stage[], rateSps?: number): string;
+/** The update service's operations, by name. */
+export declare const UPDATE_OPS: {
+    readonly start: 1;
+    readonly query: 2;
+    readonly finish: 3;
+    readonly activate: 4;
+    readonly abort: 5;
+};
+/** The name of any operation `UPDATE_OPS` defines. */
+export type UpdateOpName = keyof typeof UPDATE_OPS;
+/** Operation names by their number, the reverse of `UPDATE_OPS`. */
+export declare const UPDATE_OP_BY_CODE: Readonly<Record<number, UpdateOpName>>;
+/** What a transfer carries: an application, weights, or a head. */
+export declare const UPDATE_TARGETS: {
+    readonly app: 1;
+    readonly weights: 2;
+    readonly head: 3;
+};
+/** The name of any target `UPDATE_TARGETS` defines. */
+export type UpdateTargetName = keyof typeof UPDATE_TARGETS;
+/** Target names by their number, the reverse of `UPDATE_TARGETS`. */
+export declare const UPDATE_TARGET_BY_CODE: Readonly<Record<number, UpdateTargetName>>;
+/** What an update control response's status byte means. */
+export declare const UPDATE_STATUS: Readonly<Record<number, string>>;
+/** A transfer's state, in words, by its QUERY `state` code. */
+export declare const UPDATE_STATES: Readonly<Record<number, string>>;
+/** Why FINISH accepted or refused an image, in words, by its `verify_result` code. */
+export declare const VERIFY_RESULTS: Readonly<Record<number, string>>;
+/** The length of a START request, in bytes. */
+export declare const UPDATE_START_LEN = 15;
+/** The length of an image envelope's plain header, in bytes. */
+export declare const ENVELOPE_LEN = 32;
+/** An image envelope's magic bytes, as hex. */
+export declare const ENVELOPE_MAGIC = "494d5550";
+/** The only envelope version this contract defines. */
+export declare const ENVELOPE_VERSION = 1;
+/** The `slot_link` byte for an image that is not linked to an application slot. */
+export declare const SLOT_LINK_NONE = 255;
+/** A START request, as the device reads it. */
+export declare function encodeUpdateStart(target: UpdateTargetName | number, slot: number, totalLen: number, transferId: Uint8Array | string): Uint8Array;
+/** A request with no body: QUERY, FINISH, ACTIVATE, or ABORT, as the device reads it. */
+export declare function encodeUpdateOp(op: UpdateOpName): Uint8Array;
+/** An update control request, as `decodeUpdateRequest` reads it. */
+export interface UpdateRequest {
+    /** The raw operation byte. */
+    readonly op: number;
+    /** `op` in words. */
+    readonly opName: UpdateOpName;
+    /** What is being transferred, for a START request. Null otherwise. */
+    readonly target: number | null;
+    /** `target` in words. */
+    readonly targetName: UpdateTargetName | null;
+    /** The slot, for a START request. Null otherwise. */
+    readonly slot: number | null;
+    /** The exact byte count the host will send, for a START request. Null otherwise. */
+    readonly totalLen: number | null;
+    /** The transfer's identifier, for a START request. Null otherwise. */
+    readonly transferId: string | null;
+}
+/**
+ * An update control write, as the device reads it. An operation with no
+ * body arrives as exactly one byte.
+ */
+export declare function decodeUpdateRequest(data: Uint8Array): UpdateRequest;
+/** An update control response, as `decodeUpdateResponse` reads it. */
+export interface UpdateResponse {
+    /** The operation byte this answers. */
+    readonly op: number;
+    /** `op` in words, or null for a number this contract does not define. */
+    readonly opName: UpdateOpName | null;
+    /** The status byte, 0 for success. */
+    readonly status: number;
+    /** `status` in words. */
+    readonly statusName: string;
+    /** Whether `status` is 0. */
+    readonly ok: boolean;
+    /** FINISH says why it refused an image. No other operation carries one. */
+    readonly verifyResult: number | null;
+    /** `verifyResult` in words, or null when there is none. */
+    readonly verifyResultName: string | null;
+    /** The bytes after the operation and status. */
+    readonly payload: Uint8Array;
+}
+/** An update control response, as the device sends it. */
+export declare function decodeUpdateResponse(data: Uint8Array): UpdateResponse;
+/** An update control response, as the device sends it. */
+export declare function encodeUpdateResponse(op: number, status: number, payload?: Uint8Array): Uint8Array;
+/** START's answer: the slot, the chunk limit, and how much the device already has. */
+export interface UpdateStart {
+    /** Which slot the device wants the image in. */
+    readonly targetSlot: number;
+    /** The largest write it takes. */
+    readonly chunkMax: number;
+    /** How much of this transfer it already has. */
+    readonly resumeOffset: number;
+}
+/** START's answer, as the device sends it. */
+export declare function decodeUpdateStart(payload: Uint8Array): UpdateStart;
+/** QUERY's answer: the transfer's state, how much the device holds, and its checksum over that. */
+export interface UpdateQuery {
+    /** The transfer's state code. See `UPDATE_STATES`. */
+    readonly state: number;
+    /** `state` in words. */
+    readonly stateName: string;
+    /** Bytes the device has accepted so far. */
+    readonly offset: number;
+    /** The device's own checksum over every byte it has accepted. */
+    readonly crc32: number;
+}
+/** QUERY's answer, as the device sends it. */
+export declare function decodeUpdateQuery(payload: Uint8Array): UpdateQuery;
+/**
+ * The plain head of a wrapped image. Everything after it is encrypted and
+ * means nothing to a host, which is the point: a host carries an update
+ * without being able to read or forge one.
+ */
+export interface Envelope {
+    /** What is being transferred: application or weights. */
+    readonly target: number;
+    /** `target` in words. */
+    readonly targetName: UpdateTargetName;
+    /** Which application slot this image is built for. `SLOT_LINK_NONE` for weights. */
+    readonly slotLink: number;
+    /** The key identifier the envelope names. */
+    readonly keyId: number;
+    /** The encryption nonce. */
+    readonly nonce: Uint8Array;
+    /** Length of the encrypted payload, in bytes. */
+    readonly plainLen: number;
+    /** The envelope's length plus the payload's. */
+    readonly totalLen: number;
+}
+/** An image envelope's plain header, as the device reads it. */
+export declare function decodeEnvelope(data: Uint8Array): Envelope;
+/** An image envelope's plain header, as the device reads it. */
+export declare function encodeEnvelope(e: {
+    target: UpdateTargetName | number;
+    slotLink: number;
+    keyId: number;
+    nonce: Uint8Array;
+    plainLen: number;
+}): Uint8Array;
+/** A head blob's magic bytes, as hex. */
+export declare const HEAD_MAGIC = "494d4844";
+/** The length of a format 1 head header, in bytes. */
+export declare const HEAD_HEADER_LEN = 32;
+/** 1.3: format 2 appends the eight byte id of the encoder the head was trained beside. */
+export declare const HEAD_HEADER_LEN_2 = 40;
+/** The length of a head blob's trailing hash, in bytes. */
+export declare const HEAD_HASH_LEN = 32;
+/** The only head kind this contract defines. */
+export declare const HEAD_KIND_LINEAR = 1;
+/** The length of a head's name field, in bytes. */
+export declare const HEAD_NAME_LEN = 16;
+/**
+ * Counts per unit of embedding. Part of the contract: changing it would
+ * change every head ever trained.
+ */
+export declare const EMBED_SCALE = 4096;
+/** The exact length of a head blob for a shape and format version. */
+export declare function headBlobLen(inDim: number, outDim: number, version?: number): number;
+/**
+ * The integers a head receives for a float embedding. Saturates rather than
+ * wrapping, so an extreme value is clipped and never reversed.
+ */
+export declare function quantizeEmbedding(embedding: ArrayLike<number>): number[];
+/** A head, decoded: the weights, and everything needed to run them. */
+export interface HeadBlob {
+    /** `HEAD_KIND_LINEAR`, the only kind this contract defines. */
+    readonly kind: number;
+    /** The embedding width this head takes. Must equal the loaded encoder's. */
+    readonly inDim: number;
+    /** Outputs this head produces. */
+    readonly outDim: number;
+    /** The head's name. */
+    readonly name: string;
+    /** The head's identity, the first eight bytes of its SHA-256. */
+    readonly headId: string;
+    /** One row per output, each row `inDim` signed byte values. */
+    readonly weights: number[][];
+    /** One integer per output. */
+    readonly bias: number[];
+    /** One float per output. */
+    readonly scale: number[];
+    /** The format the file was written in: 1, or 2 with an encoder id. */
+    readonly version: number;
+    /** 1.3: the encoder the head was trained beside; `NO_ENCODER_ID` when the file does not say. The device never judges it. */
+    readonly encoderId: string;
+}
+/**
+ * A head blob, ready to upload.
+ *
+ * `weights` is one row per output, each row `inDim` values in the range a
+ * signed byte holds. `bias` is one integer per output and `scale` one float
+ * per output, which together carry whatever range the outputs need. The
+ * hash is computed here, because a head the device cannot check is a head
+ * the device refuses.
+ *
+ * `encoderId` names the encoder the head was trained beside (1.3, format 2),
+ * so a host can warn when it is uploaded to a device running another;
+ * `version` 1 writes the 1.0 header for a device that predates format 2.
+ */
+export declare function buildHead(weights: ReadonlyArray<ArrayLike<number>>, bias: ArrayLike<number>, scale: ArrayLike<number>, options?: {
+    name?: string;
+    inDim?: number;
+    encoderId?: string;
+    version?: number;
+}): Uint8Array;
+/** Read a head back, and check it the way the device does. */
+export declare function decodeHead(blob: Uint8Array): HeadBlob;
+/**
+ * What a head produces, computed the way the device computes it: the
+ * accumulation is exact in integers and only the scale is a float.
+ *
+ * `embedding` is the integers a head receives, which is what
+ * `quantizeEmbedding` returns. Floats are not taken here, because a head
+ * that was handed floats would silently produce something the device never
+ * would.
+ */
+export declare function evaluateHead(head: HeadBlob, embedding: ArrayLike<number>): number[];
+//# sourceMappingURL=protocol.d.ts.map