edfcore 0.1.0

package/dist/record-index.js

@@ -0,0 +1,290 @@
+/**
+ * The record index: two probes at open, one targeted probe on demand, a full scan only if asked.
+ *
+ * Layer 6. This module owns the I/O STRATEGY for record onsets and nothing else — what a valid
+ * timeline is belongs to `time/timeline.ts`, what a timekeeping TAL is belongs to
+ * `tal/annotations.ts`, and segmentation belongs to `time/segments.ts`. Every onset that reaches
+ * those modules from here came out of `decodeAnnotations`, so the "first TAL of the first
+ * annotation signal" rule has exactly one implementation.
+ *
+ * Cost is the design constraint. Opening a million-record EDF+D over HTTP must not read the file,
+ * so:
+ *
+ * - a file with no annotation signal is probed ZERO times: without a timekeeping TAL there is no
+ *   per-record onset on disk, and record `r` starts at `r * recordDuration` by definition;
+ * - otherwise `buildTimeline` probes exactly two records, the first and the last, which detects
+ *   any NET drift of the timeline for two reads. It is not a proof of contiguity, and
+ *   `time/timeline.ts` says so in the diagnostic it emits;
+ * - `onsetTicks(r)` reads that ONE record and memoises the answer, so `locate()` costs
+ *   O(log recordCount) reads and a second `locate()` nearby costs almost none;
+ * - `buildRecordIndex()` is the only function here that touches every record, it is chunked so
+ *   memory stays bounded whatever the file size, and it is never called implicitly.
+ *
+ * A probe reads a whole data record rather than just the annotation signal's region. That is
+ * decision 7 of the design — the unit of I/O is the record range, never the channel range — and
+ * it is also what lets `decodeAnnotations` own the timekeeping rule: it requires the record's
+ * full bytes, and reading less would mean reimplementing that rule here.
+ */
+import { DEFAULT_MAX_MATERIALIZE_BYTES } from './constants.js';
+import { EdfRangeError } from './errors.js';
+import { readRecordBytes } from './io/read.js';
+import { decodeAnnotations } from './tal/annotations.js';
+import { secondsToTicks, ticksToSeconds } from './tal/ticks.js';
+import { buildSegmentation } from './time/segments.js';
+import { assertMonotonicOnsetArray, assertMonotonicOnsets, buildTimelineFromProbes, } from './time/timeline.js';
+/**
+ * How much a full scan is allowed to hold at once, independently of `maxMaterializeBytes`.
+ *
+ * The materialisation budget is a ceiling on what one call may allocate; this is the working set
+ * of a traversal that could otherwise read a 13 GB BDF into a single buffer just because the
+ * budget permitted it. A scan is sequential, so a bigger block buys nothing.
+ */
+const SCAN_BLOCK_TARGET_BYTES = 4 * 1024 * 1024;
+/** Records per chunk of a full traversal: bounded memory, and never fewer than one record. */
+export function scanChunkRecords(header, maxMaterializeBytes) {
+    const budget = Math.min(SCAN_BLOCK_TARGET_BYTES, maxMaterializeBytes ?? DEFAULT_MAX_MATERIALIZE_BYTES);
+    if (header.recordByteLength <= 0)
+        return 1;
+    return Math.max(1, Math.floor(budget / header.recordByteLength));
+}
+/**
+ * The onset a record has when the file carries no timekeeping TAL to read.
+ *
+ * Not a fallback for a missing TAL — `decodeAnnotations` owns that case and reports it — but the
+ * definition for a plain EDF or BDF file, where record onsets are not stored at all.
+ */
+function nominalOnsetTicks(header, recordIndex) {
+    return BigInt(recordIndex) * header.recordDurationTicks;
+}
+/** True when the file stores per-record onsets, i.e. when probing can learn anything. */
+function hasTimekeeping(header) {
+    return header.annotationSignalIndices.length > 0;
+}
+async function probeOnset(source, header, recordIndex, options) {
+    const records = { start: recordIndex, count: 1 };
+    const bytes = await readRecordBytes(source, header, records, options);
+    const decoded = decodeAnnotations(header, bytes, records, options);
+    // decodeAnnotations fills one entry per record in the range, always; the range is one record.
+    const ticks = decoded.recordOnsetTicks[0] ?? nominalOnsetTicks(header, recordIndex);
+    return { ticks, diagnostics: decoded.diagnostics };
+}
+/**
+ * The one `EdfRecordIndex` implementation.
+ *
+ * `locate` is written against `onsetOf` alone, so the probed index and the complete one share it:
+ * the first pays one read per probe and memoises, the second answers from an array it already
+ * has. The search is the same either way, and so is its behaviour at a gap.
+ */
+function createIndex(input) {
+    const { recordCount, recordDurationTicks, startOffsetTicks, onsetOf } = input;
+    function assertRecordIndex(recordIndex) {
+        if (Number.isSafeInteger(recordIndex) && recordIndex >= 0 && recordIndex < recordCount) {
+            return;
+        }
+        throw new EdfRangeError(`record ${recordIndex} is not one of the ${recordCount} data records this file contains, ` +
+            'so it has no onset to read. Next: pass an index in ' +
+            `0..${recordCount - 1}, or call locate(seconds) to find one for a time.`, { requested: { start: recordIndex, count: 1 }, available: { start: 0, count: recordCount } });
+    }
+    async function onsetTicks(recordIndex, options) {
+        assertRecordIndex(recordIndex);
+        return onsetOf(recordIndex, options);
+    }
+    /**
+     * The last record whose onset is at or before `targetTicks`, or `undefined` when every record
+     * starts after it.
+     *
+     * Binary search over a monotonic sequence, and monotonicity is verified at every pair the
+     * search actually observes: a violation makes every time-based answer for the file wrong, so
+     * `assertMonotonicOnsets` throws rather than letting the search return a plausible record.
+     */
+    async function findRecordAtOrBefore(targetTicks, options) {
+        let low = 0;
+        let lowTicks = await onsetOf(0, options);
+        if (targetTicks < lowTicks)
+            return undefined;
+        let high = recordCount - 1;
+        if (high === low)
+            return { recordIndex: low, onsetTicks: lowTicks };
+        let highTicks = await onsetOf(high, options);
+        assertMonotonicOnsets({ recordIndex: low, onsetTicks: lowTicks }, { recordIndex: high, onsetTicks: highTicks });
+        if (targetTicks >= highTicks)
+            return { recordIndex: high, onsetTicks: highTicks };
+        // Invariant: lowTicks <= target < highTicks, and low < high.
+        while (high - low > 1) {
+            const middle = low + Math.floor((high - low) / 2);
+            const middleTicks = await onsetOf(middle, options);
+            assertMonotonicOnsets({ recordIndex: low, onsetTicks: lowTicks }, { recordIndex: middle, onsetTicks: middleTicks });
+            assertMonotonicOnsets({ recordIndex: middle, onsetTicks: middleTicks }, { recordIndex: high, onsetTicks: highTicks });
+            if (middleTicks <= targetTicks) {
+                low = middle;
+                lowTicks = middleTicks;
+            }
+            else {
+                high = middle;
+                highTicks = middleTicks;
+            }
+        }
+        return { recordIndex: low, onsetTicks: lowTicks };
+    }
+    async function locate(seconds, options) {
+        if (recordCount <= 0)
+            return undefined;
+        // `seconds` is elapsed recording time; stored onsets are relative to the header start time.
+        const targetTicks = secondsToTicks(seconds) + startOffsetTicks;
+        const found = await findRecordAtOrBefore(targetTicks, options);
+        if (found === undefined)
+            return undefined;
+        const recordStartSeconds = ticksToSeconds(found.onsetTicks - startOffsetTicks);
+        if (recordDurationTicks === 0n) {
+            // Zero-duration records occupy no time, so only the instant itself is inside one. The last
+            // record sharing that instant is the one returned, which is what the search converges on.
+            if (targetTicks !== found.onsetTicks)
+                return undefined;
+            return {
+                recordIndex: found.recordIndex,
+                recordStartSeconds,
+                offsetInRecordSeconds: 0,
+            };
+        }
+        // Past the end of the record it follows: the time is in a gap, or after the recording.
+        if (targetTicks >= found.onsetTicks + recordDurationTicks)
+            return undefined;
+        return {
+            recordIndex: found.recordIndex,
+            recordStartSeconds,
+            offsetInRecordSeconds: ticksToSeconds(targetTicks - found.onsetTicks),
+        };
+    }
+    return {
+        coverage: input.coverage,
+        recordCount,
+        segments: input.segments,
+        gaps: input.gaps,
+        onsetTicks,
+        locate,
+    };
+}
+/**
+ * The timeline and a lazily probing index, for two reads at most.
+ *
+ * The probes are records 0 and `recordCount - 1` (one probe for a single-record file, none at all
+ * when the file has no annotation signal). Both are memoised into the index, so `onsetTicks(0)`
+ * and `onsetTicks(recordCount - 1)` are free after `openEdf`.
+ *
+ * `index.coverage` stays `'probed'` and `index.segments`/`index.gaps` stay `undefined` until
+ * `buildRecordIndex()` promotes them. Nothing on the returned object can be mistaken for a
+ * verified statement that the recording is continuous.
+ */
+export async function buildTimeline(source, header, options) {
+    const recordCount = header.recordCount;
+    const timekept = hasTimekeeping(header);
+    const strict = options?.strict === true;
+    const probeOptions = (readOptions) => readOptions === undefined ? { strict } : { ...readOptions, strict };
+    const memo = new Map();
+    const probes = [];
+    const probeDiagnostics = [];
+    const probeIndices = recordCount === 0 ? [] : recordCount === 1 ? [0] : [0, recordCount - 1];
+    for (const recordIndex of probeIndices) {
+        if (!timekept) {
+            const ticks = nominalOnsetTicks(header, recordIndex);
+            memo.set(recordIndex, ticks);
+            probes.push({ recordIndex, onsetTicks: ticks });
+            continue;
+        }
+        const probe = await probeOnset(source, header, recordIndex, probeOptions(options));
+        memo.set(recordIndex, probe.ticks);
+        probeDiagnostics.push(...probe.diagnostics);
+        probes.push({ recordIndex, onsetTicks: probe.ticks });
+    }
+    const timeline = buildTimelineFromProbes({ header, probes, probeDiagnostics }, options);
+    async function onsetOf(recordIndex, readOptions) {
+        const cached = memo.get(recordIndex);
+        if (cached !== undefined)
+            return cached;
+        if (!timekept) {
+            const ticks = nominalOnsetTicks(header, recordIndex);
+            memo.set(recordIndex, ticks);
+            return ticks;
+        }
+        const probe = await probeOnset(source, header, recordIndex, probeOptions(readOptions));
+        memo.set(recordIndex, probe.ticks);
+        return probe.ticks;
+    }
+    const index = createIndex({
+        coverage: 'probed',
+        recordCount,
+        recordDurationTicks: header.recordDurationTicks,
+        startOffsetTicks: timeline.startOffsetTicks,
+        segments: undefined,
+        gaps: undefined,
+        onsetOf,
+    });
+    return { timeline, index };
+}
+/**
+ * Every record's onset, read in bounded chunks.
+ *
+ * `onProgress` is called once per chunk with the number of records finished, so a caller can show
+ * a bar for the one operation in edfcore whose cost is proportional to the file.
+ *
+ * A file with no annotation signal is not scanned: its record onsets are arithmetic, so reading
+ * the data would answer a question the bytes do not contain. `onProgress` is still called once,
+ * with the traversal complete, so a caller's bar finishes.
+ */
+async function scanOnsets(recording, options) {
+    const { source, header } = recording;
+    const recordCount = header.recordCount;
+    const onsets = new BigInt64Array(recordCount);
+    if (!hasTimekeeping(header)) {
+        for (let recordIndex = 0; recordIndex < recordCount; recordIndex += 1) {
+            onsets[recordIndex] = nominalOnsetTicks(header, recordIndex);
+        }
+        options?.onProgress?.(recordCount, recordCount);
+        return onsets;
+    }
+    const chunkRecords = scanChunkRecords(header, options?.maxMaterializeBytes);
+    let scanned = 0;
+    while (scanned < recordCount) {
+        const records = {
+            start: scanned,
+            count: Math.min(chunkRecords, recordCount - scanned),
+        };
+        const bytes = await readRecordBytes(source, header, records, options);
+        const decoded = decodeAnnotations(header, bytes, records, options);
+        onsets.set(decoded.recordOnsetTicks, scanned);
+        scanned += records.count;
+        options?.onProgress?.(scanned, recordCount);
+    }
+    return onsets;
+}
+/**
+ * A `'complete'` index: every onset verified, with the segments and gaps they imply.
+ *
+ * This is one of only two functions that read the whole file, the other being `validateRecording`, and it is never called
+ * implicitly. Its diagnostics are deliberately not returned — an `EdfRecordIndex` is a
+ * structural answer, and `validateRecording()` is the call that reports on a traversal — but a
+ * non-monotonic timeline still throws, because no index over it would mean anything.
+ *
+ * `EdfRecording` is a plain struct, so the returned index is used by rebuilding one:
+ * `readWindow({ ...recording, index }, selection)`.
+ */
+export async function buildRecordIndex(recording, options) {
+    const { header, timeline } = recording;
+    const onsets = await scanOnsets(recording, options);
+    assertMonotonicOnsetArray(onsets);
+    const segmentation = buildSegmentation(onsets, header.recordDurationTicks, timeline.startOffsetTicks);
+    async function onsetOf(recordIndex) {
+        // Bounds were checked by `createIndex` before this is reached.
+        return onsets[recordIndex] ?? nominalOnsetTicks(header, recordIndex);
+    }
+    return createIndex({
+        coverage: 'complete',
+        recordCount: header.recordCount,
+        recordDurationTicks: header.recordDurationTicks,
+        startOffsetTicks: timeline.startOffsetTicks,
+        segments: segmentation.segments,
+        gaps: segmentation.gaps,
+        onsetOf,
+    });
+}
+//# sourceMappingURL=record-index.js.map

