edfcore 0.1.0

package/dist/tal/grammar.js

@@ -0,0 +1,324 @@
+/**
+ * The byte-level TAL state machine.
+ *
+ * Layer 3. Sole owner of turning ONE annotation region into time-stamped annotation lists.
+ * `annotations.ts` adds provenance and EDF+ semantics on top; nothing here knows about records,
+ * signals, or timekeeping.
+ *
+ * Two rules define the module, and both are where other EDF readers go wrong:
+ *
+ * 1. Parsing is HARD-BOUNDED to `[regionStart, regionStart + regionBytes)`. A TAL with no
+ *    terminating 0x00 inside the region is discarded, never continued past the bound — the bytes
+ *    after it are the next signal's samples, and parsing those is how a reader invents
+ *    annotations that are not in the file.
+ * 2. The region is split on the STRUCTURAL bytes (0x00, 0x14, 0x15) FIRST and each text run is
+ *    decoded as UTF-8 LAST. That order is safe in exactly one direction: every byte of a
+ *    multi-byte UTF-8 sequence is >= 0x80 and can never collide with a structural byte, while a
+ *    string that has already been decoded can no longer be split on bytes at all.
+ *
+ * `src/tal/` is the only part of edfcore allowed to use `TextDecoder`, and only for annotation
+ * text. Header bytes go through `decodeHeaderLatin1`, for the cross-runtime reason documented in
+ * `src/bytes/latin1.ts`.
+ *
+ * Each defect is reported at most once per region, with an occurrence count: a corrupt region
+ * can hold thousands of malformed TALs, and one diagnostic per TAL would be an unbounded
+ * allocation dressed up as diligence. Nothing is hidden — `occurrences` says how many there were.
+ */
+import { decodeHeaderLatin1 } from '../bytes/latin1.js';
+import { sliceBytes } from '../bytes/view.js';
+import { TAL_FIELD_TERMINATOR, TAL_ONSET_DURATION_SEPARATOR, TAL_TERMINATOR, } from '../constants.js';
+import { parseSignedTicks, parseUnsignedTicks } from './ticks.js';
+/** Caps the bytes copied into a diagnostic. The full region is one hexdump from `byteOffset`. */
+export const TAL_PREVIEW_MAX_BYTES = 48;
+/**
+ * `recordOnsetTicks` is a `BigInt64Array`, and assigning an out-of-range bigint to one WRAPS
+ * silently instead of throwing. A value that cannot round-trip through int64 is therefore
+ * refused here rather than stored wrong. The bound is ~29,000 years, so nothing real is lost.
+ */
+const INT64_MIN = -(2n ** 63n);
+const INT64_MAX = 2n ** 63n - 1n;
+/**
+ * An int64 tick count needs at most 19 digits, plus a sign, a point and 7 fractional digits.
+ * The cap exists so a corrupt region of digits cannot drive quadratic bigint work: the digits
+ * are counted before any bigint is built.
+ */
+const MAX_TIMESTAMP_FIELD_CHARS = 40;
+const CHANNEL_LABEL_SEPARATOR = '@@';
+const ASCII_HIGH_BIT = 0x80;
+const ASCII_DEL = 0x7f;
+const ASCII_FIRST_PRINTABLE = 0x20;
+/** `undefined` = not looked up yet, `null` = this runtime has no `TextDecoder`. */
+let cachedUtf8Decoder;
+/**
+ * A strict UTF-8 decoder, or `null`.
+ *
+ * `fatal` is what makes invalid UTF-8 detectable at all; without it the decoder substitutes
+ * U+FFFD and the file's bytes are gone. `ignoreBOM` keeps a leading U+FEFF as a character,
+ * because annotation text is exposed verbatim and a silently stripped BOM is a silently changed
+ * string. Every runtime edfcore supports has `TextDecoder`; the `null` branch exists so an
+ * exotic one degrades to Latin-1 with a diagnostic instead of throwing.
+ */
+function utf8Decoder() {
+    if (cachedUtf8Decoder === undefined) {
+        const Decoder = globalThis.TextDecoder;
+        cachedUtf8Decoder =
+            Decoder === undefined ? null : new Decoder('utf-8', { fatal: true, ignoreBOM: true });
+    }
+    return cachedUtf8Decoder;
+}
+/**
+ * `noUncheckedIndexedAccess` types `region[i]` as `number | undefined`. -1 is not a byte value,
+ * so every structural comparison below is simply false past the end of the region.
+ */
+function readByte(region, index) {
+    return region[index] ?? -1;
+}
+function indexOfByte(region, start, end, byte) {
+    for (let i = start; i < end; i += 1) {
+        if (readByte(region, i) === byte)
+            return i;
+    }
+    return -1;
+}
+function escapeControls(text) {
+    let out = '';
+    for (let i = 0; i < text.length; i += 1) {
+        const code = text.charCodeAt(i);
+        out +=
+            code < ASCII_FIRST_PRINTABLE || code === ASCII_DEL
+                ? `\\x${code.toString(16).padStart(2, '0')}`
+                : text.charAt(i);
+    }
+    return out;
+}
+/**
+ * Bytes as a short, escaped, single-line string for a diagnostic message.
+ *
+ * Latin-1 and not UTF-8 on purpose: this is evidence about bytes, so every byte must map to
+ * exactly one visible character even when the run is the invalid UTF-8 being complained about.
+ */
+export function previewBytes(bytes, offset, length) {
+    const shown = Math.min(length, TAL_PREVIEW_MAX_BYTES);
+    const text = escapeControls(decodeHeaderLatin1(sliceBytes(bytes, offset, shown)));
+    return length > shown ? `${text}...` : text;
+}
+function logIssue(log, code, region, offset, length, detail) {
+    const existing = log.get(code);
+    if (existing !== undefined) {
+        existing.occurrences += 1;
+        return;
+    }
+    log.set(code, {
+        code,
+        byteOffsetInRegion: offset,
+        byteLength: length,
+        occurrences: 1,
+        detail,
+        raw: previewBytes(region, offset, length),
+    });
+}
+function isAsciiRun(bytes) {
+    for (const byte of bytes) {
+        if (byte >= ASCII_HIGH_BIT)
+            return false;
+    }
+    return true;
+}
+function decodeTextRun(region, start, length, log) {
+    const bytes = sliceBytes(region, start, length);
+    // ASCII is UTF-8, byte for byte, and it is what almost every file contains. Taking it here
+    // means the decoder is only ever built for text that actually needs one.
+    if (isAsciiRun(bytes)) {
+        return {
+            text: decodeHeaderLatin1(bytes),
+            encoding: 'utf-8',
+            byteOffsetInRegion: start,
+            byteLength: length,
+        };
+    }
+    const decoder = utf8Decoder();
+    if (decoder !== null) {
+        try {
+            return {
+                text: decoder.decode(bytes),
+                encoding: 'utf-8',
+                byteOffsetInRegion: start,
+                byteLength: length,
+            };
+        }
+        catch {
+            // A fatal decoder rejects invalid UTF-8 with a TypeError. Fall through to Latin-1.
+        }
+    }
+    logIssue(log, 'ANNOTATION_TEXT_NOT_UTF8', region, start, length, decoder === null
+        ? 'this runtime has no TextDecoder, so the text run could not be verified as UTF-8 and ' +
+            'was decoded as ISO-8859-1'
+        : 'the text run is not valid UTF-8 and was decoded as ISO-8859-1 instead');
+    return {
+        text: decodeHeaderLatin1(bytes),
+        encoding: 'latin-1-fallback',
+        byteOffsetInRegion: start,
+        byteLength: length,
+    };
+}
+function outsideInt64(ticks) {
+    return ticks < INT64_MIN || ticks > INT64_MAX;
+}
+/**
+ * One TAL slot at `start`, which is known to hold a non-0x00 byte.
+ *
+ * Returns `tal: undefined` for a slot that was skipped; `next` still advances past it, so the
+ * rest of the region is parsed either way. That is the whole point of `TAL_MALFORMED` being a
+ * warning: one bad TAL must not cost the file.
+ */
+function scanTal(region, start, ordinal, log) {
+    const regionLength = region.length;
+    const bodyEnd = indexOfByte(region, start, regionLength, TAL_TERMINATOR);
+    if (bodyEnd < 0) {
+        logIssue(log, 'TAL_TRUNCATED_AT_REGION_END', region, start, regionLength - start, 'a TAL begins here and has no terminating 0x00 inside the region, so it was discarded ' +
+            "rather than continued into the following signal's samples");
+        return { tal: undefined, next: regionLength };
+    }
+    const next = bodyEnd + 1;
+    const timestampEnd = indexOfByte(region, start, bodyEnd, TAL_FIELD_TERMINATOR);
+    if (timestampEnd < 0) {
+        logIssue(log, 'TAL_MALFORMED', region, start, bodyEnd - start, 'the timestamp is not terminated by 0x14, so the TAL was skipped');
+        return { tal: undefined, next };
+    }
+    const separator = indexOfByte(region, start, timestampEnd, TAL_ONSET_DURATION_SEPARATOR);
+    const onsetEnd = separator < 0 ? timestampEnd : separator;
+    if (onsetEnd - start > MAX_TIMESTAMP_FIELD_CHARS) {
+        logIssue(log, 'TAL_MALFORMED', region, start, onsetEnd - start, `the onset field is ${onsetEnd - start} bytes long, which no time in 100 ns ticks needs; ` +
+            'the TAL was skipped');
+        return { tal: undefined, next };
+    }
+    const onsetRaw = decodeHeaderLatin1(sliceBytes(region, start, onsetEnd - start));
+    const signedOnset = parseSignedTicks(onsetRaw);
+    let onsetTicks = signedOnset.ticks;
+    if (!signedOnset.ok) {
+        // `parseSignedTicks` fails for a missing sign and for a bad magnitude alike. Only the first
+        // is recoverable, and re-parsing without the sign is how they are told apart.
+        const unsignedOnset = parseUnsignedTicks(onsetRaw);
+        if (!unsignedOnset.ok) {
+            logIssue(log, 'TAL_MALFORMED', region, start, Math.max(onsetEnd - start, 1), `the onset "${onsetRaw}" is not ("+" / "-") 1*DIGIT [ "." 1*DIGIT ], so the TAL was ` +
+                'skipped');
+            return { tal: undefined, next };
+        }
+        onsetTicks = unsignedOnset.ticks;
+        logIssue(log, 'TAL_MALFORMED', region, start, onsetEnd - start, `the onset "${onsetRaw}" has no mandatory sign; the value is unambiguous, so the TAL was ` +
+            'kept and the onset read as positive');
+    }
+    if (outsideInt64(onsetTicks)) {
+        logIssue(log, 'TAL_MALFORMED', region, start, onsetEnd - start, `the onset "${onsetRaw}" is outside the +/-2^63 tick range edfcore can represent, so the ` +
+            'TAL was skipped');
+        return { tal: undefined, next };
+    }
+    let durationRaw;
+    let durationTicks;
+    if (separator >= 0) {
+        const durationStart = separator + 1;
+        const durationLength = timestampEnd - durationStart;
+        if (durationLength > MAX_TIMESTAMP_FIELD_CHARS) {
+            logIssue(log, 'TAL_MALFORMED', region, durationStart, durationLength, `the duration field is ${durationLength} bytes long, which no time in 100 ns ticks ` +
+                'needs; the TAL was skipped');
+            return { tal: undefined, next };
+        }
+        durationRaw = decodeHeaderLatin1(sliceBytes(region, durationStart, durationLength));
+        const duration = parseUnsignedTicks(durationRaw);
+        if (!duration.ok || outsideInt64(duration.ticks)) {
+            logIssue(log, 'TAL_MALFORMED', region, durationStart, Math.max(durationLength, 1), `0x15 is present but the duration "${durationRaw}" is not 1*DIGIT [ "." 1*DIGIT ] — a ` +
+                'duration is never signed — so the TAL was skipped');
+            return { tal: undefined, next };
+        }
+        durationTicks = duration.ticks;
+    }
+    const texts = [];
+    let runStart = timestampEnd + 1;
+    for (let i = runStart; i < bodyEnd; i += 1) {
+        if (readByte(region, i) !== TAL_FIELD_TERMINATOR)
+            continue;
+        texts.push(readTextRun(region, runStart, i, log));
+        runStart = i + 1;
+    }
+    if (runStart < bodyEnd) {
+        // The grammar terminates every text with 0x14, so a run left over here means the last text
+        // ran straight into the TAL terminator. The bytes are unambiguous, so the text is kept.
+        logIssue(log, 'TAL_MALFORMED', region, runStart, bodyEnd - runStart, 'the last text of the TAL is not terminated by 0x14; the text was kept verbatim');
+        texts.push(readTextRun(region, runStart, bodyEnd, log));
+    }
+    return {
+        tal: {
+            ordinal,
+            byteOffsetInRegion: start,
+            byteLength: next - start,
+            onsetRaw,
+            onsetTicks,
+            durationRaw,
+            durationTicks,
+            texts,
+        },
+        next,
+    };
+}
+function readTextRun(region, start, end, log) {
+    if (indexOfByte(region, start, end, TAL_ONSET_DURATION_SEPARATOR) >= 0) {
+        logIssue(log, 'TAL_MALFORMED', region, start, end - start, 'a text run contains 0x15, which the grammar reserves for the onset/duration separator; ' +
+            'the text was kept verbatim');
+    }
+    return decodeTextRun(region, start, end - start, log);
+}
+/**
+ * Every TAL in `[regionStart, regionStart + regionBytes)`, and nothing outside it.
+ *
+ * `region = *TAL *%x00`, so a 0x00 where a TAL would start means the padding has begun. Content
+ * after that point is `TAL_REGION_NOT_NUL_TERMINATED`; parsing then RESUMES at those bytes
+ * rather than stopping, because they are still inside this signal's own region and a writer
+ * that pads between TALs would otherwise lose every annotation after the first pad. Recovery is
+ * bounded: each attempt consumes at least one byte, and a slot that does not parse is skipped
+ * to just past its 0x00.
+ */
+export function parseTalRegion(bytes, regionStart, regionBytes) {
+    const region = sliceBytes(bytes, regionStart, regionBytes);
+    const log = new Map();
+    const tals = [];
+    let position = 0;
+    let ordinal = 0;
+    while (position < regionBytes) {
+        if (readByte(region, position) === TAL_TERMINATOR) {
+            let scan = position;
+            while (scan < regionBytes && readByte(region, scan) === TAL_TERMINATOR)
+                scan += 1;
+            if (scan === regionBytes)
+                break;
+            logIssue(log, 'TAL_REGION_NOT_NUL_TERMINATED', region, scan, regionBytes - scan, 'the region tail after the last TAL is not all 0x00; parsing resumed at this byte');
+            // A TAL found after padding did not begin the region, so it must never be promoted into
+            // the timekeeping role: slot 0 is a position, not "the first TAL we managed to parse".
+            if (ordinal === 0)
+                ordinal = 1;
+            position = scan;
+            continue;
+        }
+        const scan = scanTal(region, position, ordinal, log);
+        if (scan.tal !== undefined)
+            tals.push(scan.tal);
+        ordinal += 1;
+        position = scan.next;
+    }
+    return { tals, issues: [...log.values()] };
+}
+/**
+ * `description@@channel` split at the LAST `@@`, because the channel label is the suffix and a
+ * description is free to contain anything.
+ *
+ * A trailing `@@` with nothing after it is not a channel label: the text keeps it verbatim.
+ * `@@Fp1` with nothing before it yields an empty description and the channel — the run itself
+ * is not empty, so it is still a real annotation.
+ */
+export function splitChannelLabel(run) {
+    const at = run.lastIndexOf(CHANNEL_LABEL_SEPARATOR);
+    if (at < 0 || at + CHANNEL_LABEL_SEPARATOR.length >= run.length) {
+        return { text: run, channelLabel: undefined };
+    }
+    return { text: run.slice(0, at), channelLabel: run.slice(at + CHANNEL_LABEL_SEPARATOR.length) };
+}
+//# sourceMappingURL=grammar.js.map

