linked-rolls 0.56.0 → 0.58.0

package/lib/ops/beliefs.js

@@ -0,0 +1,31 @@
+import { v4 } from "uuid";
+import { getAt } from "../view/EditionView.js";
+const onAssumptionAt = (path, op) => draft => {
+    const assumption = getAt(path, draft);
+    if (assumption)
+        op(assumption);
+};
+const onBeliefAt = (path, op) => onAssumptionAt(path, assumption => {
+    const belief = assumption['@annotation']?.belief;
+    if (belief)
+        op(belief);
+});
+/** Annotates the assumption at the path with a belief held true, for reasons to be added. */
+export const createBelief = (path) => onAssumptionAt(path, assumption => {
+    assumption['@annotation'] = {
+        id: v4(),
+        belief: { type: 'belief', id: v4(), certainty: 'true', reasons: [] }
+    };
+});
+export const clearBelief = (path) => onAssumptionAt(path, assumption => {
+    delete assumption['@annotation'];
+});
+export const setCertainty = (path, certainty) => onBeliefAt(path, belief => {
+    belief.certainty = certainty;
+});
+export const addReason = (path, reason) => onBeliefAt(path, belief => {
+    belief.reasons.push(reason);
+});
+export const removeReason = (path, index) => onBeliefAt(path, belief => {
+    belief.reasons.splice(index, 1);
+});

package/lib/ops/collation.d.ts

@@ -0,0 +1,62 @@
+import { EditionView } from "../view/EditionView.js";
+import { CollationTolerance } from "../collation/Collation.js";
+import { ObjectAssumption } from "../model/Assumption.js";
+import { EditionOp } from "./draft.js";
+/**
+ * Bases the child on the parent. A symbol of the child that collates
+ * with one the parent hands down adds its carriers to that symbol; the
+ * rest become the child's insertions, and what the parent hands down
+ * and the child lacks becomes its deletions. The derivation states the
+ * 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
+ * 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.
+ *
+ * The child's own text is what it shows less what the parent hands
+ * down, so that connecting two versions already connected collates the
+ * child's symbols and not the parent's with themselves.
+ *
+ * A version is based on itself or on one of its own descendants in no
+ * statement, since the stemma would loop; asked for that, nothing
+ * changes.
+ */
+export declare const connectVersions: (given: EditionView, childId: string, parentId: string, tolerance?: ObjectAssumption<CollationTolerance>) => EditionOp;
+/**
+ * Folds the version's own symbols into those it inherits and collates
+ * with: the carriers pass over, and the insertions go. Collates at the
+ * tolerance of the derivation, where the caller names none.
+ */
+export declare const collateSymbols: (given: EditionView, versionId: string, symbolIds: readonly string[], tolerance?: CollationTolerance) => EditionOp;
+/**
+ * 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.
+ *
+ * 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
+ * is one symbol carrying every copy that reads it, so nothing else
+ * takes the two readings apart again, and without that a tolerance
+ * arrived at after the fact could never be applied.
+ *
+ * The copies named are one **side** of the derivation, the same side a
+ * window is measured over, and `sidesOf` is what says which they are.
+ * Naming one copy of a side that has several does not separate that
+ * side: what stays behind is the rest of it, mixed with the other
+ * side's copies, and a collation then compares one copy against that
+ * mixture rather than the two texts against each other.
+ *
+ * Symbols the named copies alone carry are already the version's own
+ * and are passed over, so a reading somebody has separated by hand
+ * keeps its identifier and the edit that speaks for it. Named symbols
+ * narrow the act to those; naming none separates the whole reading.
+ */
+export declare const separateReadings: (given: EditionView, versionId: string, copies: ReadonlySet<string>, symbolIds?: readonly string[]) => EditionOp;

package/lib/ops/collation.js

