linked-rolls 0.70.0 → 0.72.0

package/lib/filiation/search.js

@@ -0,0 +1,268 @@
+import { leadsTo, systemAbove } from "./systems.js";
+import { stemmataOf } from "./trees.js";
+/**
+ * The costs the edition of WM 225 is reproduced with: a gain 10, a lost
+ * redundancy 0.25, a loss on a transfer 0.25, a deviation of a copy 1
+ * and a lost state 4. They were found by searching for values that give
+ * that stemma, so they say that it is consistent with such rules, not
+ * that the rules confirm it.
+ * @category Filiation
+ */
+export const defaultCosts = {
+    gain: 10,
+    redundantLoss: 0.25,
+    transferLoss: 0.25,
+    copyDeviation: 1,
+    lostState: 4
+};
+const INF = 1e12;
+const lay = (tree, systems, names, transfers) => {
+    const copy = [];
+    const parent = [];
+    const system = [];
+    const below = [];
+    let lost = 0;
+    const visit = (node) => {
+        const visited = [];
+        for (const child of node.children) {
+            const done = visit(child);
+            if (!done)
+                return undefined;
+            visited.push(done);
+        }
+        const under = new Set(visited.flatMap(child => [...child.systems]));
+        let own;
+        if (node.copy !== undefined) {
+            own = systems[node.copy];
+            // A copy carrying a version above others is of a system that leads to theirs.
+            if ([...under].some(other => !leadsTo(transfers, own, other)))
+                return undefined;
+        }
+        else {
+            own = systemAbove(transfers, under);
+            if (own === undefined)
+                return undefined;
+            lost++;
+        }
+        const index = copy.length;
+        copy.push(node.copy ?? -1);
+        parent.push(-1);
+        system.push(own);
+        below.push(visited.reduce((mask, child) => mask | below[child.index], node.copy !== undefined ? 1 << node.copy : 0));
+        visited.forEach(child => { parent[child.index] = index; });
+        const label = node.copy !== undefined ? names[node.copy] : '*';
+        const notation = visited.length === 0 ? label : `${label}(${visited.map(child => child.notation).sort().join(',')})`;
+        return { index, systems: new Set([own, ...under]), notation };
+    };
+    const root = visit(tree);
+    if (!root)
+        return undefined;
+    const transfer = system.map((own, index) => parent[index] >= 0 && system[parent[index]] !== own ? 1 : 0);
+    return {
+        copy: Int16Array.from(copy),
+        parent: Int16Array.from(parent),
+        transfer: Uint8Array.from(transfer),
+        system,
+        below: Int32Array.from(below),
+        lost,
+        notation: root.notation
+    };
+};
+const classesOf = (rows, copies, costs) => {
+    const counts = new Map();
+    for (const row of rows) {
+        const key = `${row.presence.map(p => p[0]).join('')}${row.redundant ? 'r' : ''}`;
+        const known = counts.get(key);
+        if (known)
+            known.n++;
+        else
+            counts.set(key, { row, n: 1 });
+    }
+    const classes = [...counts.values()];
+    return {
+        weight: Float64Array.from(classes.map(({ n }) => n)),
+        loss: Float64Array.from(classes.map(({ row }) => row.redundant ? costs.redundantLoss : 1)),
+        forbidsAbsent: Array.from({ length: copies }, (_, c) => Uint8Array.from(classes.map(({ row }) => row.presence[c] === 'present' ? 1 : 0))),
+        forbidsPresent: Array.from({ length: copies }, (_, c) => Uint8Array.from(classes.map(({ row }) => row.presence[c] === 'absent' ? 1 : 0))),
+        total: rows.length
+    };
+};
+/**
+ * The cost of every class at every node, children first: what the
+ * subtree below costs if the node lacks the reading (`absent`) and if
+ * it holds it (`present`).
+ */
+const fill = (tree, classes, costs, absent, present) => {
+    const k = classes.weight.length;
+    for (let v = 0; v < tree.copy.length; v++) {
+        const a = absent[v];
+        const p = present[v];
+        a.fill(0);
+        p.fill(0);
+        const copy = tree.copy[v];
+        if (copy >= 0) {
+            const inner = tree.below[v] !== 1 << copy;
+            const noAbsent = classes.forbidsAbsent[copy];
+            const noPresent = classes.forbidsPresent[copy];
+            for (let c = 0; c < k; c++) {
+                if (noAbsent[c])
+                    a[c] = INF;
+                if (noPresent[c])
+                    p[c] = inner ? costs.copyDeviation : INF;
+            }
+        }
+    }
+    for (let v = 0; v < tree.copy.length; v++) {
+        const u = tree.parent[v];
+        if (u < 0)
+            continue;
+        const factor = tree.transfer[v] ? costs.transferLoss : 1;
+        const a = absent[v];
+        const p = present[v];
+        const pa = absent[u];
+        const pp = present[u];
+        for (let c = 0; c < k; c++) {
+            pa[c] += Math.min(a[c], p[c] + costs.gain);
+            pp[c] += Math.min(p[c], a[c] + classes.loss[c] * factor);
+        }
+    }
+};
+const scoreOf = (tree, classes, costs, absent, present) => {
+    fill(tree, classes, costs, absent, present);
+    const root = tree.copy.length - 1;
+    let sum = 0;
+    for (let c = 0; c < classes.weight.length; c++) {
+        sum += classes.weight[c] * Math.min(absent[root][c], present[root][c] + costs.gain);
+    }
+    return sum - costs.gain * classes.total + costs.lostState * tree.lost;
+};
+const before = (a, b) => a.cost < b.cost - 1e-9 || (Math.abs(a.cost - b.cost) <= 1e-9 && (a.lost < b.lost || (a.lost === b.lost && a.notation < b.notation)));
+/**
+ * Scores every stemma of the copies and keeps the best, the runners-up
+ * and, for each grouping of the best, the best stemma without it. Ties
+ * go to fewer lost states, then to the notation, so that the outcome
+ * depends on nothing but the copies and the costs.
+ */
+export const searchStemmata = (copies, names, systems, rows, costs, transfers, keep) => {
+    const n = copies.length;
+    const classes = classesOf(rows, n, costs);
+    const pool = 2 * n;
+    const absent = Array.from({ length: pool }, () => new Float64Array(classes.weight.length));
+    const present = Array.from({ length: pool }, () => new Float64Array(classes.weight.length));
+    const masks = 1 << n;
+    const without = new Float64Array(masks).fill(Infinity);
+    const notAncestor = new Float64Array(n).fill(Infinity);
+    const top = [];
+    let scored = 0;
+    for (const tree of stemmataOf(n)) {
+        const laid = lay(tree, systems, names, transfers);
+        if (!laid)
+            continue;
+        scored++;
+        const cost = scoreOf(laid, classes, costs, absent, present);
+        const entry = { notation: laid.notation, cost, lost: laid.lost, tree: laid };
+        if (top.length <= keep || before(entry, top[top.length - 1])) {
+            top.push(entry);
+            top.sort((a, b) => before(a, b) ? -1 : before(b, a) ? 1 : 0);
+            if (top.length > keep + 1)
+                top.pop();
+        }
+        const groupings = new Set();
+        let ancestors = 0;
+        for (let v = 0; v < laid.copy.length; v++) {
+            if (laid.below[v] === (laid.copy[v] >= 0 ? 1 << laid.copy[v] : -1))
+                continue;
+            groupings.add(laid.below[v]);
+            if (laid.copy[v] >= 0)
+                ancestors |= 1 << laid.copy[v];
+        }
+        for (let mask = 1; mask < masks; mask++) {
+            if (!groupings.has(mask) && cost < without[mask])
+                without[mask] = cost;
+        }
+        for (let c = 0; c < n; c++) {
+            if (!(ancestors & (1 << c)) && cost < notAncestor[c])
+                notAncestor[c] = cost;
+        }
+    }
+    if (top.length === 0)
+        throw new Error('No stemma of these copies is admissible');
+    const best = top[0];
+    const supports = [];
+    const named = (mask) => copies.filter((_, c) => mask & (1 << c));
+    const seen = new Set();
+    for (let v = 0; v < best.tree.copy.length; v++) {
+        const mask = best.tree.below[v];
+        const copy = best.tree.copy[v];
+        if (copy >= 0 && mask === 1 << copy)
+            continue;
+        if (mask === masks - 1 && copy < 0)
+            continue;
+        if (!seen.has(mask)) {
+            seen.add(mask);
+            supports.push({ copies: named(mask), margin: without[mask] - best.cost });
+        }
+        if (copy >= 0)
+            supports.push({ copies: named(mask), ancestor: copies[copy], margin: notAncestor[copy] - best.cost });
+    }
+    return {
+        best: best.tree,
+        cost: best.cost,
+        scored,
+        alternatives: top.slice(1).map(({ notation, cost, lost }) => ({ notation, cost, lost })),
+        supports
+    };
+};
+/**
+ * What every node holds of one reading under the least costly account
+ * of it: children first, as `LaidOut` orders the nodes. A node may be
+ * held to a state (`fixed`), as an edit the editor wrote holds a
+ * version to what it inserts or deletes. Where two accounts cost the
+ * same, the one with the node lacking the reading is taken, so that a
+ * reading arises as late as the copies allow. Nothing where the fixed
+ * states cannot be met.
+ */
+export const statesOf = (tree, presence, redundant, costs, fixed) => {
+    const size = tree.copy.length;
+    const absent = new Float64Array(size);
+    const present = new Float64Array(size);
+    const loss = redundant ? costs.redundantLoss : 1;
+    for (let v = 0; v < size; v++) {
+        const copy = tree.copy[v];
+        if (copy >= 0) {
+            const inner = tree.below[v] !== 1 << copy;
+            if (presence[copy] === 'present')
+                absent[v] = INF;
+            if (presence[copy] === 'absent')
+                present[v] = inner ? costs.copyDeviation : INF;
+        }
+        const held = fixed?.get(v);
+        if (held === true)
+            absent[v] = INF;
+        if (held === false)
+            present[v] = INF;
+    }
+    for (let v = 0; v < size; v++) {
+        const u = tree.parent[v];
+        if (u < 0)
+            continue;
+        const factor = tree.transfer[v] ? costs.transferLoss : 1;
+        absent[u] += Math.min(absent[v], present[v] + costs.gain);
+        present[u] += Math.min(present[v], absent[v] + loss * factor);
+    }
+    const states = Array.from({ length: size }, () => false);
+    const root = size - 1;
+    const rootAbsent = absent[root];
+    const rootPresent = present[root] + costs.gain;
+    if (Math.min(rootAbsent, rootPresent) >= INF / 2)
+        return undefined;
+    states[root] = rootPresent < rootAbsent;
+    for (let v = size - 2; v >= 0; v--) {
+        const u = tree.parent[v];
+        const factor = tree.transfer[v] ? costs.transferLoss : 1;
+        const a = states[u] ? absent[v] + loss * factor : absent[v];
+        const p = states[u] ? present[v] : present[v] + costs.gain;
+        states[v] = p < a;
+    }
+    return states;
+};

