edfcore 0.1.0

package/src/header/variant.ts

@@ -0,0 +1,239 @@
+/**
+ * Which dialect the file claims to be.
+ *
+ * Layer 2. Sole owner of the version-block and reserved-field grammars — the two fields that
+ * decide sample width, EDF+ dialect and continuity, and therefore every byte offset and every
+ * time value computed downstream.
+ *
+ * Two rules deserve stating because they look wrong:
+ *
+ * - The 8-byte version block is the ONLY reliable EDF-vs-BDF discriminator. EDF+ deliberately
+ *   keeps `'0       '` so legacy readers still open the file, so nothing in the reserved field
+ *   can be trusted to identify the family.
+ * - BDF's version block is not ASCII: byte 0 is 0xFF, then `'BIOSEMI'`.
+ */
+
+import { trimEdfField } from '../bytes/latin1.js';
+import { readAsciiField, sliceBytes } from '../bytes/view.js';
+import {
+  BDF_ANNOTATIONS_LABEL,
+  BDF_DIGITAL_MAX,
+  BDF_DIGITAL_MIN,
+  EDF_ANNOTATIONS_LABEL,
+  EDF_DIGITAL_MAX,
+  EDF_DIGITAL_MIN,
+  HEADER_FIELDS,
+} from '../constants.js';
+import { type DiagnosticSink, fatalError } from '../diagnostics/collector.js';
+import type { EdfVariant } from '../types.js';
+
+/** ASCII `'0'`: the whole of EDF's version block, before padding. */
+const EDF_VERSION_BYTE = 0x30;
+/** Not ASCII. This single byte is what separates a BDF file from an EDF one. */
+const BDF_VERSION_BYTE = 0xff;
+const BDF_VERSION_TEXT = 'BIOSEMI';
+
+const CHAR_NUL = 0x00;
+const CHAR_SPACE = 0x20;
+
+const EDF_BYTES_PER_SAMPLE = 2 as const;
+const BDF_BYTES_PER_SAMPLE = 3 as const;
+
+export type EdfFamily = 'EDF' | 'BDF';
+
+/** The recognised reserved-field prefixes. Matched on the first five bytes, never trimmed. */
+export type EdfReservedMarker = 'EDF+C' | 'EDF+D' | 'BDF+C' | 'BDF+D' | '24BIT';
+
+const RESERVED_MARKERS: readonly EdfReservedMarker[] = [
+  'EDF+C',
+  'EDF+D',
+  'BDF+C',
+  'BDF+D',
+  '24BIT',
+];
+
+export interface EdfVariantInfo {
+  readonly variant: EdfVariant;
+  /** From the version block alone. Sample width follows from this and nothing else. */
+  readonly family: EdfFamily;
+  readonly bytesPerSample: 2 | 3;
+  readonly continuity: 'continuous' | 'discontinuous';
+  /** True for EDF+C/EDF+D/BDF+C/BDF+D: the file claims the EDF+ dialect, so the subfield
+   *  grammars in `identification.ts` apply and an annotation signal is mandatory. */
+  readonly isPlus: boolean;
+  /** The five-byte prefix that actually matched, or `undefined` when the field is blank or
+   *  unrecognised. */
+  readonly reservedMarker: EdfReservedMarker | undefined;
+  /** Trimmed, case-sensitive annotation label for this family. */
+  readonly annotationsLabel: string;
+  /** What the sample width can represent. Drives `DIGITAL_RANGE_EXCEEDS_FORMAT`. */
+  readonly digitalMinimumLimit: number;
+  readonly digitalMaximumLimit: number;
+}
+
+/**
+ * EDF's version block: ASCII `'0'` then seven spaces.
+ *
+ * NUL is accepted as padding alongside space. The spec says space, but a writer that pads with
+ * NUL has produced the same value, and `NOT_AN_EDF_FILE` — the only alternative here — would
+ * refuse a file whose every other byte is fine.
+ */
+export function isEdfVersionBlock(versionBytes: Uint8Array): boolean {
+  if (versionBytes[0] !== EDF_VERSION_BYTE) return false;
+  for (let i = 1; i < versionBytes.length; i++) {
+    const byte = versionBytes[i];
+    if (byte !== CHAR_SPACE && byte !== CHAR_NUL) return false;
+  }
+  return true;
+}
+
+/** BDF's version block: byte 0 = 0xFF, bytes 1..7 = `'BIOSEMI'`. Exact, no padding tolerance. */
+export function isBdfVersionBlock(versionBytes: Uint8Array): boolean {
+  if (versionBytes[0] !== BDF_VERSION_BYTE) return false;
+  for (let i = 0; i < BDF_VERSION_TEXT.length; i++) {
+    if (versionBytes[i + 1] !== BDF_VERSION_TEXT.charCodeAt(i)) return false;
+  }
+  return true;
+}
+
+/**
+ * The dialect marker carried by the reserved field, matched on its five-byte PREFIX.
+ *
+ * The prefix rule is what makes `'EDF+D v2.1'` an EDF+D file rather than an unrecognised one.
+ */
+export function reservedMarkerOf(reserved: string): EdfReservedMarker | undefined {
+  for (const marker of RESERVED_MARKERS) {
+    if (reserved.startsWith(marker)) return marker;
+  }
+  return undefined;
+}
+
+function markerFamily(marker: EdfReservedMarker): EdfFamily {
+  return marker === 'EDF+C' || marker === 'EDF+D' ? 'EDF' : 'BDF';
+}
+
+function hexBytes(bytes: Uint8Array): string {
+  const parts: string[] = [];
+  for (const byte of bytes) parts.push(byte.toString(16).padStart(2, '0'));
+  return parts.join(' ');
+}
+
+function variantOf(
+  family: EdfFamily,
+  isPlus: boolean,
+  continuity: 'continuous' | 'discontinuous',
+): EdfVariant {
+  if (!isPlus) return family;
+  if (family === 'BDF') return continuity === 'discontinuous' ? 'BDF+D' : 'BDF+C';
+  return continuity === 'discontinuous' ? 'EDF+D' : 'EDF+C';
+}
+
+/**
+ * Read the version block and the reserved field, and decide the variant.
+ *
+ * `headerBytes` must cover at least the 256-byte fixed header; the caller has already refused
+ * anything shorter with `SOURCE_TOO_SMALL`.
+ *
+ * When the reserved marker names a different family than the version block does — `'BDF+C'` on
+ * a file whose version block is EDF — the version block wins for the family, but the marker is
+ * still honoured for continuity and EDF+ dialect, and the disagreement is reported. Dropping
+ * the `D` would silently turn a discontinuous recording into one whose every timestamp is
+ * wrong; keeping the wrong sample width would make every sample wrong instead.
+ */
+export function detectVariant(headerBytes: Uint8Array, sink: DiagnosticSink): EdfVariantInfo {
+  const versionBytes = sliceBytes(
+    headerBytes,
+    HEADER_FIELDS.version.offset,
+    HEADER_FIELDS.version.length,
+  );
+  const isBdf = isBdfVersionBlock(versionBytes);
+  const isEdf = !isBdf && isEdfVersionBlock(versionBytes);
+
+  if (!isBdf && !isEdf) {
+    const raw = readAsciiField(
+      headerBytes,
+      HEADER_FIELDS.version.offset,
+      HEADER_FIELDS.version.length,
+    );
+    throw fatalError({
+      code: 'NOT_AN_EDF_FILE',
+      message:
+        `version field (8 bytes at offset ${HEADER_FIELDS.version.offset}) is ` +
+        `${JSON.stringify(raw)}, bytes ${hexBytes(versionBytes)}: this is neither EDF's ` +
+        `"0" followed by seven spaces nor BDF's 0xFF followed by "BIOSEMI". ` +
+        'EDF specification, header record bytes 0-7 (version of this data format). ' +
+        'Next: confirm the bytes are an uncompressed EDF or BDF recording — a gzip, zip or ' +
+        'vendor container has to be unpacked before edfcore sees it.',
+      field: 'version',
+      byteOffset: HEADER_FIELDS.version.offset,
+      byteLength: HEADER_FIELDS.version.length,
+      rawBytes: versionBytes,
+      raw,
+      expected: '"0       " (EDF) or 0xFF "BIOSEMI" (BDF)',
+      actual: hexBytes(versionBytes),
+      specReference: 'EDF specification, header record bytes 0-7',
+    });
+  }
+
+  const family: EdfFamily = isBdf ? 'BDF' : 'EDF';
+  const reservedRaw = readAsciiField(
+    headerBytes,
+    HEADER_FIELDS.reserved.offset,
+    HEADER_FIELDS.reserved.length,
+  );
+  const marker = reservedMarkerOf(reservedRaw);
+  const reservedText = trimEdfField(reservedRaw);
+
+  if (marker === undefined && reservedText.length > 0) {
+    sink.report({
+      code: 'NONSTANDARD_RESERVED_FIELD',
+      message:
+        `reserved field (44 bytes at offset ${HEADER_FIELDS.reserved.offset}) is ` +
+        `${JSON.stringify(reservedText)}, which is neither blank nor one of the recognised ` +
+        'five-byte markers "EDF+C", "EDF+D", "BDF+C", "BDF+D" or "24BIT". EDF+ specification ' +
+        '2.1.1: the reserved field must start with "EDF+C" when the recording is ' +
+        'uninterrupted and "EDF+D" when it is not. Next: the file is read as plain ' +
+        `${family}; header.reserved keeps all 44 bytes verbatim.`,
+      field: 'reserved',
+      byteOffset: HEADER_FIELDS.reserved.offset,
+      byteLength: HEADER_FIELDS.reserved.length,
+      raw: reservedRaw,
+      expected: '"" or one of "EDF+C", "EDF+D", "BDF+C", "BDF+D", "24BIT"',
+      actual: reservedText,
+      specReference: 'EDF+ specification 2.1.1 (the EDF+ header)',
+    });
+  } else if (marker !== undefined && markerFamily(marker) !== family) {
+    sink.report({
+      code: 'NONSTANDARD_RESERVED_FIELD',
+      message:
+        `reserved field (44 bytes at offset ${HEADER_FIELDS.reserved.offset}) declares ` +
+        `${JSON.stringify(marker)} but the version block says this file is ${family}, and ` +
+        'the version block is the only reliable discriminator (EDF+ keeps "0       " so ' +
+        `legacy readers still open the file). Next: the file is read as ${family} with ` +
+        `${family === 'BDF' ? 3 : 2} bytes per sample; the marker's continuity is still ` +
+        'honoured, because ignoring a "D" would make every reported time wrong.',
+      field: 'reserved',
+      byteOffset: HEADER_FIELDS.reserved.offset,
+      byteLength: HEADER_FIELDS.reserved.length,
+      raw: reservedRaw,
+      expected: family === 'BDF' ? '"BDF+C", "BDF+D" or "24BIT"' : '"EDF+C" or "EDF+D"',
+      actual: marker,
+      specReference: 'EDF specification, header record bytes 0-7',
+    });
+  }
+
+  const isPlus = marker !== undefined && marker !== '24BIT';
+  const continuity = marker === 'EDF+D' || marker === 'BDF+D' ? 'discontinuous' : 'continuous';
+
+  return {
+    variant: variantOf(family, isPlus, continuity),
+    family,
+    bytesPerSample: family === 'BDF' ? BDF_BYTES_PER_SAMPLE : EDF_BYTES_PER_SAMPLE,
+    continuity,
+    isPlus,
+    reservedMarker: marker,
+    annotationsLabel: family === 'BDF' ? BDF_ANNOTATIONS_LABEL : EDF_ANNOTATIONS_LABEL,
+    digitalMinimumLimit: family === 'BDF' ? BDF_DIGITAL_MIN : EDF_DIGITAL_MIN,
+    digitalMaximumLimit: family === 'BDF' ? BDF_DIGITAL_MAX : EDF_DIGITAL_MAX,
+  };
+}

