edfcore 0.1.0

package/src/diagnostics/codes.ts

@@ -0,0 +1,209 @@
+/**
+ * The diagnostic vocabulary.
+ *
+ * Layer 1. Imports nothing, so every other module may depend on it.
+ *
+ * A diagnostic is a *value*, never a log line. Each code has exactly one severity and one
+ * disposition, both fixed here:
+ *
+ * - `fatal`    — edfcore cannot proceed without inventing something. Always throws, even when
+ *                `strict` is false.
+ * - `deferred` — the header parses, but one signal cannot be scaled. `signal.scale` becomes
+ *                `undefined`, `decodeDigital` keeps working, and `toPhysical` throws.
+ * - `warning`  — the file is impolite but readable, and what we return is true.
+ * - `info`     — the file is correct; the note exists because the situation surprises people.
+ */
+
+export type EdfSeverity = 'error' | 'warning' | 'info';
+
+/** How a code behaves when it fires. See the module comment. */
+export type EdfDiagnosticDisposition = 'fatal' | 'deferred' | 'warning' | 'info';
+
+/**
+ * Every code edfcore itself can emit, grouped by disposition.
+ *
+ * This union and the `DISPOSITIONS` map below are checked against each other by the compiler:
+ * the map is typed as a total `Record` over this union, so a code added to one and not the
+ * other is a build error rather than a silent gap.
+ */
+export type EdfKnownDiagnosticCode =
+  // Always fatal
+  | 'NOT_AN_EDF_FILE'
+  | 'SOURCE_TOO_SMALL'
+  | 'SIGNAL_COUNT_INVALID'
+  | 'NUMERIC_FIELD_INVALID'
+  | 'COMMA_DECIMAL_SEPARATOR'
+  | 'RECORD_SIZE_ZERO'
+  | 'EDFPLUS_WITHOUT_ANNOTATION_SIGNAL'
+  | 'TIMELINE_NOT_MONOTONIC'
+  // Deferred-fatal: header parses, scaling does not
+  | 'DEGENERATE_DIGITAL_RANGE'
+  | 'DEGENERATE_PHYSICAL_RANGE'
+  | 'INVERTED_DIGITAL_RANGE'
+  | 'LOG_TRANSFORMED_CHANNEL'
+  | 'SCALE_UNAVAILABLE'
+  // Warnings
+  | 'HEADER_SIZE_MISMATCH'
+  | 'RECORD_COUNT_RECOVERED'
+  | 'TRUNCATED_FILE'
+  | 'PARTIAL_FINAL_RECORD'
+  | 'TRAILING_BYTES'
+  | 'RECORD_SIZE_ABOVE_RECOMMENDED'
+  | 'NONSTANDARD_RESERVED_FIELD'
+  | 'NON_ASCII_HEADER_FIELD'
+  | 'NUMERIC_FIELD_NOT_LEFT_JUSTIFIED'
+  | 'DATE_FIELDS_DISAGREE'
+  | 'DATE_UNPARSEABLE'
+  | 'PATIENT_ID_NONCONFORMANT'
+  | 'RECORDING_ID_NONCONFORMANT'
+  | 'DUPLICATE_SIGNAL_LABEL'
+  | 'DIGITAL_RANGE_EXCEEDS_FORMAT'
+  | 'ZERO_SAMPLES_PER_RECORD'
+  | 'ZERO_RECORD_DURATION'
+  | 'ANNOTATION_SIGNAL_HEADER_NONCONFORMANT'
+  | 'MISSING_EDFPLUS_MARKER'
+  | 'TIMEKEEPING_TAL_MISSING'
+  | 'TIMEKEEPING_TAL_NONCONFORMANT'
+  | 'START_OFFSET_OUT_OF_RANGE'
+  | 'TAL_MALFORMED'
+  | 'TAL_TRUNCATED_AT_REGION_END'
+  | 'TAL_REGION_NOT_NUL_TERMINATED'
+  | 'ANNOTATION_TEXT_NOT_UTF8'
+  | 'RECORD_ONSET_SPACING_VIOLATION'
+  | 'DISCONTINUITY_IN_CONTINUOUS_FILE'
+  // Info
+  | 'DATE_CLIPPED_TO_1985_2084'
+  | 'INVERTED_PHYSICAL_RANGE'
+  | 'NEGATIVE_ANNOTATION_ONSET';
+
+const DISPOSITIONS: Readonly<Record<EdfKnownDiagnosticCode, EdfDiagnosticDisposition>> = {
+  // ---- Always fatal --------------------------------------------------------
+  /** No recognisable EDF or BDF version block at offset 0. */
+  NOT_AN_EDF_FILE: 'fatal',
+  /** Fewer than 256 bytes, or fewer than 256*(ns+1). */
+  SOURCE_TOO_SMALL: 'fatal',
+  /** ns outside 1..9999, blank, or non-numeric. Every later offset is a multiple of it. */
+  SIGNAL_COUNT_INVALID: 'fatal',
+  /** A field the file geometry depends on failed its grammar end-to-end. */
+  NUMERIC_FIELD_INVALID: 'fatal',
+  /** '0,5' and '1,024' are indistinguishable; guessing turns 1024 into 1.024. */
+  COMMA_DECIMAL_SEPARATOR: 'fatal',
+  /** Every signal declares 0 samples per record, so records have no size to step by. */
+  RECORD_SIZE_ZERO: 'fatal',
+  /** EDF+ marker present but no annotation signal: no per-record timing exists, so any
+   *  time we reported would be invented. */
+  EDFPLUS_WITHOUT_ANNOTATION_SIGNAL: 'fatal',
+  /** Record onsets went backwards. Every time-based answer would be wrong. */
+  TIMELINE_NOT_MONOTONIC: 'fatal',
+
+  // ---- Deferred-fatal: header parses, scaling does not -----------------------
+  /** digitalMinimum === digitalMaximum. Division by zero. EDF+ spec item 5. */
+  DEGENERATE_DIGITAL_RANGE: 'deferred',
+  /** physicalMinimum === physicalMaximum. Every sample would map to one value. */
+  DEGENERATE_PHYSICAL_RANGE: 'deferred',
+  /** digitalMinimum > digitalMaximum. Violates EDF+ item 5; we will not guess the intent. */
+  INVERTED_DIGITAL_RANGE: 'deferred',
+  /** Physical dimension is exactly 'Filtered': values are log-compressed (edffloat.html),
+   *  so the linear formula would be wrong by orders of magnitude. Refused, not applied. */
+  LOG_TRANSFORMED_CHANNEL: 'deferred',
+  /** `toPhysical` was called on a signal with no scale and the specific cause was not
+   *  re-derivable from the signal alone. Naming the wrong cause would be worse. */
+  SCALE_UNAVAILABLE: 'deferred',
+
+  // ---- Warnings: the file stays readable and what we return is true ----------
+  /** Header byte-count field disagrees with 256*(ns+1). The computed value always wins. */
+  HEADER_SIZE_MISMATCH: 'warning',
+  /** recordCount was -1 (writer never closed the file); recovered from the source length. */
+  RECORD_COUNT_RECOVERED: 'warning',
+  /** The file is shorter than its declared record count implies. */
+  TRUNCATED_FILE: 'warning',
+  /** A final partial record exists. Only whole records are exposed; nothing is zero-padded. */
+  PARTIAL_FINAL_RECORD: 'warning',
+  /** Bytes exist beyond the last whole data record. */
+  TRAILING_BYTES: 'warning',
+  /** Record exceeds the 61440-byte recommendation. */
+  RECORD_SIZE_ABOVE_RECOMMENDED: 'warning',
+  /** Reserved field is neither blank nor a recognised EDF+/BDF+ marker. */
+  NONSTANDARD_RESERVED_FIELD: 'warning',
+  /** A header field carries bytes outside printable ASCII. Decoded as Latin-1. */
+  NON_ASCII_HEADER_FIELD: 'warning',
+  /** A numeric field is right-justified; the spec requires left-justified. */
+  NUMERIC_FIELD_NOT_LEFT_JUSTIFIED: 'warning',
+  /** Header startdate and the recording-id Startdate disagree. Both are exposed; we pick no winner. */
+  DATE_FIELDS_DISAGREE: 'warning',
+  /** The date could not be parsed at all. */
+  DATE_UNPARSEABLE: 'warning',
+  /** Patient identification does not follow the EDF+ subfield grammar. */
+  PATIENT_ID_NONCONFORMANT: 'warning',
+  /** Recording identification does not follow the EDF+ subfield grammar. */
+  RECORDING_ID_NONCONFORMANT: 'warning',
+  /** Two signals share a label. `getSignal` by label will throw for these. */
+  DUPLICATE_SIGNAL_LABEL: 'warning',
+  /** Declared digital range exceeds what the sample width can represent. */
+  DIGITAL_RANGE_EXCEEDS_FORMAT: 'warning',
+  /** A signal declares 0 samples per record. */
+  ZERO_SAMPLES_PER_RECORD: 'warning',
+  /** Record duration is 0. Legal in EDF+, but sample rates become undefined. */
+  ZERO_RECORD_DURATION: 'warning',
+  /** An annotation signal's header fields deviate from the EDF+ requirements. */
+  ANNOTATION_SIGNAL_HEADER_NONCONFORMANT: 'warning',
+  /** An 'EDF Annotations' signal exists without an EDF+ marker in the reserved field.
+   *  Annotations are parsed anyway; the channel is never exposed as an ordinary signal. */
+  MISSING_EDFPLUS_MARKER: 'warning',
+  /** A data record has no timekeeping TAL. */
+  TIMEKEEPING_TAL_MISSING: 'warning',
+  /** The timekeeping TAL exists but deviates (e.g. the widespread `+t 0x14 0x00` shorthand). */
+  TIMEKEEPING_TAL_NONCONFORMANT: 'warning',
+  /** Record 0's sub-second start offset fell outside [0, 1). */
+  START_OFFSET_OUT_OF_RANGE: 'warning',
+  /** A TAL did not match the grammar. That TAL is skipped; the file is kept. */
+  TAL_MALFORMED: 'warning',
+  /** A TAL ran past the end of its annotation region and was discarded. */
+  TAL_TRUNCATED_AT_REGION_END: 'warning',
+  /** The annotation region tail was not NUL padding. */
+  TAL_REGION_NOT_NUL_TERMINATED: 'warning',
+  /** Annotation text was not valid UTF-8; decoded as Latin-1 instead. */
+  ANNOTATION_TEXT_NOT_UTF8: 'warning',
+  /** Consecutive record onsets are not spaced by the record duration. */
+  RECORD_ONSET_SPACING_VIOLATION: 'warning',
+  /** A file marked EDF+C contains a real discontinuity. */
+  DISCONTINUITY_IN_CONTINUOUS_FILE: 'warning',
+
+  // ---- Info: correct, and deliberately not a warning ------------------------
+  /** A two-digit year was resolved through the spec's own 1985..2084 rule. Every conforming
+   *  EDF file has a two-digit year, so this is the normal path, not a defect — it is
+   *  reported only because the resolved century is worth being able to see. */
+  DATE_CLIPPED_TO_1985_2084: 'info',
+  /** physicalMinimum > physicalMaximum encodes a negative amplifier gain. Spec-sanctioned
+   *  (EDF FAQ Q6). Never "fixed" — swapping them is a silent polarity flip. */
+  INVERTED_PHYSICAL_RANGE: 'info',
+  /** A negative annotation onset is normal for pre-stimulus events. */
+  NEGATIVE_ANNOTATION_ONSET: 'info',
+};
+
+/**
+ * Open union: known codes autocomplete, and a `default` branch stays mandatory so adding a
+ * code in a minor release cannot break a consumer's exhaustive switch.
+ */
+export type EdfDiagnosticCode = EdfKnownDiagnosticCode | (string & {});
+
+export const DIAGNOSTIC_DISPOSITIONS: Readonly<
+  Record<EdfKnownDiagnosticCode, EdfDiagnosticDisposition>
+> = DISPOSITIONS;
+
+/** Unknown codes are treated as warnings — an unrecognised note must never escalate. */
+export function dispositionOf(code: EdfDiagnosticCode): EdfDiagnosticDisposition {
+  return DISPOSITIONS[code as EdfKnownDiagnosticCode] ?? 'warning';
+}
+
+export function severityOf(code: EdfDiagnosticCode): EdfSeverity {
+  const disposition = dispositionOf(code);
+  if (disposition === 'fatal' || disposition === 'deferred') return 'error';
+  if (disposition === 'warning') return 'warning';
+  return 'info';
+}
+
+/** Fires regardless of `strict`: proceeding would require inventing data. */
+export function isAlwaysFatal(code: EdfDiagnosticCode): boolean {
+  return dispositionOf(code) === 'fatal';
+}

