linked-rolls 0.25.1 → 0.27.0

package/lib/editionOps.js

@@ -3,7 +3,7 @@ import { v4 } from "uuid";
 import { getAt } from "./EditionView";
 import { isPerforation, placementRelations } from "./Symbol";
 import { collationsOf, defaultCollationTolerance } from "./Collation";
-import { collationToleranceOf, insertedBy } from "./Version";
+import { collationToleranceOf, editsOf, insertedBy, principalDerivationOf } from "./Version";
 import { asSymbols, barOf, isPaperStretch } from "./RollCopy";
 import { systemOf } from "./TrackerBar";
 import { substitutionsBetween } from "./substitution";
@@ -65,7 +65,9 @@ const droppingInsertions = (symbolIds) => (edit) => {
 };
 /** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
 const dropInsertions = (version, symbolIds) => {
-    version.edits = edited(stateOf(version).edits, droppingInsertions(symbolIds));
+    const edits = stateOf(version).edits;
+    if (edits)
+        version.edits = edited(edits, droppingInsertions(symbolIds));
 };
 /**
  * Puts the copy into the edition with a version of its own, which
@@ -86,6 +88,14 @@ export const createVersion = (siglum, copy) => draft => {
         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') {
@@ -125,6 +135,39 @@ export const stateSource = (copyId, source) => onCopy(copyId, copy => {
 export const clearSource = (copyId) => onCopy(copyId, copy => {
     copy.readFrom = undefined;
 });
+/** A reference under the belief given, where one is given. */
+const referenceHeld = (id, belief) => ({ ...assignReference(id), ...(belief && { '@annotation': { id: v4(), belief } }) });
+/** The references less those that match, or nothing where none is left. */
+const withoutReferences = (references, matches) => {
+    const kept = references.filter(reference => !matches(reference));
+    return kept.length > 0 ? kept : undefined;
+};
+/** Takes out the copy's statements that match, and the list itself where none is left. */
+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
@@ -278,15 +321,17 @@ const forgetFeatures = (draft, features) => {
     const versions = stateOf(draft.versions);
     const dropped = new Set(insertedIn(versions).filter(carriedOnlyOn(features)).map(symbol => symbol.id));
     const forget = forgettingFeatures(features, dropped);
-    const edits = versions.map(version => edited(version.edits, forget));
+    const edits = versions.map(version => version.edits && edited(version.edits, forget));
     const gone = new Set([
         ...features,
         ...dropped,
-        ...versions.flatMap((version, i) => droppedIds(version.edits, edits[i]))
+        ...versions.flatMap((version, i) => droppedIds(editsOf(version), edits[i] ?? []))
     ]);
     renameReferences(draft, ids => without(ids, id => gone.has(id)));
     draft.versions.forEach((version, i) => {
-        version.edits = edits[i];
+        const stated = edits[i];
+        if (stated)
+            version.edits = stated;
     });
 };
 /**
@@ -417,7 +462,9 @@ const carryOver = (draft, replaced, mergedId) => {
     };
     const versions = stateOf(draft.versions);
     draft.versions.forEach((version, i) => {
-        version.edits = mapped(versions[i].edits, recarrying);
+        const edits = versions[i].edits;
+        if (edits)
+            version.edits = mapped(edits, recarrying);
     });
 };
 /**
@@ -463,12 +510,34 @@ const differ = (child, parent) => {
     const other = trackerBarOf(parent?.system);
     return one !== undefined && other !== undefined && one.id !== other.id;
 };
+/** Whether the version's text is read against the parent, its principal derivation naming it. */
+const readsAgainst = (version, parentId) => {
+    const principal = principalDerivationOf(version);
+    return principal !== undefined && idOf(principal) === parentId;
+};
+/** The derivations the version states beside its principal one, less any naming the parent. */
+const hypothesesBeside = (version, parentId) => {
+    const principal = principalDerivationOf(version);
+    return (version.basedOn ?? []).filter(derivation => derivation !== principal && idOf(derivation) !== parentId);
+};
+/** Takes out the derivations that match, and the list itself where none is left. */
+const dropDerivations = (version, matches) => {
+    const derivations = stateOf(version).basedOn;
+    if (!derivations?.some(matches))
+        return;
+    const kept = withoutReferences(derivations, matches);
+    if (kept)
+        version.basedOn = kept;
+    else
+        delete version.basedOn;
+};
 /**
  * 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.
+ * tolerance it was collated at and becomes the principal one; the
+ * hypotheses the child stated beside its former one stay.
  */
 export const connectVersions = (view, childId, parentId, tolerance = defaultCollationTolerance) => {
     const inherited = view.snapshot(parentId);
@@ -504,7 +573,10 @@ export const connectVersions = (view, childId, parentId, tolerance = defaultColl
     return onVersion(childId, (child, draft) => {
         handOverCarriers(view, draft, collations);
         child.edits = edits;
-        child.basedOn = { ...assignReference(parentId), collationTolerance: tolerance };
+        child.basedOn = [
+            { ...assignReference(parentId), collationTolerance: tolerance },
+            ...hypothesesBeside(stateOf(child), parentId)
+        ];
     });
 };
 /**
@@ -514,11 +586,12 @@ export const connectVersions = (view, childId, parentId, tolerance = defaultColl
  */
 export const collateSymbols = (view, versionId, symbolIds, tolerance) => {
     const version = view.get(versionId);
-    if (!version?.basedOn)
+    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(version.basedOn)), symbol => view.placeOf(symbol), tolerance ?? collationToleranceOf(version.basedOn));
+    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);
@@ -527,8 +600,8 @@ export const collateSymbols = (view, versionId, symbolIds, tolerance) => {
 };
 /**
  * Makes the version stand on its own: what it inherited becomes its
- * own insertions, and the link to the version it was based on goes,
- * with the motivations that belonged to that derivation.
+ * own insertions, and its derivations go, the hypotheses among them,
+ * with the motivations that belonged to them.
  */
 export const detachVersion = (view, versionId) => {
     const edits = view.snapshot(versionId).map(insertion);
@@ -538,13 +611,20 @@ export const detachVersion = (view, versionId) => {
         version.motivations = [];
     });
 };
