linked-rolls 0.74.0 → 0.76.0

package/lib/io/migrate.js

@@ -4,6 +4,7 @@ import { trackerBars } from "../systems/index.js";
 import { welteT100 } from "../systems/welteT100/bar.js";
 import { isDateString } from "../shared/utils.js";
 import { mapped, withValues } from "../ops/immutable.js";
+import { musicalChange, technicalChange } from "../model/Edit.js";
 const retiredVersionTypes = new Set(['edition', 'unicum']);
 /**
  * The vocabulary the steps below were written against, as it stood in
@@ -63,6 +64,37 @@ const renamedEditTypes = {
 const withRenamedEditType = (node) => typeof node.editType === 'string' && Object.hasOwn(renamedEditTypes, node.editType)
     ? { ...node, editType: renamedEditTypes[node.editType] }
     : node;
+/** The motivation a corrected error is stated with, as `correctedErrorMotivation` was when the kind of edit was retired. */
+const correctedErrorMotivation = {
+    '@type': 'motivation',
+    '@id': 'corrected-error',
+    note: 'Puts right an error of the version it derives from.'
+};
+const isTypedCorrectError = (edit) => edit !== null && typeof edit === 'object' && (edit.editType === 'correct-error' || edit.classification === 'correct-error');
+/**
+ * Whether a change corrects an error was once one of the kinds of edit,
+ * though it is not read off the shape of a change but is a reason for
+ * it. An edit typed so states it as its motivation instead, where it
+ * gives none of its own, and the version states what the motivation
+ * means; one that gives a motivation of its own keeps that one. Either
+ * way it states no kind, its shape being left to be read again. Once
+ * motivations are the edition's, a corrected error is a musical change
+ * (`withMotivationsOfTheEdition`).
+ */
+const withCorrectedErrorsMotivated = (node) => {
+    if (!Array.isArray(node.edits) || !node.edits.some(isTypedCorrectError))
+        return node;
+    const edits = node.edits.map((edit) => {
+        if (!isTypedCorrectError(edit))
+            return edit;
+        const { editType: _kind, classification: _named, ...rest } = edit;
+        return rest.motivation === undefined || rest.motivation === 'unchecked' ? { ...rest, motivation: correctedErrorMotivation['@id'] } : rest;
+    });
+    const motivations = Array.isArray(node.motivations) ? node.motivations : [];
+    const declare = edits.some((edit) => edit?.motivation === correctedErrorMotivation['@id'])
+        && !motivations.some(motivation => motivation?.['@id'] === correctedErrorMotivation['@id']);
+    return { ...node, edits, ...(declare && { motivations: [...motivations, correctedErrorMotivation] }) };
+};
 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;
@@ -503,7 +535,7 @@ const withMeasuredByInReasons = (node) => {
         }
     };
 };
