linked-rolls 0.46.0 → 0.48.0

package/README.md

@@ -143,17 +143,50 @@ and the onset alone 39, so neither test is idle, but a difference at the
 end is as often a punch measured badly as a punch genuinely prolonged,
 and the two are not worth confusing.
 
+## What a reader adds to a hole
+
+A copy read pneumatically rather than scanned reports how long a valve
+stayed open, and a valve is held on past the perforation that opened it,
+so its holes run longer than the punched slots while their onsets agree.
+Left in, that is not a difference between copies: a collation comparing
+such a copy's hole ends against a scanned copy's compares an on-time
+with a slot, and reads the one as a lengthening of the other.
+
+`shortenHoles` takes the extension off and records it on the copy,
+`revertShortening` puts it back, and `readFromPhillipsEroll` will take
+it off at import. Only holes are touched, what a writing spans being no
+valve. The figure is measured against the other copies rather than
+derived from the bar, since Phillips gives only the difference between
+two bars and not the absolute.
+
+On welte225.org that figure is about 1.6 mm, and its shape is simple. It
+does not grow with the length of the perforation: the ratio of the read
+length to the true one falls from 1.34 on the shortest punches to 1.01
+on the longest, which is what a constant added to everything does. There
+is no shortest on-time the valve cannot fall below. It shows no run
+along the roll, though one roll's span of paper speed is too narrow to
+tell a constant in millimetres from a constant in time. What it does
+vary with is the port that read it, by about half a millimetre either
+way and with no gradient across the bar, which is measured but too
+coarse to model from a single roll.
+
 ## Collating a derivation a second time
 
 A collated symbol is one symbol carrying every copy that reads it, so a
 collation cannot simply be run again: there is no second symbol left to
-match. `separateReadings` is the inverse. It takes one copy's carriers
-back off the symbols it shares, gives them to new symbols of the
+match. `separateReadings` is the inverse. It takes the carriers of one
+side back off the symbols it shares, gives them to new symbols of the
 version's own, and states the exchange, leaving the edition in the state
 a collation would have produced had nothing joined. `connectVersions` at
 a new tolerance then re-collates, joining again whatever the new window
 admits.
 
+It takes a side and not a copy, the same side `sidesOf` names and a
+window is measured over. Naming one copy of a side that has several does
+not separate that side: the rest of it stays behind on the other side's
+symbol, and a collation then compares one copy against that mixture
+rather than the two texts against each other.
+
 Nothing an editor established is lost by that. `connectVersions`
 rewrites only what a collation wrote (`isCollationsOwn`): a bare
 insertion or deletion, or an equivalence between two systems' spellings.

package/lib/Collation.d.ts

@@ -85,6 +85,27 @@ export type Collation = {
 };
 /** Each of the own symbols with every inherited symbol it collates with, both in the order given. */
 export declare const collationsOf: (own: readonly Readonly<AnySymbol>[], inherited: readonly Readonly<AnySymbol>[], locate: Locate, tolerance?: CollationTolerance) => Collation[];
+/**
+ * The motivation a collation writes on what it makes, saying that
+ * nobody has read it yet.
+ *
+ * A collation produces its edits by a rule, and an edition that
+ * publishes them unmarked would present a machine's output as an
+ * editor's reading. Stating that they are unchecked is the honest
+ * middle: the readings are there to be seen and argued with, and a
+ * reader can tell which of them anybody has weighed.
+ *
+ * It does not make an edit the editor's. `isCollationsOwn` passes over
+ * this motivation exactly, so a collation rewrites what it marked
+ * before, and only what somebody has actually written stays.
+ */
+export declare const unchecked = "unchecked";
+/** The version's statement of what the unchecked motivation means, to stand in its `motivations`. */
+export declare const uncheckedMotivation: {
+    readonly type: 'motivation';
+    readonly id: "unchecked";
+    readonly note: 'Made by collating the two texts and not yet read by an editor.';
+};
 /**
  * Whether the edit is one a collation writes by itself: a bare
  * insertion or a bare deletion saying nothing further, or an

package/lib/Collation.js

@@ -89,6 +89,27 @@ export const collationsOf = (own, inherited, locate, tolerance = defaultCollatio
 };
 /** The edit type a collation draws by itself, from the two systems' vocabularies rather than off the paper. */
 const drawnByCollation = 'replace-with-equivalent';
