linked-rolls 0.70.0 → 0.72.0

package/lib/collation/statistics.js

@@ -9,7 +9,10 @@ import { quantity } from "../model/Quantity.js";
  * stood out; a median and a median absolute deviation leave them out of
  * account.
  */
-/** The middle of a sample, the mean of the two middle values where it has an even number of them. */
+/**
+ * The middle of a sample, the mean of the two middle values where it has an even number of them.
+ * @internal
+ */
 export const medianOf = (values) => {
     if (values.length === 0)
         return undefined;
@@ -21,7 +24,10 @@ export const medianOf = (values) => {
 };
 /** What the median absolute deviation must be multiplied by to estimate the standard deviation of a normal sample. */
 const MAD_TO_SIGMA = 1.4826;
-/** Where the sample sits and how far it scatters, or nothing for an empty sample. */
+/**
+ * Where the sample sits and how far it scatters, or nothing for an empty sample.
+ * @internal
+ */
 export const spreadOf = (values) => {
     const median = medianOf(values);
     if (median === undefined)
@@ -33,7 +39,10 @@ export const spreadOf = (values) => {
         sigma: quantity(MAD_TO_SIGMA * (medianOf(deviations) ?? 0))
     };
 };
-/** How far the value lies from the centre of the spread, in units of its scatter. */
+/**
+ * How far the value lies from the centre of the spread, in units of its scatter.
+ * @internal
+ */
 export const standardise = (value, spread) => (value - spread.median) / spread.sigma;
 /** The complementary error function, after Press et al., whose fractional error stays below 1.2e-7. */
 const erfc = (x) => {
@@ -44,9 +53,15 @@ const erfc = (x) => {
             t * (-0.82215223 + t * 0.17087277)))))))));
     return x >= 0 ? tail : 2 - tail;
 };
-/** The share of a normal sample lying below `z` standard deviations. */
+/**
+ * The share of a normal sample lying below `z` standard deviations.
+ * @internal
+ */
 export const normalBelow = (z) => erfc(-z / Math.SQRT2) / 2;