-const nodeSteps = [withRenamedKeys, withRenamedEditType, withTypology, withRenamedType, withoutVersionType, withoutVersionSiglum, withLowerCaseTerms, withSplitMethod, withReferences, withKeeper, withoutEmptyKeeper,
+const nodeSteps = [withRenamedKeys, withRenamedEditType, withCorrectedErrorsMotivated, withTypology, withRenamedType, withoutVersionType, withoutVersionSiglum, withLowerCaseTerms, withSplitMethod, withReferences, withKeeper, withoutEmptyKeeper,
     withPerforator, withProductionNodes, withTypedPerforator, withScale, withoutOps, withDerivationList, withReadingKind, withTimeSpanDates,
     withoutFeatureKind, withBorneFeaturesNamed, withFeaturesInActs, withOwnPlaces, withDriveOfStaggering, withoutPattern, withoutBearings, withoutEntailedType,
     withMeasuredByInReasons];
@@ -677,6 +709,168 @@ const withReferenceCopy = (edition) => {
         : edition;
 };
 const editionSteps = [withoutFormatVersion, withoutTempoAdjustment, withoutEditionType, withSystems, withEditors, withDerivationTolerance, withReferenceCopy];
+/**
+ * The motivation an edit of a version that derives from another is left
+ * with where only the edition can tell what kind of change it is: one
+ * that states neither a kind nor a reason, as a collation once left
+ * them. `importJsonLd` reads its kind off its shape (`proposedMotivations`).
+ */
+export const uncheckedMotivation = 'unchecked';
+/** The kinds of edit, as they were stated once, whose shape is a musical decision. */
+const musicalEditTypes = new Set(['additional-accent', 'shift', 'shorten', 'prolong']);
+/** The kinds of edit, as they were stated once, whose shape is a technical change. */
+const technicalEditTypes = new Set(['recoding', 'remove-redundancy', 'add-redundancy']);
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Whether the version derives from another, so that its edits are changes rather than its text. */
+const derives = (version) => Array.isArray(version?.basedOn) ? version.basedOn.length > 0 : version?.basedOn !== undefined;
+/**
+ * The motivation an edit states once motivations say what kind of
+ * change it is, from the kind it was given and the reason it gave.
+ */
+const motivationOfEdit = (editType, motivation, derived) => {
+    // A corrected error put back a perforation in its place, and so made a musical change.
+    const stated = motivation === 'corrected-error' ? musicalChange : motivation;
+    if (!derived)
+        return stated === uncheckedMotivation || stated === musicalChange ? undefined : stated;
+    const technical = typeof editType === 'string' && technicalEditTypes.has(editType);
+    // A reason given for a technical change explained what the change or the procedure says already.
+    if (technical)
+        return technicalChange;
+    if (stated === undefined || stated === uncheckedMotivation) {
+        return typeof editType === 'string' && musicalEditTypes.has(editType) ? musicalChange : uncheckedMotivation;
+    }
+    return stated;
+};
+/** Whether the document still states what motivations and kinds of edit were before 0.76. */
+const statesMotivationsPerVersion = (versions) => versions.some(version => Array.isArray(version?.motivations)
+    || (Array.isArray(version?.edits) && version.edits.some((edit) => isRecord(edit) && (Object.hasOwn(edit, 'editType') || edit.motivation === 'corrected-error'))));
+/**
+ * Before 0.76 each version stated the motivations its edits named, and
+ * an edit stated its kind beside its reason. The motivations are the
+ * edition's now, once each, and the motivation alone says what kind of
+ * change an edit is (`kindOfChange`):
+ *
+ * - A motivation two versions stated under one id with different notes
+ *   is kept under an id of its own for the second.
+ * - The unchecked motivation goes, and so does the declaration of a
+ *   corrected error: it put a perforation back in its place, and so is
+ *   a musical change whose reason is not given.
+ * - An edit of a version that derives from another, that gave no reason
+ *   or only that it was unchecked, is a musical change whose reason is
+ *   not given where its kind was an added accent, a shift, a shortening
+ *   or a prolongation, and a technical change where it was a recoding or
+ *   a redundancy removed or added. One that stated no kind is left
+ *   unchecked, for an import to read its kind off its shape.
+ * - A reason given for a recoding or a redundancy goes, since a
+ *   technical change needs none, and a motivation nothing names any
+ *   longer goes with it. Every other reason stays, and makes the change
+ *   a musical one.
+ * - The edits of a version that derives from none state its text and
+ *   keep no motivation but a reason someone gave.
+ */
+const withMotivationsOfTheEdition = (edition) => {
+    const versions = listAt(edition, 'versions');
+    if (!versions || !statesMotivationsPerVersion(versions))
+        return edition;
+    const notes = new Map((listAt(edition, 'motivations') ?? []).filter(isRecord).map(motivation => [motivation['@id'], motivation]));
+    const referencedBefore = new Set();
+    const migrated = versions.map((version, index) => {
+        if (!isRecord(version))
+            return version;
+        const renamed = new Map();
+        for (const motivation of Array.isArray(version.motivations) ? version.motivations.filter(isRecord) : []) {
+            const id = motivation['@id'];
+            if (typeof id !== 'string' || id === uncheckedMotivation || id === 'corrected-error')
+                continue;
+            const known = notes.get(id);
+            if (!known)
+                notes.set(id, motivation);
+            else if (known.note !== motivation.note) {
+                const own = `${id}-${index}`;
+                renamed.set(id, own);
+                notes.set(own, { ...motivation, '@id': own });
+            }
+        }
+        const derived = derives(version);
+        const { motivations: _declared, ...rest } = version;
+        if (!Array.isArray(version.edits))
+            return rest;
+        return {
+            ...rest,
+            edits: version.edits.map((edit) => {
+                if (!isRecord(edit))
+                    return edit;
+                const { editType, motivation: given, ...stated } = edit;
+                const named = typeof given === 'string' ? renamed.get(given) ?? given : given;
+                if (typeof named === 'string')
+                    referencedBefore.add(named);
+                const motivation = motivationOfEdit(editType, named, derived);
+                return motivation === undefined ? stated : { ...stated, motivation };
+            })
+        };
+    });
+    const referenced = new Set(migrated.flatMap((version) => (Array.isArray(version?.edits) ? version.edits : []).map((edit) => edit?.motivation).filter((id) => typeof id === 'string')));
+    const motivations = [...notes.values()].filter(motivation => referenced.has(motivation['@id']) || !referencedBefore.has(motivation['@id']));
+    const { motivations: _stated, ...rest } = edition;
+    return { ...rest, versions: migrated, ...(motivations.length > 0 && { motivations }) };
+};
+/**
+ * Before 0.76 an adopted proposal was recorded as a proposition set: each
+ * statement of it named the set in its annotation, and the set held them
+ * under one belief whose inference named the release that found them and
+ * the rules it followed. The edition states what a program concluded
+ * plainly now, and its creation names the rules among its principles and
+ * the release among its software. A statement of a set the edition held
+ * below likely keeps the doubt, under a belief of its own that is the
+ * set's.
+ */
+const withoutPropositionSets = (edition) => {
+    const sets = listAt(edition, 'propositionSets');
+    if (!sets)
+        return edition;
+    const beliefOf = new Map(sets.filter(isRecord).map(set => [set['@id'], set.belief]));
+    const inferences = sets.filter(isRecord).flatMap(set => Array.isArray(set.belief?.reasons) ? set.belief.reasons : []);
+    const rules = inferences.flatMap(inference => Array.isArray(inference?.applies) ? inference.applies : []);
+    const programs = inferences.flatMap(inference => Array.isArray(inference?.software) ? inference.software : []);
+    let held = 0;
+    const unset = (value) => {
+        if (Array.isArray(value))
+            return mapped(value, unset);
+        if (!isRecord(value))
+            return value;
+        const annotation = value['@annotation'];
+        const set = isRecord(annotation) && typeof annotation['@id'] === 'string' ? beliefOf.get(annotation['@id']) : undefined;
+        if (!set || (isRecord(annotation.belief) && Object.keys(annotation.belief).some(key => key !== '@id')))
+            return withValues(value, unset);
+        const { '@annotation': _member, ...rest } = value;
+        if (set.certainty === 'true' || set.certainty === 'likely')
+            return withValues(rest, unset);
+        held += 1;
+        return withValues({
+            ...rest,
+            '@annotation': { '@id': `${annotation['@id']}/${held}`, belief: { ...set, '@id': `${set['@id']}/${held}` } }
+        }, unset);
+    };
+    const { propositionSets: _recorded, ...rest } = edition;
+    const unsetted = unset(rest);
+    const creation = isRecord(unsetted.creation) ? unsetted.creation : undefined;
+    if (!creation)
+        return unsetted;
+    const principles = [...new Set([...(Array.isArray(creation.principles) ? creation.principles : []), ...rules])];
+    const known = Array.isArray(creation.software) ? creation.software : [];
+    const software = [...known, ...programs.filter((program, index) => !known.some((other) => other?.name === program?.name && other?.version === program?.version)
+            && programs.findIndex(other => other?.name === program?.name && other?.version === program?.version) === index)];
+    return {
+        ...unsetted,
+        creation: {
+            ...creation,
+            ...(principles.length > 0 && { principles }),
+            ...(software.length > 0 && { software })
+        }
+    };
+};
+/** Steps that read the document as the node steps leave it, an old document's kinds of edit renamed. */
+const finalSteps = [withoutPropositionSets, withMotivationsOfTheEdition];
 /**
  * Brings the JSON of an edition written by an earlier release of the
  * format up to the current shape. A document that is current already
@@ -685,4 +879,4 @@ const editionSteps = [withoutFormatVersion, withoutTempoAdjustment, withoutEditi
  * to look at an old document as JSON.
  * @category Reading and writing
  */
-export const migrate = (edition) => walk(editionSteps.reduce((result, step) => step(result), edition));
+export const migrate = (edition) => finalSteps.reduce((result, step) => step(result), walk(editionSteps.reduce((result, step) => step(result), edition)));

package/lib/model/Agent.d.ts

@@ -107,7 +107,9 @@ export type Concept = (WithId & Partial<Named>) | (Named & Partial<WithId>);
 /**
  * Software that captured a copy or measured it: the transcriber that
  * read a recording into notes, the emulator that wrote a MIDI file, the
- * program that found the holes on a scan or aligned two copies.
+ * program that found the holes on a scan or aligned two copies. Or the
+ * software an edition was made with, such as the release of this
+ * library that found its stemma.
  * @see crmdig:D14 Software
  * @category Format types
  */

package/lib/model/Assumption.d.ts

@@ -21,7 +21,8 @@ export type Certainty = typeof certainties[number];
  */
 export declare const isAsserted: (certainty: Certainty) => boolean;
 /**
- * The certainty a statement is held with. One that carries no belief is stated plainly, and so held true.
+ * The certainty a statement is held with. One that carries no belief is
+ * stated plainly, and so held true.
  * @category Assumptions and beliefs
  */
 export declare const certaintyOf: (assumption: Readonly<Assumption>) => Certainty;
@@ -202,6 +203,12 @@ export interface Assumption {
      * 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.
+     *
+     * A statement that carries none is stated plainly, and what a
+     * program concluded is stated so too: an edition asserts its stemma
+     * and its edits, as a printed edition does, and its creation names
+     * the principles and the release they were found by
+     * (`EditionCreation`). A belief is kept for what the editor doubts.
      */
     '@annotation'?: WithId & {
         /**

package/lib/model/Assumption.js

@@ -19,7 +19,8 @@ export const certainties = [
  */
 export const isAsserted = (certainty) => certainty === 'true' || certainty === 'likely';
 /**
- * The certainty a statement is held with. One that carries no belief is stated plainly, and so held true.
+ * The certainty a statement is held with. One that carries no belief is
+ * stated plainly, and so held true.
  * @category Assumptions and beliefs
  */
 export const certaintyOf = (assumption) => assumption['@annotation']?.belief.certainty ?? 'true';

package/lib/model/Edit.d.ts

@@ -1,30 +1,92 @@
 import { Assumption } from "./Assumption.js";
 import { AnySymbol } from "./Symbol.js";
-import { WithId } from "../shared/utils.js";
+import { WithId, WithNote, WithType } from "../shared/utils.js";
 /**
- * The types of editorial change an edit may state.
+ * A reason for a musical change, in the editor's words. The edition
+ * states its motivations once (`Edition.motivations`), and an edit of
+ * any version names the one it was made for. Every change of a version
+ * that derives from another states a motivation: a program states
+ * whether it is musical or technical (`musicalChange`,
+ * `technicalChange`), and the editor puts a reason of their own in
+ * place of a musical one. Speculating about why a change was made is
+ * kept to the musical changes.
+ * @see crm:E33 Linguistic Object
+ * @category Format types
+ */
+export type Motivation = WithType<'motivation'> & WithId & WithNote;
+/**
+ * The motivation of a musical change whose reason is not given yet: a
+ * change of the performance, such as an added accent or a perforation
+ * put elsewhere. A program states it for a change whose shape a musical
+ * decision makes, under the rule that later versions are the more
+ * refined; the editor puts a reason of their own in its place.
+ * @category Versions and stemma
+ */
+export declare const musicalChange = "https://w3id.org/reo/type/motivation/musical";
+/**
+ * The motivation of a technical change: one that changes only how the
+ * performance is carried, a redundancy cleaned up or added, or a
+ * command recoded for another reproducing system. A program states it
+ * for a change of such a shape, and the procedure of the version's
+ * creation explains it, so that no reason of its own is given.
+ * @category Versions and stemma
+ */
+export declare const technicalChange = "https://w3id.org/reo/type/motivation/technical";
+/**
+ * The kinds of change an edit can be: one that changes the
+ * performance, and one that changes only how it is carried.
  * @category Vocabulary
  */
-export declare const editTypes: readonly ['additional-accent', 'add-redundancy', 'remove-redundancy', 
+export declare const changeKinds: readonly ['musical', 'technical'];
+/**
+ * The kind of change an edit is (`kindOfChange`).
+ * @category Format types
+ */
+export type ChangeKind = typeof changeKinds[number];
+/**
+ * What kind of change the edit is, as its motivation says: technical
+ * if it is `technicalChange`, musical if it is `musicalChange` or a
+ * reason of the editor's.
+ *
+ * An edit without a motivation is of no kind: the edits of a version
+ * that derives from none state its text rather than a change.
+ * @category Versions and stemma
+ */
+export declare const kindOfChange: (edit: Readonly<Pick<Edit, 'motivation'>>) => ChangeKind | undefined;
+/**
+ * The shapes a change can take, read off what it inserts and deletes
+ * and the systems of the two versions (`shapeOf`, `proposeEdits`). A
+ * shape is not stated: it is what a program reads to propose a
+ * motivation, and what a view can call a change.
+ * @category Vocabulary
+ */
+export declare const editShapes: readonly ['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'];
+'recoding', 'shift', '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,
- * adds an accent, shifts a note, or shortens/prolongs a perforation.
+ * The shape of a change (`editShapes`).
  * @category Format types
  */
-export type EditType = typeof editTypes[number];
+export type EditShape = typeof editShapes[number];
+/**
+ * The motivation a program states for a change of this shape. A
+ * recoding and a redundancy removed or added are technical changes
+ * (`technicalChange`). Every other change of a later version is taken
+ * for a refinement, and so for a musical change whose reason is not
+ * given yet (`musicalChange`).
+ * @category Versions and stemma
+ */
+export declare const motivationProposedFor: (shape: EditShape | undefined) => string;
 /**
  * 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.
+ * What kind of change an edit is follows from its motivation
+ * (`kindOfChange`).
  * 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.
@@ -38,13 +100,10 @@ export type EditType = typeof editTypes[number];
 export interface Edit extends WithId, Assumption {
     type: 'edit';
     /**
-     * The type of editorial change (e.g. 'correct-error', 'additional-accent').
-     * @see crm:P2 has type
-     */
-    editType?: EditType;
-    /**
-     * A textual description of the motivation for this edit,
-     * referencing a motivation defined in the version's motivations list.
+     * Why the edit was made: one of the edition's motivations, by id,
+     * or one the vocabulary publishes, by IRI (`musicalChange`,
+     * `technicalChange`). An edit of a version that derives from none
+     * states none.
      * @see crm:P17 was motivated by
      */
     motivation?: string;

package/lib/model/Edit.js

@@ -1,8 +1,47 @@
 /**
- * The types of editorial change an edit may state.
+ * The motivation of a musical change whose reason is not given yet: a
+ * change of the performance, such as an added accent or a perforation
+ * put elsewhere. A program states it for a change whose shape a musical
+ * decision makes, under the rule that later versions are the more
+ * refined; the editor puts a reason of their own in its place.
+ * @category Versions and stemma
+ */
+export const musicalChange = 'https://w3id.org/reo/type/motivation/musical';
+/**
+ * The motivation of a technical change: one that changes only how the
+ * performance is carried, a redundancy cleaned up or added, or a
+ * command recoded for another reproducing system. A program states it
+ * for a change of such a shape, and the procedure of the version's
+ * creation explains it, so that no reason of its own is given.
+ * @category Versions and stemma
+ */
+export const technicalChange = 'https://w3id.org/reo/type/motivation/technical';
+/**
+ * The kinds of change an edit can be: one that changes the
+ * performance, and one that changes only how it is carried.
  * @category Vocabulary
  */
-export const editTypes = [
+export const changeKinds = ['musical', 'technical'];
+/**
+ * What kind of change the edit is, as its motivation says: technical
+ * if it is `technicalChange`, musical if it is `musicalChange` or a
+ * reason of the editor's.
+ *
+ * An edit without a motivation is of no kind: the edits of a version
+ * that derives from none state its text rather than a change.
+ * @category Versions and stemma
+ */
+export const kindOfChange = (edit) => edit.motivation === undefined
+    ? undefined
+    : edit.motivation === technicalChange ? 'technical' : 'musical';
+/**
+ * The shapes a change can take, read off what it inserts and deletes
+ * and the systems of the two versions (`shapeOf`, `proposeEdits`). A
+ * shape is not stated: it is what a program reads to propose a
+ * motivation, and what a view can call a change.
+ * @category Vocabulary
+ */
+export const editShapes = [
     'additional-accent',
     'add-redundancy',
     'remove-redundancy',
@@ -14,10 +53,20 @@ export const editTypes = [
      */
     'recoding',
     'shift',
-    'correct-error',
     'shorten',
     'prolong',
 ];
+/**
+ * The motivation a program states for a change of this shape. A
+ * recoding and a redundancy removed or added are technical changes
+ * (`technicalChange`). Every other change of a later version is taken
+ * for a refinement, and so for a musical change whose reason is not
+ * given yet (`musicalChange`).
+ * @category Versions and stemma
+ */
+export const motivationProposedFor = (shape) => shape === 'recoding' || shape === 'remove-redundancy' || shape === 'add-redundancy'
+    ? technicalChange
+    : musicalChange;
 /**
  * Whether the object is an edit.
  * @category Lookups

package/lib/model/Edition.d.ts

@@ -1,10 +1,12 @@
 import { RollCopy } from "./RollCopy.js";
 import { Version } from "./Version.js";
+import { Motivation } from "./Edit.js";
 import { DateAssignment } from "./Assumption.js";
-import { Editor, Person, Place } from "./Agent.js";
+import { Editor, Person, Place, Software } from "./Agent.js";
 /**
- * This type describes the creation of an edition,
- * i.e. the editor, publisher, and publication date.
+ * This type describes the creation of an edition: the editors,
+ * publisher and publication date, the editorial principles the edition
+ * follows, and the programs it was made with.
  * @see lrmoo:F28 Expression Creation
  * @category Format types
  */
@@ -28,6 +30,25 @@ export interface EditionCreation {
      * @see dcterms:date
      */
     publicationDate: Date;
+    /**
+     * The editorial principles the edition follows, by IRI: the
+     * published rules its stemma and its edits rest on, whether the
+     * editor applied them or a program did, such as that the same
+     * addition at the same place is not made twice independently
+     * (`stemmaRules`, `editRules`). Adopting a proposal names those it
+     * follows. An edition that names none leaves it out.
+     * @see crm:P33 used specific technique
+     */
+    principles?: string[];
+    /**
+     * The programs the edition was made with, each with its release:
+     * the release of this library that found its stemma and grouped its
+     * edits, which finds them again with the defaults it has. Adopting a
+     * proposal names it, and saving the edition does not, so that the
+     * release named is the one that found what the edition states.
+     * @see crm:P16 used specific object
+     */
+    software?: Software[];
 }
 /**
  * Describes the event of recording and documents
@@ -159,6 +180,14 @@ export interface Edition {
      * @see lrmoo:R75 incorporates
      */
     versions: Version[];
+    /**
+     * The editor's motivations, each a reason for musical changes in
+     * words, stated once and named by the edits of any version
+     * (`Edit.motivation`). The motivations the vocabulary publishes are
+     * named by IRI and not stated here (`musicalChange`,
+     * `technicalChange`).
+     */
+    motivations?: Motivation[];
 }
 /**
  * What an edition states about itself rather than about the copies and

package/lib/model/RollCopy.js

@@ -65,7 +65,7 @@ const exportedMeasurementsOf = (copy) => [copy.measurements.dimensions, copy.mea
  */
 export const measuringSoftwareOf = (copy) => {
     const named = exportedMeasurementsOf(copy)
-        .flatMap(value => value['@annotation']?.belief.reasons ?? [])
+        .flatMap(value => value['@annotation']?.belief?.reasons ?? [])
         .flatMap(reason => reason.type === 'measurement' ? reason.software ?? [] : []);
     return [...new Map(named.map(software => [`${software.name}\u0000${software.version ?? ''}`, software])).values()];
 };

package/lib/model/Version.d.ts

@@ -3,14 +3,7 @@ import { Concept } from "./Agent.js";
 import { ActorAssignment, Belief, Certainty, DateAssignment, ObjectAssumption, ReferenceAssumption } from "./Assumption.js";
 import { CollationTolerance } from "../collation/Collation.js";
 import { AnySymbol } from "./Symbol.js";
-import { WithId, WithNote, WithType } from "../shared/utils.js";
-/**
- * A motivation provides a reason or rationale for an editorial change.
- * Motivations are defined at the version level and referenced by edits.
- * @see crm:E33 Linguistic Object
- * @category Format types
- */
-export type Motivation = WithType<'motivation'> & WithId & WithNote;
+import { WithId } from "../shared/utils.js";
 /**
  * A derivation names the version another one was derived from, together
  * with the tolerance the two were collated at. How precisely the copies
@@ -148,10 +141,6 @@ export interface Version extends WithId {
      * @see reo:involvedEdit
      */
     edits?: Edit[];
-    /**
-     * A collection of motivations used in this version's edits.
-     */
-    motivations: Motivation[];
 }
 /**
  * The edits the version states, none where it leaves its text unstated.
@@ -170,7 +159,8 @@ export declare const insertedBy: (version: Readonly<Version>) => AnySymbol[];
 export declare const deletedBy: (version: Readonly<Version>) => string[];
 /**
  * The parents the version names, in the order of `basedOn`, each with the
- * certainty its derivation is held with and the belief it rests on.
+ * certainty its derivation is held with and the belief it rests on, where
+ * it carries one.
  * @category Versions and stemma
  */
 export declare const derivationsOf: (version: Readonly<Version>) => {

package/lib/model/Version.js

@@ -22,12 +22,17 @@ export const insertedBy = (version) => editsOf(version).flatMap(edit => edit.ins
 export const deletedBy = (version) => editsOf(version).flatMap(edit => edit.delete ?? []);
 /**
  * The parents the version names, in the order of `basedOn`, each with the
- * certainty its derivation is held with and the belief it rests on.
+ * certainty its derivation is held with and the belief it rests on, where
+ * it carries one.
  * @category Versions and stemma
  */
 export const derivationsOf = (version) => (version.basedOn ?? []).map(derivation => {
     const belief = derivation['@annotation']?.belief;
-    return { parent: idOf(derivation), certainty: certaintyOf(derivation), ...(belief && { belief }) };
+    return {
+        parent: idOf(derivation),
+        certainty: belief?.certainty ?? 'true',
+        ...(belief && { belief })
+    };
 });
 const rankOf = (derivation) => certainties.indexOf(certaintyOf(derivation));
 /**

package/lib/ops/collation.d.ts

@@ -9,15 +9,18 @@ import { EditionOp } from "./draft.js";
  * tolerance it was collated at and becomes the principal one; the
  * hypotheses the child stated beside its former one stay.
  *
- * The edits the child already stated are rewritten only as far as a
- * collation wrote them (`isCollationsOwn`). An editor's reading of the
+ * The edits the child already stated are rewritten only as far as they
+ * are the program's (`isCollationsOwn`). An editor's reading of the
  * difference between the two texts stays, and the symbols it speaks for
  * are left out of the collation, so that connecting the two again
  * neither doubles them nor silently drops what somebody established by
  * hand. An equivalence is the collation's own, since it is drawn from
  * the two systems' vocabularies rather than read off the paper, but one
  * drawn again over the very same symbols is kept as it stands, with its
- * identifier and whatever was written on it.
+ * identifier and whatever was written on it. An insertion or deletion
+ * drawn anew has the motivation its shape calls for
+ * (`motivationProposedFor`): the generic musical one, or the technical
+ * one, which an equivalence drawn anew always has.
  *
  * The child's own text is what it shows less what the parent hands
  * down, so that connecting two versions already connected collates the
@@ -40,7 +43,8 @@ export declare const collateSymbols: (versionId: string, symbolIds: readonly str
  * 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.
+ * version states the exchange, with the motivation its shape calls for
+ * (`motivationProposedFor`) where the version derives from another.
  *
  * This is the inverse of the hand-over a collation makes, and it is
  * what lets a derivation be collated a second time. A collated symbol