package/lib/filiation/systems.d.ts

@@ -0,0 +1,21 @@
+import { TrackerBar } from "../systems/TrackerBar.js";
+/**
+ * By system, the systems a roll of it was re-cut for, as the procedures
+ * of the vocabulary name them: a red roll was re-punched for the
+ * Licensee system and for the green one, and never the other way round.
+ * @category Filiation
+ */
+export declare const transfersOf: () => ReadonlyMap<string, ReadonlySet<string>>;
+/** Whether a version of the one system can stand above a version of the other: the same system, or one re-cut from it. */
+export declare const leadsTo: (transfers: ReadonlyMap<string, ReadonlySet<string>>, from: string, to: string) => boolean;
+/**
+ * The system of a lost version above versions of the given systems: the
+ * one they share, or else the one they were all re-cut from. A lost
+ * state above a red and a Licensee version is red, since a Licensee
+ * version is never re-cut into red. Where no system leads to all of
+ * them, nothing.
+ * @category Filiation
+ */
+export declare const systemAbove: (transfers: ReadonlyMap<string, ReadonlySet<string>>, systems: ReadonlySet<string>) => string | undefined;
+/** The bar of a system the library knows, by its identifier. */
+export declare const barNamed: (id: string) => TrackerBar | undefined;

package/lib/filiation/systems.js

