linked-rolls 0.25.1 → 0.27.0

package/README.md

@@ -43,28 +43,54 @@ the keeper and the production metadata are nodes with a name and
 authority links, and the roll names its reproducing system. Exports
 are always in the current format.
 
+## What a version derives from
+
+A version names the versions it is held to derive from in `basedOn`,
+each under the belief it rests on. Its text is read against the
+principal derivation, the first of those held most certain, and one
+held unlikely or false never gives the text. The others stand as
+hypotheses, such as a contamination: `stateDerivation` adds one and
+`clearDerivation` takes it back. A version may leave out its `edits`
+where nobody can state them, as for a text that only a recording hints
+at. It then reads as the version it derives from, and
+`reservationsAboutVersion` says so. A file that names a single
+derivation loads as a list of one.
+
 ## Where a copy's features come from
 
 `readFrom` states what a copy's features were read from: the roll
 itself, a `scan` of it, an `analysis` somebody else measured on a
-scan, an `emulation` in which the roll has already been read into
-notes and commands, or a `recording` captured while the copy was
-played. Beside the kind it holds who carried the capture out, on what
-device, when, and a note. What is not known is left out.
+scan, a `reading` of the timed switches of a roll reader, an
+`emulation` in which the roll has already been read into notes and
+commands, or a `recording` of the copy being played on an instrument.
+Beside the kind it holds who carried the capture out, on what device,
+with what software, on which instrument a recorded copy was played,
+when, and a note. What is not known is left out.
 
 This says where the numbers of the edition come from and nothing
 about the state of the paper, which is a condition of the copy. In
 RDF it is `reo:capture`, an activity typed by what it read from; the
 file it produced is `crmdig:L11 had output`, the machine it ran on
-`crmdig:L12 happened on device`.
+`crmdig:L12 happened on device`, the software `crmdig:L23 used
+software or firmware`, the instrument `crm:P16 used specific object`.
 
 Nothing records that a copy is doubtful. `reservationsAbout` works
 out from what a copy states what the edition cannot vouch for in it:
 that it names no source, that the making of its source is
