@needmoretruth/nmts-cli 0.17.2 → 0.34.1

package/dist/shared/lib/drive/manifest-settings.js

@@ -14,6 +14,23 @@ export const TEXT_SCALE_MIN_PCT = 80;
 export const TEXT_SCALE_MAX_PCT = 160;
 /** Follow the device. Not written to the wire — absence is the only spelling of it. */
 export const TEXT_SCALE_DEFAULT_PCT = 100;
+/** The most a standing tip can be: the whole payment. Above the dial's 10 % it is typed and confirmed. */
+export const TIP_TENTHS_MAX = 1000;
+/**
+ * The deposit range this format carries: whole credits, 0 to 64.
+ *
+ * ⚠ The SERVER's own ceiling rides on the account view (`deposit_max`) and is what the payment
+ * screen holds the chosen figure inside. This pair is the format's bound, so a value written by
+ * some other build is read back only when it is one this build can also write.
+ */
+export const DEPOSIT_MAX_CREDITS = 64;
+/** What an account's deposit is when nobody chose. Not written to the wire — absence spells it. */
+export const DEPOSIT_DEFAULT_CREDITS = DEPOSIT_MAX_CREDITS;
+/** The default deposit in force for an account, in credits. Absence is the full deposit, not 0. */
+export function depositDefaultOf(settings) {
+    const stored = settings?.depositDefault;
+    return typeof stored === "number" ? stored : DEPOSIT_DEFAULT_CREDITS;
+}
 /** Settings → wire, or null when every field is at its default (then nothing is written). */
 export function settingsToWire(s) {
     if (!s)
@@ -28,9 +45,28 @@ export function settingsToWire(s) {
         s.textScalePct <= TEXT_SCALE_MAX_PCT) {
         w.tx = Math.round(s.textScalePct);
     }
-    if (s.paddingMode === "pow2")
-        w.pd = "pow2";
-    return w.dm !== undefined || w.tx !== undefined || w.pd !== undefined ? w : null;
+    if (s.paddingMode === "pow2" || s.paddingMode === "none")
+        w.pd = s.paddingMode;
+    if (typeof s.depositDefault === "number" &&
+        Number.isInteger(s.depositDefault) &&
+        s.depositDefault >= 0 &&
+        s.depositDefault < DEPOSIT_MAX_CREDITS) {
+        w.dd = s.depositDefault;
+    }
+    if (typeof s.tipTenths === "number" && Number.isInteger(s.tipTenths) && s.tipTenths > 0 && s.tipTenths <= TIP_TENTHS_MAX) {
+        w.tp = s.tipTenths;
+    }
+    if (typeof s.tipConsentAt === "number" && Number.isFinite(s.tipConsentAt) && s.tipConsentAt > 0) {
+        w.tc = Math.round(s.tipConsentAt);
+    }
+    return w.dm !== undefined ||
+        w.tx !== undefined ||
+        w.pd !== undefined ||
+        w.dd !== undefined ||
+        w.tp !== undefined ||
+        w.tc !== undefined
+        ? w
+        : null;
 }
 /**
  * Wire → settings, dropping anything unusable. A text scale outside the bounds is DROPPED, not
@@ -45,6 +81,9 @@ export function settingsFromWire(w) {
     const dm = Reflect.get(w, "dm");
     const tx = Reflect.get(w, "tx");
     const pd = Reflect.get(w, "pd");
+    const dd = Reflect.get(w, "dd");
+    const tp = Reflect.get(w, "tp");
+    const tc = Reflect.get(w, "tc");
     const s = {};
     if (dm === 1)
         s.developerMode = true;
@@ -57,9 +96,51 @@ export function settingsFromWire(w) {
     }
     // An unknown rule is DROPPED, not guessed at: padding a file by a rule this build does not know
     // would give it a size no reader here can undo. Falling back to the default is always readable.
-    if (pd === "pow2")
-        s.paddingMode = "pow2";
-    return s.developerMode !== undefined || s.textScalePct !== undefined || s.paddingMode !== undefined
+    if (pd === "pow2" || pd === "none")
+        s.paddingMode = pd;
+    // A deposit outside the range is DROPPED, not clamped: holding back a number some other build
+    // miswrote is worse than holding back the full deposit, which is what every account starts at.
+    if (typeof dd === "number" && Number.isInteger(dd) && dd >= 0 && dd < DEPOSIT_MAX_CREDITS) {
+        s.depositDefault = dd;
+    }
+    // A tip outside the bounds is DROPPED, not clamped: sending a share some other build miswrote is
+    // worse than sending nothing, which is always what 0 means.
+    if (typeof tp === "number" && Number.isInteger(tp) && tp > 0 && tp <= TIP_TENTHS_MAX)
+        s.tipTenths = tp;
+    if (typeof tc === "number" && Number.isFinite(tc) && tc > 0)
+        s.tipConsentAt = Math.round(tc);
+    return s.developerMode !== undefined ||
+        s.textScalePct !== undefined ||
+        s.paddingMode !== undefined ||
+        s.depositDefault !== undefined ||
+        s.tipTenths !== undefined ||
+        s.tipConsentAt !== undefined
         ? s
         : undefined;
 }
+/** Folds a deposit patch into a settings copy: out-of-range is clamped, the full deposit clears. */
+export function applyDepositPatch(next, depositDefault) {
+    if (depositDefault === undefined || !Number.isFinite(depositDefault))
+        return;
+    const credits = Math.round(Math.min(DEPOSIT_MAX_CREDITS, Math.max(0, depositDefault)));
+    if (credits === DEPOSIT_DEFAULT_CREDITS)
+        delete next.depositDefault;
+    else
+        next.depositDefault = credits;
+}
+/** Folds a tip patch into a settings copy: 0 clears, above the cap is capped, fractions are rounded. */
+export function applyTipPatch(next, tipTenths, tipConsentAt) {
+    if (tipTenths !== undefined && Number.isFinite(tipTenths)) {
+        const t = Math.round(Math.min(TIP_TENTHS_MAX, Math.max(0, tipTenths)));
+        if (t === 0)
+            delete next.tipTenths;
+        else
+            next.tipTenths = t;
+    }
+    if (tipConsentAt !== undefined && Number.isFinite(tipConsentAt)) {
+        if (tipConsentAt <= 0)
+            delete next.tipConsentAt;
+        else
+            next.tipConsentAt = Math.round(tipConsentAt);
+    }
+}