package/dist/tal/grammar.js.map

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

package/dist/tal/ticks.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Decimal text to exact 100 ns ticks.
+ *
+ * Layer 3. Sole owner of the string -> tick conversion, which is the whole reason event times
+ * in edfcore compare exactly. `parseFloat`, `Number(text)` and float arithmetic appear nowhere
+ * on that path: an onset written `+0.1` and one written `+0.3` are integers here, so equality,
+ * ordering and subtraction are decided by the digits on disk rather than by float64 rounding.
+ */
+/**
+ * One parsed onset or duration field.
+ *
+ * `ticks` is the authoritative value; `seconds` and any float derived from it are conveniences.
+ */
+export interface TickParse {
+    /**
+     * The text matched the EDF+ grammar for its field. When false, `ticks` is 0n except in the
+     * one documented case in `parseSignedTicks` (a valid magnitude with the sign missing).
+     */
+    readonly ok: boolean;
+    readonly ticks: bigint;
+    /** The input verbatim, so a caller never has to reconstruct the digits it came from. */
+    readonly raw: string;
+    /** Lossy by construction. See `ticksToSeconds`. */
+    readonly seconds: number;
+}
+/**
+ * An EDF+ onset: `("+" / "-") 1*DIGIT [ "." 1*DIGIT ]`.
+ *
+ * The sign is mandatory, so an unsigned onset is a spec violation and `ok` is false — the caller
+ * emits `TAL_MALFORMED`. The magnitude is parsed anyway and returned in `ticks`, so a lenient
+ * caller can still use the value instead of discarding an otherwise readable annotation. That is
+ * the only case where `ok: false` comes with a meaningful `ticks`.
+ *
+ * `-` applies to the WHOLE value, fraction included: `-0.5` is -5000000 ticks, not -0 plus
+ * 5000000. Splitting the sign off the fraction flips pre-stimulus event times about zero.
+ */
+export declare function parseSignedTicks(text: string): TickParse;
+/**
+ * An EDF+ duration: `1*DIGIT [ "." 1*DIGIT ]`, never signed.
+ *
+ * A leading `+` or `-` fails the grammar; it is not tolerated and not stripped, because a signed
+ * duration means the writer's field layout is not the one we are reading.
+ */
+export declare function parseUnsignedTicks(text: string): TickParse;
+/**
+ * Ticks as float64 seconds, for ergonomics and display.
+ *
+ * Lossy by construction — most tick values are not representable in binary floating point, and
+ * beyond 2^53 ticks (~28.5 years) even the integer part rounds. The exact value always stays
+ * available as ticks, and that is what comparisons must use.
+ *
+ * Split into whole seconds plus remainder so that only the remainder is ever divided; bigint
+ * `/` truncates toward zero and `%` keeps the dividend's sign, so both parts share a sign and
+ * the sum is correct for negative onsets.
+ */
+export declare function ticksToSeconds(ticks: bigint): number;
+/**
+ * Seconds to ticks, rounded to the NEAREST tick (ties away from zero is not required; ties go
+ * toward +Infinity, as `Math.round` does).
+ *
+ * Only for user-supplied bounds such as a time window, never for a value read from disk: a
+ * caller's `30.0` must resolve to 300000000 ticks and not to 299999999 because `30 * 1e7` landed
+ * one ULP low. On-disk values reach ticks through the digit parsers above, which never round.
+ *
+ * Throws `RangeError` for a non-finite argument: there is no tick count for NaN or Infinity, and
+ * inventing 0 would silently move a window to the file start.
+ */
+export declare function secondsToTicks(seconds: number): bigint;
+//# sourceMappingURL=ticks.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ticks.d.ts","sourceRoot":"","sources":["../../src/tal/ticks.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH;;;;GAIG;AACH,MAAM,WAAW,SAAS;IACxB;;;OAGG;IACH,QAAQ,CAAC,EAAE,EAAE,OAAO,CAAC;IACrB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,wFAAwF;IACxF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAwED;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAOxD;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAQ1D;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAIpD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAQtD"}