@@ -0,0 +1,39 @@
+/** Which reproducing system a version of the stemma is coded for, and which systems a roll was re-cut into. */
+import { procedures } from "../model/procedures.js";
+import { trackerBars } from "../systems/index.js";
+const TRANSFER = /\/umstanzung\/(.+)-to-(.+)$/;
+/**
+ * By system, the systems a roll of it was re-cut for, as the procedures
+ * of the vocabulary name them: a red roll was re-punched for the
+ * Licensee system and for the green one, and never the other way round.
+ * @category Filiation
+ */
+export const transfersOf = () => {
+    const transfers = new Map();
+    for (const procedure of procedures) {
+        const match = TRANSFER.exec(procedure.id ?? "");
+        if (!match)
+            continue;
+        const [from, to] = [match[1], match[2]];
+        transfers.set(from, new Set([...(transfers.get(from) ?? []), to]));
+    }
+    return transfers;
+};
+/** Whether a version of the one system can stand above a version of the other: the same system, or one re-cut from it. */
+export const leadsTo = (transfers, from, to) => from === to || (transfers.get(from)?.has(to) ?? false);
+/**
+ * The system of a lost version above versions of the given systems: the
+ * one they share, or else the one they were all re-cut from. A lost
+ * state above a red and a Licensee version is red, since a Licensee
+ * version is never re-cut into red. Where no system leads to all of
+ * them, nothing.
+ * @category Filiation
+ */
+export const systemAbove = (transfers, systems) => {
+    if (systems.size === 1)
+        return [...systems][0];
+    const candidates = new Set([...systems, ...transfers.keys()]);
+    return [...candidates].sort().find(candidate => [...systems].every(system => leadsTo(transfers, candidate, system)));
+};
+/** The bar of a system the library knows, by its identifier. */
+export const barNamed = (id) => trackerBars.find(bar => bar.id === id);

