linked-rolls 0.75.0 → 0.76.0

package/lib/model/Edit.d.ts

@@ -1,14 +1,66 @@
 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. Each is read off the
- * shape of the change, as `proposeEdits` reads it. Whether a change
- * corrects an error is not: it is a reason for the change, and stated as
- * its motivation (`correctedError`).
+ * 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,
@@ -17,18 +69,24 @@ export declare const editTypes: readonly ['additional-accent', 'add-redundancy',
  */
 'recoding', 'shift', 'shorten', 'prolong'];
 /**
- * The type of editorial change applied to a symbol or set of symbols.
- * Classifies the shape of the edit, e.g. whether it adds an accent,
- * shifts a note, or shortens/prolongs a perforation. Why it was made is
- * its motivation.
+ * 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 strengthen an 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.
@@ -42,13 +100,10 @@ export type EditType = typeof editTypes[number];
 export interface Edit extends WithId, Assumption {
     type: 'edit';
     /**
-     * The type of editorial change, as its shape shows it (e.g. 'shift', '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,11 +1,47 @@
 /**
- * The types of editorial change an edit may state. Each is read off the
- * shape of the change, as `proposeEdits` reads it. Whether a change
- * corrects an error is not: it is a reason for the change, and stated as
- * its motivation (`correctedError`).
+ * 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',
@@ -20,6 +56,17 @@ export const editTypes = [
     '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 { DateAssignment, PropositionSet } from "./Assumption.js";
-import { Editor, Person, Place } from "./Agent.js";
+import { Motivation } from "./Edit.js";
+import { DateAssignment } from "./Assumption.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
@@ -160,14 +181,13 @@ export interface Edition {
      */
     versions: Version[];
     /**
-     * The statements the edition holds together under one belief, each
-     * set with the reasoning that concluded it: a stemma a program
-     * proposed and the editor adopted, the edits it grouped. A statement
-     * belongs to a set by naming it in its annotation. An edition that
-     * holds no such set leaves it out.
-     * @see crminf:I4 Proposition Set
+     * 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`).
      */