package/dist/record-index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"record-index.js","sourceRoot":"","sources":["../src/record-index.ts"],"names":[],"mappings":"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"}

package/dist/recording.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The convenience layer: composition over the primitives, and no behaviour of its own.
+ *
+ * Layer 6. Everything here is a few lines of arrangement around `io/read.ts`, `decode/` and
+ * `time/`. That is the point — a facade that made its own decisions would be a second place where
+ * the library's rules live, and the rules are what edfcore is.
+ *
+ * Three shapes are load-bearing:
+ *
+ * - `readRecords` returns exactly ONE chunk and costs exactly one read. The caller named the
+ *   records, so a gap inside them cannot surprise anyone.
+ * - `readWindow` ALWAYS returns an array, one chunk per contiguous run, including for a
+ *   continuous file where the array always has one element. If two shapes existed, consumers
+ *   would write against the easy one and misbehave on EDF+D. A window entirely inside a gap
+ *   returns `[]`, and nothing is ever filled in: there is no gap-fill and no gap-fill option.
+ * - Chunks stay RECORD-ALIGNED and are therefore usually wider than the window asked for. The
+ *   exact per-signal narrowing is `trimToWindow`, which is pure and testable without I/O.
+ *
+ * Every chunk carries the onsets of the records it contains, verified from the bytes that were
+ * already read — annotation regions live inside those bytes, so this costs no extra I/O and makes
+ * a sparsely indexed file safe for the data you actually received.
+ */
+import type { ByteSource, DecodeAnnotationsOptions, EdfAnnotationsResult, EdfChunk, EdfRecording, OpenOptions, ReadOptions, RecordRange, RecordSelection, WindowSelection } from './types.js';
+/**
+ * Open a recording: the header, then the timeline.
+ *
+ * Never scans the file. On a plain EDF or BDF this is two reads in total; on an EDF+ or BDF+ file
+ * it is two more, probing the first and last records for their timekeeping onsets.
+ */
+export declare function openEdf(source: ByteSource, options?: OpenOptions): Promise<EdfRecording>;
+/** Exactly one chunk and exactly one read: you named the records, so gaps cannot surprise you. */
+export declare function readRecords(recording: EdfRecording, selection: RecordSelection, options?: ReadOptions): Promise<EdfChunk>;
+/**
+ * A time window, as one chunk per contiguous run of records.
+ *
+ * Always an array. `[]` means the window is entirely inside a gap or entirely outside the
+ * recording — never that the read failed. Chunks are record-aligned and may be wider than asked
+ * for; `trimToWindow(header, chunkSignal, startSeconds, durationSeconds)` narrows them exactly.
+ *
+ * Runs are read one after another rather than concurrently, so the read pattern a caller observes
+ * is the one this function issued, in order, with no burst it did not ask for. Concurrency over a
+ * `ByteSource` belongs to the source — `httpSource` has `maxConcurrency` — not here.
+ *
+ * On a discontinuous file a probed index cannot map seconds to records; `resolveTimeWindow`
+ * refuses rather than guessing. Build a complete index and rebuild the recording around it:
+ * `const index = await buildRecordIndex(rec); await readWindow({ ...rec, index }, selection)`.
+ */
+export declare function readWindow(recording: EdfRecording, selection: WindowSelection, options?: ReadOptions): Promise<readonly EdfChunk[]>;
+/**
+ * The annotations in a record range, in one read.
+ *
+ * `records` is required and has no default. A full-file annotation scan is a legitimate thing to
+ * want and an expensive thing to do by accident, so it is always visible in the caller's source
+ * as `{ start: 0, count: recording.header.recordCount }`.
+ */
+export declare function readAnnotations(recording: EdfRecording, records: RecordRange, options?: DecodeAnnotationsOptions & ReadOptions): Promise<EdfAnnotationsResult>;
+//# sourceMappingURL=recording.d.ts.map