package/lib/filiation/trees.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Every stemma a handful of copies can stand in: rooted trees whose
+ * nodes are versions, a copy carrying any of them, a lost one above
+ * any two or more.
+ */
+/**
+ * A node of a stemma: the copy carrying it at first hand, by its number,
+ * or none for a lost state, and the nodes derived from it.
+ */
+export interface StemmaNode {
+    readonly copy?: number;
+    readonly children: readonly StemmaNode[];
+}
+/**
+ * Every stemma of n copies: 3 for two copies, 91,984 for six. They are
+ * produced one by one, so that only the leaf trees, far fewer, are held.
+ */
+export declare function stemmataOf(n: number): Generator<StemmaNode>;
+/** How many stemmata the exhaustive search scores, at most. */
+export declare const MAX_COPIES = 7;

package/lib/filiation/trees.js

@@ -0,0 +1,69 @@
+/**
+ * Every stemma a handful of copies can stand in: rooted trees whose
+ * nodes are versions, a copy carrying any of them, a lost one above
+ * any two or more.
+ */
+const leaf = (copy) => ({ copy, children: [] });
+/** Every way to add the copy to the tree: as a further child of a lost node, or on an edge, above any subtree. */
+function* insertions(tree, copy) {
+    yield { children: [tree, leaf(copy)] };
+    if (tree.children.length === 0)
+        return;
+    yield { ...tree, children: [...tree.children, leaf(copy)] };
+    for (let i = 0; i < tree.children.length; i++) {
+        for (const child of insertions(tree.children[i], copy)) {
+            yield { ...tree, children: [...tree.children.slice(0, i), child, ...tree.children.slice(i + 1)] };
+        }
+    }
+}
+/** The trees whose leaves are the copies 0 to n − 1 and whose inner nodes are all lost, each once. */
+const leafTrees = (n) => {
+    if (n === 1)
+        return [leaf(0)];
+    let trees = [{ children: [leaf(0), leaf(1)] }];
+    for (let copy = 2; copy < n; copy++) {
+        trees = trees.flatMap(tree => [...insertions(tree, copy)]);
+    }
+    return trees;
+};
+const product = (lists) => lists.reduce((combos, list) => combos.flatMap(combo => list.map(item => [...combo, item])), [[]]);
+/**
+ * The tree with as many of its copies moved up as it allows: at each
+ * lost node, at most one copy among its leaf children may come to carry
+ * it instead, making that copy's text the ancestor of the others'.
+ * Every stemma arises from exactly one leaf tree in exactly one way.
+ */
+function* promotions(tree) {
+    if (tree.children.length === 0) {
+        yield tree;
+        return;
+    }
+    const options = tree.children.map(child => [...promotions(child)]);
+    const leaves = tree.children.flatMap((child, index) => child.children.length === 0 ? [index] : []);
+    for (const combo of product(options)) {
+        yield { children: combo };
+        for (const index of leaves) {
+            yield { copy: tree.children[index].copy, children: combo.filter((_, i) => i !== index) };
+        }
+    }
+}
+const cache = new Map();
+/**
+ * Every stemma of n copies: 3 for two copies, 91,984 for six. They are
+ * produced one by one, so that only the leaf trees, far fewer, are held.
+ */
+export function* stemmataOf(n) {
+    let trees = cache.get(n);
+    if (!trees) {
+        trees = leafTrees(n);
+        cache.set(n, trees);
+    }
+    if (n === 1) {
+        yield trees[0];
+        return;
+    }
+    for (const tree of trees)
+        yield* promotions(tree);
+}
+/** How many stemmata the exhaustive search scores, at most. */
+export const MAX_COPIES = 7;

