linked-rolls 0.58.0 → 0.60.0

package/lib/collation/Collation.d.ts

@@ -108,19 +108,23 @@ export declare const uncheckedMotivation: {
 };
 /**
  * Whether the edit is one a collation writes by itself: a bare
- * insertion or a bare deletion saying nothing further, or an
- * equivalence between two systems' spellings for one command.
+ * insertion or a bare deletion saying nothing further, or a recoding
+ * that exchanges two systems' spellings for one command.
  *
  * Collating again rewrites these and keeps the rest. An edit that says
  * what the change is, or why it was made, or what it rests on, is an
  * editor's reading of the difference between two texts, and collating
  * the two again is no reason to discard it.
  *
- * An equivalence counts as the collation's own even where an editor
+ * Such an exchange counts as the collation's own even where an editor
  * added a motivation to it, because it is derived rather than read:
  * freezing it would leave the transfers, where nearly every edit is
  * one, unable to be collated again at all. What an editor wrote on it
- * is not lost by that, since `connectVersions` keeps an equivalence it
+ * is not lost by that, since `connectVersions` keeps an exchange it
  * draws a second time over the very same symbols.
+ *
+ * A recoding that only inserts or only deletes is the editor's: a
+ * collation types no one-sided edit, so one typed so is a reading of
+ * the transfer that collating again must not undo.
  */
 export declare const isCollationsOwn: (edit: Readonly<Edit>) => boolean;

package/lib/collation/Collation.js

@@ -88,7 +88,7 @@ export const collationsOf = (own, inherited, locate, tolerance = defaultCollatio
         .map(({ symbol: counterpart }) => ({ symbol, counterpart })));
 };
 /** The edit type a collation draws by itself, from the two systems' vocabularies rather than off the paper. */
-const drawnByCollation = 'replace-with-equivalent';
+const drawnByCollation = 'recoding';
 /**
  * The motivation a collation writes on what it makes, saying that
  * nobody has read it yet.
@@ -112,22 +112,26 @@ export const uncheckedMotivation = {
 };
 /**
  * Whether the edit is one a collation writes by itself: a bare
- * insertion or a bare deletion saying nothing further, or an
- * equivalence between two systems' spellings for one command.
+ * insertion or a bare deletion saying nothing further, or a recoding
+ * that exchanges two systems' spellings for one command.
  *
  * Collating again rewrites these and keeps the rest. An edit that says
  * what the change is, or why it was made, or what it rests on, is an
  * editor's reading of the difference between two texts, and collating
  * the two again is no reason to discard it.
  *
- * An equivalence counts as the collation's own even where an editor
+ * Such an exchange counts as the collation's own even where an editor
  * added a motivation to it, because it is derived rather than read:
  * freezing it would leave the transfers, where nearly every edit is
  * one, unable to be collated again at all. What an editor wrote on it
- * is not lost by that, since `connectVersions` keeps an equivalence it
+ * is not lost by that, since `connectVersions` keeps an exchange it
  * draws a second time over the very same symbols.
+ *
+ * A recoding that only inserts or only deletes is the editor's: a
+ * collation types no one-sided edit, so one typed so is a reading of
+ * the transfer that collating again must not undo.
  */
-export const isCollationsOwn = (edit) => edit.editType === drawnByCollation
+export const isCollationsOwn = (edit) => (edit.editType === drawnByCollation && !!edit.insert?.length && !!edit.delete?.length)
     || (edit.editType === undefined
         && (edit.motivation === undefined || edit.motivation === unchecked)
         && edit['@annotation'] === undefined);

package/lib/index.d.ts

@@ -45,7 +45,7 @@ export * from './analysis/sigla.js';
 export * from './model/notes.js';
 export { asJsonLd } from './io/asJsonLd.js';
 export { importJsonLd } from './io/importJsonLd.js';