package/dist/tal/ticks.js

@@ -0,0 +1,137 @@
+/**
+ * Decimal text to exact 100 ns ticks.
+ *
+ * Layer 3. Sole owner of the string -> tick conversion, which is the whole reason event times
+ * in edfcore compare exactly. `parseFloat`, `Number(text)` and float arithmetic appear nowhere
+ * on that path: an onset written `+0.1` and one written `+0.3` are integers here, so equality,
+ * ordering and subtraction are decided by the digits on disk rather than by float64 rounding.
+ */
+import { TICKS_PER_SECOND } from '../constants.js';
+const ASCII_ZERO = 0x30;
+const ASCII_NINE = 0x39;
+const ASCII_PLUS = 0x2b;
+const ASCII_MINUS = 0x2d;
+const ASCII_DOT = 0x2e;
+/** `TICKS_PER_SECOND` is 10^7, so exactly seven fractional decimal digits are representable. */
+const TICK_FRACTION_DIGITS = 7;
+/** Exact: 10^7 is far below 2^53, so this conversion loses nothing. */
+const TICKS_PER_SECOND_FLOAT = Number(TICKS_PER_SECOND);
+const MAGNITUDE_FAILED = { ok: false, ticks: 0n };
+function isAsciiDigit(code) {
+    return code >= ASCII_ZERO && code <= ASCII_NINE;
+}
+/**
+ * `1*DIGIT [ "." 1*DIGIT ]` starting at `start`, accumulated digit by digit into a bigint.
+ *
+ * Fractional digits beyond the seventh are below tick resolution and are TRUNCATED, never
+ * rounded: rounding would move an event to a time that is in no file, and for a stimulus marker
+ * that is the difference between a pre- and a post-stimulus sample. The extra digits are still
+ * required to be digits, so `+1.00000000x` is rejected rather than silently truncated.
+ */
+function parseMagnitudeTicks(text, start) {
+    const end = text.length;
+    let i = start;
+    let whole = 0n;
+    while (i < end) {
+        const code = text.charCodeAt(i);
+        if (!isAsciiDigit(code))
+            break;
+        whole = whole * 10n + BigInt(code - ASCII_ZERO);
+        i += 1;
+    }
+    if (i === start)
+        return MAGNITUDE_FAILED;
+    let ticks = whole * TICKS_PER_SECOND;
+    if (i === end)
+        return { ok: true, ticks };
+    // Anything other than a decimal point here is a space, a second sign, a stray structural
+    // byte or trailing padding, and none of those are part of the grammar.
+    if (text.charCodeAt(i) !== ASCII_DOT)
+        return MAGNITUDE_FAILED;
+    i += 1;
+    let fractionDigits = 0;
+    let scale = TICKS_PER_SECOND;
+    while (i < end) {
+        const code = text.charCodeAt(i);
+        if (!isAsciiDigit(code))
+            return MAGNITUDE_FAILED;
+        fractionDigits += 1;
+        if (fractionDigits <= TICK_FRACTION_DIGITS) {
+            scale = scale / 10n;
+            ticks += BigInt(code - ASCII_ZERO) * scale;
+        }
+        i += 1;
+    }
+    if (fractionDigits === 0)
+        return MAGNITUDE_FAILED;
+    return { ok: true, ticks };
+}
+/**
+ * An EDF+ onset: `("+" / "-") 1*DIGIT [ "." 1*DIGIT ]`.
+ *
+ * The sign is mandatory, so an unsigned onset is a spec violation and `ok` is false — the caller
+ * emits `TAL_MALFORMED`. The magnitude is parsed anyway and returned in `ticks`, so a lenient
+ * caller can still use the value instead of discarding an otherwise readable annotation. That is
+ * the only case where `ok: false` comes with a meaningful `ticks`.
+ *
+ * `-` applies to the WHOLE value, fraction included: `-0.5` is -5000000 ticks, not -0 plus
+ * 5000000. Splitting the sign off the fraction flips pre-stimulus event times about zero.
+ */
+export function parseSignedTicks(text) {
+    const first = text.length > 0 ? text.charCodeAt(0) : -1;
+    const negative = first === ASCII_MINUS;
+    const signed = negative || first === ASCII_PLUS;
+    const magnitude = parseMagnitudeTicks(text, signed ? 1 : 0);
+    const ticks = negative ? -magnitude.ticks : magnitude.ticks;
+    return { ok: magnitude.ok && signed, ticks, raw: text, seconds: ticksToSeconds(ticks) };
+}
+/**
+ * An EDF+ duration: `1*DIGIT [ "." 1*DIGIT ]`, never signed.
+ *
+ * A leading `+` or `-` fails the grammar; it is not tolerated and not stripped, because a signed
+ * duration means the writer's field layout is not the one we are reading.
+ */
+export function parseUnsignedTicks(text) {
+    const magnitude = parseMagnitudeTicks(text, 0);
+    return {
+        ok: magnitude.ok,
+        ticks: magnitude.ticks,
+        raw: text,
+        seconds: ticksToSeconds(magnitude.ticks),
+    };
+}
+/**
+ * Ticks as float64 seconds, for ergonomics and display.
+ *
+ * Lossy by construction — most tick values are not representable in binary floating point, and
+ * beyond 2^53 ticks (~28.5 years) even the integer part rounds. The exact value always stays
+ * available as ticks, and that is what comparisons must use.
+ *
+ * Split into whole seconds plus remainder so that only the remainder is ever divided; bigint
+ * `/` truncates toward zero and `%` keeps the dividend's sign, so both parts share a sign and
+ * the sum is correct for negative onsets.
+ */
+export function ticksToSeconds(ticks) {
+    const wholeSeconds = ticks / TICKS_PER_SECOND;
+    const remainder = ticks % TICKS_PER_SECOND;
+    return Number(wholeSeconds) + Number(remainder) / TICKS_PER_SECOND_FLOAT;
+}
+/**
+ * Seconds to ticks, rounded to the NEAREST tick (ties away from zero is not required; ties go
+ * toward +Infinity, as `Math.round` does).
+ *
+ * Only for user-supplied bounds such as a time window, never for a value read from disk: a
+ * caller's `30.0` must resolve to 300000000 ticks and not to 299999999 because `30 * 1e7` landed
+ * one ULP low. On-disk values reach ticks through the digit parsers above, which never round.
+ *
+ * Throws `RangeError` for a non-finite argument: there is no tick count for NaN or Infinity, and
+ * inventing 0 would silently move a window to the file start.
+ */
+export function secondsToTicks(seconds) {
+    if (!Number.isFinite(seconds)) {
+        throw new RangeError(`secondsToTicks(): expected a finite number of seconds, received ${seconds}. ` +
+            'Next: check the window bound you passed in.');
+    }
+    return BigInt(Math.round(seconds * TICKS_PER_SECOND_FLOAT));
+}
+//# sourceMappingURL=ticks.js.map

