linked-rolls 0.42.0 → 0.44.0

package/README.md

@@ -75,6 +75,83 @@ at. It then reads as the version it derives from, and
 `reservationsAboutVersion` says so. A file that names a single
 derivation loads as a list of one.
 
+What a version is called is not stored with it. `siglaOf` reads the
+sigla off the stemma as it stands, so a label never outlives the
+arrangement it describes, and nothing should cite one without saying
+which state of the edition it belongs to.
+
+## The tolerance a derivation was collated at
+
+`collationTolerance` on a derivation is the window two readings of one
+symbol must fall in to be collated: how far apart they may lie at
+either end, and, since two copies differ by a systematic offset as well
+as by scatter, where that window is centred. A window naming no offset
+is centred on nothing, which is what every window written before the
+offset was held here means.
+
+The number decides what counts as a reading at all, so it is worth
+measuring rather than picking. `scatterOfCopy` measures how far one
+copy puts each symbol from where the copies collated with it put it,
+and `scatterOf` describes that sample: its median, its scatter as a
+median absolute deviation scaled to a standard deviation, a histogram
+with the normal curve to lay over it, and the readings the curve does
+not account for. The scatter is taken from the median because the
+displacements an editor is looking for are in the sample, and a
+standard deviation would grow towards them until they no longer stood
+out.
+
+The tolerance that follows is the scatter times a threshold fixed by
+the size of the sample, the point beyond which fewer than one reading
+is expected to fall by chance (`departureThreshold`). For the few
+hundred readings an edge of a stemma yields this lands a little above
+three. `toleranceAcross` covers several samples with one window, since
+a derivation states one tolerance while notes and expressions scatter
+differently, and `inferredTolerance` builds the belief the number rests
+on, to annotate `collationTolerance` with. It is held likely and not
+true: the tolerance follows from the sample only as far as the sample
+is normal, which is what the reported excess kurtosis and tail counts
+are there to show.
+
+Two limits are worth naming. Notes and expressions are estimated apart
+by default, which is a stopgap standing in for a skew across the width
+of the paper rather than a distinction in the model, so the grouping is
+a parameter of the estimator and appears nowhere in the format. And the
+method screens: it says which readings the curve does not account for,
+and an editor says which of those are editorial acts.
+
+A separation reports which end made it (`separatedBy`, and
+`admittedAtEnds` for a collation). The two ends answer different
+questions: the onset, with the kind, decides whether two copies read one
+command, and the end decides whether that command was lengthened or
+shortened. On welte225.org the end alone decides 24 collations of 2839
+and the onset alone 39, so neither test is idle, but a difference at the
+end is as often a punch measured badly as a punch genuinely prolonged,
+and the two are not worth confusing.
+
+## Collating a derivation a second time
+
+A collated symbol is one symbol carrying every copy that reads it, so a
+collation cannot simply be run again: there is no second symbol left to
+match. `separateReadings` is the inverse. It takes one copy's carriers
+back off the symbols it shares, gives them to new symbols of the
+version's own, and states the exchange, leaving the edition in the state
+a collation would have produced had nothing joined. `connectVersions` at
+a new tolerance then re-collates, joining again whatever the new window
+admits.
+
+Nothing an editor established is lost by that. `connectVersions`
+rewrites only what a collation wrote (`isCollationsOwn`): a bare
+insertion or deletion, or an equivalence between two systems' spellings.
+An edit naming what the change is, why it was made, or what it rests on
+stays, and the symbols it speaks for are left out of the collation. An
+equivalence counts as the collation's own, since it is derived from the
+two systems' vocabularies rather than read off the paper and freezing it
+would leave the transfers uncollatable, but one drawn a second time over
+the very same symbols is kept as it stands, identifier and motivation
+and all. Readings already separated by hand are carried by one copy
+alone, so `separateReadings` passes over them and they keep their
+identifiers.
+
 ## What brought a feature about
 
 A copy states no list of features. Each feature stands in the act that
@@ -140,8 +217,8 @@ they carry it, a statement with the belief it rests on;
 `versionsWitnessedBy` gathers the same from the side of a copy.
 `carriageProblems` reports a statement made beside features that carry
 symbols already, or one naming a version the edition lacks. A copy may