-export { formatVersion, migrate } from './io/migrate.js';
+export { migrate } from './io/migrate.js';
 export { readFromStanfordAton, type StanfordAtonOptions } from './readers/stanfordAton.js';
 export { readFromPhillipsEroll, CONTROL_OFFSET, phillipsSystems, type PhillipsErollOptions } from './readers/phillipsEroll.js';
 export { readFromSpencerBar, readSpencerAnn, paperSpeedOfSpencerAnn, SPENCER_ROWS_PER_INCH, type SpencerBarOptions } from './readers/spencerBar.js';

package/lib/index.js

@@ -38,7 +38,7 @@ export * from './analysis/sigla.js';
 export * from './model/notes.js';
 export { asJsonLd } from './io/asJsonLd.js';
 export { importJsonLd } from './io/importJsonLd.js';
-export { formatVersion, migrate } from './io/migrate.js';
+export { migrate } from './io/migrate.js';
 export { readFromStanfordAton } from './readers/stanfordAton.js';
 export { readFromPhillipsEroll, CONTROL_OFFSET, phillipsSystems } from './readers/phillipsEroll.js';
 export { readFromSpencerBar, readSpencerAnn, paperSpeedOfSpencerAnn, SPENCER_ROWS_PER_INCH } from './readers/spencerBar.js';

package/lib/io/asJsonLd.js

@@ -1,7 +1,6 @@
 import { systemIdIn } from "../systems/TrackerBar.js";
 import { certaintyOf, isAsserted } from "../model/Assumption.js";
 import context from "../spec/context.json" with { type: 'json' };
-import { formatVersion } from "./migrate.js";
 /**
  * The keys an export derives from the tree, which no node of the
  * edition states itself. An import reads them off again.
@@ -164,7 +163,6 @@ export const asJsonLd = (edition) => {
             }
         ],
         '@id': edition.base,
-        formatVersion,
         ...rest,
         ...(quoted.length > 0 && { '@included': quoted })
     };

package/lib/io/importJsonLd.js

@@ -119,7 +119,7 @@ const withQuotedStatementsInPlace = (edition) => {
     return withReferencesOn({ ...rest, ...(others.length > 0 && { '@included': others }) }, bySubject);
 };
 export const importJsonLd = (json) => {
-    const { '@context': context, formatVersion: _revision, ...document } = withPlainCopyIds(migrate(withQuotedStatementsInPlace(json)));
+    const { '@context': context, ...document } = withPlainCopyIds(migrate(withQuotedStatementsInPlace(json)));
     const edition = fromJsonLdEntity(document);
     edition.base = Array.isArray(context)
         ? context.find((c) => c['@base'])?.['@base'] || ''

package/lib/io/migrate.d.ts

@@ -13,14 +13,5 @@
 type Json = any;
 /** A copy's id without the `copy/` that documents of earlier releases put before it. */
 export declare const plainCopyId: (id: string) => string;
-/**
- * The revision of the format this release writes, stated in every export
- * as `formatVersion`. A document stating it is in the current shape and
- * passes through untouched; one stating none was written before the
- * revisions were numbered and is brought up by recognising its shapes.
- * A step added later is to run on the documents of the revisions before
- * it, and to raise this number.
- */
-export declare const formatVersion = 1;
 export declare const migrate: (edition: Json) => Json;
 export {};

package/lib/io/migrate.js

@@ -4,10 +4,10 @@ import { welteT100 } from "../systems/welteT100/bar.js";
 import { isDateString } from "../shared/utils.js";
 const retiredVersionTypes = new Set(['edition', 'unicum']);
 /**
- * The vocabulary the steps below were written against, as it stood when
- * the format was first given a revision number. It is copied here rather
- * than imported from the model, so that changing today's vocabulary
- * cannot change how an old document is read. The tracker bars are still
+ * The vocabulary the steps below were written against, as it stood in
+ * release 0.58.0. It is copied here rather than imported from the model,
+ * so that changing today's vocabulary cannot change how an old document
+ * is read. The tracker bars are still
  * asked, being the layout of instruments rather than a choice of the
  * format.
  */
@@ -54,6 +54,13 @@ const withTypology = (node) => {
     }
     return node;
 };
