linked-rolls 0.62.0 → 0.64.0

package/lib/analysis/reservations.d.ts

@@ -1,6 +1,6 @@
 import { RollCopy } from "../model/RollCopy.js";
 import { Version } from "../model/Version.js";
-import { EditionView } from "../view/EditionView.js";
+import { Edition } from "../model/Edition.js";
 export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'software-not-named', 'instrument-not-named', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated', 'system-unknown', 'keeper-unknown'];
 export type ReservationType = typeof reservationTypes[number];
 /**
@@ -27,4 +27,4 @@ export declare const reservationsAbout: (copy: RollCopy) => Reservation[];
 export declare const versionReservationTypes: readonly ['text-not-stated', 'witnessed-by-statement-only', 'no-direct-witness'];
 export type VersionReservationType = typeof versionReservationTypes[number];
 /** What the edition cannot vouch for in a version, in the order the checks are listed. */
-export declare const reservationsAboutVersion: (view: EditionView, version: Readonly<Version>) => Reservation<VersionReservationType>[];
+export declare const reservationsAboutVersion: (edition: Edition, version: Readonly<Version>) => Reservation<VersionReservationType>[];

package/lib/analysis/reservations.js

@@ -105,12 +105,12 @@ export const versionReservationTypes = [
     'witnessed-by-statement-only',
     'no-direct-witness'
 ];