package/dist/recording.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording.d.ts","sourceRoot":"","sources":["../src/recording.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAUH,OAAO,KAAK,EACV,UAAU,EACV,wBAAwB,EACxB,oBAAoB,EACpB,QAAQ,EAKR,YAAY,EAEZ,WAAW,EACX,WAAW,EACX,WAAW,EACX,eAAe,EACf,eAAe,EAChB,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,wBAAsB,OAAO,CAAC,MAAM,EAAE,UAAU,EAAE,OAAO,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,YAAY,CAAC,CAI9F;AAqHD,kGAAkG;AAClG,wBAAsB,WAAW,CAC/B,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,eAAe,EAC1B,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,QAAQ,CAAC,CAEnB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,UAAU,CAC9B,SAAS,EAAE,YAAY,EACvB,SAAS,EAAE,eAAe,EAC1B,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,SAAS,QAAQ,EAAE,CAAC,CAa9B;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,SAAS,EAAE,YAAY,EACvB,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,wBAAwB,GAAG,WAAW,GAC/C,OAAO,CAAC,oBAAoB,CAAC,CAG/B"}

package/dist/recording.js

@@ -0,0 +1,178 @@
+/**
+ * The convenience layer: composition over the primitives, and no behaviour of its own.
+ *
+ * Layer 6. Everything here is a few lines of arrangement around `io/read.ts`, `decode/` and
+ * `time/`. That is the point — a facade that made its own decisions would be a second place where
+ * the library's rules live, and the rules are what edfcore is.
+ *
+ * Three shapes are load-bearing:
+ *
+ * - `readRecords` returns exactly ONE chunk and costs exactly one read. The caller named the
+ *   records, so a gap inside them cannot surprise anyone.
+ * - `readWindow` ALWAYS returns an array, one chunk per contiguous run, including for a
+ *   continuous file where the array always has one element. If two shapes existed, consumers
+ *   would write against the easy one and misbehave on EDF+D. A window entirely inside a gap
+ *   returns `[]`, and nothing is ever filled in: there is no gap-fill and no gap-fill option.
+ * - Chunks stay RECORD-ALIGNED and are therefore usually wider than the window asked for. The
+ *   exact per-signal narrowing is `trimToWindow`, which is pure and testable without I/O.
+ *
+ * Every chunk carries the onsets of the records it contains, verified from the bytes that were
+ * already read — annotation regions live inside those bytes, so this costs no extra I/O and makes
+ * a sparsely indexed file safe for the data you actually received.
+ */
+import { decodeDigitalCounted } from './decode/digital.js';
+import { EdfChannelNotFoundError } from './errors.js';
+import { readHeader, readRecordBytes } from './io/read.js';
+import { buildTimeline } from './record-index.js';
+import { decodeAnnotations } from './tal/annotations.js';
+import { ticksToSeconds } from './tal/ticks.js';
+import { assertMonotonicOnsetArray } from './time/timeline.js';
+import { resolveTimeWindow } from './time/window.js';
+/**
+ * Open a recording: the header, then the timeline.
+ *
+ * Never scans the file. On a plain EDF or BDF this is two reads in total; on an EDF+ or BDF+ file
+ * it is two more, probing the first and last records for their timekeeping onsets.
+ */
+export async function openEdf(source, options) {
+    const header = await readHeader(source, options);
+    const { timeline, index } = await buildTimeline(source, header, options);
+    return { source, header, timeline, index };
+}
+/**
+ * The signals to decode, deduplicated and in the order given.
+ *
+ * An annotation signal is refused with a plain `RangeError` rather than an `EdfError`: its bytes
+ * are TAL text, and decoding them as samples produces numbers that look exactly like a signal.
+ * That is the failure this library exists to prevent, and it can only ever be a caller's mistake.
+ */
+function resolveSignals(header, signalIndices) {
+    const seen = new Set();
+    const signals = [];
+    for (const signalIndex of signalIndices) {
+        if (seen.has(signalIndex))
+            continue;
+        seen.add(signalIndex);
+        const signal = header.signals[signalIndex];
+        if (signal === undefined) {
+            throw new EdfChannelNotFoundError(`signalIndex ${signalIndex} is outside the ${header.signals.length} signals this file ` +
+                'declares. Next: pass an index from header.dataSignalIndices, or resolve one with ' +
+                'getSignal(header, label).', { selector: signalIndex, availableLabels: header.signals.map((s) => s.label) });
+        }
+        if (signal.kind === 'annotations') {
+            throw new RangeError(`signal ${signalIndex} (${JSON.stringify(signal.label)}) is this file's annotations ` +
+                'channel: its bytes are TAL text, not samples, so decoding them as samples would ' +
+                'produce numbers that look like a signal. Next: call readAnnotations(recording, ' +
+                'records) for it, and pass only header.dataSignalIndices here.');
+        }
+        signals.push(signal);
+    }
+    return signals;
+}
+/**
+ * The gap immediately before `recordStart`, when the index knows where the gaps are.
+ *
+ * `undefined` for a probed index, and that is not a claim that there is no gap — it is the honest
+ * answer that nobody has read the onsets in between. `buildRecordIndex()` is what turns the
+ * question into an answerable one.
+ */
+function gapBefore(index, recordStart) {
+    const { segments, gaps } = index;
+    if (segments === undefined || gaps === undefined)
+        return undefined;
+    for (const gap of gaps) {
+        const after = segments[gap.afterSegmentIndex];
+        if (after !== undefined && after.records.start === recordStart)
+            return gap;
+    }
+    return undefined;
+}
+/**
+ * One record range in, one chunk out, one read.
+ *
+ * The annotation regions of these records are already inside the bytes that were read, so their
+ * onsets are decoded and checked for free. That is what makes `chunk.startSeconds` the record's
+ * TRUE start on an EDF+D file rather than a nominal `start * recordDuration` that a gap would
+ * have invalidated.
+ */
+async function readChunk(recording, records, signalIndices, options) {
+    const { source, header, timeline, index } = recording;
+    const signals = resolveSignals(header, signalIndices);
+    const bytes = await readRecordBytes(source, header, records, options);
+    const byteOffset = header.headerByteLength + records.start * header.recordByteLength;
+    // Never strict, and not because the flag was lost: a read that threw on an impolite TAL in a
+    // record the caller asked for would return no samples at all over a defect in a different
+    // channel. The defects land on `chunk.diagnostics`, next to the data they were found beside.
+    const annotations = decodeAnnotations(header, bytes, records);
+    const onsets = annotations.recordOnsetTicks;
+    assertMonotonicOnsetArray(onsets, records.start);
+    const durationTicks = header.recordDurationTicks;
+    const nominalFirstTicks = timeline.startOffsetTicks + BigInt(records.start) * durationTicks;
+    const firstOnsetTicks = onsets[0] ?? nominalFirstTicks;
+    const lastOnsetTicks = records.count > 0 ? (onsets[records.count - 1] ?? firstOnsetTicks) : firstOnsetTicks;
+    const startTicks = firstOnsetTicks - timeline.startOffsetTicks;
+    // The SPAN of the chunk, not the time it covers: they are equal for one contiguous run, which
+    // is what readWindow produces, and they differ when a caller names records across a gap.
+    const spanTicks = records.count > 0 ? lastOnsetTicks + durationTicks - firstOnsetTicks : 0n;
+    const startSeconds = ticksToSeconds(startTicks);
+    const chunkSignals = signals.map((signal) => {
+        const decoded = decodeDigitalCounted(header, bytes, records, signal.index, undefined, options);
+        return {
+            signalIndex: signal.index,
+            sampleCount: decoded.digital.length,
+            digital: decoded.digital,
+            firstSampleIndex: records.start * signal.samplesPerRecord,
+            startSeconds,
+            outOfDigitalRangeCount: decoded.outOfDigitalRangeCount,
+        };
+    });
+    return {
+        records,
+        startSeconds,
+        durationSeconds: ticksToSeconds(spanTicks),
+        byteOffset,
+        byteLength: bytes.length,
+        signals: Object.freeze(chunkSignals),
+        precededByGap: gapBefore(index, records.start),
+        diagnostics: annotations.diagnostics,
+    };
+}
+/** Exactly one chunk and exactly one read: you named the records, so gaps cannot surprise you. */
+export async function readRecords(recording, selection, options) {
+    return readChunk(recording, selection.records, selection.signalIndices, options);
+}
+/**
+ * A time window, as one chunk per contiguous run of records.
+ *
+ * Always an array. `[]` means the window is entirely inside a gap or entirely outside the
+ * recording — never that the read failed. Chunks are record-aligned and may be wider than asked
+ * for; `trimToWindow(header, chunkSignal, startSeconds, durationSeconds)` narrows them exactly.
+ *
+ * Runs are read one after another rather than concurrently, so the read pattern a caller observes
+ * is the one this function issued, in order, with no burst it did not ask for. Concurrency over a
+ * `ByteSource` belongs to the source — `httpSource` has `maxConcurrency` — not here.
+ *
+ * On a discontinuous file a probed index cannot map seconds to records; `resolveTimeWindow`
+ * refuses rather than guessing. Build a complete index and rebuild the recording around it:
+ * `const index = await buildRecordIndex(rec); await readWindow({ ...rec, index }, selection)`.
+ */
+export async function readWindow(recording, selection, options) {
+    const ranges = resolveTimeWindow(recording.timeline, recording.index, selection.startSeconds, selection.durationSeconds);
+    const chunks = [];
+    for (const records of ranges) {
+        chunks.push(await readChunk(recording, records, selection.signalIndices, options));
+    }
+    return Object.freeze(chunks);
+}
+/**
+ * The annotations in a record range, in one read.
+ *
+ * `records` is required and has no default. A full-file annotation scan is a legitimate thing to
+ * want and an expensive thing to do by accident, so it is always visible in the caller's source
+ * as `{ start: 0, count: recording.header.recordCount }`.
+ */
+export async function readAnnotations(recording, records, options) {
+    const bytes = await readRecordBytes(recording.source, recording.header, records, options);
+    return decodeAnnotations(recording.header, bytes, records, options);
+}
+//# sourceMappingURL=recording.js.map