package/lib/index.d.ts

@@ -1,11 +1,41 @@
 /**
+ * Digital editions of piano rolls: reading an edition and writing it out
+ * as JSON-LD, finding what it holds, changing it through operations on
+ * an immer draft, reading copies from scans and analysis files,
+ * collating them into versions, and working out what the edition can
+ * and cannot vouch for. The reproducing systems that play a version are
+ * entry points of their own, so that the emulator they need is loaded
+ * only where it is wanted.
+ *
  * The public interface of the library. Everything else under lib/ is its
  * implementation and may change in any release: the in-place helpers the
  * operations are built from, the date conversions of the serialisation,
- * and the general utilities.
+ * and the general utilities. So may the exports tagged `@internal`,
+ * which the API reference leaves out.
+ *
+ * @module linked-rolls
+ *
+ * @categoryDescription Format types
+ * The types of an edition. They are documented field by field, with the
+ * ontology terms each field maps to, in the
+ * [format reference](https://pfefferniels.github.io/linked-rolls/); they
+ * are listed here so that the signatures can link to them.
+ *
+ * @categoryDescription Units
+ * A quantity is a plain number at runtime; its unit lives in its type, so
+ * that a length in millimetres cannot be passed where one in pixels is
+ * wanted. The constructors make a number into a quantity.
  */
 export type { WithId, WithNote, WithType } from './shared/utils.js';
 export * from './model/Quantity.js';
+/**
+ * A number in a unit, the unit carried in the type alone: at runtime it
+ * is the plain number it was made from. A number becomes a quantity only
+ * through a constructor such as `mm` or `track`, and a quantity in one
+ * unit cannot stand in for one in another.
+ * @category Units
+ */
+export type { Quantity } from './model/Quantity.js';
 export * from './model/Agent.js';
 export * from './model/Assumption.js';
 export * from './model/ConditionState.js';
@@ -41,10 +71,12 @@ export * from './emulation/negotiation.js';
 export * from './collation/scatter.js';
 export * from './ops/index.js';
 export * from './emulation/Emulation.js';
