linked-rolls 0.74.0 → 0.76.0

package/README.md

@@ -132,6 +132,22 @@ edits the editor wrote, which hold their versions to what they insert
 and delete. Motivations, beliefs and versions known only from a
 recording remain the editor's to state.
 
+What the program concluded is stated plainly, as an edition states its
+stemma. The edition's creation names how it was found: the published
+rules the costs carry out among its principles (`stemmaRules`), and
+this release of the library among its software, which finds the
+stemma again with the defaults it has. A derivation the editor holds
+under a belief of their own, and an edit that says why it was made,
+stay as they are. Among the versions, derivations and edits, whatever
+carries neither a belief nor a motivation of the editor's is the
+program's.
+
+```ts
+const adopted = produce(edition, adoptStemma(proposal))
+adopted.creation.principles // ['https://welte225.org/rules#shared-addition', …]
+adopted.creation.software   // [{ name: 'linked-rolls', version: '0.76.0' }]
+```
+
 The costs are those with which the stemma of WM 225 comes out of its
 six copies. They were found by searching for such values, so they show
 that the stemma is consistent with these principles, not that the
@@ -139,24 +155,26 @@ principles confirm it.
 
 ## Proposing the edits
 
-What a version inserts and deletes can be grouped into edits and typed
-by their shape alone. `proposeEdits` reads a version's changes line by
-line, a latched function, a held one or a pitch, and never across a
-command both texts keep, so that an edit stays at one place. A function
-turned on and off again is one edit, typed an additional accent where
-the bar spells an accent so; a perforation put elsewhere is one move
-with the one it replaces, typed a shift, or shortened or prolonged
-where it begins about where the other did; overlapping notes are one
-edit, a note struck again or two tied; a held command standing for a
-latched pair is one recoding; a command the text makes no use of is a
-redundancy added or removed; cancels punched across lines at one place
-are one row. `adoptEdits` puts the proposal in place of the edits a
-collation wrote and nobody has motivated, and keeps the rest.
+What a version inserts and deletes can be grouped into edits, and the
+shape of each read off them alone. `proposeEdits` reads a version's
+changes line by line, a latched function, a held one or a pitch, and
+never across a command both texts keep, so that an edit stays at one
+place. A function turned on and off again is one edit, an additional
+accent where the bar spells an accent so; a perforation put elsewhere
+is one move with the one it replaces, a shift, or shortened or
+prolonged where it begins about where the other did; overlapping notes
+are one edit, a note struck again or two tied; a held command standing
+for a latched pair is one recoding; a command the text makes no use of
+is a redundancy added or removed; cancels punched across lines at one
+place are one row. `adoptEdits` puts the proposal in place of the
+program's edits, those that say nothing of why they were made or only
+that they are musical or technical changes, and keeps the rest. Its creation comes to
+name the rule that keeps an edit at one place among its principles.
 
 ```ts
 import { adoptEdits, adoptStemma, proposeEdits, proposeStemma } from 'linked-rolls'
 
-proposeEdits(edition, versionId)  // [{ insert, delete, editType, grouping }, …]
+proposeEdits(edition, versionId)  // [{ insert, delete, shape, grouping }, …]
 
 // The stemma and the edits of its versions, as one undo step
 const adopted = produce(edition, draft => {
@@ -165,12 +183,26 @@ const adopted = produce(edition, draft => {
 })
 ```
 
-Why an edit was made is not read off its shape, and neither is whether
-a shift corrects an error: what is left to the editor is the
-motivation. On WM 225 the proposal reproduces 370 of the 414 edits the
-editor wrote, from what each version changes, and all of their types
-but the shifts the editor took for corrected errors. From the copies
-alone, through the proposed stemma, it reproduces 326.
+Every change of a version that derives from another states a
+motivation, and the motivation says what kind of change it is
+(`kindOfChange`). A program states it from the shape of the change: a
+redundancy cleaned up or added, or a command recoded for another
+system, is a technical change (`technicalChange`), which the procedure
+of the version's creation explains; an added accent, a shift, a
+shortening or a prolongation is a musical change (`musicalChange`),
+under the rule that later versions are the more refined. The editor
+may say otherwise, and adopting the edits again keeps the kind an edit
+over the same changes states. The editor speculates on the musical
+changes only: a reason of their own, which the edition states once
+(`Edition.motivations`) and any version's edits name, takes the place of
+the generic musical motivation. The edits of a version that derives from none state its
+text, and no motivation.
+
+On WM 225 the proposal reproduces 601 of the 690 edits of the versions
+that derive from another, from what each version changes, and from the
+copies alone, through the proposed stemma, 554. It agrees with the
+editor on what kind of change an edit is but for two, each a reason the
+editor gives for what the program reads as a redundancy.
 
 ## Format
 