@@ -0,0 +1,228 @@
+import { v4 } from "uuid";
+import { getAt } from "../view/EditionView.js";
+import { collationsOf, defaultCollationTolerance, isCollationsOwn, unchecked } from "../collation/Collation.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, stateOf, insertion, deletion, asUnchecked, declaring, insertedIn, dropInsertions, reading } from "./draft.js";
+import { hypothesesBeside } from "./versions.js";
+/** The carriers of each collated symbol pass to its counterpart. */
+const handOverCarriers = (view, draft, collations) => collations.forEach(({ symbol, counterpart }) => {
+    const path = view.getPath(counterpart.id);
+    const target = path && getAt(path, draft);
+    target?.carriers.push(...symbol.carriers);
+});
+/** Whether the two versions are coded for different reproducing systems. */
+const differ = (child, parent) => {
+    const one = trackerBarOf(child?.system);
+    const other = trackerBarOf(parent?.system);
+    return one !== undefined && other !== undefined && one.id !== other.id;
+};
+/** The symbols a set of edits speaks for, whether by inserting or by deleting them. */
+const spokenForBy = (edits) => new Set(edits.flatMap(edit => [
+    ...(edit.insert ?? []).map(symbol => symbol.id),
+    ...(edit.delete ?? [])
+]));
+/** An exchange of symbols, as a key: what it puts in against what it takes out. */
+const exchangeKey = (inserted, deleted) => `${[...inserted].sort().join(',')}/${[...deleted].sort().join(',')}`;
+/**
+ * The edits already stated, by the exchange each of them makes. An
+ * equivalence the collation draws a second time is the one already
+ * stated, and drawing it again is no reason to mint a new identifier or
+ * to drop the motivation somebody wrote on it.
+ */
+const byExchange = (edits) => new Map(edits.map(edit => [exchangeKey((edit.insert ?? []).map(symbol => symbol.id), edit.delete ?? []), edit]));
+/**
+ * Bases the child on the parent. A symbol of the child that collates
+ * with one the parent hands down adds its carriers to that symbol; the
+ * rest become the child's insertions, and what the parent hands down
+ * and the child lacks becomes its deletions. The derivation states the
+ * 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
+ * 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.
+ *
+ * The child's own text is what it shows less what the parent hands
+ * down, so that connecting two versions already connected collates the
+ * child's symbols and not the parent's with themselves.
+ *
+ * A version is based on itself or on one of its own descendants in no
+ * statement, since the stemma would loop; asked for that, nothing
+ * changes.
+ */
+export const connectVersions = (given, childId, parentId, tolerance = defaultCollationTolerance) => reading(given, view => {
+    if (childId === parentId || derivesFrom(view.edition.versions, parentId, childId))
+        return noChange;
+    const child = view.version(childId);
+    const stated = child ? editsOf(child) : [];
+    const established = stated.filter(edit => !isCollationsOwn(edit));
+    const spokenFor = spokenForBy(established);
+    const unspoken = (symbol) => !spokenFor.has(symbol.id);
+    // What the parent hands down and the child still shows passes
+    // through: it is neither the child's own symbol nor one it lacks.
+    // Without that, connecting a pair already connected would collate
+    // the inherited symbols with themselves and double their carriers.
+    const handedDown = view.snapshot(parentId).filter(unspoken);
+    const shown = new Set(view.snapshot(childId).map(symbol => symbol.id));
+    const inheritedIds = new Set(handedDown.map(symbol => symbol.id));
+    const inherited = handedDown.filter(symbol => !shown.has(symbol.id));
+    const own = view.snapshot(childId).filter(symbol => unspoken(symbol) && !inheritedIds.has(symbol.id));
+    const locate = (symbol) => view.placeOf(symbol);
+    const collations = collationsOf(own, inherited, locate, tolerance);
+    const collated = new Set(collations.map(({ symbol }) => symbol.id));
+    const matched = new Set(collations.map(({ counterpart }) => counterpart.id));
+    /**
+     * Where the child is coded for another system, a held command of
+     * its own often stands for a latched pair of the parent's. Saying so
+     * as one edit is the transfer being carried out, and leaving the two
+     * apart would make the apparatus a list of unexplained losses beside
+     * a list of unexplained gains.
+     */
+    const substituted = differ(child, view.version(parentId))
+        ? substitutionsBetween(own.filter(symbol => !collated.has(symbol.id)), inherited.filter(symbol => !matched.has(symbol.id)), locate, tolerance)
+        : [];
+    const paired = new Set(substituted.flatMap(({ replaced, by }) => [...by, ...replaced].map(symbol => symbol.id)));
+    const alreadyStated = byExchange(stated);
+    const equivalence = ({ replaced, by }) => {
+        const inserted = by.map(symbol => symbol.id);
+        const deleted = replaced.map(symbol => symbol.id);
+        return alreadyStated.get(exchangeKey(inserted, deleted)) ?? {
+            type: 'edit',
+            id: v4(),
+            editType: 'replace-with-equivalent',
+            motivation: unchecked,
+            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),
+        ...inherited
+            .filter(symbol => !matched.has(symbol.id) && !paired.has(symbol.id))
+            .map(symbol => asUnchecked(deletion(symbol.id)))
+    ];
+    return onVersion(childId, (child, draft) => {
+        handOverCarriers(view, draft, collations);
+        child.edits = edits;
+        child.motivations = declaring(stateOf(child).motivations, edits);
+        child.basedOn = [
+            { ...assignReference(parentId), collationTolerance: tolerance },
+            ...hypothesesBeside(stateOf(child), parentId)
+        ];
+    });
+});
+/**
+ * Folds the version's own symbols into those it inherits and collates
+ * with: the carriers pass over, and the insertions go. Collates at the
+ * tolerance of the derivation, where the caller names none.
+ */
+export const collateSymbols = (given, versionId, symbolIds, tolerance) => reading(given, view => {
+    const version = view.version(versionId);
+    const principal = version && principalDerivationOf(version);
+    if (!version || !principal)
+        return noChange;
+    const chosen = new Set(symbolIds);
+    const own = insertedIn([version]).filter(symbol => chosen.has(symbol.id));
+    const collations = collationsOf(own, view.snapshot(idOf(principal)), symbol => view.placeOf(symbol), tolerance ?? collationToleranceOf(principal));
+    const collated = new Set(collations.map(({ symbol }) => symbol.id));
+    return onVersion(versionId, (version, draft) => {
+        handOverCarriers(view, draft, collations);
+        dropInsertions(version, collated);
+    });
+});
+/** The symbol as one copy reads it: what it says, on the given carriers, standing in no relation of its own. */
+const readingOf = (symbol, carriers) => {
+    const identity = { id: v4(), carriers };
+    switch (symbol.type) {
+        case 'note':
+            return { type: 'note', pitch: symbol.pitch, ...identity };
+        case 'expression':
+            return { type: 'expression', expressionType: symbol.expressionType, scope: symbol.scope, ...identity };
+        case 'text':
+            return { type: 'text', text: symbol.text, ...identity };
+    }
+};
+/**
+ * The symbol where the named copies and at least one other carry it,
+ * with the carriers of each side.
+ *
+ * A symbol the named copies alone carry has no other side to be
+ * separated from and is passed over. That covers the insertions, and it
+ * covers a symbol an ancestor holds on one branch's witness alone,
+ * where the two versions do not disagree and there is nothing to take
+ * apart.
+ */
+const sharedWith = (view, symbol, copies) => {
+    const onNamedCopy = (carrier) => {
+        const copy = view.copyOf(idOf(carrier));
+        return copy !== undefined && copies.has(copy.id);
+    };
+    const mine = symbol.carriers.filter(onNamedCopy);
+    const theirs = symbol.carriers.filter(carrier => !onNamedCopy(carrier));
+    return mine.length > 0 && theirs.length > 0 ? [{ symbol, mine, theirs }] : [];
+};
+/**
+ * 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.
+ *
+ * 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
+ * is one symbol carrying every copy that reads it, so nothing else
+ * takes the two readings apart again, and without that a tolerance
+ * arrived at after the fact could never be applied.
+ *
+ * The copies named are one **side** of the derivation, the same side a
+ * window is measured over, and `sidesOf` is what says which they are.
+ * Naming one copy of a side that has several does not separate that
+ * side: what stays behind is the rest of it, mixed with the other
+ * side's copies, and a collation then compares one copy against that
+ * mixture rather than the two texts against each other.
+ *
+ * Symbols the named copies alone carry are already the version's own
+ * and are passed over, so a reading somebody has separated by hand
+ * keeps its identifier and the edit that speaks for it. Named symbols
+ * narrow the act to those; naming none separates the whole reading.
+ */
+export const separateReadings = (given, versionId, copies, symbolIds) => reading(given, view => {
+    const version = view.version(versionId);
+    if (!version)
+        return noChange;
+    const chosen = symbolIds && new Set(symbolIds);
+    const shared = view.snapshot(versionId)
+        .filter(symbol => chosen === undefined || chosen.has(symbol.id))
+        .flatMap(symbol => sharedWith(view, symbol, copies));
+    if (shared.length === 0)
+        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] })
+    }));
+    return onVersion(versionId, (version, draft) => {
+        shared.forEach(({ symbol, theirs }) => {
+            const path = view.getPath(symbol.id);
+            const target = path && getAt(path, draft);
+            if (target)
+                target.carriers = theirs;
+        });
+        version.edits = [...stated, ...separations];
+    });
+});