package/src/index.ts

@@ -0,0 +1,151 @@
+/**
+ * `edfcore` — the universal entry point.
+ *
+ * Layer 7. Re-exports only: this file contains no logic, so nothing can be true here that is not
+ * true in the module that owns it.
+ *
+ * Two rules hold for everything reachable from this file, transitively:
+ *
+ * - NO import of a Node built-in, transitively. `edfcore/node` is the only module allowed one, and
+ *   a packaging test greps the built universal bundle for the scheme prefix to prove it — which is
+ *   also why that prefix is not written out anywhere in this file. It is what lets one build serve
+ *   Node, browsers, Deno and Bun with no environment conditions in the exports map: conditions are
+ *   the single largest source of ecosystem incompatibility, and a dual CJS/ESM build would load
+ *   two copies of `EdfFormatError` and break every `instanceof`.
+ * - NO top-level `await`, which is what makes `require(esm)` on Node >= 22.12 safe.
+ *
+ * The API is three layers, and they are meant to be visible as three. PRIMITIVES are pure,
+ * synchronous and take bytes; the I/O LAYER is thin, async and does no caching; the CONVENIENCE
+ * LAYER is composition over both. A consumer who outgrows the top layer drops to the one below it
+ * without leaving the package.
+ */
+
+// ===========================================================================
+// Types — every public data shape. `export type` throughout, for
+// verbatimModuleSyntax and so nothing here emits a runtime import.
+// ===========================================================================
+
+/** The trailing `options` argument shared by every primitive that can allocate. */
+export type { MaterializeOptions } from './decode/digital.js';
+export type { FormatDiagnosticsOptions } from './diagnostics/format.js';
+export type {
+  AbortSignalLike,
+  BlobLike,
+  BuildIndexOptions,
+  ByteSource,
+  CacheOptions,
+  DecodeAnnotationsOptions,
+  EdfAnnotation,
+  EdfAnnotationsResult,
+  EdfCalendarDate,
+  EdfChunk,
+  EdfChunkSignal,
+  EdfClockTime,
+  EdfDiagnostic,
+  EdfDiagnosticCode,
+  EdfGap,
+  EdfHeader,
+  EdfInspection,
+  EdfKnownDiagnosticCode,
+  EdfLocation,
+  EdfPatientId,
+  EdfRawHeaderFields,
+  EdfRawSignalFields,
+  EdfRecordIndex,
+  EdfRecording,
+  EdfRecordingId,
+  EdfScale,
+  EdfSegment,
+  EdfSeverity,
+  EdfSignal,
+  EdfStartTime,
+  EdfTimeline,
+  EdfVariant,
+  FetchLike,
+  HttpResponseLike,
+  HttpSourceOptions,
+  OpenOptions,
+  ParseOptions,
+  ReadOptions,
+  RecordRange,
+  RecordSelection,
+  WindowSelection,
+} from './types.js';
+
+// ===========================================================================
+// Errors
+//
+// `edfErrorKind` is the supported way to discriminate: `instanceof` is false across a realm
+// boundary — an iframe, a worker, two copies of the package in one tree — and `isEdfError`
+// exists so that check has one spelling.
+// ===========================================================================
+
+export type { AnyEdfError, EdfErrorKind, EdfFormatErrorInit } from './errors.js';
+export {
+  EdfAmbiguousChannelError,
+  EdfBudgetError,
+  EdfChannelNotFoundError,
+  EdfError,
+  EdfFormatError,
+  EdfRangeError,
+  EdfScalingError,
+  EdfSourceError,
+  isEdfError,
+} from './errors.js';
+
+// ===========================================================================
+// Constants
+// ===========================================================================
+
+export {
+  BDF_ANNOTATIONS_LABEL,
+  BDF_DIGITAL_MAX,
+  BDF_DIGITAL_MIN,
+  EDF_ANNOTATIONS_LABEL,
+  EDF_DIGITAL_MAX,
+  EDF_DIGITAL_MIN,
+  EDF_HEADER_BLOCK_BYTES,
+  EDF_RECOMMENDED_MAX_RECORD_BYTES,
+  TICKS_PER_SECOND,
+  VERSION,
+} from './constants.js';
+
+// ===========================================================================
+// Primitives — pure, synchronous, zero I/O. Every one of these is testable
+// from a Uint8Array literal with no mocks.
+// ===========================================================================
+
+export { decodeHeaderLatin1 } from './bytes/latin1.js';
+export { decodeDigital } from './decode/digital.js';
+export { clampToDigitalRange, toPhysical } from './decode/physical.js';
+export { formatDiagnostics } from './diagnostics/format.js';
+export { formatStartTimeNaive } from './header/dates.js';
+export { findSignals, getSignal, isAnnotationLabel } from './header/lookup.js';
+export { parseHeader } from './header/parse.js';
+export { decodeAnnotations } from './tal/annotations.js';
+export { resolveTimeWindow, trimToWindow } from './time/window.js';
+
+// ===========================================================================
+// I/O adapters — universal, format-independent, and none of them caches.
+// `cachedSource` is the only cache in edfcore: opt-in, visible at the call
+// site, and removed by deleting one wrapper.
+// ===========================================================================
+
+export { blobSource } from './io/blob.js';
+export { byteSource } from './io/bytes.js';
+export { cachedSource } from './io/cached.js';
+export { httpSource } from './io/http.js';
+
+// ===========================================================================
+// I/O layer — thin, async, no caching.
+// ===========================================================================
+
+export { readHeader, readRecordBytes } from './io/read.js';
+export { buildRecordIndex, buildTimeline } from './record-index.js';
+
+// ===========================================================================
+// Convenience layer
+// ===========================================================================
+
+export { inspectEdf } from './inspect.js';
+export { openEdf, readAnnotations, readRecords, readWindow } from './recording.js';