-/** The share of a normal sample lying further than `z` standard deviations from its centre, on either side. */
+/**
+ * The share of a normal sample lying further than `z` standard deviations from its centre, on either side.
+ * @internal
+ */
 export const normalBeyond = (z) => erfc(z / Math.SQRT2);
 const horner = (coefficients, x) => coefficients.reduce((total, coefficient) => total * x + coefficient, 0);
 const CENTRAL_NUMERATOR = [
@@ -74,6 +89,7 @@ const tailQuantile = (share) => {
  * How many standard deviations out the given share of a normal sample
  * lies below, after Acklam's rational approximation, whose relative
  * error stays below 1.15e-9. The inverse of `normalBelow`.
+ * @internal
  */
 export const normalQuantile = (share) => {
     if (share <= 0)
@@ -92,9 +108,13 @@ export const normalQuantile = (share) => {
  * How much heavier the tails of a standardised sample are than a normal
  * sample's. Zero for a normal shape, positive where more of the sample
  * lies far out than the curve allows.
+ * @internal
  */
 export const excessKurtosisOf = (standardised) => standardised.reduce((total, z) => total + z ** 4, 0) / standardised.length - 3;
-/** What the sample puts beyond the given distance, against what a normal sample would. */
+/**
+ * What the sample puts beyond the given distance, against what a normal sample would.
+ * @internal
+ */
 export const tailOf = (standardised, beyond) => ({
     beyond,
     observed: standardised.filter(z => Math.abs(z) > beyond).length,
@@ -104,6 +124,7 @@ export const tailOf = (standardised, beyond) => ({
  * The sample counted into bins of the given width, laid out on
  * multiples of that width so that two histograms of one width share
  * their bounds. Nothing for an empty sample or a width of nothing.
+ * @internal
  */
 export const histogramOf = (values, binWidth) => {
     if (values.length === 0 || binWidth <= 0)

package/lib/collation/substitution.d.ts

@@ -8,11 +8,13 @@ export type { Operation, Spelling } from "../systems/TrackerBar.js";
  * nothing for a word no bar here knows or one without a counterpart in
  * another scale. The bars share their words where they share a scale,
  * as the Licensee does the T-100's, so the first that reads it answers.
+ * @category Systems and emulation
  */
 export declare const operationOf: (expressionType: string) => Operation | undefined;
 /**
  * A latched function of the older version and the held command of the
  * newer one that stands for it.
+ * @category Collation and alignment
  */
 export interface Substitution {
     /** The command that turned the function on, and the one that cancelled it. */
@@ -30,6 +32,7 @@ export interface Substitution {
  * command. The T-98 punches a hold as a chain of round holes on a
  * 2.66 mm grid with bridges of about a millimetre, so a scan read hole
  * by hole shows a run where the paper shows one command.
+ * @category Collation and alignment
  */
 export declare const defaultChainGap: import("../index.js").Quantity<"mm">;
 /**
@@ -42,6 +45,7 @@ export declare const defaultChainGap: import("../index.js").Quantity<"mm">;
  * the green bar, so drawing it as a perforation is out of the question,
  * but an edit still has to be shown somewhere, and the lane the green
  * scale gives the same function is where it belongs.
+ * @internal
  */
 export declare const positionOfSameFunction: (bar: TrackerBar, symbol: Expression) => Track | undefined;
 /**
@@ -54,5 +58,6 @@ export declare const positionOfSameFunction: (bar: TrackerBar, symbol: Expressio
  * reported and the editor is left to say what happened. Nothing is
  * invented either: both sides are perforations somebody punched, and all
  * this asserts is which stands for which.
+ * @category Collation and alignment
  */
 export declare const substitutionsBetween: (own: readonly AnySymbol[], inherited: readonly AnySymbol[], locate: Locate, tolerance?: CollationTolerance, chainGap?: Millimeters) => Substitution[];

package/lib/collation/substitution.js

@@ -6,6 +6,7 @@ import { trackerBars } from "../systems/index.js";
  * nothing for a word no bar here knows or one without a counterpart in
  * another scale. The bars share their words where they share a scale,
  * as the Licensee does the T-100's, so the first that reads it answers.
+ * @category Systems and emulation
  */
 export const operationOf = (expressionType) => {
     for (const bar of trackerBars) {
@@ -20,6 +21,7 @@ export const operationOf = (expressionType) => {
  * command. The T-98 punches a hold as a chain of round holes on a
  * 2.66 mm grid with bridges of about a millimetre, so a scan read hole
  * by hole shows a run where the paper shows one command.
+ * @category Collation and alignment
  */
 export const defaultChainGap = mm(3);
 const isExpression = (symbol) => symbol.type === 'expression';
@@ -35,6 +37,7 @@ const functionKey = (symbol, operation) => operation.sided ? `${operation.operat
  * the green bar, so drawing it as a perforation is out of the question,
  * but an edit still has to be shown somewhere, and the lane the green
  * scale gives the same function is where it belongs.
+ * @internal
  */
 export const positionOfSameFunction = (bar, symbol) => {
     const wanted = operationOf(symbol.expressionType);
@@ -132,6 +135,7 @@ const theOnly = (items) => items.length === 1 ? items[0] : undefined;
  * reported and the editor is left to say what happened. Nothing is
  * invented either: both sides are perforations somebody punched, and all
  * this asserts is which stands for which.
+ * @category Collation and alignment
  */
 export const substitutionsBetween = (own, inherited, locate, tolerance = defaultCollationTolerance, chainGap = defaultChainGap) => {
     const latched = latchedIn(inherited, locate);

package/lib/emulation/Emulation.d.ts

@@ -4,6 +4,10 @@ import { Version } from "../model/Version.js";
 import { AnyPerformedRollFeature, EmulatedCurve, NegotiatedEvent, ReproducingSystem } from "../systems/ReproducingSystem.js";
 import { Millimeters } from "../model/Quantity.js";
 import { Edition } from "../model/Edition.js";
+/**
+ * Which part of a version `emulate` plays, and where its clock starts.
+ * @category Systems and emulation
+ */
 export type EmulationScope = {
     /** Only notes whose onset lies within this span of the roll are played. */
     range?: [Millimeters, Millimeters];
@@ -15,15 +19,20 @@ export type EmulationScope = {
  * left as they were. The edition supplies the copies, whose measurements
  * decide how far before or after its reference a command goes, and a
  * punch diameter, or a millimetre, where no copy agrees with a statement.
+ * @category Systems and emulation
  */
 export declare const withPlacementsApplied: (edition: Edition, events: readonly NegotiatedEvent[]) => NegotiatedEvent[];
 /**
  * The commands of a version as the bar performs them, in order of place,
  * within the scope and with the placements applied. A note plays only
  * where its onset falls in the range; expressions play throughout.
+ * @category Systems and emulation
  */
 export declare const negotiatedEventsOf: (edition: Edition, version: Readonly<Version>, bar: TrackerBar, { range }?: Pick<EmulationScope, 'range'>) => NegotiatedEvent[];
-/** A version performed: what was negotiated, and what the system made of it. */
+/**
+ * A version performed: what was negotiated, and what the system made of it.
+ * @category Systems and emulation
+ */
 export interface Emulated {
     /** The id of the version performed. */
     readonly source: string;
@@ -35,18 +44,21 @@ export interface Emulated {
 /**
  * Performs a version on a reproducing system: the symbols are negotiated
  * into placed events and the system plays them. Nothing given is changed.
+ * @category Systems and emulation
  */
 export declare const emulate: <Options extends object>(system: ReproducingSystem<Options>, version: Readonly<Version>, edition: Edition, options?: Options, { range, skipToFirstNote }?: EmulationScope) => Emulated;
 /**
  * The performed events as a MIDI file, in which every note and pedal step
  * is labelled with the symbol it performs. The file names the system, the
  * version and the options it was played with.
+ * @category Systems and emulation
  */
 export declare const midiOf: (events: readonly AnyPerformedRollFeature[], systemName: string, options: object, source?: string) => MidiFile;
 /**
  * A version of the edition, performed and kept: `emulate` and `midiOf`
  * with the result held on the object between the two calls. Prefer the
  * functions where nothing needs holding.
+ * @category Systems and emulation
  */
 export declare class Emulation<Options extends object> {
     readonly system: ReproducingSystem<Options>;
@@ -58,7 +70,10 @@ export declare class Emulation<Options extends object> {
     constructor(system: ReproducingSystem<Options>, options?: Options);
     /** Moves the negotiated events to where their statements put them; see `withPlacementsApplied`. */
     applyConstraints(edition: Edition): void;
+    /** Performs the version, keeps what came of it, and returns the performed events; see `emulate`. */
     emulateVersion(version: Version, edition: Edition, scope?: EmulationScope): AnyPerformedRollFeature[];
+    /** The performed events that sound or follow from the symbol with the id. */
     findEventsPerforming(id: string): AnyPerformedRollFeature[];
+    /** The performed events as a MIDI file; see `midiOf`. */
     asMIDI(): MidiFile;
 }

package/lib/emulation/Emulation.js

@@ -151,6 +151,7 @@ const earliestOf = (times) => times.length === 0 ? seconds(0) : times.reduce((so
  * left as they were. The edition supplies the copies, whose measurements
  * decide how far before or after its reference a command goes, and a
  * punch diameter, or a millimetre, where no copy agrees with a statement.
+ * @category Systems and emulation
  */
 export const withPlacementsApplied = (edition, events) => {
     const gap = meanPunchDiameterOf(edition) ?? mm(1);
@@ -168,6 +169,7 @@ export const withPlacementsApplied = (edition, events) => {
  * The commands of a version as the bar performs them, in order of place,
  * within the scope and with the placements applied. A note plays only
  * where its onset falls in the range; expressions play throughout.
+ * @category Systems and emulation
  */
 export const negotiatedEventsOf = (edition, version, bar, { range } = {}) => {
     const inScope = (event) => !range || event.type !== 'note' || (event.horizontal.from > range[0] && event.horizontal.from < range[1]);
@@ -180,6 +182,7 @@ export const negotiatedEventsOf = (edition, version, bar, { range } = {}) => {
 /**
  * Performs a version on a reproducing system: the symbols are negotiated
  * into placed events and the system plays them. Nothing given is changed.
+ * @category Systems and emulation
  */
 export const emulate = (system, version, edition, options = system.defaultOptions, { range, skipToFirstNote = false } = {}) => {
     const negotiated = negotiatedEventsOf(edition, version, system.trackerBar, { range });
@@ -202,6 +205,7 @@ export const emulate = (system, version, edition, options = system.defaultOption
  * The performed events as a MIDI file, in which every note and pedal step
  * is labelled with the symbol it performs. The file names the system, the
  * version and the options it was played with.
+ * @category Systems and emulation
  */
 export const midiOf = (events, systemName, options, source) => {
     const TICKS_PER_SECOND = 1000;
@@ -262,6 +266,8 @@ export const midiOf = (events, systemName, options, source) => {
             midi.push(controller(controllerOf(event), event.value, labelled ? deltaTime : 0));
         }
     }
+    // a standard MIDI file ends every track with this event
+    midi.push({ type: 'meta', subtype: 'endOfTrack', deltaTime: 0 });
     return {
         header: {
             ticksPerBeat: TICKS_PER_SECOND,
@@ -275,6 +281,7 @@ export const midiOf = (events, systemName, options, source) => {
  * A version of the edition, performed and kept: `emulate` and `midiOf`
  * with the result held on the object between the two calls. Prefer the
  * functions where nothing needs holding.
+ * @category Systems and emulation
  */
 export class Emulation {
     constructor(system, options = system.defaultOptions) {
@@ -322,6 +329,7 @@ export class Emulation {
     applyConstraints(edition) {
         this.negotiatedEvents = withPlacementsApplied(edition, this.negotiatedEvents);
     }
+    /** Performs the version, keeps what came of it, and returns the performed events; see `emulate`. */
     emulateVersion(version, edition, scope = {}) {
         const emulated = emulate(this.system, version, edition, this.options, scope);
         this.source = emulated.source;
@@ -330,9 +338,11 @@ export class Emulation {
         this.midiEvents = [...emulated.events];
         return this.midiEvents;
     }
+    /** The performed events that sound or follow from the symbol with the id. */
     findEventsPerforming(id) {
         return this.midiEvents.filter(event => event.performs.id === id);
     }
+    /** The performed events as a MIDI file; see `midiOf`. */
     asMIDI() {
         return midiOf(this.midiEvents, this.system.name, this.options, this.source);
     }

package/lib/emulation/negotiation.d.ts

@@ -10,5 +10,6 @@ import { Edition } from "../model/Edition.js";
  * transfer between systems leaves behind: a red `ForzandoOn` a
  * green version still inherits cannot be performed on a green
  * machine, and an edit has yet to say what took its place.
+ * @category Systems and emulation
  */
 export declare const negotiatedEventOf: (edition: Edition, symbol: Note | Expression, bar: TrackerBar) => NegotiatedEvent | null;

package/lib/emulation/negotiation.js

@@ -7,6 +7,7 @@ import { placeOf } from "../analysis/text.js";
  * transfer between systems leaves behind: a red `ForzandoOn` a
  * green version still inherits cannot be performed on a green
  * machine, and an edit has yet to say what took its place.
+ * @category Systems and emulation
  */
 export const negotiatedEventOf = (edition, symbol, bar) => {
     const horizontal = placeOf(edition, symbol);

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,190 @@
+/** 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)) {
+            if (proposed.copy)
+                copiesBelow.get(at).add(proposed.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.copy ?? ''}|${[...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 = proposed.copy ? edition.copies.find(copy => copy.id === proposed.copy) : undefined;
+        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,12 @@
+/**
+ * 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";

package/lib/filiation/index.js

@@ -0,0 +1,12 @@
+/**
+ * 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";