linked-rolls 0.14.0 → 0.16.0

package/lib/EditionView.js

@@ -13,8 +13,10 @@ export const getAt = (path, obj) => {
 /** Keys under which an object names others by id, singly or in a list. */
 const referenceKeys = ['delete', 'comprehends', 'motivation'];
 const isObject = (v) => v !== null && typeof v === "object";
-/** An object that names another by its id and says nothing else, save perhaps a belief about the reference. */
-const isReferenceOnly = (keys) => keys.every(key => key === 'id' || key === '@annotation');
+/** What a reference may state besides the id: a belief about it, and the tolerance a derivation was collated at. */
+const referenceOwnKeys = new Set(['id', '@annotation', 'collationTolerance']);
+/** An object that names another by its id and says nothing of its own beyond that. */
+const isReferenceOnly = (keys) => keys.every(key => referenceOwnKeys.has(key));
 const pathOf = (trail) => {
     const path = [];
     for (let link = trail; link !== null; link = link.up)

package/lib/Feature.d.ts

@@ -89,6 +89,14 @@ export declare const conditions: {
     readonly Mark: readonly ["faded"];
     readonly GluedOn: readonly ["detaching", "ripped"];
 };
+/** The kinds of condition a feature may be in, whichever kind of feature it is. */
+export type FeatureConditionType = typeof conditions[FeatureType][number];
+/**
+ * A condition assigned to a feature, annotatable with a belief about
+ * its certainty. Which of the kinds a feature may be in depends on its
+ * own kind, which `conditions` states.
+ */
+export type FeatureConditionAssignment = ObjectAssumption<ConditionState<FeatureConditionType>>;
 /**
  * A hole (perforation) in the roll paper. Holes are the primary
  * carriers of musical information on piano rolls, as they trigger
@@ -109,7 +117,7 @@ export interface Hole extends RollFeature<'Hole', typeof conditions.Hole[number]
  * A trace is a visible mark or writing on the roll surface.
  * Traces may fade over time.
  */
-export interface Trace<T extends FeatureType> extends RollFeature<T, typeof conditions.Mark[number]> {
+export interface Trace<T extends FeatureType> extends RollFeature<T, typeof conditions[T][number]> {
 }
 export declare const writingMethods: readonly ['Print', 'Handwriting', 'Stamp'];
 /**

package/lib/Quantity.d.ts

@@ -7,7 +7,7 @@
  * The unit names are the ones the records state in their `unit` field.
  */
 declare const unit: unique symbol;
-export type Unit = 'mm' | 'cm' | 'px' | 'track' | 's' | 'ms' | 'ft/min' | 'm/min';
+export type Unit = 'mm' | 'cm' | 'px' | 'track' | 's' | 'ms' | 'ft/min' | 'm/min' | 'px/in';
 export type Quantity<U extends Unit> = number & {
     readonly [unit]: U;
 };
@@ -22,6 +22,8 @@ export type Seconds = Quantity<'s'>;
 export type Milliseconds = Quantity<'ms'>;
 export type FeetPerMinute = Quantity<'ft/min'>;
 export type MetersPerMinute = Quantity<'m/min'>;
+/** How finely a scan was read: pixels of the image per inch of paper. */
+export type Resolution = Quantity<'px/in'>;
 export declare const mm: (value: number) => Quantity<"mm">;
 export declare const cm: (value: number) => Quantity<"cm">;
 export declare const px: (value: number) => Quantity<"px">;
@@ -30,6 +32,7 @@ export declare const seconds: (value: number) => Quantity<"s">;
 export declare const milliseconds: (value: number) => Quantity<"ms">;
 export declare const feetPerMinute: (value: number) => Quantity<"ft/min">;
 export declare const metersPerMinute: (value: number) => Quantity<"m/min">;
+export declare const pixelsPerInch: (value: number) => Quantity<"px/in">;
 /**
  * A value together with the unit it was measured in, as a record
  * states it.
@@ -56,6 +59,8 @@ export declare const sum: <U extends Unit>(values: readonly Quantity<U>[]) => Qu
 export declare const mean: <U extends Unit>(values: readonly Quantity<U>[]) => Quantity<U>;
 /** A place in a scan taken at `dpi` dots per inch, on the paper. */
 export declare const inMillimeters: (place: Pixels, dpi: number) => Millimeters;
+/** A place on the paper, in a scan taken at `dpi` dots per inch. */
+export declare const inPixels: (place: Millimeters, dpi: number) => Pixels;
 export declare const inCentimeters: (length: Millimeters) => Centimeters;
 export declare const inSeconds: (time: Milliseconds) => Seconds;
 /** A speed as a record states it, in feet or metres per minute. */

package/lib/Quantity.js

@@ -7,6 +7,7 @@ export const seconds = quantity;
 export const milliseconds = quantity;
 export const feetPerMinute = quantity;
 export const metersPerMinute = quantity;
+export const pixelsPerInch = quantity;
 // The second operand takes its unit from the first. Inferred from both,
 // TypeScript would unite two units rather than reject them.
 export const add = (a, b) => quantity(a + b);
@@ -21,6 +22,8 @@ export const mean = (values) => quantity(sum(values) / values.length);
 const MM_PER_INCH = 25.4;
 /** A place in a scan taken at `dpi` dots per inch, on the paper. */
 export const inMillimeters = (place, dpi) => mm(place / dpi * MM_PER_INCH);
+/** A place on the paper, in a scan taken at `dpi` dots per inch. */
+export const inPixels = (place, dpi) => px(place / MM_PER_INCH * dpi);
 export const inCentimeters = (length) => cm(length / 10);
 export const inSeconds = (time) => seconds(time / 1000);
 const METERS_PER_FOOT = 0.3048;

package/lib/RollCopy.d.ts

@@ -222,6 +222,16 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
          * Not exported to RDF.
          */
         scale: number;
+        /**
+         * The resolution this copy's scan was read at, along the roll.
+         * It is what the measurements given in pixels are to be read
+         * against, and what every conversion between a place in the
+         * scan and one on the paper goes through. A scanner may read
+         * across the roll at another resolution, which the analysis
+         * files do not state.
+         * @see reo:scanResolution
+         */
+        scanResolution: Measure<'px/in'>;
         /**
          * Relates this copy's scan to the tracker bar: how the scanning
          * software's hole numbering was shifted onto the bar, and where

package/lib/Version.d.ts

@@ -1,5 +1,6 @@
 import { Edit } from "./Edit";
 import { ReferenceAssumption } from "./Assumption";
+import { CollationTolerance } from "./Collation";
 import { AnySymbol } from "./Symbol";
 import { WithId, WithNote, WithType } from "./utils";
 export declare const versionTypes: readonly [
@@ -24,6 +25,23 @@ export type VersionType = typeof versionTypes[number];
  * @see crm:E33 Linguistic Object
  */
 export type Motivation = WithType<'motivation'> & WithId & WithNote;
+/**
+ * A derivation names the version another one was derived from, together
+ * with the tolerance the two were collated at. How precisely the copies
+ * put a symbol depends on what they are and on how their features were
+ * obtained, so the tolerance can differ from derivation to derivation.
+ * @see lrmoo:R76 is derivative of
+ */
+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.
+     */
+    collationTolerance?: CollationTolerance;
+};
+/** The tolerance the derivation was collated at, or the default where it states none. */
+export declare const collationToleranceOf: (derivation: Readonly<Derivation>) => CollationTolerance;
 /**
  * A version is defined by the sum of edits applied
  * to the version it is based on. For simple identification,
@@ -46,7 +64,7 @@ export interface Version extends WithId, WithType<'Version'> {
      * If no derivation is defined, it is assumed that this version represents the mother roll.
      * @see lrmoo:R76 is derivative of
      */
-    basedOn?: ReferenceAssumption;
+    basedOn?: Derivation;
     /**
      * The list of edits that, applied to the base version, produce this version.
      * @see reo:involvedEdit

package/lib/Version.js

@@ -1,3 +1,4 @@
+import { defaultCollationTolerance } from "./Collation";
 export const versionTypes = [
     /**
      * The roll is in a state where it is (possibly) used as
@@ -9,6 +10,8 @@ export const versionTypes = [
      */
     'unicum'
 ];
+/** The tolerance the derivation was collated at, or the default where it states none. */
+export const collationToleranceOf = (derivation) => derivation.collationTolerance ?? defaultCollationTolerance;
 /** The symbols the version's edits insert. */
 export const insertedBy = (version) => version.edits.flatMap(edit => edit.insert ?? []);
 /** The ids of the symbols the version's edits delete. */

package/lib/editionOps.d.ts

@@ -4,9 +4,10 @@ import { Edition } from "./Edition";
 import { AnySymbol, PlacementRelation } from "./Symbol";
 import { CollationTolerance } from "./Collation";
 import { Edit } from "./Edit";
-import { RollCopy, ScaleReading, Shift } from "./RollCopy";
+import { GeneralRollCondition, RollCopy, ScaleReading, Shift } from "./RollCopy";
 import { FeatureSource } from "./FeatureSource";
-import { AnyArgumentation, Certainty } from "./Assumption";
+import { AnyArgumentation, Certainty, ObjectAssumption } from "./Assumption";
+import { AnyFeature, FeatureConditionAssignment } from "./Feature";
 /**
  * A change to an edition, written onto an immer draft of it. One
  * operation is one undo step, so an operation that has to read the
@@ -35,25 +36,64 @@ export declare const unalignCopy: (copyId: string) => EditionOp;
 export declare const stateSource: (copyId: string, source: FeatureSource) => EditionOp;
 /** Takes back the statement, leaving the copy silent about its source again. */
 export declare const clearSource: (copyId: string) => EditionOp;
+/**
+ * Adds a general condition to the copy, beside whatever is stated of it
+ * already. The other condition a copy may be in, a paper stretch, is
+ * read off an alignment and stated by `alignCopy`.
+ */
+export declare const addGeneralCondition: (copyId: string, condition: ObjectAssumption<GeneralRollCondition>) => EditionOp;
+/**
+ * States the condition of the feature, in place of any earlier
+ * statement. Throws where the kind of feature is in no such condition;
+ * `conditions` says which conditions each kind of feature may be in.
+ */
+export declare const stateFeatureCondition: (copyId: string, featureId: string, condition: FeatureConditionAssignment) => EditionOp;
 /** The symbols of the versions that no other copy carries. */
 export declare const symbolsCarriedOnlyBy: (edition: Edition, copyId: string) => AnySymbol[];
 /** Takes the features off the copy, and out of the versions with what only they carried. */
 export declare const removeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;
 /**
  * Takes the copy out of the edition together with the symbols only it
- * carries, and with every reference the versions made to those symbols.
+ * carries, and with every reference the versions and the argumentations
+ * made to those symbols.
  */
 export declare const removeCopy: (copyId: string) => EditionOp;
+/** Why several features cannot be replaced by one. */
+export type MergeObstacle = 'fewer-than-two' | 'different-types' | 'different-tracks' | 'differing-conditions' | 'unlike-features';
+/**
+ * What stands in the way of reading the features as one, or nothing
+ * where they may be merged. Features may be merged where they differ
+ * in nothing but their place along the roll, their depiction and the
+ * condition at most one of them states. How far apart they lie is not
+ * asked: whether a gap is a bridge of the perforator, a tear or two
+ * perforations of their own is the editor's reading.
+ */
+export declare const mergeObstacle: (features: readonly AnyFeature[]) => MergeObstacle | undefined;
+/**
+ * Replaces the features of the copy with a single one covering them
+ * all, where a scan has split what the editor reads as one feature.
+ * The merged feature takes the place of the first it replaces and
+ * spans from the first to the last, any gap between them included.
+ * What the replaced features carried is carried by the merged one, and
+ * whatever else named them, a modification or a comprehension, names
+ * the merged one in their stead.
+ *
+ * Throws where the features cannot stand for one; `mergeObstacle`
+ * says beforehand whether they can.
+ */
+export declare const mergeFeatures: (copyId: string, featureIds: readonly string[]) => EditionOp;
 /**
  * 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
  * rest become the child's insertions, and what the parent hands down
- * and the child lacks becomes its deletions.
+ * and the child lacks becomes its deletions. The derivation states the
+ * tolerance it was collated at.
  */
 export declare const connectVersions: (view: EditionView, childId: string, parentId: string, tolerance?: CollationTolerance) => EditionOp;
 /**
  * Folds the version's own symbols into those it inherits and collates
- * with: the carriers pass over, and the insertions go.
+ * 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;
 /**

package/lib/editionOps.js

@@ -3,10 +3,11 @@ import { v4 } from "uuid";
 import { getAt } from "./EditionView";
 import { isPerforation, placementRelations } from "./Symbol";
 import { collationsOf, defaultCollationTolerance } from "./Collation";
-import { insertedBy } from "./Version";
+import { collationToleranceOf, insertedBy } from "./Version";
 import { asSymbols } from "./RollCopy";
 import { applyShift, applyScale, revertShift, revertScale } from "./alignment";
 import { assignReference, idOf } from "./Assumption";
+import { conditions as conditionsAllowed } from "./Feature";
 import { distance, mm, subtract } from "./Quantity";
 const noChange = () => undefined;
 const onCopy = (copyId, op) => draft => {
@@ -19,6 +20,11 @@ const onVersion = (versionId, op) => draft => {
     if (version)
         op(version, draft);
 };
+const onFeature = (copyId, featureId, op) => onCopy(copyId, copy => {
+    const feature = copy.features.find(f => f.id === featureId);
+    if (feature)
+        op(feature);
+});
 /**
  * The state a draft stands at, as plain data. Reading a draft proxies
  * everything it touches, so what is only read is read from this.
@@ -31,15 +37,24 @@ const mapped = (items, change) => {
     const changed = items.map(change);
     return changed.every((item, i) => item === items[i]) ? items : changed;
 };
+/** The items each changed, less those the change emptied; the very same array where it changed none. */
+const pruned = (items, change, emptied) => {
+    const changed = mapped(items, change);
+    return changed === items ? items : changed.filter((item, i) => item === items[i] || !emptied(item));
+};
+/** The record with the field replaced, or the very same record where that is what stood there. */
+const replacing = (record, key, value) => record[key] === value ? record : { ...record, [key]: value };
+/** The ids of the items the rewriting left out. */
+const droppedIds = (before, after) => {
+    const kept = new Set(after.map(item => item.id));
+    return before.flatMap(item => kept.has(item.id) ? [] : [item.id]);
+};
 const insertion = (symbol) => ({ type: 'edit', id: v4(), insert: [symbol] });
 const deletion = (symbolId) => ({ type: 'edit', id: v4(), delete: [symbolId] });
 const isEmpty = (edit) => !edit.insert?.length && !edit.delete?.length;
 const insertedIn = (versions) => versions.flatMap(insertedBy);
 /** The edits with the change applied, less those it emptied; the very same array where it changed none. */
-const edited = (edits, change) => {
-    const changed = mapped(edits, change);
-    return changed === edits ? edits : changed.filter((edit, i) => edit === edits[i] || !isEmpty(edit));
-};
+const edited = (edits, change) => pruned(edits, change, isEmpty);
 /** The edit without the symbols among its insertions, or the very same edit where it inserts none of them. */
 const droppingInsertions = (symbolIds) => (edit) => {
     const insert = edit.insert && without(edit.insert, symbol => symbolIds.has(symbol.id));
@@ -104,6 +119,34 @@ export const stateSource = (copyId, source) => onCopy(copyId, copy => {
 export const clearSource = (copyId) => onCopy(copyId, copy => {
     copy.readFrom = undefined;
 });
+/**
+ * Adds a general condition to the copy, beside whatever is stated of it
+ * already. The other condition a copy may be in, a paper stretch, is
+ * read off an alignment and stated by `alignCopy`.
+ */
+export const addGeneralCondition = (copyId, condition) => onCopy(copyId, copy => {
+    copy.conditions.push(condition);
+});
+/**
+ * Whether the feature's own kind allows a condition of this kind. The
+ * type narrowed to is the weaker statement, holding of a condition any
+ * kind of feature may be in.
+ */
+const allows = (feature, condition) => {
+    const allowed = conditionsAllowed[feature.type];
+    return allowed.includes(condition.conditionType);
+};
+/**
+ * States the condition of the feature, in place of any earlier
+ * statement. Throws where the kind of feature is in no such condition;
+ * `conditions` says which conditions each kind of feature may be in.
+ */
+export const stateFeatureCondition = (copyId, featureId, condition) => onFeature(copyId, featureId, feature => {
+    if (!allows(feature, condition)) {
+        throw new Error(`A ${feature.type} is in no '${condition.conditionType}' condition`);
+    }
+    feature.condition = condition;
+});
 const featureIdsOf = (copy) => new Set(copy.features.map(feature => feature.id));
 /**
  * A symbol every carrier of which lies among the features loses its
@@ -146,17 +189,97 @@ const forgettingFeatures = (features, dropped) => {
         return { ...edit, ...(insert && { insert }), ...(deleted && { delete: deleted }) };
     };
 };
+const isRecord = (value) => typeof value === 'object' && value !== null;
+/** The record's values each changed, or the very same record where the change left every one as it was. */
+const withValues = (record, change) => {
+    const entries = Object.entries(record);
+    const changed = entries.map(([key, value]) => [key, change(value)]);
+    return changed.every(([, value], i) => value === entries[i][1]) ? record : Object.fromEntries(changed);
+};
+/** The value with the change applied to every record within it and then to itself, innermost first. */
+const deeply = (change) => {
+    const changed = (value) => Array.isArray(value) ? mapped(value, changed)
+        : isRecord(value) ? change(withValues(value, changed))
+            : value;
+    return changed;
+};
+/** Whether the two stand alike, so that what differs within them can be written where it lies. */
+const alike = (before, after) => {
+    if (!isRecord(before) || !isRecord(after))
+        return false;
+    if (Array.isArray(before))
+        return Array.isArray(after) && before.length === after.length;
+    return !Array.isArray(after);
+};
+/** Writes onto the draft what the rewriting changed, as deep as the change reaches. */
+const writeInto = (draft, before, after) => Object.entries(after).forEach(([key, value]) => {
+    if (value === before[key])
+        return;
+    if (alike(before[key], value))
+        writeInto(draft[key], before[key], value);
+    else
+        draft[key] = value;
+});
+const isCopy = (record) => 'type' in record && record.type === 'RollCopy';
+const isBelief = (record) => 'type' in record && record.type === 'belief';
+const isComprehension = (reason) => reason.type === 'meaningComprehension';
+/** What the modification names, be it as added or as removed. */
+const membersOf = (modification) => modification.type === 'Addition' ? modification.added : modification.removed;
+const namesNothing = (modification) => membersOf(modification).length === 0;
+const comprehendsNothing = (reason) => isComprehension(reason) && reason.comprehends.length === 0;
+/** The modification with what it names rewritten, or the very same one where that leaves it as it was. */
+const renamingMembers = (rename) => (modification) => modification.type === 'Addition'
+    ? replacing(modification, 'added', rename(modification.added))
+    : replacing(modification, 'removed', rename(modification.removed));
+/** The reason with what a comprehension comprehends rewritten; any other reason names nothing of the kind. */
+const renamingComprehended = (rename) => (reason) => isComprehension(reason) ? replacing(reason, 'comprehends', rename(reason.comprehends)) : reason;
+/**
+ * The record with the ids it names rewritten: what a copy's
+ * modifications added or removed, and what the comprehensions among a
+ * belief's reasons comprehend. A modification or a comprehension the
+ * rewriting emptied goes with what it named; one that named nothing
+ * before stays, as an edit that was empty before it does.
+ */
+const renaming = (rename) => (record) => {
+    if (isCopy(record)) {
+        return replacing(record, 'modifications', pruned(record.modifications, renamingMembers(rename), namesNothing));
+    }
+    if (isBelief(record)) {
+        return replacing(record, 'reasons', pruned(record.reasons, renamingComprehended(rename), comprehendsNothing));
+    }
+    return record;
+};
 /**
- * Strikes the features from the versions: their carriers go, a symbol
- * that had no other carrier goes with them, and so does every
- * reference the versions made to such a symbol.
+ * Rewrites the ids by which the edition names features and symbols
+ * outside the versions. A belief is annotatable anywhere, so the whole
+ * edition is read; what the rewriting leaves alone is left the very
+ * object it was.
+ */
+const renameReferences = (draft, rename) => {
+    const before = stateOf(draft);
+    const after = deeply(renaming(rename))(before);
+    if (after !== before)
+        writeInto(draft, before, after);
+};
+/**
+ * Strikes the features from the edition: their carriers go, a symbol
+ * that had no other carrier goes with them, an edit left exchanging
+ * nothing goes as well, and so does every reference the versions, the
+ * modifications of the copies and the comprehensions made to what went.
  */
 const forgetFeatures = (draft, features) => {
     const versions = stateOf(draft.versions);
     const dropped = new Set(insertedIn(versions).filter(carriedOnlyOn(features)).map(symbol => symbol.id));
     const forget = forgettingFeatures(features, dropped);
+    const edits = versions.map(version => edited(version.edits, forget));
+    const gone = new Set([
+        ...features,
+        ...dropped,
+        ...versions.flatMap((version, i) => droppedIds(version.edits, edits[i]))
+    ]);
+    renameReferences(draft, ids => without(ids, id => gone.has(id)));
     draft.versions.forEach((version, i) => {
-        version.edits = edited(versions[i].edits, forget);
+        version.edits = edits[i];
     });
 };
 /** Takes the features off the copy, and out of the versions with what only they carried. */
@@ -167,12 +290,126 @@ export const removeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draf
 });
 /**
  * Takes the copy out of the edition together with the symbols only it
- * carries, and with every reference the versions made to those symbols.
+ * carries, and with every reference the versions and the argumentations
+ * made to those symbols.
  */
 export const removeCopy = (copyId) => onCopy(copyId, (copy, draft) => {
     forgetFeatures(draft, featureIdsOf(copy));
     draft.copies = draft.copies.filter(c => c.id !== copyId);
 });
+/**
+ * Whether two records of the edition state the same, the identity of a
+ * statement left out: two transcriptions reading the same word say the
+ * same, whichever ids they were given.
+ */
+const sayTheSame = (a, b) => {
+    if (a === b)
+        return true;
+    if (!isRecord(a) || !isRecord(b) || Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const keys = new Set([...Object.keys(a), ...Object.keys(b)]);
+    keys.delete('id');
+    return [...keys].every(key => sayTheSame(a[key], b[key]));
+};
+/** What a feature states beyond its identity, its place along the roll, its depiction and its condition. */
+const nature = (feature) => {
+    const { id, horizontal, depiction, condition, ...rest } = feature;
+    return rest;
+};
+const conditionsOf = (features) => features.flatMap(feature => feature.condition ? [feature.condition] : []);
+/**
+ * What stands in the way of reading the features as one, or nothing
+ * where they may be merged. Features may be merged where they differ
+ * in nothing but their place along the roll, their depiction and the
+ * condition at most one of them states. How far apart they lie is not
+ * asked: whether a gap is a bridge of the perforator, a tear or two
+ * perforations of their own is the editor's reading.
+ */
+export const mergeObstacle = (features) => {
+    if (features.length < 2)
+        return 'fewer-than-two';
+    const [first, ...rest] = features;
+    if (rest.some(feature => feature.type !== first.type))
+        return 'different-types';
+    if (rest.some(feature => !sayTheSame(feature.vertical, first.vertical)))
+        return 'different-tracks';
+    if (rest.some(feature => !sayTheSame(nature(feature), nature(first))))
+        return 'unlike-features';
+    const conditions = conditionsOf(features);
+    if (conditions.some(condition => !sayTheSame(condition, conditions[0])))
+        return 'differing-conditions';
+    return undefined;
+};
+/** The items with the replacement in the place of the first it stands for, the others dropped. */
+const standingFor = (items, stands, replacement) => {
+    const first = items.findIndex(stands);
+    if (first < 0)
+        return items;
+    return items.flatMap((item, i) => i === first ? [replacement] : stands(item) ? [] : [item]);
+};
+const spanning = (features) => ({
+    unit: 'mm',
+    from: mm(Math.min(...features.map(feature => feature.horizontal.from))),
+    to: mm(Math.max(...features.map(feature => feature.horizontal.to)))
+});
+/**
+ * The feature the merged ones give way to. It spans them all and is in
+ * every other respect the one of them that states a condition, the
+ * others being alike in all but their place. The depiction goes: a
+ * region of the scan showing one part depicts no more than that part.
+ */
+const mergedFrom = (features) => {
+    const stating = features.find(feature => feature.condition) ?? features[0];
+    const merged = { ...stating, id: v4(), horizontal: spanning(features) };
+    delete merged.depiction;
+    return merged;
+};
+/** The symbol carried by the merged feature where it named one of those it replaces, and naming it once. */
+const carriedByMerged = (replaced, mergedId) => (symbol) => {
+    const names = (carrier) => replaced.has(idOf(carrier));
+    const first = symbol.carriers.find(names);
+    if (!first)
+        return symbol;
+    return { ...symbol, carriers: standingFor(symbol.carriers, names, { ...first, id: mergedId }) };
+};
+/** Points the versions at the merged feature wherever they name one it replaces. */
+const carryOver = (draft, replaced, mergedId) => {
+    const recarry = carriedByMerged(replaced, mergedId);
+    const recarrying = (edit) => {
+        const insert = edit.insert && mapped(edit.insert, recarry);
+        return insert === edit.insert ? edit : { ...edit, insert };
+    };
+    const versions = stateOf(draft.versions);
+    draft.versions.forEach((version, i) => {
+        version.edits = mapped(versions[i].edits, recarrying);
+    });
+};
+/**
+ * Replaces the features of the copy with a single one covering them
+ * all, where a scan has split what the editor reads as one feature.
+ * The merged feature takes the place of the first it replaces and
+ * spans from the first to the last, any gap between them included.
+ * What the replaced features carried is carried by the merged one, and
+ * whatever else named them, a modification or a comprehension, names
+ * the merged one in their stead.
+ *
+ * Throws where the features cannot stand for one; `mergeObstacle`
+ * says beforehand whether they can.
+ */
+export const mergeFeatures = (copyId, featureIds) => onCopy(copyId, (copy, draft) => {
+    const replaced = new Set(featureIds);
+    const isReplaced = (feature) => replaced.has(feature.id);
+    const features = stateOf(copy.features);
+    const toMerge = features.filter(isReplaced);
+    const obstacle = mergeObstacle(toMerge);
+    if (obstacle) {
+        throw new Error(`The features of copy ${copyId} cannot be merged: ${obstacle}`);
+    }
+    const merged = mergedFrom(toMerge);
+    copy.features = standingFor(features, isReplaced, merged);
+    carryOver(draft, replaced, merged.id);
+    renameReferences(draft, ids => standingFor(ids, id => replaced.has(id), merged.id));
+});
 /** The carriers of each collated symbol pass to its counterpart. */
 const handOverCarriers = (view, draft, collations) => collations.forEach(({ symbol, counterpart }) => {
     const path = view.getPath(counterpart.id);
@@ -183,7 +420,8 @@ const handOverCarriers = (view, draft, collations) => collations.forEach(({ symb
  * 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
  * rest become the child's insertions, and what the parent hands down
- * and the child lacks becomes its deletions.
+ * and the child lacks becomes its deletions. The derivation states the
+ * tolerance it was collated at.
  */
 export const connectVersions = (view, childId, parentId, tolerance = defaultCollationTolerance) => {
     const inherited = view.snapshot(parentId);
@@ -198,20 +436,21 @@ export const connectVersions = (view, childId, parentId, tolerance = defaultColl
     return onVersion(childId, (child, draft) => {
         handOverCarriers(view, draft, collations);
         child.edits = edits;
-        child.basedOn = assignReference(parentId);
+        child.basedOn = { ...assignReference(parentId), collationTolerance: tolerance };
     });
 };
 /**
  * Folds the version's own symbols into those it inherits and collates
- * with: the carriers pass over, and the insertions go.
+ * with: the carriers pass over, and the insertions go. Collates at the
+ * tolerance of the derivation, where the caller names none.
  */
-export const collateSymbols = (view, versionId, symbolIds, tolerance = defaultCollationTolerance) => {
+export const collateSymbols = (view, versionId, symbolIds, tolerance) => {
     const version = view.get(versionId);
     if (!version?.basedOn)
         return noChange;
     const chosen = new Set(symbolIds);
     const own = insertedIn([version]).filter(symbol => chosen.has(symbol.id));
-    const collations = collationsOf(own, view.snapshot(idOf(version.basedOn)), symbol => view.dimensionOf(symbol), tolerance);
+    const collations = collationsOf(own, view.snapshot(idOf(version.basedOn)), symbol => view.dimensionOf(symbol), tolerance ?? collationToleranceOf(version.basedOn));
     const collated = new Set(collations.map(({ symbol }) => symbol.id));
     return onVersion(versionId, (version, draft) => {
         handOverCarriers(view, draft, collations);

package/lib/index.d.ts

@@ -27,5 +27,6 @@ export * from './constraints';
 export * from './context';
 export * from './asJsonLd';
 export * from './importJsonLd';
+export * from './migrate';
 export { readFromStanfordAton, type StanfordAtonOptions } from './readers/stanfordAton';
 export { readFromSpencerBar, readSpencerAnn, paperSpeedOfSpencerAnn, SPENCER_ROWS_PER_INCH, type SpencerBarOptions } from './readers/spencerBar';

package/lib/index.js

@@ -27,5 +27,6 @@ export * from './constraints';
 export * from './context';
 export * from './asJsonLd';
 export * from './importJsonLd';
+export * from './migrate';
 export { readFromStanfordAton } from './readers/stanfordAton';
 export { readFromSpencerBar, readSpencerAnn, paperSpeedOfSpencerAnn, SPENCER_ROWS_PER_INCH } from './readers/spencerBar';

package/lib/migrate.js

@@ -107,4 +107,24 @@ const withRollSystem = (edition) => {
 const withEditors = (edition) => !edition.creation || edition.creation.editors
     ? edition
     : { ...edition, creation: { ...edition.creation, editors: [] } };
-export const migrate = (edition) => walk(withRollSystem(withEditors(edition)));
+const statesNoTolerance = (version) => version.basedOn && !version.basedOn.collationTolerance;
+/**
+ * The collation tolerance was the edition's before it was stated on
+ * each derivation. An edition written then collated every version at
+ * that one value, so it is written onto every derivation that gives
+ * none of its own.
+ */
+const withDerivationTolerance = (edition) => {
+    const collationTolerance = edition.creation?.collationTolerance;
+    const versions = Array.isArray(edition.versions) ? edition.versions : [];
+    if (!collationTolerance || !versions.some(statesNoTolerance))
+        return edition;
+    return {
+        ...edition,
+        versions: versions.map(version => statesNoTolerance(version)
+            ? { ...version, basedOn: { ...version.basedOn, collationTolerance } }
+            : version)
+    };
+};
+const editionSteps = [withRollSystem, withEditors, withDerivationTolerance];
+export const migrate = (edition) => walk(editionSteps.reduce((result, step) => step(result), edition));

package/lib/readers/stanfordAton.js

@@ -2,7 +2,7 @@ import { v4 } from "uuid";
 import { AtonParser } from "./AtonParser";
 import { systemOf, translationBetween } from "../TrackerBar";
 import { welteT100 } from "../systems/welteT100/bar";
-import { inMillimeters, mean, mm, px, subtract, track } from "../Quantity";
+import { inMillimeters, mean, mm, pixelsPerInch, px, subtract, track } from "../Quantity";
 /** Values in these files carry their unit as a suffix, e.g. "37.7646px". */
 const readPx = (value) => px(parseFloat(value));
 /** The parser writes one record as an object and several as an array. */
@@ -155,6 +155,9 @@ export function readFromStanfordAton(atonString, { trackShift, bar = welteT100,
                 bass: readPx(json.ROLLINFO.HARD_MARGIN_BASS),
                 unit: 'px'
             },
+            ...(Number.isFinite(dpi) && {
+                scanResolution: { value: pixelsPerInch(dpi), unit: 'px/in' }
+            }),
             trackCalibration: calibration,
             ...(measuredBy && { measuredBy })
         },

package/lib/schema.json

@@ -277,6 +277,41 @@
             ],
             "type": "object"
         },
+        "Derivation": {
+            "description": "A derivation names the version another one was derived from, together with the tolerance the two were collated at. How precisely the copies put a symbol depends on what they are and on how their features were obtained, so the tolerance can differ from derivation to derivation. [ontology: lrmoo:R76 is derivative of]",
+            "properties": {
+                "@annotation": {
+                    "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                    "properties": {
+                        "belief": {
+                            "$ref": "#/definitions/Belief",
+                            "description": "The belief held about the annotated statement. [ontology: crminf:J4i is subject of]"
+                        },
+                        "@id": {
+                            "description": "A unique identifier for this object.",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "belief",
+                        "@id"
+                    ],
+                    "type": "object"
+                },
+                "collationTolerance": {
+                    "$ref": "#/definitions/CollationTolerance",
+                    "description": "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."
+                },
+                "@id": {
+                    "description": "A unique identifier for this object.",
+                    "type": "string"
+                }
+            },
+            "required": [
+                "@id"
+            ],
+            "type": "object"
+        },
         "Edit": {
             "description": "A set of edits transforms a version of a roll into another version. Edits insert or delete symbols, or both (= replace). Edits may be motivated by a given set of reasons, e.g. to add an additional accent or to correct an error. If an edit is the interpretation of a metamark, such as a pencil mark, this should be made explicit using a meaning comprehension on the `@annotation` field. [ontology: reo:Edit]",
             "properties": {
@@ -882,6 +917,25 @@
             ],
             "type": "object"
         },
+        "Measure<\"px/in\">": {
+            "description": "A value together with the unit it was measured in, as a record states it. [ontology: crm:E54 Dimension]",
+            "properties": {
+                "unit": {
+                    "const": "px/in",
+                    "description": "The unit of measurement. [ontology: crm:P91 has unit]",
+                    "type": "string"
+                },
+                "value": {
+                    "$ref": "#/definitions/Quantity%3C%22px%2Fin%22%3E",
+                    "description": "The measured value. [ontology: crm:P90 has value]"
+                }
+            },
+            "required": [
+                "value",
+                "unit"
+            ],
+            "type": "object"
+        },
         "Millimeters": {
             "$ref": "#/definitions/Quantity%3C%22mm%22%3E",
             "description": "A place along the roll, or any length on the paper."
@@ -1227,6 +1281,49 @@
             ],
             "type": "object"
         },
+        "ObjectAssumption<ConditionState<(\"illegible\")>>": {
+            "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain.",
+            "properties": {
+                "@annotation": {
+                    "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                    "properties": {
+                        "belief": {
+                            "$ref": "#/definitions/Belief",
+                            "description": "The belief held about the annotated statement. [ontology: crminf:J4i is subject of]"
+                        },
+                        "@id": {
+                            "description": "A unique identifier for this object.",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "belief",
+                        "@id"
+                    ],
+                    "type": "object"
+                },
+                "conditionType": {
+                    "const": "illegible",
+                    "description": "The kind of condition, from the list the roll or the kind of feature allows. [ontology: crm:P2 has type]",
+                    "type": "string"
+                },
+                "description": {
+                    "description": "A free-text description of the condition, providing details beyond the type classification. [ontology: crm:P3 has note]",
+                    "type": "string"
+                },
+                "@type": {
+                    "const": "ConditionState",
+                    "description": "The type discriminator for this object. [ontology: rdf:type]",
+                    "type": "string",
+                    "ontology": "rdf:type"
+                }
+            },
+            "required": [
+                "conditionType",
+                "@type"
+            ],
+            "type": "object"
+        },
         "ObjectAssumption<ConditionState<(\"partially-torn\"|\"missing-perforation\")>>": {
             "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain.",
             "properties": {
@@ -1610,6 +1707,9 @@
         "Quantity<\"px\">": {
             "type": "number"
         },
+        "Quantity<\"px/in\">": {
+            "type": "number"
+        },
         "Quantity<\"track\">": {
             "type": "number"
         },
@@ -1817,6 +1917,10 @@
                             "description": "The factor this copy's features were scaled by to align them with the others. What it is put down to is stated apart: a paper-stretch condition, or the speed the copy was cut for. Not exported to RDF.",
                             "type": "number"
                         },
+                        "scanResolution": {
+                            "$ref": "#/definitions/Measure%3C%22px%2Fin%22%3E",
+                            "description": "The resolution this copy's scan was read at, along the roll. It is what the measurements given in pixels are to be read against, and what every conversion between a place in the scan and one on the paper goes through. A scanner may read across the roll at another resolution, which the analysis files do not state. [ontology: reo:scanResolution]"
+                        },
                         "shift": {
                             "$ref": "#/definitions/Shift",
                             "description": "The shift applied to align this copy with the others. Not exported to RDF."
@@ -1978,7 +2082,7 @@
             "description": "A version is defined by the sum of edits applied to the version it is based on. For simple identification, a siglum is given to each version. [ontology: lrmoo:F2 Expression]",
             "properties": {
                 "basedOn": {
-                    "$ref": "#/definitions/ReferenceAssumption",
+                    "$ref": "#/definitions/Derivation",
                     "description": "If no derivation is defined, it is assumed that this version represents the mother roll. [ontology: lrmoo:R76 is derivative of]"
                 },
                 "edits": {
@@ -2059,7 +2163,7 @@
             "description": "A piece of writing found on the roll, such as a label, catalogue number, or annotation. Writings have a method of production and a transcription of their content. [ontology: crm:E25 Human-Made Feature]",
             "properties": {
                 "condition": {
-                    "$ref": "#/definitions/ObjectAssumption%3CConditionState%3C(%22faded%22)%3E%3E",
+                    "$ref": "#/definitions/ObjectAssumption%3CConditionState%3C(%22illegible%22)%3E%3E",
                     "description": "This can be used e.g. to indicate a perforation which is torn out or in any other way damaged. [ontology: crm:P44 has condition]"
                 },
                 "depiction": {

package/lib/spec/context.json

@@ -131,6 +131,7 @@
                 "height": "reo:height",
                 "punchDiameter": "reo:punchDiameter",
                 "holeSeparation": "reo:holeSeparation",
+                "scanResolution": "reo:scanResolution",
                 "value": "crm:P90_has_value",
                 "measuredBy": "crmdig:L23_used_software_or_firmware",
                 "software": "rdfs:label",

package/lib/validate.d.ts

@@ -1,3 +1,12 @@
+import { type ErrorObject } from "ajv";
 import { Edition } from "./Edition";
-declare const validate: import("ajv").ValidateFunction<Edition>;
+/**
+ * Holds a document against the edition schema. `errors` says what the
+ * last call found wrong, and is empty where it found nothing.
+ */
+export interface ValidateEdition {
+    (document: unknown): document is Edition;
+    errors?: ErrorObject[] | null;
+}
+declare const validate: ValidateEdition;
 export { validate };

package/lib/validate.js

@@ -1,10 +1,15 @@
 import Ajv from "ajv";
 import * as schema from "./schema.json";
-const ajv = new Ajv({
-    strict: false,
-    formats: {
-        "date": true
-    }
-});
-const validate = ajv.compile(schema);
+const compileEditionSchema = () => new Ajv({ strict: false, formats: { "date": true } }).compile(schema);
+/**
+ * Compiling costs enough that a consumer which never validates should not
+ * pay for it, so the compiled form is made on first use and kept.
+ */
+let compiled;
+const validate = (document) => {
+    compiled ?? (compiled = compileEditionSchema());
+    const valid = compiled(document);
+    validate.errors = compiled.errors;
+    return valid;
+};
 export { validate };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.14.0",
+  "version": "0.16.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {
@@ -8,6 +8,7 @@
     "url": "git+https://github.com/pfefferniels/linked-rolls.git"
   },
   "type": "module",
+  "sideEffects": false,
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "exports": {