edfcore 0.1.0

package/dist/decode/physical.js

@@ -0,0 +1,178 @@
+/**
+ * Digital counts to physical units.
+ *
+ * Layer 3. Sole owner of the scaling expression. The expression is PINNED — see `toPhysical`
+ * before changing anything in this file.
+ *
+ * Also home to `clampToDigitalRange`, which is a cross-validation tool and never part of a
+ * read: EDFlib clamps silently when it loads samples, edfcore does not, and reproducing that
+ * behaviour has to be something a caller asks for explicitly.
+ */
+import { DEFAULT_MAX_MATERIALIZE_BYTES } from '../constants.js';
+import { EdfBudgetError, EdfScalingError } from '../errors.js';
+const BYTES_PER_FLOAT64 = 8;
+const BYTES_PER_INT32 = 4;
+/** The physical dimension that marks a log-compressed channel (EDFlib `edffloat.html`). */
+const LOG_TRANSFORMED_DIMENSION = 'Filtered';
+function assertWithinBudget(requiredBytes, what, options) {
+    const budgetBytes = options?.maxMaterializeBytes ?? DEFAULT_MAX_MATERIALIZE_BYTES;
+    if (requiredBytes <= budgetBytes)
+        return;
+    throw new EdfBudgetError(`Producing ${what} needs a ${requiredBytes}-byte array, above the ${budgetBytes}-byte ` +
+        'maxMaterializeBytes budget, so the allocation was refused before it was attempted. ' +
+        'Next: convert fewer samples per call, reuse an `out` array, or raise ' +
+        'options.maxMaterializeBytes.', { requiredBytes, budgetBytes });
+}
+/**
+ * Why `signal.scale` is `undefined`, re-derived from the signal itself.
+ *
+ * The header records the matching diagnostic at parse time, but a bare `EdfSignal` does not
+ * carry it, and `toPhysical` takes a signal. These four tests are the same ones `header/scale.ts`
+ * applies, IN THE SAME ORDER — a signal can fail two of them at once, and the order is what
+ * decides which cause is named, so the code reported here is the code the header reported.
+ * `buildScale` owns that order; this function follows it. A signal that fails none
+ * of them yet still has no scale gets `SCALE_UNAVAILABLE` rather than the nearest-looking code:
+ * naming the wrong cause is worse than admitting the cause is not on hand.
+ */
+function describeScalingFailure(signal) {
+    const digitalSpec = 'EDF+ additional specification 5: "Digital maximum must be larger than Digital minimum"';
+    if (signal.digitalMinimum === signal.digitalMaximum) {
+        return {
+            code: 'DEGENERATE_DIGITAL_RANGE',
+            reason: `declares digitalMinimum == digitalMaximum == ${signal.digitalMinimum}, which makes ` +
+                'the gain a division by zero',
+            specReference: digitalSpec,
+        };
+    }
+    if (signal.physicalMinimum === signal.physicalMaximum) {
+        return {
+            code: 'DEGENERATE_PHYSICAL_RANGE',
+            reason: `declares physicalMinimum == physicalMaximum == ${signal.physicalMinimum}, so every ` +
+                'sample would map to that one value',
+            specReference: undefined,
+        };
+    }
+    if (signal.digitalMinimum > signal.digitalMaximum) {
+        return {
+            code: 'INVERTED_DIGITAL_RANGE',
+            reason: `declares digitalMinimum ${signal.digitalMinimum} above digitalMaximum ` +
+                `${signal.digitalMaximum}, and edfcore will not guess which one the writer meant`,
+            specReference: digitalSpec,
+        };
+    }
+    if (signal.physicalDimension.trim() === LOG_TRANSFORMED_DIMENSION) {
+        return {
+            code: 'LOG_TRANSFORMED_CHANNEL',
+            reason: `has physical dimension "${LOG_TRANSFORMED_DIMENSION}", so its values are ` +
+                'log-compressed and the linear formula would be wrong by orders of magnitude',
+            specReference: 'EDFlib edffloat.html',
+        };
+    }
+    return {
+        code: 'SCALE_UNAVAILABLE',
+        reason: 'has no usable scale, and the header recorded the reason rather than the signal',
+        specReference: undefined,
+    };
+}
+function scalingError(signal) {
+    const failure = describeScalingFailure(signal);
+    const message = `[${failure.code}] signal ${signal.index} "${signal.label}" ${failure.reason}, so ` +
+        'physical units are undefined for it. Raw fields: digital minimum ' +
+        `"${signal.raw.digitalMinimum}", digital maximum "${signal.raw.digitalMaximum}", ` +
+        `physical minimum "${signal.raw.physicalMinimum}", physical maximum ` +
+        `"${signal.raw.physicalMaximum}", physical dimension "${signal.raw.physicalDimension}". ` +
+        (failure.specReference === undefined ? '' : `${failure.specReference}. `) +
+        'Next: decodeDigital() still works on this signal; edfcore will not invent a gain.';
+    return new EdfScalingError(message, {
+        code: failure.code,
+        signalIndex: signal.index,
+        label: signal.label,
+    });
+}
+/**
+ * Float64 by contract, never Float32.
+ *
+ * Float32 carries 24 significand bits, so a 24-bit BDF sample scaled into it loses about a
+ * quarter of a quantisation step — a rounding error a quarter the size of the smallest real
+ * difference the hardware can express.
+ */
+function resolveFloat64Out(out, length, options) {
+    if (out === undefined) {
+        assertWithinBudget(length * BYTES_PER_FLOAT64, `${length} physical samples`, options);
+        return new Float64Array(length);
+    }
+    if (out.length < length) {
+        throw new RangeError(`out holds ${out.length} samples but this conversion produces ${length}. Next: size the ` +
+            'reused array to digital.length, or omit it and let toPhysical allocate.');
+    }
+    // A longer `out` is narrowed to a view over its own memory, so reuse still allocates no
+    // samples while `result.length` stays equal to the real sample count.
+    return out.length === length ? out : out.subarray(0, length);
+}
+function resolveInt32Out(out, length, options) {
+    if (out === undefined) {
+        assertWithinBudget(length * BYTES_PER_INT32, `${length} clamped samples`, options);
+        return new Int32Array(length);
+    }
+    if (out.length < length) {
+        throw new RangeError(`out holds ${out.length} samples but this clamp produces ${length}. Next: size the ` +
+            'reused array to digital.length, or omit it and let clampToDigitalRange allocate.');
+    }
+    return out.length === length ? out : out.subarray(0, length);
+}
+/**
+ * `physical = bitValue * (offset + digital)`, in float64 throughout.
+ *
+ * THIS EXPRESSION IS PINNED AND MUST NOT BE "SIMPLIFIED". It is numerically worse than
+ * `physicalMinimum + (digital - digitalMinimum) * gain`, and that is not an accident: it is
+ * EDFlib's exact form, kept verbatim so edfcore reproduces pyEDFlib/EDFlib float64 output
+ * bit for bit. The two forms disagree by up to ~9.3e-10 LSB — ten orders of magnitude below
+ * the quantisation floor, and on asymmetric ranges they differ on nearly half the samples by
+ * one ULP. Rewriting this line breaks the golden-value tests, and rightly so.
+ *
+ * Throws `EdfScalingError` when `signal.scale` is `undefined`. edfcore never fabricates a gain,
+ * and `decodeDigital` keeps working on such a signal.
+ */
+export function toPhysical(signal, digital, out, options) {
+    const scale = signal.scale;
+    if (scale === undefined)
+        throw scalingError(signal);
+    const length = digital.length;
+    const physical = resolveFloat64Out(out, length, options);
+    const bitValue = scale.bitValue;
+    const offset = scale.offset;
+    for (let i = 0; i < length; i++) {
+        // biome-ignore lint/style/noNonNullAssertion: i < digital.length, per the ArrayLike contract.
+        physical[i] = bitValue * (offset + digital[i]);
+    }
+    return physical;
+}
+/**
+ * Clamp to the declared digital range. POST-HOC ONLY — nothing on the read path calls this.
+ *
+ * It exists to reproduce a clamping consumer (EDFlib clamps silently on read; edfcore does not)
+ * when cross-validating against one. Clamping to `[min(digMin, digMax), max(digMin, digMax)]`
+ * rather than to `[digMin, digMax]` matters for an inverted declaration, where the naive bounds
+ * are empty and collapse every sample onto a single value.
+ */
+export function clampToDigitalRange(signal, digital, out, options) {
+    const low = Math.min(signal.digitalMinimum, signal.digitalMaximum);
+    const high = Math.max(signal.digitalMinimum, signal.digitalMaximum);
+    if (!Number.isFinite(low) || !Number.isFinite(high)) {
+        // Every comparison against a NaN bound is false, so proceeding would return the input
+        // unchanged while claiming to have clamped it.
+        throw new RangeError(`signal ${signal.index} "${signal.label}" declares digital minimum ` +
+            `"${signal.raw.digitalMinimum}" and digital maximum "${signal.raw.digitalMaximum}", ` +
+            'which do not both parse as numbers, so there is no range to clamp to. Next: read ' +
+            'header.diagnostics for this signal.');
+    }
+    const length = digital.length;
+    const clamped = resolveInt32Out(out, length, options);
+    for (let i = 0; i < length; i++) {
+        // biome-ignore lint/style/noNonNullAssertion: i < digital.length.
+        const value = digital[i];
+        clamped[i] = value < low ? low : value > high ? high : value;
+    }
+    return clamped;
+}
+//# sourceMappingURL=physical.js.map