package/dist/shared/lib/drive/name-conflict.d.ts

@@ -0,0 +1,76 @@
+/** What to do with one name that is already in use. */
+export type ConflictChoice = "rename" | "overwrite";
+/** One file whose desired name is already taken. */
+export interface Conflict {
+    /** Index into the batch handed to `findConflicts`, so the caller can match its own record. */
+    readonly at: number;
+    /** The name that is already in use. */
+    readonly name: string;
+    /** The folder it collides in — null is the root. */
+    readonly parentId: string | null;
+}
+/** A conflict as it is put to whoever answers, with the answer already worked out for one branch. */
+export interface Asked extends Conflict {
+    /**
+     * The name renaming would actually produce, at this point in the batch.
+     *
+     * ⛔ THE NAME, NOT "A NUMBER GETS ADDED". A screen that cannot say what the file will be called
+     *    is asking somebody to choose between one known outcome and one unknown one. And it has to
+     *    come from this walk rather than be guessed alongside it, or the second of three collisions
+     *    is shown `(2)` and stored as `(3)`.
+     */
+    readonly renamedTo: string;
+    /** How many conflicts are still to come after this one. 0 means this is the last. */
+    readonly remaining: number;
+}
+/** One file on its way in, as much of it as this file needs. */
+export interface Incoming {
+    readonly name: string;
+    readonly parentId: string | null;
+}
+/**
+ * Which of these collide, in batch order.
+ *
+ * ⛔ THE TAKEN SET GROWS AS THIS WALKS. Two files called `report.pdf` in one drop collide with each
+ *    other, not only with the drive — and a caller that asked only about the drive would give both
+ *    the same name. So a name that has been handed out here counts as taken from then on, and the
+ *    second one is reported as a conflict too.
+ */
+export declare function findConflicts(batch: readonly Incoming[], takenIn: (parentId: string | null) => ReadonlySet<string>): Conflict[];
+/** What one file ended up as, after the choices were applied. */
+export interface Settled {
+    /** The name it will be stored under. */
+    readonly name: string;
+    readonly parentId: string | null;
+    /**
+     * The name it replaces in that folder, when the choice was to overwrite.
+     *
+     * ⚠ The NAME, not an id: this file does not know the drive's identifiers, and the caller that
+     *   does is the one that has to find and destroy the old record.
+     */
+    readonly replaces?: string;
+}
+/**
+ * Apply the choices and hand back what each file becomes.
+ *
+ * `choiceFor` is asked only about names that actually collide, one at a time and in batch order, so
+ * a screen can put the question to a person and this walk waits. Anything it is not asked about
+ * keeps its name. A batch answer ("do this for all") is the caller returning the same value from
+ * then on without asking again — this file does not need to know that happened.
+ *
+ * ⛔ A RENAME CONSUMES THE NAME IT WAS GIVEN, an overwrite does not. Two files called `report.pdf`
+ *    both overwriting would otherwise be two writes to one name — the second wins and the first is
+ *    lost with nothing said. So the second one is renamed regardless of the choice, and the caller
+ *    can see that because the name it gets back is not the name it asked for.
+ */
+export declare function settle(batch: readonly Incoming[], takenIn: (parentId: string | null) => ReadonlySet<string>, choiceFor: (conflict: Asked) => ConflictChoice | Promise<ConflictChoice>, 
+/**
+ * Can the thing holding this name be replaced at all?
+ *
+ * ⛔ A FOLDER CAN HOLD THE NAME. Offering "overwrite" then would offer to delete a folder and
+ *    everything under it in order to store one file, from a dialog that names a file. Nothing
+ *    asks; those are renamed, which is what happened before anything was asked at all.
+ * ⚠ Left out means everything is replaceable, which is right for callers whose names are all
+ *   files (the S3 gateway has no folders).
+ */
+overwritable?: (conflict: Conflict) => boolean): Promise<Settled[]>;

