@graphty/graph-io 0.3.25 → 0.3.26

package/dist/src/formats/obo/exporter.js

@@ -0,0 +1,1736 @@
+/**
+ * The OBO exporter: writes a snapshot as an OBO 1.4 flat file, the text format of the Gene
+ * Ontology and the OBO Foundry ontologies.
+ *
+ * Every node is a frame (`[Term]`, or `[Instance]` / `[Typedef]` from the `type` column) in node
+ * order; every edge is a clause on its source's frame: `is_a: T` for the relation `is_a`,
+ * `instance_of: T` on an Instance, `relationship: R T` for anything else, an edge without a
+ * relation as `is_a` (the `relation` option). The columns of the OBO vocabulary
+ * (src/common/ontology.ts: `name`, `namespace`, `def`, `synonym`, `xref`, ...) are written back
+ * as their tags; any other node column becomes `property_value: <column> "<value>" xsd:<type>`
+ * lines (with a `[Typedef]` declaring the column as a metadata relation), any other edge column a
+ * qualifier of the edge's clause. A placeholder node (`graphty.placeholder`, a target no frame
+ * declared) gets no frame, so the re-import makes it again. The header, the Typedefs and the
+ * unknown frames an OBO import kept in `meta.extra.obo` are written back.
+ *
+ * check() predicts every difference the OBO importer produces on re-import: a vocabulary column
+ * whose values the file cannot carry exactly is written as `property_value` lines instead and
+ * reported, never written half right.
+ */
+import { GraphFormatError } from "@graphty/graph-format";
+import { COLUMN_AS_PROPERTY_VALUE_CODE, GRAPH_COLUMN_AS_METADATA_CODE, NODE_ORDER_CODE, RELATION_ASSUMED_CODE, ROLE_ASSUMED_CODE, TYPEDEF_NODES_CODE, } from "../../common/codes.js";
+import { pairFolding } from "../../common/direction.js";
+import { capabilities, LOSS } from "../../common/export.js";
+import { formatNumber } from "../../common/format.js";
+import { OBO_NODE_COLUMNS, PLACEHOLDER_COLUMN, SYNONYM_SCOPES } from "../../common/ontology.js";
+import { capabilityNotes, cellOf, emptyColumnNotes, fitsVocabulary, FRAME_KINDS, framelessNodes, isQualifierRecord, movedNodes, notePropertyColumn, slotColumn, textOf, UNWRITTEN_ROLES, } from "../../common/ontology-export.js";
+import { resolveExportOptions } from "../../common/options.js";
+import { agree, plural } from "../../common/plural.js";
+import { explicitWeights } from "../../common/weights.js";
+import { encodeChunks, joinText } from "../../common/writer.js";
+import { BOOL_TAGS, DEPRECATED_TAGS, ID_LIST_TAGS, TEXT_TAGS, TYPEDEF_TAGS } from "./importer.js";
+import { escapeOboQuoted, escapeOboValue, escapeOboWord, hasLineEnd, isOboWord, isQualifierName, NOT_IN_WORD, qualifierBlock, tokenize, } from "./syntax.js";
+/**
+ * The loss notes the OBO exporter's check() returns, by name. A key is the code without its
+ * severity and format prefixes.
+ * @category Built-in formats
+ */
+export const OBO_LOSS = Object.freeze({
+    /** A node column outside the OBO vocabulary (or one whose values a tag cannot carry exactly) reads back inside the `property_value` column. */
+    COLUMN_AS_PROPERTY_VALUE: COLUMN_AS_PROPERTY_VALUE_CODE,
+    /** An edge column (or the explicit weights) reads back inside the `qualifiers` column. */
+    EDGE_COLUMN_AS_QUALIFIER: "W_OBO_EDGE_COLUMN_AS_QUALIFIER",
+    /** Every edge is written from its source to its target, so an undirected graph reads back as directed. */
+    UNDIRECTED_AS_DIRECTED: "W_OBO_UNDIRECTED_AS_DIRECTED",
+    /** Two identical clauses on one frame (parallel edges with one relation and the same qualifiers, a repeated list item) read back as one. */
+    DUPLICATE_CLAUSE: "W_OBO_DUPLICATE_CLAUSE",
+    /** An edge without a relation is written with the `relation` option (default `is_a`). */
+    RELATION_ASSUMED: RELATION_ASSUMED_CODE,
+    /** A relation that is not an OBO id (empty, or holding a space, `!`, `{` or `}`) is written with `_` in place of those characters. */
+    RELATION_RENAMED: "W_OBO_RELATION_RENAMED",
+    /** The graph name is not an ontology id; the header `ontology` is written with `_` in place of the other characters. */
+    ONTOLOGY_NAME: "W_OBO_ONTOLOGY_NAME",
+    /** `[Typedef]` frames read back as nodes only under the importer's `typedefs: "nodes"`; by default they are metadata. */
+    TYPEDEF_NODES: TYPEDEF_NODES_CODE,
+    /** Edges are written in the frame of their source node, so they read back grouped by source, in node order. */
+    EDGE_ORDER: "W_OBO_EDGE_ORDER",
+    /**
+     * A graph attribute is written as a header `property_value` and reads back in `snapshot.meta.extra.obo.header`,
+     * not as a graph attribute.
+     */
+    GRAPH_COLUMN_AS_METADATA: GRAPH_COLUMN_AS_METADATA_CODE,
+    /** A carriage return or form feed in a text cannot be written; it is written as a line feed. */
+    LINE_END: "W_OBO_LINE_END",
+    /** The nodes read back in a different order. */
+    NODE_ORDER: NODE_ORDER_CODE,
+    /** A mutual pair is written as two clauses without its mark. */
+    MUTUAL_EXPANDED: LOSS.MUTUAL_EXPANDED,
+    /**
+     * The undirected edges of a mixed graph are written the way `onMixedDirection` chose ("directed" or "undirected").
+     */
+    MIXED_DIRECTION: LOSS.MIXED_DIRECTION,
+    /**
+     * The graph has both directed and undirected edges and `onMixedDirection` is "error". An import stops; a save to a
+     * format that holds one direction per file fails with E_DIRECTED. Pass "directed" or "undirected" to read or write
+     * it anyway.
+     */
+    MIXED_DIRECTION_ERROR: LOSS.MIXED_DIRECTION_ERROR,
+    /** OBO has no edge ids. */
+    EDGE_IDS_DROPPED: LOSS.EDGE_IDS_DROPPED,
+    /** OBO has no positions. */
+    POSITIONS_DROPPED: LOSS.POSITIONS,
+    /** OBO has no containment. */
+    HIERARCHY_DROPPED: LOSS.HIERARCHY,
+    /** OBO has no time. */
+    TEMPORAL_DROPPED: LOSS.TEMPORAL,
+    /** OBO has no visual columns. */
+    VIZ_DROPPED: LOSS.VIZ,
+    /** An attribute with a role the format has no place for is written as a plain attribute; the role is lost. */
+    ROLE_DROPPED: LOSS.ROLE,
+    /**
+     * An attribute without a role is written where the format keeps a role (for example, a `name` column as the label), and
+     * reads back with that role.
+     */
+    ROLE_ASSUMED: ROLE_ASSUMED_CODE,
+    /**
+     * An attribute with a role (for example, the label) is written where the format keeps that role, and reads back under the
+     * name the format's importer gives it.
+     */
+    COLUMN_NAME_CHANGED: LOSS.COLUMN_NAME_CHANGED,
+    /**
+     * An OBO attribute stored as text where graph-io uses a dictionary (or the other way round); it reads back with
+     * graph-io's usual type. The values are the same.
+     */
+    DTYPE_UNSUPPORTED: LOSS.DTYPE,
+    /** A column without a value on any written element reads back absent. */
+    EMPTY_COLUMN_DROPPED: LOSS.EMPTY_COLUMN,
+    /** A declared default: OBO has none. */
+    DEFAULT_DROPPED: LOSS.DEFAULT,
+    /** Declared options: OBO has no enumerations. */
+    OPTIONS_DROPPED: LOSS.OPTIONS,
+    /** An extension table OBO cannot carry. */
+    EXTENSION_TABLE_DROPPED: LOSS.EXTENSION_TABLE,
+    /**
+     * Node ids the format cannot write, under `sanitizeIds: "error"`; the save fails with E_INVALID_ID. Pass
+     * `sanitizeIds: "mangle"` to rewrite them.
+     */
+    ID_CHARSET: LOSS.ID_CHARSET,
+    /** Node ids OBO cannot write as they are, under sanitizeIds "mangle": rewritten, the original kept. */
+    ID_MANGLED: LOSS.ID_MANGLED,
+    /** Numeric ids are written as text and read back as strings. */
+    ID_TEXT_TYPE: LOSS.ID_TEXT_TYPE,
+    /**
+     * Two node ids would be written as the same text (the number 5 and the text "5"); the save fails with
+     * E_INVALID_ID.
+     */
+    ID_TEXT_COLLISION: LOSS.ID_TEXT_COLLISION,
+});
+/**
+ * What the OBO flat file keeps: a directed multigraph with self-loops and any id (the exporter's
+ * own rule refuses whitespace, control characters, `!`, `{` and `}`). No column of the snapshot's own reads back as
+ * a column: the file keeps the OBO vocabulary (`name`, `def`, `synonym`, ... with their own
+ * types) and writes every other node column as property values and every edge column as
+ * qualifiers, which check() reports column by column.
+ * @category Built-in formats
+ */
+export const OBO_CAPABILITIES = capabilities({
+    mixedDirection: false,
+    multiEdges: true,
+    selfLoops: true,
+    edgeIds: "none",
+    idCharset: "any",
+    dtypes: [],
+    components: false,
+    lists: false,
+    json: false,
+    defaults: false,
+    options: false,
+    hierarchy: false,
+    temporal: "none",
+    graphAttributes: false,
+    positions: false,
+    viz: false,
+});
+/** The roles OBO has a slot for, and the column names its importer gives them. */
+/** The node column that keeps a rewritten id's original (restored by restoreMangledIds). */
+const ORIGINAL_ID = "graphty:originalId";
+/** The edge columns of the vocabulary. */
+const RELATION_COLUMN = "relation";
+const QUALIFIERS_COLUMN = "qualifiers";
+/** The qualifier name the explicit weights are written under. */
+const WEIGHT_QUALIFIER = "weight";
+/** The relations a file may use without declaring them (the importer's built-ins). */
+const BUILTIN_RELATIONS = new Set([
+    "is_a",
+    "instance_of",
+    "disjoint_from",
+    "inverse_of",
+    "union_of",
+    "intersection_of",
+]);
+/** Marks where the edge clauses go in TAG_ORDER. */
+const EDGES = "\u0000edges";
+/** Marks where the unknown tags go in TAG_ORDER. */
+const UNRECOGNIZED = "obo.unrecognized";
+/** The order of the tags in a frame (the OBO 1.4 guide's, Term, Instance and Typedef tags merged). */
+const TAG_ORDER = [
+    "is_anonymous",
+    "name",
+    "namespace",
+    "alt_id",
+    "def",
+    "comment",
+    "subset",
+    "synonym",
+    "xref",
+    "builtin",
+    "property_value",
+    "domain",
+    "range",
+    "holds_over_chain",
+    "is_anti_symmetric",
+    "is_cyclic",
+    "is_reflexive",
+    "is_symmetric",
+    "is_asymmetric",
+    "is_transitive",
+    "is_functional",
+    "is_inverse_functional",
+    EDGES,
+    "intersection_of",
+    "union_of",
+    "equivalent_to",
+    "disjoint_from",
+    "inverse_of",
+    "transitive_over",
+    "equivalent_to_chain",
+    "disjoint_over",
+    "created_by",
+    "creation_date",
+    "is_obsolete",
+    "replaced_by",
+    "consider",
+    "expand_assertion_to",
+    "expand_expression_to",
+    "is_metadata_tag",
+    "is_class_level",
+    UNRECOGNIZED,
+];
+/** The header tags in the 1.4 guide's order; every other kept header tag follows them. */
+const HEADER_ORDER = [
+    "format-version",
+    "data-version",
+    "version",
+    "date",
+    "saved-by",
+    "auto-generated-by",
+    "import",
+    "subsetdef",
+    "synonymtypedef",
+    "idspace",
+    "default-relationship-id-prefix",
+    "id-mapping",
+    "default-namespace",
+    "namespace-id-rule",
+    "remark",
+    "ontology",
+];
+/** Tags the importer applies (so an unknown tag of that name would not read back as unknown). */
+const APPLIED_TAGS = new Set([
+    "id",
+    "is_a",
+    "instance_of",
+    "relationship",
+    "intersection_of",
+    "holds_over_chain",
+    "equivalent_to_chain",
+    "def",
+    "expand_assertion_to",
+    "expand_expression_to",
+    "synonym",
+    "xref",
+    "property_value",
+    ...TEXT_TAGS,
+    ...BOOL_TAGS,
+    ...ID_LIST_TAGS,
+    ...DEPRECATED_TAGS.keys(),
+]);
+/** The vocabulary node columns the flat file writes as tags (`type`, `name` and `propertyType` aside). */
+const TAG_COLUMNS = new Set(Object.keys(OBO_NODE_COLUMNS).filter((name) => name !== "type" && name !== "name" && name !== "propertyType"));
+/** The xsd datatype of a dtype in a `property_value` line. */
+const XSD = Object.freeze({
+    string: "xsd:string",
+    dict: "xsd:string",
+    bool: "xsd:boolean",
+    i32: "xsd:integer",
+    u32: "xsd:integer",
+    u8: "xsd:integer",
+    f32: "xsd:double",
+    f64: "xsd:double",
+});
+// ============================================================ values
+/**
+ * Whether a text survives as an unquoted tag value: the reader trims it, and the OBO grammar
+ * (fastobo, owlapi) refuses an empty one.
+ * @param text - the text
+ * @returns true when the text is not empty and has no surrounding whitespace
+ */
+function isTrimmed(text) {
+    return text.length > 0 && text === text.trim();
+}
+/**
+ * Whether a value is an array whose items all pass a test.
+ * @param value - the value
+ * @param item - the item test
+ * @param nonEmpty - whether the array must have an item
+ * @returns true when it is such an array
+ */
+function arrayOf(value, item, nonEmpty = true) {
+    return Array.isArray(value) && (!nonEmpty || value.length > 0) && value.every(item);
+}
+/**
+ * Whether a value is a string the unquoted xref slot keeps (non-empty, no surrounding whitespace).
+ * @param value - the value
+ * @returns true for such a string
+ */
+function isXrefId(value) {
+    return typeof value === "string" && value.length > 0 && isTrimmed(value);
+}
+/**
+ * Whether a value is an OBO word.
+ * @param value - the value
+ * @returns true for a string isOboWord() accepts
+ */
+function isWord(value) {
+    return typeof value === "string" && isOboWord(value);
+}
+/**
+ * Whether an object has exactly the given keys, `qualifiers` optional (and then a qualifier record).
+ * @param value - the value
+ * @param keys - the required keys
+ * @returns true when it has those keys and nothing else
+ */
+function hasKeys(value, keys) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        return false;
+    }
+    const own = Object.keys(value);
+    const record = value;
+    if (Object.hasOwn(record, "qualifiers")) {
+        if (!isQualifierRecord(record.qualifiers, isQualifierName)) {
+            return false;
+        }
+        return own.length === keys.length + 1 && keys.every((k) => Object.hasOwn(record, k));
+    }
+    return own.length === keys.length && keys.every((k) => Object.hasOwn(record, k));
+}
+/**
+ * Replace every character a word cannot hold with `_`.
+ * @param text - the text
+ * @returns a word
+ */
+function wordOf(text) {
+    const out = text.replaceAll(new RegExp(NOT_IN_WORD.source, "gu"), "_");
+    return out.length === 0 ? "_" : out;
+}
+/**
+ * A qualifier record as name / value pairs (a list value as one pair per item).
+ * @param record - a record isQualifierRecord() accepts
+ * @returns the pairs
+ */
+function qualifierPairs(record) {
+    const out = [];
+    for (const [name, value] of Object.entries(record)) {
+        for (const item of Array.isArray(value) ? value : [value]) {
+            out.push([name, item]);
+        }
+    }
+    return out;
+}
+// ============================================================ the plan
+/**
+ * Resolve the OBO-specific options.
+ * @param options - the caller's options
+ * @returns the relation and the ontology; E_UNSUPPORTED for a value that is not an OBO id
+ */
+function resolveOboOptions(options) {
+    const relation = options?.relation ?? "is_a";
+    if (typeof relation !== "string" || !isOboWord(relation)) {
+        throw new GraphFormatError("E_UNSUPPORTED", `option relation: ${JSON.stringify(relation)} is not an OBO id`, {
+            option: "relation",
+            found: relation,
+        });
+    }
+    const ontology = options?.ontology ?? null;
+    if (ontology !== null && (typeof ontology !== "string" || !/^[A-Za-z0-9_.\-/]+$/.test(ontology))) {
+        throw new GraphFormatError("E_UNSUPPORTED", `option ontology: ${JSON.stringify(ontology)} is not an ontology id (letters, digits, _ . - /)`, { option: "ontology", found: ontology });
+    }
+    return { relation, ontology };
+}
+/**
+ * The ids to write: each node's id text, or under "mangle" a word with `_` for the characters a
+ * word cannot hold (and `_2`, `_3`... on a collision), the original kept.
+ * @param snapshot - the snapshot
+ * @param mode - the sanitizeIds option
+ * @param note - records a note
+ * @returns the ids, the originals and the fatal error, if any
+ */
+function planIds(snapshot, mode, note) {
+    const n = snapshot.nodeCount;
+    const ids = new Array(n);
+    const bad = [];
+    let numeric = 0;
+    for (let i = 0; i < n; i++) {
+        const id = snapshot.ids.idOf(i);
+        if (typeof id === "number") {
+            numeric++;
+        }
+        ids[i] = String(id);
+        if (!isOboWord(ids[i])) {
+            bad.push(i);
+        }
+    }
+    if (numeric > 0) {
+        note(LOSS.ID_TEXT_TYPE, `${numeric} numeric node id${plural(numeric)} ${agree(numeric, "is", "are")} written as text and read back as strings`, null, numeric);
+    }
+    const originals = new Map();
+    let fatal = null;
+    if (bad.length > 0 && mode === "error") {
+        fatal = refuseIds(snapshot, ids, bad, note);
+    }
+    else if (bad.length > 0) {
+        mangleIds(ids, bad, originals, note);
+    }
+    return { ids, originals, fatal: fatal ?? collidingIds(snapshot, ids, note) };
+}
+/**
+ * Note the ids that are not OBO words, for a save that refuses them.
+ * @param snapshot - the snapshot
+ * @param ids - the id texts
+ * @param bad - the indices of the ids that are not OBO words
+ * @param note - records a note
+ * @returns the error the save throws
+ */
+function refuseIds(snapshot, ids, bad, note) {
+    note(LOSS.ID_CHARSET, `${bad.length} node id${plural(bad.length)} ${agree(bad.length, "is", "are")} not OBO ids (empty, or holding whitespace, a control character, "!", "{" or "}"); the save fails unless sanitizeIds is "mangle"`, null, bad.length);
+    return new GraphFormatError("E_INVALID_ID", `${bad.length} node id${plural(bad.length)} cannot be written as OBO ids (first: ${JSON.stringify(ids[bad[0]])}); pass sanitizeIds: "mangle" to rewrite them`, { reason: "charset", count: bad.length, id: snapshot.ids.idOf(bad[0]), index: bad[0] });
+}
+/**
+ * Rewrite the ids that are not OBO words with "_" (and `_2`, `_3`... on a collision), keeping the
+ * originals.
+ * @param ids - the id texts, rewritten in place
+ * @param bad - the indices of the ids that are not OBO words
+ * @param originals - receives each rewritten id's original text
+ * @param note - records a note
+ */
+function mangleIds(ids, bad, originals, note) {
+    const badSet = new Set(bad);
+    const used = new Set(ids.filter((_, i) => !badSet.has(i)));
+    for (const i of bad) {
+        const base = wordOf(ids[i]);
+        let candidate = base;
+        let k = 2;
+        while (used.has(candidate)) {
+            candidate = `${base}_${k}`;
+            k++;
+        }
+        used.add(candidate);
+        originals.set(i, ids[i]);
+        ids[i] = candidate;
+    }
+    note(LOSS.ID_MANGLED, `${bad.length} node id${plural(bad.length)} that ${agree(bad.length, "is", "are")} not OBO ids ${agree(bad.length, "is", "are")} rewritten with "_"; the originals are kept as ${ORIGINAL_ID} property values (JSON text; an import with restoreMangledIds: true reads them back as the ids)`, null, bad.length);
+}
+/**
+ * Note the first two node ids that have the same text, which OBO cannot tell apart.
+ * @param snapshot - the snapshot
+ * @param ids - the id texts
+ * @param note - records a note
+ * @returns the error the save throws, or null when every text is unique
+ */
+function collidingIds(snapshot, ids, note) {
+    const seen = new Map();
+    for (let i = 0; i < ids.length; i++) {
+        const before = seen.get(ids[i]);
+        if (before !== undefined) {
+            note(LOSS.ID_TEXT_COLLISION, `node ids ${JSON.stringify(snapshot.ids.idOf(before))} and ${JSON.stringify(snapshot.ids.idOf(i))} have the same text; the save fails`, null, 1);
+            return new GraphFormatError("E_INVALID_ID", "two node ids have the same text; OBO keeps ids as text", {
+                reason: "collision",
+            });
+        }
+        seen.set(ids[i], i);
+    }
+    return null;
+}
+/**
+ * The written edges (the mirror halves of folded pairs left out) grouped by source, in node order
+ * then edge order, and the direction notes.
+ * @param snapshot - the snapshot
+ * @param folding - the pair folding
+ * @param common - the common options
+ * @param note - records a note
+ * @returns the edge list, the CSR by source and the targets
+ */
+function planEdges(snapshot, folding, common, note) {
+    const { src, dst } = snapshot.edgeList();
+    const written = [];
+    for (let e = 0; e < snapshot.edgeCount; e++) {
+        if (!folding.folded(e)) {
+            written.push(e);
+        }
+    }
+    const edgeStart = new Uint32Array(snapshot.nodeCount + 1);
+    for (const e of written) {
+        edgeStart[src[e] + 1]++;
+    }
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        edgeStart[i + 1] += edgeStart[i];
+    }
+    const fill = edgeStart.slice(0, snapshot.nodeCount);
+    const edgeOrder = new Uint32Array(written.length);
+    for (const e of written) {
+        edgeOrder[fill[src[e]]++] = e;
+    }
+    let moved = 0;
+    for (let k = 0; k < edgeOrder.length; k++) {
+        if (edgeOrder[k] !== written[k]) {
+            moved++;
+        }
+    }
+    if (moved > 0) {
+        note(OBO_LOSS.EDGE_ORDER, `${moved} edge${plural(moved)} ${agree(moved, "reads", "read")} back at another position: edges are written on their source's frame, grouped by source in node order`, null, moved);
+    }
+    if (!snapshot.directed) {
+        note(OBO_LOSS.UNDIRECTED_AS_DIRECTED, `the snapshot is undirected; every edge is written from its source to its target and reads back directed (${written.length} edge${plural(written.length)})`, null, written.length);
+    }
+    else if (common.onMixedDirection !== "error") {
+        const undirected = written.filter((e) => !folding.sourceDirected(e)).length;
+        if (undirected > 0) {
+            note(OBO_LOSS.UNDIRECTED_AS_DIRECTED, `${undirected} undirected edge${plural(undirected)} ${agree(undirected, "is", "are")} written as one directed clause each; OBO has no undirected edge`, null, undirected);
+        }
+    }
+    if (folding.mutualCount > 0) {
+        note(LOSS.MUTUAL_EXPANDED, `${folding.mutualCount} mutual pair${plural(folding.mutualCount)} ${agree(folding.mutualCount, "is", "are")} written as two clauses; the mutual mark is lost`, null, folding.mutualCount);
+    }
+    return { written, edgeStart, edgeOrder, dst };
+}
+/**
+ * The frame types: the `type` column when every written node has one of Term, Instance or
+ * Typedef, else Term for every node (and the column is a property value).
+ * @param snapshot - the snapshot
+ * @param frameless - the frameless flags
+ * @returns the kinds and the type column used, or null
+ */
+function planKinds(snapshot, frameless) {
+    const kinds = new Array(snapshot.nodeCount).fill("Term");
+    const type = snapshot.nodes.get("type");
+    if (type === null || (type.dtype !== "dict" && type.dtype !== "string")) {
+        return { kinds, type: null };
+    }
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        if (frameless[i] === 1) {
+            if (type.isSet(i)) {
+                return { kinds: kinds.fill("Term"), type: null };
+            }
+            continue;
+        }
+        const value = cellOf(type, i);
+        if (typeof value !== "string" || !FRAME_KINDS.has(value)) {
+            return { kinds: kinds.fill("Term"), type: null };
+        }
+        kinds[i] = value;
+    }
+    return { kinds, type };
+}
+/**
+ * Whether a vocabulary column's values are written by its tag and read back unchanged, on every
+ * written node (the vocabulary's dtype, the shape the importer builds, OBO words where the tag
+ * takes an id, no surrounding space in an unquoted value, a Typedef tag on Typedef frames only).
+ * @param name - the column (a TAG_COLUMNS name)
+ * @param column - the column
+ * @param rows - the written nodes
+ * @param kinds - the frame types
+ * @param scopes - the default scope of each declared synonym type
+ * @returns true when the tag carries the column
+ */
+function tagCarries(name, column, rows, kinds, scopes) {
+    const spec = OBO_NODE_COLUMNS[name];
+    if (!fitsVocabulary(spec.dtype, column) || column.meta.components > 1) {
+        return false;
+    }
+    const typedefOnly = TYPEDEF_TAGS.has(name);
+    const valid = (v) => {
+        if (TEXT_TAGS.has(name)) {
+            return typeof v === "string" && isTrimmed(v);
+        }
+        if (BOOL_TAGS.has(name)) {
+            return typeof v === "boolean";
+        }
+        if (ID_LIST_TAGS.has(name)) {
+            return arrayOf(v, isWord);
+        }
+        switch (name) {
+            case "def":
+                return typeof v === "string";
+            case "def.xrefs":
+                return arrayOf(v, isXrefId, false);
+            case "xref":
+                return arrayOf(v, isXrefId);
+            case "xref.descriptions":
+                return (typeof v === "object" &&
+                    v !== null &&
+                    !Array.isArray(v) &&
+                    Object.values(v).every((d) => typeof d === "string"));
+            case "synonym":
+                return arrayOf(v, (s) => hasKeys(s, ["text", "scope", "type", "xrefs"]) &&
+                    typeof s.text === "string" &&
+                    typeof s.scope === "string" &&
+                    SYNONYM_SCOPES.has(s.scope) &&
+                    (s.type === null || isWord(s.type)) &&
+                    (s.type === null || (scopes.get(s.type) ?? s.scope) === s.scope) &&
+                    arrayOf(s.xrefs, isXrefId, false));
+            case "intersection_of":
+                return arrayOf(v, (x) => hasKeys(x, ["relation", "target"]) &&
+                    (x.relation === null || isWord(x.relation)) &&
+                    isWord(x.target));
+            case "property_value":
+                return arrayOf(v, (x) => hasKeys(x, ["relation", "value", "datatype"]) &&
+                    isWord(x.relation) &&
+                    x.relation !== ORIGINAL_ID &&
+                    typeof x.value === "string" &&
+                    (x.datatype === null || isWord(x.datatype)));
+            case "holds_over_chain":
+            case "equivalent_to_chain":
+                return arrayOf(v, (pair) => arrayOf(pair, isWord) && pair.length === 2);
+            case "expand_assertion_to":
+            case "expand_expression_to":
+                return arrayOf(v, (x) => hasKeys(x, ["template", "xrefs"]) &&
+                    typeof x.template === "string" &&
+                    arrayOf(x.xrefs, isXrefId, false));
+            case "obo.qualifiers":
+                return (typeof v === "object" &&
+                    v !== null &&
+                    !Array.isArray(v) &&
+                    Object.values(v).every((entries) => arrayOf(entries, (entry) => hasKeys(entry, ["value"]) &&
+                        Object.hasOwn(entry, "qualifiers") &&
+                        typeof entry.value === "string" &&
+                        isQualifierRecord(entry.qualifiers, isQualifierName))));
+            default:
+                return false;
+        }
+    };
+    for (const i of rows) {
+        if (!column.isSet(i)) {
+            continue;
+        }
+        if (typedefOnly && kinds[i] !== "Typedef") {
+            return false;
+        }
+        if (!valid(cellOf(column, i))) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Whether the `obo.unrecognized` column reads back unchanged: a record of tag to texts, each tag
+ * one the importer does not apply on that frame type.
+ * @param column - the column
+ * @param rows - the written nodes
+ * @param kinds - the frame types
+ * @returns true when every cell is written as unknown tags and read back as the same
+ */
+function unrecognizedCarried(column, rows, kinds) {
+    if (column.dtype !== "json") {
+        return false;
+    }
+    for (const i of rows) {
+        const v = cellOf(column, i);
+        if (v === undefined) {
+            continue;
+        }
+        if (typeof v !== "object" || v === null || Array.isArray(v)) {
+            return false;
+        }
+        for (const [tag, values] of Object.entries(v)) {
+            const applied = (APPLIED_TAGS.has(tag) || TYPEDEF_TAGS.has(tag)) &&
+                !(TYPEDEF_TAGS.has(tag) && kinds[i] !== "Typedef") &&
+                !(tag === "instance_of" && kinds[i] !== "Instance");
+            if (applied ||
+                tag.length === 0 ||
+                !isTrimmed(tag) ||
+                !arrayOf(values, (t) => typeof t === "string" && isTrimmed(t))) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+/**
+ * The default scope of each synonym type the kept header declares (null: none declared).
+ * @param header - the kept header (tag to raw values)
+ * @returns the scopes by type
+ */
+function synonymTypeScopes(header) {
+    const out = new Map();
+    for (const raw of header.synonymtypedef ?? []) {
+        const tokens = tokenize(raw);
+        if (tokens.length > 0 && tokens[0].kind === "word") {
+            const scope = tokens.slice(1).find((t) => t.kind === "word" && SYNONYM_SCOPES.has(t.text));
+            out.set(tokens[0].text, scope?.text ?? null);
+        }
+    }
+    return out;
+}
+/**
+ * The record of an OBO import kept under `meta.extra.obo`, or empty records.
+ * @param snapshot - the snapshot
+ * @returns the header, the Typedefs and the unknown frames
+ */
+function keptObo(snapshot) {
+    const raw = snapshot.meta.extra.obo;
+    const record = typeof raw === "object" && raw !== null && !Array.isArray(raw) ? raw : {};
+    const clauses = (value) => {
+        const out = {};
+        if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+            for (const [tag, values] of Object.entries(value)) {
+                if (Array.isArray(values)) {
+                    out[tag] = values.filter((v) => typeof v === "string");
+                }
+            }
+        }
+        return out;
+    };
+    const typedefs = {};
+    if (typeof record.typedefs === "object" && record.typedefs !== null && !Array.isArray(record.typedefs)) {
+        for (const [id, frame] of Object.entries(record.typedefs)) {
+            typedefs[id] = clauses(frame);
+        }
+    }
+    const unknownFrames = Array.isArray(record.unknownFrames)
+        ? record.unknownFrames.flatMap((f) => typeof f === "object" && f !== null && typeof f.type === "string"
+            ? [{ type: f.type, clauses: clauses(f.clauses) }]
+            : [])
+        : [];
+    return { header: clauses(record.header), typedefs, unknownFrames };
+}
+/**
+ * Plan an export: the notes, the fatal condition and what is written.
+ * @param snapshot - the snapshot
+ * @param options - the caller's options
+ * @returns the plan
+ */
+function plan(snapshot, options) {
+    const common = resolveExportOptions(options);
+    const obo = resolveOboOptions(options);
+    const notes = [];
+    const note = (code, message, column = null, count = null) => {
+        notes.push(Object.freeze({ code, message, column, count }));
+    };
+    let fatal = null;
+    const { ids, originals, fatal: idFatal } = planIds(snapshot, common.sanitizeIds, note);
+    fatal ?? (fatal = idFatal);
+    const folding = pairFolding(snapshot);
+    const { written, edgeStart, edgeOrder, dst } = planEdges(snapshot, folding, common, note);
+    const frameless = framelessNodes(snapshot, written, {
+        outgoingAllowed: false,
+        changed: (i) => originals.has(i),
+    });
+    const moved = movedNodes(frameless, Array.from(edgeOrder, (e) => dst[e]));
+    if (moved > 0) {
+        note(NODE_ORDER_CODE, `${moved} node${plural(moved)} ${agree(moved, "reads", "read")} back at another position: placeholder nodes have no frame and read back after the written nodes`, null, moved);
+    }
+    const rows = [];
+    for (let i = 0; i < snapshot.nodeCount; i++) {
+        if (frameless[i] === 0) {
+            rows.push(i);
+        }
+    }
+    const { kinds, type } = planKinds(snapshot, frameless);
+    const typedefNodes = rows.filter((i) => kinds[i] === "Typedef").length;
+    if (typedefNodes > 0) {
+        note(OBO_LOSS.TYPEDEF_NODES, `${typedefNodes} node${plural(typedefNodes)} ${agree(typedefNodes, "is", "are")} written as [Typedef] frames; they read back as nodes only when imported with typedefs: "nodes", and then after the other nodes, with the [Typedef] frames that declare the relations`, "type", typedefNodes);
+    }
+    const kept = keptObo(snapshot);
+    const scopes = synonymTypeScopes(kept.header);
+    // the label: the label column, or a role-less name column
+    const labelSlot = slotColumn(snapshot.nodes, "label", "name");
+    const labelColumn = labelSlot.column;
+    const label = labelColumn !== null && rows.every((i) => !labelColumn.isSet(i) || isTrimmed(String(labelColumn.value(i))))
+        ? labelColumn
+        : null;
+    const tags = planTags(snapshot, rows, kinds, scopes, label);
+    fatal ?? (fatal = capabilityNotes(snapshot, common, {
+        caps: OBO_CAPABILITIES,
+        label,
+        labelAssumed: labelSlot.assumed,
+        edgeSlot: "a qualifier",
+        note,
+    }));
+    oboColumnNotes(snapshot, label, tags, note);
+    const properties = planProperties(snapshot, rows, frameless, label, tags, type, note);
+    // edges
+    const relationSlot = slotColumn(snapshot.edges, "kind", RELATION_COLUMN);
+    const relations = planRelations(snapshot, written, relationSlot.column, obo.relation, note);
+    if (relationSlot.assumed && relationSlot.column !== null) {
+        note(ROLE_ASSUMED_CODE, `edge column "${RELATION_COLUMN}" has no role, so it is taken as the relation of each edge: it is written as each line's relation, and reads back with the relation role ("kind")`, RELATION_COLUMN, relationSlot.column.length - relationSlot.column.nullCount);
+    }
+    const weights = explicitWeights(snapshot);
+    const { qualifiers, edgeColumns } = planEdgeColumns(snapshot, written, relationSlot.column, weights, note);
+    emptyColumnNotes(snapshot, rows, frameless, written, note);
+    const p = {
+        notes,
+        fatal,
+        options: obo,
+        ids,
+        originals,
+        frameless,
+        kinds,
+        label,
+        tags,
+        properties,
+        edgeStart,
+        edgeOrder,
+        dst,
+        relations,
+        qualifiers,
+        edgeColumns,
+        weights,
+        header: [],
+        tail: [],
+    };
+    // write every frame once: the duplicate clauses, the line ends and the qualifier placement
+    let stats = simulate(p, rows);
+    if (!stats.qualifiersPlaced) {
+        tags.delete("obo.qualifiers");
+        const column = snapshot.nodes.get("obo.qualifiers");
+        if (column !== null) {
+            properties.push({ column, relation: "obo.qualifiers" });
+            notePropertyColumn(note, column, rows, "property_value lines (relation obo.qualifiers)");
+        }
+        stats = simulate(p, rows);
+    }
+    if (stats.duplicates > 0) {
+        note(OBO_LOSS.DUPLICATE_CLAUSE, `${stats.duplicates} clause${plural(stats.duplicates)} ${agree(stats.duplicates, "repeats", "repeat")} another clause of their frame word for word (parallel edges with one relation and the same qualifiers, a repeated list item) and read back as one`, null, stats.duplicates);
+    }
+    const header = planHeader(snapshot, kept.header, obo, rows, tags, note, stats);
+    const tail = planTail({
+        kept,
+        rows,
+        kinds,
+        ids,
+        properties,
+        relations,
+        edges: edgeOrder,
+        xref: tags.get("xref") ?? null,
+    });
+    if (stats.lineEnds > 0) {
+        note(OBO_LOSS.LINE_END, `${stats.lineEnds} text${plural(stats.lineEnds)} ${agree(stats.lineEnds, "holds", "hold")} a carriage return or form feed, which OBO cannot carry; written as a line feed`, null, stats.lineEnds);
+    }
+    return { ...p, header, tail };
+}
+/**
+ * The vocabulary columns written as their tags: each one tagCarries() accepts, then the pairs
+ * resolved (def.xrefs needs def, a def needs its def.xrefs written when that column exists, the
+ * xref descriptions need their xrefs written).
+ * @param snapshot - the snapshot
+ * @param rows - the written nodes
+ * @param kinds - the frame types
+ * @param scopes - the default scope of each declared synonym type
+ * @param label - the label column (never a tag)
+ * @returns the columns by tag
+ */
+function planTags(snapshot, rows, kinds, scopes, label) {
+    const tags = new Map();
+    for (const name of TAG_COLUMNS) {
+        const column = snapshot.nodes.get(name);
+        if (column === null || column === label || (column.meta.role !== null && column.meta.role !== "label")) {
+            continue;
+        }
+        if (name === UNRECOGNIZED
+            ? unrecognizedCarried(column, rows, kinds)
+            : tagCarries(name, column, rows, kinds, scopes)) {
+            tags.set(name, column);
+        }
+    }
+    // pairs: def.xrefs needs def; xref.descriptions needs its xrefs written
+    const def = tags.get("def");
+    const defXrefs = tags.get("def.xrefs");
+    if (defXrefs !== undefined && (def === undefined || rows.some((i) => def.isSet(i) !== defXrefs.isSet(i)))) {
+        tags.delete("def.xrefs");
+    }
+    if (def !== undefined && !tags.has("def.xrefs") && snapshot.nodes.get("def.xrefs") !== null) {
+        // a def.xrefs column that is not written would read back as the empty list on every def
+        tags.delete("def");
+    }
+    const descriptions = tags.get("xref.descriptions");
+    if (descriptions !== undefined && !rows.every((i) => describedXrefsWritten(tags, descriptions, i))) {
+        tags.delete("xref.descriptions");
+    }
+    return tags;
+}
+/**
+ * Whether every described xref of a node is written in one of its xref slots (so the description
+ * has a place).
+ * @param tags - the columns written as tags
+ * @param descriptions - the `xref.descriptions` column
+ * @param row - the node
+ * @returns true when every description has its xref
+ */
+function describedXrefsWritten(tags, descriptions, row) {
+    const map = cellOf(descriptions, row);
+    if (map === undefined) {
+        return true;
+    }
+    const written = new Set();
+    const add = (values) => {
+        if (Array.isArray(values)) {
+            for (const v of values) {
+                if (typeof v === "string") {
+                    written.add(v);
+                }
+            }
+        }
+    };
+    for (const name of ["def.xrefs", "xref"]) {
+        const column = tags.get(name);
+        if (column !== undefined) {
+            add(cellOf(column, row));
+        }
+    }
+    for (const name of ["synonym", "expand_assertion_to", "expand_expression_to"]) {
+        const column = tags.get(name);
+        const items = column === undefined ? undefined : cellOf(column, row);
+        if (Array.isArray(items)) {
+            for (const item of items) {
+                add(item.xrefs);
+            }
+        }
+    }
+    return Object.keys(map).every((id) => written.has(id));
+}
+/**
+ * The OBO-only column notes: the vocabulary column of the other text dtype, and the graph columns
+ * written as header property values.
+ * @param snapshot - the snapshot
+ * @param label - the label column written as `name`, or null
+ * @param tags - the vocabulary columns written as tags
+ * @param note - records a note
+ */
+function oboColumnNotes(snapshot, label, tags, note) {
+    for (const [name, column] of [...tags, ...(label === null ? [] : [["name", label]])]) {
+        const want = name === "name" ? "string" : OBO_NODE_COLUMNS[name].dtype;
+        if (((want === "string" || want === "dict") && column.dtype !== want) ||
+            (column.dtype === "list" && column.child.dtype !== "string")) {
+            const held = column.dtype === "list" ? `${column.child.dtype} items` : column.dtype;
+            note(LOSS.DTYPE, `node column "${column.meta.name}" holds ${held}; it reads back as ${column.dtype === "list" ? "string items" : want}`, column.meta.name, column.length - column.nullCount);
+        }
+    }
+    for (const column of snapshot.graph) {
+        note(GRAPH_COLUMN_AS_METADATA_CODE, `graph column "${column.meta.name}" is written as a header property_value and reads back in meta.extra.obo.header, not as a column`, column.meta.name, column.length - column.nullCount);
+    }
+}
+/**
+ * The node columns written as `property_value` lines: every column that is not written by a tag,
+ * the label or the type, and not one OBO leaves out (positions, visual and temporal columns), each
+ * with its note.
+ * @param snapshot - the snapshot
+ * @param rows - the written nodes
+ * @param frameless - the frameless flags
+ * @param label - the label column
+ * @param tags - the columns written as tags
+ * @param type - the type column
+ * @param note - records a note
+ * @returns the columns
+ */
+function planProperties(snapshot, rows, frameless, label, tags, type, note) {
+    const out = [];
+    const slotted = new Set([
+        ...tags.values(),
+        ...(label === null ? [] : [label]),
+        ...(type === null ? [] : [type]),
+    ]);
+    for (const column of snapshot.nodes) {
+        const { role, name } = column.meta;
+        if (slotted.has(column) || (role !== null && UNWRITTEN_ROLES.has(role))) {
+            continue;
+        }
+        if (name === PLACEHOLDER_COLUMN && rows.every((i) => !column.isSet(i)) && frameless.includes(1)) {
+            // read back from the frameless nodes alone
+            continue;
+        }
+        const relation = isOboWord(name) && name !== ORIGINAL_ID ? name : wordOf(name.replaceAll(":", "_"));
+        out.push({ column, relation });
+        notePropertyColumn(note, column, rows, `property_value lines (relation ${relation})`);
+    }
+    return out;
+}
+/**
+ * The relation written for each edge, with the notes of the assumed and renamed ones.
+ * @param snapshot - the snapshot
+ * @param written - the written edges
+ * @param relation - the relation column, or null
+ * @param fallback - the relation of an edge without one
+ * @param note - records a note
+ * @returns the relation per edge index
+ */
+function planRelations(snapshot, written, relation, fallback, note) {
+    const out = new Array(snapshot.edgeCount).fill(fallback);
+    let assumed = 0;
+    let renamed = 0;
+    for (const e of written) {
+        const value = relation === null ? undefined : cellOf(relation, e);
+        if (typeof value !== "string") {
+            assumed++;
+            continue;
+        }
+        if (isOboWord(value)) {
+            out[e] = value;
+        }
+        else {
+            out[e] = wordOf(value);
+            renamed++;
+        }
+    }
+    if (assumed > 0) {
+        note(OBO_LOSS.RELATION_ASSUMED, `${assumed} edge${plural(assumed)} ${agree(assumed, "has", "have")} no relation; written as ${fallback} (an ontology reads is_a as subclassing)`, relation?.meta.name ?? null, assumed);
+    }
+    if (renamed > 0) {
+        note(OBO_LOSS.RELATION_RENAMED, `${renamed} relation${plural(renamed)} ${agree(renamed, "is", "are")} not OBO ids; written with "_" in place of the space, "!", "{" or "}"`, relation?.meta.name ?? null, renamed);
+    }
+    return out;
+}
+/**
+ * The edge columns written as qualifiers: the vocabulary `qualifiers` column when its cells are
+ * qualifier records, every other edge column (and the explicit weights) as `name="value"` pairs,
+ * each with its note.
+ * @param snapshot - the snapshot
+ * @param written - the written edges
+ * @param relation - the relation column
+ * @param weights - the explicit weights
+ * @param note - records a note
+ * @returns the qualifiers column and the other columns
+ */
+function planEdgeColumns(snapshot, written, relation, weights, note) {
+    const qualifiers = qualifierRecords(snapshot, written);
+    const edgeColumns = [];
+    const count = (column) => written.filter((e) => column.isSet(e)).length;
+    const merged = qualifiers === null ? "" : " (merged with its values)";
+    for (const column of snapshot.edges) {
+        const { role, name } = column.meta;
+        if (column === relation ||
+            column === qualifiers ||
+            role === "id" ||
+            (role !== null && UNWRITTEN_ROLES.has(role))) {
+            continue;
+        }
+        const written2 = isQualifierName(name) ? name : wordOf(name.replaceAll(/[=",[\]\\]/g, "_"));
+        edgeColumns.push({ column, name: written2 });
+        const n = count(column);
+        if (n > 0) {
+            note(OBO_LOSS.EDGE_COLUMN_AS_QUALIFIER, `edge column "${name}" is written as the qualifier ${written2} and reads back inside the qualifiers column${merged}`, name, n);
+        }
+    }
+    const explicit = weights.weighted ? written.filter((e) => weights.isExplicit(e)).length : 0;
+    if (explicit > 0) {
+        note(OBO_LOSS.EDGE_COLUMN_AS_QUALIFIER, `${explicit} explicit edge weight${plural(explicit)} ${agree(explicit, "is", "are")} written as the qualifier ${WEIGHT_QUALIFIER} and read back inside the qualifiers column, not as weights`, snapshot.edges.byRole("weight")?.meta.name ?? null, explicit);
+    }
+    return { qualifiers, edgeColumns };
+}
+/**
+ * The vocabulary `qualifiers` edge column, when every written cell of it is a qualifier record.
+ * @param snapshot - the snapshot
+ * @param written - the written edges
+ * @returns the column, or null when there is none or it holds something else
+ */
+function qualifierRecords(snapshot, written) {
+    const qualifiers = snapshot.edges.get(QUALIFIERS_COLUMN);
+    if (qualifiers?.dtype !== "json" || qualifiers.meta.role !== null) {
+        return null;
+    }
+    const records = written.every((e) => !qualifiers.isSet(e) || isQualifierRecord(cellOf(qualifiers, e), isQualifierName));
+    return records ? qualifiers : null;
+}
+/**
+ * The header lines: the kept header in the guide's order with the missing fields filled from the
+ * metadata, and the graph columns as `property_value` lines.
+ * @param snapshot - the snapshot
+ * @param kept - the kept header
+ * @param obo - the OBO options
+ * @param obo.ontology - the ontology option, or null
+ * @param rows - the written nodes
+ * @param tags - the columns written as tags
+ * @param note - records a note
+ * @param stats - the line-end counter
+ * @returns the lines
+ */
+function planHeader(snapshot, kept, obo, rows, tags, note, stats) {
+    const { values, filled } = headerFields(snapshot, kept, obo.ontology, note);
+    // a default namespace applies to every frame without one: keep it only when none lacks one
+    const namespace = tags.get("namespace");
+    if (values.has("default-namespace") && (namespace === undefined || rows.some((i) => !namespace.isSet(i)))) {
+        values.delete("default-namespace");
+    }
+    const lines = [];
+    // the filled fields in the guide's order, then the kept ones as the file had them
+    const tagsInOrder = [
+        ...HEADER_ORDER.filter((t) => filled.has(t)),
+        ...[...values.keys()].filter((t) => !filled.has(t)),
+    ];
+    for (const tag of tagsInOrder) {
+        for (const value of values.get(tag) ?? []) {
+            lines.push(`${escapeTag(tag)}: ${value}`);
+        }
+    }
+    if (lines.length === 0 && rows.length === 0) {
+        // a file of nothing reads back as an empty input: the version line makes it an empty ontology
+        lines.push("format-version: 1.4");
+    }
+    for (const column of snapshot.graph) {
+        const relation = isOboWord(column.meta.name) ? column.meta.name : wordOf(column.meta.name);
+        for (const line of propertyLines({ column, relation }, 0, stats)) {
+            lines.push(`property_value: ${line}`);
+        }
+    }
+    return lines;
+}
+/**
+ * The header fields: the kept ones, and for a graph not read from OBO the fields its metadata has.
+ * @param snapshot - the snapshot
+ * @param kept - the kept header
+ * @param ontologyOption - the ontology option, or null
+ * @param note - records a note
+ * @returns the values by tag, and the tags filled in (not kept)
+ */
+function headerFields(snapshot, kept, ontologyOption, note) {
+    const { meta } = snapshot;
+    const values = new Map(Object.entries(kept).map(([tag, v]) => [tag, v.map(rawValue)]));
+    const filled = new Set();
+    const fill = (tag, value) => {
+        if (value !== null && !values.has(tag)) {
+            values.set(tag, [value]);
+            filled.add(tag);
+        }
+    };
+    // a file read from OBO keeps its own header; any other graph gets the fields its metadata has
+    if (meta.sourceFormat !== "obo") {
+        fill("format-version", "1.4");
+        fill("date", oboDate(meta.created));
+        fill("saved-by", meta.creator === null ? null : escapeOboValue(meta.creator));
+    }
+    const ontology = ontologyField(ontologyOption, meta.name, values.has("ontology"), note);
+    if (ontology !== null) {
+        if (!values.has("ontology")) {
+            filled.add("ontology");
+        }
+        values.set("ontology", [ontology]);
+    }
+    return { values, filled };
+}
+/**
+ * The ontology header field to write: the ontology option, else the graph name when it is an
+ * ontology id, else the name rewritten with "_" when the kept header has none.
+ * @param option - the ontology option, or null
+ * @param name - the graph name, or null
+ * @param kept - whether the kept header has an ontology field
+ * @param note - records a note
+ * @returns the value to set, or null to leave the field as it is
+ */
+function ontologyField(option, name, kept, note) {
+    if (option !== null) {
+        return option;
+    }
+    if (name === null || name.length === 0 || kept) {
+        return null;
+    }
+    if (/^[A-Za-z0-9_.\-/]+$/.test(name)) {
+        return name;
+    }
+    const slug = name.replaceAll(/[^A-Za-z0-9_.-]/g, "_");
+    note(OBO_LOSS.ONTOLOGY_NAME, `the graph name ${JSON.stringify(name)} is not an ontology id; written as ${slug}`, null, null);
+    return slug;
+}
+/**
+ * A kept raw value made safe for one line (a line break in metadata a caller built becomes `\n`).
+ * @param raw - the raw value
+ * @returns the value to write
+ */
+function rawValue(raw) {
+    return raw.replaceAll(/\r\n|\r|\n|\f/g, String.raw `\n`);
+}
+/**
+ * A tag name escaped for the left of its colon.
+ * @param tag - the tag
+ * @returns the escaped tag
+ */
+function escapeTag(tag) {
+    return escapeOboValue(tag).replaceAll(":", String.raw `\:`);
+}
+/**
+ * An ISO date (`yyyy-MM-ddTHH:mm...`) as the OBO header date `dd:MM:yyyy HH:mm`.
+ * @param iso - the date, or null
+ * @returns the header text, or null when the date is not of that form
+ */
+function oboDate(iso) {
+    const m = iso === null ? null : /^(\d{4})-(\d{2})-(\d{2})(?:T(\d{2}):(\d{2}))?/.exec(iso);
+    if (m === null) {
+        return null;
+    }
+    return `${m[3]}:${m[2]}:${m[1]} ${m[4] ?? "00"}:${m[5] ?? "00"}`;
+}
+/**
+ * The frames after the nodes: the kept Typedefs (unless a node is that Typedef), a declaration of
+ * every relation and property-value relation no Typedef declares, and the kept unknown frames.
+ * @param input - what the frames are planned from
+ * @returns the lines
+ */
+function planTail(input) {
+    const { kept, rows, properties, relations } = input;
+    const lines = [];
+    const declared = nodeTypedefs(input);
+    keptTypedefLines(kept.typedefs, declared, lines);
+    const declare = (relation, metadata) => {
+        if (declared.has(relation)) {
+            return;
+        }
+        declared.add(relation);
+        lines.push("", "[Typedef]", `id: ${escapeOboWord(relation)}`, `name: ${escapeOboValue(relation)}`);
+        if (metadata) {
+            lines.push("is_metadata_tag: true");
+        }
+    };
+    const used = new Set();
+    for (const e of input.edges) {
+        used.add(relations[e]);
+    }
+    for (const { column, relation } of properties) {
+        if (rows.some((i) => column.isSet(i))) {
+            declare(relation, true);
+        }
+    }
+    for (const relation of used) {
+        declare(relation, false);
+    }
+    for (const frame of kept.unknownFrames) {
+        lines.push("", `[${frame.type.replaceAll(/[\]\r\n]/g, "_")}]`, ...clauseLines(frame.clauses));
+    }
+    return lines;
+}
+/**
+ * The relations the built-in ones, the Typedef nodes and their xrefs declare.
+ * @param input - what the frames are planned from
+ * @returns the declared relation ids
+ */
+function nodeTypedefs(input) {
+    const { rows, kinds, ids, xref } = input;
+    const declared = new Set(BUILTIN_RELATIONS);
+    for (const i of rows) {
+        if (kinds[i] !== "Typedef") {
+            continue;
+        }
+        declared.add(ids[i]);
+        const xrefs = xref === null ? undefined : cellOf(xref, i);
+        for (const x of Array.isArray(xrefs) ? xrefs : []) {
+            declared.add(String(x));
+        }
+    }
+    return declared;
+}
+/**
+ * Write the kept Typedef frames no node already declares, and declare them and their xrefs.
+ * @param typedefs - the kept Typedef frames by id
+ * @param declared - the declared relations, added to
+ * @param lines - the lines, appended to
+ */
+function keptTypedefLines(typedefs, declared, lines) {
+    for (const [id, clauses] of Object.entries(typedefs)) {
+        if (declared.has(id) && !BUILTIN_RELATIONS.has(id)) {
+            continue;
+        }
+        declared.add(id);
+        lines.push("", "[Typedef]", `id: ${escapeOboWord(id)}`, ...clauseLines(clauses, "id"));
+        for (const xref of clauses.xref ?? []) {
+            declared.add(xref.trim());
+        }
+    }
+}
+/**
+ * The clause lines of a kept frame, each value made safe for one line.
+ * @param clauses - the values by tag
+ * @param skip - a tag to leave out, or null
+ * @returns the lines
+ */
+function clauseLines(clauses, skip = null) {
+    return Object.entries(clauses)
+        .filter(([tag]) => tag !== skip)
+        .flatMap(([tag, values]) => values.map((value) => `${escapeTag(tag)}: ${rawValue(value)}`));
+}
+// ============================================================ the frames
+/** Hands out the `obo.qualifiers` entries of one frame to the clauses they belong to, in order. */
+class QualifierCursor {
+    /**
+     * Create a cursor.
+     * @param cell - the frame's `obo.qualifiers` cell, or undefined
+     */
+    constructor(cell) {
+        this.next = new Map();
+        this.entries = (cell ?? {});
+    }
+    /**
+     * The qualifier block of a clause: the next entry of its tag when that entry is for this value.
+     * @param tag - the tag (or `<tag>.xrefs` for an xref inside a list)
+     * @param value - the clause's value as the column holds it
+     * @returns the block with a leading space, or ""
+     */
+    block(tag, value) {
+        const list = Object.hasOwn(this.entries, tag) ? this.entries[tag] : undefined;
+        const k = this.next.get(tag) ?? 0;
+        if (list === undefined || k >= list.length || list[k].value !== value) {
+            return "";
+        }
+        this.next.set(tag, k + 1);
+        return qualifierBlock(qualifierPairs(list[k].qualifiers));
+    }
+    /**
+     * Whether every entry found its clause.
+     * @returns true when all were placed
+     */
+    placed() {
+        return Object.entries(this.entries).every(([tag, list]) => (this.next.get(tag) ?? 0) === list.length);
+    }
+}
+/**
+ * Count a text that loses a line end, and return it.
+ * @param s - the frame state's stats
+ * @param text - the text
+ * @returns the text
+ */
+function counted(s, text) {
+    if (hasLineEnd(text)) {
+        s.lineEnds++;
+    }
+    return text;
+}
+/**
+ * One xref as written inside a list or after `xref:`: its id, its description the first time the
+ * frame names it, and its own qualifiers.
+ * @param f - the frame state
+ * @param id - the xref id
+ * @param listTag - the `<tag>.xrefs` key of its qualifiers, or null after `xref:`
+ * @returns the text
+ */
+function xrefText(f, id, listTag) {
+    let out = escapeOboValue(counted(f.stats, id));
+    const descriptions = f.p.tags.get("xref.descriptions");
+    const map = descriptions === undefined ? undefined : cellOf(descriptions, f.row);
+    if (map !== undefined && Object.hasOwn(map, id) && !f.described.has(id)) {
+        f.described.add(id);
+        out += ` "${escapeOboQuoted(counted(f.stats, map[id]))}"`;
+    }
+    if (listTag !== null) {
+        out += f.cursor.block(listTag, id);
+    }
+    return out;
+}
+/**
+ * An xref list: `[A:1, B:2 "description"]`.
+ * @param f - the frame state
+ * @param ids - the xref ids
+ * @param tag - the clause's tag
+ * @returns the list
+ */
+function xrefList(f, ids, tag) {
+    const field = `${tag}.xrefs`;
+    return `[${ids.map((id) => xrefText(f, id, field)).join(", ")}]`;
+}
+/**
+ * The `property_value` values of one cell of a property column: `relation "value" xsd:type` per
+ * value (a list item each, JSON text for nested values).
+ * @param prop - the column and its relation
+ * @param row - the row
+ * @param stats - the line-end counter
+ * @returns the values after `property_value: `
+ */
+function propertyLines(prop, row, stats) {
+    const { column, relation } = prop;
+    const value = cellOf(column, row);
+    if (value === undefined) {
+        return [];
+    }
+    const head = escapeOboWord(relation);
+    const one = (v, dtype) => {
+        let text;
+        let xsd = XSD[dtype] ?? "xsd:string";
+        if (typeof v === "number" && xsd === "xsd:double") {
+            text = xsdDouble(v, dtype);
+        }
+        else if (typeof v === "string" || typeof v === "boolean" || typeof v === "number") {
+            text = textOf(v, dtype);
+        }
+        else {
+            text = JSON.stringify(v) ?? "null";
+            xsd = "xsd:string";
+        }
+        return `${head} "${escapeOboQuoted(counted(stats, text))}" ${xsd}`;
+    };
+    if (column.dtype === "list") {
+        return value.map((item) => one(item, column.child.dtype));
+    }
+    if (column.dtype === "json" || column.meta.components > 1) {
+        return [one(value, "json")];
+    }
+    return [one(value, column.dtype)];
+}
+/**
+ * A double as xsd:double writes it: INF, -INF and NaN for the non-finite values.
+ * @param v - the value
+ * @param dtype - the column dtype (f32 values use their shortest text)
+ * @returns the text
+ */
+function xsdDouble(v, dtype) {
+    if (Number.isNaN(v)) {
+        return "NaN";
+    }
+    if (!Number.isFinite(v)) {
+        return v > 0 ? "INF" : "-INF";
+    }
+    return formatNumber(v, dtype === "f32" ? "f32" : "f64");
+}
+/**
+ * The qualifier block of one edge: the `qualifiers` record, then the other columns and the weight.
+ * @param f - the frame state
+ * @param e - the edge
+ * @returns the block with a leading space, or ""
+ */
+function edgeQualifiers(f, e) {
+    const { p } = f;
+    const pairs = [];
+    if (p.qualifiers !== null) {
+        const record = cellOf(p.qualifiers, e);
+        if (record !== undefined) {
+            pairs.push(...qualifierPairs(record));
+        }
+    }
+    for (const { column, name } of p.edgeColumns) {
+        pairs.push(...qualifierTexts(column, e).map((text) => [name, text]));
+    }
+    const weight = p.weights.text(e);
+    if (weight !== null) {
+        pairs.push([WEIGHT_QUALIFIER, weight]);
+    }
+    for (const [, value] of pairs) {
+        counted(f.stats, value);
+    }
+    return qualifierBlock(pairs);
+}
+/**
+ * The qualifier values an edge column gives one edge: one per item of a list, none when unset.
+ * @param column - the edge column
+ * @param e - the edge
+ * @returns the value texts
+ */
+function qualifierTexts(column, e) {
+    const value = cellOf(column, e);
+    if (value === undefined) {
+        return [];
+    }
+    if (column.dtype === "list") {
+        return value.map((item) => textOf(item, column.child.dtype));
+    }
+    return [column.dtype === "json" ? (JSON.stringify(value) ?? "null") : textOf(value, column.dtype)];
+}
+/**
+ * The clauses of one tag column on a frame.
+ * @param f - the frame state
+ * @param tag - the tag
+ * @param column - the column
+ * @param out - the lines
+ */
+function tagLines(f, tag, column, out) {
+    const value = cellOf(column, f.row);
+    if (value === undefined) {
+        return;
+    }
+    const { cursor, stats } = f;
+    const push = (text, stored, raw = false) => {
+        out.push(`${tag}: ${raw ? text : escapeOboValue(counted(stats, text))}${cursor.block(tag, stored)}`);
+    };
+    if (TEXT_TAGS.has(tag)) {
+        push(value, value);
+        return;
+    }
+    if (BOOL_TAGS.has(tag)) {
+        push(value ? "true" : "false", value ? "true" : "false", true);
+        return;
+    }
+    if (ID_LIST_TAGS.has(tag)) {
+        for (const id of value) {
+            push(escapeOboWord(id), id, true);
+        }
+        return;
+    }
+    // def.xrefs, xref.descriptions and obo.qualifiers are written with the clauses they belong to
+    if (Object.hasOwn(STRUCTURED_TAGS, tag)) {
+        STRUCTURED_TAGS[tag](f, tag, value, out);
+    }
+}
+/**
+ * The qualifier block of a structured value.
+ * @param qualifiers - the value's qualifiers, or undefined
+ * @returns the block with a leading space, or ""
+ */
+function blockOf(qualifiers) {
+    return qualifiers === undefined ? "" : qualifierBlock(qualifierPairs(qualifiers));
+}
+/** The writers of the tags whose cells hold more than a text, an id list or a boolean. */
+const STRUCTURED_TAGS = {
+    def(f, _tag, value, out) {
+        const xrefs = f.p.tags.get("def.xrefs");
+        const ids = (xrefs === undefined ? [] : (cellOf(xrefs, f.row) ?? []));
+        const text = value;
+        out.push(`def: "${escapeOboQuoted(counted(f.stats, text))}" ${xrefList(f, ids, "def")}${f.cursor.block("def", text)}`);
+    },
+    xref(f, _tag, value, out) {
+        for (const id of value) {
+            out.push(`xref: ${xrefText(f, id, null)}${f.cursor.block("xref", id)}`);
+        }
+    },
+    synonym(f, _tag, value, out) {
+        for (const s of value) {
+            const type = s.type === null ? "" : ` ${escapeOboWord(s.type)}`;
+            out.push(`synonym: "${escapeOboQuoted(counted(f.stats, s.text))}" ${s.scope}${type} ${xrefList(f, s.xrefs, "synonym")}${blockOf(s.qualifiers)}`);
+        }
+    },
+    intersection_of(_f, _tag, value, out) {
+        for (const x of value) {
+            const relation = x.relation === null ? "" : `${escapeOboWord(x.relation)} `;
+            out.push(`intersection_of: ${relation}${escapeOboWord(x.target)}${blockOf(x.qualifiers)}`);
+        }
+    },
+    property_value(f, _tag, value, out) {
+        for (const x of value) {
+            const datatype = x.datatype === null ? "" : ` ${escapeOboWord(x.datatype)}`;
+            const literal = x.datatype === null && isOboWord(x.value)
+                ? escapeOboWord(x.value)
+                : `"${escapeOboQuoted(counted(f.stats, x.value))}"${datatype}`;
+            out.push(`property_value: ${escapeOboWord(x.relation)} ${literal}${blockOf(x.qualifiers)}`);
+        }
+    },
+    holds_over_chain: chainLines,
+    equivalent_to_chain: chainLines,
+    expand_assertion_to: expansionLines,
+    expand_expression_to: expansionLines,
+    [UNRECOGNIZED](f, _tag, value, out) {
+        for (const [unknown, values] of Object.entries(value)) {
+            for (const v of values) {
+                out.push(`${escapeTag(unknown)}: ${escapeOboValue(counted(f.stats, v))}`);
+            }
+        }
+    },
+};
+/**
+ * The clauses of a relation chain tag (`holds_over_chain`, `equivalent_to_chain`).
+ * @param f - the frame state
+ * @param tag - the tag
+ * @param value - the cell: pairs of relations
+ * @param out - the lines
+ */
+function chainLines(f, tag, value, out) {
+    for (const [a, b] of value) {
+        const pair = `${a} ${b}`;
+        out.push(`${tag}: ${escapeOboWord(a)} ${escapeOboWord(b)}${f.cursor.block(tag, pair)}`);
+    }
+}
+/**
+ * The clauses of a macro expansion tag (`expand_assertion_to`, `expand_expression_to`).
+ * @param f - the frame state
+ * @param tag - the tag
+ * @param value - the cell: templates with their xrefs
+ * @param out - the lines
+ */
+function expansionLines(f, tag, value, out) {
+    for (const x of value) {
+        out.push(`${tag}: "${escapeOboQuoted(counted(f.stats, x.template))}" ${xrefList(f, x.xrefs, tag)}${blockOf(x.qualifiers)}`);
+    }
+}
+/**
+ * The lines of one node's frame.
+ * @param p - the plan
+ * @param row - the node
+ * @param stats - the counters
+ * @returns the lines, the frame header first
+ */
+function frameLines(p, row, stats) {
+    const qualifiersColumn = p.tags.get("obo.qualifiers");
+    const f = {
+        p,
+        row,
+        cursor: new QualifierCursor(qualifiersColumn === undefined ? undefined : cellOf(qualifiersColumn, row)),
+        described: new Set(),
+        stats,
+    };
+    const out = [`[${p.kinds[row]}]`, `id: ${escapeOboWord(p.ids[row])}`];
+    for (const tag of TAG_ORDER) {
+        if (tag === "name") {
+            nameLine(f, out);
+        }
+        else if (tag === "property_value") {
+            propertyValueLines(f, out);
+        }
+        else if (tag === EDGES) {
+            edgeLines(f, out);
+        }
+        else {
+            const column = p.tags.get(tag);
+            if (column !== undefined) {
+                tagLines(f, tag, column, out);
+            }
+        }
+    }
+    stats.qualifiersPlaced && (stats.qualifiersPlaced = f.cursor.placed());
+    return out;
+}
+/**
+ * The name clause of a frame, from the label column.
+ * @param f - the frame state
+ * @param out - the lines
+ */
+function nameLine(f, out) {
+    const name = f.p.label === null ? undefined : cellOf(f.p.label, f.row);
+    if (typeof name === "string") {
+        out.push(`name: ${escapeOboValue(counted(f.stats, name))}${f.cursor.block("name", name)}`);
+    }
+}
+/**
+ * The property_value clauses of a frame: the original id of a rewritten one, the property_value
+ * column, then the property-value columns.
+ * @param f - the frame state
+ * @param out - the lines
+ */
+function propertyValueLines(f, out) {
+    const { p, row } = f;
+    const original = p.originals.get(row);
+    if (original !== undefined) {
+        // as JSON text, so a carriage return in the original survives
+        out.push(`property_value: ${ORIGINAL_ID} "${escapeOboQuoted(JSON.stringify(original))}" xsd:string`);
+    }
+    const column = p.tags.get("property_value");
+    if (column !== undefined) {
+        tagLines(f, "property_value", column, out);
+    }
+    for (const prop of p.properties) {
+        for (const line of propertyLines(prop, row, f.stats)) {
+            out.push(`property_value: ${line}`);
+        }
+    }
+}
+/**
+ * The edge clauses of a frame: `is_a` (and `instance_of` on an Instance) as their own tags, any
+ * other relation as a `relationship` clause.
+ * @param f - the frame state
+ * @param out - the lines
+ */
+function edgeLines(f, out) {
+    const { p, row } = f;
+    for (let k = p.edgeStart[row]; k < p.edgeStart[row + 1]; k++) {
+        const e = p.edgeOrder[k];
+        const target = escapeOboWord(p.ids[p.dst[e]]);
+        const relation = p.relations[e];
+        const block = edgeQualifiers(f, e);
+        if (relation === "is_a" || (relation === "instance_of" && p.kinds[row] === "Instance")) {
+            out.push(`${relation}: ${target}${block}`);
+        }
+        else {
+            out.push(`relationship: ${escapeOboWord(relation)} ${target}${block}`);
+        }
+    }
+}
+/**
+ * Write every frame once without keeping the text: count the clauses that repeat another of their
+ * frame (the importer reads them as one), the line ends and whether the qualifiers were placed.
+ * @param p - the plan
+ * @param rows - the written nodes
+ * @returns the counts
+ */
+function simulate(p, rows) {
+    const stats = { lineEnds: 0, qualifiersPlaced: true, duplicates: 0 };
+    for (const i of rows) {
+        const lines = frameLines(p, i, stats);
+        const seen = new Set();
+        for (let k = 2; k < lines.length; k++) {
+            if (seen.has(lines[k])) {
+                stats.duplicates++;
+            }
+            seen.add(lines[k]);
+        }
+    }
+    return stats;
+}
+/**
+ * The text parts of the file: the header, one frame per written node, the tail frames.
+ * @param p - the plan
+ * @yields the header and one part per frame
+ * @returns nothing
+ */
+function* write(p) {
+    if (p.fatal !== null) {
+        throw p.fatal;
+    }
+    yield p.header.map((line) => `${line}\n`).join("");
+    const stats = { lineEnds: 0, qualifiersPlaced: true };
+    for (let i = 0; i < p.ids.length; i++) {
+        if (p.frameless[i] === 0) {
+            yield `\n${frameLines(p, i, stats).join("\n")}\n`;
+        }
+    }
+    if (p.tail.length > 0) {
+        yield `${p.tail.join("\n")}\n`;
+    }
+}
+/**
+ * The text parts of an export, planned when the first part is asked for, so a refused option
+ * rejects the export instead of throwing from the call.
+ * @param snapshot - the snapshot
+ * @param options - format-specific and common options
+ * @yields the parts
+ * @returns nothing
+ */
+function* written(snapshot, options) {
+    yield* write(plan(snapshot, options));
+}
+/**
+ * The OBO exporter plugin.
+ * @category Built-in formats
+ */
+export const oboExporter = Object.freeze({
+    format: "obo",
+    options: Object.freeze(["ontology", "relation"]),
+    capabilities: OBO_CAPABILITIES,
+    /**
+     * Pre-flight: what export() would lose, without writing anything.
+     * @param snapshot - the snapshot
+     * @param options - format-specific and common options
+     * @returns the notes, empty when the export is exact
+     */
+    check(snapshot, options) {
+        return Object.freeze([...plan(snapshot, options).notes]);
+    },
+    /**
+     * Write the file as UTF-8 chunks.
+     * @param snapshot - the snapshot
+     * @param options - format-specific and common options
+     * @returns the chunks
+     */
+    export(snapshot, options) {
+        return encodeChunks(written(snapshot, options));
+    },
+    /**
+     * Write the file as one string.
+     * @param snapshot - the snapshot
+     * @param options - format-specific and common options
+     * @returns the file
+     */
+    exportToString(snapshot, options) {
+        return joinText(written(snapshot, options));
+    },
+});
+//# sourceMappingURL=exporter.js.map