-    propositionSets?: PropositionSet[];
+    motivations?: Motivation[];
 }
 /**
  * What an edition states about itself rather than about the copies and

package/lib/model/Version.d.ts

@@ -1,36 +1,9 @@
 import { Edit } from "./Edit.js";
 import { Concept } from "./Agent.js";
-import { ActorAssignment, Belief, Certainty, DateAssignment, ObjectAssumption, PropositionSet, ReferenceAssumption } from "./Assumption.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;
-/**
- * The motivation of an edit that puts right what the version it derives
- * from got wrong: a perforation put in the wrong place, struck or left
- * out. Whether a change corrects an error is not read off its shape, as
- * its type is, but is a reason for it, and so the editor's to give.
- * The edit types held it once, and a document written then is read with
- * this motivation in place of that type.
- * @category Versions and stemma
- */
-export declare const correctedError = "corrected-error";
-/**
- * The version's statement of what the motivation of a corrected error
- * means, to stand in its `motivations`.
- * @category Versions and stemma
- */
-export declare const correctedErrorMotivation: {
-    readonly type: 'motivation';
-    readonly id: "corrected-error";
-    readonly note: 'Puts right an error of the version it derives from.';
-};
+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
@@ -168,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.
@@ -190,19 +159,14 @@ 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. Given
- * the edition, a derivation that belongs to a proposition set, as an
- * adopted stemma's do, is read with the belief of the set, and names it
- * (`propositionSet`); without it, only a belief of its own is read.
+ * 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>, edition?: {
-    propositionSets?: readonly PropositionSet[];
-}) => {
+export declare const derivationsOf: (version: Readonly<Version>) => {
     parent: string;
     certainty: Certainty;
     belief?: Belief;
-    propositionSet?: string;
 }[];
 /**
  * The derivation the version's text is read against: the first of those

package/lib/model/Version.js

@@ -1,25 +1,5 @@
-import { beliefIn, certainties, certaintyOf, idOf } from "./Assumption.js";
+import { certainties, certaintyOf, idOf } from "./Assumption.js";
 import { defaultCollationTolerance } from "../collation/Collation.js";
-/**
- * The motivation of an edit that puts right what the version it derives
- * from got wrong: a perforation put in the wrong place, struck or left
- * out. Whether a change corrects an error is not read off its shape, as
- * its type is, but is a reason for it, and so the editor's to give.
- * The edit types held it once, and a document written then is read with
- * this motivation in place of that type.
- * @category Versions and stemma
- */
-export const correctedError = 'corrected-error';
-/**
- * The version's statement of what the motivation of a corrected error
- * means, to stand in its `motivations`.
- * @category Versions and stemma
- */
-export const correctedErrorMotivation = {
-    type: 'motivation',
-    id: correctedError,
-    note: 'Puts right an error of the version it derives from.'
-};
 /**
  * The tolerance the derivation was collated at, or the default where it states none.
  * @category Collation and alignment
@@ -42,20 +22,16 @@ 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. Given
- * the edition, a derivation that belongs to a proposition set, as an
- * adopted stemma's do, is read with the belief of the set, and names it
- * (`propositionSet`); without it, only a belief of its own is read.
+ * certainty its derivation is held with and the belief it rests on, where
+ * it carries one.
  * @category Versions and stemma
  */
-export const derivationsOf = (version, edition = {}) => (version.basedOn ?? []).map(derivation => {
-    const belief = beliefIn(edition, derivation);
-    const set = derivation['@annotation']?.belief === undefined ? derivation['@annotation']?.id : undefined;
+export const derivationsOf = (version) => (version.basedOn ?? []).map(derivation => {
+    const belief = derivation['@annotation']?.belief;
     return {
         parent: idOf(derivation),
         certainty: belief?.certainty ?? 'true',
-        ...(belief && { belief }),
-        ...(set !== undefined && { propositionSet: set })
+        ...(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

package/lib/ops/collation.js

@@ -1,14 +1,18 @@
 import { v4 } from "uuid";
 import { getAt, pathIn } from "../lookup/paths.js";
-import { collationsOf, defaultCollationTolerance, isCollationsOwn, unchecked } from "../collation/Collation.js";
+import { collationsOf, defaultCollationTolerance, isCollationsOwn } from "../collation/Collation.js";
+import { motivationProposedFor, technicalChange } from "../model/Edit.js";
 import { collationToleranceOf, derivesFrom, editsOf, insertedBy, principalDerivationOf } from "../model/Version.js";
 import { substitutionsBetween } from "../collation/substitution.js";
 import { trackerBarOf } from "../systems/index.js";
 import { assignReference, idOf } from "../model/Assumption.js";
-import { noChange, onVersion, insertion, deletion, asUnchecked, declaring, dropInsertions, reading } from "./draft.js";
+import { noChange, onVersion, insertion, deletion, dropInsertions, reading } from "./draft.js";
 import { hypothesesBeside } from "./versions.js";
+import { shapeOf } from "./edits.js";
+import { predecessorOf } from "../analysis/stemma.js";
 import { placeOf, snapshotOf } from "../analysis/text.js";
 import { copyOfFeature, versionIn } from "../lookup/lookup.js";
+import { motivationOfChanges, proposedMotivations } from "../filiation/edits.js";
 /** The carriers of each collated symbol pass to its counterpart. */
 const handOverCarriers = (edition, draft, collations) => collations.forEach(({ symbol, counterpart }) => {
     const path = pathIn(edition, counterpart.id);
@@ -43,15 +47,18 @@ const byExchange = (edits) => new Map(edits.map(edit => [exchangeKey((edit.inser
  * 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
@@ -101,31 +108,36 @@ export const connectVersions = (childId, parentId, tolerance = defaultCollationT
         return alreadyStated.get(exchangeKey(inserted, deleted)) ?? {
             type: 'edit',
             id: v4(),
-            editType: 'recoding',
-            motivation: unchecked,
+            motivation: technicalChange,
             insert: [...by],
             delete: deleted
         };
     };
-    const edits = [
-        ...established,
-        ...substituted.map(equivalence),
-        ...own.filter(symbol => !collated.has(symbol.id) && !paired.has(symbol.id)).map(insertion).map(asUnchecked),
+    const bare = [
+        ...own.filter(symbol => !collated.has(symbol.id) && !paired.has(symbol.id)).map(insertion),
         ...inherited
             .filter(symbol => !matched.has(symbol.id) && !paired.has(symbol.id))
-            .map(symbol => asUnchecked(deletion(symbol.id)))
+            .map(symbol => deletion(symbol.id))
     ];
+    const drawn = [...established, ...substituted.map(equivalence), ...bare];
     // Read off the child as it stands, since once its edits are written a
     // reading of it would copy them all.
-    const motivations = declaring(child?.motivations ?? [], edits);
     const basedOn = [
         { ...assignReference(parentId), collationTolerance: tolerance },
         ...(child ? hypothesesBeside(child, parentId) : [])
     ];
+    // What kind of change an insertion or a deletion is depends on what it stands among.
+    const connected = { ...edition, versions: edition.versions.map(version => version.id === childId ? { ...version, edits: drawn, basedOn } : version) };
+    const motivations = proposedMotivations(connected, childId);
+    const anew = new Set(bare.map(edit => edit.id));
+    const edits = drawn.map(edit => {
+        if (!anew.has(edit.id))
+            return edit;
+        return { ...edit, motivation: motivationOfChanges(motivations, [...(edit.insert ?? []).map(symbol => symbol.id), ...(edit.delete ?? [])]) };
+    });
     return onVersion(childId, (version, draft) => {
         handOverCarriers(edition, draft, collations);
         version.edits = edits;
-        version.motivations = motivations;
         version.basedOn = basedOn;
     });
 });
@@ -184,7 +196,8 @@ const sharedWith = (edition, symbol, copies) => {
  * 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
@@ -217,14 +230,18 @@ export const separateReadings = (versionId, copies, symbolIds) => reading(editio
         return noChange;
     const inserted = new Set(insertedBy(version).map(symbol => symbol.id));
     const stated = editsOf(version);
-    const separations = shared.map(({ symbol, mine }) => ({
-        type: 'edit',
-        id: v4(),
-        insert: [readingOf(symbol, [...mine])],
-        // A symbol the version inserts itself stays where it is, minus
-        // the carriers that leave it. Only one it inherits is exchanged.
-        ...(inserted.has(symbol.id) ? {} : { delete: [symbol.id] })
-    }));
+    const derived = predecessorOf(edition, versionId) !== undefined;
+    const separations = shared.map(({ symbol, mine }) => {
+        const separation = {
+            type: 'edit',
+            id: v4(),
+            insert: [readingOf(symbol, [...mine])],
+            // A symbol the version inserts itself stays where it is, minus
+            // the carriers that leave it. Only one it inherits is exchanged.
+            ...(inserted.has(symbol.id) ? {} : { delete: [symbol.id] })
+        };
+        return derived ? { ...separation, motivation: motivationProposedFor(shapeOf(edition, versionId, separation)) } : separation;
+    });
     return onVersion(versionId, (version, draft) => {
         shared.forEach(({ symbol, theirs }) => {
             const path = pathIn(edition, symbol.id);

package/lib/ops/copies.js

@@ -21,8 +21,7 @@ export const createVersion = (copy) => draft => {
     draft.versions.push({
         id: v4(),
         system: systemOf(bar),
-        edits: asSymbols(featuresOf(copy), bar).map(insertion),
-        motivations: []
+        edits: asSymbols(featuresOf(copy), bar).map(insertion)
     });
 };
 /**

package/lib/ops/draft.d.ts

@@ -3,7 +3,7 @@ import { Draft } from "immer";
 import { Edition } from "../model/Edition.js";
 import { AnySymbol } from "../model/Symbol.js";
 import { Edit } from "../model/Edit.js";
-import { Motivation, Version } from "../model/Version.js";
+import { Version } from "../model/Version.js";
 import { RollCopy } from "../model/RollCopy.js";
 import { Belief, ReferenceAssumption } from "../model/Assumption.js";
 import { FeatureOrPatch } from "../model/Feature.js";
@@ -42,14 +42,6 @@ export declare const droppedIds: (before: readonly WithId[], after: readonly Wit
 export type Ids = ReadonlySet<string>;
 export declare const insertion: (symbol: AnySymbol) => Edit;
 export declare const deletion: (symbolId: string) => Edit;
-/** The edit as a collation leaves it: made by rule, and not yet read by anybody. */
-export declare const asUnchecked: (edit: Edit) => Edit;
-/**
- * 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.
- */
-export declare const declaring: (motivations: Motivation[], edits: readonly Edit[]) => Motivation[];
 export declare const insertedIn: (versions: readonly Version[]) => AnySymbol[];
 /** The edits with the change applied, less those it emptied; the very same array where it changed none. */
 export declare const edited: (edits: Edit[], change: (edit: Edit) => Edit) => Edit[];

package/lib/ops/draft.js

@@ -1,7 +1,6 @@
 /** What the operations are built from: the type of an operation, how one finds what it writes to on the draft, and the edits it writes. */
 import { isDraft } from "immer";
 import { v4 } from "uuid";
-import { unchecked, uncheckedMotivation } from "../collation/Collation.js";
 import { insertedBy } from "../model/Version.js";
 import { featuresOf } from "../model/RollCopy.js";
 import { assignReference } from "../model/Assumption.js";
@@ -45,17 +44,6 @@ export const droppedIds = (before, after) => {
 };
 export const insertion = (symbol) => ({ type: 'edit', id: v4(), insert: [symbol] });
 export 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. */
-export 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.
- */
-export 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;
 export const insertedIn = (versions) => versions.flatMap(insertedBy);
 /** The edits with the change applied, less those it emptied; the very same array where it changed none. */

package/lib/ops/edits.d.ts

@@ -1,15 +1,30 @@
-import { Edit } from "../model/Edit.js";
+import { Edit, EditShape } from "../model/Edit.js";
 import { EditionOp } from "./draft.js";
+import { Edition } from "../model/Edition.js";
+/**
+ * A guess at the shape of an edit, from the symbols it exchanges and
+ * from the systems the version and the one it is based on are coded
+ * for, or nothing where it takes no shape the guess knows. It looks at
+ * the edit alone: a single expression deleted is taken for a redundancy
+ * removed, which `proposeEdits` checks against the text.
+ * @category Lookups
+ */
+export declare const shapeOf: (edition: Edition, versionId: string, edit: Readonly<Edit>) => EditShape | undefined;
 /**
  * Replaces the edits with a single one carrying all their insertions
- * and deletions, classified by a guess at what the exchange does, where
- * its shape says. The edit is the editor's: it belongs to no proposition
- * set a program's run concluded, as one of those merged may have.
+ * and deletions. It keeps the first motivation of the editor's that any
+ * of them states, and where none does, it has the one its shape calls
+ * for (`motivationProposedFor`), so that a merge says it is a musical
+ * or a technical change, unless the version derives from none. A
+ * grouping that says no more is the program's by rule
+ * (`isCollationsOwn`), until the editor says why it was made.
  * @category Operations
  */
 export declare const mergeEdits: (versionId: string, toMerge: readonly Edit[]) => EditionOp;
 /**
- * Replaces the edit with one edit per inserted and one per deleted symbol.
+ * Replaces the edit with one edit per inserted and one per deleted
+ * symbol. Each part keeps the motivation of the edit, since splitting
+ * an edit does not change why it was made.
  * @category Operations
  */
 export declare const splitEdit: (versionId: string, toSplit: Edit) => EditionOp;