+/**
+ * The motivation a collation writes on what it makes, saying that
+ * nobody has read it yet.
+ *
+ * A collation produces its edits by a rule, and an edition that
+ * publishes them unmarked would present a machine's output as an
+ * editor's reading. Stating that they are unchecked is the honest
+ * middle: the readings are there to be seen and argued with, and a
+ * reader can tell which of them anybody has weighed.
+ *
+ * It does not make an edit the editor's. `isCollationsOwn` passes over
+ * this motivation exactly, so a collation rewrites what it marked
+ * before, and only what somebody has actually written stays.
+ */
+export const unchecked = 'unchecked';
+/** The version's statement of what the unchecked motivation means, to stand in its `motivations`. */
+export const uncheckedMotivation = {
+    type: 'motivation',
+    id: unchecked,
+    note: 'Made by collating the two texts and not yet read by an editor.'
+};
 /**
  * Whether the edit is one a collation writes by itself: a bare
  * insertion or a bare deletion saying nothing further, or an
@@ -107,4 +128,6 @@ const drawnByCollation = 'replace-with-equivalent';
  * draws a second time over the very same symbols.
  */
 export const isCollationsOwn = (edit) => edit.editType === drawnByCollation
-    || (edit.editType === undefined && edit.motivation === undefined && edit['@annotation'] === undefined);
+    || (edit.editType === undefined
+        && (edit.motivation === undefined || edit.motivation === unchecked)
+        && edit['@annotation'] === undefined);

package/lib/RollCopy.d.ts

@@ -201,7 +201,7 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      * (e.g. 'shifted', 'stretched') to normalize measurements
      * for comparison with other copies. Not exported to RDF.
      */
-    ops: Array<'shifted' | 'stretched'>;
+    ops: Array<'shifted' | 'stretched' | 'shortened'>;
     /**
      * Physical measurements of this roll copy, including
      * dimensions, punch diameter, hole separation, margins,
@@ -258,6 +258,17 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
          * Not exported to RDF.
          */
         scale: number;