+/** Edit types renamed since: an exchange of two systems' spellings is one kind of recoding. */
+const renamedEditTypes = {
+    'replace-with-equivalent': 'recoding'
+};
+const withRenamedEditType = (node) => typeof node.editType === 'string' && Object.hasOwn(renamedEditTypes, node.editType)
+    ? { ...node, editType: renamedEditTypes[node.editType] }
+    : node;
 const withRenamedType = (node) => Object.hasOwn(renamedTypes, node['@type']) ? { ...node, '@type': renamedTypes[node['@type']] } : node;
 /** Whether the feature is of the class under either name, since a node is migrated before its children are. */
 const isOfType = (type) => (feature) => feature?.['@type'] === type || renamedTypes[feature?.['@type']] === type;
@@ -371,7 +378,7 @@ const withTimeSpanDates = (node) => {
     const { '@value': within, '@type': _typed, ...rest } = node;
     return { ...rest, within };
 };
-const migrateNode = (node) => [withRenamedKeys, withTypology, withRenamedType, withoutVersionType, withoutVersionSiglum, withLowerCaseTerms, withSplitMethod, withReferences, withKeeper, withoutEmptyKeeper,
+const migrateNode = (node) => [withRenamedKeys, withRenamedEditType, withTypology, withRenamedType, withoutVersionType, withoutVersionSiglum, withLowerCaseTerms, withSplitMethod, withReferences, withKeeper, withoutEmptyKeeper,
     withPerforator, withProductionNodes, withTypedPerforator, withScale, withoutOps, withDerivationList, withReadingKind, withTimeSpanDates,
     withoutFeatureKind, withBorneFeaturesNamed, withFeaturesInActs, withDriveOfStaggering, withoutPattern, withoutBearings, withoutEntailedType]
     .reduce((result, step) => step(result), node);
@@ -511,27 +518,12 @@ const withDerivationTolerance = (edition) => {
             : version)
     };
 };
-const editionSteps = [withoutEditionType, withSystems, withEditors, withDerivationTolerance];
-/**
- * The revision of the format this release writes, stated in every export
- * as `formatVersion`. A document stating it is in the current shape and
- * passes through untouched; one stating none was written before the
- * revisions were numbered and is brought up by recognising its shapes.
- * A step added later is to run on the documents of the revisions before
- * it, and to raise this number.
- */
-export const formatVersion = 1;
-export const migrate = (edition) => {
-    const stated = edition?.formatVersion;
-    if (stated === formatVersion)
+/** Release 0.58.0 stated a revision of the format, which the format does not state. */
+const withoutFormatVersion = (edition) => {
+    if (!Object.hasOwn(edition, 'formatVersion'))
         return edition;
-    if (typeof stated === 'number' && stated > formatVersion) {
-        throw new Error(`The document is written in revision ${stated} of the format, which this release, reading up to ${formatVersion}, does not know`);
-    }
-    const current = walk(editionSteps.reduce((result, step) => step(result), edition));
-    // What comes out is in the current revision and says so, so that it
-    // passes through untouched when it is migrated again.
-    return current !== null && typeof current === 'object' && !Array.isArray(current)
-        ? { ...current, formatVersion }
-        : current;
+    const { formatVersion: _stated, ...rest } = edition;
+    return rest;
 };
+const editionSteps = [withoutFormatVersion, withoutEditionType, withSystems, withEditors, withDerivationTolerance];
+export const migrate = (edition) => walk(editionSteps.reduce((result, step) => step(result), edition));

package/lib/model/Edit.d.ts

@@ -7,7 +7,14 @@ export declare const editTypes: readonly [
  * sforzando on/off due to the short space left between
  * the notes to be differentiated.
  */
-'short-dynamic-differentation', 'additional-accent', 'add-redundancy', 'remove-redundancy', 'replace-with-equivalent', 'shift', 'correct-error', 'shorten', 'prolong'];
+'short-dynamic-differentation', 'additional-accent', 'add-redundancy', 'remove-redundancy', 
+/**
+ * Carries the text into another reproducing system's coding: a
+ * latched pair of one system giving way to the other's held command,
+ * a command the other system cannot read struck, or one of its own
+ * put in where the first had no word for it.
+ */
+'recoding', 'shift', 'correct-error', 'shorten', 'prolong'];
 /**
  * The type of editorial change applied to a symbol or set of symbols.
  * Classifies the nature of the edit, e.g. whether it corrects an error,

package/lib/model/Edit.js

@@ -8,7 +8,13 @@ export const editTypes = [
     'additional-accent',
     'add-redundancy',
     'remove-redundancy',
-    'replace-with-equivalent',
+    /**
+     * Carries the text into another reproducing system's coding: a
+     * latched pair of one system giving way to the other's held command,
+     * a command the other system cannot read struck, or one of its own
+     * put in where the first had no word for it.
+     */
+    'recoding',
     'shift',
     'correct-error',
     'shorten',