package/dist/decode/physical.js.map

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

package/dist/diagnostics/codes.d.ts

@@ -0,0 +1,38 @@
+/**
+ * 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 = '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' | 'DEGENERATE_DIGITAL_RANGE' | 'DEGENERATE_PHYSICAL_RANGE' | 'INVERTED_DIGITAL_RANGE' | 'LOG_TRANSFORMED_CHANNEL' | 'SCALE_UNAVAILABLE' | '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' | 'DATE_CLIPPED_TO_1985_2084' | 'INVERTED_PHYSICAL_RANGE' | 'NEGATIVE_ANNOTATION_ONSET';
+/**
+ * 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 declare const DIAGNOSTIC_DISPOSITIONS: Readonly<Record<EdfKnownDiagnosticCode, EdfDiagnosticDisposition>>;
+/** Unknown codes are treated as warnings — an unrecognised note must never escalate. */
+export declare function dispositionOf(code: EdfDiagnosticCode): EdfDiagnosticDisposition;
+export declare function severityOf(code: EdfDiagnosticCode): EdfSeverity;
+/** Fires regardless of `strict`: proceeding would require inventing data. */
+export declare function isAlwaysFatal(code: EdfDiagnosticCode): boolean;
+//# sourceMappingURL=codes.d.ts.map