package/src/diagnostics/collector.ts

@@ -0,0 +1,129 @@
+/**
+ * The strict-vs-collect decision.
+ *
+ * Layer 1. Every diagnostic edfcore emits is built here, which is what makes two invariants
+ * structural rather than conventional:
+ *
+ * - `strict: true` throws `EdfFormatError` carrying the first would-be diagnostic, so under
+ *   strict every `diagnostics` array is empty by construction;
+ * - a code whose disposition is `fatal` throws whether or not `strict` is set, because
+ *   proceeding would require inventing data.
+ *
+ * The caller never passes a severity — it is derived from the code by `severityOf`, so one code
+ * cannot acquire two severities in two call sites.
+ */
+
+import { EdfFormatError, type EdfFormatErrorInit } from '../errors.js';
+import type { EdfDiagnostic, ParseOptions } from '../types.js';
+import { type EdfDiagnosticCode, isAlwaysFatal, severityOf } from './codes.js';
+
+/**
+ * Everything a diagnostic may carry except its severity. Optional here, required-or-undefined
+ * on `EdfDiagnostic`: `createDiagnostic` normalises between the two, which is what lets the
+ * result type stay exhaustive under `exactOptionalPropertyTypes`.
+ */
+export interface DiagnosticInit {
+  readonly code: EdfDiagnosticCode;
+  /** Must name the field, the raw bytes as written, the rule, and an actionable next step. */
+  readonly message: string;
+  readonly field?: string;
+  readonly byteOffset?: number;
+  readonly byteLength?: number;
+  readonly rawBytes?: Uint8Array;
+  readonly raw?: string;
+  readonly expected?: string;
+  readonly actual?: string;
+  readonly signalIndex?: number;
+  readonly recordIndex?: number;
+  /** A spec clause, e.g. 'EDF+ additional specification 5'. */
+  readonly specReference?: string;
+}
+
+export function createDiagnostic(init: DiagnosticInit): EdfDiagnostic {
+  return {
+    code: init.code,
+    severity: severityOf(init.code),
+    message: init.message,
+    field: init.field,
+    byteOffset: init.byteOffset,
+    byteLength: init.byteLength,
+    // Copied, not aliased: a diagnostic outlives the read that produced it, and the caller's
+    // view is typically a subarray of a buffer an I/O adapter is free to reuse.
+    rawBytes: init.rawBytes === undefined ? undefined : init.rawBytes.slice(),
+    raw: init.raw,
+    expected: init.expected,
+    actual: init.actual,
+    signalIndex: init.signalIndex,
+    recordIndex: init.recordIndex,
+    specReference: init.specReference,
+  };
+}
+
+/**
+ * The one way to turn a diagnostic into the error that carries it. `EdfFormatError` re-derives
+ * `field`/`byteOffset`/`signalIndex`/`recordIndex` from the diagnostic, so they are not repeated.
+ */
+export function toFormatError(diagnostic: EdfDiagnostic, cause?: unknown): EdfFormatError {
+  const init: EdfFormatErrorInit =
+    cause === undefined
+      ? { code: diagnostic.code, diagnostic }
+      : { code: diagnostic.code, diagnostic, cause };
+  return new EdfFormatError(`[${diagnostic.code}] ${diagnostic.message}`, init);
+}
+
+/**
+ * `toFormatError(createDiagnostic(init))`, for the paths that throw without a sink — an always
+ * fatal code detected before one exists, or where the type system needs the `throw` to be
+ * visible at the call site.
+ */
+export function fatalError(init: DiagnosticInit, cause?: unknown): EdfFormatError {
+  return toFormatError(createDiagnostic(init), cause);
+}
+
+export class DiagnosticSink {
+  /**
+   * Readable so a caller can skip building a message it is about to throw away. Never so a
+   * caller can re-implement the decision in `report`.
+   */
+  readonly strict: boolean;
+
+  #collected: EdfDiagnostic[] = [];
+
+  constructor(options?: ParseOptions) {
+    this.strict = options?.strict === true;
+  }
+
+  get size(): number {
+    return this.#collected.length;
+  }
+
+  /**
+   * Records the diagnostic, or throws `EdfFormatError` when the code is always fatal, or when
+   * `strict` is set and the code describes an actual defect. There is no severity parameter
+   * by design.
+   *
+   * `info` codes are exempt from `strict`. They exist to explain something that is correct but
+   * surprising — a spec-sanctioned negative gain, a pre-stimulus onset, the mandated two-digit
+   * year rule — so throwing on one would contradict what the severity means, and would make
+   * `strict` reject conforming files. Every `info` note is still collected and readable.
+   */
+  report(init: DiagnosticInit): void {
+    const diagnostic = createDiagnostic(init);
+    if (isAlwaysFatal(diagnostic.code) || (this.strict && diagnostic.severity !== 'info')) {
+      throw toFormatError(diagnostic);
+    }
+    this.#collected.push(diagnostic);
+  }
+
+  /** A frozen copy: an array already attached to a result must not grow if reporting continues. */
+  get diagnostics(): readonly EdfDiagnostic[] {
+    return Object.freeze(this.#collected.slice());
+  }
+
+  /** `diagnostics`, then reset — for a sink reused across records. */
+  drain(): readonly EdfDiagnostic[] {
+    const collected = this.diagnostics;
+    this.#collected = [];
+    return collected;
+  }
+}

package/src/diagnostics/format.ts

@@ -0,0 +1,143 @@
+/**
+ * Rendering diagnostics for humans.
+ *
+ * Layer 1. Layout only: by the message contract a diagnostic's own message already names the
+ * field, the raw bytes as written, the rule and the next step, so this module adds structure —
+ * severity marker, code, location, the bytes as hex — and invents no wording.
+ *
+ * Output is deterministic and asserted as such: no locale-sensitive number or date formatting,
+ * no iteration over an unordered collection, and no ANSI escapes unless `color` is requested.
+ */
+
+import type { EdfDiagnostic, EdfSeverity } from '../types.js';
+
+export interface FormatDiagnosticsOptions {
+  readonly color?: boolean;
+  readonly maxItems?: number;
+}
+
+const INDENT = '  ';
+
+/** A report is a summary, not a hex dump; longer runs are elided with a count. */
+const MAX_RAW_BYTES_SHOWN = 24;
+
+const ANSI_RESET = '\u001b[0m';
+const ANSI_DIM = '\u001b[2m';
+
+const SEVERITY_COLORS: Readonly<Record<EdfSeverity, string>> = {
+  error: '\u001b[31m',
+  warning: '\u001b[33m',
+  info: '\u001b[36m',
+};
+
+/**
+ * A multi-line report, one block per diagnostic. Returns `''` for an empty list so the result
+ * can be concatenated into a larger report without a stray blank line.
+ */
+export function formatDiagnostics(
+  diagnostics: readonly EdfDiagnostic[],
+  options?: FormatDiagnosticsOptions,
+): string {
+  const color = options?.color === true;
+  const shown = resolveLimit(options?.maxItems, diagnostics.length);
+  const lines: string[] = [];
+
+  for (let i = 0; i < shown; i++) {
+    const diagnostic = diagnostics[i];
+    // i < shown <= diagnostics.length, so this only satisfies noUncheckedIndexedAccess.
+    if (diagnostic === undefined) continue;
+    appendDiagnostic(lines, diagnostic, color);
+  }
+
+  const hidden = diagnostics.length - shown;
+  if (hidden > 0) lines.push(paint(`... and ${hidden} more`, ANSI_DIM, color));
+
+  return lines.join('\n');
+}
+
+function resolveLimit(maxItems: number | undefined, total: number): number {
+  if (maxItems === undefined || !Number.isFinite(maxItems)) return total;
+  return Math.max(0, Math.min(total, Math.floor(maxItems)));
+}
+
+function appendDiagnostic(lines: string[], diagnostic: EdfDiagnostic, color: boolean): void {
+  const marker = paint(
+    `${diagnostic.severity} [${diagnostic.code}]`,
+    SEVERITY_COLORS[diagnostic.severity],
+    color,
+  );
+
+  const messageLines = diagnostic.message.split('\n');
+  const first = messageLines[0] ?? '';
+  lines.push(`${marker} ${first}`.trimEnd());
+  for (let i = 1; i < messageLines.length; i++) {
+    const line = messageLines[i];
+    if (line === undefined) continue;
+    lines.push(`${INDENT}${line.trim()}`);
+  }
+
+  const location = locationOf(diagnostic);
+  if (location !== undefined) detail(lines, location, color);
+  if (diagnostic.raw !== undefined) detail(lines, `raw: ${quote(diagnostic.raw)}`, color);
+  if (diagnostic.rawBytes !== undefined && diagnostic.rawBytes.length > 0) {
+    detail(lines, `bytes: ${hexDump(diagnostic.rawBytes)}`, color);
+  }
+  if (diagnostic.expected !== undefined) detail(lines, `expected: ${diagnostic.expected}`, color);
+  if (diagnostic.actual !== undefined) detail(lines, `actual: ${diagnostic.actual}`, color);
+  if (diagnostic.specReference !== undefined) {
+    detail(lines, `spec: ${diagnostic.specReference}`, color);
+  }
+}
+
+function detail(lines: string[], text: string, color: boolean): void {
+  lines.push(`${INDENT}${paint(text, ANSI_DIM, color)}`);
+}
+
+function locationOf(diagnostic: EdfDiagnostic): string | undefined {
+  const parts: string[] = [];
+  if (diagnostic.byteOffset !== undefined) {
+    parts.push(
+      diagnostic.byteLength === undefined
+        ? `byte offset ${diagnostic.byteOffset}`
+        : `byte offset ${diagnostic.byteOffset} (${diagnostic.byteLength} bytes)`,
+    );
+  }
+  if (diagnostic.field !== undefined) parts.push(diagnostic.field);
+  if (diagnostic.signalIndex !== undefined) parts.push(`signal ${diagnostic.signalIndex}`);
+  if (diagnostic.recordIndex !== undefined) parts.push(`record ${diagnostic.recordIndex}`);
+  return parts.length === 0 ? undefined : `at ${parts.join(', ')}`;
+}
+
+/** `30 20 20 20  |0   |`. Built byte by byte — TextDecoder is banned outside `src/tal/`. */
+function hexDump(bytes: Uint8Array): string {
+  const shown = bytes.subarray(0, MAX_RAW_BYTES_SHOWN);
+  const hex: string[] = [];
+  let ascii = '';
+  for (const byte of shown) {
+    hex.push(byte.toString(16).padStart(2, '0'));
+    ascii += isPrintableAscii(byte) ? String.fromCharCode(byte) : '.';
+  }
+  const elided = bytes.length - shown.length;
+  return `${hex.join(' ')}  |${ascii}|${elided > 0 ? ` +${elided} more` : ''}`;
+}
+
+function isPrintableAscii(byte: number): boolean {
+  return byte >= 0x20 && byte <= 0x7e;
+}
+
+/** Keeps every entry on one line: control and non-ASCII characters become escapes, not bytes. */
+function quote(value: string): string {
+  let out = '"';
+  for (const char of value) {
+    const code = char.codePointAt(0) ?? 0;
+    if (char === '"' || char === '\\') out += `\\${char}`;
+    else if (isPrintableAscii(code)) out += char;
+    else if (code <= 0xff) out += `\\x${code.toString(16).padStart(2, '0')}`;
+    else out += `\\u{${code.toString(16)}}`;
+  }
+  return `${out}"`;
+}
+
+function paint(text: string, color: string, enabled: boolean): string {
+  return enabled ? `${color}${text}${ANSI_RESET}` : text;
+}

package/src/errors.ts

@@ -0,0 +1,208 @@
+/**
+ * The error hierarchy.
+ *
+ * Layer 1. One rule decides which of these you get: if edfcore cannot proceed without
+ * inventing something, it throws; if it can proceed truthfully, it records an `EdfDiagnostic`.
+ * There is no third category, and there is no `console` call anywhere in this package.
+ *
+ * `edfErrorKind` exists so consumers can discriminate without `instanceof`, which fails across
+ * realms — an iframe, a worker, or two copies of the package in one dependency tree.
+ */
+
+import type { EdfDiagnostic, EdfDiagnosticCode, RecordRange } from './types.js';
+
+export type EdfErrorKind = 'format' | 'scaling' | 'range' | 'source' | 'budget' | 'channel';
+
+export abstract class EdfError extends Error {
+  abstract readonly edfErrorKind: EdfErrorKind;
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options as ErrorOptions | undefined);
+    this.name = new.target.name;
+  }
+}
+
+/**
+ * Every concrete error edfcore throws.
+ *
+ * This exists so `edfErrorKind` actually discriminates in TypeScript. `EdfError` alone
+ * declares only the kind, so narrowing against the abstract class leaves the extra fields
+ * (`code`, `budgetBytes`, `matchingIndices`, …) unreachable and forces a cast at every call
+ * site. Switching on `edfErrorKind` over this union reaches them without one.
+ */
+export type AnyEdfError =
+  | EdfFormatError
+  | EdfScalingError
+  | EdfRangeError
+  | EdfSourceError
+  | EdfBudgetError
+  | EdfAmbiguousChannelError
+  | EdfChannelNotFoundError;
+
+/**
+ * Returns true for any error thrown by edfcore, across realms.
+ *
+ * Checks the `edfErrorKind` brand rather than `instanceof`, which fails whenever the error
+ * crossed a realm boundary — an iframe, a worker, or two copies of the package in one
+ * dependency tree.
+ *
+ * Note that a handful of caller-error paths deliberately throw a plain `RangeError` instead
+ * (asking for records that cannot exist, or handing an annotation channel to a sample read).
+ * Those are bugs in the calling code rather than problems with the file, and this returns
+ * false for them.
+ */
+export function isEdfError(value: unknown): value is AnyEdfError {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as { edfErrorKind?: unknown }).edfErrorKind === 'string'
+  );
+}
+
+export interface EdfFormatErrorInit {
+  readonly code: EdfDiagnosticCode;
+  readonly diagnostic?: EdfDiagnostic;
+  readonly field?: string;
+  readonly byteOffset?: number;
+  readonly signalIndex?: number;
+  readonly recordIndex?: number;
+  readonly cause?: unknown;
+}
+
+/**
+ * The file is wrong. Also what `strict: true` throws, carrying the diagnostic that would
+ * otherwise have been collected.
+ */
+export class EdfFormatError extends EdfError {
+  readonly edfErrorKind = 'format' as const;
+  readonly code: EdfDiagnosticCode;
+  readonly diagnostic: EdfDiagnostic | undefined;
+  readonly field: string | undefined;
+  readonly byteOffset: number | undefined;
+  readonly signalIndex: number | undefined;
+  readonly recordIndex: number | undefined;
+
+  constructor(message: string, init: EdfFormatErrorInit) {
+    super(message, { cause: init.cause });
+    this.code = init.code;
+    this.diagnostic = init.diagnostic;
+    this.field = init.field ?? init.diagnostic?.field;
+    this.byteOffset = init.byteOffset ?? init.diagnostic?.byteOffset;
+    this.signalIndex = init.signalIndex ?? init.diagnostic?.signalIndex;
+    this.recordIndex = init.recordIndex ?? init.diagnostic?.recordIndex;
+  }
+}
+
+/**
+ * Physical units are unavailable for one signal, because the header's ranges do not define a
+ * scale. `decodeDigital` still works on that signal — edfcore will not invent a gain.
+ */
+export class EdfScalingError extends EdfError {
+  readonly edfErrorKind = 'scaling' as const;
+  readonly code: EdfDiagnosticCode;
+  readonly signalIndex: number;
+  readonly label: string;
+
+  constructor(
+    message: string,
+    init: { code: EdfDiagnosticCode; signalIndex: number; label: string; cause?: unknown },
+  ) {
+    super(message, { cause: init.cause });
+    this.code = init.code;
+    this.signalIndex = init.signalIndex;
+    this.label = init.label;
+  }
+}
+
+/** Your bug, not the file's: you asked for records that do not exist. */
+export class EdfRangeError extends EdfError {
+  readonly edfErrorKind = 'range' as const;
+  readonly requested: RecordRange;
+  readonly available: RecordRange;
+
+  constructor(
+    message: string,
+    init: { requested: RecordRange; available: RecordRange; cause?: unknown },
+  ) {
+    super(message, { cause: init.cause });
+    this.requested = init.requested;
+    this.available = init.available;
+  }
+}
+
+/** A `ByteSource` broke its contract: it returned a different number of bytes than asked. */
+export class EdfSourceError extends EdfError {
+  readonly edfErrorKind = 'source' as const;
+  readonly offset: number;
+  readonly requestedLength: number;
+  readonly receivedLength: number | undefined;
+
+  constructor(
+    message: string,
+    init: {
+      offset: number;
+      requestedLength: number;
+      receivedLength?: number | undefined;
+      cause?: unknown;
+    },
+  ) {
+    super(message, { cause: init.cause });
+    this.offset = init.offset;
+    this.requestedLength = init.requestedLength;
+    this.receivedLength = init.receivedLength;
+  }
+}
+
+/**
+ * An allocation was refused before it happened. Float64 physical output is four times the
+ * on-disk size for EDF, so without this one honest call can take down a browser tab.
+ */
+export class EdfBudgetError extends EdfError {
+  readonly edfErrorKind = 'budget' as const;
+  readonly requiredBytes: number;
+  readonly budgetBytes: number;
+  readonly optionName = 'maxMaterializeBytes' as const;
+
+  constructor(
+    message: string,
+    init: { requiredBytes: number; budgetBytes: number; cause?: unknown },
+  ) {
+    super(message, { cause: init.cause });
+    this.requiredBytes = init.requiredBytes;
+    this.budgetBytes = init.budgetBytes;
+  }
+}
+
+/**
+ * Two or more signals share the requested label. Real files do this: CHB-MIT ships `T8-P8`
+ * twice. Silently returning the first is how the wrong channel ends up in a paper.
+ */
+export class EdfAmbiguousChannelError extends EdfError {
+  readonly edfErrorKind = 'channel' as const;
+  readonly label: string;
+  readonly matchingIndices: readonly number[];
+
+  constructor(
+    message: string,
+    init: { label: string; matchingIndices: readonly number[]; cause?: unknown },
+  ) {
+    super(message, { cause: init.cause });
+    this.label = init.label;
+    this.matchingIndices = init.matchingIndices;
+  }
+}
+
+export class EdfChannelNotFoundError extends EdfError {
+  readonly edfErrorKind = 'channel' as const;
+  readonly selector: string | number;
+  readonly availableLabels: readonly string[];
+
+  constructor(
+    message: string,
+    init: { selector: string | number; availableLabels: readonly string[]; cause?: unknown },
+  ) {
+    super(message, { cause: init.cause });
+    this.selector = init.selector;
+    this.availableLabels = init.availableLabels;
+  }
+}