+        /**
+         * How much longer this copy's reading of a hole ran than the
+         * perforation that caused it, where that was taken off the ends
+         * again. A pneumatic reader reports how long a valve stayed
+         * open, which exceeds the perforation that opened it, so its
+         * holes are overlong by a constant while its onsets agree.
+         * Nothing for a copy read by other means, whose holes are the
+         * punched slots themselves.
+         * Not exported to RDF.
+         */
+        readerExtension: Millimeters;
         /**
          * The resolution this copy's scan was read at, along the roll.
          * It is what the measurements given in pixels are to be read

package/lib/alignment.d.ts

@@ -9,6 +9,45 @@ export declare const applyScale: (factor: number, copy: RollCopy) => void;
 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;
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's holes, and records how much was taken.
+ *
+ * Such a reader reports how long a valve stayed open, and a valve is
+ * held on past the perforation that opened it, so its holes run longer
+ * than the punched slots while their onsets agree. Left in, the
+ * difference is not a difference between copies at all: a collation
+ * comparing this copy's hole ends against a scanned copy's compares a
+ * pneumatic on-time with a punched slot, and reads the one as a
+ * lengthening of the other.
+ *
+ * The extension is a property of the reader rather than of the roll,
+ * and on the material measured so far it is a constant: it does not
+ * grow with the length of the perforation, there is no shortest
+ * on-time the valve cannot fall below, and it does not run along the
+ * roll with the paper speed as far as one roll can show. What it does
+ * vary with is the port that read it, by about half a millimetre either
+ * way and without any gradient across the bar, which is measured but
+ * too coarse to model from one roll.
+ *
+ * Only holes are touched. What a writing or a mark spans is no valve.
+ */
+/**
+ * The holes the extension cannot be taken off, being no longer than it
+ * is: the reader reported them open for less time than it holds a valve
+ * on beyond the perforation, so the constant over-corrects them and
+ * would leave them ending before they begin.
+ *
+ * They are where the constant shows its limit rather than where the
+ * copy is wrong, the extension varying by about half a millimetre with
+ * the port. What to do with them is an editorial question — a condition
+ * on the feature, a reading of the hole, a smaller extension — and
+ * `shortenHoles` throws rather than answer it.
+ */
+export declare const tooShortToShorten: (extension: Millimeters, copy: RollCopy) => Readonly<FeatureOrPatch>[];
+export declare const shortenHoles: (extension: Millimeters, copy: RollCopy) => void;
+/** Puts the reader's extension back on the copy's holes, as far as one was taken off. */
+export declare const revertShortening: (copy: RollCopy) => void;
 /**
  * How a copy's places are carried onto another copy's:
  * `x_other = (x + shift) · scale`.

package/lib/alignment.js

@@ -1,6 +1,6 @@
 import { featuresOf } from "./RollCopy.js";
 import { welteT100 } from "./systems/welteT100/bar.js";
-import { add, mm, scale } from "./Quantity.js";
+import { add, mm, scale, subtract } from "./Quantity.js";
 /** Moves both ends of a span, the far end only where the span has one. */
 const move = (span, by) => {
     span.from = add(span.from, by);
@@ -54,6 +54,65 @@ export const revertScale = (copy) => {
     copy.ops = copy.ops.filter(op => op !== 'stretched');
     delete copy.measurements.scale;
 };
+const holesOf = (copy) => featuresOf(copy).filter(feature => feature.type === 'Hole');
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's holes, and records how much was taken.
+ *
+ * Such a reader reports how long a valve stayed open, and a valve is
+ * held on past the perforation that opened it, so its holes run longer
+ * than the punched slots while their onsets agree. Left in, the
+ * difference is not a difference between copies at all: a collation
+ * comparing this copy's hole ends against a scanned copy's compares a
+ * pneumatic on-time with a punched slot, and reads the one as a
+ * lengthening of the other.
+ *
+ * The extension is a property of the reader rather than of the roll,
+ * and on the material measured so far it is a constant: it does not
+ * grow with the length of the perforation, there is no shortest
+ * on-time the valve cannot fall below, and it does not run along the
+ * roll with the paper speed as far as one roll can show. What it does
+ * vary with is the port that read it, by about half a millimetre either
+ * way and without any gradient across the bar, which is measured but
+ * too coarse to model from one roll.
+ *
+ * Only holes are touched. What a writing or a mark spans is no valve.
+ */
+/**
+ * The holes the extension cannot be taken off, being no longer than it
+ * is: the reader reported them open for less time than it holds a valve
+ * on beyond the perforation, so the constant over-corrects them and
+ * would leave them ending before they begin.
+ *
+ * They are where the constant shows its limit rather than where the
+ * copy is wrong, the extension varying by about half a millimetre with
+ * the port. What to do with them is an editorial question — a condition
+ * on the feature, a reading of the hole, a smaller extension — and
+ * `shortenHoles` throws rather than answer it.
+ */
+export const tooShortToShorten = (extension, copy) => holesOf(copy).filter(hole => hole.horizontal.to - hole.horizontal.from <= extension);
+export const shortenHoles = (extension, copy) => {
+    if (copy.ops.includes('shortened'))
+        return;
+    const tooShort = tooShortToShorten(extension, copy);
+    if (tooShort.length > 0) {
+        throw new Error(`The extension of ${extension} mm cannot be taken off ${tooShort.length} `
+            + `hole(s) of copy ${copy.id}, which are no longer than it: `
+            + `${tooShort.map(hole => hole.id).join(', ')}`);
+    }
+    holesOf(copy).forEach(hole => { hole.horizontal.to = subtract(hole.horizontal.to, extension); });
+    copy.ops = [...copy.ops, 'shortened'];
+    copy.measurements.readerExtension = extension;
+};
+/** Puts the reader's extension back on the copy's holes, as far as one was taken off. */
+export const revertShortening = (copy) => {
+    const extension = copy.measurements.readerExtension;
+    if (!copy.ops.includes('shortened') || extension === undefined)
+        return;
+    holesOf(copy).forEach(hole => { hole.horizontal.to = add(hole.horizontal.to, extension); });
+    copy.ops = copy.ops.filter(op => op !== 'shortened');
+    delete copy.measurements.readerExtension;
+};
 const byPlace = (x, y) => x.at - y.at || x.pitch - y.pitch;
 /** The notes the bar reads off the features, in the order they pass it. */
 const noteOnsets = (features, bar) => features

package/lib/editionOps.d.ts

@@ -8,6 +8,7 @@ import { GeneralRollCondition, ModificationPurpose, RollCopy, ScaleReading, Shif
 import { FeatureSource } from "./FeatureSource.js";
 import { AnyArgumentation, Belief, Certainty, ObjectAssumption } from "./Assumption.js";
 import { FeatureConditionAssignment, FeatureOrPatch, NestedFeature } from "./Feature.js";
+import { Millimeters } from "./Quantity.js";
 /**
  * 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
@@ -40,6 +41,14 @@ export declare const alignCopy: (copyId: string, shift: Shift, scale: number, re
  * being a fact about the copy.
  */
 export declare const unalignCopy: (copyId: string) => EditionOp;
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's holes, and records how much was taken, so that its lengths
+ * can be compared with a scanned copy's at all.
+ */
+export declare const shortenCopy: (copyId: string, extension: Millimeters) => EditionOp;
+/** Puts the reader's extension back on the copy's holes. */
+export declare const unshortenCopy: (copyId: string) => EditionOp;
 /** States what the copy's features were read from, in place of any earlier statement. */
 export declare const stateSource: (copyId: string, source: FeatureSource) => EditionOp;
 /** Takes back the statement, leaving the copy silent about its source again. */
@@ -180,9 +189,9 @@ export declare const connectVersions: (view: EditionView, childId: string, paren
  */
 export declare const collateSymbols: (view: EditionView, versionId: string, symbolIds: readonly string[], tolerance?: CollationTolerance) => EditionOp;
 /**
- * Takes the copy's reading of a symbol back out of the symbol it was
- * collated into: the copy's carriers pass to a new symbol of the
- * version's own, the other copies keep the symbol they had, and the
+ * Takes the named copies' reading of a symbol back out of the symbol it
+ * was collated into: their carriers pass to a new symbol of the
+ * version's own, the remaining copies keep the symbol they had, and the
  * version states the exchange.
  *
  * This is the inverse of the hand-over a collation makes, and it is
@@ -191,12 +200,19 @@ export declare const collateSymbols: (view: EditionView, versionId: string, symb
  * takes the two readings apart again, and without that a tolerance
  * arrived at after the fact could never be applied.
  *
- * Symbols the copy alone carries are already the version's own and are
- * passed over, so a reading somebody has separated by hand keeps its
- * identifier and the edit that speaks for it. Named symbols narrow the
- * act to those; naming none separates the copy's whole reading.
+ * The copies named are one **side** of the derivation, the same side a
+ * window is measured over, and `sidesOf` is what says which they are.
+ * Naming one copy of a side that has several does not separate that
+ * side: what stays behind is the rest of it, mixed with the other
+ * side's copies, and a collation then compares one copy against that
+ * mixture rather than the two texts against each other.
+ *
+ * Symbols the named copies alone carry are already the version's own
+ * and are passed over, so a reading somebody has separated by hand
+ * keeps its identifier and the edit that speaks for it. Named symbols
+ * narrow the act to those; naming none separates the whole reading.
  */
-export declare const separateReadings: (view: EditionView, versionId: string, copyId: string, symbolIds?: readonly string[]) => EditionOp;
+export declare const separateReadings: (view: EditionView, versionId: string, copies: ReadonlySet<string>, symbolIds?: readonly string[]) => EditionOp;
 /**
  * Makes the version stand on its own: what it inherited becomes its
  * own insertions, and its derivations go, the hypotheses among them,

package/lib/editionOps.js

@@ -2,13 +2,13 @@ import { current, isDraft } from "immer";
 import { v4 } from "uuid";
 import { getAt } from "./EditionView.js";
 import { isCommand, placementRelations } from "./Symbol.js";
-import { collationsOf, defaultCollationTolerance, isCollationsOwn } from "./Collation.js";
+import { collationsOf, defaultCollationTolerance, isCollationsOwn, unchecked, uncheckedMotivation } from "./Collation.js";
 import { collationToleranceOf, editsOf, insertedBy, principalDerivationOf } from "./Version.js";
 import { asSymbols, barOf, featuresByAct, featuresOf, isPaperStretch, statesNothing } from "./RollCopy.js";
 import { systemOf } from "./TrackerBar.js";
 import { substitutionsBetween } from "./substitution.js";
 import { trackerBarOf } from "./systems/index.js";
-import { applyShift, applyScale, revertShift, revertScale } from "./alignment.js";
+import { applyShift, applyScale, revertShift, revertScale, revertShortening, shortenHoles } from "./alignment.js";
 import { assignReference, idOf } from "./Assumption.js";
 import { conditions as conditionsAllowed, featuresBorneBy, isGluedOn, withBorneFeatures } from "./Feature.js";
 import { distance, mm, subtract } from "./Quantity.js";
@@ -54,6 +54,17 @@ const droppedIds = (before, after) => {
 };
 const insertion = (symbol) => ({ type: 'edit', id: v4(), insert: [symbol] });
 const deletion = (symbolId) => ({ type: 'edit', id: v4(), delete: [symbolId] });
+/** The edit as a collation leaves it: made by rule, and not yet read by anybody. */
+const asUnchecked = (edit) => ({ ...edit, motivation: unchecked });
+/**
+ * The motivations with the unchecked one declared, where any edit
+ * names it and the version does not state it yet. An edit naming a
+ * motivation the version leaves undeclared points at nothing.
+ */
+const declaring = (motivations, edits) => edits.some(edit => edit.motivation === unchecked)
+    && !motivations.some(motivation => motivation.id === unchecked)
+    ? [...motivations, uncheckedMotivation]
+    : motivations;
 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. */
@@ -125,6 +136,14 @@ export const unalignCopy = (copyId) => onCopy(copyId, copy => {
     revertShift(copy);
     copy.conditions = without(copy.conditions, isPaperStretch);
 });
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's holes, and records how much was taken, so that its lengths
+ * can be compared with a scanned copy's at all.
+ */
+export const shortenCopy = (copyId, extension) => onCopy(copyId, copy => shortenHoles(extension, copy));
+/** Puts the reader's extension back on the copy's holes. */
+export const unshortenCopy = (copyId) => onCopy(copyId, copy => revertShortening(copy));
 /** States what the copy's features were read from, in place of any earlier statement. */
 export const stateSource = (copyId, source) => onCopy(copyId, copy => {
     copy.readFrom = source;
@@ -725,6 +744,7 @@ export const connectVersions = (view, childId, parentId, tolerance = defaultColl
             type: 'edit',
             id: v4(),
             editType: 'replace-with-equivalent',
+            motivation: unchecked,
             insert: [...by],
             delete: deleted
         };
@@ -732,14 +752,15 @@ export const connectVersions = (view, childId, parentId, tolerance = defaultColl
     const edits = [
         ...established,
         ...substituted.map(equivalence),
-        ...own.filter(symbol => !collated.has(symbol.id) && !paired.has(symbol.id)).map(insertion),
+        ...own.filter(symbol => !collated.has(symbol.id) && !paired.has(symbol.id)).map(insertion).map(asUnchecked),
         ...inherited
             .filter(symbol => !matched.has(symbol.id) && !paired.has(symbol.id))
-            .map(symbol => deletion(symbol.id))
+            .map(symbol => asUnchecked(deletion(symbol.id)))
     ];
     return onVersion(childId, (child, draft) => {
         handOverCarriers(view, draft, collations);
         child.edits = edits;
+        child.motivations = declaring(stateOf(child).motivations, edits);
         child.basedOn = [
             { ...assignReference(parentId), collationTolerance: tolerance },
             ...hypothesesBeside(stateOf(child), parentId)
@@ -778,16 +799,29 @@ const readingOf = (symbol, carriers) => {
     }
 };
 /** The symbol where the copy and at least one other carry it, with the carriers of each side. */
-const sharedWith = (view, symbol, copyId) => {
-    const onCopy = (carrier) => view.copyOf(idOf(carrier))?.id === copyId;
-    const mine = symbol.carriers.filter(onCopy);
-    const theirs = symbol.carriers.filter(carrier => !onCopy(carrier));
+/**
+ * The symbol where the named copies and at least one other carry it,
+ * with the carriers of each side.
+ *
+ * A symbol the named copies alone carry has no other side to be
+ * separated from and is passed over. That covers the insertions, and it
+ * covers a symbol an ancestor holds on one branch's witness alone,
+ * where the two versions do not disagree and there is nothing to take
+ * apart.
+ */
+const sharedWith = (view, symbol, copies) => {
+    const onNamedCopy = (carrier) => {
+        const copy = view.copyOf(idOf(carrier));
+        return copy !== undefined && copies.has(copy.id);
+    };
+    const mine = symbol.carriers.filter(onNamedCopy);
+    const theirs = symbol.carriers.filter(carrier => !onNamedCopy(carrier));
     return mine.length > 0 && theirs.length > 0 ? [{ symbol, mine, theirs }] : [];
 };
 /**
- * Takes the copy's reading of a symbol back out of the symbol it was
- * collated into: the copy's carriers pass to a new symbol of the
- * version's own, the other copies keep the symbol they had, and the
+ * Takes the named copies' reading of a symbol back out of the symbol it
+ * was collated into: their carriers pass to a new symbol of the
+ * version's own, the remaining copies keep the symbol they had, and the
  * version states the exchange.
  *
  * This is the inverse of the hand-over a collation makes, and it is
@@ -796,19 +830,26 @@ const sharedWith = (view, symbol, copyId) => {
  * takes the two readings apart again, and without that a tolerance
  * arrived at after the fact could never be applied.
  *
- * Symbols the copy alone carries are already the version's own and are
- * passed over, so a reading somebody has separated by hand keeps its
- * identifier and the edit that speaks for it. Named symbols narrow the
- * act to those; naming none separates the copy's whole reading.
+ * The copies named are one **side** of the derivation, the same side a
+ * window is measured over, and `sidesOf` is what says which they are.
+ * Naming one copy of a side that has several does not separate that
+ * side: what stays behind is the rest of it, mixed with the other
+ * side's copies, and a collation then compares one copy against that
+ * mixture rather than the two texts against each other.
+ *
+ * Symbols the named copies alone carry are already the version's own
+ * and are passed over, so a reading somebody has separated by hand
+ * keeps its identifier and the edit that speaks for it. Named symbols
+ * narrow the act to those; naming none separates the whole reading.
  */
-export const separateReadings = (view, versionId, copyId, symbolIds) => {
+export const separateReadings = (view, versionId, copies, symbolIds) => {
     const version = view.get(versionId);
     if (!version)
         return noChange;
     const chosen = symbolIds && new Set(symbolIds);
     const shared = view.snapshot(versionId)
         .filter(symbol => chosen === undefined || chosen.has(symbol.id))
-        .flatMap(symbol => sharedWith(view, symbol, copyId));
+        .flatMap(symbol => sharedWith(view, symbol, copies));
     if (shared.length === 0)
         return noChange;
     const inserted = new Set(insertedBy(version).map(symbol => symbol.id));

package/lib/readers/phillipsEroll.d.ts

@@ -20,16 +20,21 @@ import { Millimeters, Seconds } from "../Quantity.js";
  * perforation, the height of the tracker bar hole and the paper speed
  * (p. 180).
  *
- * That extension is not subtracted. Doing so would need the absolute
- * hole height of the Welte bar, where he gives only the 0.5 mm by which
- * it exceeds the Licensee's. So the end of a hole on this copy is a
- * pneumatic on-time where the end of a scanned copy's hole is a punched
- * slot, and the two are not the same quantity. It shows in a collation:
- * across welte225.org his notes run about 1.8 mm longer than the other
- * copies read them, while the onsets agree. Until it is corrected, a
- * comparison of hole ends against this copy measures the reader as much
- * as the roll, and `offsetEnd` on the derivation absorbs the systematic
- * part of it.
+ * Left in, that extension is not a difference between copies at all:
+ * the end of a hole here is a pneumatic on-time where the end of a
+ * scanned copy's hole is a punched slot, so a collation comparing the
+ * two reads the one as a lengthening of the other. `extension` takes it
+ * off at the end of every hole, and the copy records what was taken.
+ *
+ * How much to take off is measured rather than derived, since he gives
+ * only the 0.5 mm by which the Welte bar's holes exceed the Licensee's
+ * and not the absolute. Across welte225.org it comes to about 1.6 mm,
+ * and the shape of it is simple: a constant, not growing with the
+ * length of the perforation, with no shortest on-time the valve cannot
+ * fall below, and with no run along the roll that one roll's span of
+ * paper speed could show. The port that read it matters by about half a
+ * millimetre either way, without any gradient across the bar, which is
+ * measured but too coarse to model from one roll.
  */
 /**
  * He numbers his files by two rules at once, which his free samples
@@ -64,12 +69,25 @@ export interface PhillipsErollOptions {
      * account for it.
      */
     placeAt?: (elapsed: Seconds) => Millimeters;
+    /**
+     * How much longer a valve is held on than the perforation that
+     * opened it, taken off the end of every hole so that these lengths
+     * can be compared with a scanned copy's. Nothing leaves the holes
+     * as the reader reported them, which is what every copy read before
+     * this option existed states.
+     *
+     * The copy records what was taken, and `revertShortening` puts it
+     * back, so a figure revised later needs no second import. On
+     * welte225.org the extension measures about 1.6 mm, with no
+     * dependence on how long the perforation is.
+     */
+    extension?: Millimeters;
 }
 /**
  * Reads one of his e-roll files as a copy of the roll, in millimetres
  * of paper, on the bar it was cut for and in that bar's numbering. A
  * position the bar does not read is left out, as the bar would leave it.
  */
-export declare function readFromPhillipsEroll(buffer: ArrayBuffer, { system, controlOffset, placeAt }?: PhillipsErollOptions): RollCopy;
+export declare function readFromPhillipsEroll(buffer: ArrayBuffer, { system, controlOffset, placeAt, extension }?: PhillipsErollOptions): RollCopy;
 /** The bars his files are known to be numbered by. */
 export declare const phillipsSystems: readonly TrackerBar[];

package/lib/readers/phillipsEroll.js

@@ -2,6 +2,7 @@ import { read } from "midifile-ts";
 import { v4 } from "uuid";
 import { assignObject } from "../Assumption.js";
 import { systemOf } from "../TrackerBar.js";
+import { shortenHoles } from "../alignment.js";
 import { welteT100 } from "../systems/welteT100/bar.js";
 import { welteLicensee } from "../systems/welteLicensee/bar.js";
 import { inMetersPerMinute, mm, seconds, track } from "../Quantity.js";
@@ -24,16 +25,21 @@ import { inMetersPerMinute, mm, seconds, track } from "../Quantity.js";
  * perforation, the height of the tracker bar hole and the paper speed
  * (p. 180).
  *
- * That extension is not subtracted. Doing so would need the absolute
- * hole height of the Welte bar, where he gives only the 0.5 mm by which
- * it exceeds the Licensee's. So the end of a hole on this copy is a
- * pneumatic on-time where the end of a scanned copy's hole is a punched
- * slot, and the two are not the same quantity. It shows in a collation:
- * across welte225.org his notes run about 1.8 mm longer than the other
- * copies read them, while the onsets agree. Until it is corrected, a
- * comparison of hole ends against this copy measures the reader as much
- * as the roll, and `offsetEnd` on the derivation absorbs the systematic
- * part of it.
+ * Left in, that extension is not a difference between copies at all:
+ * the end of a hole here is a pneumatic on-time where the end of a
+ * scanned copy's hole is a punched slot, so a collation comparing the
+ * two reads the one as a lengthening of the other. `extension` takes it
+ * off at the end of every hole, and the copy records what was taken.
+ *
+ * How much to take off is measured rather than derived, since he gives
+ * only the 0.5 mm by which the Welte bar's holes exceed the Licensee's
+ * and not the absolute. Across welte225.org it comes to about 1.6 mm,
+ * and the shape of it is simple: a constant, not growing with the
+ * length of the perforation, with no shortest on-time the valve cannot
+ * fall below, and with no run along the roll that one roll's span of
+ * paper speed could show. The port that read it matters by about half a
+ * millimetre either way, without any gradient across the bar, which is
+ * measured but too coarse to model from one roll.
  */
 /**
  * He numbers his files by two rules at once, which his free samples
@@ -134,7 +140,7 @@ const positionsByPitch = (bar) => new Map(Array.from({ length: bar.trackCount },
  * of paper, on the bar it was cut for and in that bar's numbering. A
  * position the bar does not read is left out, as the bar would leave it.
  */
-export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffset, placeAt } = {}) {
+export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffset, placeAt, extension } = {}) {
     const file = read(new Uint8Array(buffer));
     const timed = onOneClock(file.tracks);
     const elapsedAt = clockOf(temposIn(timed), file.header.ticksPerBeat);
@@ -157,7 +163,7 @@ export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffse
                 }
             }];
     });
-    return {
+    const copy = {
         type: 'RollCopy',
         id: v4(),
         ops: [],
@@ -171,6 +177,9 @@ export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffse
             note: 'Read on Phillips’s pneumatic roll reader. The places are elapsed time put back onto the paper, and a hole runs as long as its switch stayed open, which is longer than the perforation.'
         }
     };
+    if (extension !== undefined)
+        shortenHoles(extension, copy);
+    return copy;
 }
 /** The bars his files are known to be numbered by. */
 export const phillipsSystems = [welteT100, welteLicensee];

package/lib/schema.json

@@ -2828,6 +2828,10 @@
                             "description": "The average diameter of punched holes.",
                             "ontology": "reo:punchDiameter"
                         },
+                        "readerExtension": {
+                            "$ref": "#/definitions/Millimeters",
+                            "description": "How much longer this copy's reading of a hole ran than the perforation that caused it, where that was taken off the ends again. A pneumatic reader reports how long a valve stayed open, which exceeds the perforation that opened it, so its holes are overlong by a constant while its onsets agree. Nothing for a copy read by other means, whose holes are the punched slots themselves. Not exported to RDF."
+                        },
                         "scale": {
                             "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"
@@ -2861,7 +2865,8 @@
                     "items": {
                         "enum": [
                             "shifted",
-                            "stretched"
+                            "stretched",
+                            "shortened"
                         ],
                         "type": "string"
                     },

package/lib/spec/context.json

@@ -151,6 +151,7 @@
             "@context": {
                 "shift": null,
                 "scale": null,
+                "readerExtension": null,
                 "trackCalibration": null,
                 "margins": null,
                 "dimensions": "reo:dimensions",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.46.0",
+  "version": "0.48.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {