@graphty/graph-io 0.3.18 → 0.3.20

package/dist/src/formats/cx2/importer.js

@@ -0,0 +1,1652 @@
+/**
+ * The CX2 importer (design/graph-io/cytoscape-and-obo/design.md section 1.3; the feature and error
+ * inventory is research-cx2.md): the JSON exchange format of NDEx, Cytoscape 3.10+ and Cytoscape
+ * Web. A CX2 document is one array: a descriptor (`CXVersion`), aspect blocks (`nodes`, `edges`,
+ * `attributeDeclarations`, `networkAttributes`, `nodeBypasses`, `visualProperties`, opaque
+ * aspects) and a final `status`.
+ *
+ * The document is read through the streaming scanner of common/json-elements.ts, so its text is
+ * never held as one string; the parsed aspect elements are collected and the graph is built at the
+ * end, which makes every aspect order the format allows (declarations after the nodes, edges
+ * before their nodes) read the same.
+ *
+ * Mapping: every edge is directed (CX2 has no undirected edge); node ids follow the CX id rule
+ * (design section 1.0.2); declared attributes become typed columns named by their full name, with
+ * the alias in `origin.id` and the declared default in `meta.default`; `name` is the label; node
+ * `x` / `y` become the position column with y flipped to y-up, `z` the `z` column; per-element
+ * bypasses become one column per visual property (origin namespace "cx2.bypass"); style rules
+ * (`visualProperties`, `visualEditorProperties`) and every opaque aspect are kept verbatim in
+ * `meta.extra.cx2.opaque` and are not applied (W_STYLES_NOT_IMPORTED, issue #706).
+ */
+import { GraphFormatError, INVALID_INDEX, } from "@graphty/graph-format";
+import { declareResolved, uniqueColumnName } from "../../common/attributes.js";
+import { ASPECT_ORDER_CODE, BAD_ASPECT_BLOCK_CODE, BAD_DEFAULT_CODE, BAD_VALUE_CODE, COLUMN_RENAMED_CODE, COUNT_MISMATCH_CODE, DANGLING_REFERENCE_CODE, DIRECTION_FORCED_CODE, DIRECTION_REFUSED_CODE, DUPLICATE_ATTRIBUTE_CODE, DUPLICATE_EDGE_ID_CODE, DUPLICATE_NODE_CODE, EMPTY_INPUT_CODE, ENCODING_FALLBACK_CODE, ID_MERGED_CODE, ID_TEXT_TYPE_CODE, INVALID_ENCODING_CODE, INVALID_UTF8_CODE, MISSING_ENDPOINT_CODE, MISSING_ID_CODE, OPTION_IGNORED_CODE, PRECISION_CODE, ROLE_TAKEN_CODE, SINK_OPTION_CODE, STATUS_FAILED_CODE, STATUS_WARNING_CODE, STYLES_NOT_IMPORTED_CODE, SYNTAX_CODE, TOO_LARGE_CODE, UNKNOWN_ATTR_TYPE_CODE, UNKNOWN_ELEMENT_CODE, UNKNOWN_ENCODING_CODE, } from "../../common/codes.js";
+import { DirectionResolver } from "../../common/direction.js";
+import { IdCoercer } from "../../common/ids.js";
+import { textChunks, throwIfAborted } from "../../common/input.js";
+import { cxId, CxStructure, declareFresh, ExactInteger, flipY, inexactLiteral, isRecord, JsonScanError, plainJson, positionDecl, reportTooDeep, scanAspects, zDecl, } from "../../common/json-elements.js";
+import { reportSinkOptions, reportUnusedOptions, resolveImportOptions, } from "../../common/options.js";
+import { ImportReportBuilder } from "../../common/report.js";
+import { weightFromValue } from "../../common/weights.js";
+/** The format name. */
+export const CX2_FORMAT = "cx2";
+/** The node attribute the exporter's `sanitizeIds: "mangle"` keeps an original id in. */
+export const ORIGINAL_ID_ATTRIBUTE = "graphty:originalId";
+/** The origin namespace of the per-element visual property columns. */
+export const BYPASS_NAMESPACE = "cx2.bypass";
+/**
+ * The issue codes the CX2 importer records (design section 1.3), by name: the codes shared with
+ * the other importers (src/common/codes.ts) and the CX2-specific ones. A key is the code without
+ * its severity and format prefixes.
+ */
+export const CX2_ISSUE = Object.freeze({
+    /** The input is empty (fatal). */
+    EMPTY_INPUT: EMPTY_INPUT_CODE,
+    /** The text is not JSON (fatal). */
+    SYNTAX: SYNTAX_CODE,
+    /** Invalid UTF-8 (fatal). */
+    INVALID_UTF8: INVALID_UTF8_CODE,
+    /** Invalid bytes in the encoding a BOM or the encoding option chose (fatal). */
+    INVALID_ENCODING: INVALID_ENCODING_CODE,
+    /** Bytes that are not UTF-8 were read as windows-1252. */
+    ENCODING_FALLBACK: ENCODING_FALLBACK_CODE,
+    /** An encoding the platform cannot decode was ignored. */
+    UNKNOWN_ENCODING: UNKNOWN_ENCODING_CODE,
+    /** The document is not an array or does not start with a descriptor holding CXVersion (fatal). */
+    NO_DESCRIPTOR: "E_CX2_NO_DESCRIPTOR",
+    /** CXVersion names a major version other than 2 (fatal); "1.x" says the file is CX1. */
+    VERSION: "E_CX2_VERSION",
+    /** CXVersion is a 2.x other than "2.0" (or not a string); the document is read. */
+    MINOR_VERSION: "W_CX2_MINOR_VERSION",
+    /** The document has no status block, or a malformed one. */
+    NO_STATUS: "E_CX2_NO_STATUS",
+    /** The producer marked the document as failed (fatal). */
+    STATUS_FAILED: STATUS_FAILED_CODE,
+    /** The producer marked the document as successful with an error text. */
+    STATUS_WARNING: STATUS_WARNING_CODE,
+    /** An aspect appears in several blocks although the descriptor does not declare fragments. */
+    UNDECLARED_FRAGMENTS: "W_CX2_UNDECLARED_FRAGMENTS",
+    /** An attribute declared twice with two different types; the first declaration wins. */
+    DECLARATION_CONFLICT: "E_CX2_DECLARATION_CONFLICT",
+    /** An attribute value whose name no declaration covers; its column is inferred. */
+    UNDECLARED_ATTRIBUTE: "W_CX2_UNDECLARED_ATTRIBUTE",
+    /** A node or edge attribute named `id`, which the specification reserves. */
+    RESERVED_KEY: "W_CX2_RESERVED_KEY",
+    /** An alias that is another attribute's name or another attribute's alias; the alias is ignored. */
+    ALIAS_CONFLICT: "E_CX2_ALIAS_CONFLICT",
+    /** A network attribute declaration with an alias or a default, which CX2 forbids; both ignored. */
+    NETWORK_DECLARATION: "W_CX2_NETWORK_DECLARATION",
+    /** An aspect that holds one element holds several; the first is read. */
+    EXTRA_ELEMENTS: "W_CX2_EXTRA_ELEMENTS",
+    /** Some nodes have coordinates and others none, or a node has x without y. */
+    PARTIAL_LAYOUT: "W_CX2_PARTIAL_LAYOUT",
+    /** A full attribute name used where its alias is declared; read as the same attribute. */
+    ALIAS_BYPASSED: "W_CX2_ALIAS_BYPASSED",
+    /** A CX1 cartesianLayout aspect next to node coordinates; kept, not applied. */
+    LEGACY_LAYOUT: "W_CX2_LEGACY_LAYOUT",
+    /** The file's style rules are not applied (issue #706). */
+    STYLES_NOT_IMPORTED: STYLES_NOT_IMPORTED_CODE,
+    /** A member of the top-level array that is not a one-key aspect block, or an element that is not an object. */
+    BAD_ASPECT_BLOCK: BAD_ASPECT_BLOCK_CODE,
+    /** An aspect out of its place (after the post-metadata or the status, a third metaData, late declarations). */
+    ASPECT_ORDER: ASPECT_ORDER_CODE,
+    /** A metaData element count disagrees with what was read. */
+    COUNT_MISMATCH: COUNT_MISMATCH_CODE,
+    /** A value that does not match its declared type; the cell is unset. */
+    BAD_VALUE: BAD_VALUE_CODE,
+    /** A declared default that does not match its type. */
+    BAD_DEFAULT: BAD_DEFAULT_CODE,
+    /** A declared type CX2 does not define; the column is inferred from the values. */
+    UNKNOWN_ATTR_TYPE: UNKNOWN_ATTR_TYPE_CODE,
+    /** A bypass or a layout entry naming no node or edge. */
+    DANGLING_REFERENCE: DANGLING_REFERENCE_CODE,
+    /** The same attribute twice on one element (its alias and its full name). */
+    DUPLICATE_ATTRIBUTE: DUPLICATE_ATTRIBUTE_CODE,
+    /** A node without an id. */
+    MISSING_ID: MISSING_ID_CODE,
+    /** An edge without s or t. */
+    MISSING_ENDPOINT: MISSING_ENDPOINT_CODE,
+    /** A node id declared twice; the second merges into the first. */
+    DUPLICATE_NODE: DUPLICATE_NODE_CODE,
+    /** An edge id declared twice; the second edge is skipped. */
+    DUPLICATE_EDGE_ID: DUPLICATE_EDGE_ID_CODE,
+    /** An id that is not an integer. */
+    INVALID_ID: "E_INVALID_ID",
+    /** An edge endpoint naming no node (addMissingNodes false, the default). */
+    UNKNOWN_NODE: "E_UNKNOWN_NODE",
+    /** A weight that is not a number. */
+    INVALID_WEIGHT: "E_INVALID_WEIGHT",
+    /** An id spelled as a string or a non-integer literal; read as the integer. */
+    ID_TEXT_TYPE: ID_TEXT_TYPE_CODE,
+    /** An integer beyond 2^53: an id kept as its digits, a value stored as the nearest f64. */
+    PRECISION: PRECISION_CODE,
+    /** Two id texts merged under `ids: "number"`. */
+    ID_MERGED: ID_MERGED_CODE,
+    /** An element key CX2 does not define. */
+    UNKNOWN_ELEMENT: UNKNOWN_ELEMENT_CODE,
+    /** A column renamed because its name was taken. */
+    COLUMN_RENAMED: COLUMN_RENAMED_CODE,
+    /** A column that lost its role because another column holds it. */
+    ROLE_TAKEN: ROLE_TAKEN_CODE,
+    /** The sink refused the direction. */
+    DIRECTION_REFUSED: DIRECTION_REFUSED_CODE,
+    /** Edges forced to the policy's direction. */
+    DIRECTION_FORCED: DIRECTION_FORCED_CODE,
+    /** A common option CX2 has no use for. */
+    OPTION_IGNORED: OPTION_IGNORED_CODE,
+    /** A builder option the caller's sink does not honour. */
+    SINK_OPTION: SINK_OPTION_CODE,
+    /** The input is beyond a size limit (fatal). */
+    TOO_LARGE: TOO_LARGE_CODE,
+});
+const USED_OPTIONS = new Set([
+    "ids",
+    "addMissingNodes",
+    "duplicateEdges",
+    "selfLoops",
+    "onMixedDirection",
+    "weightFrom",
+    "weightDtype",
+    "long",
+    "restoreMangledIds",
+    "errorLimit",
+    "signal",
+    "onProgress",
+]);
+/** CX2 has no undirected edge: defaultDirected never applies (reported W_OPTION_IGNORED). */
+const FORMAT_DEFAULTS = {
+    ids: "keep",
+    defaultDirected: true,
+    weightFrom: "weight",
+    addMissingNodes: false,
+};
+const ABORT_CHECK_INTERVAL = 64;
+/** The keys a node element defines. */
+const NODE_KEYS = new Set(["id", "x", "y", "z", "v"]);
+/** The keys an edge element defines. */
+const EDGE_KEYS = new Set(["id", "s", "t", "v"]);
+/** The aspects that hold one element. */
+const SINGLE_ELEMENT_ASPECTS = ["networkAttributes", "visualProperties", "visualEditorProperties"];
+/** The aspects whose content is a style rule (design section 2). */
+const STYLE_ASPECTS = [
+    "visualProperties",
+    "visualEditorProperties",
+    "cyVisualProperties",
+    "tableVisualProperties",
+    "cyTableVisualProperties",
+];
+/** The aspects the stream structure owns; never kept as opaque. */
+const STRUCTURE_ASPECTS = new Set(["metaData", "status"]);
+/** The type spellings CX2 defines, plus the Python spellings ndex2 writes. */
+const SCALARS = {
+    string: "string",
+    long: "long",
+    integer: "integer",
+    double: "double",
+    boolean: "boolean",
+    str: "string",
+    int: "integer",
+    bool: "boolean",
+    float: "double",
+};
+/**
+ * Resolve a declared type text.
+ * @param d - the `d` value
+ * @returns the type, or null when CX2 does not define it
+ */
+export function cx2Type(d) {
+    const list = d.startsWith("list_of_");
+    const scalar = SCALARS[list ? d.slice("list_of_".length) : d];
+    if (scalar === undefined) {
+        return null;
+    }
+    return { d: list ? `list_of_${scalar}` : scalar, scalar, list };
+}
+/**
+ * The column dtype of a scalar type.
+ * @param scalar - the type
+ * @param long - the importer's `long` option
+ * @returns the dtype
+ */
+function scalarDtype(scalar, long) {
+    switch (scalar) {
+        case "string":
+            return "string";
+        case "long":
+            return long === "string" ? "string" : "f64";
+        case "integer":
+            return "i32";
+        case "double":
+            return "f64";
+        case "boolean":
+            return "bool";
+        default: {
+            const name = scalar;
+            return name;
+        }
+    }
+}
+/** What convertScalar() returns for a value of the wrong type. */
+const BAD = Symbol("bad");
+const I32_MIN = -2147483648;
+const I32_MAX = 2147483647;
+/**
+ * Convert one JSON value (or list item) by a declared scalar type.
+ * @param value - the value (never null)
+ * @param scalar - the type
+ * @param long - the importer's `long` option
+ * @param onPrecision - called for a long beyond 2^53
+ * @returns the value to store, or BAD
+ */
+function convertScalar(value, scalar, long, onPrecision) {
+    switch (scalar) {
+        case "string":
+            return typeof value === "string" ? value : BAD;
+        case "boolean":
+            return typeof value === "boolean" ? value : BAD;
+        case "double":
+            if (value instanceof ExactInteger) {
+                return Number(value.digits);
+            }
+            return typeof value === "number" ? value : BAD;
+        case "integer":
+            return typeof value === "number" && Number.isInteger(value) && value >= I32_MIN && value <= I32_MAX
+                ? value
+                : BAD;
+        case "long":
+            if (value instanceof ExactInteger) {
+                if (long === "string") {
+                    return value.digits;
+                }
+                onPrecision(value.digits);
+                return Number(value.digits);
+            }
+            if (typeof value === "number" && Number.isInteger(value)) {
+                return long === "string" ? String(value) : value;
+            }
+            return BAD;
+        default:
+            return BAD;
+    }
+}
+/**
+ * Convert one attribute value by its declared type.
+ * @param value - the value (never null)
+ * @param type - the declared type
+ * @param long - the importer's `long` option
+ * @param onPrecision - called for a long beyond 2^53
+ * @returns the value to store, or BAD
+ */
+function convertValue(value, type, long, onPrecision) {
+    if (!type.list) {
+        return convertScalar(value, type.scalar, long, onPrecision);
+    }
+    if (!Array.isArray(value)) {
+        return BAD;
+    }
+    const out = [];
+    for (const item of value) {
+        const converted = item === null ? BAD : convertScalar(item, type.scalar, long, onPrecision);
+        if (converted === BAD) {
+            return BAD;
+        }
+        out.push(converted);
+    }
+    return out;
+}
+/**
+ * A short JSON rendering of a value for a message.
+ * @param value - the value
+ * @returns the text, at most 60 characters
+ */
+function shown(value) {
+    if (value instanceof ExactInteger) {
+        return value.digits;
+    }
+    let text;
+    try {
+        text = JSON.stringify(value) ?? String(value);
+    }
+    catch {
+        text = String(value);
+    }
+    return text.length > 60 ? `${text.slice(0, 57)}...` : text;
+}
+/**
+ * The inexact-literal bits of an element.
+ * @param text - the element's JSON text
+ * @param keys - the id keys to check, bit 1, 2, 4 in order
+ * @returns the bits
+ */
+function inexactBits(text, keys) {
+    if (!/[0-9][.eE]/.test(text)) {
+        return 0;
+    }
+    let bits = 0;
+    keys.forEach((key, i) => {
+        if (inexactLiteral(text, key)) {
+            bits |= 1 << i;
+        }
+    });
+    return bits;
+}
+/**
+ * Read the whole document through the streaming scanner, checking its structure.
+ * @param input - the input
+ * @param report - the report
+ * @param options - the resolved options
+ * @returns what was read
+ */
+async function readDocument(input, report, options) {
+    const structure = new CxStructure(report);
+    const doc = {
+        version: "",
+        hasFragments: false,
+        nodes: [],
+        edges: [],
+        declarations: [],
+        networkAttributes: [],
+        nodeBypasses: [],
+        edgeBypasses: [],
+        cartesianLayout: [],
+        opaque: new Map(),
+        structure,
+    };
+    let descriptor = false;
+    let elementsSeen = false;
+    let sinceCheck = 0;
+    const collect = (aspect, value, text, line, exact) => {
+        structure.element(aspect, value, line);
+        switch (aspect) {
+            case "nodes":
+                elementsSeen = true;
+                doc.nodes.push({ value, line, inexact: inexactBits(text, ["id"]) });
+                return;
+            case "edges":
+                elementsSeen = true;
+                doc.edges.push({ value, line, inexact: inexactBits(text, ["id", "s", "t"]) });
+                return;
+            case "attributeDeclarations":
+                if (elementsSeen) {
+                    report.warnOnce("validation-error", ASPECT_ORDER_CODE, "attributeDeclarations comes after the elements it types; the declarations are applied to them", { line, element: aspect }, `${ASPECT_ORDER_CODE}:declarations`);
+                }
+                doc.declarations.push({ value: plainJson(value), line, inexact: 0 });
+                return;
+            case "networkAttributes":
+                elementsSeen = true;
+                doc.networkAttributes.push({ value, line, inexact: 0 });
+                return;
+            case "nodeBypasses":
+                doc.nodeBypasses.push({ value, line, inexact: 0 });
+                return;
+            case "edgeBypasses":
+                doc.edgeBypasses.push({ value, line, inexact: 0 });
+                return;
+            case "cartesianLayout":
+                doc.cartesianLayout.push({ value, line, inexact: 0 });
+                return;
+            default:
+                if (STRUCTURE_ASPECTS.has(aspect)) {
+                    return;
+                }
+                if (!doc.opaque.has(aspect)) {
+                    doc.opaque.set(aspect, []);
+                }
+                doc.opaque.get(aspect)?.push(exact ? plainJson(value, () => undefined) : value);
+        }
+    };
+    try {
+        for await (const event of scanAspects(textChunks(input, report, options))) {
+            if (++sinceCheck >= ABORT_CHECK_INTERVAL) {
+                sinceCheck = 0;
+                throwIfAborted(options.signal);
+            }
+            switch (event.kind) {
+                case "root":
+                    report.fail(CX2_ISSUE.NO_DESCRIPTOR, `a CX2 document is a JSON array; found ${isRecord(event.value) ? "an object" : shown(event.value)}`, { line: event.line });
+                    break;
+                case "member":
+                    if (!descriptor) {
+                        readDescriptor(event.value, event.line, doc, report);
+                        descriptor = true;
+                        break;
+                    }
+                    memberAspect(event.value, event.line, structure, report, (aspect, value) => {
+                        collect(aspect, value, JSON.stringify(value) ?? "", event.line, event.exact);
+                    });
+                    break;
+                case "block":
+                    if (!descriptor) {
+                        report.fail(CX2_ISSUE.NO_DESCRIPTOR, `the document starts with a "${event.aspect}" block, not a descriptor with CXVersion${event.aspect === "numberVerification" || event.aspect === "metaData" ? "; this looks like CX version 1 (read it with the cx importer)" : ""}`, { line: event.line });
+                    }
+                    structure.block(event.aspect, event.line);
+                    break;
+                case "element":
+                    collect(event.aspect, event.value, event.text, event.line, event.exact);
+                    break;
+                case "deep":
+                    reportTooDeep(report, event);
+                    if (!descriptor) {
+                        readDescriptor(null, event.line, doc, report);
+                    }
+                    break;
+                case "extraKeys":
+                    report.error("parse-error", BAD_ASPECT_BLOCK_CODE, `the "${event.aspect}" block holds more keys (${event.keys.join(", ")}); an aspect block has one key, the others are skipped`, { line: event.line, element: event.aspect });
+                    break;
+                default:
+                    break;
+            }
+        }
+    }
+    catch (err) {
+        if (err instanceof JsonScanError) {
+            report.fail(err.empty ? EMPTY_INPUT_CODE : SYNTAX_CODE, err.message, { line: err.line });
+        }
+        throw err;
+    }
+    if (!descriptor) {
+        report.fail(CX2_ISSUE.NO_DESCRIPTOR, "the document is an empty array; a CX2 document starts with a descriptor");
+    }
+    return doc;
+}
+/**
+ * Check the descriptor, the first member of the array.
+ * @param value - the member
+ * @param line - its line
+ * @param doc - the document, which receives the version and the fragment flag
+ * @param report - the report
+ */
+function readDescriptor(value, line, doc, report) {
+    if (!isRecord(value) || !("CXVersion" in value)) {
+        const keys = isRecord(value) ? Object.keys(value) : [];
+        report.fail(CX2_ISSUE.NO_DESCRIPTOR, `the first member of the array is not a descriptor with CXVersion${keys.length > 0 ? ` (keys: ${keys.join(", ")})` : ""}`, { line });
+    }
+    const raw = value.CXVersion;
+    const text = typeof raw === "string" || typeof raw === "number" ? String(raw) : "";
+    const match = /^([0-9]+)(?:\.([0-9]+))?$/.exec(text);
+    const major = match === null ? NaN : Number(match[1]);
+    if (major === 1) {
+        report.fail(CX2_ISSUE.VERSION, `CXVersion ${shown(raw)} is CX version 1, a different document shape; read it with the cx importer`, { line, element: "CXVersion" });
+    }
+    if (major !== 2) {
+        report.fail(CX2_ISSUE.VERSION, `CXVersion ${shown(raw)} is not a CX2 version`, { line, element: "CXVersion" });
+    }
+    doc.version = text;
+    if (raw !== "2.0") {
+        report.warning("validation-error", CX2_ISSUE.MINOR_VERSION, `CXVersion ${shown(raw)} is not "2.0"; the document is read as CX2 2.0`, { line, element: "CXVersion" });
+    }
+    for (const key of Object.keys(value)) {
+        if (key === "hasFragments") {
+            if (typeof value.hasFragments === "boolean") {
+                doc.hasFragments = value.hasFragments;
+            }
+            else {
+                report.error("validation-error", BAD_VALUE_CODE, `hasFragments is ${shown(value.hasFragments)}, not a boolean; read as false`, { line, element: "hasFragments" });
+            }
+        }
+        else if (key !== "CXVersion") {
+            report.warning("validation-error", UNKNOWN_ELEMENT_CODE, `the descriptor key "${key}" is not defined`, {
+                line,
+                element: key,
+            });
+        }
+    }
+}
+/**
+ * Read a member that is not a streamed block: a one-key object holding an object is a
+ * one-element aspect (`{"ndexStatus": {...}}`); anything else is E_BAD_ASPECT_BLOCK.
+ * @param value - the member
+ * @param line - its line
+ * @param structure - the structure checker
+ * @param report - the report
+ * @param collect - receives the aspect name and its one element
+ */
+function memberAspect(value, line, structure, report, collect) {
+    const keys = isRecord(value) ? Object.keys(value) : [];
+    if (isRecord(value) && keys.length === 1 && isRecord(value[keys[0]])) {
+        structure.block(keys[0], line);
+        collect(keys[0], value[keys[0]]);
+        return;
+    }
+    report.error("parse-error", BAD_ASPECT_BLOCK_CODE, `a member of the document is ${keys.length > 1 ? `an object with ${keys.length} keys (${keys.join(", ")})` : shown(value)}, not a one-key aspect block; skipped`, { line, element: keys[0] ?? null });
+}
+/**
+ * The scalar kind of one value for inference.
+ * @param value - the value
+ * @returns a CX2 scalar, or null for anything else
+ */
+function scalarKind(value) {
+    switch (typeof value) {
+        case "boolean":
+            return "boolean";
+        case "string":
+            return "string";
+        case "number":
+            return Number.isInteger(value) && value >= I32_MIN && value <= I32_MAX ? "integer" : "double";
+        default:
+            return value instanceof ExactInteger ? "double" : null;
+    }
+}
+/**
+ * Widen two scalar kinds: integer and double give double; anything else that differs has no
+ * CX2 type.
+ * @param a - the kind so far
+ * @param b - a new kind
+ * @returns the widened kind
+ */
+function widenKind(a, b) {
+    if (a === undefined || a === b) {
+        return b;
+    }
+    if (a === null || b === null) {
+        return null;
+    }
+    return (a === "integer" && b === "double") || (a === "double" && b === "integer") ? "double" : null;
+}
+/**
+ * Observe one value of an undeclared attribute.
+ * @param seen - the state
+ * @param value - the value (never null)
+ */
+function observe(seen, value) {
+    const list = Array.isArray(value);
+    if (seen.list !== undefined && seen.list !== list) {
+        seen.kind = null;
+        return;
+    }
+    seen.list = list;
+    if (!list) {
+        seen.kind = widenKind(seen.kind, scalarKind(value));
+        return;
+    }
+    for (const item of value) {
+        seen.kind = widenKind(seen.kind, item === null || Array.isArray(item) ? null : scalarKind(item));
+    }
+}
+/**
+ * The CX2 type inference settles on.
+ * @param seen - the state
+ * @returns the type, or null for a json column
+ */
+function inferredType(seen) {
+    if (seen.kind === null) {
+        return null;
+    }
+    const scalar = seen.kind ?? "string";
+    return cx2Type(seen.list === true ? `list_of_${scalar}` : scalar);
+}
+/** The declarations of one table. */
+class DeclarationTable {
+    constructor() {
+        this.byName = new Map();
+        this.byAlias = new Map();
+    }
+    /**
+     * The declaration a key of an element's `v` names.
+     * @param key - the key
+     * @returns the declaration and whether the key was its alias, or null
+     */
+    resolve(key) {
+        const viaAlias = this.byAlias.get(key);
+        if (viaAlias !== undefined) {
+            return { decl: viaAlias, viaAlias: true };
+        }
+        const decl = this.byName.get(key);
+        return decl === undefined ? null : { decl, viaAlias: false };
+    }
+}
+/** The domain key of attributeDeclarations for each table. */
+const DECLARATION_KEYS = { nodes: "node", edges: "edge", networkAttributes: "network" };
+// ============================================================ the build
+/** Reads a collected document into a sink. */
+class Cx2Reader {
+    /**
+     * Create the reader.
+     * @param sink - the sink
+     * @param report - the report
+     * @param options - the resolved options
+     * @param zAs - where z goes
+     * @param doc - the collected document
+     */
+    constructor(sink, report, options, zAs, doc) {
+        this.decls = {
+            node: new DeclarationTable(),
+            edge: new DeclarationTable(),
+            network: new DeclarationTable(),
+            other: {},
+        };
+        /** CX node id -> sink node index. */
+        this.nodeRows = new Map();
+        /** CX node id -> the id the sink holds it under (differs when a mangled id is restored). */
+        this.sinkIds = new Map();
+        /** CX edge id -> sink edge index. */
+        this.edgeRows = new Map();
+        this.positionHandle = INVALID_INDEX;
+        this.zHandle = INVALID_INDEX;
+        this.edgeIdHandle = INVALID_INDEX;
+        /** The rows that have a position (a set: a duplicate node may carry coordinates twice). */
+        this.positioned = new Set();
+        this.sinceCheck = 0;
+        this.idType = "integer";
+        this.weighted = false;
+        this.dangling = new Map();
+        this.point = [0, 0, 0];
+        this.sink = sink;
+        this.report = report;
+        this.options = options;
+        this.zAs = zAs;
+        this.doc = doc;
+        this.direction = new DirectionResolver(sink, report, options.onMixedDirection);
+        this.coercer = new IdCoercer(options.ids);
+    }
+    /** Build the graph. */
+    build() {
+        const { doc, report } = this;
+        this.direction.setHeader(true);
+        this.readDeclarations();
+        this.declareColumns();
+        this.sink.reserve(doc.nodes.length, doc.edges.length);
+        for (const held of doc.nodes) {
+            this.readNode(held);
+        }
+        this.readLegacyLayout();
+        if (this.positioned.size > 0 && this.positioned.size < this.nodeRows.size) {
+            report.warnOnce("missing-value", CX2_ISSUE.PARTIAL_LAYOUT, `${this.nodeRows.size - this.positioned.size} of ${this.nodeRows.size} node(s) have no coordinates; their positions are unset`, { element: "nodes" });
+        }
+        for (const held of doc.edges) {
+            this.readEdge(held);
+        }
+        this.readNetworkAttributes();
+        this.readBypasses("node", doc.nodeBypasses);
+        this.readBypasses("edge", doc.edgeBypasses);
+        for (const [kind, count] of this.dangling) {
+            report.warning("validation-error", DANGLING_REFERENCE_CODE, `${count} ${kind} name(s) no element; ignored`, { element: kind });
+        }
+        this.checkAspects();
+        this.setMeta();
+    }
+    // ------------------------------------------------------------ declarations
+    /** Merge every attributeDeclarations element (fragments in order) into the tables. */
+    readDeclarations() {
+        const { report } = this;
+        for (const held of this.doc.declarations) {
+            if (!isRecord(held.value)) {
+                report.error("parse-error", BAD_ASPECT_BLOCK_CODE, "an attributeDeclarations element is not an object", {
+                    line: held.line,
+                    element: "attributeDeclarations",
+                });
+                continue;
+            }
+            for (const [key, table] of Object.entries(held.value)) {
+                const domain = DECLARATION_KEYS[key];
+                if (domain === undefined) {
+                    this.decls.other[key] = table;
+                    continue;
+                }
+                if (!isRecord(table)) {
+                    report.error("validation-error", BAD_VALUE_CODE, `the ${key} declarations are not an object; ignored`, { line: held.line, element: key });
+                    continue;
+                }
+                for (const [name, decl] of Object.entries(table)) {
+                    this.declare(domain, name, decl, held.line);
+                }
+            }
+        }
+        for (const domain of ["node", "edge"]) {
+            this.checkAliases(domain);
+        }
+        this.inferUndeclared("node", this.doc.nodes);
+        this.inferUndeclared("edge", this.doc.edges);
+    }
+    /**
+     * Type the attributes no declaration types (undeclared, or declared with a type CX2 does not
+     * define) from their values, so every attribute column is declared with its CX2 type.
+     * @param domain - node or edge
+     * @param elements - the elements
+     */
+    inferUndeclared(domain, elements) {
+        const table = this.decls[domain];
+        const seen = new Map();
+        for (const { value } of elements) {
+            if (!isRecord(value) || !isRecord(value.v)) {
+                continue;
+            }
+            for (const [key, raw] of Object.entries(value.v)) {
+                const resolved = table.resolve(key);
+                if ((resolved !== null && resolved.decl.type !== null) || raw === null || raw === undefined) {
+                    continue;
+                }
+                const name = resolved?.decl.name ?? key;
+                let state = seen.get(name);
+                if (state === undefined) {
+                    state = { kind: undefined, list: undefined };
+                    seen.set(name, state);
+                }
+                observe(state, raw);
+            }
+        }
+        for (const [name, state] of seen) {
+            const type = inferredType(state);
+            const decl = table.byName.get(name);
+            if (decl !== undefined) {
+                decl.type = type;
+                if (decl.hasDefault && type !== null) {
+                    // the default of a type CX2 does not define, converted now the values typed the column
+                    decl.defaultValue = this.convertDefault(name, decl.rawDefault, type, { element: name });
+                    decl.hasDefault = decl.defaultValue !== BAD;
+                }
+                continue;
+            }
+            table.byName.set(name, {
+                name,
+                type,
+                alias: null,
+                hasDefault: false,
+                defaultValue: undefined,
+                rawDefault: undefined,
+                handle: INVALID_INDEX,
+                undeclared: true,
+            });
+        }
+    }
+    /**
+     * Add one declaration to a table.
+     * @param domain - the table
+     * @param name - the attribute name
+     * @param raw - the declaration object
+     * @param line - its line
+     */
+    declare(domain, name, raw, line) {
+        const { report } = this;
+        const table = this.decls[domain];
+        const where = { line, element: name };
+        if (!isRecord(raw)) {
+            report.error("validation-error", BAD_VALUE_CODE, `the declaration of "${name}" is not an object; ignored`, where);
+            return;
+        }
+        let type;
+        if (raw.d === undefined) {
+            type = cx2Type("string");
+            report.warning("unsupported", UNKNOWN_ATTR_TYPE_CODE, `the declaration of "${name}" has no type; read as string (the Java reader's rule)`, where);
+        }
+        else {
+            type = typeof raw.d === "string" ? cx2Type(raw.d) : null;
+            if (type === null) {
+                report.warning("unsupported", UNKNOWN_ATTR_TYPE_CODE, `the type ${shown(raw.d)} of "${name}" is not a CX2 type; the column is inferred from its values`, where);
+            }
+        }
+        const existing = table.byName.get(name);
+        if (existing !== undefined) {
+            if (existing.type?.d !== type?.d) {
+                report.error("validation-error", CX2_ISSUE.DECLARATION_CONFLICT, `"${name}" is declared ${existing.type?.d ?? "untyped"} and again ${type?.d ?? "untyped"}; the first declaration wins`, where);
+            }
+            return;
+        }
+        let alias = typeof raw.a === "string" ? raw.a : null;
+        let hasDefault = raw.v !== undefined && raw.v !== null;
+        if (domain === "network" && (raw.a !== undefined || raw.v !== undefined)) {
+            report.warning("validation-error", CX2_ISSUE.NETWORK_DECLARATION, `the network attribute "${name}" declares an alias or a default, which CX2 forbids; ignored`, where);
+            alias = null;
+            hasDefault = false;
+        }
+        let defaultValue = undefined;
+        if (hasDefault && type !== null) {
+            defaultValue = this.convertDefault(name, raw.v, type, where);
+            hasDefault = defaultValue !== BAD;
+        }
+        table.byName.set(name, {
+            name,
+            type,
+            alias,
+            hasDefault,
+            defaultValue,
+            rawDefault: hasDefault && type === null ? plainJson(raw.v) : undefined,
+            handle: INVALID_INDEX,
+            undeclared: false,
+        });
+    }
+    /**
+     * Convert a declared default; a numeric string for a numeric type (the specification's own
+     * `"v": "0.0"`) is coerced, anything else that does not match drops the default.
+     * @param name - the attribute
+     * @param value - the default
+     * @param type - its type
+     * @param where - the location
+     * @param where.line - the line
+     * @param where.element - the attribute
+     * @returns the default, or BAD when dropped
+     */
+    convertDefault(name, value, type, where) {
+        const converted = convertValue(value, type, this.options.long, () => undefined);
+        if (converted !== BAD) {
+            return converted;
+        }
+        const numeric = type.scalar === "double" || type.scalar === "integer" || type.scalar === "long";
+        if (!type.list &&
+            numeric &&
+            typeof value === "string" &&
+            value.trim() !== "" &&
+            Number.isFinite(Number(value))) {
+            const coerced = convertValue(Number(value), type, this.options.long, () => undefined);
+            if (coerced !== BAD) {
+                this.report.warning("validation-error", BAD_DEFAULT_CODE, `the default ${shown(value)} of "${name}" is a string, not a ${type.d}; read as ${shown(coerced)}`, where);
+                return coerced;
+            }
+        }
+        this.report.warning("validation-error", BAD_DEFAULT_CODE, `the default ${shown(value)} of "${name}" is not a ${type.d}; the column has no default`, where);
+        return BAD;
+    }
+    /**
+     * Check the aliases of a table in declaration order: an alias that is another attribute's
+     * name or another attribute's alias is E_CX2_ALIAS_CONFLICT and ignored.
+     * @param domain - the table
+     */
+    checkAliases(domain) {
+        const table = this.decls[domain];
+        for (const decl of table.byName.values()) {
+            const { alias } = decl;
+            if (alias === null || alias === decl.name) {
+                if (alias !== null) {
+                    table.byAlias.set(alias, decl);
+                }
+                continue;
+            }
+            const other = table.byName.get(alias) ?? table.byAlias.get(alias);
+            if (other !== undefined) {
+                this.report.error("validation-error", CX2_ISSUE.ALIAS_CONFLICT, `the alias "${alias}" of the ${domain} attribute "${decl.name}" is also ${other.name === alias ? "an attribute's name" : `the alias of "${other.name}"`}; the alias is ignored`, { element: decl.name });
+                decl.alias = null;
+                continue;
+            }
+            table.byAlias.set(alias, decl);
+        }
+    }
+    /** Declare the declared node and edge columns. */
+    declareColumns() {
+        const restore = this.options.restoreMangledIds;
+        for (const domain of ["node", "edge"]) {
+            for (const decl of this.decls[domain].byName.values()) {
+                if (domain === "node" && restore && decl.name === ORIGINAL_ID_ATTRIBUTE) {
+                    continue;
+                }
+                if (domain === "edge" && decl.name === this.options.weightFrom) {
+                    continue;
+                }
+                const column = decl.type === null
+                    ? {
+                        name: decl.name,
+                        dtype: "json",
+                        nullable: true,
+                        origin: { format: CX2_FORMAT, id: decl.alias },
+                    }
+                    : {
+                        ...this.columnDecl(decl.type),
+                        name: decl.name,
+                        origin: { format: CX2_FORMAT, id: decl.alias, type: decl.type.d },
+                    };
+                if (decl.hasDefault) {
+                    // a type nothing settled (no values) keeps its default as written, in the json column
+                    column.default = decl.type === null ? decl.rawDefault : decl.defaultValue;
+                }
+                if (domain === "node" && decl.name === "name") {
+                    column.role = "label";
+                }
+                decl.handle = declareResolved(this.sink, domain, column, this.report).handle;
+            }
+        }
+    }
+    /**
+     * The edge id column, declared with the first edge.
+     * @returns the handle
+     */
+    edgeIdColumn() {
+        if (this.edgeIdHandle === INVALID_INDEX) {
+            const taken = (name) => this.sink.edgeColumn(name) !== INVALID_INDEX;
+            this.edgeIdHandle = declareResolved(this.sink, "edge", { name: uniqueColumnName("id", "cx2", taken), dtype: "f64", role: "id", nullable: true }, this.report).handle;
+        }
+        return this.edgeIdHandle;
+    }
+    /**
+     * The dtype part of a declared column.
+     * @param type - the CX2 type
+     * @returns the dtype and item dtype
+     */
+    columnDecl(type) {
+        const scalar = scalarDtype(type.scalar, this.options.long);
+        return type.list
+            ? { name: "", dtype: "list", itemDtype: scalar, nullable: true }
+            : { name: "", dtype: scalar, nullable: true };
+    }
+    // ------------------------------------------------------------ ids
+    /**
+     * The id of an element, by the CX id rule and the `ids` option.
+     * @param raw - the parsed id
+     * @param inexact - whether the literal was not a plain integer
+     * @param element - the element name for issues
+     * @param edgeId - whether this is an edge's own id (stored in the f64 id column, not kept as digits)
+     * @returns the id, or null when it was reported
+     */
+    idOf(raw, inexact, element, edgeId = false) {
+        let id;
+        try {
+            const parsed = cxId(raw, inexact);
+            if (parsed.note === "text") {
+                this.report.warnOnce("coercion", ID_TEXT_TYPE_CODE, `${element}: the id ${shown(raw)} is not written as an integer; read as ${String(parsed.id)}`, { element });
+            }
+            else if (parsed.note === "precision" && edgeId) {
+                // the edge is told apart by its digits, but the id column is f64
+                this.report.warnOnce("precision", PRECISION_CODE, `${element}: the edge id ${String(parsed.id)} is beyond 2^53; the id column holds the nearest double`, { element }, `${PRECISION_CODE}:edge`);
+            }
+            else if (parsed.note === "precision") {
+                this.idType = "mixed";
+                this.report.warnOnce("precision", PRECISION_CODE, `${element}: the id ${String(parsed.id)} is beyond 2^53; kept as its digits (a string id)`, { element });
+            }
+            id = this.options.ids === "keep" ? parsed.id : this.coercer.value(parsed.id);
+        }
+        catch (err) {
+            this.report.recordError(err, { element });
+            return null;
+        }
+        return id;
+    }
+    /**
+     * Check the cancellation signal every ABORT_CHECK_INTERVAL elements.
+     */
+    checkAbort() {
+        if (++this.sinceCheck >= ABORT_CHECK_INTERVAL) {
+            this.sinceCheck = 0;
+            throwIfAborted(this.options.signal);
+        }
+    }
+    /**
+     * Report the keys of an element CX2 does not define, once per key.
+     * @param record - the element
+     * @param known - the keys it defines
+     * @param what - nodes or edges
+     * @param line - its line
+     */
+    unknownKeys(record, known, what, line) {
+        for (const key of Object.keys(record)) {
+            if (!known.has(key)) {
+                this.report.warnOnce("unsupported", UNKNOWN_ELEMENT_CODE, `the ${what} key "${key}" is not defined by CX2; its values are not read`, { line, element: key }, `${UNKNOWN_ELEMENT_CODE}:${what}:${key}`);
+            }
+        }
+    }
+    // ------------------------------------------------------------ nodes
+    /**
+     * Read one node element.
+     * @param held - the element
+     */
+    readNode(held) {
+        this.checkAbort();
+        const { report, sink } = this;
+        const { value, line } = held;
+        if (!isRecord(value)) {
+            report.error("parse-error", BAD_ASPECT_BLOCK_CODE, `a nodes element is ${shown(value)}, not an object`, {
+                line,
+                element: "nodes",
+            });
+            report.counts.skippedNodes++;
+            return;
+        }
+        this.unknownKeys(value, NODE_KEYS, "node", line);
+        if (value.id === undefined || value.id === null) {
+            report.error("missing-value", MISSING_ID_CODE, "a node has no id", { line, element: "nodes" });
+            report.counts.skippedNodes++;
+            return;
+        }
+        const element = `node ${shown(value.id)}`;
+        const cx = this.idOf(value.id, (held.inexact & 1) !== 0, element);
+        if (cx === null) {
+            report.counts.skippedNodes++;
+            return;
+        }
+        const attrs = isRecord(value.v) ? value.v : null;
+        if (value.v !== undefined && value.v !== null && attrs === null) {
+            report.error("validation-error", BAD_VALUE_CODE, `${element}: v is ${shown(value.v)}, not an object`, {
+                line,
+                element,
+            });
+        }
+        let row = this.nodeRows.get(cx);
+        if (row !== undefined) {
+            report.warning("merged", DUPLICATE_NODE_CODE, `${element} is declared more than once; its attributes are merged (the later values win)`, { line, element });
+        }
+        else {
+            const original = this.originalIdOf(attrs);
+            this.idTypeOf(original ?? cx);
+            try {
+                row = sink.addNode(original ?? cx);
+            }
+            catch (err) {
+                report.recordError(err, { line, element });
+                report.counts.skippedNodes++;
+                return;
+            }
+            this.nodeRows.set(cx, row);
+            this.sinkIds.set(cx, original ?? cx);
+            report.counts.nodes++;
+        }
+        this.readCoordinates(value, row, element, line);
+        if (attrs !== null) {
+            this.writeAttributes("node", row, attrs, element, line);
+        }
+    }
+    /**
+     * The original id the exporter's `sanitizeIds: "mangle"` kept, when it is to be restored.
+     * @param attrs - the node's v
+     * @returns the original id, or null
+     */
+    originalIdOf(attrs) {
+        if (attrs === null || !this.options.restoreMangledIds) {
+            return null;
+        }
+        const alias = this.decls.node.byName.get(ORIGINAL_ID_ATTRIBUTE)?.alias ?? null;
+        const raw = attrs[ORIGINAL_ID_ATTRIBUTE] ?? (alias === null ? undefined : attrs[alias]);
+        return typeof raw === "string" ? raw : null;
+    }
+    /**
+     * Track the idType of the metadata.
+     * @param id - a node id
+     */
+    idTypeOf(id) {
+        if (typeof id === "string" && this.idType === "integer") {
+            this.idType = "mixed";
+        }
+    }
+    /**
+     * Read a node's x / y / z.
+     * @param value - the node element
+     * @param row - the node
+     * @param element - the element name
+     * @param line - its line
+     */
+    readCoordinates(value, row, element, line) {
+        const coordinate = (key) => {
+            const raw = value[key];
+            if (raw === undefined || raw === null) {
+                return null;
+            }
+            if (typeof raw === "number") {
+                return raw;
+            }
+            this.report.error("validation-error", BAD_VALUE_CODE, `${element}: ${key} is ${shown(raw)}, not a number`, {
+                line,
+                element,
+            });
+            return null;
+        };
+        const x = coordinate("x");
+        const y = coordinate("y");
+        const z = coordinate("z");
+        if ((x === null) !== (y === null)) {
+            this.report.warnOnce("missing-value", CX2_ISSUE.PARTIAL_LAYOUT, `${element} has ${x === null ? "y without x" : "x without y"}; its coordinates are dropped`, { line, element }, `${CX2_ISSUE.PARTIAL_LAYOUT}:half`);
+        }
+        if (z !== null && x === null && y === null) {
+            // the specification requires x and y with z
+            this.report.warnOnce("missing-value", CX2_ISSUE.PARTIAL_LAYOUT, `${element} has z without x and y; ${this.zAs === "column" ? "z is kept in the z column" : "with no position, z is dropped"}`, { line, element }, `${CX2_ISSUE.PARTIAL_LAYOUT}:z`);
+        }
+        if (x !== null && y !== null) {
+            this.setPosition(row, x, y, z);
+        }
+        if (z !== null && this.zAs === "column") {
+            if (this.zHandle === INVALID_INDEX) {
+                this.zHandle = declareResolved(this.sink, "node", zDecl(CX2_FORMAT), this.report).handle;
+            }
+            this.sink.setNodeValue(this.zHandle, row, z);
+        }
+    }
+    /**
+     * Write a node's position, y flipped to y-up.
+     * @param row - the node
+     * @param x - screen x
+     * @param y - screen y
+     * @param z - z, used only under zAs "position"
+     */
+    setPosition(row, x, y, z) {
+        if (this.positionHandle === INVALID_INDEX) {
+            this.positionHandle = declareResolved(this.sink, "node", positionDecl(CX2_FORMAT, this.zAs === "position" ? 3 : 2), this.report).handle;
+        }
+        this.point[0] = x;
+        this.point[1] = flipY(y);
+        this.point[2] = this.zAs === "position" && z !== null ? z : 0;
+        this.sink.setNodeValue(this.positionHandle, row, this.point);
+        this.positioned.add(row);
+    }
+    /** Apply a CX1 cartesianLayout aspect when no node carries coordinates; keep and warn otherwise. */
+    readLegacyLayout() {
+        const { cartesianLayout } = this.doc;
+        if (cartesianLayout.length === 0) {
+            return;
+        }
+        if (this.positioned.size > 0) {
+            this.doc.opaque.set("cartesianLayout", cartesianLayout.map((h) => plainJson(h.value)));
+            this.report.warning("unsupported", CX2_ISSUE.LEGACY_LAYOUT, `a CX1 cartesianLayout aspect (${cartesianLayout.length} element(s)) next to node coordinates; the node coordinates are used, the aspect is kept in meta.extra.cx2`, { element: "cartesianLayout" });
+            return;
+        }
+        for (const held of cartesianLayout) {
+            const entry = held.value;
+            if (!isRecord(entry) || typeof entry.x !== "number" || typeof entry.y !== "number") {
+                this.report.error("validation-error", BAD_VALUE_CODE, "a cartesianLayout element has no numeric x and y; skipped", { line: held.line, element: "cartesianLayout" });
+                continue;
+            }
+            const row = this.rowOf(this.nodeRows, entry.node);
+            if (row === undefined) {
+                this.dangle("cartesianLayout entry");
+                continue;
+            }
+            const z = typeof entry.z === "number" ? entry.z : null;
+            this.setPosition(row, entry.x, entry.y, z);
+            if (z !== null && this.zAs === "column") {
+                if (this.zHandle === INVALID_INDEX) {
+                    this.zHandle = declareResolved(this.sink, "node", zDecl(CX2_FORMAT), this.report).handle;
+                }
+                this.sink.setNodeValue(this.zHandle, row, z);
+            }
+        }
+    }
+    /**
+     * The sink row of a referenced id.
+     * @param rows - the id map
+     * @param raw - the parsed reference
+     * @returns the row, or undefined
+     */
+    rowOf(rows, raw) {
+        try {
+            const { id } = cxId(raw);
+            return rows.get(this.options.ids === "keep" ? id : this.coercer.value(id));
+        }
+        catch {
+            return undefined;
+        }
+    }
+    /**
+     * Count a reference that names nothing.
+     * @param kind - what referred
+     */
+    dangle(kind) {
+        this.dangling.set(kind, (this.dangling.get(kind) ?? 0) + 1);
+    }
+    // ------------------------------------------------------------ attributes
+    /**
+     * Write the attributes of an element's v.
+     * @param domain - node or edge
+     * @param row - the row
+     * @param attrs - the v object
+     * @param element - the element name
+     * @param line - its line
+     */
+    writeAttributes(domain, row, attrs, element, line) {
+        const { report } = this;
+        const table = this.decls[domain];
+        for (const key of Object.keys(attrs)) {
+            const value = attrs[key];
+            const resolved = table.resolve(key);
+            const name = resolved?.decl.name ?? key;
+            if (domain === "node" && this.options.restoreMangledIds && name === ORIGINAL_ID_ATTRIBUTE) {
+                continue;
+            }
+            if (domain === "edge" && name === this.options.weightFrom) {
+                continue;
+            }
+            if (key === "id") {
+                report.warnOnce("validation-error", CX2_ISSUE.RESERVED_KEY, `${element}: the attribute name "id" is reserved in v; read as an ordinary attribute`, { line, element }, `${CX2_ISSUE.RESERVED_KEY}:${domain}`);
+            }
+            if (resolved !== null &&
+                !resolved.viaAlias &&
+                resolved.decl.alias !== null &&
+                resolved.decl.alias !== key) {
+                if (resolved.decl.alias in attrs) {
+                    report.warning("validation-error", DUPLICATE_ATTRIBUTE_CODE, `${element}: "${name}" is given under its alias and its full name; the alias wins`, { line, element });
+                    continue;
+                }
+                report.warnOnce("coercion", CX2_ISSUE.ALIAS_BYPASSED, `${element}: the full name "${name}" is used although its alias "${resolved.decl.alias}" is declared; read as the same attribute`, { line, element }, `${CX2_ISSUE.ALIAS_BYPASSED}:${domain}:${name}`);
+            }
+            if (value === null || value === undefined) {
+                continue;
+            }
+            if (resolved === null) {
+                continue;
+            }
+            const { decl } = resolved;
+            if (decl.undeclared) {
+                report.warnOnce("validation-error", CX2_ISSUE.UNDECLARED_ATTRIBUTE, `the ${domain} attribute "${key}" is not declared; its type is inferred from the values`, { line, element: key }, `${CX2_ISSUE.UNDECLARED_ATTRIBUTE}:${domain}:${key}`);
+            }
+            const converted = decl.type === null
+                ? plainJson(value, (digits) => {
+                    this.precision(name, digits);
+                })
+                : convertValue(value, decl.type, this.options.long, (digits) => {
+                    this.precision(name, digits);
+                });
+            if (converted === BAD) {
+                report.error("validation-error", BAD_VALUE_CODE, `${element}: "${name}" is ${shown(value)}, not a ${decl.type?.d ?? "value"}; the cell is unset`, { line, element });
+                continue;
+            }
+            try {
+                if (domain === "node") {
+                    this.sink.setNodeValue(decl.handle, row, converted);
+                }
+                else {
+                    this.sink.setEdgeValue(decl.handle, row, converted);
+                }
+            }
+            catch (err) {
+                report.recordError(err, { line, element });
+            }
+        }
+    }
+    /**
+     * Record a long value beyond 2^53 (once).
+     * @param name - the attribute
+     * @param digits - the value
+     */
+    precision(name, digits) {
+        this.report.warnOnce("precision", PRECISION_CODE, `"${name}": ${digits} is beyond 2^53; stored as the nearest double`, { element: name }, `${PRECISION_CODE}:value`);
+    }
+    // ------------------------------------------------------------ edges
+    /**
+     * Read one edge element.
+     * @param held - the element
+     */
+    readEdge(held) {
+        this.checkAbort();
+        const { report, sink } = this;
+        const { value, line } = held;
+        if (!isRecord(value)) {
+            report.error("parse-error", BAD_ASPECT_BLOCK_CODE, `an edges element is ${shown(value)}, not an object`, {
+                line,
+                element: "edges",
+            });
+            report.counts.skippedEdges++;
+            return;
+        }
+        this.unknownKeys(value, EDGE_KEYS, "edge", line);
+        if (value.id === undefined || value.id === null) {
+            report.error("missing-value", MISSING_ID_CODE, "an edge has no id", { line, element: "edges" });
+            report.counts.skippedEdges++;
+            return;
+        }
+        const element = `edge ${shown(value.id)}`;
+        for (const key of ["s", "t"]) {
+            if (value[key] === undefined || value[key] === null) {
+                report.error("missing-value", MISSING_ENDPOINT_CODE, `${element} has no ${key}`, { line, element });
+                report.counts.skippedEdges++;
+                return;
+            }
+        }
+        const id = this.idOf(value.id, (held.inexact & 1) !== 0, element, true);
+        const s = id === null ? null : this.idOf(value.s, (held.inexact & 2) !== 0, element);
+        const t = s === null ? null : this.idOf(value.t, (held.inexact & 4) !== 0, element);
+        if (id === null || s === null || t === null) {
+            report.counts.skippedEdges++;
+            return;
+        }
+        if (this.edgeRows.has(id)) {
+            report.error("validation-error", DUPLICATE_EDGE_ID_CODE, `${element} is declared more than once; the later edge is skipped`, { line, element });
+            report.counts.skippedEdges++;
+            return;
+        }
+        const source = this.endpoint(s, element, line);
+        const target = source === null ? null : this.endpoint(t, element, line);
+        if (source === null || target === null) {
+            report.counts.skippedEdges++;
+            return;
+        }
+        const attrs = isRecord(value.v) ? value.v : null;
+        let weight;
+        const weightKey = this.weightKey(attrs);
+        try {
+            weight = weightKey === null || attrs === null ? undefined : weightFromValue(plainJson(attrs[weightKey]));
+        }
+        catch (err) {
+            report.recordError(err, { line, element });
+            report.counts.skippedEdges++;
+            return;
+        }
+        if (weight !== undefined) {
+            this.weighted = true;
+        }
+        const before = sink.edgeCount;
+        let edge;
+        try {
+            edge = this.direction.addEdge(source, target, "directed", weight, { line, element });
+        }
+        catch (err) {
+            report.recordError(err, { line, element });
+            report.counts.skippedEdges++;
+            return;
+        }
+        report.counts.edges += sink.edgeCount - before;
+        this.edgeRows.set(id, edge);
+        sink.setEdgeValue(this.edgeIdColumn(), edge, typeof id === "number" ? id : Number(id));
+        if (attrs !== null) {
+            this.writeAttributes("edge", edge, attrs, element, line);
+        }
+    }
+    /**
+     * The key of an edge's v that holds the weight: weightFrom, or its declared alias.
+     * @param attrs - the edge's v
+     * @returns the key present in attrs, or null
+     */
+    weightKey(attrs) {
+        const { weightFrom } = this.options;
+        if (weightFrom === null || attrs === null) {
+            return null;
+        }
+        const alias = this.decls.edge.byName.get(weightFrom)?.alias ?? null;
+        if (alias !== null && alias in attrs) {
+            return alias;
+        }
+        return weightFrom in attrs ? weightFrom : null;
+    }
+    /**
+     * The sink id of an edge endpoint: a known node, or a node created under addMissingNodes.
+     * @param cx - the endpoint's CX id
+     * @param element - the edge name
+     * @param line - its line
+     * @returns the sink id, or null when the endpoint was reported
+     */
+    endpoint(cx, element, line) {
+        const known = this.sinkIds.get(cx);
+        if (known !== undefined) {
+            return known;
+        }
+        if (!this.options.addMissingNodes) {
+            this.report.error("missing-value", CX2_ISSUE.UNKNOWN_NODE, `${element}: the endpoint ${String(cx)} is not a node; the edge is skipped`, { line, element });
+            return null;
+        }
+        try {
+            this.nodeRows.set(cx, this.sink.addNode(cx));
+        }
+        catch (err) {
+            this.report.recordError(err, { line, element });
+            return null;
+        }
+        this.sinkIds.set(cx, cx);
+        this.report.counts.nodes++;
+        return cx;
+    }
+    // ------------------------------------------------------------ network attributes, bypasses
+    /** Write the network attributes (the first element; others are reported). */
+    readNetworkAttributes() {
+        const { networkAttributes } = this.doc;
+        if (networkAttributes.length === 0) {
+            return;
+        }
+        if (networkAttributes.length > 1) {
+            this.report.warning("validation-error", CX2_ISSUE.EXTRA_ELEMENTS, `networkAttributes holds ${networkAttributes.length} elements; the first is read`, { line: networkAttributes[1].line, element: "networkAttributes" });
+        }
+        const { value, line } = networkAttributes[0];
+        if (!isRecord(value)) {
+            this.report.error("parse-error", BAD_ASPECT_BLOCK_CODE, "the networkAttributes element is not an object", {
+                line,
+                element: "networkAttributes",
+            });
+            return;
+        }
+        for (const [name, raw] of Object.entries(value)) {
+            if (raw === null || raw === undefined) {
+                continue;
+            }
+            const decl = this.decls.network.byName.get(name);
+            const element = `networkAttributes.${name}`;
+            if (decl === undefined) {
+                this.report.warnOnce("validation-error", CX2_ISSUE.UNDECLARED_ATTRIBUTE, `the network attribute "${name}" is not declared; its column is inferred from the value`, { line, element: name }, `${CX2_ISSUE.UNDECLARED_ATTRIBUTE}:network:${name}`);
+            }
+            if ((name === "name" || name === "description") &&
+                typeof raw === "string" &&
+                decl?.type?.d !== "list_of_string") {
+                // the graph's own name and description: GraphMeta, written back from there
+                continue;
+            }
+            try {
+                const seen = { kind: undefined, list: undefined };
+                observe(seen, raw);
+                const type = decl?.type ?? inferredType(seen);
+                if (type === null) {
+                    this.sink.setGraphValue(name, plainJson(raw, (digits) => {
+                        this.precision(name, digits);
+                    }), {
+                        dtype: "json",
+                        origin: { format: CX2_FORMAT, id: null },
+                    });
+                    continue;
+                }
+                const converted = convertValue(raw, type, this.options.long, (digits) => {
+                    this.precision(name, digits);
+                });
+                if (converted === BAD) {
+                    this.report.error("validation-error", BAD_VALUE_CODE, `${element} is ${shown(raw)}, not a ${type.d}; unset`, { line, element });
+                    continue;
+                }
+                const scalar = scalarDtype(type.scalar, this.options.long);
+                this.sink.setGraphValue(name, converted, {
+                    dtype: type.list ? "list" : scalar,
+                    ...(type.list ? { itemDtype: scalar } : {}),
+                    origin: { format: CX2_FORMAT, id: null, type: type.d },
+                });
+            }
+            catch (err) {
+                this.report.recordError(err, { line, element });
+            }
+        }
+    }
+    /**
+     * Write the per-element visual property values: one column per property, typed by its values.
+     * @param domain - node or edge
+     * @param entries - the bypass elements
+     */
+    readBypasses(domain, entries) {
+        const rows = domain === "node" ? this.nodeRows : this.edgeRows;
+        const columns = new Map();
+        for (const held of entries) {
+            this.checkAbort();
+            const { value, line } = held;
+            if (!isRecord(value) || !isRecord(value.v)) {
+                this.report.error("parse-error", BAD_ASPECT_BLOCK_CODE, `a ${domain}Bypasses element is not an object with an id and a v object; skipped`, { line, element: `${domain}Bypasses` });
+                continue;
+            }
+            const row = this.rowOf(rows, value.id);
+            if (row === undefined) {
+                this.dangle(`${domain} bypass`);
+                continue;
+            }
+            for (const [property, raw] of Object.entries(value.v)) {
+                if (raw === null || raw === undefined) {
+                    continue;
+                }
+                let column = columns.get(property);
+                if (column === undefined) {
+                    column = { rows: [], values: [] };
+                    columns.set(property, column);
+                }
+                column.rows.push(row);
+                column.values.push(plainJson(raw));
+            }
+        }
+        for (const [property, { rows: targets, values }] of columns) {
+            const decl = {
+                name: property,
+                dtype: bypassDtype(values),
+                nullable: true,
+                // origin.id keeps the property's name: a column renamed for a clash is written back under it
+                origin: { format: CX2_FORMAT, id: property, namespace: BYPASS_NAMESPACE },
+            };
+            const handle = declareFresh(this.sink, domain, decl, this.report);
+            for (let i = 0; i < targets.length; i++) {
+                if (domain === "node") {
+                    this.sink.setNodeValue(handle, targets[i], values[i]);
+                }
+                else {
+                    this.sink.setEdgeValue(handle, targets[i], values[i]);
+                }
+            }
+        }
+    }
+    // ------------------------------------------------------------ aspects, status, metadata
+    /** The style-rule loss, the single-element aspects, the status and the metadata counts. */
+    checkAspects() {
+        const { doc, report } = this;
+        const { structure } = doc;
+        const styles = [];
+        for (const aspect of STYLE_ASPECTS) {
+            const elements = doc.opaque.get(aspect);
+            if (elements !== undefined) {
+                styles.push(describeStyle(aspect, elements));
+            }
+        }
+        if (styles.length > 0) {
+            report.warning("unsupported", STYLES_NOT_IMPORTED_CODE, `the file's style rules are not applied (${styles.join("; ")}); they are kept in meta.extra.cx2.opaque (style import is issue #706)`, { element: STYLE_ASPECTS.filter((a) => doc.opaque.has(a)).join(",") });
+        }
+        for (const aspect of SINGLE_ELEMENT_ASPECTS.slice(1)) {
+            const count = doc.opaque.get(aspect)?.length ?? 0;
+            if (count > 1) {
+                report.warning("validation-error", CX2_ISSUE.EXTRA_ELEMENTS, `${aspect} holds ${count} elements where CX2 allows one; all are kept, a reader uses the first`, { element: aspect });
+            }
+        }
+        if (!doc.hasFragments) {
+            for (const [aspect, blocks] of structure.blocks) {
+                if (blocks > 1 && !STRUCTURE_ASPECTS.has(aspect)) {
+                    report.warnOnce("validation-error", CX2_ISSUE.UNDECLARED_FRAGMENTS, `"${aspect}" comes in ${blocks} blocks although the descriptor does not declare hasFragments; the blocks are joined in order`, { element: aspect });
+                }
+            }
+        }
+        if (!structure.hasStatus) {
+            report.error("validation-error", CX2_ISSUE.NO_STATUS, "the document ends without a status block", {
+                element: "status",
+            });
+        }
+        else if (!structure.statusWellFormed() || structure.counts.get("status") !== 1) {
+            // the specification: exactly one status aspect holding exactly one element
+            const count = structure.counts.get("status") ?? 0;
+            report.error("validation-error", CX2_ISSUE.NO_STATUS, `the status is malformed (${count === 1 ? shown(structure.status) : `${count} elements`}): a document ends with one status block holding one object with a boolean success`, { element: "status" });
+        }
+        structure.checkCounts();
+    }
+    /** Record the metadata: source format and version, name, description, id type, the kept aspects. */
+    setMeta() {
+        const { doc } = this;
+        const attrs = doc.networkAttributes[0]?.value;
+        const named = isRecord(attrs) ? attrs : {};
+        const extra = {};
+        if (doc.opaque.size > 0) {
+            extra.opaque = Object.fromEntries(doc.opaque);
+        }
+        if (Object.keys(this.decls.other).length > 0) {
+            extra.declarations = this.decls.other;
+        }
+        const { weightFrom } = this.options;
+        const weightDecl = weightFrom === null ? undefined : this.decls.edge.byName.get(weightFrom);
+        const patch = {
+            sourceFormat: CX2_FORMAT,
+            sourceVersion: doc.version,
+            idType: this.idType,
+            ...(typeof named.name === "string" ? { name: named.name } : {}),
+            ...(typeof named.description === "string" ? { description: named.description } : {}),
+            ...(this.weighted && weightFrom !== null
+                ? {
+                    weightOrigin: {
+                        format: CX2_FORMAT,
+                        id: weightDecl?.alias ?? null,
+                        title: weightFrom,
+                        type: weightDecl?.type?.d ?? null,
+                        namespace: null,
+                    },
+                }
+                : {}),
+            extra: { cx2: extra },
+        };
+        this.sink.setMeta(patch);
+    }
+}
+/**
+ * The dtype of a bypass column: f64 when every value is a number, bool when every one is a
+ * boolean, string when every one is a string, json otherwise.
+ * @param values - the values
+ * @returns the dtype
+ */
+function bypassDtype(values) {
+    if (values.every((v) => typeof v === "number")) {
+        return "f64";
+    }
+    if (values.every((v) => typeof v === "boolean")) {
+        return "bool";
+    }
+    if (values.every((v) => typeof v === "string")) {
+        return "string";
+    }
+    return "json";
+}
+/**
+ * What a style aspect holds, for the W_STYLES_NOT_IMPORTED message.
+ * @param aspect - the aspect name
+ * @param elements - its elements
+ * @returns a short description
+ */
+function describeStyle(aspect, elements) {
+    const first = elements[0];
+    if (aspect === "visualProperties" && isRecord(first)) {
+        const count = (key) => (isRecord(first[key]) ? Object.keys(first[key]).length : 0);
+        const defaults = isRecord(first.default)
+            ? Object.values(first.default).reduce((n, v) => n + (isRecord(v) ? Object.keys(v).length : 0), 0)
+            : 0;
+        return `visualProperties: ${defaults} default(s), ${count("nodeMapping")} node mapping(s), ${count("edgeMapping")} edge mapping(s)`;
+    }
+    return `${aspect}: ${elements.length} element(s)`;
+}
+/**
+ * Resolve the zAs option.
+ * @param value - the option
+ * @returns the mode; E_UNSUPPORTED for any other value
+ */
+export function zAsOption(value) {
+    if (value === undefined) {
+        return "column";
+    }
+    if (value === "column" || value === "position") {
+        return value;
+    }
+    throw new GraphFormatError("E_UNSUPPORTED", `option zAs: ${shown(value)} is not one of "column", "position"`, {
+        option: "zAs",
+        found: typeof value === "string" ? value : typeof value,
+    });
+}
+/**
+ * The CX2 importer plugin (design section 1.3).
+ */
+export const cx2Importer = Object.freeze({
+    format: CX2_FORMAT,
+    extensions: Object.freeze([".cx2"]),
+    mimeTypes: Object.freeze(["application/json"]),
+    /**
+     * Confidence that the head is CX2: 0.97 when the first member of a top-level array is an
+     * object with a CXVersion key, in any key order.
+     * @param head - the first bytes
+     * @returns the confidence
+     */
+    sniff(head) {
+        const text = new TextDecoder("utf-8").decode(head.subarray(0, 1024)).replace(/^\uFEFF/, "");
+        return /^\s*\[\s*\{(?:\s*"[^"]*"\s*:\s*(?:true|false|"[^"]*"|[0-9.]+)\s*,)*\s*"CXVersion"\s*:/.test(text)
+            ? 0.97
+            : 0;
+    },
+    /**
+     * Read a CX2 document into the sink.
+     * @param input - the text, bytes or stream
+     * @param sink - the sink
+     * @param options - format-specific and common options
+     * @returns the import report; ImportError on a fatal error or beyond the error limit
+     */
+    async import(input, sink, options) {
+        const resolved = resolveImportOptions(options, FORMAT_DEFAULTS);
+        const zAs = zAsOption(options?.zAs);
+        const report = new ImportReportBuilder(CX2_FORMAT, resolved.errorLimit);
+        reportSinkOptions(sink, options, report, true);
+        reportUnusedOptions(options, report, USED_OPTIONS);
+        const doc = await readDocument(input, report, resolved);
+        new Cx2Reader(sink, report, resolved, zAs, doc).build();
+        throwIfAborted(resolved.signal);
+        return report.finish();
+    },
+});
+//# sourceMappingURL=importer.js.map