package/dist/diagnostics/codes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"codes.d.ts","sourceRoot":"","sources":["../../src/diagnostics/codes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,MAAM,MAAM,WAAW,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEvD,gEAAgE;AAChE,MAAM,MAAM,wBAAwB,GAAG,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,CAAC;AAEjF;;;;;;GAMG;AACH,MAAM,MAAM,sBAAsB,GAE9B,iBAAiB,GACjB,kBAAkB,GAClB,sBAAsB,GACtB,uBAAuB,GACvB,yBAAyB,GACzB,kBAAkB,GAClB,mCAAmC,GACnC,wBAAwB,GAExB,0BAA0B,GAC1B,2BAA2B,GAC3B,wBAAwB,GACxB,yBAAyB,GACzB,mBAAmB,GAEnB,sBAAsB,GACtB,wBAAwB,GACxB,gBAAgB,GAChB,sBAAsB,GACtB,gBAAgB,GAChB,+BAA+B,GAC/B,4BAA4B,GAC5B,wBAAwB,GACxB,kCAAkC,GAClC,sBAAsB,GACtB,kBAAkB,GAClB,0BAA0B,GAC1B,4BAA4B,GAC5B,wBAAwB,GACxB,8BAA8B,GAC9B,yBAAyB,GACzB,sBAAsB,GACtB,wCAAwC,GACxC,wBAAwB,GACxB,yBAAyB,GACzB,+BAA+B,GAC/B,2BAA2B,GAC3B,eAAe,GACf,6BAA6B,GAC7B,+BAA+B,GAC/B,0BAA0B,GAC1B,gCAAgC,GAChC,kCAAkC,GAElC,2BAA2B,GAC3B,yBAAyB,GACzB,2BAA2B,CAAC;AA2GhC;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,sBAAsB,GAAG,CAAC,MAAM,GAAG,EAAE,CAAC,CAAC;AAEvE,eAAO,MAAM,uBAAuB,EAAE,QAAQ,CAC5C,MAAM,CAAC,sBAAsB,EAAE,wBAAwB,CAAC,CAC1C,CAAC;AAEjB,wFAAwF;AACxF,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,wBAAwB,CAE/E;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,WAAW,CAK/D;AAED,6EAA6E;AAC7E,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO,CAE9D"}