package/dist/tal/ticks.js.map

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

package/dist/time/segments.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Record onsets to segments and gaps.
+ *
+ * Layer 4. Pure and synchronous, and structural only: it reports the shape the onsets actually
+ * have and judges none of it. Monotonicity and the spacing rules belong to `time/timeline.ts`,
+ * which is their sole owner — run `assertMonotonicOnsetArray` on the same array first, and a gap
+ * can then only have a non-negative duration.
+ *
+ * Only `buildRecordIndex` calls this, because only a complete traversal has every onset. The
+ * boundary rule is the one edfcore states everywhere else: a new segment starts wherever
+ * `onset[r] !== onset[r - 1] + recordDurationTicks`, in exact ticks. Not "differs by more than an
+ * epsilon" — a float tolerance is how a one-sample overlap becomes invisible.
+ *
+ * Every second here is elapsed recording time, measured from record 0's start (see
+ * `time/timeline.ts`), so `segment.startTicks` is the rebased value and
+ * `ticksToSeconds(segment.startTicks) === segment.startSeconds` holds by construction.
+ */
+import type { EdfGap, EdfSegment } from '../types.js';
+export interface Segmentation {
+    /** In time order, contiguous within each entry, and covering every record exactly once. */
+    readonly segments: readonly EdfSegment[];
+    /** One per adjacent pair of segments, so `gaps.length === segments.length - 1` (or 0). */
+    readonly gaps: readonly EdfGap[];
+}
+/**
+ * `onsetTicks` holds one entry per record, record 0 first — the `BigInt64Array` that
+ * `decodeAnnotations` returns for a full-file range fits directly.
+ *
+ * `originTicks` is the tick value that maps to `0` seconds. It defaults to `onsetTicks[0]`,
+ * which is record 0's own onset and therefore the recording's sub-second start offset.
+ */
+export declare function buildSegmentation(onsetTicks: ArrayLike<bigint>, recordDurationTicks: bigint, originTicks?: bigint): Segmentation;
+//# sourceMappingURL=segments.d.ts.map

package/dist/time/segments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"segments.d.ts","sourceRoot":"","sources":["../../src/time/segments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEtD,MAAM,WAAW,YAAY;IAC3B,2FAA2F;IAC3F,QAAQ,CAAC,QAAQ,EAAE,SAAS,UAAU,EAAE,CAAC;IACzC,0FAA0F;IAC1F,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAaD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,SAAS,CAAC,MAAM,CAAC,EAC7B,mBAAmB,EAAE,MAAM,EAC3B,WAAW,CAAC,EAAE,MAAM,GACnB,YAAY,CA0Dd"}