@@ -182,7 +214,10 @@ https://pfefferniels.github.io/linked-rolls/, to which the w3id.org
 identifiers redirect.
 
 Beliefs are written as JSON-LD-star annotations (`@annotation`), so you
-need a processor that supports JSON-LD-star to read them.
+need a processor that supports JSON-LD-star to read them. They are kept
+for what the editor doubts; everything else, the stemma and the edits a
+program found among it, is stated plainly and reaches RDF with any
+JSON-LD processor.
 
 ## Development
 
@@ -199,11 +234,12 @@ TypeScript 7 no longer has the compiler API it reads the source with.
 
 ## Releasing
 
-Raise the version in `package.json` and in `CITATION.cff`, there with
-the day as `date-released`, commit, and push a tag `v<version>`. The
-`publish.yml` workflow builds, tests and publishes to npm, then makes a
-GitHub release of the tag, which Zenodo archives with a DOI. A test fails
-while the two versions differ.
+Raise the version in `package.json`, in `CITATION.cff`, there with the
+day as `date-released`, and in `src/software.ts`, which names the release
+in the edition's creation when a proposal is adopted. Then commit, and push a tag
+`v<version>`. The `publish.yml` workflow builds, tests and publishes to
+npm, then makes a GitHub release of the tag, which Zenodo archives with
+a DOI. A test fails while the versions differ.
 
 ## About
 

package/lib/collation/Collation.d.ts