package/dist/diagnostics/codes.js

@@ -0,0 +1,134 @@
+/**
+ * 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.
+ */
+const DISPOSITIONS = {
+    // ---- 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',
+};
+export const DIAGNOSTIC_DISPOSITIONS = DISPOSITIONS;
+/** Unknown codes are treated as warnings — an unrecognised note must never escalate. */
+export function dispositionOf(code) {
+    return DISPOSITIONS[code] ?? 'warning';
+}
+export function severityOf(code) {
+    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) {
+    return dispositionOf(code) === 'fatal';
+}
+//# sourceMappingURL=codes.js.map

package/dist/diagnostics/codes.js.map

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

package/dist/diagnostics/collector.d.ts

@@ -0,0 +1,76 @@
+/**
+ * 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 } from '../errors.js';
+import type { EdfDiagnostic, ParseOptions } from '../types.js';
+import { type EdfDiagnosticCode } 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 declare function createDiagnostic(init: DiagnosticInit): EdfDiagnostic;
+/**
+ * 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 declare function toFormatError(diagnostic: EdfDiagnostic, cause?: unknown): EdfFormatError;
+/**
+ * `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 declare function fatalError(init: DiagnosticInit, cause?: unknown): EdfFormatError;
+export declare class DiagnosticSink {
+    #private;
+    /**
+     * 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;
+    constructor(options?: ParseOptions);
+    get size(): number;
+    /**
+     * 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;
+    /** A frozen copy: an array already attached to a result must not grow if reporting continues. */
+    get diagnostics(): readonly EdfDiagnostic[];
+    /** `diagnostics`, then reset — for a sink reused across records. */
+    drain(): readonly EdfDiagnostic[];
+}
+//# sourceMappingURL=collector.d.ts.map

package/dist/diagnostics/collector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.d.ts","sourceRoot":"","sources":["../../src/diagnostics/collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAA2B,MAAM,cAAc,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,KAAK,iBAAiB,EAA6B,MAAM,YAAY,CAAC;AAE/E;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,4FAA4F;IAC5F,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,QAAQ,CAAC,EAAE,UAAU,CAAC;IAC/B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG,aAAa,CAkBpE;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,UAAU,EAAE,aAAa,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,cAAc,CAMxF;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,cAAc,CAEhF;AAED,qBAAa,cAAc;;IACzB;;;OAGG;IACH,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;gBAIb,OAAO,CAAC,EAAE,YAAY;IAIlC,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAI,EAAE,cAAc,GAAG,IAAI;IAQlC,iGAAiG;IACjG,IAAI,WAAW,IAAI,SAAS,aAAa,EAAE,CAE1C;IAED,oEAAoE;IACpE,KAAK,IAAI,SAAS,aAAa,EAAE;CAKlC"}

package/dist/diagnostics/collector.js

