linked-rolls 0.71.0 → 0.73.0

package/README.md

@@ -97,6 +97,46 @@ const midi = midiOf(events, welteT100System.name, welteT100System.defaultOptions
 The systems are `linked-rolls/welte-t100` (red Welte),
 `linked-rolls/welte-t98` (green Welte) and `linked-rolls/welte-licensee`.
 
+## Proposing a stemma
+
+Which versions there are, lost ones included, how they derive from each
+other and which edits belong to which can be proposed from the copies
+alone. `proposeStemma` collates the transcribed copies all at once,
+notes which copies have, lack or cannot show each reading, and scores
+every stemma the copies admit. Copies of one system that differ in no
+more than a few readings, or that the edition gives one version, are
+taken to carry one text, and so one version, as pressings of one master
+do; what one of them lacks is a deviation of that copy. The search
+covers up to seven such texts, however many copies carry them. A reading arising
+costs ten times a reading lost. Losses count for less where the
+editorial principles of an edition say they are weak evidence: a
+redundancy cleaned up, or what a re-cut for another system lacks. On
+the best stemma, each reading arises in the latest version all copies
+carrying it descend from.
+
+```ts
+import { produce } from 'immer'
+import { adoptStemma, proposeStemma, stemmaChanges } from 'linked-rolls'
+
+const proposal = proposeStemma(edition)
+proposal.notation   // '*(St1(*(Ne1,St2(Bo1,Ch1))),Wi1)' for WM 225
+proposal.supports   // by how much the copies decide each grouping
+
+const adopted = produce(edition, adoptStemma(proposal))
+const changes = stemmaChanges(edition, adopted)
+```
+
+Adopting keeps what the edition holds wherever the proposal stands for
+it: the ids of versions and symbols, a derivation's belief, and the
+edits the editor wrote, which hold their versions to what they insert
+and delete. Motivations, beliefs and versions known only from a
+recording remain the editor's to state.
+
+The costs are those with which the stemma of WM 225 comes out of its
+six copies. They were found by searching for such values, so they show
+that the stemma is consistent with these principles, not that the
+principles confirm it.
+
 ## Format
 
 The export uses the Roll Edition Ontology (REO), namespace
@@ -129,3 +169,53 @@ the day as `date-released`, commit, and push a tag `v<version>`. The
 `publish.yml` workflow builds, tests and publishes to npm, then makes a
 GitHub release of the tag, which Zenodo archives with a DOI. A test fails
 while the two versions differ.
+
+## About
+
+linked-rolls grew out of the dissertation *Grünfelds Geist.
+Rekonstruktion einer Welte-Mignon-Klavierrollenaufnahme* (Niels
+Pfeffer, Eberhard Karls Universität Tübingen, Musikwissenschaftliches
+Institut, 2026), which edits Alfred Grünfeld's 1905 recording of
+Schumann's *Träumerei*, Welte-Mignon roll 225, from its surviving
+copies. That edition is published at https://welte225.org/ and can be
+read in the [Roll Desk](https://rolldesk.welte225.org/).
+
+Its aim is a scholarly edition of a piano roll that treats the roll the
+way a critical edition treats a text: every copy is a witness, the
+differences between copies are collated into versions, and every
+editorial decision is recorded together with the evidence and the
+beliefs behind it, so that a reader can retrace and contest it. The
+data are meant to be reused outside the library, which is why the
+format is linked data built on CIDOC CRM rather than a file format of
+its own.
+
+### Related formats
+
+Several formats have been developed or used to represent piano rolls at
+different stages of processing:
+
+- **Scan images:** CIS and MRS, often accompanied by ANN metadata.
+- **Event lists:** Wayne Stahnke's RAW, WEB and BAR, PRF, SCN, ROL, and
+  the e-roll MIDI files of pneumatic readers.
+- **Symbolic descriptions:** the Roll Analysis files of the Stanford
+  University Piano Roll Archive, serialised as ATON.
+
+None of them is concerned with what a critical edition needs: an
+apparatus of the variants between copies, the traces a copy carries
+(handwritten notes, patches, perforations added later), a record of how
+and on what assumptions each reading came about, and identifiers by
+which all of this can be referred to and annotated. The dissertation
+surveys these formats in its chapter on variants.
+
+Editions of texts and of notated music are mostly encoded in TEI and
+MEI. A roll edition, however, is less a nested text document than a
+flat structure of roll events described in numbers, and its data should
+link to other domains, which is why the Roll Edition Format is JSON-LD
+built on CIDOC CRM and LRMoo.
+
+### Maintenance
+
+The library is maintained by Niels Pfeffer
+([ORCID 0000-0002-6210-7255](https://orcid.org/0000-0002-6210-7255)). It
+is released under the MIT licence, the ontology and its documentation
+under CC BY 4.0.

package/lib/filiation/adoption.d.ts

@@ -0,0 +1,47 @@
+import { Edition } from "../model/Edition.js";
+import { Version } from "../model/Version.js";
+import { EditionOp } from "../ops/draft.js";
+import { StemmaProposal, Unpinned } from "./proposal.js";
+/**
+ * What adopting a proposal makes of the stemma: the versions it puts in
+ * place of the edition's, and what of the edition it leaves out.
+ * @category Filiation
+ */
+export interface Adoption {
+    versions: Version[];
+    /** By version of the proposal, the id of the version it becomes. */
+    ids: Record<string, string>;
+    /** The versions of the edition the adoption leaves out. */
+    removed: string[];
+    /** The edits the editor wrote that the adoption leaves out, and why. */
+    dropped: Unpinned[];
+}
+/**
+ * What adopting the proposal makes of the edition's stemma, worked out
+ * without changing it, so that it can be looked at first.
+ *
+ * A version of the proposal that stands for a version of the edition
+ * keeps its id, system, creation and motivations, the derivation it
+ * states where it still derives from the same version, and its other
+ * derivations, the hypotheses, as long as they name a version that is
+ * still there and does not derive from it. Its edits are the proposal's:
+ * the edits the editor wrote that the proposal keeps, as they are, and
+ * one edit for each further reading it inserts or deletes, or for each
+ * recoding. An edit the version stated before over the very same
+ * readings is taken over with its id and what was written on it; the
+ * others are new and marked unchecked, as a collation marks its own.
+ *
+ * A reading that stands for a symbol of the edition keeps that symbol's
+ * id and whatever it states beside its carriers. A version of the edition
+ * nothing stands for goes, unless it states no edits and derives from a
+ * version that stays, as a version known only from a recording does.
+ * @category Filiation
+ */
+export declare const adoptionOf: (edition: Edition, proposal: StemmaProposal) => Adoption;
+/**
+ * Puts the proposed stemma in place of the edition's, as `adoptionOf`
+ * describes, and takes back a copy's statement that it carries a version
+ * that goes. One operation, and so one undo step.
+ * @category Operations
+ */
+export declare const adoptStemma: (proposal: StemmaProposal) => EditionOp;

package/lib/filiation/adoption.js

@@ -0,0 +1,189 @@
+/** Taking a proposed stemma into the edition, as one operation. */
+import { v5 } from "uuid";
+import { assignReference, idOf } from "../model/Assumption.js";
+import { derivesFrom, editsOf, insertedBy, principalDerivationOf } from "../model/Version.js";
+import { systemOf } from "../systems/TrackerBar.js";
+import { unchecked } from "../collation/Collation.js";
+import { versionIn } from "../lookup/lookup.js";
+import { declaring, reading } from "../ops/draft.js";
+import { dropStatements } from "../ops/copies.js";
+import { barNamed } from "./systems.js";
+/** The namespace the names of adopted versions and edits are minted in, so that adopting again gives them again. */
+const ADOPTED = '6f1d2c8e-93a4-4f0b-b8a1-2f4c5d7e9a31';
+const exchangeKey = (inserted, deleted) => `${[...inserted].sort().join(',')}/${[...deleted].sort().join(',')}`;
+/** The carriers of the reading, keeping what the edition states of those it held already. */
+const carriersOf = (reading, stated) => {
+    const known = new Map(stated.map(carrier => [idOf(carrier), carrier]));
+    return reading.carriers.map(id => known.get(id) ?? assignReference(id));
+};
+/**
+ * What adopting the proposal makes of the edition's stemma, worked out
+ * without changing it, so that it can be looked at first.
+ *
+ * A version of the proposal that stands for a version of the edition
+ * keeps its id, system, creation and motivations, the derivation it
+ * states where it still derives from the same version, and its other
+ * derivations, the hypotheses, as long as they name a version that is
+ * still there and does not derive from it. Its edits are the proposal's:
+ * the edits the editor wrote that the proposal keeps, as they are, and
+ * one edit for each further reading it inserts or deletes, or for each
+ * recoding. An edit the version stated before over the very same
+ * readings is taken over with its id and what was written on it; the
+ * others are new and marked unchecked, as a collation marks its own.
+ *
+ * A reading that stands for a symbol of the edition keeps that symbol's
+ * id and whatever it states beside its carriers. A version of the edition
+ * nothing stands for goes, unless it states no edits and derives from a
+ * version that stays, as a version known only from a recording does.
+ * @category Filiation
+ */
+export const adoptionOf = (edition, proposal) => {
+    const readingOf = new Map(proposal.collation.readings.map(reading => [reading.id, reading]));
+    const symbolIdOf = (reading) => proposal.symbols[reading] ?? reading;
+    const existing = new Map(edition.versions.flatMap(insertedBy).map(symbol => [symbol.id, symbol]));
+    // A reading the stemma lets arise more than once is one symbol for each time it arises, each
+    // carried by the copies below where it arose: the edition inserts a symbol in one version only.
+    const parentOf = new Map(proposal.versions.map(proposed => [proposed.id, proposed.parent]));
+    const copiesBelow = new Map(proposal.versions.map(proposed => [proposed.id, new Set()]));
+    for (const proposed of proposal.versions) {
+        for (let at = proposed.id; at !== undefined; at = parentOf.get(at)) {
+            proposed.copies.forEach(copy => copiesBelow.get(at).add(copy));
+        }
+    }
+    const arising = new Map();
+    for (const proposed of proposal.versions) {
+        for (const reading of proposed.inserts)
+            arising.set(reading, [...(arising.get(reading) ?? []), proposed.id]);
+    }
+    /** The symbol a reading is where it arose in the version given. */
+    const symbolIdAt = (reading, at) => {
+        const places = arising.get(reading) ?? [];
+        return places.indexOf(at) > 0 ? `symbol_${v5(`${reading}|${at}`, ADOPTED)}` : symbolIdOf(reading);
+    };
+    /** The symbol a version inherits of a reading: the one that arose nearest above it. */
+    const inheritedAt = (reading, at) => {
+        const places = arising.get(reading) ?? [];
+        for (let above = parentOf.get(at); above !== undefined; above = parentOf.get(above)) {
+            if (places.includes(above))
+                return symbolIdAt(reading, above);
+        }
+        return symbolIdOf(reading);
+    };
+    const symbolOf = (id, at) => {
+        const reading = readingOf.get(id);
+        const twice = (arising.get(id)?.length ?? 0) > 1;
+        const below = copiesBelow.get(at);
+        const own = twice
+            ? { ...reading, carriers: reading.carriers.filter((_, index) => below.has(reading.copies[index])) }
+            : reading;
+        const symbol = symbolIdAt(id, at);
+        const stated = symbol === proposal.symbols[id] ? existing.get(symbol) : undefined;
+        const carriers = carriersOf(own, stated?.carriers ?? []);
+        if (stated)
+            return { ...stated, carriers };
+        return reading.meaning.type === 'note'
+            ? { type: 'note', id: symbol, pitch: reading.meaning.pitch, carriers }
+            : { type: 'expression', id: symbol, expressionType: reading.meaning.expressionType, scope: reading.meaning.scope, carriers };
+    };
+    const standingFor = new Map(Object.entries(proposal.symbols).map(([reading, symbol]) => [symbol, reading]));
+    /** The symbol as an edit the editor wrote inserts it, with the carriers of the reading it stands for. */
+    const restated = (symbol) => {
+        const reading = standingFor.get(symbol.id);
+        return reading ? { ...symbol, carriers: carriersOf(readingOf.get(reading), symbol.carriers) } : symbol;
+    };
+    const idFor = (proposed) => proposed.version ?? v5(`version|${proposed.copies.join(',')}|${[...proposed.inserts].sort().join(',')}`, ADOPTED);
+    const ids = new Map(proposal.versions.map(proposed => [proposed.id, idFor(proposed)]));
+    const staying = new Set(ids.values());
+    const versions = proposal.versions.map((proposed) => {
+        const id = ids.get(proposed.id);
+        const before = proposed.version ? versionIn(edition, proposed.version) : undefined;
+        const pinned = new Set(proposed.pinned);
+        const stated = before ? editsOf(before) : [];
+        const kept = stated
+            .filter(edit => pinned.has(edit.id))
+            .map(edit => edit.insert ? { ...edit, insert: edit.insert.map(restated) } : edit);
+        const spoken = new Set(kept.flatMap(edit => [...(edit.insert ?? []).map(symbol => symbol.id), ...(edit.delete ?? [])]));
+        const statedBefore = new Map(stated.map(edit => [exchangeKey((edit.insert ?? []).map(symbol => symbol.id), edit.delete ?? []), edit]));
+        const made = (inserts, deletes, recoding) => {
+            const inserted = inserts.map(reading => symbolIdAt(reading, proposed.id));
+            const deleted = deletes.map(reading => inheritedAt(reading, proposed.id));
+            if ([...inserted, ...deleted].some(symbol => spoken.has(symbol)))
+                return undefined;
+            const key = exchangeKey(inserted, deleted);
+            const same = statedBefore.get(key);
+            const insert = inserts.map(reading => symbolOf(reading, proposed.id));
+            if (same)
+                return { ...same, ...(insert.length > 0 && { insert }), ...(deleted.length > 0 && { delete: deleted }) };
+            return {
+                type: 'edit',
+                id: v5(`edit|${id}|${key}`, ADOPTED),
+                ...(recoding && { editType: 'recoding' }),
+                motivation: unchecked,
+                ...(insert.length > 0 && { insert }),
+                ...(deleted.length > 0 && { delete: deleted })
+            };
+        };
+        // A recoding an edit of the editor's cuts into is stated reading by reading.
+        const whole = proposed.recodings.filter(recoding => ![...recoding.by.map(reading => symbolIdAt(reading, proposed.id)), ...recoding.replaced.map(reading => inheritedAt(reading, proposed.id))]
+            .some(symbol => spoken.has(symbol)));
+        const recoded = new Set(whole.flatMap(recoding => [...recoding.by, ...recoding.replaced]));
+        const edits = [
+            ...kept,
+            ...whole.map(recoding => made(recoding.by, recoding.replaced, true)),
+            ...proposed.inserts.filter(reading => !recoded.has(reading)).map(reading => made([reading], [], false)),
+            ...proposed.deletes.filter(reading => !recoded.has(reading)).map(reading => made([], [reading], false))
+        ].filter((edit) => edit !== undefined);
+        const parent = proposed.parent ? ids.get(proposed.parent) : undefined;
+        const principal = before && principalDerivationOf(before);
+        const derivation = parent === undefined
+            ? undefined
+            : principal && idOf(principal) === parent ? principal : assignReference(parent);
+        const hypotheses = (before?.basedOn ?? [])
+            .filter(other => other !== principal && staying.has(idOf(other)) && idOf(other) !== parent);
+        const basedOn = [...(derivation ? [derivation] : []), ...hypotheses];
+        const copy = edition.copies.find(copy => copy.id === proposed.copies[0]);
+        const bar = barNamed(proposed.system);
+        const system = copy?.production?.system ?? before?.system ?? (bar ? systemOf(bar) : { id: proposed.system, name: proposed.system, sameAs: [] });
+        const { basedOn: _, edits: __, ...rest } = before ?? {};
+        return {
+            ...rest,
+            id,
+            system,
+            ...(basedOn.length > 0 && { basedOn }),
+            edits,
+            motivations: declaring(before?.motivations ?? [], edits)
+        };
+    });
+    // A hypothesis may not name a version that now derives from the one stating it.
+    const pruned = versions.map(version => ({
+        ...version,
+        ...(version.basedOn && {
+            basedOn: version.basedOn.filter((derivation, index) => index === 0 || !derivesFrom(versions, idOf(derivation), version.id))
+        })
+    }));
+    const statedOnly = edition.versions.filter(version => {
+        if (staying.has(version.id) || editsOf(version).length > 0)
+            return false;
+        const principal = principalDerivationOf(version);
+        return principal !== undefined && staying.has(idOf(principal));
+    });
+    const removed = edition.versions.filter(version => !staying.has(version.id) && !statedOnly.includes(version)).map(version => version.id);
+    // The edition's order where a version stays, the new ones after it.
+    const rank = new Map(edition.versions.map((version, index) => [version.id, index]));
+    const ordered = [...pruned, ...statedOnly].sort((a, b) => (rank.get(a.id) ?? Infinity) - (rank.get(b.id) ?? Infinity));
+    return { versions: ordered, ids: Object.fromEntries(ids), removed, dropped: proposal.unpinned };
+};
+/**
+ * Puts the proposed stemma in place of the edition's, as `adoptionOf`
+ * describes, and takes back a copy's statement that it carries a version
+ * that goes. One operation, and so one undo step.
+ * @category Operations
+ */
+export const adoptStemma = (proposal) => reading(edition => {
+    const { versions, removed } = adoptionOf(edition, proposal);
+    const gone = new Set(removed);
+    return draft => {
+        draft.versions = versions;
+        draft.copies.forEach(copy => dropStatements(copy, statement => gone.has(idOf(statement))));
+    };
+});

package/lib/filiation/changes.d.ts

@@ -0,0 +1,33 @@
+/** What tells two states of a stemma apart, version by version. */
+import { Edition } from "../model/Edition.js";
+/**
+ * How a version differs between two states of the edition: whether it
+ * is in either, what it derives from in each, and which symbols it
+ * inserts and deletes in one and not the other.
+ * @category Filiation
+ */
+export interface VersionChange {
+    version: string;
+    /** The version it derives from in the state before, where it is in that state. */
+    parentBefore?: string | null;
+    /** The version it derives from in the state after, where it is in that state. */
+    parentAfter?: string | null;
+    inserted: {
+        kept: number;
+        gone: string[];
+        added: string[];
+    };
+    deleted: {
+        kept: number;
+        gone: string[];
+        added: string[];
+    };
+}
+/**
+ * Version by version, how the stemma of one state of the edition differs
+ * from that of another, as when a proposed stemma is set against the one
+ * the edition holds. The versions of the state before come first, in
+ * their order, then those only the state after holds.
+ * @category Filiation
+ */
+export declare const stemmaChanges: (before: Pick<Edition, 'versions'>, after: Pick<Edition, 'versions'>) => VersionChange[];

package/lib/filiation/changes.js

@@ -0,0 +1,38 @@
+import { idOf } from "../model/Assumption.js";
+import { deletedBy, insertedBy, principalDerivationOf } from "../model/Version.js";
+const compared = (before, after) => {
+    const was = new Set(before);
+    const is = new Set(after);
+    return {
+        kept: after.filter(id => was.has(id)).length,
+        gone: before.filter(id => !is.has(id)),
+        added: after.filter(id => !was.has(id))
+    };
+};
+const parentOf = (version) => {
+    const principal = principalDerivationOf(version);
+    return principal ? idOf(principal) : null;
+};
+/**
+ * Version by version, how the stemma of one state of the edition differs
+ * from that of another, as when a proposed stemma is set against the one
+ * the edition holds. The versions of the state before come first, in
+ * their order, then those only the state after holds.
+ * @category Filiation
+ */
+export const stemmaChanges = (before, after) => {
+    const was = new Map(before.versions.map(version => [version.id, version]));
+    const is = new Map(after.versions.map(version => [version.id, version]));
+    const ids = [...new Set([...was.keys(), ...is.keys()])];
+    return ids.map(id => {
+        const one = was.get(id);
+        const other = is.get(id);
+        return {
+            version: id,
+            ...(one && { parentBefore: parentOf(one) }),
+            ...(other && { parentAfter: parentOf(other) }),
+            inserted: compared(one ? insertedBy(one).map(symbol => symbol.id) : [], other ? insertedBy(other).map(symbol => symbol.id) : []),
+            deleted: compared(one ? deletedBy(one) : [], other ? deletedBy(other) : [])
+        };
+    });
+};

package/lib/filiation/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Filiation: proposing a stemma from the copies alone, by the editorial
+ * principles the rules of an edition state, and taking it into the
+ * edition.
+ */
+export { collateCopies, readingsOfCopy, type CopyCollation, type CollatedReading, type CopyReading, type PairWindow, type Recoding } from "./readings.js";
+export { presenceIn, ineffectiveAmong, defaultMargin, type Presence, type PresenceMatrix } from "./presence.js";
+export { defaultCosts, type Costs, type Scored, type Support } from "./search.js";
+export { transfersOf, systemAbove } from "./systems.js";
+export { proposeStemma, defaultMovedWithin, type FiliationOptions, type ProposedVersion, type StemmaProposal, type Unpinned } from "./proposal.js";
+export { adoptionOf, adoptStemma, type Adoption } from "./adoption.js";
+export { stemmaChanges, type VersionChange } from "./changes.js";
+export { sharedTexts, differencesBetween, defaultSameText, type SharedText, type KeptApart } from "./texts.js";

package/lib/filiation/index.js

@@ -0,0 +1,13 @@
+/**
+ * Filiation: proposing a stemma from the copies alone, by the editorial
+ * principles the rules of an edition state, and taking it into the
+ * edition.
+ */
+export { collateCopies, readingsOfCopy } from "./readings.js";
+export { presenceIn, ineffectiveAmong, defaultMargin } from "./presence.js";
+export { defaultCosts } from "./search.js";
+export { transfersOf, systemAbove } from "./systems.js";
+export { proposeStemma, defaultMovedWithin } from "./proposal.js";
+export { adoptionOf, adoptStemma } from "./adoption.js";
+export { stemmaChanges } from "./changes.js";
+export { sharedTexts, differencesBetween, defaultSameText } from "./texts.js";

package/lib/filiation/presence.d.ts

@@ -0,0 +1,50 @@
+/** Which copies carry which collated reading, which lack it, and where a copy cannot say. */
+import { Edition } from "../model/Edition.js";
+import { HorizontalSpan } from "../model/Feature.js";
+import { Millimeters } from "../model/Quantity.js";
+import { TrackerBar, TrackMeaning } from "../systems/TrackerBar.js";
+import { CopyCollation } from "./readings.js";
+/**
+ * What a copy says of a reading: it carries it, it lacks it, or it
+ * cannot tell, because it is torn there, its text does not reach so
+ * far, or its system has no word for the reading.
+ * @category Filiation
+ */
+export type Presence = 'present' | 'absent' | 'unknown';
+/**
+ * The presence of every collated reading in every copy, and the readings
+ * that are ineffective in a copy carrying them.
+ * @category Filiation
+ */
+export interface PresenceMatrix {
+    copies: string[];
+    /** By reading, by copy. */
+    presence: Record<string, Record<string, Presence>>;
+    /** The readings that are ineffective where a copy carries them: a latched function set again, or cancelled again. */
+    redundant: string[];
+}
+/** How far beyond the end of its text, or the edge of a tear, a copy cannot say what it lacks. */
+export declare const defaultMargin: import("../index.js").Quantity<"mm">;
+/**
+ * The readings a latched function makes no use of in the text given: a
+ * command setting what is set already, or cancelling what is cancelled.
+ * Commands at one place are taken cancel first, as the valves take them.
+ * @category Filiation
+ */
+export declare const ineffectiveAmong: (bar: TrackerBar, readings: readonly {
+    id: string;
+    meaning: TrackMeaning;
+    place: HorizontalSpan;
+}[]) => Set<string>;
+/**
+ * The presence of every reading in every copy of the collation.
+ *
+ * A copy lacking a reading is taken to lack it only where it could show
+ * it: inside its text, away from its tears, and in its own system's
+ * words. A copy re-cut for a system that holds what another latches
+ * carries a latched pair where one of its held commands stands for it;
+ * where it holds the same function nearby without standing for the pair,
+ * or where the pair was ineffective anyway, it cannot say.
+ * @category Filiation
+ */
+export declare const presenceIn: (edition: Pick<Edition, 'copies'>, collation: CopyCollation, margin?: Millimeters) => PresenceMatrix;

package/lib/filiation/presence.js

@@ -0,0 +1,122 @@
+import { barOf, tearsOf } from "../model/RollCopy.js";
+import { mm } from "../model/Quantity.js";
+import { reads } from "./readings.js";
+/** How far beyond the end of its text, or the edge of a tear, a copy cannot say what it lacks. */
+export const defaultMargin = mm(3);
+/** How far from a held command of the same function a copy cannot say whether it holds a latched pair. */
+const HELD_REACH = mm(5);
+/** The function a latching command sets or cancels, and whether it sets it, or nothing for any other. */
+const latchOf = (bar, meaning) => {
+    if (meaning.type !== 'expression')
+        return undefined;
+    const operation = bar.operationOf(meaning.expressionType);
+    if (!operation || operation.spelling === 'held')
+        return undefined;
+    return {
+        latch: operation.sided ? `${operation.operates} ${meaning.scope}` : operation.operates,
+        on: operation.spelling === 'on'
+    };
+};
+/** The function a command operates, the side included where it counts, whatever its spelling. */
+const functionOf = (bar, meaning) => {
+    if (meaning.type !== 'expression')
+        return undefined;
+    const operation = bar.operationOf(meaning.expressionType);
+    return operation && (operation.sided ? `${operation.operates} ${meaning.scope}` : operation.operates);
+};
+/**
+ * The readings a latched function makes no use of in the text given: a
+ * command setting what is set already, or cancelling what is cancelled.
+ * Commands at one place are taken cancel first, as the valves take them.
+ * @category Filiation
+ */
+export const ineffectiveAmong = (bar, readings) => {
+    const byLatch = new Map();
+    for (const reading of readings) {
+        const latch = latchOf(bar, reading.meaning);
+        if (!latch)
+            continue;
+        const commands = byLatch.get(latch.latch) ?? [];
+        commands.push({ id: reading.id, at: reading.place.from, on: latch.on });
+        byLatch.set(latch.latch, commands);
+    }
+    const ineffective = new Set();
+    for (const commands of byLatch.values()) {
+        commands.sort((a, b) => a.at - b.at || Number(a.on) - Number(b.on));
+        let on = false;
+        for (const command of commands) {
+            if (command.on === on)
+                ineffective.add(command.id);
+            on = command.on;
+        }
+    }
+    return ineffective;
+};
+const within = (at, span, margin) => at >= span.from - margin && at <= span.to + margin;
+/**
+ * The presence of every reading in every copy of the collation.
+ *
+ * A copy lacking a reading is taken to lack it only where it could show
+ * it: inside its text, away from its tears, and in its own system's
+ * words. A copy re-cut for a system that holds what another latches
+ * carries a latched pair where one of its held commands stands for it;
+ * where it holds the same function nearby without standing for the pair,
+ * or where the pair was ineffective anyway, it cannot say.
+ * @category Filiation
+ */
+export const presenceIn = (edition, collation, margin = defaultMargin) => {
+    const copyOf = new Map(edition.copies.map(copy => [copy.id, copy]));
+    const barFor = new Map(collation.copies.map(id => [id, barOf(copyOf.get(id))]));
+    const placeOf = new Map();
+    for (const id of collation.copies) {
+        for (const feature of copyOf.get(id).production?.produced ?? []) {
+            if ('horizontal' in feature && feature.horizontal)
+                placeOf.set(feature.id, feature.horizontal);
+        }
+    }
+    const redundant = new Set();
+    for (const copy of collation.copies) {
+        const carried = collation.readings.flatMap(reading => {
+            const index = reading.copies.indexOf(copy);
+            if (index < 0)
+                return [];
+            return [{ id: reading.id, meaning: reading.meaning, place: placeOf.get(reading.carriers[index]) ?? reading.place }];
+        });
+        ineffectiveAmong(barFor.get(copy), carried).forEach(id => redundant.add(id));
+    }
+    const standsFor = new Map();
+    for (const recoding of collation.recodings) {
+        for (const replaced of recoding.replaced)
+            standsFor.set(replaced, [...(standsFor.get(replaced) ?? []), ...recoding.by]);
+    }
+    const copiesOf = new Map(collation.readings.map(reading => [reading.id, new Set(reading.copies)]));
+    const heldBy = new Map(collation.copies.map(copy => [copy, collation.readings.filter(reading => reading.meaning.type === 'expression' && copiesOf.get(reading.id).has(copy))]));
+    const tears = new Map(collation.copies.map(copy => [copy, tearsOf(copyOf.get(copy)).map(tear => tear.horizontal)]));
+    const presenceOf = (reading, copy) => {
+        if (copiesOf.get(reading.id).has(copy))
+            return 'present';
+        const at = reading.place.from;
+        if (!within(at, collation.extent[copy], margin))
+            return 'unknown';
+        if (tears.get(copy).some(tear => within(at, tear, margin)))
+            return 'unknown';
+        const bar = barFor.get(copy);
+        if (reads(bar, reading.meaning))
+            return 'absent';
+        if (reading.meaning.type !== 'expression')
+            return 'unknown';
+        if ((standsFor.get(reading.id) ?? []).some(by => copiesOf.get(by)?.has(copy)))
+            return 'present';
+        if (redundant.has(reading.id))
+            return 'unknown';
+        const wanted = functionOf(barFor.get(reading.copies[0]), reading.meaning);
+        const held = heldBy.get(copy).some(other => functionOf(bar, other.meaning) === wanted
+            && at >= other.place.from - HELD_REACH && at <= other.place.to + HELD_REACH);
+        return held ? 'unknown' : 'absent';
+    };
+    const presence = {};
+    for (const reading of collation.readings) {
+        presence[reading.id] = Object.fromEntries(collation.copies.map(copy => [copy, presenceOf(reading, copy)]));
+    }
+    return { copies: [...collation.copies], presence, redundant: [...redundant].sort() };
+};