package/lib/ops/commands.d.ts

@@ -0,0 +1,9 @@
+import { EditionView } from "../view/EditionView.js";
+import { PlacementRelation } from "../model/Symbol.js";
+import { EditionOp } from "./draft.js";
+/** States how the follower is placed relative to the reference, in place of any earlier statement. */
+export declare const placeCommand: (view: EditionView, followerId: string, referenceId: string, relation: PlacementRelation) => EditionOp;
+export declare const unplaceCommand: (view: EditionView, followerId: string) => EditionOp;
+/** The pair is stated on `statingId` only, as the format asks. */
+export declare const pairCommands: (view: EditionView, statingId: string, partnerId: string) => EditionOp;
+export declare const unpairCommand: (view: EditionView, statingId: string) => EditionOp;

package/lib/ops/commands.js

@@ -0,0 +1,29 @@
+import { getAt } from "../view/EditionView.js";
+import { isCommand, placementRelations } from "../model/Symbol.js";
+import { assignReference } from "../model/Assumption.js";
+import { reading } from "./draft.js";
+/**
+ * Runs the change on the command the view locates by id, in whichever
+ * version inserted it. A statement made there holds in every version
+ * that carries the command.
+ */
+const onCommand = (view, id, op) => reading(view, fresh => draft => {
+    const path = fresh.getPath(id);
+    const symbol = path && getAt(path, draft);
+    if (isCommand(symbol))
+        op(symbol);
+});
+const clearPlacement = (command) => placementRelations.forEach(relation => { delete command[relation]; });
+/** States how the follower is placed relative to the reference, in place of any earlier statement. */
+export const placeCommand = (view, followerId, referenceId, relation) => onCommand(view, followerId, command => {
+    clearPlacement(command);
+    command[relation] = assignReference(referenceId);
+});
+export const unplaceCommand = (view, followerId) => onCommand(view, followerId, clearPlacement);
+/** The pair is stated on `statingId` only, as the format asks. */
+export const pairCommands = (view, statingId, partnerId) => onCommand(view, statingId, command => {
+    command.pairedWith = assignReference(partnerId);
+});
+export const unpairCommand = (view, statingId) => onCommand(view, statingId, command => {
+    delete command.pairedWith;
+});

