@graphty/graph-io 0.3.24 → 0.3.26

package/dist/src/common/json-elements.js

@@ -12,17 +12,37 @@
  */
 import { GraphFormatError, INVALID_INDEX, } from "@graphty/graph-format";
 import { declareResolved, uniqueColumnName } from "./attributes.js";
-import { ASPECT_ORDER_CODE, BAD_ASPECT_BLOCK_CODE, COLUMN_RENAMED_CODE, COUNT_MISMATCH_CODE, STATUS_FAILED_CODE, STATUS_WARNING_CODE, } from "./codes.js";
+import { ASPECT_ORDER_CODE, BAD_ASPECT_BLOCK_CODE, BAD_VALUE_CODE, COLUMN_RENAMED_CODE, COUNT_MISMATCH_CODE, DUPLICATE_ATTRIBUTE_CODE, JSON_NONSTANDARD_NUMBER_CODE, MULTI_ASPECT_FRAGMENT_CODE, PRECISION_CODE, STATUS_FAILED_CODE, STATUS_WARNING_CODE, } from "./codes.js";
+import { agree, plural } from "./plural.js";
+import { trimTrailingZeros } from "./text.js";
 // ============================================================ exact integers
-/** A run of 16 digits not inside a fraction: the shortest integer literal that can exceed 2^53 (9007199254740992). */
+/**
+ * A run of 16 digits not inside a fraction: the shortest integer literal that can exceed 2^53 (9007199254740992).
+ * @category Plugin helpers
+ */
 export const MAYBE_UNSAFE_INTEGER = /(?<![0-9.])[0-9]{16}/;
+/**
+ * A literal the double read for may not equal: an exponent of 15 or more (`9.007199254740993e15`,
+ * `1e400`: an integer beyond 2^53 or an overflow), an exponent of -300 or less (`1e-400`: an
+ * underflow to 0), or 16 or more digits split by a decimal point before an exponent
+ * (`90071992547409.93e2`). MAYBE_UNSAFE_INTEGER sees none of them.
+ * ponytail: a literal that underflows through 300+ leading fraction zeros and no exponent is not
+ * gated; add a digit-count check if such files turn up.
+ * @category Plugin helpers
+ */
+export const MAYBE_INEXACT_EXPONENT = new RegExp([
+    /\d[eE]\+?0*(?:1[5-9]|[2-9]\d|[1-9]\d{2,})/, // an exponent of 15 or more
+    /\d[eE]-0*(?:[3-9]\d{2}|[1-9]\d{3,})/, // an exponent of -300 or less
+    /(?<![\d.])(?=(?:\d\.?){16})\d+\.\d+[eE]/, // 16 or more digits split by a decimal point
+]
+    .map((r) => r.source)
+    .join("|"));
 /**
  * The prefix of the string a non-standard token or an exact integer is rewritten to (a NUL
- * character first, which no sensible attribute value starts with).
+ * character first, which no sensible attribute value starts with). A document that already holds
+ * the text gets a numbered variant, so a genuine string is never revived as a number.
  */