-export * from './validate.js';
+/** @category Reading and writing */
+export { validate, type ValidateEdition } from './validate.js';
 export * from './analysis/constraints.js';
 export * from './collation/substitution.js';
 export * from './io/context.js';
+export * from './filiation/index.js';
 export * from './analysis/sigla.js';
 export * from './model/notes.js';
 export { asJsonLd } from './io/asJsonLd.js';

package/lib/index.js

@@ -34,10 +34,12 @@ export * from './emulation/negotiation.js';
 export * from './collation/scatter.js';
 export * from './ops/index.js';
 export * from './emulation/Emulation.js';
-export * from './validate.js';
+/** @category Reading and writing */
+export { validate } from './validate.js';
 export * from './analysis/constraints.js';
 export * from './collation/substitution.js';
 export * from './io/context.js';
+export * from './filiation/index.js';
 export * from './analysis/sigla.js';
 export * from './model/notes.js';
 export { asJsonLd } from './io/asJsonLd.js';

package/lib/io/asJsonLd.d.ts

@@ -5,4 +5,14 @@ import { Edition } from "../model/Edition.js";
  */
 export declare const derivedKeys: ReadonlySet<string>;
 export declare const exportDate: (date: Date) => string;
+/**
+ * Writes the edition as a JSON-LD document in the terms of the Roll
+ * Edition Ontology. Each copy's features and tears go back to the
+ * copy's own places, as they were read, with the alignment beside them,
+ * and every version carries the context of its own reproducing system.
+ * A reference the edition holds possible, unlikely or false is quoted
+ * rather than stated, so that a reader of the RDF does not take it for
+ * a fact. The edition given is not changed.
+ * @category Reading and writing
+ */
 export declare const asJsonLd: (edition: Edition) => any;

package/lib/io/asJsonLd.js