-undocumented, that its features are somebody else's reading, that its
-source bears no physical evidence, that no measuring software is
-recorded, that it is not calibrated. A reservation goes away when the
-gap it names is filled.
+undocumented, that no software or instrument is named for an
+emulation or a recording, that its features are somebody else's
+reading, that its source bears no physical evidence, that no measuring
+software is recorded, that it is not calibrated, that nobody is known
+to hold it. A reservation goes away when the gap it names is filled.
+
+A copy nobody can reach, such as one known only from a recording, has
+no features to carry the symbols of a version. It states instead
+which versions it is held to carry, in `carries`, each under a belief
+that says how certainly and why. `witnessesOf` gathers the copies of a
+version, whether their features carry its symbols or they state that
+they carry it, and `carriageProblems` reports a statement made beside
+features that carry symbols already, or one naming a version the
+edition lacks.
 
 ```ts
 import { reservationsAbout, stateSource } from 'linked-rolls'

package/lib/Assumption.d.ts

@@ -13,6 +13,8 @@ export type Certainty = typeof certainties[number];
  * take a doubted statement for the edition's own.
  */
 export declare const isAsserted: (certainty: Certainty) => boolean;
+/** The certainty a statement is held with. One that carries no belief is stated plainly, and so held true. */
+export declare const certaintyOf: (assumption: Readonly<Assumption>) => Certainty;
 /**
  * An argumentation provides reasons for a belief and
  * may be associated with a person carrying out that argumentation.
@@ -42,11 +44,18 @@ export interface MeaningComprehension extends Argumentation<'meaningComprehensio
  */
 export interface Inference extends Argumentation<'inference'> {
     /**
-     * References (by `@id`) to the beliefs or facts
+     * References (by `@id`) to the beliefs
      * from which the conclusion is drawn.
      * @see crminf:J1 used as premise
      */
     premises: string[];
+    /**
+     * References (by `@id`) to what the inference worked on besides
+     * beliefs, such as the versions it compared or the analysis output
+     * it cites.
+     * @see crm:P16 used specific object
+     */
+    used?: string[];
 }
 /**
  * A belief adoption adopts someone else's belief. This type is used

package/lib/Assumption.js

@@ -12,6 +12,8 @@ export const certainties = [
  * take a doubted statement for the edition's own.
  */
 export const isAsserted = (certainty) => certainty === 'true' || certainty === 'likely';
+/** The certainty a statement is held with. One that carries no belief is stated plainly, and so held true. */
+export const certaintyOf = (assumption) => assumption['@annotation']?.belief.certainty ?? 'true';
 export function valueOf(assumption) {
     return assumption['@value'];
 }

package/lib/EditionView.d.ts

@@ -60,6 +60,7 @@ export declare class EditionView {
     speedScalesIn(version: Readonly<Version>): number[];
     /** The copies of the version's own system that carry any of its symbols. */
     copiesOwning(version: Readonly<Version>): Readonly<RollCopy>[];
+    /** The version the given one's text is read against, by its principal derivation. */
     predecessorOf(versionId: string): Readonly<Version> | undefined;
     /**
      * Where along the roll the symbol lies, as its carriers put it, or

package/lib/EditionView.js

@@ -1,5 +1,5 @@
 import { withBorneFeatures } from "./Feature";
-import { deletedBy, insertedBy } from "./Version";
+import { deletedBy, insertedBy, principalDerivationOf } from "./Version";
 import { systemIdOf } from "./TrackerBar";
 import { isPaperStretch } from "./RollCopy";
 import { idOf, idsOf } from "./Assumption";
@@ -14,7 +14,7 @@ export const getAt = (path, obj) => {
     return node;
 };
 /** Keys under which an object names others by id, singly or in a list. */
-const referenceKeys = ['delete', 'comprehends', 'motivation'];
+const referenceKeys = ['delete', 'comprehends', 'motivation', 'premises', 'used'];
 const isObject = (v) => v !== null && typeof v === "object";
 /** What a reference may state besides the id: a belief about it, and the tolerance a derivation was collated at. */
 const referenceOwnKeys = new Set(['id', '@annotation', 'collationTolerance']);
@@ -138,8 +138,9 @@ export class EditionView {
         if (!v)
             return;
         callback(v);
-        if (v.basedOn) {
-            this.travelUp(idOf(v.basedOn), callback);
+        const principal = principalDerivationOf(v);
+        if (principal) {
+            this.travelUp(idOf(principal), callback);
         }
     }
     /** The version and its ancestors, from the version up to the root. */
@@ -200,11 +201,11 @@ export class EditionView {
         }));
         return this.edition.copies.filter(copy => carrying.has(copy.id) && systemIdOf(copy.production?.system) === system);
     }
+    /** The version the given one's text is read against, by its principal derivation. */
     predecessorOf(versionId) {
         const v = this.get(versionId);
-        if (!v?.basedOn)
-            return;
-        return this.get(idOf(v.basedOn));
+        const principal = v && principalDerivationOf(v);
+        return principal && this.get(idOf(principal));
     }
     /**
      * Where along the roll the symbol lies, as its carriers put it, or
@@ -271,7 +272,8 @@ export class EditionView {
             }
             inStack.add(id);
             let gen;
-            const basedOn = node.basedOn && idOf(node.basedOn);
+            const principal = principalDerivationOf(node);
+            const basedOn = principal && idOf(principal);
             if (basedOn === undefined) {
                 gen = 0; // root
             }

package/lib/FeatureSource.d.ts

@@ -1,20 +1,22 @@
-import { ActorAssignment, DateAssignment } from "./Assumption";
-import { Concept } from "./Agent";
+import { ActorAssignment, DateAssignment, ObjectAssumption } from "./Assumption";
+import { Concept, Named } from "./Agent";
+import { ConditionState } from "./ConditionState";
 import { WithNote } from "./utils";
 /**
  * What a copy's features were read from. The kinds run from the paper
- * itself to a file in which the roll has already been read into notes
- * and commands.
+ * itself, through files in which the roll has already been read into
+ * notes and commands, to a sound recording of the copy being played.
  */
-export declare const sourceKinds: readonly ['roll', 'scan', 'analysis', 'emulation', 'recording'];
+export declare const sourceKinds: readonly ['roll', 'scan', 'analysis', 'reading', 'emulation', 'recording'];
 export type SourceKind = typeof sourceKinds[number];
 /** How each kind of source is referred to in prose. */
 export declare const sourceLabels: Record<SourceKind, string>;
 /**
- * Whether a source of this kind gives positions that were measured.
- * An emulation and a recording give the reading somebody else made:
- * the roll has been turned into notes and commands already, and
- * turning those back into holes reconstructs them.
+ * Whether a source of this kind gives positions that were measured. A
+ * roll reader measures when each perforation passes its bar. An
+ * emulation and a recording give the reading somebody else made: the
+ * roll has been turned into notes and commands already, and turning
+ * those back into holes reconstructs them.
  */
 export declare const isMeasured: (kind: SourceKind) => boolean;
 /**
@@ -23,11 +25,38 @@ export declare const isMeasured: (kind: SourceKind) => boolean;
  * be observed on the roll and on an image of it, and on nothing else.
  */
 export declare const bearsPhysicalEvidence: (kind: SourceKind) => boolean;
+/**
+ * Software a capture ran, such as the transcriber that read a recording
+ * into notes or the emulator that wrote a MIDI file.
+ * @see crmdig:D14 Software
+ */
+export interface Software {
+    /**
+     * @see rdfs:label
+     */
+    name: string;
+    /**
+     * The release, or the model checkpoint of a transcriber.
+     * @see owl:versionInfo
+     */
+    version?: string;
+}
+/**
+ * An instrument a copy was played on to be recorded. How it was
+ * regulated, where that is known, is its condition.
+ * @see crm:E22 Human-Made Object
+ */
+export interface Instrument extends Named {
+    /**
+     * @see crm:P44 has condition
+     */
+    condition?: ObjectAssumption<ConditionState<'general'>>;
+}
 /**
  * The capture by which a copy's features became data: what they were
- * read from, who read them, on what device and when. It states where
- * the numbers of the edition come from and says nothing about the
- * state of the paper, which is a condition.
+ * read from, who read them, on what device, with what software and
+ * when. It states where the numbers of the edition come from and says
+ * nothing about the state of the paper, which is a condition.
  *
  * What is not known is left out. A reader is told about the gap by
  * `reservationsAbout`, which works out what a copy cannot vouch for
@@ -56,6 +85,17 @@ export interface FeatureSource extends WithNote {
      * @see crmdig:L12 happened on device
      */
     device?: Concept;
+    /**
+     * The software the capture ran, each with its version.
+     * @see crmdig:L23 used software or firmware
+     */
+    software?: Software[];
+    /**
+     * The instrument the copy was played on, where the capture is a
+     * recording of it.
+     * @see crm:P16 used specific object
+     */
+    instrument?: ObjectAssumption<Instrument>;
     /**
      * When the capture took place.
      * @format date

package/lib/FeatureSource.js

@@ -1,12 +1,13 @@
 /**
  * What a copy's features were read from. The kinds run from the paper
- * itself to a file in which the roll has already been read into notes
- * and commands.
+ * itself, through files in which the roll has already been read into
+ * notes and commands, to a sound recording of the copy being played.
  */
 export const sourceKinds = [
     'roll',
     'scan',
     'analysis',
+    'reading',
     'emulation',
     'recording'
 ];
@@ -15,16 +16,18 @@ export const sourceLabels = {
     roll: 'the roll itself',
     scan: 'a scan of the roll',
     analysis: 'a hole analysis of a scan',
+    reading: 'the timed switches of a roll reader',
     emulation: 'an emulated MIDI file',
-    recording: 'a MIDI recording of the copy being played'
+    recording: 'a sound recording of the copy being played'
 };
-const measured = ['roll', 'scan', 'analysis'];
+const measured = ['roll', 'scan', 'analysis', 'reading'];
 const physical = ['roll', 'scan'];
 /**
- * Whether a source of this kind gives positions that were measured.
- * An emulation and a recording give the reading somebody else made:
- * the roll has been turned into notes and commands already, and
- * turning those back into holes reconstructs them.
+ * Whether a source of this kind gives positions that were measured. A
+ * roll reader measures when each perforation passes its bar. An
+ * emulation and a recording give the reading somebody else made: the
+ * roll has been turned into notes and commands already, and turning
+ * those back into holes reconstructs them.
  */
 export const isMeasured = (kind) => measured.includes(kind);
 /**

package/lib/RollCopy.d.ts

@@ -3,7 +3,7 @@ import { AnySymbol } from "./Symbol";
 import { TrackerBar } from "./TrackerBar";
 import { TrackCalibration } from "./TrackCalibration";
 import { AnyFeature } from "./Feature";
-import { ActorAssignment, DateAssignment, ObjectAssumption } from "./Assumption";
+import { ActorAssignment, DateAssignment, ObjectAssumption, ReferenceAssumption } from "./Assumption";
 import { WithId, WithType } from "./utils";
 import { Agent, Concept } from "./Agent";
 import { FeatureSource } from "./FeatureSource";
@@ -274,10 +274,11 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      */
     conditions: RollConditionAssignment[];
     /**
-     * The institution or person holding this copy.
+     * The institution or person holding this copy. Left out where it is
+     * not known, as for a copy known only from a recording.
      * @see crm:P50 has current keeper
      */
-    keeper: Agent;
+    keeper?: Agent;
     /**
      * The physical features found on this copy, with shift
      * and stretch already applied when `ops` says so.
@@ -300,6 +301,13 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      * @see reo:capture
      */
     readFrom?: FeatureSource;
+    /**
+     * The versions this copy is held to carry, where its features are not
+     * read into symbols, as for a copy known only from a recording. Each
+     * statement carries the belief it rests on.
+     * @see crm:P128 carries
+     */
+    carries?: ReferenceAssumption[];
 }
 /**
  * Whether the condition is the stretch or shrinkage of the paper. A

package/lib/Version.d.ts

@@ -1,6 +1,6 @@
 import { Edit } from "./Edit";
 import { Concept } from "./Agent";
-import { ActorAssignment, DateAssignment, ReferenceAssumption } from "./Assumption";
+import { ActorAssignment, Certainty, DateAssignment, ReferenceAssumption } from "./Assumption";
 import { CollationTolerance } from "./Collation";
 import { AnySymbol } from "./Symbol";
 import { WithId, WithNote, WithType } from "./utils";
@@ -98,15 +98,20 @@ export interface Version extends WithId, WithType<'Version'> {
     system: Concept;
     /**
      * Whether the version served as a master for reproductions
-     * or exists on one copy only.
+     * or exists on one copy only. Left out where that is not known,
+     * as for a version only a secondary witness hints at.
      * @see crm:P2 has type
      */
-    versionType: VersionType;
+    versionType?: VersionType;
     /**
-     * If no derivation is defined, it is assumed that this version represents the mother roll.
+     * The versions this one is held to derive from, each under the
+     * belief it rests on. The text is read against the principal one
+     * (`principalDerivationOf`); the others stand as hypotheses, such as
+     * a contamination. A version that names none represents the mother
+     * roll.
      * @see lrmoo:R76 is derivative of
      */
-    basedOn?: Derivation;
+    basedOn?: Derivation[];
     /**
      * The act that made this version, where it is known: who carried it
      * out, when, and by what rule.
@@ -114,16 +119,32 @@ export interface Version extends WithId, WithType<'Version'> {
      */
     creation?: VersionCreation;
     /**
-     * The list of edits that, applied to the base version, produce this version.
+     * The list of edits that, applied to the base version, produce this
+     * version. A hypothetical version whose changes nobody can state
+     * leaves it out; it then reads as the version it derives from.
      * @see reo:involvedEdit
      */
-    edits: Edit[];
+    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. */
+export declare const editsOf: (version: Readonly<Version>) => Edit[];
 /** The symbols the version's edits insert. */
 export declare const insertedBy: (version: Readonly<Version>) => AnySymbol[];
 /** The ids of the symbols the version's edits delete. */
 export declare const deletedBy: (version: Readonly<Version>) => string[];
+/** The parents the version names, each with the certainty its derivation is held with. */
+export declare const derivationsOf: (version: Readonly<Version>) => {
+    parent: string;
+    certainty: Certainty;
+}[];
+/**
+ * The derivation the version's text is read against: the first of those
+ * held most certain. One held unlikely or false is a rejected hypothesis
+ * and gives no text. Lowering the certainty of the principal derivation
+ * below another's reads the version's edits against another parent.
+ */
+export declare const principalDerivationOf: (version: Readonly<Version>) => Readonly<Derivation> | undefined;

package/lib/Version.js

@@ -1,3 +1,4 @@
+import { certainties, certaintyOf, idOf } from "./Assumption";
 import { defaultCollationTolerance } from "./Collation";
 export const versionTypes = [
     /**
@@ -12,7 +13,21 @@ export const versionTypes = [
 ];
 /** The tolerance the derivation was collated at, or the default where it states none. */
 export const collationToleranceOf = (derivation) => derivation.collationTolerance ?? defaultCollationTolerance;
+/** The edits the version states, none where it leaves its text unstated. */
+export const editsOf = (version) => version.edits ?? [];
 /** The symbols the version's edits insert. */
-export const insertedBy = (version) => version.edits.flatMap(edit => edit.insert ?? []);
+export const insertedBy = (version) => editsOf(version).flatMap(edit => edit.insert ?? []);
 /** The ids of the symbols the version's edits delete. */
-export const deletedBy = (version) => version.edits.flatMap(edit => edit.delete ?? []);
+export const deletedBy = (version) => editsOf(version).flatMap(edit => edit.delete ?? []);
+/** The parents the version names, each with the certainty its derivation is held with. */
+export const derivationsOf = (version) => (version.basedOn ?? []).map(derivation => ({ parent: idOf(derivation), certainty: certaintyOf(derivation) }));
+const rankOf = (derivation) => certainties.indexOf(certaintyOf(derivation));
+/**
+ * The derivation the version's text is read against: the first of those
+ * held most certain. One held unlikely or false is a rejected hypothesis
+ * and gives no text. Lowering the certainty of the principal derivation
+ * below another's reads the version's edits against another parent.
+ */
+export const principalDerivationOf = (version) => (version.basedOn ?? [])
+    .filter(derivation => rankOf(derivation) <= certainties.indexOf('possible'))
+    .reduce((principal, derivation) => principal === undefined || rankOf(derivation) < rankOf(principal) ? derivation : principal, undefined);

package/lib/asJsonLd.js

@@ -1,5 +1,5 @@
 import { systemIdIn } from "./TrackerBar";
-import { isAsserted } from "./Assumption";
+import { certaintyOf, isAsserted } from "./Assumption";
 import context from "./spec/context.json";
 export const exportDate = (date) => {
     const year = date.getFullYear();
@@ -76,7 +76,7 @@ const silentTerms = new Set(Object.entries(context['@context'])
 const isDoubtedReference = (value) => isRecord(value)
     && typeof value['@id'] === 'string'
     && isRecord(value['@annotation'])
-    && !isAsserted(value['@annotation'].belief?.certainty ?? 'true')
+    && !isAsserted(certaintyOf(value))
     && Object.keys(value).every(key => key === '@id' || key === '@annotation' || silentTerms.has(key));
 /**
  * The statement a doubted reference makes, as a JSON-LD-star embedded

package/lib/editionOps.d.ts

@@ -6,7 +6,7 @@ import { CollationTolerance } from "./Collation";
 import { Edit } from "./Edit";
 import { GeneralRollCondition, RollCopy, ScaleReading, Shift } from "./RollCopy";
 import { FeatureSource } from "./FeatureSource";
-import { AnyArgumentation, Certainty, ObjectAssumption } from "./Assumption";
+import { AnyArgumentation, Belief, Certainty, ObjectAssumption } from "./Assumption";
 import { AnyFeature, FeatureConditionAssignment } from "./Feature";
 /**
  * A change to an edition, written onto an immer draft of it. One
@@ -22,6 +22,12 @@ export type EditionOp = (draft: Draft<Edition>) => void;
  * system the copy was cut for.
  */
 export declare const createVersion: (siglum: string, 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,
@@ -38,6 +44,16 @@ export declare const unalignCopy: (copyId: string) => EditionOp;
 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;
+/**
+ * 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
@@ -99,7 +115,8 @@ export declare const mergeFeatures: (copyId: string, featureIds: readonly string
  * 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 declare const connectVersions: (view: EditionView, childId: string, parentId: string, tolerance?: CollationTolerance) => EditionOp;
 /**
@@ -110,16 +127,30 @@ export declare const connectVersions: (view: EditionView, childId: string, paren
 export declare const collateSymbols: (view: EditionView, versionId: string, symbolIds: readonly string[], tolerance?: CollationTolerance) => EditionOp;
 /**
  * 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 declare const detachVersion: (view: EditionView, versionId: string) => EditionOp;
-/** 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 declare const removeVersion: (view: EditionView, versionId: string) => EditionOp;
 /** Takes the symbols out of the version's own insertions, and the edits that had nothing else. */
 export declare const removeSymbols: (versionId: string, symbolIds: readonly string[]) => EditionOp;
 /** Moves the edits into a new version based on this one. */
 export declare const deriveVersion: (versionId: string, editIds: readonly string[]) => EditionOp;
+/**
+ * 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 declare const stateDerivation: (versionId: string, parentId: string, belief?: Belief) => EditionOp;
+/** Takes back the hypothesis that the version derives from the parent; the principal derivation goes with `detachVersion`. */
+export declare const clearDerivation: (versionId: string, parentId: string) => EditionOp;
 /**
  * Replaces the edits with a single one carrying all their insertions
  * and deletions, classified by a guess at what the exchange does.