package/dist/shared/lib/drive/rebuild-verify.d.ts

@@ -0,0 +1,73 @@
+/** Bytes of one sealed part that decide the question (NCF-3 §4.1 header, §4.2 commitment). */
+export declare const NCF3_HEADER_BYTES = 72;
+/**
+ * How many of these reads are in flight at once.
+ *
+ * Small on purpose: it is one tiny range request per file against the public aggregators, and a
+ * rebuild is not a download — going wider would spend an account's whole read budget on 72-byte
+ * requests and make the progress line lie about what is happening.
+ */
+export declare const REBUILD_VERIFY_CONCURRENCY = 4;
+/** Why one pair could not be shown to belong together. */
+export type UnverifiedReason = 
+/** The server's row carries no wrapped key at all — nothing to pair, and nothing to check. */
+"no-key"
+/** The row names no stored part, so there is no header this key could be tried against. */
+ | "no-parts"
+/** The header could not be read (network, aggregator, an unknown storage network). */
+ | "unreadable"
+/** The header was read and this key does not open it — the pair is WRONG, not merely unproven. */
+ | "wrong-key";
+/** One item whose key was not shown to belong to it. */
+export interface UnverifiedPair {
+    readonly id: string;
+    readonly reason: UnverifiedReason;
+}
+/** What one attempt to open a row's first part header came back with. */
+export type PairVerdict = {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly reason: UnverifiedReason;
+};
+/** The least a row must expose to be checked. */
+export interface RebuildRow {
+    readonly id: string;
+    /** The wrapped file key, absent on a row committed before the server kept one. */
+    readonly dekWrapped?: string | undefined;
+}
+export interface VerifyPairingsInput<T extends RebuildRow> {
+    readonly rows: readonly T[];
+    /**
+     * Read this row's FIRST sealed part's header prefix and try to open it with the row's own key.
+     *
+     * ⛔ IT MUST NOT THROW FOR AN ORDINARY FAILURE — a verdict is the answer, and `unreadable` is a
+     *    verdict. A throw is still handled (as `unreadable`, never as a pass) so that a bug on the
+     *    caller's side cannot turn into a list full of keys nobody checked.
+     */
+    openFirstPartHeader(row: T): Promise<PairVerdict>;
+    /** In-flight reads. Defaults to REBUILD_VERIFY_CONCURRENCY; anything below 1 is raised to 1. */
+    readonly concurrency?: number;
+    /** Ticks as answers arrive, so a large account is not a silent wait. */
+    onProgress?: (checked: number, total: number) => void;
+}
+export interface PairingVerdicts {
+    /** Ids whose key was shown to open their own first part. Only these may be written with a key. */
+    readonly verified: ReadonlySet<string>;
+    /** Everything else, in the order the rows were given, each with why. */
+    readonly unverified: readonly UnverifiedPair[];
+}
+/**
+ * Decide, for every row, whether its key belongs to it.
+ *
+ * A row with no key is answered here rather than by the caller's reader: there is nothing to
+ * fetch, and spending a request to learn that would be a request per keyless file.
+ */
+export declare function verifyKeyPairings<T extends RebuildRow>(input: VerifyPairingsInput<T>): Promise<PairingVerdicts>;
+/**
+ * True when this row's key may be written into the rebuilt list.
+ *
+ * Both rebuild paths ask this one question rather than each testing the set themselves, because
+ * "which way round is the set" is exactly the kind of thing two copies get differently.
+ */
+export declare function mayCarryKey(id: string, verdicts: PairingVerdicts): boolean;