-carry a `siglum`, as a version does; one without is named by its
-keeper.
+carry a `siglum`, which is given by hand and not read off anything;
+one without is named by its keeper.
 
 ```ts
 import { reservationsAbout, stateSource } from 'linked-rolls'

package/lib/Agent.d.ts

@@ -67,10 +67,15 @@ export type WithActor = {
 export interface Place extends Named {
 }
 /**
- * A term from a vocabulary, such as a roll system or a kind of
- * paper. A term the type vocabulary knows carries its IRI as `id`.
+ * A term from a vocabulary, such as a roll system, a procedure or a
+ * kind of paper.
+ *
+ * A term the type vocabulary declares is named by its IRI, and what it
+ * is called stands in the vocabulary rather than in the edition, so it
+ * needs no name of its own; `nameOf` reads one either way. A term the
+ * vocabulary does not have is given by name, which is then all there is
+ * to go on.
  * @see crm:E55 Type
  */
-export interface Concept extends Named, Partial<WithId> {
-}
+export type Concept = (WithId & Partial<Named>) | (Named & Partial<WithId>);
 export {};

package/lib/Collation.d.ts

@@ -1,17 +1,69 @@
+import { Edit } from "./Edit";
 import { HorizontalSpan } from "./Feature";
 import { AnySymbol } from "./Symbol";
 import { Millimeters } from "./Quantity";
+/** A value taken at each end of a feature: where it begins and where it stops. */
+export interface BothEnds<T> {
+    from: T;
+    to: T;
+}
+/** How far one text puts a feature from where another puts it, at either end. */
+export type Displacement = BothEnds<Millimeters>;
 /**
- * Tolerance used in collation of roll copies: the acceptable deviation
- * at either end when aligning features across copies.
+ * The window two readings of one feature must fall in to be collated:
+ * how far apart they may lie at either end, and where that window is
+ * centred.
+ *
+ * The centre is worth stating. Two copies of one roll differ by a
+ * systematic offset as well as by scatter, and a window centred on
+ * nothing has to be widened by the whole of that offset before it
+ * admits what the offset alone displaces. Naming the offset lets the
+ * tolerance stand for the scatter only. A window that names none is
+ * centred on nothing, which is what every window written before the
+ * offset was held here means.
  */
 export interface CollationTolerance {
-    /** Tolerance at the start position of a feature. */
+    /** How far the two readings may lie apart at the start of a feature, measured from `offsetStart`. */
     toleranceStart: Millimeters;
-    /** Tolerance at the end position of a feature. */
+    /** How far they may lie apart at the end, measured from `offsetEnd`. */
     toleranceEnd: Millimeters;
+    /**
+     * How much later the collated copy puts the start of a feature than
+     * the copy it is read against, where the two differ systematically.
+     * Nothing where they do not.
+     */
+    offsetStart?: Millimeters;
+    /** The same at the end of a feature. */
+    offsetEnd?: Millimeters;
 }
 export declare const defaultCollationTolerance: CollationTolerance;
+/** Where the window is centred at the start of a feature, on nothing where it names no offset. */
+export declare const offsetStartOf: (tolerance: CollationTolerance) => Millimeters;
+/** Where the window is centred at the end of a feature. */
+export declare const offsetEndOf: (tolerance: CollationTolerance) => Millimeters;
+/**
+ * Whether the window admits the displacement at each end, taken apart.
+ *
+ * The two ends answer different questions. The onset, with the kind,
+ * decides identity: whether the two copies read one command. The end
+ * decides duration: whether the same command was lengthened or
+ * shortened. A collation joins two readings only where both admit, so a
+ * separation may be the work of either, and an editor looking at one
+ * wants to know which.
+ *
+ * A difference at the end alone has at least three causes and only the
+ * first is an editorial act. A punch may genuinely have been lengthened
+ * or shortened. A chain of punches, bridged to keep the paper strong,
+ * may have been read as one perforation on one copy and as repeated
+ * notes on the other, which Phillips names as a common error of roll
+ * scanning and which runs in both directions (p. 173). Or a reading may
+ * report something other than the punched slot, as a pneumatic reader
+ * reports how long a valve stayed open. Long held notes are where the
+ * second is likeliest, since that is where the chains are.
+ */
+export declare const admittedAtEnds: (tolerance: CollationTolerance, displacement: Displacement) => BothEnds<boolean>;
+/** Whether the window admits the displacement: within the tolerance of the offset, at both ends. */
+export declare const admits: (tolerance: CollationTolerance, displacement: Displacement) => boolean;
 /** Where a symbol lies along the roll, as its carriers put it, or nothing for a symbol without a place. */
 export type Locate = (symbol: AnySymbol) => Readonly<HorizontalSpan> | undefined;
 /**
@@ -26,3 +78,21 @@ export type Collation = {
 };
 /** Each of the own symbols with every inherited symbol it collates with, both in the order given. */
 export declare const collationsOf: (own: readonly Readonly<AnySymbol>[], inherited: readonly Readonly<AnySymbol>[], locate: Locate, tolerance?: CollationTolerance) => Collation[];
+/**
+ * Whether the edit is one a collation writes by itself: a bare
+ * insertion or a bare deletion saying nothing further, or an
+ * equivalence between two systems' spellings for one command.
+ *
+ * Collating again rewrites these and keeps the rest. An edit that says
+ * what the change is, or why it was made, or what it rests on, is an
+ * editor's reading of the difference between two texts, and collating
+ * the two again is no reason to discard it.
+ *
+ * An equivalence counts as the collation's own even where an editor
+ * added a motivation to it, because it is derived rather than read:
+ * freezing it would leave the transfers, where nearly every edit is
+ * one, unable to be collated again at all. What an editor wrote on it
+ * is not lost by that, since `connectVersions` keeps an equivalence it
+ * draws a second time over the very same symbols.
+ */
+export declare const isCollationsOwn: (edit: Readonly<Edit>) => boolean;

package/lib/Collation.js

@@ -1,7 +1,41 @@
 import { keyOf } from "./TrackerBar";
 import { distance, mm } from "./Quantity";
 import { partitionPoint } from "./sorted";
+import { groupBy } from "./utils";
 export const defaultCollationTolerance = { toleranceStart: mm(5), toleranceEnd: mm(5) };
+/** Where the window is centred at the start of a feature, on nothing where it names no offset. */
+export const offsetStartOf = (tolerance) => tolerance.offsetStart ?? mm(0);
+/** Where the window is centred at the end of a feature. */
+export const offsetEndOf = (tolerance) => tolerance.offsetEnd ?? mm(0);
+/**
+ * Whether the window admits the displacement at each end, taken apart.
+ *
+ * The two ends answer different questions. The onset, with the kind,
+ * decides identity: whether the two copies read one command. The end
+ * decides duration: whether the same command was lengthened or
+ * shortened. A collation joins two readings only where both admit, so a
+ * separation may be the work of either, and an editor looking at one
+ * wants to know which.
+ *
+ * A difference at the end alone has at least three causes and only the
+ * first is an editorial act. A punch may genuinely have been lengthened
+ * or shortened. A chain of punches, bridged to keep the paper strong,
+ * may have been read as one perforation on one copy and as repeated
+ * notes on the other, which Phillips names as a common error of roll
+ * scanning and which runs in both directions (p. 173). Or a reading may
+ * report something other than the punched slot, as a pneumatic reader
+ * reports how long a valve stayed open. Long held notes are where the
+ * second is likeliest, since that is where the chains are.
+ */
+export const admittedAtEnds = (tolerance, displacement) => ({
+    from: distance(displacement.from, offsetStartOf(tolerance)) <= tolerance.toleranceStart,
+    to: distance(displacement.to, offsetEndOf(tolerance)) <= tolerance.toleranceEnd
+});
+/** Whether the window admits the displacement: within the tolerance of the offset, at both ends. */
+export const admits = (tolerance, displacement) => {
+    const ends = admittedAtEnds(tolerance, displacement);
+    return ends.from && ends.to;
+};
 /**
  * What a symbol says, as a key: the pitch of a note, the type and scope
  * of an expression. Symbols collate within one key only. This is the
@@ -10,8 +44,8 @@ export const defaultCollationTolerance = { toleranceStart: mm(5), toleranceEnd:
  * what carries a note across a transfer between systems.
  */
 const kindOf = (symbol) => symbol.type === 'text' ? 'text' : keyOf(symbol);
-const nearby = (here, there, tolerance) => distance(here.from, there.from) <= tolerance.toleranceStart
-    && distance(here.to, there.to) <= tolerance.toleranceEnd;
+const displacementBetween = (here, there) => ({ from: mm(here.from - there.from), to: mm(here.to - there.to) });
+const nearby = (here, there, tolerance) => admits(tolerance, displacementBetween(here, there));
 /**
  * Two symbols collate when they are of one kind, say the same thing
  * (pitch, or expression type and scope), and lie at about the same
@@ -28,15 +62,6 @@ const placed = (symbols, locate) => symbols.flatMap((symbol, index) => {
     const horizontal = locate(symbol);
     return horizontal ? [{ symbol, index, horizontal }] : [];
 });
-const groupBy = (items, keyOf) => items.reduce((groups, item) => {
-    const key = keyOf(item);
-    const group = groups.get(key);
-    if (group)
-        group.push(item);
-    else
-        groups.set(key, [item]);
-    return groups;
-}, new Map());
 /** The placed symbols by kind, each kind in order of onset. */
 const byKindInOrderOfOnset = (symbols) => {
     const groups = groupBy(symbols, ({ symbol }) => kindOf(symbol));
@@ -47,8 +72,9 @@ const byKindInOrderOfOnset = (symbols) => {
 const WINDOW_SLACK = 1e-9;
 /** The symbols of a kind whose onset lies within the start tolerance of the span. */
 const nearOnsetOf = (kind, span, tolerance) => {
-    const lowest = span.from - tolerance.toleranceStart - WINDOW_SLACK;
-    const highest = span.from + tolerance.toleranceStart + WINDOW_SLACK;
+    const centre = span.from - offsetStartOf(tolerance);
+    const lowest = centre - tolerance.toleranceStart - WINDOW_SLACK;
+    const highest = centre + tolerance.toleranceStart + WINDOW_SLACK;
     const first = partitionPoint(kind, candidate => candidate.horizontal.from < lowest);
     const end = partitionPoint(kind, candidate => candidate.horizontal.from <= highest);
     return kind.slice(first, end);
@@ -61,3 +87,24 @@ export const collationsOf = (own, inherited, locate, tolerance = defaultCollatio
         .sort((a, b) => a.index - b.index)
         .map(({ symbol: counterpart }) => ({ symbol, counterpart })));
 };
+/** The edit type a collation draws by itself, from the two systems' vocabularies rather than off the paper. */
+const drawnByCollation = 'replace-with-equivalent';
+/**
+ * Whether the edit is one a collation writes by itself: a bare
+ * insertion or a bare deletion saying nothing further, or an
+ * equivalence between two systems' spellings for one command.
+ *
+ * Collating again rewrites these and keeps the rest. An edit that says
+ * what the change is, or why it was made, or what it rests on, is an
+ * editor's reading of the difference between two texts, and collating
+ * the two again is no reason to discard it.
+ *
+ * An equivalence counts as the collation's own even where an editor
+ * added a motivation to it, because it is derived rather than read:
+ * freezing it would leave the transfers, where nearly every edit is
+ * one, unable to be collated again at all. What an editor wrote on it
+ * is not lost by that, since `connectVersions` keeps an equivalence it
+ * draws a second time over the very same symbols.
+ */
+export const isCollationsOwn = (edit) => edit.editType === drawnByCollation
+    || (edit.editType === undefined && edit.motivation === undefined && edit['@annotation'] === undefined);

package/lib/Edition.d.ts

@@ -29,9 +29,15 @@ export interface EditionCreation {
      */
     publicationDate: Date;
     /**
-     * The tolerance parameters used when collating (aligning)
-     * the different roll copies for this edition.
+     * The tolerance every version of the edition was collated at,
+     * before each derivation stated its own. How precisely two copies
+     * place a symbol depends on which two they are, so the tolerance
+     * belongs to the derivation, `Derivation.collationTolerance`, and
+     * migration writes this one onto every derivation that gives none.
+     * Nothing else reads it. A window's offset is the displacement
+     * between two particular copies and so can never be stated here.
      * Not exported to RDF.
+     * @deprecated
      */
     collationTolerance?: CollationTolerance;
 }

package/lib/Version.d.ts

@@ -1,6 +1,6 @@
 import { Edit } from "./Edit";
 import { Concept } from "./Agent";
-import { ActorAssignment, Belief, Certainty, DateAssignment, ReferenceAssumption } from "./Assumption";
+import { ActorAssignment, Belief, Certainty, DateAssignment, ObjectAssumption, ReferenceAssumption } from "./Assumption";
 import { CollationTolerance } from "./Collation";
 import { AnySymbol } from "./Symbol";
 import { WithId, WithNote, WithType } from "./utils";
@@ -22,8 +22,14 @@ export type Derivation = ReferenceAssumption & {
      * The tolerance at which the derived version was collated against
      * the one it is based on. A derivation written before the tolerance
      * was held here states none. Not exported to RDF.
+     *
+     * It is an object assumption, so that a tolerance calculated from
+     * the scatter of the readings can carry the inference it was drawn
+     * by. It is the one quantity in the edition that decides what
+     * counts as a reading at all, and a number arrived at by a method
+     * should say so.
      */
-    collationTolerance?: CollationTolerance;
+    collationTolerance?: ObjectAssumption<CollationTolerance>;
 };
 /** The tolerance the derivation was collated at, or the default where it states none. */
 export declare const collationToleranceOf: (derivation: Readonly<Derivation>) => CollationTolerance;
@@ -66,14 +72,6 @@ export interface VersionCreation {
  * @see lrmoo:F2 Expression
  */
 export interface Version extends WithId, WithType<'Version'> {
-    /**
-     * A label a document carries from before the sigla were computed.
-     * Nothing should write one here and nothing should show one: what a
-     * version is called comes from `siglaOf`.
-     * @deprecated
-     * @see reo:siglum
-     */
-    siglum?: string;
     /**
      * The reproducing system this version is coded for. One roll was
      * often issued for several of them, and a version is a reading in

package/lib/editionOps.d.ts

@@ -157,14 +157,46 @@ export declare const mergeFeatures: (copyId: string, featureIds: readonly string
  * and the child lacks becomes its deletions. The derivation states the
  * tolerance it was collated at and becomes the principal one; the
  * hypotheses the child stated beside its former one stay.
+ *
+ * The edits the child already stated are rewritten only as far as a
+ * collation wrote them (`isCollationsOwn`). An editor's reading of the
+ * difference between the two texts stays, and the symbols it speaks for
+ * are left out of the collation, so that connecting the two again
+ * neither doubles them nor silently drops what somebody established by
+ * hand. An equivalence is the collation's own, since it is drawn from
+ * the two systems' vocabularies rather than read off the paper, but one
+ * drawn again over the very same symbols is kept as it stands, with its
+ * identifier and whatever was written on it.
+ *
+ * The child's own text is what it shows less what the parent hands
+ * down, so that connecting two versions already connected collates the
+ * child's symbols and not the parent's with themselves.
  */
-export declare const connectVersions: (view: EditionView, childId: string, parentId: string, tolerance?: CollationTolerance) => EditionOp;
+export declare const connectVersions: (view: EditionView, childId: string, parentId: string, tolerance?: ObjectAssumption<CollationTolerance>) => EditionOp;
 /**
  * Folds the version's own symbols into those it inherits and collates
  * with: the carriers pass over, and the insertions go. Collates at the
  * tolerance of the derivation, where the caller names none.
  */
 export declare const collateSymbols: (view: EditionView, versionId: string, symbolIds: readonly string[], tolerance?: CollationTolerance) => EditionOp;
+/**
+ * Takes the copy's reading of a symbol back out of the symbol it was
+ * collated into: the copy's carriers pass to a new symbol of the
+ * version's own, the other copies keep the symbol they had, and the
+ * version states the exchange.
+ *
+ * This is the inverse of the hand-over a collation makes, and it is
+ * what lets a derivation be collated a second time. A collated symbol
+ * is one symbol carrying every copy that reads it, so nothing else
+ * takes the two readings apart again, and without that a tolerance
+ * arrived at after the fact could never be applied.
+ *
+ * Symbols the copy alone carries are already the version's own and are
+ * passed over, so a reading somebody has separated by hand keeps its
+ * identifier and the edit that speaks for it. Named symbols narrow the
+ * act to those; naming none separates the copy's whole reading.
+ */
+export declare const separateReadings: (view: EditionView, versionId: string, copyId: string, symbolIds?: readonly string[]) => EditionOp;
 /**
  * Makes the version stand on its own: what it inherited becomes its
  * own insertions, and its derivations go, the hypotheses among them,

package/lib/editionOps.js

@@ -2,7 +2,7 @@ import { current, isDraft } from "immer";
 import { v4 } from "uuid";
 import { getAt } from "./EditionView";
 import { isCommand, placementRelations } from "./Symbol";
-import { collationsOf, defaultCollationTolerance } from "./Collation";
+import { collationsOf, defaultCollationTolerance, isCollationsOwn } from "./Collation";
 import { collationToleranceOf, editsOf, insertedBy, principalDerivationOf } from "./Version";
 import { asSymbols, barOf, featuresByAct, featuresOf, isPaperStretch, statesNothing } from "./RollCopy";
 import { systemOf } from "./TrackerBar";
@@ -651,6 +651,20 @@ const dropDerivations = (version, matches) => {
     else
         delete version.basedOn;
 };
+/** The symbols a set of edits speaks for, whether by inserting or by deleting them. */
+const spokenForBy = (edits) => new Set(edits.flatMap(edit => [
+    ...(edit.insert ?? []).map(symbol => symbol.id),
+    ...(edit.delete ?? [])
+]));
+/** An exchange of symbols, as a key: what it puts in against what it takes out. */
+const exchangeKey = (inserted, deleted) => `${[...inserted].sort().join(',')}/${[...deleted].sort().join(',')}`;
+/**
+ * The edits already stated, by the exchange each of them makes. An
+ * equivalence the collation draws a second time is the one already
+ * stated, and drawing it again is no reason to mint a new identifier or
+ * to drop the motivation somebody wrote on it.
+ */
+const byExchange = (edits) => new Map(edits.map(edit => [exchangeKey((edit.insert ?? []).map(symbol => symbol.id), edit.delete ?? []), edit]));
 /**
  * Bases the child on the parent. A symbol of the child that collates
  * with one the parent hands down adds its carriers to that symbol; the
@@ -658,10 +672,36 @@ const dropDerivations = (version, matches) => {
  * and the child lacks becomes its deletions. The derivation states the
  * tolerance it was collated at and becomes the principal one; the
  * hypotheses the child stated beside its former one stay.
+ *
+ * The edits the child already stated are rewritten only as far as a
+ * collation wrote them (`isCollationsOwn`). An editor's reading of the
+ * difference between the two texts stays, and the symbols it speaks for
+ * are left out of the collation, so that connecting the two again
+ * neither doubles them nor silently drops what somebody established by
+ * hand. An equivalence is the collation's own, since it is drawn from
+ * the two systems' vocabularies rather than read off the paper, but one
+ * drawn again over the very same symbols is kept as it stands, with its
+ * identifier and whatever was written on it.
+ *
+ * The child's own text is what it shows less what the parent hands
+ * down, so that connecting two versions already connected collates the
+ * child's symbols and not the parent's with themselves.
  */
 export const connectVersions = (view, childId, parentId, tolerance = defaultCollationTolerance) => {
-    const inherited = view.snapshot(parentId);
-    const own = view.snapshot(childId);
+    const child = view.get(childId);
+    const stated = child ? editsOf(child) : [];
+    const established = stated.filter(edit => !isCollationsOwn(edit));
+    const spokenFor = spokenForBy(established);
+    const unspoken = (symbol) => !spokenFor.has(symbol.id);
+    // What the parent hands down and the child still shows passes
+    // through: it is neither the child's own symbol nor one it lacks.
+    // Without that, connecting a pair already connected would collate
+    // the inherited symbols with themselves and double their carriers.
+    const handedDown = view.snapshot(parentId).filter(unspoken);
+    const shown = new Set(view.snapshot(childId).map(symbol => symbol.id));
+    const inheritedIds = new Set(handedDown.map(symbol => symbol.id));
+    const inherited = handedDown.filter(symbol => !shown.has(symbol.id));
+    const own = view.snapshot(childId).filter(symbol => unspoken(symbol) && !inheritedIds.has(symbol.id));
     const locate = (symbol) => view.placeOf(symbol);
     const collations = collationsOf(own, inherited, locate, tolerance);
     const collated = new Set(collations.map(({ symbol }) => symbol.id));
@@ -673,18 +713,25 @@ export const connectVersions = (view, childId, parentId, tolerance = defaultColl
      * apart would make the apparatus a list of unexplained losses beside
      * a list of unexplained gains.
      */
-    const substituted = differ(view.get(childId), view.get(parentId))
+    const substituted = differ(child, view.get(parentId))
         ? substitutionsBetween(own.filter(symbol => !collated.has(symbol.id)), inherited.filter(symbol => !matched.has(symbol.id)), locate, tolerance)
         : [];
     const paired = new Set(substituted.flatMap(({ replaced, by }) => [...by, ...replaced].map(symbol => symbol.id)));
-    const edits = [
-        ...substituted.map(({ replaced, by }) => ({
+    const alreadyStated = byExchange(stated);
+    const equivalence = ({ replaced, by }) => {
+        const inserted = by.map(symbol => symbol.id);
+        const deleted = replaced.map(symbol => symbol.id);
+        return alreadyStated.get(exchangeKey(inserted, deleted)) ?? {
             type: 'edit',
             id: v4(),
             editType: 'replace-with-equivalent',
             insert: [...by],
-            delete: replaced.map(symbol => symbol.id)
-        })),
+            delete: deleted
+        };
+    };
+    const edits = [
+        ...established,
+        ...substituted.map(equivalence),
         ...own.filter(symbol => !collated.has(symbol.id) && !paired.has(symbol.id)).map(insertion),
         ...inherited
             .filter(symbol => !matched.has(symbol.id) && !paired.has(symbol.id))
@@ -718,6 +765,72 @@ export const collateSymbols = (view, versionId, symbolIds, tolerance) => {
         dropInsertions(version, collated);
     });
 };
+/** The symbol as one copy reads it: what it says, on the given carriers, standing in no relation of its own. */
+const readingOf = (symbol, carriers) => {
+    const identity = { id: v4(), carriers };
+    switch (symbol.type) {
+        case 'note':
+            return { type: 'note', pitch: symbol.pitch, ...identity };
+        case 'expression':
+            return { type: 'expression', expressionType: symbol.expressionType, scope: symbol.scope, ...identity };
+        case 'text':
+            return { type: 'text', text: symbol.text, ...identity };
+    }
+};
+/** The symbol where the copy and at least one other carry it, with the carriers of each side. */
+const sharedWith = (view, symbol, copyId) => {
+    const onCopy = (carrier) => view.copyOf(idOf(carrier))?.id === copyId;
+    const mine = symbol.carriers.filter(onCopy);
+    const theirs = symbol.carriers.filter(carrier => !onCopy(carrier));
+    return mine.length > 0 && theirs.length > 0 ? [{ symbol, mine, theirs }] : [];
+};
+/**
+ * Takes the copy's reading of a symbol back out of the symbol it was
+ * collated into: the copy's carriers pass to a new symbol of the
+ * version's own, the other copies keep the symbol they had, and the
+ * version states the exchange.
+ *
+ * This is the inverse of the hand-over a collation makes, and it is
+ * what lets a derivation be collated a second time. A collated symbol
+ * is one symbol carrying every copy that reads it, so nothing else
+ * takes the two readings apart again, and without that a tolerance
+ * arrived at after the fact could never be applied.
+ *
+ * Symbols the copy alone carries are already the version's own and are
+ * passed over, so a reading somebody has separated by hand keeps its
+ * identifier and the edit that speaks for it. Named symbols narrow the
+ * act to those; naming none separates the copy's whole reading.
+ */
+export const separateReadings = (view, versionId, copyId, symbolIds) => {
+    const version = view.get(versionId);
+    if (!version)
+        return noChange;
+    const chosen = symbolIds && new Set(symbolIds);
+    const shared = view.snapshot(versionId)
+        .filter(symbol => chosen === undefined || chosen.has(symbol.id))
+        .flatMap(symbol => sharedWith(view, symbol, copyId));
+    if (shared.length === 0)
+        return noChange;
+    const inserted = new Set(insertedBy(version).map(symbol => symbol.id));
+    const stated = editsOf(version);
+    const separations = shared.map(({ symbol, mine }) => ({
+        type: 'edit',
+        id: v4(),
+        insert: [readingOf(symbol, [...mine])],
+        // A symbol the version inserts itself stays where it is, minus
+        // the carriers that leave it. Only one it inherits is exchanged.
+        ...(inserted.has(symbol.id) ? {} : { delete: [symbol.id] })
+    }));
+    return onVersion(versionId, (version, draft) => {
+        shared.forEach(({ symbol, theirs }) => {
+            const path = view.getPath(symbol.id);
+            const target = path && getAt(path, draft);
+            if (target)
+                target.carriers = theirs;
+        });
+        version.edits = [...stated, ...separations];
+    });
+};
 /**
  * Makes the version stand on its own: what it inherited becomes its
  * own insertions, and its derivations go, the hypotheses among them,

package/lib/index.d.ts

@@ -18,11 +18,14 @@ export * from './ReproducingSystem';
 export * from './FeatureSource';
 export * from './RollCopy';
 export * from './procedures';
+export * from './vocabulary';
 export * from './reservations';
 export * from './witnesses';
 export * from './alignment';
+export * from './statistics';
 export * from './Edition';
 export * from './EditionView';
+export * from './scatter';
 export * from './editionOps';
 export * from './Emulation';
 export * from './validate';

package/lib/index.js

@@ -18,11 +18,14 @@ export * from './ReproducingSystem';
 export * from './FeatureSource';
 export * from './RollCopy';
 export * from './procedures';
+export * from './vocabulary';
 export * from './reservations';
 export * from './witnesses';
 export * from './alignment';
+export * from './statistics';
 export * from './Edition';
 export * from './EditionView';
+export * from './scatter';
 export * from './editionOps';
 export * from './Emulation';
 export * from './validate';

package/lib/migrate.js

@@ -40,6 +40,17 @@ const withoutVersionType = (node) => {
     const { versionType: _retired, ...rest } = node;
     return rest;
 };
+/**
+ * A version carried the label it was cited under, from before the sigla
+ * were read off the stemma. A copy keeps its siglum, which is given by
+ * hand and derives from nothing.
+ */
+const withoutVersionSiglum = (node) => {
+    if (node['@type'] !== 'Version' || !Object.hasOwn(node, 'siglum'))
+        return node;
+    const { siglum: _labelled, ...rest } = node;
+    return rest;
+};
 const withLowerCaseTerms = (node) => Object.entries(lowerCasedTerms).reduce((result, [key, terms]) => {
     const lowered = terms[result[key]];
     return lowered ? { ...result, [key]: lowered } : result;
@@ -221,7 +232,7 @@ const withTimeSpanDates = (node) => {
     const { '@value': within, '@type': _typed, ...rest } = node;
     return { ...rest, within };
 };
-const migrateNode = (node) => [withRenamedKeys, withTypology, withoutVersionType, withLowerCaseTerms, withSplitMethod, withReferences, withKeeper, withoutEmptyKeeper,
+const migrateNode = (node) => [withRenamedKeys, withTypology, withoutVersionType, withoutVersionSiglum, withLowerCaseTerms, withSplitMethod, withReferences, withKeeper, withoutEmptyKeeper,
     withProductionNodes, withScale, withDerivationList, withReadingKind, withTimeSpanDates, withoutFeatureKind,
     withBorneFeaturesNamed, withFeaturesInActs]
     .reduce((result, step) => step(result), node);