package/lib/ops/copies.d.ts

@@ -0,0 +1,74 @@
+/** Operations on the copies: adding and aligning them, and what they state of their source, their carriage and their condition. */
+import { Draft } from "immer";
+import { Edition } from "../model/Edition.js";
+import { AnySymbol } from "../model/Symbol.js";
+import { GeneralRollCondition, RollCopy, ScaleReading, Shift } from "../model/RollCopy.js";
+import { FeatureSource } from "../model/FeatureSource.js";
+import { Belief, ObjectAssumption, ReferenceAssumption } from "../model/Assumption.js";
+import { Millimeters } from "../model/Quantity.js";
+import { EditionOp } from "./draft.js";
+/**
+ * Puts the copy into the edition with a version of its own, which
+ * inserts every symbol the copy's own tracker bar reads on it. The
+ * version is a reading in that system's words, so it is coded for the
+ * system the copy was cut for.
+ */
+export declare const createVersion: (copy: RollCopy) => EditionOp;
+/**
+ * Puts the copy into the edition without a version of its own, as for a
+ * copy whose features are not read into symbols: one known only from a
+ * recording states instead which versions it carries.
+ */
+export declare const addCopy: (copy: RollCopy) => EditionOp;
+/**
+ * Shifts and then scales the copy's features into line with another
+ * copy's, and puts the scale down to what the reading says: the paper,
+ * or the speed the copy was cut for.
+ */
+export declare const alignCopy: (copyId: string, shift: Shift, scale: number, reading?: ScaleReading) => EditionOp;
+/**
+ * Puts the copy's features back where they were measured. A paper
+ * stretch read off the alignment goes with it; a speed stated stays,
+ * being a fact about the copy.
+ */
+export declare const unalignCopy: (copyId: string) => EditionOp;
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's chains of holes, and records how much was taken, so that their lengths
+ * can be compared with a scanned copy's at all.
+ */
+export declare const shortenCopy: (copyId: string, extension: Millimeters, leaving?: ReadonlySet<string>) => EditionOp;
+/** Puts the reader's extension back on the copy's chains of holes. */
+export declare const unshortenCopy: (copyId: string) => EditionOp;
+/** States what the copy's features were read from, in place of any earlier statement. */
+export declare const stateSource: (copyId: string, source: FeatureSource) => EditionOp;
+/** Takes back the statement, leaving the copy silent about its source again. */
+export declare const clearSource: (copyId: string) => EditionOp;
+/** Gives the copy the siglum it is referred to by, or takes it away where the siglum given is blank. */
+export declare const nameCopy: (copyId: string, siglum: string) => EditionOp;
+/** Takes out the copy's statements that match, and the list itself where none is left. */
+export declare const dropStatements: (copy: Draft<RollCopy>, matches: (statement: Readonly<ReferenceAssumption>) => boolean) => void;
+/**
+ * States that the copy carries the version, under the belief given. It
+ * is meant for a copy whose features are not read into symbols, such as
+ * one known only from a recording, and `carriageProblems` reports it
+ * where features carry symbols already. A second statement about one
+ * version is none.
+ */
+export declare const stateCarriage: (copyId: string, versionId: string, belief?: Belief) => EditionOp;
+/** Takes back the copy's statement that it carries the version. */
+export declare const clearCarriage: (copyId: string, versionId: string) => EditionOp;
+/**
+ * Adds a general condition to the copy, beside whatever is stated of it
+ * already. The other condition a copy may be in, a paper stretch, is
+ * read off an alignment and stated by `alignCopy`.
+ */
+export declare const addGeneralCondition: (copyId: string, condition: ObjectAssumption<GeneralRollCondition>) => EditionOp;
+/** The symbols of the versions that no other copy carries. */
+export declare const symbolsCarriedOnlyBy: (edition: Edition, copyId: string) => AnySymbol[];
+/**
+ * Takes the copy out of the edition together with the symbols only it
+ * carries, and with every reference the versions and the argumentations
+ * made to those symbols.
+ */
+export declare const removeCopy: (copyId: string) => EditionOp;