@@ -160,6 +160,16 @@ const withDoubtedReferencesQuoted = (value, quoted) => {
 const atOwnPlacesAll = (edition) => edition.copies.some(copy => copy.measurements.alignment)
     ? { ...edition, copies: edition.copies.map(atOwnPlaces) }
     : edition;
+/**
+ * Writes the edition as a JSON-LD document in the terms of the Roll
+ * Edition Ontology. Each copy's features and tears go back to the
+ * copy's own places, as they were read, with the alignment beside them,
+ * and every version carries the context of its own reproducing system.
+ * A reference the edition holds possible, unlikely or false is quoted
+ * rather than stated, so that a reader of the RDF does not take it for
+ * a fact. The edition given is not changed.
+ * @category Reading and writing
+ */
 export const asJsonLd = (edition) => {
     const quoted = [];
     const node = withDoubtedReferencesQuoted(withSystemContexts(withCreations(withChanges(asJsonLdEntity(atOwnPlacesAll(edition))))), quoted);

package/lib/io/context.d.ts

@@ -1,12 +1,26 @@
+/**
+ * The JSON-LD context of the format, which an exported edition names by
+ * its address, `https://w3id.org/reo/context.jsonld`: it maps the keys of
+ * the document onto the Roll Edition Ontology, CIDOC CRM, LRMoo and
+ * CRMinf.
+ * @category Reading and writing
+ */
 export { default as jsonLdContext } from '../spec/context.json';
-/** The context of the Welte-Mignon T-100, added to a version coded for it. */
+/**
+ * The context of the Welte-Mignon T-100, added to a version coded for it.
+ * @category Reading and writing
+ */
 export { default as welteT100JsonLdContext } from '../spec/welte-t100.context.json';
 /**
  * The context of the Welte-Mignon Licensee. Its expression terms are
  * the T-100's, the two systems differing in the tracker scale rather
  * than in the coding, so it reads them out of the T-100's vocabulary
  * rather than minting a second set of IRIs for the same commands.
+ * @category Reading and writing
  */
 export { default as welteLicenseeJsonLdContext } from '../spec/welte-licensee.context.json';
-/** The context of the Welte-Mignon T-98, added to an edition of a green roll. */
+/**
+ * The context of the Welte-Mignon T-98, added to an edition of a green roll.
+ * @category Reading and writing
+ */
 export { default as welteT98JsonLdContext } from '../spec/welte-t98.context.json';

package/lib/io/context.js

@@ -1,12 +1,26 @@
+/**
+ * The JSON-LD context of the format, which an exported edition names by
+ * its address, `https://w3id.org/reo/context.jsonld`: it maps the keys of
+ * the document onto the Roll Edition Ontology, CIDOC CRM, LRMoo and
+ * CRMinf.
+ * @category Reading and writing
+ */
 export { default as jsonLdContext } from '../spec/context.json' with { type: 'json' };
-/** The context of the Welte-Mignon T-100, added to a version coded for it. */
+/**
+ * The context of the Welte-Mignon T-100, added to a version coded for it.
+ * @category Reading and writing
+ */
 export { default as welteT100JsonLdContext } from '../spec/welte-t100.context.json' with { type: 'json' };
 /**
  * The context of the Welte-Mignon Licensee. Its expression terms are
  * the T-100's, the two systems differing in the tracker scale rather
  * than in the coding, so it reads them out of the T-100's vocabulary
  * rather than minting a second set of IRIs for the same commands.
+ * @category Reading and writing
  */
 export { default as welteLicenseeJsonLdContext } from '../spec/welte-licensee.context.json' with { type: 'json' };
-/** The context of the Welte-Mignon T-98, added to an edition of a green roll. */
+/**
+ * The context of the Welte-Mignon T-98, added to an edition of a green roll.
+ * @category Reading and writing
+ */
 export { default as welteT98JsonLdContext } from '../spec/welte-t98.context.json' with { type: 'json' };

package/lib/io/importJsonLd.d.ts

@@ -5,6 +5,7 @@ type Json = any;
  * Reads an edition. A document holds each copy's features and tears at
  * the copy's own places, as they were read; the edition holds them on
  * its axis, which is where the copy's alignment carries them.
+ * @category Reading and writing
  */
 export declare const importJsonLd: (json: Json) => Edition;
 export {};

package/lib/io/importJsonLd.js

@@ -133,6 +133,7 @@ const withQuotedStatementsInPlace = (edition) => {
  * Reads an edition. A document holds each copy's features and tears at
  * the copy's own places, as they were read; the edition holds them on
  * its axis, which is where the copy's alignment carries them.
+ * @category Reading and writing
  */
 export const importJsonLd = (json) => {
     const { '@context': context, ...document } = withoutEmptyCreations(withPlainCopyIds(migrate(withQuotedStatementsInPlace(json))));

package/lib/io/migrate.d.ts

@@ -13,5 +13,13 @@
 type Json = any;
 /** A copy's id without the `copy/` that documents of earlier releases put before it. */
 export declare const plainCopyId: (id: string) => string;
+/**
+ * Brings the JSON of an edition written by an earlier release of the
+ * format up to the current shape. A document that is current already
+ * passes through unchanged, and one may be migrated any number of
+ * times. `importJsonLd` migrates what it reads, so this is needed only
+ * to look at an old document as JSON.
+ * @category Reading and writing
+ */
 export declare const migrate: (edition: Json) => Json;
 export {};

package/lib/io/migrate.js

@@ -677,4 +677,12 @@ const withReferenceCopy = (edition) => {
         : edition;
 };
 const editionSteps = [withoutFormatVersion, withoutTempoAdjustment, withoutEditionType, withSystems, withEditors, withDerivationTolerance, withReferenceCopy];
+/**
+ * Brings the JSON of an edition written by an earlier release of the
+ * format up to the current shape. A document that is current already
+ * passes through unchanged, and one may be migrated any number of
+ * times. `importJsonLd` migrates what it reads, so this is needed only
+ * to look at an old document as JSON.
+ * @category Reading and writing
+ */
 export const migrate = (edition) => walk(editionSteps.reduce((result, step) => step(result), edition));