@@ -0,0 +1,95 @@
+/**
+ * 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 } from '../errors.js';
+import { isAlwaysFatal, severityOf } from './codes.js';
+export function createDiagnostic(init) {
+    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, cause) {
+    const init = 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, cause) {
+    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`.
+     */
+    strict;
+    #collected = [];
+    constructor(options) {
+        this.strict = options?.strict === true;
+    }
+    get size() {
+        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) {
+        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() {
+        return Object.freeze(this.#collected.slice());
+    }
+    /** `diagnostics`, then reset — for a sink reused across records. */
+    drain() {
+        const collected = this.diagnostics;
+        this.#collected = [];
+        return collected;
+    }
+}
+//# sourceMappingURL=collector.js.map

package/dist/diagnostics/collector.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collector.js","sourceRoot":"","sources":["../../src/diagnostics/collector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,cAAc,EAA2B,MAAM,cAAc,CAAC;AAEvE,OAAO,EAA0B,aAAa,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC;AAwB/E,MAAM,UAAU,gBAAgB,CAAC,IAAoB;IACnD,OAAO;QACL,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,QAAQ,EAAE,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC;QAC/B,OAAO,EAAE,IAAI,CAAC,OAAO;QACrB,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,UAAU,EAAE,IAAI,CAAC,UAAU;QAC3B,yFAAyF;QACzF,4EAA4E;QAC5E,QAAQ,EAAE,IAAI,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,QAAQ,CAAC,KAAK,EAAE;QACzE,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,QAAQ,EAAE,IAAI,CAAC,QAAQ;QACvB,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,aAAa,EAAE,IAAI,CAAC,aAAa;KAClC,CAAC;AACJ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,UAAyB,EAAE,KAAe;IACtE,MAAM,IAAI,GACR,KAAK,KAAK,SAAS;QACjB,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE;QACvC,CAAC,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,IAAI,EAAE,UAAU,EAAE,KAAK,EAAE,CAAC;IACnD,OAAO,IAAI,cAAc,CAAC,IAAI,UAAU,CAAC,IAAI,KAAK,UAAU,CAAC,OAAO,EAAE,EAAE,IAAI,CAAC,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,IAAoB,EAAE,KAAe;IAC9D,OAAO,aAAa,CAAC,gBAAgB,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC;AACtD,CAAC;AAED,MAAM,OAAO,cAAc;IACzB;;;OAGG;IACM,MAAM,CAAU;IAEzB,UAAU,GAAoB,EAAE,CAAC;IAEjC,YAAY,OAAsB;QAChC,IAAI,CAAC,MAAM,GAAG,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IACzC,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,UAAU,CAAC,MAAM,CAAC;IAChC,CAAC;IAED;;;;;;;;;OASG;IACH,MAAM,CAAC,IAAoB;QACzB,MAAM,UAAU,GAAG,gBAAgB,CAAC,IAAI,CAAC,CAAC;QAC1C,IAAI,aAAa,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,IAAI,UAAU,CAAC,QAAQ,KAAK,MAAM,CAAC,EAAE,CAAC;YACtF,MAAM,aAAa,CAAC,UAAU,CAAC,CAAC;QAClC,CAAC;QACD,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,UAAU,CAAC,CAAC;IACnC,CAAC;IAED,iGAAiG;IACjG,IAAI,WAAW;QACb,OAAO,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,UAAU,CAAC,KAAK,EAAE,CAAC,CAAC;IAChD,CAAC;IAED,oEAAoE;IACpE,KAAK;QACH,MAAM,SAAS,GAAG,IAAI,CAAC,WAAW,CAAC;QACnC,IAAI,CAAC,UAAU,GAAG,EAAE,CAAC;QACrB,OAAO,SAAS,CAAC;IACnB,CAAC;CACF"}

package/dist/diagnostics/format.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 } from '../types.js';
+export interface FormatDiagnosticsOptions {
+    readonly color?: boolean;
+    readonly maxItems?: number;
+}
+/**
+ * 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 declare function formatDiagnostics(diagnostics: readonly EdfDiagnostic[], options?: FormatDiagnosticsOptions): string;
+//# sourceMappingURL=format.d.ts.map

package/dist/diagnostics/format.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"format.d.ts","sourceRoot":"","sources":["../../src/diagnostics/format.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,aAAa,CAAC;AAE9D,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAgBD;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,WAAW,EAAE,SAAS,aAAa,EAAE,EACrC,OAAO,CAAC,EAAE,wBAAwB,GACjC,MAAM,CAgBR"}