-/** Takes the version out; whatever was based on it comes to stand on its own. */
+/**
+ * Takes the version out. Whatever read its text against it comes to
+ * stand on its own, a hypothesis that something derives from it goes,
+ * and so does a copy's statement that it carries the version.
+ */
 export const removeVersion = (view, versionId) => {
     const detachments = view.edition.versions
-        .filter(version => version.basedOn && idOf(version.basedOn) === versionId)
+        .filter(version => readsAgainst(version, versionId))
         .map(version => detachVersion(view, version.id));
+    const namesIt = (reference) => idOf(reference) === versionId;
     return draft => {
         detachments.forEach(detach => detach(draft));
+        draft.versions.forEach(version => dropDerivations(version, namesIt));
+        draft.copies.forEach(copy => dropStatements(copy, namesIt));
         draft.versions = without(draft.versions, version => version.id === versionId);
     };
 };
@@ -553,19 +633,39 @@ export const removeSymbols = (versionId, symbolIds) => onVersion(versionId, vers
 /** Moves the edits into a new version based on this one. */
 export const deriveVersion = (versionId, editIds) => onVersion(versionId, (version, draft) => {
     const chosen = new Set(editIds);
-    const moved = version.edits.filter(edit => chosen.has(edit.id));
-    version.edits = without(version.edits, edit => chosen.has(edit.id));
+    const moved = editsOf(version).filter(edit => chosen.has(edit.id));
+    if (version.edits)
+        version.edits = without(version.edits, edit => chosen.has(edit.id));
     draft.versions.push({
         type: 'Version',
         id: v4(),
         siglum: `${version.siglum}_derived`,
         system: stateOf(version).system,
         versionType: 'unicum',
-        basedOn: assignReference(versionId),
+        basedOn: [assignReference(versionId)],
         edits: moved,
         motivations: []
     });
 });
+/**
+ * States that the version may also derive from the parent, beside what
+ * it derives from already: a hypothesis, such as a contamination, under
+ * the belief given. The text stays read against the principal derivation
+ * unless the belief holds this one more certain. A version derives from
+ * itself, or twice from one parent, in no statement.
+ */
+export const stateDerivation = (versionId, parentId, belief) => onVersion(versionId, version => {
+    const derivations = stateOf(version).basedOn ?? [];
+    if (parentId === versionId || derivations.some(derivation => idOf(derivation) === parentId))
+        return;
+    version.basedOn = [...derivations, referenceHeld(parentId, belief)];
+});
+/** Takes back the hypothesis that the version derives from the parent; the principal derivation goes with `detachVersion`. */
+export const clearDerivation = (versionId, parentId) => onVersion(versionId, version => {
+    if (readsAgainst(stateOf(version), parentId))
+        return;
+    dropDerivations(version, derivation => idOf(derivation) === parentId);
+});
 const sameSequence = (a, b) => a.length === b.length && a.every((value, i) => value === b[i]);
 const expressionTypesOf = (symbols) => symbols.filter((symbol) => symbol.type === 'expression').map(symbol => symbol.expressionType);
 /**
@@ -640,7 +740,7 @@ export const mergeEdits = (view, versionId, toMerge) => {
     merged.editType = guessEditType(view, versionId, merged);
     const mergedIds = new Set(toMerge.map(edit => edit.id));
     return onVersion(versionId, version => {
-        version.edits = [...version.edits.filter(edit => !mergedIds.has(edit.id)), merged];
+        version.edits = [...editsOf(version).filter(edit => !mergedIds.has(edit.id)), merged];
     });
 };
 /** Replaces the edit with one edit per inserted and one per deleted symbol. */
@@ -650,7 +750,7 @@ export const splitEdit = (versionId, toSplit) => {
         ...(toSplit.delete ?? []).map(deletion)
     ];
     return onVersion(versionId, version => {
-        version.edits = [...version.edits.filter(edit => edit.id !== toSplit.id), ...parts];
+        version.edits = [...editsOf(version).filter(edit => edit.id !== toSplit.id), ...parts];
     });
 };
 /**

package/lib/index.d.ts

@@ -18,6 +18,7 @@ export * from './ReproducingSystem';
 export * from './FeatureSource';
 export * from './RollCopy';
 export * from './reservations';
+export * from './witnesses';
 export * from './alignment';
 export * from './Edition';
 export * from './EditionView';

package/lib/index.js

@@ -18,6 +18,7 @@ export * from './ReproducingSystem';
 export * from './FeatureSource';
 export * from './RollCopy';
 export * from './reservations';
+export * from './witnesses';
 export * from './alignment';
 export * from './Edition';
 export * from './EditionView';

package/lib/migrate.js

@@ -69,7 +69,27 @@ const withScale = (node) => {
     const factor = (node.conditions ?? []).find(isPaperStretch)?.factor;
     return factor === undefined ? node : { ...node, measurements: { ...node.measurements, scale: factor } };
 };
-const migrateNode = (node) => [withRenamedKeys, withTypology, withReferences, withKeeper, withProductionNodes, withScale]
+/** A derivation written as a single one, before a version could name several. */
+const isSingleDerivation = (basedOn) => basedOn !== null && typeof basedOn === 'object' && !Array.isArray(basedOn);
+const withDerivationList = (node) => isSingleDerivation(node.basedOn) ? { ...node, basedOn: [node.basedOn] } : node;
+/**
+ * A copy read on a roll reader was stated as a recording before a sound
+ * recording could be one. A sound recording gives no holes, so a recording
+ * with holes is a reading.
+ */
+const withReadingKind = (node) => node.readFrom?.kind === 'recording' && Array.isArray(node.features)
+    && node.features.some((feature) => feature?.['@type'] === 'Hole')
+    ? { ...node, readFrom: { ...node.readFrom, kind: 'reading' } }
+    : node;
+/** A keeper nobody could name was written as an empty one before a copy could leave it out. */
+const withoutEmptyKeeper = (node) => {
+    if (node.keeper?.name !== '' || node.keeper.sameAs?.length)
+        return node;
+    const { keeper: _unnamed, ...rest } = node;
+    return rest;
+};
+const migrateNode = (node) => [withRenamedKeys, withTypology, withReferences, withKeeper, withoutEmptyKeeper, withProductionNodes, withScale,
+    withDerivationList, withReadingKind]
     .reduce((result, step) => step(result), node);
 /** The items each walked, or the very same list where the walk changed none. */
 const walked = (items) => {
@@ -181,7 +201,7 @@ const withSystems = (edition) => {
 const withEditors = (edition) => !edition.creation || edition.creation.editors
     ? edition
     : { ...edition, creation: { ...edition.creation, editors: [] } };
-const statesNoTolerance = (version) => version.basedOn && !version.basedOn.collationTolerance;
+const statesNoTolerance = (version) => isSingleDerivation(version.basedOn) && !version.basedOn.collationTolerance;
 /**
  * The collation tolerance was the edition's before it was stated on
  * each derivation. An edition written then collated every version at

package/lib/readers/phillipsEroll.js

@@ -147,13 +147,12 @@ export function readFromPhillipsEroll(buffer, { system = welteT100, controlOffse
         id: v4(),
         ops: [],
         conditions: [],
-        keeper: { name: '', sameAs: [] },
         measurements: {},
         production: { system: systemOf(system) },
         modifications: [],
         features,
         readFrom: {
-            kind: 'recording',
+            kind: 'reading',
             actor: assignObject({ name: 'Phillips, Peter', sameAs: [] }),
             note: 'Read on Phillips’s pneumatic roll reader. The places are elapsed time put back onto the paper, and a hole runs as long as its switch stayed open, which is longer than the perforation.'
         }

package/lib/readers/spencerBar.js

@@ -113,7 +113,6 @@ export function readFromSpencerBar(buffer, { rowsPerInch = SPENCER_ROWS_PER_INCH
         id: v4(),
         ops: [],
         conditions: [],
-        keeper: { name: '', sameAs: [] },
         measurements: {},
         production: { system: systemOf(system) },
         modifications: [],

package/lib/readers/stanfordAton.js

@@ -157,7 +157,6 @@ export function readFromStanfordAton(atonString, { trackShift, system = welteT10
         id: v4(),
         ops: [],
         conditions: [],
-        keeper: { name: '', sameAs: [] },
         production: { system: systemOf(system) },
         modifications: [],
         ...((scan ?? stanford) && { scan: scan ?? stanford?.scan }),

package/lib/reservations.d.ts

@@ -1,23 +1,30 @@
 import { RollCopy } from "./RollCopy";
-export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated', 'system-unknown'];
+import { Version } from "./Version";
+import { EditionView } from "./EditionView";
+export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'software-not-named', 'instrument-not-named', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated', 'system-unknown', 'keeper-unknown'];
 export type ReservationType = typeof reservationTypes[number];
 /**
- * Something an edition cannot vouch for in one of its copies.
+ * Something an edition cannot vouch for in one of its copies or
+ * versions.
  *
- * A reservation is worked out from what the copy states about itself
- * and is never written into the edition: it says that knowledge of
- * the copy is incomplete, so filling in what is missing makes it go
- * away. Nothing here describes the state of the paper, which is a
+ * A reservation is worked out from what the copy or version states
+ * about itself and is never written into the edition: it says that
+ * knowledge of it is incomplete, so filling in what is missing makes it
+ * go away. Nothing here describes the state of the paper, which is a
  * condition of the copy.
  */
-export interface Reservation {
-    type: ReservationType;
+export interface Reservation<T extends string = ReservationType> {
+    type: T;
     /** What the reservation means for a reader, in one sentence. */
     note: string;
 }
 /**
  * What the edition cannot vouch for in a copy, in the order the
  * checks are listed: where its features came from first, then what
- * the measurement leaves open.
+ * the measurement leaves open, then who holds it.
  */
 export declare const reservationsAbout: (copy: RollCopy) => Reservation[];
+export declare const versionReservationTypes: readonly ['text-not-stated', 'type-not-stated', 'witnessed-by-statement-only'];
+export type VersionReservationType = typeof versionReservationTypes[number];
+/** What the edition cannot vouch for in a version, in the order the checks are listed. */
+export declare const reservationsAboutVersion: (view: EditionView, version: Readonly<Version>) => Reservation<VersionReservationType>[];

package/lib/reservations.js

@@ -1,14 +1,18 @@
 import { bearsPhysicalEvidence, isMeasured, sourceLabels } from "./FeatureSource";
 import { calibrationOf } from "./RollCopy";
 import { trackerBarOf } from "./systems";
+import { witnessesOf } from "./witnesses";
 export const reservationTypes = [
     'source-not-stated',
     'source-undocumented',
+    'software-not-named',
+    'instrument-not-named',
     'features-interpreted',
     'no-physical-evidence',
     'measurement-undocumented',
     'not-calibrated',
-    'system-unknown'
+    'system-unknown',
+    'keeper-unknown'
 ];
 const sourceStated = copy => copy.readFrom ? undefined : {
     type: 'source-not-stated',
@@ -23,6 +27,20 @@ const sourceDocumented = copy => {
         note: `The copy names ${sourceLabels[source.kind]} as its source, but records nobody who made it, no device and no date.`
     };
 };
+/** An emulation and a recording are turned into notes by software, which says how far to trust them. */
+const softwareNamed = copy => {
+    const source = copy.readFrom;
+    if (!source || isMeasured(source.kind) || source.software?.length)
+        return undefined;
+    return {
+        type: 'software-not-named',
+        note: `The copy names ${sourceLabels[source.kind]} as its source, but not the software that turned it into notes.`
+    };
+};
+const instrumentNamed = copy => copy.readFrom?.kind === 'recording' && !copy.readFrom.instrument ? {
+    type: 'instrument-not-named',
+    note: 'The copy is known from a recording, but neither the instrument it was played on nor its regulation is named.'
+} : undefined;
 const featuresMeasured = copy => copy.readFrom && !isMeasured(copy.readFrom.kind) ? {
     type: 'features-interpreted',
     note: `The features come from ${sourceLabels[copy.readFrom.kind]}, in which the roll has already been read into notes and commands by somebody else.`
@@ -58,18 +76,50 @@ const systemKnown = copy => {
         note: `The copy names ${system.name || 'a reproducing system'}, which the edition has no tracker bar for, so it is read by the T-100's.`
     };
 };
+const keeperKnown = copy => copy.keeper ? undefined : {
+    type: 'keeper-unknown',
+    note: 'Nobody is known to hold the copy, so its paper cannot be consulted.'
+};
+/** A check on what a copy's features leave open, which has nothing to say of a copy without any. */
+const onFeatures = (check) => copy => copy.features.length > 0 ? check(copy) : undefined;
 const checks = [
     sourceStated,
     sourceDocumented,
-    featuresMeasured,
-    physicalEvidence,
-    measurementDocumented,
-    calibrated,
-    systemKnown
+    softwareNamed,
+    instrumentNamed,
+    onFeatures(featuresMeasured),
+    onFeatures(physicalEvidence),
+    onFeatures(measurementDocumented),
+    onFeatures(calibrated),
+    onFeatures(systemKnown),
+    keeperKnown
 ];
 /**
  * What the edition cannot vouch for in a copy, in the order the
  * checks are listed: where its features came from first, then what
- * the measurement leaves open.
+ * the measurement leaves open, then who holds it.
  */
 export const reservationsAbout = (copy) => checks.flatMap(check => check(copy) ?? []);
+export const versionReservationTypes = [
+    'text-not-stated',
+    'type-not-stated',
+    'witnessed-by-statement-only'
+];
+const textStated = (_view, version) => version.edits ? undefined : {
+    type: 'text-not-stated',
+    note: 'The version does not state its edits, so it reads as the version it derives from.'
+};
+const typeStated = (_view, version) => version.versionType ? undefined : {
+    type: 'type-not-stated',
+    note: 'The version does not say whether it served as a master for several copies or exists on one only.'
+};
+const witnessedByFeatures = (view, version) => {
+    const witnesses = witnessesOf(view, version.id);
+    return witnesses.length > 0 && witnesses.every(({ by }) => by === 'statement') ? {
+        type: 'witnessed-by-statement-only',
+        note: 'No copy\'s features carry what the version inserts; only copies that state they carry it bear witness to it.'
+    } : undefined;
+};
+const versionChecks = [textStated, typeStated, witnessedByFeatures];
+/** What the edition cannot vouch for in a version, in the order the checks are listed. */
+export const reservationsAboutVersion = (view, version) => versionChecks.flatMap(check => check(view, version) ?? []);