-const textStated = (_view, version) => version.edits ? undefined : {
+const textStated = (_edition, version) => version.edits ? undefined : {
     type: 'text-not-stated',
     note: 'The version does not state its edits, so it reads as the version it derives from.'
 };
-const witnessedByFeatures = (view, version) => {
-    const witnesses = witnessesOf(view, version.id);
+const witnessedByFeatures = (edition, version) => {
+    const witnesses = witnessesOf(edition, version.id);
     return witnesses.length > 0 && witnesses.every(({ by }) => by === 'statement') ? {
         type: 'witnessed-by-statement-only',
         note: 'No copy\'s features carry what the version inserts; only copies that state they carry it bear witness to it.'
@@ -121,8 +121,8 @@ const witnessedByFeatures = (view, version) => {
  * Its text is a reconstruction from below, as a lost state's is, and
  * nothing surviving shows it as it stood.
  */
-const witnessedAtFirstHand = (view, version) => {
-    const carriers = witnessesOf(view, version.id).filter(({ by }) => by === 'carriers');
+const witnessedAtFirstHand = (edition, version) => {
+    const carriers = witnessesOf(edition, version.id).filter(({ by }) => by === 'carriers');
     return carriers.length > 0 && carriers.every(({ through }) => through !== undefined) ? {
         type: 'no-direct-witness',
         note: 'No copy carries it at first hand; its text is a reconstruction from the versions derived from it.'
@@ -130,4 +130,4 @@ const witnessedAtFirstHand = (view, version) => {
 };
 const versionChecks = [textStated, witnessedByFeatures, witnessedAtFirstHand];
 /** What the edition cannot vouch for in a version, in the order the checks are listed. */
-export const reservationsAboutVersion = (view, version) => versionChecks.flatMap(check => check(view, version) ?? []);
+export const reservationsAboutVersion = (edition, version) => versionChecks.flatMap(check => check(edition, version) ?? []);

package/lib/analysis/sigla.d.ts

@@ -1,13 +1,12 @@
 import { Edition } from '../model/Edition.js';
-import { EditionView } from '../view/EditionView.js';
 /**
- * What the sigla are read off: the versions alone, or a view, which knows
- * the copies as well and so can tell which versions a witness shows.
+ * What the sigla are read off: the versions alone, or the edition, whose
+ * copies tell which versions a witness shows.
  */
-export type Stemma = Pick<Edition, 'versions'> | EditionView;
+export type Stemma = Pick<Edition, 'versions'> | Edition;
 /**
  * The siglum of every version, as the stemma stands: where it sits
- * (`alongTheStemma`) and, given a view, whether any copy shows it.
+ * (`alongTheStemma`) and, given the edition, whether any copy shows it.
  *
  * A version no copy's features carry at first hand is inferred, whether
  * it is reached only through the versions derived from it or a copy does

package/lib/analysis/sigla.js

@@ -91,7 +91,7 @@ const alongTheStemma = (versions) => {
     }
     return sigla;
 };
-const isView = (stemma) => !('versions' in stemma);
+const holdsCopies = (stemma) => 'copies' in stemma;
 /**
  * The sigla with the inferred versions in lowercase, as editions mark a
  * state nothing surviving shows. The letter still names the system and
@@ -100,7 +100,7 @@ const isView = (stemma) => !('versions' in stemma);
 const marking = (sigla, attested) => new Map([...sigla].map(([id, siglum]) => [id, attested.has(id) ? siglum : siglum.toLowerCase()]));
 /**
  * The siglum of every version, as the stemma stands: where it sits
- * (`alongTheStemma`) and, given a view, whether any copy shows it.
+ * (`alongTheStemma`) and, given the edition, whether any copy shows it.
  *
  * A version no copy's features carry at first hand is inferred, whether
  * it is reached only through the versions derived from it or a copy does
@@ -112,8 +112,8 @@ const marking = (sigla, attested) => new Map([...sigla].map(([id, siglum]) => [i
  * A siglum is computed anew when the stemma or the copies change, so
  * nothing should cite one without saying which state it belongs to.
  */
-export const siglaOf = (stemma) => isView(stemma)
-    ? marking(alongTheStemma(stemma.edition.versions), attestedVersions(stemma))
+export const siglaOf = (stemma) => holdsCopies(stemma)
+    ? marking(alongTheStemma(stemma.versions), attestedVersions(stemma))
     : alongTheStemma(stemma.versions);
 /** The siglum of one version as the stemma stands, or nothing where the edition holds no such version. */
 export const siglumOf = (stemma, versionId) => siglaOf(stemma).get(versionId);

package/lib/analysis/stemma.d.ts

@@ -0,0 +1,22 @@
+/** Walking the stemma of an edition along the principal derivations. */
+import { Edition } from "../model/Edition.js";
+import { Version } from "../model/Version.js";
+/**
+ * The version and its ancestors along the principal line, from the
+ * version up to the root. A stemma that loops back on itself is walked
+ * once round, so that an edition in that state can still be read and
+ * repaired.
+ */
+export declare const lineageOf: (edition: Pick<Edition, 'versions'>, versionId: string) => Readonly<Version>[];
+/** The version the given one's text is read against, by its principal derivation. */
+export declare const predecessorOf: (edition: Pick<Edition, 'versions'>, versionId: string) => Readonly<Version> | undefined;
+/**
+ * Every version with its generation: how many principal derivations
+ * lie between it and the root. A version whose parent the edition does
+ * not hold counts as a root. In a stemma that loops, the loop is walked
+ * once round, as `lineageOf` walks it, so that the stemma of an edition
+ * in that state can still be drawn and repaired.
+ */
+export declare const withGenerations: (edition: Pick<Edition, 'versions'>) => Array<Version & {
+    generation: number;
+}>;

package/lib/analysis/stemma.js

@@ -0,0 +1,38 @@
+import { principalDerivationOf } from "../model/Version.js";
+import { idOf } from "../model/Assumption.js";
+import { versionIn } from "../lookup/lookup.js";
+/**
+ * The version and its ancestors along the principal line, from the
+ * version up to the root. A stemma that loops back on itself is walked
+ * once round, so that an edition in that state can still be read and
+ * repaired.
+ */
+export const lineageOf = (edition, versionId) => {
+    const lineage = [];
+    const visited = new Set();
+    let v = versionIn(edition, versionId);
+    while (v && !visited.has(v.id)) {
+        visited.add(v.id);
+        lineage.push(v);
+        const principal = principalDerivationOf(v);
+        v = principal && versionIn(edition, idOf(principal));
+    }
+    return lineage;
+};
+/** The version the given one's text is read against, by its principal derivation. */
+export const predecessorOf = (edition, versionId) => {
+    const v = versionIn(edition, versionId);
+    const principal = v && principalDerivationOf(v);
+    return principal && versionIn(edition, idOf(principal));
+};
+/**
+ * Every version with its generation: how many principal derivations
+ * lie between it and the root. A version whose parent the edition does
+ * not hold counts as a root. In a stemma that loops, the loop is walked
+ * once round, as `lineageOf` walks it, so that the stemma of an edition
+ * in that state can still be drawn and repaired.
+ */
+export const withGenerations = (edition) => edition.versions.map(version => ({
+    ...version,
+    generation: lineageOf(edition, version.id).length - 1
+}));

package/lib/analysis/text.d.ts

@@ -0,0 +1,31 @@
+/** What a version shows, and where along the roll its symbols lie. */
+import { Edition } from "../model/Edition.js";
+import { FeatureOrPatch, HorizontalSpan, NestedFeature } from "../model/Feature.js";
+import { AnySymbol } from "../model/Symbol.js";
+import { Millimeters } from "../model/Quantity.js";
+export declare const carriersOf: (edition: Pick<Edition, 'copies'>, symbol: AnySymbol) => Readonly<NestedFeature>[];
+/** The carriers that state a place of their own, which a feature on a patch does not. */
+export declare const placedCarriersOf: (edition: Pick<Edition, 'copies'>, symbol: AnySymbol) => Readonly<FeatureOrPatch>[];
+/**
+ * Where along the roll the symbol lies, as its carriers put it, or
+ * nothing for a symbol no copy carries.
+ *
+ * Only the place is measured. Which track the symbol sits on is not
+ * a measurement but a question for a tracker bar, since a note of
+ * one pitch sits on exactly one position of a given bar: ask
+ * `bar.positionOf`. The carriers cannot answer it, because a copy
+ * cut for another system numbers its tracks differently, and one
+ * symbol may be carried by copies of both — averaging a red carrier
+ * on track 47 with a green one on 45 would give 46, a legal
+ * position a semitone away on either bar.
+ */
+export declare const placeOf: (edition: Pick<Edition, 'copies'>, symbol: AnySymbol) => Readonly<HorizontalSpan> | undefined;
+/** Where the symbol begins, as the mean onset of its carriers, or nothing for a symbol without a place. */
+export declare const onsetOf: (edition: Pick<Edition, 'copies'>, symbol: AnySymbol) => Millimeters | undefined;
+/**
+ * The symbols the version shows: what it and its ancestors insert,
+ * each version's deletions striking what it or its ancestors inserted.
+ * They are worked out once for each state of the edition, and the list
+ * is frozen, since everyone who asks is handed the same one.
+ */
+export declare const snapshotOf: (edition: Edition, versionId: string) => readonly Readonly<AnySymbol>[];

package/lib/analysis/text.js

@@ -0,0 +1,62 @@
+import { isPlaced } from "../model/Feature.js";
+import { deletedBy, insertedBy } from "../model/Version.js";
+import { idsOf } from "../model/Assumption.js";
+import { mean } from "../model/Quantity.js";
+import { featuresIn } from "../lookup/lookup.js";
+import { perState } from "../lookup/perState.js";
+import { lineageOf } from "./stemma.js";
+export const carriersOf = (edition, symbol) => featuresIn(edition, idsOf(symbol.carriers));
+/** The carriers that state a place of their own, which a feature on a patch does not. */
+export const placedCarriersOf = (edition, symbol) => carriersOf(edition, symbol).filter(isPlaced);
+/**
+ * Where along the roll the symbol lies, as its carriers put it, or
+ * nothing for a symbol no copy carries.
+ *
+ * Only the place is measured. Which track the symbol sits on is not
+ * a measurement but a question for a tracker bar, since a note of
+ * one pitch sits on exactly one position of a given bar: ask
+ * `bar.positionOf`. The carriers cannot answer it, because a copy
+ * cut for another system numbers its tracks differently, and one
+ * symbol may be carried by copies of both — averaging a red carrier
+ * on track 47 with a green one on 45 would give 46, a legal
+ * position a semitone away on either bar.
+ */
+export const placeOf = (edition, symbol) => {
+    const carriers = placedCarriersOf(edition, symbol);
+    if (carriers.length === 0)
+        return;
+    return {
+        unit: 'mm',
+        from: mean(carriers.map(carrier => carrier.horizontal.from)),
+        to: mean(carriers.map(carrier => carrier.horizontal.to))
+    };
+};
+/** Where the symbol begins, as the mean onset of its carriers, or nothing for a symbol without a place. */
+export const onsetOf = (edition, symbol) => placeOf(edition, symbol)?.from;
+/** The symbols by onset, those without a place first; symbols at one place keep their order. */
+const inOrderOfPlace = (edition, symbols) => symbols
+    .map(symbol => ({ symbol, at: onsetOf(edition, symbol) || 0 }))
+    .sort((a, b) => a.at - b.at)
+    .map(({ symbol }) => symbol);
+/** The snapshots of a state asked for so far, by version. */
+const snapshotsIn = perState((_) => new Map());
+/**
+ * The symbols the version shows: what it and its ancestors insert,
+ * each version's deletions striking what it or its ancestors inserted.
+ * They are worked out once for each state of the edition, and the list
+ * is frozen, since everyone who asks is handed the same one.
+ */
+export const snapshotOf = (edition, versionId) => {
+    const known = snapshotsIn(edition);
+    const kept = known.get(versionId);
+    if (kept)
+        return kept;
+    const deleted = new Set();
+    const symbols = lineageOf(edition, versionId).flatMap(version => {
+        deletedBy(version).forEach(id => deleted.add(id));
+        return insertedBy(version).filter(symbol => !deleted.has(symbol.id));
+    });
+    const snapshot = Object.freeze(inOrderOfPlace(edition, symbols));
+    known.set(versionId, snapshot);
+    return snapshot;
+};

package/lib/analysis/witnesses.d.ts

@@ -1,5 +1,5 @@
 import { Belief, Certainty } from "../model/Assumption.js";
-import { EditionView } from "../view/EditionView.js";
+import { Edition } from "../model/Edition.js";
 export type WitnessBy = 'carriers' | 'statement';
 /** A copy that bears witness to a version, and how. */
 export interface Witness {
@@ -25,7 +25,7 @@ export interface Witness {
  * the versions derived from it, or is attested by statement alone, and
  * its text is a reconstruction rather than a reading.
  */
-export declare const attestedVersions: (view: EditionView) => ReadonlySet<string>;
+export declare const attestedVersions: (edition: Edition) => ReadonlySet<string>;
 /**
  * The copies that bear witness to the version: those whose features carry
  * a symbol the version's own edits insert, and those that state they carry
@@ -44,12 +44,12 @@ export declare const attestedVersions: (view: EditionView) => ReadonlySet<string
  * reported as it stands. A version whose edits are not stated inserts
  * nothing and is witnessed by statement alone.
  */
-export declare const witnessesOf: (view: EditionView, versionId: string) => Witness[];
+export declare const witnessesOf: (edition: Edition, versionId: string) => Witness[];
 /**
  * The versions the copy bears witness to, each with how, in the order the
  * edition lists its versions.
  */
-export declare const versionsWitnessedBy: (view: EditionView, copyId: string) => (Witness & {
+export declare const versionsWitnessedBy: (edition: Edition, copyId: string) => (Witness & {
     version: string;
 })[];
 export type CarriageProblem = {
@@ -62,4 +62,4 @@ export type CarriageProblem = {
  * made although the copy's features carry symbols, which say by
  * themselves what it carries, and one naming a version the edition lacks.
  */
-export declare const carriageProblems: (view: EditionView) => CarriageProblem[];
+export declare const carriageProblems: (edition: Edition) => CarriageProblem[];

package/lib/analysis/witnesses.js

@@ -1,24 +1,26 @@
 import { certaintyOf, idOf, idsOf } from "../model/Assumption.js";
 import { insertedBy } from "../model/Version.js";
+import { lineageOf } from "./stemma.js";
+import { copyOfFeature, versionIn } from "../lookup/lookup.js";
 /** The copies whose features carry any of the symbols. */
-const copiesCarrying = (view, symbols) => new Set(symbols
+const copiesCarrying = (edition, symbols) => new Set(symbols
     .flatMap(symbol => idsOf(symbol.carriers))
     .flatMap(id => {
-    const copy = view.copyOf(id);
+    const copy = copyOfFeature(edition, id);
     return copy ? [copy.id] : [];
 }));
 /** Every copy carrying what a version inserts, version by version, the copies in the order the edition lists them. */
-const carriagesIn = (view) => view.edition.versions.flatMap(version => {
-    const carrying = copiesCarrying(view, insertedBy(version));
-    const depth = view.lineageOf(version.id).length;
-    return view.edition.copies
+const carriagesIn = (edition) => edition.versions.flatMap(version => {
+    const carrying = copiesCarrying(edition, insertedBy(version));
+    const depth = lineageOf(edition, version.id).length;
+    return edition.copies
         .filter(copy => carrying.has(copy.id))
         .map((copy) => ({ copy: copy.id, version: version.id, depth }));
 });
-const carriersIn = (view) => {
-    const carriages = carriagesIn(view);
+const carriersIn = (edition) => {
+    const carriages = carriagesIn(edition);
     return {
-        copiesOf: new Map(view.edition.versions.map(version => [
+        copiesOf: new Map(edition.versions.map(version => [
             version.id,
             carriages.filter(carriage => carriage.version === version.id).map(carriage => carriage.copy)
         ])),
@@ -34,15 +36,15 @@ const carriersIn = (view) => {
  * the versions derived from it, or is attested by statement alone, and
  * its text is a reconstruction rather than a reading.
  */
-export const attestedVersions = (view) => new Set(carriersIn(view).latestOf.values());
-const witnessesIn = (carriers, view, versionId) => {
+export const attestedVersions = (edition) => new Set(carriersIn(edition).latestOf.values());
+const witnessesIn = (carriers, edition, versionId) => {
     const carrying = carriers.copiesOf.get(versionId) ?? [];
     const byCarriers = carrying.map((copy) => {
         const latest = carriers.latestOf.get(copy);
         return { copy, by: 'carriers', ...(latest !== undefined && latest !== versionId && { through: latest }) };
     });
     const carryingIt = new Set(carrying);
-    const byStatement = view.edition.copies
+    const byStatement = edition.copies
         .filter(copy => !carryingIt.has(copy.id))
         .flatMap(copy => (copy.carries ?? [])
         .filter(statement => idOf(statement) === versionId)
@@ -70,14 +72,14 @@ const witnessesIn = (carriers, view, versionId) => {
  * reported as it stands. A version whose edits are not stated inserts
  * nothing and is witnessed by statement alone.
  */
-export const witnessesOf = (view, versionId) => view.version(versionId) ? witnessesIn(carriersIn(view), view, versionId) : [];
+export const witnessesOf = (edition, versionId) => versionIn(edition, versionId) ? witnessesIn(carriersIn(edition), edition, versionId) : [];
 /**
  * The versions the copy bears witness to, each with how, in the order the
  * edition lists its versions.
  */
-export const versionsWitnessedBy = (view, copyId) => {
-    const carriers = carriersIn(view);
-    return view.edition.versions.flatMap(version => witnessesIn(carriers, view, version.id)
+export const versionsWitnessedBy = (edition, copyId) => {
+    const carriers = carriersIn(edition);
+    return edition.versions.flatMap(version => witnessesIn(carriers, edition, version.id)
         .filter(witness => witness.copy === copyId)
         .map(witness => ({ ...witness, version: version.id })));
 };
@@ -86,13 +88,13 @@ export const versionsWitnessedBy = (view, copyId) => {
  * made although the copy's features carry symbols, which say by
  * themselves what it carries, and one naming a version the edition lacks.
  */
-export const carriageProblems = (view) => {
-    const carrying = copiesCarrying(view, view.edition.versions.flatMap(insertedBy));
-    return view.edition.copies.flatMap(copy => (copy.carries ?? []).flatMap((statement) => {
+export const carriageProblems = (edition) => {
+    const carrying = copiesCarrying(edition, edition.versions.flatMap(insertedBy));
+    return edition.copies.flatMap(copy => (copy.carries ?? []).flatMap((statement) => {
         const version = idOf(statement);
         return [
             ...(carrying.has(copy.id) ? [{ copy: copy.id, version, problem: 'stated-beside-carriers' }] : []),
-            ...(view.version(version) ? [] : [{ copy: copy.id, version, problem: 'version-missing' }])
+            ...(versionIn(edition, version) ? [] : [{ copy: copy.id, version, problem: 'version-missing' }])
         ];
     }));
 };

package/lib/collation/alignment.d.ts

@@ -1,14 +1,34 @@
 import { FeatureOrPatch } from "../model/Feature.js";
-import { RollCopy, Shift } from "../model/RollCopy.js";
+import { Alignment, RollCopy } from "../model/RollCopy.js";
 import { TrackerBar } from "../systems/TrackerBar.js";
 import { Millimeters } from "../model/Quantity.js";
-export declare const applyShift: (shift: Shift, copy: RollCopy) => void;
-/** Scales the copy's features away from the beginning of the roll, and records the factor. */
-export declare const applyScale: (factor: number, copy: RollCopy) => void;
-/** Takes the shift off the copy's features again, as far as one was applied. */
-export declare const revertShift: (copy: RollCopy) => void;
-/** Takes the scale off the copy's features again, as far as one was applied. */
-export declare const revertScale: (copy: RollCopy) => void;
+/** A place on the copy's own paper, on the edition's axis. */
+export declare const toAxis: (alignment: Alignment | undefined) => (place: Millimeters) => Millimeters;
+/** A place on the edition's axis, on the copy's own paper. */
+export declare const fromAxis: (alignment: Alignment | undefined) => (place: Millimeters) => Millimeters;
+/**
+ * Carries the copy's features and tears from its own places onto the
+ * axis, and records how, in place of any alignment it had: that one is
+ * taken off first.
+ */
+export declare const applyAlignment: (alignment: Alignment, copy: RollCopy) => void;
+/** Takes the copy's features and tears back to its own places, as far as it was aligned. */
+export declare const revertAlignment: (copy: RollCopy) => void;
+/**
+ * The copy with its features and tears at its own places, as a document
+ * holds them, and its alignment kept to say how they go onto the axis.
+ * The copy given is left as it is. A copy that is not aligned is the
+ * very same copy.
+ */
+export declare const atOwnPlaces: (copy: RollCopy) => RollCopy;
+/**
+ * Puts the features and tears of a copy read from a document, which
+ * holds them at the copy's own places, onto the axis. The copy given is
+ * changed.
+ */
+export declare const putOnAxis: (copy: RollCopy) => void;
+/** The copy's features at its own places, as it was read, whatever alignment it has. */
+export declare const ownFeaturesOf: (copy: RollCopy) => FeatureOrPatch[];
 /**
  * Takes the extension a pneumatic reader adds off the ends of the
  * copy's chains of holes, and records how much was taken.
@@ -59,6 +79,16 @@ export declare const tooShortToShorten: (extension: Millimeters, copy: RollCopy,
 export declare const shortenChains: (extension: Millimeters, copy: RollCopy, leaving?: ReadonlySet<string>) => void;
 /** Puts the reader's extension back on the chains it was taken off, as far as one was taken off. */
 export declare const revertShortening: (copy: RollCopy) => void;
+/**
+ * The method `alignFeatures` follows, as an alignment records it. Its
+ * revision changes when the method does and at no other release, so
+ * that an alignment found by an earlier method can be told from one
+ * that would be found again as it stands.
+ */
+export declare const ALIGNMENT_METHOD: {
+    readonly software: 'linked-rolls alignFeatures';
+    readonly version: '1';
+};
 /**
  * How a copy's places are carried onto another copy's:
  * `x_other = (x + shift) · scale`.
@@ -71,6 +101,14 @@ export interface AlignmentResult {
     matched: number;
     /** How far the counterparts still lie apart, as a root mean square in the other copy's millimetres. */
     residual: Millimeters;
+    /**
+     * The standard error of the scale, as for a line of least squares
+     * through the matches: the residual over the spread of the matched
+     * notes along the copy, and over the root of their number. The
+     * robust line is fitted otherwise, but on Welte 225 this comes
+     * within a few per cent of what resampling the matches gives.
+     */
+    scaleError: number;
 }
 /**
  * Finds the shift and scale that carry the places of `rollA` onto those