linked-rolls 0.47.0 → 0.49.0

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

@@ -259,16 +259,28 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
          */
         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.
+         * What a pneumatic reader added to this copy's holes, where it
+         * was taken off again. Such a 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;
+        readerExtension: {
+            /** How much longer the reading of a hole ran than the perforation that caused it. */
+            length: Millimeters;
+            /**
+             * The holes it was not taken off, by `@id`, being no longer
+             * than it is. The constant reaches its limit there rather
+             * than the copy being wrong, and why they were left is for
+             * the edition to state about the features themselves; this
+             * only records that they stand as the reader gave them, so
+             * that putting the extension back does not lengthen a hole
+             * nothing was taken from.
+             */
+            leaving?: string[];
+        };
         /**
          * 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

@@ -32,8 +32,32 @@ export declare const revertScale: (copy: RollCopy) => void;
  *
  * Only holes are touched. What a writing or a mark spans is no valve.
  */
-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. */
+/**
+ * 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, leaving?: ReadonlySet<string>) => Readonly<FeatureOrPatch>[];
+/**
+ * Takes the extension off, leaving the named holes as the reader gave
+ * them. Naming a hole is an editorial act and not a repair: it says
+ * this one is where the constant stops applying, and the edition is
+ * what has to say why. The copy records which were left, so that
+ * putting the extension back does not lengthen a hole nothing was
+ * taken from.
+ *
+ * Throws where a hole that was not named is no longer than the
+ * extension, `tooShortToShorten` saying beforehand which those are.
+ */
+export declare const shortenHoles: (extension: Millimeters, copy: RollCopy, leaving?: ReadonlySet<string>) => void;
+/** Puts the reader's extension back on the holes it was taken off, 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:

package/lib/alignment.js

@@ -78,19 +78,55 @@ const holesOf = (copy) => featuresOf(copy).filter(feature => feature.type === 'H
  *
  * Only holes are touched. What a writing or a mark spans is no valve.
  */
-export const shortenHoles = (extension, copy) => {
+/**
+ * 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, leaving = new Set()) => holesOf(copy).filter(hole => !leaving.has(hole.id) && hole.horizontal.to - hole.horizontal.from <= extension);
+/**
+ * Takes the extension off, leaving the named holes as the reader gave
+ * them. Naming a hole is an editorial act and not a repair: it says
+ * this one is where the constant stops applying, and the edition is
+ * what has to say why. The copy records which were left, so that
+ * putting the extension back does not lengthen a hole nothing was
+ * taken from.
+ *
+ * Throws where a hole that was not named is no longer than the
+ * extension, `tooShortToShorten` saying beforehand which those are.
+ */
+export const shortenHoles = (extension, copy, leaving = new Set()) => {
     if (copy.ops.includes('shortened'))
         return;
-    holesOf(copy).forEach(hole => { hole.horizontal.to = subtract(hole.horizontal.to, extension); });
+    const tooShort = tooShortToShorten(extension, copy, leaving);
+    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(', ')}`);
+    }
+    const left = holesOf(copy).filter(hole => leaving.has(hole.id)).map(hole => hole.id);
+    holesOf(copy)
+        .filter(hole => !leaving.has(hole.id))
+        .forEach(hole => { hole.horizontal.to = subtract(hole.horizontal.to, extension); });
     copy.ops = [...copy.ops, 'shortened'];
-    copy.measurements.readerExtension = extension;
+    copy.measurements.readerExtension = { length: extension, ...(left.length > 0 && { leaving: left }) };
 };
-/** Puts the reader's extension back on the copy's holes, as far as one was taken off. */
+/** Puts the reader's extension back on the holes it was taken off, as far as one was taken off. */
 export const revertShortening = (copy) => {
-    const extension = copy.measurements.readerExtension;
-    if (!copy.ops.includes('shortened') || extension === undefined)
+    const taken = copy.measurements.readerExtension;
+    if (!copy.ops.includes('shortened') || taken === undefined)
         return;
-    holesOf(copy).forEach(hole => { hole.horizontal.to = add(hole.horizontal.to, extension); });
+    const left = new Set(taken.leaving ?? []);
+    holesOf(copy)
+        .filter(hole => !left.has(hole.id))
+        .forEach(hole => { hole.horizontal.to = add(hole.horizontal.to, taken.length); });
     copy.ops = copy.ops.filter(op => op !== 'shortened');
     delete copy.measurements.readerExtension;
 };

package/lib/editionOps.d.ts

@@ -46,7 +46,7 @@ export declare const unalignCopy: (copyId: string) => EditionOp;
  * 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;
+export declare const shortenCopy: (copyId: string, extension: Millimeters, leaving?: ReadonlySet<string>) => 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. */

package/lib/editionOps.js

@@ -2,7 +2,7 @@ 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";
@@ -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. */
@@ -130,7 +141,7 @@ export const unalignCopy = (copyId) => onCopy(copyId, copy => {
  * 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));
+export const shortenCopy = (copyId, extension, leaving) => onCopy(copyId, copy => shortenHoles(extension, copy, leaving));
 /** 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. */
@@ -733,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
         };
@@ -740,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)

package/lib/schema.json

@@ -2829,8 +2829,24 @@
                             "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."
+                            "description": "What a pneumatic reader added to this copy's holes, where it was taken off again. Such a 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.",
+                            "properties": {
+                                "leaving": {
+                                    "description": "The holes it was not taken off, by `@id`, being no longer than it is. The constant reaches its limit there rather than the copy being wrong, and why they were left is for the edition to state about the features themselves; this only records that they stand as the reader gave them, so that putting the extension back does not lengthen a hole nothing was taken from.",
+                                    "items": {
+                                        "type": "string"
+                                    },
+                                    "type": "array"
+                                },
+                                "length": {
+                                    "$ref": "#/definitions/Millimeters",
+                                    "description": "How much longer the reading of a hole ran than the perforation that caused it."
+                                }
+                            },
+                            "required": [
+                                "length"
+                            ],
+                            "type": "object"
                         },
                         "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.",

package/package.json

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