package/dist/shared/lib/drive/rebuild-verify.js

@@ -0,0 +1,112 @@
+// Checking that a rebuilt file list pairs each KEY with the file it actually opens. ⚠ PUBLISHED —
+// copied byte-for-byte into the `nmts` command-line package; keep comments self-contained English.
+//
+// ⛔ WHY THIS EXISTS. A rebuild takes each server row's wrapped file key (`dek_wrapped`) and pairs
+//    it with the item as the server presents it. The wrapped key is sealed under a FIXED domain
+//    separator (`nmts/v3/dek-wrap`, NCF-3 §2.2) and NOT under the item's id, so every one of an
+//    account's wrapped keys opens under the same account key — which means a server that handed
+//    back row A's key beside row B's id would produce a list whose pairs are wrong, and every
+//    check on this side would pass. The mistake is invisible because rebuilt names are
+//    placeholders, and it is then SEALED into the list and carried into the recovery list.
+//
+// ⛔ WHY NOTHING FALSE IS EVER READ, AND WHY THAT IS NOT ENOUGH. A part decrypted with the wrong
+//    key fails at its authentication tag, so a wrong pair is a file that will not open — never
+//    wrong bytes. What the wrong pair does is PERSIST: it is written into the sealed list, it
+//    survives every later edit, and the day somebody tries to open the file is years after the
+//    day the pairing could still have been worked out from what the server held.
+//
+// ⭐ THE CHECK IS ONE HEADER, NOT ONE FILE. NCF-3 §4.1 puts a 72-byte plaintext header in front of
+//    every sealed part, and §4.2 puts a key commitment in it — `HKDF(ikm = DEK, salt = nonce_prefix,
+//    info = "nmts/v3/stream-commit" || header[0..40])` — which the decryptor recomputes and
+//    compares IN CONSTANT TIME BEFORE ANY CHUNK IS DECRYPTED. So opening a part's header with a
+//    key either succeeds or does not, and neither answer needs a single byte of ciphertext, a tag,
+//    or a chunk. That is what makes verifying a whole account affordable: one 72-byte ranged read
+//    per file, on the read path the download engine already uses.
+//
+// ⛔ A PAIR THAT DOES NOT OPEN IS NOT WRITTEN WITH A KEY. It keeps its entry — the row, the size
+//    and the dates are real, and an entry is what says the file was there — but the key stays off
+//    it, because a key written beside the wrong file is a claim this side cannot make. The count
+//    and the reasons come back to the caller so a screen or a command can say which is which.
+//
+// ⛔ EVERY UNKNOWN ANSWER IS "UNVERIFIED", never "verified". A read that timed out, an aggregator
+//    that is down, a part row that is missing: none of them is evidence that the key belongs to
+//    the file, and treating them as evidence is exactly how the defect this file closes came back.
+/** Bytes of one sealed part that decide the question (NCF-3 §4.1 header, §4.2 commitment). */
+export const NCF3_HEADER_BYTES = 72;
+/**
+ * How many of these reads are in flight at once.
+ *
+ * Small on purpose: it is one tiny range request per file against the public aggregators, and a
+ * rebuild is not a download — going wider would spend an account's whole read budget on 72-byte
+ * requests and make the progress line lie about what is happening.
+ */
+export const REBUILD_VERIFY_CONCURRENCY = 4;
+/**
+ * Decide, for every row, whether its key belongs to it.
+ *
+ * A row with no key is answered here rather than by the caller's reader: there is nothing to
+ * fetch, and spending a request to learn that would be a request per keyless file.
+ */
+export async function verifyKeyPairings(input) {
+    const { rows, openFirstPartHeader, onProgress } = input;
+    const total = rows.length;
+    // Answers are parked BY POSITION and read back in order at the end: the pool finishes them in
+    // whatever order the network allows, and a list of problems in network order is a list whose
+    // order changes every run.
+    const verdicts = new Array(total);
+    let checked = 0;
+    // The same bounded runner the relay pool probes with: a shared cursor and N workers walking it,
+    // so at most N reads are open and nothing is queued that will not be started.
+    let next = 0;
+    const worker = async () => {
+        while (next < total) {
+            const at = next;
+            next += 1;
+            const row = rows[at];
+            if (row === undefined)
+                continue;
+            verdicts[at] =
+                row.dekWrapped === undefined || row.dekWrapped === ""
+                    ? { ok: false, reason: "no-key" }
+                    : await attempt(openFirstPartHeader, row);
+            checked += 1;
+            onProgress?.(checked, total);
+        }
+    };
+    const workers = Math.min(Math.max(input.concurrency ?? REBUILD_VERIFY_CONCURRENCY, 1), total);
+    await Promise.all(Array.from({ length: workers }, () => worker()));
+    const verified = new Set();
+    const unverified = [];
+    for (let at = 0; at < total; at += 1) {
+        const row = rows[at];
+        if (row === undefined)
+            continue;
+        const verdict = verdicts[at];
+        // An absent verdict cannot happen while the loop above covers every position, and if it ever
+        // did it would mean "not checked" — which is `unverified`, because the alternative is a key
+        // written on the strength of a read nobody made.
+        if (verdict !== undefined && verdict.ok)
+            verified.add(row.id);
+        else
+            unverified.push({ id: row.id, reason: verdict === undefined ? "unreadable" : verdict.reason });
+    }
+    return { verified, unverified };
+}
+/** Run one attempt, turning a thrown reader into the verdict it should have returned. */
+async function attempt(open, row) {
+    try {
+        return await open(row);
+    }
+    catch {
+        return { ok: false, reason: "unreadable" };
+    }
+}
+/**
+ * True when this row's key may be written into the rebuilt list.
+ *
+ * Both rebuild paths ask this one question rather than each testing the set themselves, because
+ * "which way round is the set" is exactly the kind of thing two copies get differently.
+ */
+export function mayCarryKey(id, verdicts) {
+    return verdicts.verified.has(id);
+}

package/dist/shared/lib/drive/unique-name.d.ts

@@ -0,0 +1,9 @@
+/**
+ * A name not present in `taken`.
+ *
+ * Returns `desired` untouched when it is free. Otherwise inserts ` (n)` before the extension,
+ * starting at 2, until it finds a free one — matching desktop behaviour so nobody has to learn a
+ * new convention. `taken` is not mutated; callers uploading several files at once must add each
+ * returned name themselves, or a batch of identical names would all resolve to the same `(2)`.
+ */
+export declare function uniqueFileName(desired: string, taken: ReadonlySet<string>): string;

package/dist/shared/lib/drive/zstd.d.ts

@@ -0,0 +1,27 @@
+/**
+ * What a platform must provide to write (and read) flag 0x02.
+ *
+ * `decompress` is given the largest plaintext the caller will accept. It exists so an encoder can
+ * refuse a frame that CLAIMS to expand past that bound before it allocates for it — a sealed
+ * document is authenticated, but a build that meets a corrupt or hostile one must still not be
+ * asked for a gigabyte of memory first.
+ */
+export interface ZstdCodec {
+    compress(bytes: Uint8Array, level: number): Uint8Array | Promise<Uint8Array>;
+    decompress(bytes: Uint8Array, maxOut: number): Uint8Array | Promise<Uint8Array>;
+}
+/** The level a writer asks for. See the measurement in this file's header before changing it. */
+export declare const ZSTD_LEVEL = 6;
+/** Hand this build its zstd encoder, or `null` to take it away again (tests do the second). */
+export declare function setZstdCodec(codec: ZstdCodec | null): void;
+/** The registered encoder, or null when this build has none. */
+export declare function zstdCodec(): ZstdCodec | null;
+/**
+ * The size the frame SAYS it expands to, or null when the frame does not declare one.
+ *
+ * Reads only the frame header described by RFC 8878, which is at most 14 bytes, so it costs
+ * nothing and — this is the point — it runs BEFORE any buffer is allocated for the output. NCF-3
+ * §6.3.4 requires our writers to emit the content size for exactly this reason; a frame without
+ * one is not ours and is refused by the caller rather than guessed at.
+ */
+export declare function zstdContentSize(frame: Uint8Array): number | null;

package/dist/shared/lib/drive/zstd.js