package/lib/ops/copies.js

@@ -0,0 +1,135 @@
+import { v4 } from "uuid";
+import { asSymbols, barOf, featuresOf, isPaperStretch } from "../model/RollCopy.js";
+import { systemOf } from "../systems/TrackerBar.js";
+import { applyShift, applyScale, revertShift, revertScale, revertShortening, shortenChains } from "../collation/alignment.js";
+import { idOf } from "../model/Assumption.js";
+import { onCopy, stateOf, insertion, insertedIn, referenceHeld, withoutReferences } from "./draft.js";
+import { without } from "./immutable.js";
+import { featureIdsOf, carriedOnlyOn, forgetFeatures } from "./forget.js";
+/**
+ * Puts the copy into the edition with a version of its own, which
+ * inserts every symbol the copy's own tracker bar reads on it. The
+ * version is a reading in that system's words, so it is coded for the
+ * system the copy was cut for.
+ */
+export const createVersion = (copy) => draft => {
+    const bar = barOf(copy);
+    draft.copies.push(copy);
+    draft.versions.push({
+        id: v4(),
+        system: systemOf(bar),
+        edits: asSymbols(featuresOf(copy), bar).map(insertion),
+        motivations: []
+    });
+};
+/**
+ * Puts the copy into the edition without a version of its own, as for a
+ * copy whose features are not read into symbols: one known only from a
+ * recording states instead which versions it carries.
+ */
+export const addCopy = (copy) => draft => {
+    draft.copies.push(copy);
+};
+/** States what the scale is put down to, in place of an earlier reading. */
+const readScale = (copy, reading) => {
+    if (reading.cause === 'paper') {
+        copy.conditions = [...copy.conditions.filter(condition => !isPaperStretch(condition)), reading.condition];
+        return;
+    }
+    if (!copy.production)
+        copy.production = {};
+    copy.production.speed = reading.speed;
+};
+/**
+ * Shifts and then scales the copy's features into line with another
+ * copy's, and puts the scale down to what the reading says: the paper,
+ * or the speed the copy was cut for.
+ */
+export const alignCopy = (copyId, shift, scale, reading) => onCopy(copyId, copy => {
+    applyShift(shift, copy);
+    applyScale(scale, copy);
+    if (reading)
+        readScale(copy, reading);
+});
+/**
+ * Puts the copy's features back where they were measured. A paper
+ * stretch read off the alignment goes with it; a speed stated stays,
+ * being a fact about the copy.
+ */
+export const unalignCopy = (copyId) => onCopy(copyId, copy => {
+    revertScale(copy);
+    revertShift(copy);
+    copy.conditions = without(copy.conditions, isPaperStretch);
+});
+/**
+ * Takes the extension a pneumatic reader adds off the ends of the
+ * copy's chains of holes, and records how much was taken, so that their lengths
+ * can be compared with a scanned copy's at all.
+ */
+export const shortenCopy = (copyId, extension, leaving) => onCopy(copyId, copy => shortenChains(extension, copy, leaving));
+/** Puts the reader's extension back on the copy's chains of holes. */
+export const unshortenCopy = (copyId) => onCopy(copyId, copy => revertShortening(copy));
+/** States what the copy's features were read from, in place of any earlier statement. */
+export const stateSource = (copyId, source) => onCopy(copyId, copy => {
+    copy.readFrom = source;
+});
+/** Takes back the statement, leaving the copy silent about its source again. */
+export const clearSource = (copyId) => onCopy(copyId, copy => {
+    copy.readFrom = undefined;
+});
+/** Gives the copy the siglum it is referred to by, or takes it away where the siglum given is blank. */
+export const nameCopy = (copyId, siglum) => onCopy(copyId, copy => {
+    const trimmed = siglum.trim();
+    if (trimmed)
+        copy.siglum = trimmed;
+    else
+        delete copy.siglum;
+});
+/** Takes out the copy's statements that match, and the list itself where none is left. */
+export const dropStatements = (copy, matches) => {
+    const statements = stateOf(copy).carries;
+    if (!statements?.some(matches))
+        return;
+    const kept = withoutReferences(statements, matches);
+    if (kept)
+        copy.carries = kept;
+    else
+        delete copy.carries;
+};
+/**
+ * States that the copy carries the version, under the belief given. It
+ * is meant for a copy whose features are not read into symbols, such as
+ * one known only from a recording, and `carriageProblems` reports it
+ * where features carry symbols already. A second statement about one
+ * version is none.
+ */
+export const stateCarriage = (copyId, versionId, belief) => onCopy(copyId, copy => {
+    const statements = stateOf(copy).carries ?? [];
+    if (statements.some(statement => idOf(statement) === versionId))
+        return;
+    copy.carries = [...statements, referenceHeld(versionId, belief)];
+});
+/** Takes back the copy's statement that it carries the version. */
+export const clearCarriage = (copyId, versionId) => onCopy(copyId, copy => dropStatements(copy, statement => idOf(statement) === versionId));
+/**
+ * Adds a general condition to the copy, beside whatever is stated of it
+ * already. The other condition a copy may be in, a paper stretch, is
+ * read off an alignment and stated by `alignCopy`.
+ */
+export const addGeneralCondition = (copyId, condition) => onCopy(copyId, copy => {
+    copy.conditions.push(condition);
+});
+/** The symbols of the versions that no other copy carries. */
+export const symbolsCarriedOnlyBy = (edition, copyId) => {
+    const copy = edition.copies.find(c => c.id === copyId);
+    return copy ? insertedIn(edition.versions).filter(carriedOnlyOn(featureIdsOf(copy))) : [];
+};
+/**
+ * Takes the copy out of the edition together with the symbols only it
+ * carries, and with every reference the versions and the argumentations
+ * made to those symbols.
+ */
+export const removeCopy = (copyId) => onCopy(copyId, (copy, draft) => {
+    forgetFeatures(draft, featureIdsOf(copy));
+    draft.copies = draft.copies.filter(c => c.id !== copyId);
+});