package/dist/recording.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"recording.js","sourceRoot":"","sources":["../src/recording.ts"],"names":[],"mappings":"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"}

package/dist/tal/annotations.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `decodeAnnotations`: TALs plus EDF+ semantics.
+ *
+ * Layer 3. Sole owner of timekeeping extraction and of the annotation sort. The byte grammar
+ * lives in `grammar.ts`; everything here is about which TAL means what.
+ *
+ * Three rules the rest of the library depends on:
+ *
+ * 1. The FIRST TAL of the FIRST annotation signal of the file is that record's timekeeping TAL.
+ *    "First" is a position, not "the first one that parsed", and "first annotation signal" is
+ *    `header.annotationSignalIndices[0]` — not the first signal this call was asked for. An
+ *    additional annotation signal carries NO timekeeping TAL, and stripping its first TAL would
+ *    silently delete a real event.
+ * 2. `recordOnsetTicks` has one entry for EVERY record in the decoded range, always. A record
+ *    whose timekeeping TAL is missing gets the derived onset `start + recordIndex * duration`
+ *    rather than a hole or a sentinel, and `TIMEKEEPING_TAL_MISSING` carries the record index so
+ *    the derivation is never invisible. Every timeline in edfcore is built from this array.
+ * 3. Onsets are exposed under both conventions as separately named fields, never as an option:
+ *    `onsetSecondsFromHeaderStart` is the verbatim on-disk value and
+ *    `onsetSecondsFromFirstRecord` is rebased to record 0's true start. `onsetTicks` is exact
+ *    and is the only one worth comparing.
+ *
+ * Diagnostic volume is bounded on purpose, by one test: does another occurrence of this code
+ * carry information available nowhere else? `TIMEKEEPING_TAL_MISSING` does — it names a record
+ * whose onset was derived — so it is reported per record. `NEGATIVE_ANNOTATION_ONSET` and
+ * `TIMEKEEPING_TAL_NONCONFORMANT` do not: the onsets are in the result and the shorthand is a
+ * property of the writer, so they are reported once per call. The grammar's own defects are
+ * deduplicated per region and carry an occurrence count.
+ *
+ * Record-onset spacing and monotonicity are deliberately NOT checked here. This module produces
+ * `recordOnsetTicks`; `time/timeline.ts` owns enforcing what a valid timeline is, and splitting
+ * that would give one rule two owners.
+ */
+import type { DecodeAnnotationsOptions, EdfAnnotationsResult, EdfHeader, RecordRange } from '../types.js';
+export declare function decodeAnnotations(header: EdfHeader, recordBytes: Uint8Array, records: RecordRange, options?: DecodeAnnotationsOptions): EdfAnnotationsResult;
+//# sourceMappingURL=annotations.d.ts.map

package/dist/tal/annotations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotations.d.ts","sourceRoot":"","sources":["../../src/tal/annotations.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AAMH,OAAO,KAAK,EACV,wBAAwB,EAExB,oBAAoB,EACpB,SAAS,EAET,WAAW,EACZ,MAAM,aAAa,CAAC;AAmTrB,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,UAAU,EACvB,OAAO,EAAE,WAAW,EACpB,OAAO,CAAC,EAAE,wBAAwB,GACjC,oBAAoB,CAsItB"}