@@ -120,50 +120,20 @@ export type Collation = {
  */
 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.
+ * Whether the edit is the program's: one that a collation or a proposal
+ * wrote and nobody has explained, so that collating again or proposing
+ * the edits again may write it anew. It carries no belief and names no
+ * motivation of the editor's: only the kind of change it is, the generic
+ * musical or technical one a program states (`musicalChange`,
+ * `technicalChange`), or none.
  *
- * 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.
+ * Everything else is the editor's and stays: an edit that says why it
+ * was made, or that is held under a belief. A grouping of the editor's stays theirs once it says
+ * why; one that says nothing reads as the program's would.
  *
- * 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.
- * @category Collation and alignment
- */
-export declare const unchecked = "unchecked";
-/**
- * The version's statement of what the unchecked motivation means, to stand in its `motivations`.
- * @category Collation and alignment
- */
-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 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.
- *
- * 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 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.
+ * An exchange a collation draws again over the very same symbols is
+ * kept as it stands, with its identifier and whatever was written on
+ * it (`connectVersions`).
  * @category Collation and alignment
  */
 export declare const isCollationsOwn: (edit: Readonly<Edit>) => boolean;

package/lib/collation/Collation.js

@@ -1,3 +1,4 @@
+import { musicalChange, technicalChange } from "../model/Edit.js";
 import { keyOf } from "../systems/TrackerBar.js";
 import { distance, mm } from "../model/Quantity.js";
 import { partitionPoint } from "../shared/sorted.js";
@@ -106,56 +107,22 @@ export const collationsOf = (own, inherited, locate, tolerance = defaultCollatio
         .sort((a, b) => a.index - b.index)
         .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 = 'recoding';
 /**
- * The motivation a collation writes on what it makes, saying that
- * nobody has read it yet.
+ * Whether the edit is the program's: one that a collation or a proposal
+ * wrote and nobody has explained, so that collating again or proposing
+ * the edits again may write it anew. It carries no belief and names no
+ * motivation of the editor's: only the kind of change it is, the generic
+ * musical or technical one a program states (`musicalChange`,
+ * `technicalChange`), or none.
  *
- * 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.
+ * Everything else is the editor's and stays: an edit that says why it
+ * was made, or that is held under a belief. A grouping of the editor's stays theirs once it says
+ * why; one that says nothing reads as the program's would.
  *
- * 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.
+ * An exchange a collation draws again over the very same symbols is
+ * kept as it stands, with its identifier and whatever was written on
+ * it (`connectVersions`).
  * @category Collation and alignment
  */
-export const unchecked = 'unchecked';
-/**
- * The version's statement of what the unchecked motivation means, to stand in its `motivations`.
- * @category Collation and alignment
- */
-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 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.
- *
- * 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 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.
- * @category Collation and alignment
- */
-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);
+export const isCollationsOwn = (edit) => edit['@annotation'] === undefined
+    && (edit.motivation === undefined || edit.motivation === musicalChange || edit.motivation === technicalChange);

package/lib/filiation/adoption.d.ts

@@ -15,6 +15,12 @@ export interface Adoption {
     removed: string[];
     /** The edits the editor wrote that the adoption leaves out, and why. */
     dropped: Unpinned[];
+    /**
+     * The published rules the proposal follows, as far as its costs and
+     * settings carry them out, which the edition's creation comes to
+     * name among its principles.
+     */
+    principles: string[];
 }
 /**
  * What adopting the proposal makes of the edition's stemma, worked out
@@ -28,20 +34,33 @@ export interface Adoption {
  * the edits the editor wrote that the proposal keeps, as they are, and
  * one edit for each further reading it inserts or deletes, or for each
  * recoding. An edit the version stated before over the very same
- * readings is taken over with its id and what was written on it; the
- * others are new and marked unchecked, as a collation marks its own.
+ * readings is taken over with its id and what was written on it, the
+ * kind of change it states among it, which the editor may have said
+ * otherwise than the program read it; the others are new. An edit that
+ * states no kind has the motivation the shape of the change calls for
+ * (`motivationProposedFor`): the generic musical one, whose reason is
+ * left to the editor, or the technical one, which a recoding always has.
+ * The edits of the root state its text, and no kind of change.
  *
  * A reading that stands for a symbol of the edition keeps that symbol's
  * id and whatever it states beside its carriers. A version of the edition
  * nothing stands for goes, unless it states no edits and derives from a
  * version that stays, as a version known only from a recording does.
+ *
+ * What the program concluded is stated plainly, as an edition states its
+ * stemma. A derivation the editor holds under a belief of their own
+ * stays as it is, and so does every edit that says why it was made.
  * @category Filiation
  */
 export declare const adoptionOf: (edition: Edition, proposal: StemmaProposal) => Adoption;
 /**
  * Puts the proposed stemma in place of the edition's, as `adoptionOf`
- * describes, and takes back a copy's statement that it carries a version
- * that goes. One operation, and so one undo step.
+ * describes, and takes back a copy's statement that it carries a
+ * version that goes. The edition's creation comes to name the rules the
+ * proposal follows among its principles, in place of those of the
+ * stemma it no longer follows, and this release of the library among its
+ * software, which finds the stemma again with the defaults it has. One
+ * operation, and so one undo step.
  * @category Operations
  */
 export declare const adoptStemma: (proposal: StemmaProposal) => EditionOp;

package/lib/filiation/adoption.js

@@ -1,21 +1,50 @@
 /** Taking a proposed stemma into the edition, as one operation. */
 import { v5 } from "uuid";
+import { musicalChange, technicalChange } from "../model/Edit.js";
+import { isCollationsOwn } from "../collation/Collation.js";
 import { assignReference, idOf } from "../model/Assumption.js";
 import { derivesFrom, editsOf, insertedBy, principalDerivationOf } from "../model/Version.js";
 import { systemOf } from "../systems/TrackerBar.js";
-import { unchecked } from "../collation/Collation.js";
 import { versionIn } from "../lookup/lookup.js";
-import { declaring, reading } from "../ops/draft.js";
+import { reading } from "../ops/draft.js";
 import { dropStatements } from "../ops/copies.js";
 import { barNamed } from "./systems.js";
+import { madeWith, stemmaRules } from "./record.js";
+import { motivationOfChanges, proposedMotivations } from "./edits.js";
 /** The namespace the names of adopted versions and edits are minted in, so that adopting again gives them again. */
 const ADOPTED = '6f1d2c8e-93a4-4f0b-b8a1-2f4c5d7e9a31';
+/** The rules the proposal followed, as far as its costs and settings carry them out. */
+const rulesOf = (proposal) => [
+    ...(proposal.costs.gain > 1 ? [stemmaRules.sharedAddition] : []),
+    ...(proposal.costs.redundantLoss < 1 ? [stemmaRules.independentCleanup] : []),
+    ...(proposal.costs.transferLoss < 1 ? [stemmaRules.recutLoss] : []),
+    ...(Number.isFinite(proposal.costs.copyDeviation) ? [stemmaRules.copyDeviation] : []),
+    ...(proposal.costs.lostState > 0 ? [stemmaRules.lostStates] : []),
+    ...(proposal.sameText >= 0 ? [stemmaRules.oneText] : []),
+    stemmaRules.refinement,
+    stemmaRules.noContamination
+];
 const exchangeKey = (inserted, deleted) => `${[...inserted].sort().join(',')}/${[...deleted].sort().join(',')}`;
 /** The carriers of the reading, keeping what the edition states of those it held already. */
 const carriersOf = (reading, stated) => {
     const known = new Map(stated.map(carrier => [idOf(carrier), carrier]));
     return reading.carriers.map(id => known.get(id) ?? assignReference(id));
 };
+/** The version with its edits stating its text: no kind of change, though any reason the editor gave. */
+const withoutKinds = (version) => {
+    const kindOnly = (edit) => edit.motivation === musicalChange || edit.motivation === technicalChange;
+    if (!editsOf(version).some(kindOnly))
+        return version;
+    return {
+        ...version,
+        edits: editsOf(version).map(edit => {
+            if (!kindOnly(edit))
+                return edit;
+            const { motivation: _kind, ...text } = edit;
+            return text;
+        })
+    };
+};
 /**
  * What adopting the proposal makes of the edition's stemma, worked out
  * without changing it, so that it can be looked at first.
@@ -28,16 +57,26 @@ const carriersOf = (reading, stated) => {
  * the edits the editor wrote that the proposal keeps, as they are, and
  * one edit for each further reading it inserts or deletes, or for each
  * recoding. An edit the version stated before over the very same
- * readings is taken over with its id and what was written on it; the
- * others are new and marked unchecked, as a collation marks its own.
+ * readings is taken over with its id and what was written on it, the
+ * kind of change it states among it, which the editor may have said
+ * otherwise than the program read it; the others are new. An edit that
+ * states no kind has the motivation the shape of the change calls for
+ * (`motivationProposedFor`): the generic musical one, whose reason is
+ * left to the editor, or the technical one, which a recoding always has.
+ * The edits of the root state its text, and no kind of change.
  *
  * A reading that stands for a symbol of the edition keeps that symbol's
  * id and whatever it states beside its carriers. A version of the edition
  * nothing stands for goes, unless it states no edits and derives from a
  * version that stays, as a version known only from a recording does.
+ *
+ * What the program concluded is stated plainly, as an edition states its
+ * stemma. A derivation the editor holds under a belief of their own
+ * stays as it is, and so does every edit that says why it was made.
  * @category Filiation
  */
 export const adoptionOf = (edition, proposal) => {
+    const fresh = new Set();
     const readingOf = new Map(proposal.collation.readings.map(reading => [reading.id, reading]));
     const symbolIdOf = (reading) => proposal.symbols[reading] ?? reading;
     const existing = new Map(edition.versions.flatMap(insertedBy).map(symbol => [symbol.id, symbol]));
@@ -112,16 +151,15 @@ export const adoptionOf = (edition, proposal) => {
             const key = exchangeKey(inserted, deleted);
             const same = statedBefore.get(key);
             const insert = inserts.map(reading => symbolOf(reading, proposed.id));
-            if (same)
-                return { ...same, ...(insert.length > 0 && { insert }), ...(deleted.length > 0 && { delete: deleted }) };
-            return {
-                type: 'edit',
-                id: v5(`edit|${id}|${key}`, ADOPTED),
-                ...(recoding && { editType: 'recoding' }),
-                motivation: unchecked,
-                ...(insert.length > 0 && { insert }),
-                ...(deleted.length > 0 && { delete: deleted })
-            };
+            const exchange = { ...(insert.length > 0 && { insert }), ...(deleted.length > 0 && { delete: deleted }) };
+            // An edit over the same changes stays, with the kind of change it states, which the editor may have said.
+            if (same && (!isCollationsOwn(same) || same.motivation !== undefined))
+                return { ...same, ...exchange };
+            const made = { ...(same ?? { type: 'edit', id: v5(`edit|${id}|${key}`, ADOPTED) }), ...(recoding && { motivation: technicalChange }), ...exchange };
+            // A recoding is technical; the motivation of any other change is read off its shape below.
+            if (!recoding)
+                fresh.add(made.id);
+            return made;
         };
         // A recoding an edit of the editor's cuts into is stated reading by reading.
         const whole = proposed.recodings.filter(recoding => ![...recoding.by.map(reading => symbolIdAt(reading, proposed.id)), ...recoding.replaced.map(reading => inheritedAt(reading, proposed.id))]
@@ -133,11 +171,11 @@ export const adoptionOf = (edition, proposal) => {
             ...proposed.inserts.filter(reading => !recoded.has(reading)).map(reading => made([reading], [], false)),
             ...proposed.deletes.filter(reading => !recoded.has(reading)).map(reading => made([], [reading], false))
         ].filter((edit) => edit !== undefined);
+        // A derivation stated before is kept with what it states, a belief of the editor's among it.
         const parent = proposed.parent ? ids.get(proposed.parent) : undefined;
         const principal = before && principalDerivationOf(before);
-        const derivation = parent === undefined
-            ? undefined
-            : principal && idOf(principal) === parent ? principal : assignReference(parent);
+        const same = principal && idOf(principal) === parent ? principal : undefined;
+        const derivation = parent === undefined ? undefined : same ?? assignReference(parent);
         const hypotheses = (before?.basedOn ?? [])
             .filter(other => other !== principal && staying.has(idOf(other)) && idOf(other) !== parent);
         const basedOn = [...(derivation ? [derivation] : []), ...hypotheses];
@@ -150,8 +188,7 @@ export const adoptionOf = (edition, proposal) => {
             id,
             system,
             ...(basedOn.length > 0 && { basedOn }),
-            edits,
-            motivations: declaring(before?.motivations ?? [], edits)
+            edits
         };
     });
     // A hypothesis may not name a version that now derives from the one stating it.
@@ -171,19 +208,40 @@ export const adoptionOf = (edition, proposal) => {
     // The edition's order where a version stays, the new ones after it.
     const rank = new Map(edition.versions.map((version, index) => [version.id, index]));
     const ordered = [...pruned, ...statedOnly].sort((a, b) => (rank.get(a.id) ?? Infinity) - (rank.get(b.id) ?? Infinity));
-    return { versions: ordered, ids: Object.fromEntries(ids), removed, dropped: proposal.unpinned };
+    // A new edit's motivation follows from the shape of the change, read in the stemma adopted.
+    const adopted = { ...edition, versions: ordered };
+    const motivated = ordered.map(version => {
+        if (!principalDerivationOf(version))
+            return withoutKinds(version);
+        if (!editsOf(version).some(edit => fresh.has(edit.id)))
+            return version;
+        const motivations = proposedMotivations(adopted, version.id);
+        return {
+            ...version,
+            edits: editsOf(version).map(edit => fresh.has(edit.id)
+                ? { ...edit, motivation: motivationOfChanges(motivations, [...(edit.insert ?? []).map(symbol => symbol.id), ...(edit.delete ?? [])]) }
+                : edit)
+        };
+    });
+    return { versions: motivated, ids: Object.fromEntries(ids), removed, dropped: proposal.unpinned, principles: rulesOf(proposal) };
 };
 /**
  * Puts the proposed stemma in place of the edition's, as `adoptionOf`
- * describes, and takes back a copy's statement that it carries a version
- * that goes. One operation, and so one undo step.
+ * describes, and takes back a copy's statement that it carries a
+ * version that goes. The edition's creation comes to name the rules the
+ * proposal follows among its principles, in place of those of the
+ * stemma it no longer follows, and this release of the library among its
+ * software, which finds the stemma again with the defaults it has. One
+ * operation, and so one undo step.
  * @category Operations
  */
 export const adoptStemma = (proposal) => reading(edition => {
-    const { versions, removed } = adoptionOf(edition, proposal);
+    const { versions, removed, principles } = adoptionOf(edition, proposal);
     const gone = new Set(removed);
+    const creation = madeWith(edition.creation, principles, Object.values(stemmaRules));
     return draft => {
         draft.versions = versions;
         draft.copies.forEach(copy => dropStatements(copy, statement => gone.has(idOf(statement))));
+        draft.creation = creation;
     };
 });

package/lib/filiation/edits.d.ts

@@ -1,5 +1,5 @@
 import { Edition } from "../model/Edition.js";
-import { Edit, EditType } from "../model/Edit.js";
+import { EditShape } from "../model/Edit.js";
 import { Millimeters } from "../model/Quantity.js";
 import { EditionOp } from "../ops/draft.js";
 /**
@@ -69,8 +69,8 @@ export interface ProposedEdit {
     insert: string[];
     /** The ids of the symbols it deletes, in the order of their places. */
     delete: string[];
-    /** The kind of change, where its shape says. */
-    editType?: EditType;
+    /** The shape of the change, where it takes one the program knows. */
+    shape?: EditShape;
     grouping: EditGrouping;
 }
 /**
@@ -94,8 +94,8 @@ export interface ProposedEdit {
  * punched across three lines or more at one place are one edit, as a
  * cancel row is.
  *
- * The type is read off the shape: a pair the bar spells an accent with is
- * an additional accent, as is a note set off from its chord by a few
+ * The shape is read off the group: a pair the bar spells an accent with
+ * is an additional accent, as is a note set off from its chord by a few
  * millimetres where the version puts an accent's On; a perforation put
  * elsewhere is a shift, or where it begins about where the other did,
  * shortened or prolonged; a note struck again is shortened, two tied
@@ -110,25 +110,41 @@ export interface ProposedEdit {
  */
 export declare const proposeEdits: (edition: Edition, versionId: string, options?: EditOptions) => ProposedEdit[];
 /**
- * Whether the edit is left for a proposal to group again: one a
- * collation or an adoption wrote, that nobody has given a motivation.
+ * The motivation a program states for each change the version makes,
+ * by the id of the symbol it inserts or deletes: the one the shape of
+ * the proposed edit it belongs to calls for (`motivationProposedFor`),
+ * musical or technical. A version that derives from none makes no
+ * change, and its symbols are given none.
  * @category Filiation
  */