package/lib/ops/draft.d.ts

@@ -0,0 +1,59 @@
+import { EditionView } from "../view/EditionView.js";
+/** 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 { 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 { RollCopy } from "../model/RollCopy.js";
+import { Belief, ReferenceAssumption } from "../model/Assumption.js";
+import { FeatureOrPatch } from "../model/Feature.js";
+import { WithId } from "../shared/utils.js";
+/**
+ * A change to an edition, written onto an immer draft of it. One
+ * operation is one undo step, so an operation that has to read the
+ * edition first takes an `EditionView` of the state it will be
+ * applied to and does all its writing in the one function it returns.
+ * Where operations run one after another on one draft, the ones after
+ * the first read a view of the draft as it then stands (`reading`).
+ */
+export type EditionOp = (draft: Draft<Edition>) => void;
+export declare const noChange: EditionOp;
+export declare const onCopy: (copyId: string, op: (copy: Draft<RollCopy>, draft: Draft<Edition>) => void) => EditionOp;
+export declare const onVersion: (versionId: string, op: (version: Draft<Version>, draft: Draft<Edition>) => void) => EditionOp;
+export declare const onFeature: (copyId: string, featureId: string, op: (feature: Draft<FeatureOrPatch>) => void) => EditionOp;
+/**
+ * The operation built from a view of the state it is applied to. The
+ * view given is used where the draft still stands as the view saw it,
+ * and a fresh one is taken of the draft where an operation run before
+ * on the same draft has changed it: a path or an index read off the
+ * view would otherwise name what stood there before.
+ */
+export declare const reading: (view: EditionView, build: (view: EditionView) => EditionOp) => EditionOp;
+/**
+ * The state a draft stands at, as plain data. Reading a draft proxies
+ * everything it touches, so what is only read is read from this.
+ */
+export declare const stateOf: <T>(draft: Draft<T>) => T;
+/** The ids of the items the rewriting left out. */
+export declare const droppedIds: (before: readonly WithId[], after: readonly WithId[]) => string[];
+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[];
+/** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
+export declare const dropInsertions: (version: Draft<Version>, symbolIds: Ids) => void;
+/** A reference under the belief given, where one is given. */
+export declare const referenceHeld: (id: string, belief?: Belief) => ReferenceAssumption;
+/** The references less those that match, or nothing where none is left. */
+export declare const withoutReferences: <R extends ReferenceAssumption>(references: readonly R[], matches: (reference: Readonly<R>) => boolean) => R[] | undefined;