-const SENTINEL = `${String.fromCharCode(0)}graph-io:`;
-/** The sentinel prefix of an integer literal kept as its digits. */
-const EXACT_SENTINEL = `${SENTINEL}exact:`;
+const SENTINEL = `${String.fromCodePoint(0)}graph-io`;
 /** The non-standard tokens Python's json module writes, longest first so -Infinity wins over a bare minus. */
 const NONSTANDARD_TOKENS = [
     ["-Infinity", -Infinity],
@@ -31,24 +51,103 @@ const NONSTANDARD_TOKENS = [
 ];
 /** A JSON integer literal (no fraction, no exponent, no leading zero), as CANONICAL_INTEGER in common/ids.ts. */
 const INTEGER_LITERAL = /^-?(0|[1-9][0-9]*)$/;
+/** A JSON number literal, split into sign, integer digits, fraction digits and exponent. */
+const NUMBER_PARTS = /^(-?)(\d+)(?:\.(\d+))?(?:[eE]([+-]?\d+))?$/;
+/**
+ * The sentinel prefix of one rewrite: SENTINEL with a colon, or a numbered variant when the document
+ * already holds that one. A string can only decode to a NUL by escaping it (`\u0000`), so when the
+ * text holds that escape the escaped strings are decoded and searched too: any other escape in them
+ * (`graph\u002dio:`) would hide the sentinel from a search of the raw text.
+ * @param text - the document text
+ * @returns the prefix
+ */
+function sentinelFor(text) {
+    let haystack = text;
+    if (/\\u0000/i.test(text)) {
+        const decoded = [];
+        for (const [literal] of text.matchAll(/"(?:[^"\\]|\\.)*"/g)) {
+            if (literal.includes("\\")) {
+                decoded.push(decodeString(literal));
+            }
+        }
+        haystack = `${decoded.join("\n")}\n${text}`;
+    }
+    let k = 0;
+    while (haystack.includes(`graph-io${k === 0 ? "" : String(k)}:`)) {
+        k++;
+    }
+    return `${SENTINEL}${k === 0 ? "" : String(k)}:`;
+}
+/**
+ * Decode one JSON string literal, or give it back as written when it is not valid (the parse then
+ * reports the syntax error).
+ * @param literal - the literal with its quotes
+ * @returns the decoded value
+ */
+function decodeString(literal) {
+    try {
+        return String(JSON.parse(literal));
+    }
+    catch {
+        return literal;
+    }
+}
+/**
+ * Whether a number literal with a fraction or an exponent reads back as another value: an integer
+ * beyond 2^53 written with more significant digits than a double keeps, which the nearest double
+ * misses, or a finite literal beyond the double range or a non-zero one below it.
+ * @param literal - the literal as written
+ * @returns true when the double read for it is not the value it denotes
+ */
+function isInexactLiteral(literal) {
+    const value = Number(literal);
+    if (!Number.isFinite(value)) {
+        return true;
+    }
+    if (value === 0) {
+        // a non-zero literal below the smallest double underflows to 0
+        return /[1-9]/.test(literal.split(/[eE]/)[0]);
+    }
+    if (Number.isSafeInteger(value) || !Number.isInteger(value)) {
+        return false;
+    }
+    const m = NUMBER_PARTS.exec(literal);
+    if (m === null) {
+        return false;
+    }
+    const digits = trimTrailingZeros(m[2] + (m[3] ?? ""));
+    const exponent = Number(m[4] ?? "0") - (m[3] ?? "").length + ((m[2] + (m[3] ?? "")).length - digits.length);
+    if (digits.replace(/^0+/, "").length <= 15 || exponent < 0) {
+        // up to 15 significant digits the nearest double reads back as the same text (1e39 is the
+        // float it says); a fraction that rounds to an integer is ordinary floating-point rounding
+        return false;
+    }
+    const exact = BigInt(digits) * 10n ** BigInt(exponent);
+    return exact !== BigInt(Math.abs(value));
+}
 /**
  * Rewrite the numbers JSON.parse cannot read exactly, outside strings and in value positions only:
  * NaN / Infinity / -Infinity become sentinel strings (when `nonstandard` is true), an integer
  * literal that is not a safe integer becomes a string of its digits (or, with `exactSentinel`, a
- * sentinel string reviveExact() turns into an ExactInteger). A container stack tells a value
- * position (after `:`, `[`, or `,` inside an array) from a key position, so `{NaN: 1}` stays invalid.
+ * sentinel string the result's reviveExact turns into an ExactInteger). A container stack tells a
+ * value position (after `:`, `[`, or `,` inside an array) from a key position, so `{NaN: 1}` stays
+ * invalid. Literals with a fraction or an exponent that no double holds are listed, not rewritten.
  * @param text - the document text
  * @param options - which rewrites apply
  * @param options.nonstandard - rewrite NaN / Infinity / -Infinity (default true)
  * @param options.exactSentinel - quote big integers as sentinels instead of bare digits (default false)
- * @returns the rewritten text, the non-standard tokens seen and the integer literals quoted
+ * @returns the rewritten text, what was found and the revivers of this rewrite
+ * @category Plugin helpers
  */
 export function rewriteNumbers(text, options = {}) {
     const nonstandard = options.nonstandard ?? true;
     const exactSentinel = options.exactSentinel ?? false;
+    const sentinel = sentinelFor(text);
+    const exactPrefix = `${sentinel}exact:`;
     const parts = [];
     const tokens = new Set();
     const bigIntegers = [];
+    const inexact = [];
     const arrays = [];
     let expectValue = true;
     let copied = 0;
@@ -87,7 +186,7 @@ export function rewriteNumbers(text, options = {}) {
             if (token !== undefined) {
                 end = i + token[0].length;
                 tokens.add(token[0]);
-                replacement = JSON.stringify(`${SENTINEL}${token[0]}`);
+                replacement = JSON.stringify(`${sentinel}${token[0]}`);
             }
             else if (ch === "-" || (ch >= "0" && ch <= "9")) {
                 end = i + 1;
@@ -95,9 +194,14 @@ export function rewriteNumbers(text, options = {}) {
                     end++;
                 }
                 const literal = text.slice(i, end);
-                if (INTEGER_LITERAL.test(literal) && !Number.isSafeInteger(Number(literal))) {
-                    bigIntegers.push(literal);
-                    replacement = exactSentinel ? JSON.stringify(`${EXACT_SENTINEL}${literal}`) : `"${literal}"`;
+                if (INTEGER_LITERAL.test(literal)) {
+                    if (!Number.isSafeInteger(Number(literal))) {
+                        bigIntegers.push(literal);
+                        replacement = exactSentinel ? JSON.stringify(`${exactPrefix}${literal}`) : `"${literal}"`;
+                    }
+                }
+                else if (isInexactLiteral(literal)) {
+                    inexact.push(literal);
                 }
             }
             if (replacement !== null) {
@@ -110,23 +214,163 @@ export function rewriteNumbers(text, options = {}) {
         i++;
     }
     parts.push(text.slice(copied));
-    return { text: parts.join(""), tokens, bigIntegers };
+    const revive = (_key, value) => {
+        if (typeof value === "string" && value.startsWith(sentinel)) {
+            const found = NONSTANDARD_TOKENS.find(([word]) => word === value.slice(sentinel.length));
+            return found === undefined ? value : found[1];
+        }
+        return value;
+    };
+    const reviveExact = (_key, value) => typeof value === "string" && value.startsWith(exactPrefix)
+        ? new ExactInteger(value.slice(exactPrefix.length))
+        : value;
+    return { text: parts.join(""), tokens, bigIntegers, inexact, revive, reviveExact };
 }
+/** Keys of one object compared pairwise up to this count; a wider object switches to a Set. */
+const LINEAR_KEYS = 32;
 /**
- * The JSON.parse reviver that turns the non-standard sentinel strings of rewriteNumbers() back into
- * numbers.
- * @param _key - the member key (unused)
- * @param value - the parsed value
- * @returns the number for a sentinel string, the value otherwise
+ * The keys that occur twice in one object of a valid JSON text, which JSON.parse silently reduces
+ * to the last value (RFC 8259 section 4: names SHOULD be unique). One pass over the characters
+ * that jumps over strings; the keys of a small object are compared in place, without
+ * slicing (the parse itself costs about as much as this scan, so it allocates nothing per key).
+ * Keys are compared as written: `"\u0069d"` and `"id"` are not recognized as one key.
+ * @param text - a text JSON.parse accepted (or its rewrite)
+ * @returns every repetition in document order
+ * @category Plugin helpers
  */
-export function reviveNonstandard(_key, value) {
-    if (typeof value === "string" && value.startsWith(SENTINEL)) {
-        const found = NONSTANDARD_TOKENS.find(([word]) => word === value.slice(SENTINEL.length));
-        return found === undefined ? value : found[1];
+export function findDuplicateKeys(text) {
+    const found = [];
+    // per depth: the [start, end) of each key of the open object (reused), or -1 for an array
+    const spans = [];
+    const wide = [];
+    let depth = 0;
+    const n = text.length;
+    let at = 0;
+    while (at < n) {
+        const c = text.codePointAt(at);
+        if (c === 123 || c === 91) {
+            // { or [
+            openContainer(spans, wide, depth, c === 91);
+            depth++;
+        }
+        else if (c === 125 || c === 93) {
+            depth--;
+        }
+        else if (c === 34) {
+            const end = closingQuote(text, at + 1);
+            const keys = depth > 0 ? spans[depth - 1] : null;
+            // an array's span list starts with -1: its strings are values, never keys
+            const isObjectKey = keys !== null && keys[0] !== -1 && isKey(text, end + 1);
+            if (isObjectKey && isRepeated(text, at + 1, end, keys, wide, depth - 1)) {
+                found.push({ key: text.slice(at + 1, end), offset: at });
+            }
+            at = end;
+        }
+        at++;
     }
-    return value;
+    return found;
 }
-/** An integer literal beyond 2^53, kept as its exact digits (a CX id must never lose a digit). */
+/**
+ * Start the key list of a container just opened at a depth (reusing the list of an earlier one).
+ * @param spans - the key spans per depth
+ * @param wide - the key sets per depth, for wide objects
+ * @param depth - the container's depth
+ * @param isArray - whether it is an array, whose strings are never keys
+ */
+function openContainer(spans, wide, depth, isArray) {
+    if (spans.length === depth) {
+        spans.push([]);
+        wide.push(null);
+    }
+    spans[depth].length = 0;
+    if (isArray) {
+        spans[depth].push(-1);
+    }
+    wide[depth] = null;
+}
+/**
+ * Whether a key repeats one already seen in its object, remembering it otherwise.
+ * @param text - the text
+ * @param start - the key's first character
+ * @param end - the key's closing quote
+ * @param keys - the spans of the object's keys so far
+ * @param wide - the Set of each depth's keys once the object is wide
+ * @param level - the object's depth
+ * @returns true for a repetition
+ */
+function isRepeated(text, start, end, keys, wide, level) {
+    const set = wide[level];
+    if (set !== null) {
+        const key = text.slice(start, end);
+        return set.has(key) || (set.add(key), false);
+    }
+    const length = end - start;
+    for (let k = 0; k < keys.length; k += 2) {
+        if (keys[k + 1] - keys[k] === length && sameText(text, keys[k], start, length)) {
+            return true;
+        }
+    }
+    keys.push(start, end);
+    if (keys.length > 2 * LINEAR_KEYS) {
+        const all = new Set();
+        for (let k = 0; k < keys.length; k += 2) {
+            all.add(text.slice(keys[k], keys[k + 1]));
+        }
+        wide[level] = all;
+    }
+    return false;
+}
+/**
+ * Whether two ranges of one text hold the same characters.
+ * @param text - the text
+ * @param a - the first range's start
+ * @param b - the second range's start
+ * @param length - the ranges' length
+ * @returns true when equal
+ */
+function sameText(text, a, b, length) {
+    for (let i = 0; i < length; i++) {
+        if (text.codePointAt(a + i) !== text.codePointAt(b + i)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * The offset of the quote that closes a JSON string.
+ * @param text - the text
+ * @param from - the offset after the opening quote
+ * @returns the closing quote's offset (the text length when there is none)
+ */
+function closingQuote(text, from) {
+    for (let q = text.indexOf('"', from); q >= 0; q = text.indexOf('"', q + 1)) {
+        let backslashes = 0;
+        while (text.codePointAt(q - 1 - backslashes) === 92) {
+            backslashes++;
+        }
+        if (backslashes % 2 === 0) {
+            return q;
+        }
+    }
+    return text.length;
+}
+/**
+ * Whether the string that ends before an offset is an object key: a colon follows after whitespace.
+ * @param text - the text
+ * @param from - the offset after the closing quote
+ * @returns true for a key
+ */
+function isKey(text, from) {
+    let i = from;
+    while (i < text.length && isSpace(text.codePointAt(i))) {
+        i++;
+    }
+    return text.codePointAt(i) === 58;
+}
+/**
+ * An integer literal beyond 2^53, kept as its exact digits (a CX id must never lose a digit).
+ * @category Plugin helpers
+ */
 export class ExactInteger {
     /**
      * Wrap the digits of an integer literal.
@@ -143,22 +387,11 @@ export class ExactInteger {
         return Number(this.digits);
     }
 }
-/**
- * The JSON.parse reviver of an element whose big integers were rewritten as exact sentinels.
- * @param _key - the member key (unused)
- * @param value - the parsed value
- * @returns an ExactInteger for an exact sentinel, the value otherwise
- */
-function reviveExact(_key, value) {
-    if (typeof value === "string" && value.startsWith(EXACT_SENTINEL)) {
-        return new ExactInteger(value.slice(EXACT_SENTINEL.length));
-    }
-    return value;
-}
 /**
  * Parse one JSON value, keeping integer literals beyond 2^53 as ExactInteger.
  * @param text - the JSON text
  * @returns the value and whether it may hold an ExactInteger; SyntaxError when it is not JSON
+ * @category Plugin helpers
  */
 export function parseExact(text) {
     if (!MAYBE_UNSAFE_INTEGER.test(text)) {
@@ -168,7 +401,7 @@ export function parseExact(text) {
     if (scan.bigIntegers.length === 0) {
         return { value: JSON.parse(text), exact: false };
     }
-    return { value: JSON.parse(scan.text, reviveExact), exact: true };
+    return { value: JSON.parse(scan.text, scan.reviveExact), exact: true };
 }
 /**
  * A parsed value with every ExactInteger replaced by its nearest number, for metadata and for
@@ -176,6 +409,7 @@ export function parseExact(text) {
  * @param value - the value
  * @param onPrecision - called with the digits of each integer that lost precision
  * @returns the plain JSON value
+ * @category Plugin helpers
  */
 export function plainJson(value, onPrecision) {
     if (value instanceof ExactInteger) {
@@ -188,14 +422,208 @@ export function plainJson(value, onPrecision) {
     if (typeof value === "object" && value !== null) {
         const out = {};
         for (const [key, item] of Object.entries(value)) {
-            out[key] = plainJson(item, onPrecision);
+            setOwn(out, key, plainJson(item, onPrecision));
         }
         return out;
     }
     return value;
 }
+/**
+ * Set an own property, also for the key `__proto__` (which an assignment would turn into the
+ * object's prototype, losing the entry).
+ * @param target - the object
+ * @param key - the key
+ * @param value - the value
+ * @category Plugin helpers
+ */
+export function setOwn(target, key, value) {
+    if (key === "__proto__") {
+        Object.defineProperty(target, key, { value, enumerable: true, writable: true, configurable: true });
+    }
+    else {
+        target[key] = value;
+    }
+}
+/**
+ * Parse a text with the bare tokens NaN / Infinity / -Infinity that Python's json writes.
+ * @param text - the JSON text that JSON.parse refused
+ * @returns the value, whether it may hold an ExactInteger and the tokens seen; null when the
+ * tokens are not what made the text invalid
+ */
+function parseNonstandard(text) {
+    if (!/NaN|Infinity/.test(text)) {
+        return null;
+    }
+    const scan = rewriteNumbers(text, { nonstandard: true, exactSentinel: true });
+    if (scan.tokens.size === 0) {
+        return null;
+    }
+    try {
+        const value = JSON.parse(scan.text, (key, raw) => scan.reviveExact(key, scan.revive(key, raw)));
+        return { value, exact: scan.bigIntegers.length > 0, tokens: scan.tokens };
+    }
+    catch {
+        return null;
+    }
+}
+/** A lone surrogate code unit: a high one not followed by a low one, or a low one not after a high one. */
+/** The escapes of the surrogate range, as a message writes them. */
+const SURROGATE_ESCAPES = String.raw `\uD800-\uDFFF`;
+const LONE_SURROGATE = /[\ud800-\udbff](?![\udc00-\udfff])|(?<![\ud800-\udbff])[\udc00-\udfff]/g;
+/** Text that may hold a surrogate: an escaped one, or a raw one (string input). */
+const MAYBE_SURROGATE = /\\u[dD][89a-fA-F]|[\ud800-\udfff]/;
+/**
+ * Replace every lone surrogate of a parsed value's strings and keys with U+FFFD, in place.
+ * @param value - the parsed value
+ * @param fixed - counts the strings repaired and names the keys two repaired keys collapse into
+ * @param fixed.count - the count
+ * @param fixed.collisions - a key one object holds twice once repaired (the later value is kept)
+ * @returns the value (a string, or an object with a repaired key, is returned as a new value)
+ */
+function repairSurrogates(value, fixed) {
+    if (typeof value === "string") {
+        const repaired = value.replaceAll(LONE_SURROGATE, "\ufffd");
+        if (repaired !== value) {
+            fixed.count++;
+        }
+        return repaired;
+    }
+    if (Array.isArray(value)) {
+        for (let i = 0; i < value.length; i++) {
+            value[i] = repairSurrogates(value[i], fixed);
+        }
+        return value;
+    }
+    if (isRecord(value)) {
+        const keys = Object.keys(value);
+        const repairedKeys = keys.map((key) => key.replaceAll(LONE_SURROGATE, "\ufffd"));
+        const renamed = repairedKeys.some((key, i) => key !== keys[i]);
+        const out = renamed ? {} : value;
+        keys.forEach((key, i) => {
+            if (repairedKeys[i] !== key) {
+                fixed.count++;
+            }
+            if (renamed && Object.hasOwn(out, repairedKeys[i])) {
+                fixed.collisions.push(repairedKeys[i]);
+            }
+            setOwn(out, repairedKeys[i], repairSurrogates(value[key], fixed));
+        });
+        return out;
+    }
+    return value;
+}
+/**
+ * The number of keys of a parsed value, at every depth.
+ * @param value - the value
+ * @returns the count
+ */
+function keyCount(value) {
+    if (Array.isArray(value)) {
+        return value.reduce((n, item) => n + keyCount(item), 0);
+    }
+    if (isRecord(value)) {
+        return Object.keys(value).reduce((n, key) => n + 1 + keyCount(value[key]), 0);
+    }
+    return 0;
+}
+/**
+ * The first key an object of a JSON text holds twice (JSON.parse keeps the later value silently).
+ * @param text - valid JSON text
+ * @returns the key, or null
+ */
+function duplicateKey(text) {
+    const stack = [];
+    let i = 0;
+    while (i < text.length) {
+        const c = text[i];
+        if (c === "{") {
+            stack.push(new Set());
+        }
+        else if (c === "[") {
+            stack.push(null);
+        }
+        else if (c === "}" || c === "]") {
+            stack.pop();
+        }
+        else if (c === '"') {
+            const start = i;
+            i = stringEnd(text, i + 1);
+            const keys = stack.at(-1) ?? null;
+            if (keys !== null && text[skipSpace(text, i + 1)] === ":") {
+                const key = JSON.parse(text.slice(start, i + 1));
+                if (keys.has(key)) {
+                    return key;
+                }
+                keys.add(key);
+            }
+        }
+        i++;
+    }
+    return null;
+}
+/**
+ * The offset of the quote that ends a JSON string, skipping escaped characters.
+ * @param text - the text
+ * @param from - the offset after the opening quote
+ * @returns the closing quote's offset, or the text length (or one past it) when there is none
+ */
+function stringEnd(text, from) {
+    let i = from;
+    while (i < text.length && text[i] !== '"') {
+        i += text[i] === "\\" ? 2 : 1;
+    }
+    return i;
+}
+/**
+ * The index of the first character at or after `from` that is not JSON whitespace.
+ * @param text - the text
+ * @param from - the first index
+ * @returns the index (text.length at the end)
+ */
+function skipSpace(text, from) {
+    let i = from;
+    while (i < text.length && isSpace(text.codePointAt(i))) {
+        i++;
+    }
+    return i;
+}
+/** A key followed by its colon, for the cheap duplicate-key check. */
+const KEY_COLON = /"\s*:/g;
+/**
+ * The checks of a parsed element that JSON.parse cannot make, recorded in the report: lone
+ * surrogates (replaced with U+FFFD, E_BAD_VALUE) and a key held twice by one object
+ * (W_DUPLICATE_ATTRIBUTE; the later value is the one read, also for two keys that a repair makes one).
+ * @param text - the element text
+ * @param parsed - the parsed element
+ * @param line - its line
+ * @param report - the report
+ * @returns the value, repaired
+ */
+function checkParsed(text, parsed, line, report) {
+    let value = parsed;
+    if (MAYBE_SURROGATE.test(text)) {
+        const fixed = { count: 0, collisions: [] };
+        value = repairSurrogates(value, fixed);
+        for (const key of fixed.collisions) {
+            report.warnOnce("validation-error", DUPLICATE_ATTRIBUTE_CODE, `an object holds two keys that are the same key ${JSON.stringify(key)} once their lone surrogates are replaced with U+FFFD; the later value is read`, { line, element: key }, `${DUPLICATE_ATTRIBUTE_CODE}:json:${key}`);
+        }
+        if (fixed.count > 0) {
+            report.error("validation-error", BAD_VALUE_CODE, `${fixed.count} string${plural(fixed.count)} ${agree(fixed.count, "holds", "hold")} a lone surrogate (an unpaired ${SURROGATE_ESCAPES} escape); each is read with U+FFFD in its place`, { line });
+        }
+    }
+    if (typeof value === "object" && value !== null && (text.match(KEY_COLON)?.length ?? 0) > keyCount(value)) {
+        const key = duplicateKey(text);
+        if (key !== null) {
+            report.warnOnce("validation-error", DUPLICATE_ATTRIBUTE_CODE, `an object holds the key ${JSON.stringify(key)} twice; the later value is read`, { line, element: key }, `${DUPLICATE_ATTRIBUTE_CODE}:json:${key}`);
+        }
+    }
+    return value;
+}
 // ============================================================ the streaming aspect scanner
-/** A problem with the document's JSON; the importer turns it into a fatal E_SYNTAX or E_EMPTY_INPUT. */
+/**
+ * A problem with the document's JSON; the importer turns it into a fatal E_SYNTAX or E_EMPTY_INPUT.
+ * @category Plugin helpers
+ */
 export class JsonScanError extends Error {
     /**
      * Create the error.
@@ -260,6 +688,7 @@ class ChunkCursor {
             this.captureStart = 0;
         }
         this.linesBefore += countNewlines(this.buf, 0, this.buf.length);
+        const endsWithCr = this.buf.endsWith("\r");
         for (;;) {
             const next = await this.iterator.next();
             if (next.done === true) {
@@ -268,6 +697,10 @@ class ChunkCursor {
                 return false;
             }
             if (next.value.length > 0) {
+                if (endsWithCr && next.value.startsWith("\n")) {
+                    // a CR LF split across two chunks is one line break, counted with the CR
+                    this.linesBefore--;
+                }
                 this.buf = next.value;
                 this.pos = 0;
                 return true;
@@ -281,6 +714,14 @@ class ChunkCursor {
     line() {
         return this.linesBefore + countNewlines(this.buf, 0, Math.min(this.pos, this.buf.length));
     }
+    /**
+     * The text from the read position to the end of the current chunk, at most `length` characters.
+     * @param length - the most characters
+     * @returns the text
+     */
+    ahead(length) {
+        return this.buf.slice(this.pos, this.pos + length);
+    }
     /**
      * Skip whitespace and return the next character without consuming it.
      * @returns the character, or "" at the end of the input
@@ -412,7 +853,7 @@ class ChunkCursor {
     }
 }
 /**
- * The number of line feeds in a slice of a string.
+ * The number of line breaks in a slice of a string: LF, CR LF and a CR alone (old Mac files).
  * @param text - the string
  * @param from - the first index
  * @param to - one past the last index
@@ -425,6 +866,13 @@ function countNewlines(text, from, to) {
         count++;
         i = text.indexOf("\n", i + 1);
     }
+    i = text.indexOf("\r", from);
+    while (i >= 0 && i < to) {
+        if (text[i + 1] !== "\n") {
+            count++;
+        }
+        i = text.indexOf("\r", i + 1);
+    }
     return count;
 }
 /**
@@ -436,65 +884,125 @@ function messageOf(err) {
     return err instanceof Error ? err.message : String(err);
 }
 /**
- * Parse a captured value, turning a parse failure into a JsonScanError at its line.
+ * Parse a captured value, turning a parse failure into a JsonScanError at its line. With a report,
+ * the bare tokens NaN / Infinity / -Infinity are read as numbers (W_JSON_NONSTANDARD_NUMBER), and
+ * lone surrogates and repeated keys are recorded (checkParsed()).
  * @param text - the value text
  * @param line - the line the value starts on
+ * @param report - the report, or null to only parse
  * @returns the value and whether it may hold an ExactInteger
  */
-function parseAt(text, line) {
+function parseAt(text, line, report) {
+    let parsed;
     try {
-        return parseExact(text);
+        parsed = parseExact(text);
     }
     catch (err) {
-        throw new JsonScanError(`invalid JSON: ${messageOf(err)}`, line);
+        const recovered = report === null ? null : parseNonstandard(text);
+        if (recovered === null) {
+            throw new JsonScanError(`invalid JSON: ${messageOf(err)}`, line);
+        }
+        report?.warnOnce("coercion", JSON_NONSTANDARD_NUMBER_CODE, `the document uses the non-standard token${plural(recovered.tokens.size)} ${[...recovered.tokens].join(", ")}, which strict JSON does not allow; read as numbers`, { line });
+        parsed = recovered;
+    }
+    if (report !== null) {
+        parsed = { ...parsed, value: checkParsed(text, parsed.value, line, report) };
+    }
+    return parsed;
+}
+/**
+ * What a document that does not start with "[" looks like, for the syntax error: HTML or XML (an
+ * error page saved under the file's name), a ZIP archive, or nothing in particular.
+ * @param head - the first characters
+ * @returns a sentence to append, or ""
+ */
+function notJsonHint(head) {
+    if (head.startsWith("<")) {
+        return "; the input looks like HTML or XML (an error page saved as the file?), not JSON";
+    }
+    if (head.startsWith("PK\u0003\u0004")) {
+        return "; the input is a ZIP archive (a Cytoscape session .cys is read by the cys importer), not JSON";
     }
+    return "";
 }
 /**
  * Walk a CX document (CX1 or CX2): a top-level array of members, each normally a one-key object
  * `{"<aspect>": [elements]}`. The elements of such a block are parsed and yielded one at a time;
  * any other member is parsed whole and yielded as a "member". A document that is not an array is
- * yielded as one "root" event. Syntax errors throw JsonScanError.
+ * yielded as one "root" event (an object without reading it). Syntax errors throw JsonScanError.
  * @param chunks - the decoded text
+ * @param report - where NaN tokens, lone surrogates and repeated keys are recorded (parseAt()); null to only parse
  * @yields the events in document order
  * @returns nothing
  */
-export async function* scanAspects(chunks) {
+export async function* scanAspects(chunks, report = null) {
     const cur = new ChunkCursor(chunks);
     const first = await cur.peek();
     if (first === "") {
         throw new JsonScanError("the input is empty", 1, true);
     }
-    if (first !== "[") {
-        const line = cur.line();
-        cur.beginCapture();
-        await cur.skipValue();
-        const { value } = parseAt(cur.endCapture(), line);
-        if ((await cur.peek()) !== "") {
-            throw new JsonScanError("unexpected text after the document", cur.line());
-        }
-        yield { kind: "root", value, line };
+    const hint = notJsonHint(cur.ahead(16));
+    if (hint === "" && cur.ahead(8).includes(String.fromCodePoint(0))) {
+        throw new JsonScanError('the input holds NUL characters: UTF-16 without a byte order mark (pass the encoding option, such as "utf-16le"), or binary data; not JSON', cur.line());
+    }
+    if (first === "[") {
+        cur.pos++;
+        yield* members(cur, report);
         return;
     }
-    cur.pos++;
+    const line = cur.line();
+    if (first === "{") {
+        yield { kind: "root", value: undefined, object: true, line };
+        return;
+    }
+    yield { kind: "root", value: await scalarRoot(cur, line, hint), object: false, line };
+}
+/**
+ * Read a document that is neither an array nor an object: one value, and nothing after it.
+ * @param cur - the cursor at the value
+ * @param line - the value's line
+ * @param hint - what the input looks like when it is not JSON, for the error
+ * @returns the value
+ */
+async function scalarRoot(cur, line, hint) {
+    cur.beginCapture();
+    await cur.skipValue();
+    let value;
+    try {
+        ({ value } = parseAt(cur.endCapture(), line, null));
+    }
+    catch (err) {
+        if (err instanceof JsonScanError && hint !== "") {
+            throw new JsonScanError(`${err.message}${hint}`, err.line);
+        }
+        throw err;
+    }
+    if ((await cur.peek()) !== "") {
+        throw new JsonScanError("unexpected text after the document", cur.line());
+    }
+    return value;
+}
+/**
+ * Read the members of the top-level array, and check that nothing follows it.
+ * @param cur - the cursor after the opening bracket
+ * @param report - the report of parseAt(), or null
+ * @yields the members' events
+ * @returns nothing
+ */
+async function* members(cur, report) {
     let block = 0;
-    if ((await cur.peek()) === "]") {
+    let next = await cur.peek();
+    if (next === "]") {
         cur.pos++;
     }
-    else {
-        for (;;) {
-            yield* member(cur, block);
-            block++;
-            const next = await cur.peek();
-            if (next === ",") {
-                cur.pos++;
-                continue;
-            }
-            if (next === "]") {
-                cur.pos++;
-                break;
-            }
+    while (next !== "]") {
+        yield* member(cur, block, report);
+        block++;
+        next = await cur.peek();
+        if (next !== "," && next !== "]") {
             throw new JsonScanError(next === "" ? "the document ends before its closing bracket" : `expected "," or "]", found "${next}"`, cur.line());
         }
+        cur.pos++;
     }
     if ((await cur.peek()) !== "") {
         throw new JsonScanError("unexpected text after the closing bracket", cur.line());
@@ -504,151 +1012,247 @@ export async function* scanAspects(chunks) {
  * Read one member of the top-level array.
  * @param cur - the cursor at the member's first character
  * @param block - the member's position among the members
+ * @param report - the report of parseAt(), or null
  * @yields the member's events
  * @returns nothing
  */
-async function* member(cur, block) {
+async function* member(cur, block, report) {
     const c = await cur.peek();
     const line = cur.line();
     if (c === "" || c === "]" || c === ",") {
         throw new JsonScanError(c === "" ? "the document ends inside its array" : `unexpected "${c}"`, line);
     }
+    cur.beginCapture();
     if (c !== "{") {
-        cur.beginCapture();
         await cur.skipValue();
-        if (cur.deepest > MAX_ELEMENT_DEPTH) {
-            cur.dropCapture();
-            yield { kind: "deep", aspect: null, block, depth: cur.deepest, line };
-            return;
-        }
-        const parsed = parseAt(cur.endCapture(), line);
-        yield { kind: "member", block, value: parsed.value, exact: parsed.exact, line };
+        yield wholeMember(cur, block, line, report);
         return;
     }
-    cur.beginCapture();
     cur.pos++;
-    const k = await cur.peek();
-    if (k !== '"') {
+    if ((await cur.peek()) !== '"') {
         // `{}` or not JSON: parse the whole member so a syntax error is reported as such
         await cur.skipValue(1);
-        if (cur.deepest > MAX_ELEMENT_DEPTH) {
-            cur.dropCapture();
-            yield { kind: "deep", aspect: null, block, depth: cur.deepest, line };
-            return;
-        }
-        const parsed = parseAt(cur.endCapture(), line);
-        yield { kind: "member", block, value: parsed.value, exact: parsed.exact, line };
+        yield wholeMember(cur, block, line, report);
         return;
     }
-    // the outer capture keeps the member's text in case it is not a block; readString nests its own
+    // every array-valued key is a block whose elements stream, whatever the key order; any other
+    // value is kept as text, so a member without an array is parsed whole (a CX2 descriptor, a
+    // one-object aspect) and one with an array names its other keys (extraKeys), skipped
     const outer = cur.endCapture();
-    const keyLine = cur.line();
-    const aspect = await cur.readString();
+    const firstLine = cur.line();
+    const keys = { others: [], firstBlock: null, deep: 0 };
+    let next = ",";
+    let index = 0;
+    while (next === ",") {
+        const key = await readKey(cur);
+        yield* keyValue(cur, key, index, block, keys, report);
+        index++;
+        next = await cur.peek();
+        if (next !== "," && next !== "}") {
+            throw new JsonScanError(next === "" ? "the document ends inside a member" : `expected "," or "}" after the key "${key.name}"`, cur.line());
+        }
+        cur.pos++;
+    }
+    yield* memberEnd(keys, block, line, { outer, firstLine }, report);
+}
+/**
+ * The event of a member read whole (its capture already taken): the member, or "deep" when it
+ * nests too deep to parse.
+ * @param cur - the cursor after the member
+ * @param block - the member's position among the members
+ * @param line - the member's line
+ * @param report - the report of parseAt(), or null
+ * @returns the event
+ */
+function wholeMember(cur, block, line, report) {
+    if (cur.deepest > MAX_ELEMENT_DEPTH) {
+        cur.dropCapture();
+        return { kind: "deep", aspect: null, block, depth: cur.deepest, line };
+    }
+    const text = cur.endCapture();
+    const parsed = parseAt(text, line, report);
+    return { kind: "member", block, value: parsed.value, exact: parsed.exact, text, line };
+}
+/**
+ * Read a member's key and the colon after it.
+ * @param cur - the cursor at the key
+ * @returns the key and its line
+ */
+async function readKey(cur) {
+    if ((await cur.peek()) !== '"') {
+        throw new JsonScanError("expected a key", cur.line());
+    }
+    const line = cur.line();
+    const name = await cur.readString();
     if ((await cur.peek()) !== ":") {
-        throw new JsonScanError(`expected ":" after the key "${aspect}"`, cur.line());
+        throw new JsonScanError(`expected ":" after the key "${name}"`, cur.line());
     }
     cur.pos++;
-    const v = await cur.peek();
-    if (v !== "[") {
-        // not a block: read the rest of the object and parse the member whole
-        cur.beginCapture();
-        await cur.skipValue(1);
-        if (cur.deepest > MAX_ELEMENT_DEPTH) {
-            cur.dropCapture();
-            yield { kind: "deep", aspect, block, depth: cur.deepest, line };
-            return;
-        }
-        const rest = cur.endCapture();
-        const text = `${outer}${JSON.stringify(aspect)}:${rest}`;
-        const parsed = parseAt(text, keyLine);
-        yield { kind: "member", block, value: parsed.value, exact: parsed.exact, line };
+    return { name, line };
+}
+/**
+ * Read one key's value: an array is a block whose elements stream; any other value is kept as text
+ * (or, when it nests too deep to parse, only its depth).
+ * @param cur - the cursor at the value
+ * @param key - the key
+ * @param key.name - its name
+ * @param key.line - its line
+ * @param index - the key's position in the member
+ * @param block - the member's position among the members
+ * @param keys - what the member's keys held so far
+ * @param report - the report of parseAt(), or null
+ * @yields the block's events
+ * @returns nothing
+ */
+async function* keyValue(cur, key, index, block, keys, report) {
+    if ((await cur.peek()) === "[") {
+        cur.pos++;
+        yield { kind: "block", aspect: key.name, block, shared: index > 0, line: key.line };
+        keys.firstBlock ?? (keys.firstBlock = key.name);
+        yield* blockElements(cur, key.name, block, report);
         return;
     }
-    cur.pos++;
-    yield { kind: "block", aspect, block, line };
-    if ((await cur.peek()) === "]") {
-        cur.pos++;
+    cur.beginCapture();
+    await cur.skipValue();
+    // the member's own brace is one level more
+    if (cur.deepest + 1 > MAX_ELEMENT_DEPTH) {
+        // never parse (recursively) what no one reads
+        cur.dropCapture();
+        keys.deep = Math.max(keys.deep, cur.deepest + 1);
+        keys.others.push({ key: key.name, text: null, line: key.line });
     }
     else {
-        for (;;) {
-            const e = await cur.peek();
-            if (e === "") {
-                throw new JsonScanError(`the document ends inside the "${aspect}" block`, cur.line());
-            }
-            const elementLine = cur.line();
-            cur.beginCapture();
-            await cur.skipValue();
-            if (cur.deepest > MAX_ELEMENT_DEPTH) {
-                cur.dropCapture();
-                yield { kind: "deep", aspect, block, depth: cur.deepest, line: elementLine };
-            }
-            else {
-                const text = cur.endCapture();
-                const parsed = parseAt(text, elementLine);
-                yield {
-                    kind: "element",
-                    aspect,
-                    block,
-                    value: parsed.value,
-                    exact: parsed.exact,
-                    text,
-                    line: elementLine,
-                };
-            }
-            const next = await cur.peek();
-            if (next === ",") {
-                cur.pos++;
-                continue;
-            }
-            if (next === "]") {
-                cur.pos++;
-                break;
+        keys.others.push({ key: key.name, text: cur.endCapture(), line: key.line });
+    }
+}
+/**
+ * The events after a one-object member's keys: with a block, its other keys (checked, then named
+ * as extraKeys); without one, the member parsed whole from its kept text.
+ * @param keys - what the member's keys held
+ * @param block - the member's position among the members
+ * @param line - the member's line
+ * @param start - the member's opening text and the line after it
+ * @param start.outer - the text up to the first key
+ * @param start.firstLine - the line of the first key
+ * @param report - the report of parseAt(), or null
+ * @yields the events
+ * @returns nothing
+ */
+function* memberEnd(keys, block, line, start, report) {
+    const { others, firstBlock, deep } = keys;
+    if (firstBlock !== null) {
+        for (const other of others) {
+            if (other.text !== null) {
+                parseAt(other.text, other.line, null);
             }
-            throw new JsonScanError(next === ""
-                ? `the document ends inside the "${aspect}" block`
-                : `expected "," or "]" in the "${aspect}" block, found "${next}"`, cur.line());
         }
-    }
-    const end = await cur.peek();
-    if (end === "}") {
-        cur.pos++;
+        if (others.length > 0) {
+            yield {
+                kind: "extraKeys",
+                aspect: firstBlock,
+                block,
+                keys: others.map((o) => o.key),
+                line: others[0].line,
+            };
+        }
         return;
     }
-    if (end !== ",") {
-        throw new JsonScanError(end === "" ? "the document ends inside a member" : `expected "}" after the "${aspect}" block`, cur.line());
+    if (deep > 0) {
+        yield { kind: "deep", aspect: others[0].key, block, depth: deep, line };
+        return;
     }
-    // more keys: a malformed block; skip their values and name them
-    const keys = [];
-    const extraLine = cur.line();
-    while ((await cur.peek()) === ",") {
+    const members = others.map((o) => [JSON.stringify(o.key), o.text ?? ""].join(":"));
+    const text = `${start.outer}${members.join(",")}}`;
+    const parsed = parseAt(text, start.firstLine, report);
+    yield { kind: "member", block, value: parsed.value, exact: parsed.exact, text, line };
+}
+/**
+ * Read the elements of a block whose opening bracket was consumed, through its closing bracket.
+ * @param cur - the cursor after the opening bracket
+ * @param aspect - the block's aspect
+ * @param block - the member's position among the members
+ * @param report - the report of parseAt(), or null
+ * @yields an element (or deep) event per element
+ * @returns nothing
+ */
+async function* blockElements(cur, aspect, block, report) {
+    if ((await cur.peek()) === "]") {
         cur.pos++;
-        if ((await cur.peek()) !== '"') {
-            throw new JsonScanError("expected a key", cur.line());
-        }
-        keys.push(await cur.readString());
-        if ((await cur.peek()) !== ":") {
-            throw new JsonScanError('expected ":"', cur.line());
+        return;
+    }
+    for (;;) {
+        const e = await cur.peek();
+        if (e === "") {
+            throw new JsonScanError(`the document ends inside the "${aspect}" block`, cur.line());
         }
-        cur.pos++;
-        await cur.peek();
+        const elementLine = cur.line();
         cur.beginCapture();
         await cur.skipValue();
-        parseAt(cur.endCapture(), cur.line());
-    }
-    if ((await cur.peek()) !== "}") {
-        throw new JsonScanError('expected "}"', cur.line());
+        if (cur.deepest > MAX_ELEMENT_DEPTH) {
+            cur.dropCapture();
+            yield { kind: "deep", aspect, block, depth: cur.deepest, line: elementLine };
+        }
+        else {
+            const text = cur.endCapture();
+            const parsed = parseAt(text, elementLine, report);
+            yield {
+                kind: "element",
+                aspect,
+                block,
+                value: parsed.value,
+                exact: parsed.exact,
+                text,
+                line: elementLine,
+            };
+        }
+        const next = await cur.peek();
+        if (next === ",") {
+            cur.pos++;
+            continue;
+        }
+        if (next === "]") {
+            cur.pos++;
+            return;
+        }
+        throw new JsonScanError(next === ""
+            ? `the document ends inside the "${aspect}" block`
+            : `expected "," or "]" in the "${aspect}" block, found "${next}"`, cur.line());
     }
-    cur.pos++;
-    yield { kind: "extraKeys", aspect, block, keys, line: extraLine };
 }
 /**
  * Report an element or member the scanner refused for its depth (E_BAD_ASPECT_BLOCK; skipped).
  * @param report - the report
  * @param event - the "deep" event
+ * @category Plugin helpers
  */
 export function reportTooDeep(report, event) {
     report.error("parse-error", BAD_ASPECT_BLOCK_CODE, `${event.aspect === null ? "a member of the document" : `an element of "${event.aspect}"`} is nested ${event.depth} levels deep, more than the ${MAX_ELEMENT_DEPTH} a graph keeps; skipped`, { line: event.line, element: event.aspect });
 }
+/**
+ * The precision callback of plainJson() for an aspect kept verbatim in the metadata: W_PRECISION
+ * once, since the digits stored there are not the file's.
+ * @param report - the report
+ * @param where - where the aspect is kept (meta.extra.cx, ...)
+ * @returns the callback
+ * @category Plugin helpers
+ */
+export function keptPrecision(report, where) {
+    return (digits) => {
+        report.warnOnce("precision", PRECISION_CODE, `an aspect kept in ${where} holds ${digits}, beyond 2^53; it is kept as the nearest double`, { element: where }, `${PRECISION_CODE}:kept`);
+    };
+}
+/**
+ * Warn once (W_MULTI_ASPECT_FRAGMENT) about a block that shares its array member with another
+ * aspect (`{"nodes": [...], "edges": [...]}`); a block of its own needs nothing.
+ * @param report - the report
+ * @param event - the "block" event
+ * @category Plugin helpers
+ */
+export function reportSharedBlock(report, event) {
+    if (event.shared) {
+        report.warnOnce("coercion", MULTI_ASPECT_FRAGMENT_CODE, `the "${event.aspect}" aspect shares an array member with another aspect; each is read as its own fragment`, { line: event.line, element: event.aspect });
+    }
+}
 const DECIMAL_INTEGER_TEXT = /^-?(0|[1-9][0-9]*)$/;
 /**
  * Apply the CX id rule (design section 1.0.2) to a parsed value: a safe integer is the id; an
@@ -657,6 +1261,7 @@ const DECIMAL_INTEGER_TEXT = /^-?(0|[1-9][0-9]*)$/;
  * @param raw - the parsed value
  * @param inexactLiteral - whether the number was written as a non-integer literal (`5.0`, `1e3`)
  * @returns the id and how it was spelled
+ * @category Plugin helpers
  */
 export function cxId(raw, inexactLiteral = false) {
     if (raw instanceof ExactInteger) {
@@ -686,18 +1291,24 @@ function invalidCxId(raw, reason) {
         reason,
     });
 }
+/** A number literal at lastIndex (sticky). */
+const NUMBER_LITERAL = /-?\d[\d.eE+-]*/y;
 /**
  * Whether the element text writes a top-level key's number as a non-integer literal (`"id": 5.0`,
  * `"@id": 1e3`). A lexical check, so the parsed value (5) cannot tell. Only a key of the element
  * itself counts, not one nested in its `v` (where `s` and `id` are ordinary attribute names).
  * @param text - the element's JSON text
  * @param key - the key
+ * @param keyDepth - the nesting depth of the element's own keys: 1, or 2 for an element written as
+ * a member's single object (`{"nodes": {"@id": 1.0}}`)
  * @returns true when the literal holds a fraction or an exponent
+ * @category Plugin helpers
  */
-export function inexactLiteral(text, key) {
+export function inexactLiteral(text, key, keyDepth = 1) {
     const quoted = JSON.stringify(key);
     let depth = 0;
-    for (let i = 0; i < text.length; i++) {
+    let i = 0;
+    while (i < text.length) {
         const c = text[i];
         if (c === "{" || c === "[") {
             depth++;
@@ -707,22 +1318,33 @@ export function inexactLiteral(text, key) {
         }
         else if (c === '"') {
             const start = i;
-            for (i++; i < text.length && text[i] !== '"'; i++) {
-                if (text[i] === "\\") {
-                    i++;
-                }
-            }
+            i = stringEnd(text, i + 1);
             // the key itself (a string at depth 1 followed by a colon), not a value spelled like it
-            if (depth === 1 && text.startsWith(quoted, start) && /^\s*:/.test(text.slice(i + 1, i + 16))) {
-                const match = /^\s*:\s*(-?[0-9][0-9.eE+-]*)/.exec(text.slice(i + 1, i + 64));
-                return match !== null && /[.eE]/.test(match[1]);
+            const colon = skipSpace(text, i + 1);
+            if (depth === keyDepth && text.startsWith(quoted, start) && text[colon] === ":") {
+                return inexactNumberAt(text, skipSpace(text, colon + 1));
             }
         }
+        i++;
     }
     return false;
 }
+/**
+ * Whether a number literal at an offset holds a fraction or an exponent.
+ * @param text - the text
+ * @param at - the offset
+ * @returns true when it does; false for an integer or no number
+ */
+function inexactNumberAt(text, at) {
+    NUMBER_LITERAL.lastIndex = at;
+    const match = NUMBER_LITERAL.exec(text);
+    return match !== null && /[.eE]/.test(match[0]);
+}
 // ============================================================ Cytoscape positions (design section 1.0.2)
-/** The name of the position column of every Cytoscape-family importer. */
+/**
+ * The name of the position column of every Cytoscape-family importer.
+ * @category Plugin helpers
+ */
 export const POSITION_COLUMN = "position";
 /** The name of the stacking-order column (Cytoscape's NODE_Z_LOCATION). */
 const Z_COLUMN = "z";
@@ -731,6 +1353,7 @@ const Z_COLUMN = "z";
  * @param format - the importer's format name
  * @param sourceDims - 3 when z goes into the position (zAs "position")
  * @returns the declaration
+ * @category Plugin helpers
  */
 export function positionDecl(format, sourceDims = 2) {
     return {
@@ -748,6 +1371,7 @@ export function positionDecl(format, sourceDims = 2) {
  * The stacking-order column `z` (f64, origin namespace "cytoscape").
  * @param format - the importer's format name
  * @returns the declaration
+ * @category Plugin helpers
  */
 export function zDecl(format) {
     return {
@@ -758,11 +1382,39 @@ export function zDecl(format) {
         extra: { cytoscape: "z" },
     };
 }
+/**
+ * Whether a coordinate fits the f32 position column: finite once rounded to f32 (1e39 and the
+ * Infinity of a literal like 1e400 do not, nor does NaN).
+ * @param value - the coordinate
+ * @returns true when the column can hold it
+ * @category Plugin helpers
+ */
+export function fitsF32(value) {
+    return Number.isFinite(Math.fround(value));
+}
+/**
+ * The head of an input as text for a sniff: UTF-16 by its byte order mark, else UTF-8, never
+ * failing, without the BOM.
+ * @param head - the first bytes
+ * @returns the text
+ * @category Plugin helpers
+ */
+export function headText(head) {
+    let encoding = "utf-8";
+    if (head.byteLength >= 2 && head[0] === 0xff && head[1] === 0xfe) {
+        encoding = "utf-16le";
+    }
+    else if (head.byteLength >= 2 && head[0] === 0xfe && head[1] === 0xff) {
+        encoding = "utf-16be";
+    }
+    return new TextDecoder(encoding).decode(head).replace(/^\uFEFF/, "");
+}
 /**
  * Cytoscape's screen y (growing downward) as graph-io's y (growing upward), and back: a negation
  * that never yields -0.
  * @param y - the coordinate
  * @returns the flipped coordinate
+ * @category Plugin helpers
  */
 export function flipY(y) {
     return y === 0 ? 0 : -y;
@@ -775,6 +1427,7 @@ const STRUCTURE_ASPECTS = new Set(["metaData", "status", "numberVerification"]);
  * `metaData` or an aspect after the post-metadata or after `status` is W_ASPECT_ORDER; declared
  * element counts are compared with what was read (W_COUNT_MISMATCH); `status.success: false` is
  * fatal (E_STATUS_FAILED) and `success: true` with an error text a warning (W_STATUS_WARNING).
+ * @category Plugin helpers
  */
 export class CxStructure {
     /**
@@ -787,8 +1440,9 @@ export class CxStructure {
     /**
      * Create the checker.
      * @param report - the report
+     * @param canonical - the name an aspect named in metaData is counted under (default: itself)
      */
-    constructor(report) {
+    constructor(report, canonical = (name) => name) {
         /** Elements read per aspect name. */
         this.counts = new Map();
         /** Blocks read per aspect name. */
@@ -802,6 +1456,7 @@ export class CxStructure {
         /** The status element, when one was read. */
         this.status = undefined;
         this.report = report;
+        this.canonical = canonical;
     }
     /**
      * Record the start of a block (or a member holding one aspect).
@@ -844,15 +1499,38 @@ export class CxStructure {
     element(aspect, value, line) {
         this.counts.set(aspect, (this.counts.get(aspect) ?? 0) + 1);
         if (aspect === "metaData") {
-            if (isRecord(value) && typeof value.name === "string" && typeof value.elementCount === "number") {
-                this.declared.set(value.name, value.elementCount);
-            }
+            this.readCount(value, line);
             return;
         }
         if (aspect === "status") {
             this.readStatus(value, line);
         }
     }
+    /**
+     * Record the element count a metaData element declares; a count that is not an integer (text,
+     * a fraction) or that names no aspect is W_COUNT_MISMATCH and not checked.
+     * @param value - the metaData element
+     * @param line - its line
+     */
+    readCount(value, line) {
+        if (!isRecord(value) || value.elementCount === undefined || value.elementCount === null) {
+            return;
+        }
+        const raw = value.elementCount;
+        let count = null;
+        if (raw instanceof ExactInteger) {
+            count = Number(raw.digits);
+        }
+        else if (typeof raw === "number" && Number.isInteger(raw)) {
+            count = raw;
+        }
+        if (typeof value.name !== "string" || count === null) {
+            const shownCount = raw instanceof ExactInteger ? raw.digits : JSON.stringify(raw);
+            this.report.warning("validation-error", COUNT_MISMATCH_CODE, `a metaData element declares the elementCount ${shownCount} for the name ${JSON.stringify(value.name) ?? "undefined"}; not a count of a named aspect, not checked`, { line, element: "metaData" });
+            return;
+        }
+        this.declared.set(this.canonical(value.name), count);
+    }
     /**
      * Check a status element: success false is fatal, an error text with success true a warning.
      * @param value - the element
@@ -891,7 +1569,7 @@ export class CxStructure {
         for (const [name, declared] of this.declared) {
             const read = this.counts.get(name) ?? 0;
             if (read !== declared) {
-                this.report.warning("validation-error", COUNT_MISMATCH_CODE, `metaData declares ${declared} "${name}" element(s); ${read} were read`, { element: name });
+                this.report.warning("validation-error", COUNT_MISMATCH_CODE, `metaData declares ${declared} "${name}" element${plural(declared)}; ${read} ${agree(read, "was", "were")} read`, { element: name });
             }
         }
     }
@@ -900,6 +1578,7 @@ export class CxStructure {
  * Whether a value is a plain JSON object.
  * @param value - any value
  * @returns true for a non-null, non-array object
+ * @category Plugin helpers
  */
 export function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value) && !(value instanceof ExactInteger);
@@ -913,6 +1592,7 @@ export function isRecord(value) {
  * @param decl - the declaration
  * @param report - the report the rename is recorded in
  * @returns the handle
+ * @category Plugin helpers
  */
 export function declareFresh(sink, domain, decl, report) {
     const taken = (name) => (domain === "node" ? sink.nodeColumn(name) : sink.edgeColumn(name)) !== INVALID_INDEX;