-export declare const isRegroupable: (edit: Readonly<Edit>) => boolean;
+export declare const proposedMotivations: (edition: Edition, versionId: string, options?: EditOptions) => ReadonlyMap<string, string>;
 /**
- * Puts the proposed edits (`proposeEdits`) in place of those of the
- * versions that a collation or an adoption wrote and nobody has given a
- * motivation, every version but the root where none are named. An edit
- * someone motivated, typed beyond what a collation types, or held under a
- * belief stays as it is, and what a proposed edit shares with it stands
- * symbol by symbol beside it. An edit stated already over the very same
- * symbols as a proposed one is kept with its id and what was written on
- * it, the proposed type filled in where it states none; the others are
- * new, with ids that adopting again gives again, and marked unchecked,
- * so that what is left to the editor is to say why.
+ * The motivation a program states for an edit making these changes:
+ * the generic musical one where any of them is a musical change, or one
+ * the proposal does not see, and the technical one where all are
+ * technical.
+ */
+export declare const motivationOfChanges: (motivations: ReadonlyMap<string, string>, symbolIds: readonly string[]) => string;
+/**
+ * Puts the proposed edits (`proposeEdits`) in place of the program's
+ * edits of the versions, every version but the root where none are
+ * named: those that say nothing of why they were made, or only that they
+ * are musical or technical changes (`isCollationsOwn`). An edit with a
+ * motivation of the editor's or held under a belief stays as it is, and
+ * what a proposed edit shares with it stands symbol by symbol beside it.
+ * An edit stated already over the very same symbols as a proposed one
+ * is kept with its id and the kind of change it states, which the
+ * editor may have said otherwise than the program read it; the others
+ * are new, with ids that adopting again gives again. An edit that
+ * states no kind has the motivation its shape calls for
+ * (`motivationProposedFor`): the generic musical one for a musical
+ * change, whose reason is left to the editor, and the technical one for
+ * a technical change.
  *
  * Applied on the same draft after `adoptStemma`, it proposes the edits of
- * the stemma adopted, as one undo step.
+ * the stemma adopted, as one undo step. The edition's creation comes to
+ * name the rule that keeps an edit at one place among its principles,
+ * and this release among its software.
  * @category Operations
  */
 export declare const adoptEdits: (versionIds?: readonly string[], options?: EditOptions) => EditionOp;