package/lib/ops/collation.js

@@ -98,7 +98,7 @@ export const connectVersions = (given, childId, parentId, tolerance = defaultCol
         return alreadyStated.get(exchangeKey(inserted, deleted)) ?? {
             type: 'edit',
             id: v4(),
-            editType: 'replace-with-equivalent',
+            editType: 'recoding',
             motivation: unchecked,
             insert: [...by],
             delete: deleted

package/lib/ops/edits.js

@@ -31,18 +31,24 @@ const guessEditType = (view, versionId, edit) => {
     const bar = trackerBarOf(view.version(versionId)?.system);
     const parentBar = trackerBarOf(view.predecessorOf(versionId)?.system);
     /**
-     * Where the version is coded for another system than its parent, an
-     * exchange of expression matter is the transfer being carried out:
-     * a red ForzandoOn and ForzandoOff pair giving way to one held green
-     * SforzandoForte says the same thing in the other system's words,
-     * which is what 'replace-with-equivalent' is for. Calling it a
-     * corrected error would say the editor made a mistake.
+     * Where the version is coded for another system than its parent,
+     * expression matter changed is the transfer being carried out: a red
+     * ForzandoOn and ForzandoOff pair giving way to one held green
+     * SforzandoForte says the same thing in the other system's words, and
+     * a red command the green bar cannot read struck, or a green hold put
+     * in where the red had no word for it, belongs to the same act. That
+     * is a recoding. Calling it a corrected error would say the editor
+     * made a mistake. Only an insertion spelling the bar's own accent
+     * reads more narrowly, as the accent it spells.
      */
-    if (bar && parentBar && bar.id !== parentBar.id && inserted.length > 0 && deleted.length > 0) {
-        return 'replace-with-equivalent';
-    }
+    const transferred = bar && parentBar && bar.id !== parentBar.id;
+    if (transferred && inserted.length > 0 && deleted.length > 0)
+        return 'recoding';
     if (deleted.length === 0 && accentsOn(bar).some(accent => sameSequence(inserted, accent)))
         return 'additional-accent';
+    const onlyExpressions = [...inserts, ...deletes].every(symbol => symbol.type === 'expression');
+    if (transferred && onlyExpressions && inserted.length + deleted.length > 0)
+        return 'recoding';
     if (inserted.length > 1 && sameSequence(inserted, deleted))
         return 'shift';
     if (inserted.length === 0 && deleted.length === 1)

package/lib/schema.json

@@ -516,7 +516,7 @@
                 "additional-accent",
                 "add-redundancy",
                 "remove-redundancy",
-                "replace-with-equivalent",
+                "recoding",
                 "shift",
                 "correct-error",
                 "shorten",

package/lib/spec/context.json

@@ -89,7 +89,6 @@
             "@type": "xsd:date"
         },
         "collationTolerance": null,
-        "formatVersion": null,
         "annotation": null,
         "roll": "lrmoo:R3i_realises",
         "catalogueNumber": "dcterms:identifier",

package/package.json

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