@@ -0,0 +1,74 @@
+// The zstd seam for the chunked file list (NCF-3 §6.3.4, flag 0x02). ⚠ PUBLISHED —
+// copied byte-for-byte into the `nmts` command-line package; keep comments self-contained English.
+//
+// WHY A SEAM AND NOT AN IMPORT. The browser gets zstd from a WebAssembly build it has to fetch,
+//   and the command line gets it from Node's own `zlib`. Neither belongs in a module the two
+//   share, so this file holds the SHAPE of an encoder and the register that finds one, and each
+//   platform hands its own in. A build that registers nothing still reads and writes lists: the
+//   writer falls back to gzip (§6.3.4), and only a document that already says 0x02 needs a
+//   decoder — which is a refusal the reader names, never an empty drive.
+//
+// LEVEL 6, MEASURED 2026-09-06 on a synthetic list of 100,000 entries shaped like a real drive
+//   (2,000 folders, 98,000 files, random 104-byte wrapped-key and content-hash envelopes,
+//   realistic names), compressed as one CHUNK_PLAIN_MAX-sized chunk payload (3,899,634 bytes,
+//   10,330 entries) with @bokuweb/zstd-wasm under Node 24:
+//
+//     level 1 → 2,409,818 B (61.8 %) ·  8.2 ms/MiB
+//     level 3 → 2,357,562 B (60.5 %) · 10.3 ms/MiB
+//     level 6 → 2,321,378 B (59.5 %) · 32.9 ms/MiB   ← smallest, and well under 100 ms/MiB
+//
+//   ⚠ The ranking is not a law of zstd — it is a fact about THIS data shape, and it inverts
+//   further up: on the same kind of payload, level 10 was measured producing LARGER output than
+//   level 3, in three separate zstd builds. So the level is a measurement, never a guess:
+//   re-measure on real chunks before moving this number, and do not reason about it.
+/** The level a writer asks for. See the measurement in this file's header before changing it. */
+export const ZSTD_LEVEL = 6;
+let registered = null;
+/** Hand this build its zstd encoder, or `null` to take it away again (tests do the second). */
+export function setZstdCodec(codec) {
+    registered = codec;
+}
+/** The registered encoder, or null when this build has none. */
+export function zstdCodec() {
+    return registered;
+}
+/** Magic number every zstd frame starts with (RFC 8878 §3.1.1), little-endian on the wire. */
+const MAGIC = [0x28, 0xb5, 0x2f, 0xfd];
+/**
+ * The size the frame SAYS it expands to, or null when the frame does not declare one.
+ *
+ * Reads only the frame header described by RFC 8878, which is at most 14 bytes, so it costs
+ * nothing and — this is the point — it runs BEFORE any buffer is allocated for the output. NCF-3
+ * §6.3.4 requires our writers to emit the content size for exactly this reason; a frame without
+ * one is not ours and is refused by the caller rather than guessed at.
+ */
+export function zstdContentSize(frame) {
+    if (frame.length < 6)
+        return null;
+    for (let i = 0; i < MAGIC.length; i += 1) {
+        if (frame[i] !== MAGIC[i])
+            return null;
+    }
+    const descriptor = frame[4] ?? 0;
+    const fcsFlag = descriptor >> 6;
+    const singleSegment = (descriptor >> 5) & 1;
+    const dictIdFlag = descriptor & 3;
+    // Field widths, straight from the frame-header descriptor table in RFC 8878: the content-size
+    // field is absent when the flag is 0 unless the frame is one segment, in which case it is a
+    // single byte.
+    const fcsSize = fcsFlag === 0 ? singleSegment : 1 << fcsFlag;
+    if (fcsSize === 0)
+        return null;
+    const dictIdSize = dictIdFlag === 0 ? 0 : 1 << (dictIdFlag - 1);
+    const at = 5 + (singleSegment === 1 ? 0 : 1) + dictIdSize;
+    if (frame.length < at + fcsSize)
+        return null;
+    let value = 0;
+    for (let i = fcsSize - 1; i >= 0; i -= 1) {
+        // Built as a float rather than shifted: an 8-byte field overflows 32-bit shifts, and the only
+        // use of this number is a comparison against a bound in the low millions.
+        value = value * 256 + (frame[at + i] ?? 0);
+    }
+    // A two-byte field is stored with 256 subtracted — the one irregular width in that table.
+    return fcsSize === 2 ? value + 256 : value;
+}