package/src/inspect.ts

@@ -0,0 +1,181 @@
+/**
+ * Header-only triage that does not throw.
+ *
+ * Layer 6. This is the path that has to work when every other path has failed, which makes it the
+ * one place in edfcore where `try`/`catch` is the right tool rather than a way of losing
+ * information. Everywhere else a malformed file throws or records a diagnostic; here a malformed
+ * file becomes `ok: false` plus the diagnostic that would have been thrown, so a caller can
+ * triage a directory of unknown files without wrapping each call.
+ *
+ * Two boundaries keep that promise honest:
+ *
+ * - Only an `EdfError` is converted. Anything else is a bug in edfcore and is rethrown, because
+ *   swallowing it would turn "this file is broken" into a claim we cannot support.
+ * - The reads happen OUTSIDE the catch, so a source-level failure — a dead socket, a file that
+ *   vanished — still rejects. `inspectEdf` promises not to throw about CONTENT; it never promised
+ *   to hide I/O.
+ *
+ * At most 128 KiB is read, which is the full header of a file with up to 511 signals. A header
+ * larger than that is reported as such instead of being half-parsed.
+ */
+
+import { parseEdfInteger } from './bytes/numbers.js';
+import { readAsciiField } from './bytes/view.js';
+import { EDF_HEADER_BLOCK_BYTES, EDF_MAX_SIGNAL_COUNT, HEADER_FIELDS } from './constants.js';
+import { createDiagnostic, DiagnosticSink } from './diagnostics/collector.js';
+import { type EdfError, type EdfFormatError, isEdfError } from './errors.js';
+import { parseHeader } from './header/parse.js';
+import { detectVariant } from './header/variant.js';
+import { assertExactRead } from './io/source.js';
+import type { ByteSource, EdfDiagnostic, EdfInspection, EdfVariant, ReadOptions } from './types.js';
+
+/** 128 KiB is exactly `256 * 512`, i.e. the whole header of a 511-signal file. */
+const MAX_INSPECT_BYTES = 128 * 1024;
+
+/**
+ * A prefetch hint only: how many bytes the second read should ask for.
+ *
+ * Every judgement about this field belongs to `header/parse.ts`. Returning `undefined` here just
+ * means we hand `parseHeader` the 256 bytes we have and let it report the real problem.
+ */
+function signalCountHint(fixedHeader: Uint8Array): number | undefined {
+  if (fixedHeader.length < EDF_HEADER_BLOCK_BYTES) return undefined;
+  const { offset, length } = HEADER_FIELDS.signalCount;
+  const parse = parseEdfInteger(readAsciiField(fixedHeader, offset, length));
+  if (!parse.ok || parse.value < 1 || parse.value > EDF_MAX_SIGNAL_COUNT) return undefined;
+  return parse.value;
+}
+
+/**
+ * The family and dialect, when the header could not be parsed as a whole.
+ *
+ * The version block and the reserved field are the first 8 and 44 bytes of the fixed header and
+ * are readable long after everything else has stopped making sense, so a file whose signal count
+ * is garbage can still be reported as BDF rather than as nothing at all.
+ */
+function variantHint(headerBytes: Uint8Array): EdfVariant | undefined {
+  if (headerBytes.length < EDF_HEADER_BLOCK_BYTES) return undefined;
+  try {
+    return detectVariant(headerBytes, new DiagnosticSink()).variant;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The error, as the diagnostic it was carrying.
+ *
+ * `EdfFormatError` already holds the diagnostic it was built from, which keeps the byte offset,
+ * the raw bytes and the spec reference intact — reconstructing a diagnostic from the message
+ * would lose exactly the evidence triage needs.
+ */
+function diagnosticOf(error: EdfError): EdfDiagnostic {
+  // `edfErrorKind`, not `instanceof`: the latter is false across realms, and triage is exactly
+  // where a worker or an iframe boundary is most likely to be in play.
+  if (error.edfErrorKind === 'format') {
+    const formatError = error as EdfFormatError;
+    return (
+      formatError.diagnostic ??
+      createDiagnostic({ code: formatError.code, message: formatError.message })
+    );
+  }
+  return createDiagnostic({
+    // Not a format code: the header did not fail its grammar, some other rule refused it. The
+    // code union is open precisely so a case like this does not have to borrow a wrong name.
+    code: 'INSPECTION_FAILED',
+    message:
+      `the header could not be inspected: ${error.message} Next: this is not a statement about ` +
+      'the file grammar — read the message above, which names what was refused.',
+  });
+}
+
+function budgetDiagnostic(signalCount: number, headerByteLength: number): EdfDiagnostic {
+  return createDiagnostic({
+    code: 'HEADER_EXCEEDS_INSPECTION_BUDGET',
+    message:
+      `the header of a file declaring ${signalCount} signals is ${headerByteLength} bytes ` +
+      `(256 * (${signalCount} + 1)), above the ${MAX_INSPECT_BYTES}-byte ceiling inspectEdf() ` +
+      'reads, so it was not parsed. Rule: inspectEdf() is triage and is bounded by design. ' +
+      'Next: call readHeader(source) or openEdf(source), which read the whole header however ' +
+      'large it is.',
+    field: 'signalCount',
+    byteOffset: HEADER_FIELDS.signalCount.offset,
+    byteLength: HEADER_FIELDS.signalCount.length,
+    expected: `at most ${MAX_INSPECT_BYTES} header bytes`,
+    actual: `${headerByteLength} header bytes`,
+    specReference: 'EDF specification, header record bytes 252-255 (number of signals)',
+  });
+}
+
+/**
+ * Read at most 128 KiB and say what the file is.
+ *
+ * `ok` is true only when the header parsed AND carried no error-severity diagnostic — a signal
+ * whose scale edfcore refuses is an error even though the header itself is readable, because
+ * physical units are unavailable for it. Warnings leave `ok` true: the file is impolite, and what
+ * it reports is still true.
+ */
+export async function inspectEdf(
+  source: ByteSource,
+  options?: ReadOptions,
+): Promise<EdfInspection> {
+  const byteLength = source.byteLength;
+  const budget = Math.min(MAX_INSPECT_BYTES, byteLength);
+
+  const firstLength = Math.min(EDF_HEADER_BLOCK_BYTES, budget);
+  const fixedHeader = assertExactRead(await source.read(0, firstLength, options), 0, firstLength);
+  let bytesRead = firstLength;
+  let headerBytes = fixedHeader;
+  let overBudget: EdfDiagnostic | undefined;
+
+  const signalCount = signalCountHint(fixedHeader);
+  if (signalCount !== undefined) {
+    const headerByteLength = EDF_HEADER_BLOCK_BYTES * (signalCount + 1);
+    if (headerByteLength > MAX_INSPECT_BYTES) {
+      overBudget = budgetDiagnostic(signalCount, headerByteLength);
+    }
+    const wanted = Math.min(headerByteLength, budget);
+    const remaining = wanted - firstLength;
+    if (remaining > 0) {
+      const rest = assertExactRead(
+        await source.read(firstLength, remaining, options),
+        firstLength,
+        remaining,
+      );
+      bytesRead += remaining;
+      const combined = new Uint8Array(wanted);
+      combined.set(fixedHeader, 0);
+      combined.set(rest, firstLength);
+      headerBytes = combined;
+    }
+  }
+
+  try {
+    // Never strict: a triage call that threw on the first impolite field would be useless for
+    // exactly the files it exists to describe.
+    const header = parseHeader(headerBytes, byteLength);
+    const diagnostics =
+      overBudget === undefined ? header.diagnostics : [overBudget, ...header.diagnostics];
+    return {
+      ok: diagnostics.every((diagnostic) => diagnostic.severity !== 'error'),
+      variant: header.variant,
+      header,
+      byteLength,
+      bytesRead,
+      headerBytes,
+      diagnostics: Object.freeze(diagnostics),
+    };
+  } catch (error) {
+    if (!isEdfError(error)) throw error;
+    const failure = diagnosticOf(error);
+    return {
+      ok: false,
+      variant: variantHint(headerBytes),
+      header: undefined,
+      byteLength,
+      bytesRead,
+      headerBytes,
+      diagnostics: Object.freeze(overBudget === undefined ? [failure] : [overBudget, failure]),
+    };
+  }
+}

package/src/io/blob.ts

@@ -0,0 +1,31 @@
+/**
+ * The `Blob`/`File` adapter.
+ *
+ * Layer 5. The DOM `Blob` is never named: `BlobLike` is the structural shim from `types.ts`, so
+ * a real `File` from an `<input type="file">` remains assignable while `lib: ["DOM"]` stays out
+ * of the published `.d.ts`.
+ *
+ * A `Blob` read is the one place where the platform can legitimately hand back fewer bytes than
+ * asked (a `File` whose backing file changed on disk since the picker ran), so the exact-length
+ * contract is verified rather than assumed.
+ */
+
+import type { BlobLike, ByteSource, ReadOptions } from '../types.js';
+import { assertExactRead, assertReadRange, throwIfAborted } from './source.js';
+
+export function blobSource(blob: BlobLike): ByteSource {
+  const byteLength = blob.size;
+
+  return {
+    byteLength,
+    async read(offset: number, length: number, options?: ReadOptions): Promise<Uint8Array> {
+      throwIfAborted(options);
+      assertReadRange(offset, length, byteLength);
+      if (length === 0) return new Uint8Array(0);
+      // `Blob.slice` takes an EXCLUSIVE end, unlike an HTTP byte range.
+      const buffer = await blob.slice(offset, offset + length).arrayBuffer();
+      throwIfAborted(options);
+      return assertExactRead(new Uint8Array(buffer), offset, length);
+    },
+  };
+}

package/src/io/bytes.ts

@@ -0,0 +1,29 @@
+/**
+ * The in-memory adapter.
+ *
+ * Layer 5. Zero-copy by construction: a read hands back a `subarray` view over the caller's own
+ * buffer. That is safe precisely because it is the caller's buffer — the "returned array is
+ * owned by the caller" rule exists to stop an adapter handing out a view into state it retains,
+ * and this adapter retains nothing the caller does not already hold.
+ */
+
+import type { ByteSource, ReadOptions } from '../types.js';
+import { assertExactRead, assertReadRange, throwIfAborted } from './source.js';
+
+export function byteSource(bytes: ArrayBuffer | Uint8Array): ByteSource {
+  // `ArrayBuffer.isView` rather than `instanceof Uint8Array`: `instanceof` is false for a view
+  // that crossed a realm boundary (a worker, an iframe), and this is a public entry point.
+  const view: Uint8Array = ArrayBuffer.isView(bytes) ? bytes : new Uint8Array(bytes);
+  const byteLength = view.byteLength;
+
+  return {
+    byteLength,
+    async read(offset: number, length: number, options?: ReadOptions): Promise<Uint8Array> {
+      throwIfAborted(options);
+      assertReadRange(offset, length, byteLength);
+      // `subarray` is relative to this view, so a Uint8Array handed in with a non-zero
+      // byteOffset over a larger buffer is respected with no offset arithmetic here.
+      return assertExactRead(view.subarray(offset, offset + length), offset, length);
+    },
+  };
+}