linked-rolls 0.26.0 → 0.28.0

package/README.md

@@ -60,24 +60,40 @@ derivation loads as a list of one.
 
 `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, a statement with the belief it rests on;
+`versionsWitnessedBy` gathers the same from the side of a copy.
+`carriageProblems` reports a statement made beside features that carry
+symbols already, or one naming a version the edition lacks. A copy may
+carry a `siglum`, as a version does; one without is named by its
+keeper.
 
 ```ts
 import { reservationsAbout, stateSource } from 'linked-rolls'

package/lib/Assumption.d.ts

@@ -44,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/EditionView.js

@@ -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']);

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,17 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      */
     conditions: RollConditionAssignment[];
     /**
-     * The institution or person holding this copy.
+     * A short siglum to identify the copy, e.g. "W1" or "S2". A copy
+     * without one is named by its keeper.
+     * @see reo:siglum
+     */
+    siglum?: string;
+    /**
+     * 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 +307,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, Certainty, DateAssignment, ReferenceAssumption } from "./Assumption";
+import { ActorAssignment, Belief, Certainty, DateAssignment, ReferenceAssumption } from "./Assumption";
 import { CollationTolerance } from "./Collation";
 import { AnySymbol } from "./Symbol";
 import { WithId, WithNote, WithType } from "./utils";
@@ -136,10 +136,14 @@ export declare const editsOf: (version: Readonly<Version>) => Edit[];
 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. */
+/**
+ * The parents the version names, in the order of `basedOn`, each with the
+ * certainty its derivation is held with and the belief it rests on.
+ */
 export declare const derivationsOf: (version: Readonly<Version>) => {
     parent: string;
     certainty: Certainty;
+    belief?: Belief;
 }[];
 /**
  * The derivation the version's text is read against: the first of those

package/lib/Version.js

@@ -19,8 +19,14 @@ export const editsOf = (version) => version.edits ?? [];
 export const insertedBy = (version) => editsOf(version).flatMap(edit => edit.insert ?? []);
 /** The ids of the symbols the version's edits 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) }));
+/**
+ * The parents the version names, in the order of `basedOn`, each with the
+ * certainty its derivation is held with and the belief it rests on.
+ */
+export const derivationsOf = (version) => (version.basedOn ?? []).map(derivation => {
+    const belief = derivation['@annotation']?.belief;
+    return { parent: idOf(derivation), certainty: certaintyOf(derivation), ...(belief && { belief }) };
+});
 const rankOf = (derivation) => certainties.indexOf(certaintyOf(derivation));
 /**
  * The derivation the version's text is read against: the first of those

package/lib/editionOps.d.ts

@@ -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,18 @@ 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;
+/** 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;
+/**
+ * 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
@@ -117,7 +135,8 @@ export declare const collateSymbols: (view: EditionView, versionId: string, symb
 export declare const detachVersion: (view: EditionView, versionId: string) => EditionOp;
 /**
  * Takes the version out. Whatever read its text against it comes to
- * stand on its own, and a hypothesis that something derives from it goes.
+ * 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. */

package/lib/editionOps.js

@@ -88,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') {
@@ -127,6 +135,47 @@ export const stateSource = (copyId, source) => onCopy(copyId, copy => {
 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;
+});
+/** 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
@@ -484,8 +533,8 @@ const dropDerivations = (version, matches) => {
     const derivations = stateOf(version).basedOn;
     if (!derivations?.some(matches))
         return;
-    const kept = derivations.filter(derivation => !matches(derivation));
-    if (kept.length > 0)
+    const kept = withoutReferences(derivations, matches);
+    if (kept)
         version.basedOn = kept;
     else
         delete version.basedOn;
@@ -572,15 +621,18 @@ export const detachVersion = (view, versionId) => {
 };
 /**
  * Takes the version out. Whatever read its text against it comes to
- * stand on its own, and a hypothesis that something derives from it goes.
+ * 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 => 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, derivation => idOf(derivation) === versionId));
+        draft.versions.forEach(version => dropDerivations(version, namesIt));
+        draft.copies.forEach(copy => dropStatements(copy, namesIt));
         draft.versions = without(draft.versions, version => version.id === versionId);
     };
 };
@@ -614,10 +666,7 @@ export const stateDerivation = (versionId, parentId, belief) => onVersion(versio
     const derivations = stateOf(version).basedOn ?? [];
     if (parentId === versionId || derivations.some(derivation => idOf(derivation) === parentId))
         return;
-    version.basedOn = [
-        ...derivations,
-        { ...assignReference(parentId), ...(belief && { '@annotation': { id: v4(), belief } }) }
-    ];
+    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 => {

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

@@ -72,7 +72,24 @@ const withScale = (node) => {
 /** 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;
-const migrateNode = (node) => [withRenamedKeys, withTypology, withReferences, withKeeper, withProductionNodes, withScale, withDerivationList]
+/**
+ * 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) => {

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,6 +1,7 @@
 import { RollCopy } from "./RollCopy";
 import { Version } from "./Version";
-export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated', 'system-unknown'];
+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 or
@@ -20,10 +21,10 @@ export interface Reservation<T extends string = ReservationType> {
 /**
  * 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'];
+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: (version: Readonly<Version>) => Reservation<VersionReservationType>[];
+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,33 +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'
+    'type-not-stated',
+    'witnessed-by-statement-only'
 ];
-const textStated = version => version.edits ? undefined : {
+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 = version => version.versionType ? undefined : {
+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 versionChecks = [textStated, typeStated];
+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 = (version) => versionChecks.flatMap(check => check(version) ?? []);
+export const reservationsAboutVersion = (view, version) => versionChecks.flatMap(check => check(view, version) ?? []);

package/lib/schema.json

@@ -628,7 +628,7 @@
             "ontology": "reo:scope"
         },
         "FeatureSource": {
-            "description": "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.\n\nWhat is not known is left out. A reader is told about the gap by `reservationsAbout`, which works out what a copy cannot vouch for from what it states here.",
+            "description": "The capture by which a copy's features became data: what they were 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.\n\nWhat is not known is left out. A reader is told about the gap by `reservationsAbout`, which works out what a copy cannot vouch for from what it states here.",
             "properties": {
                 "actor": {
                     "$ref": "#/definitions/ActorAssignment",
@@ -646,6 +646,11 @@
                     "description": "The make and model of the scanner, camera or player the capture ran on.",
                     "ontology": "crmdig:L12 happened on device"
                 },
+                "instrument": {
+                    "$ref": "#/definitions/ObjectAssumption%3CInstrument%3E",
+                    "description": "The instrument the copy was played on, where the capture is a recording of it.",
+                    "ontology": "crm:P16 used specific object"
+                },
                 "kind": {
                     "$ref": "#/definitions/SourceKind",
                     "description": "What the features were read from.",
@@ -660,6 +665,14 @@
                     "description": "The file the capture produced, where it has an address.",
                     "type": "string",
                     "ontology": "crmdig:L11 had output"
+                },
+                "software": {
+                    "description": "The software the capture ran, each with its version.",
+                    "items": {
+                        "$ref": "#/definitions/Software"
+                    },
+                    "type": "array",
+                    "ontology": "crmdig:L23 used software or firmware"
                 }
             },
             "required": [
@@ -823,13 +836,21 @@
                     "ontology": "crm:P3 has note"
                 },
                 "premises": {
-                    "description": "References (by `@id`) to the beliefs or facts from which the conclusion is drawn.",
+                    "description": "References (by `@id`) to the beliefs from which the conclusion is drawn.",
                     "items": {
                         "type": "string"
                     },
                     "type": "array",
                     "ontology": "crminf:J1 used as premise"
                 },
+                "used": {
+                    "description": "References (by `@id`) to what the inference worked on besides beliefs, such as the versions it compared or the analysis output it cites.",
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array",
+                    "ontology": "crm:P16 used specific object"
+                },
                 "@type": {
                     "const": "inference",
                     "type": "string",
@@ -1312,6 +1333,52 @@
             ],
             "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain."
         },
+        "ObjectAssumption<ConditionState<\"general\">>": {
+            "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain.",
+            "properties": {
+                "@annotation": {
+                    "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                    "properties": {
+                        "belief": {
+                            "$ref": "#/definitions/Belief",
+                            "description": "The belief held about the annotated statement.",
+                            "ontology": "crminf:J4i is subject of"
+                        },
+                        "@id": {
+                            "description": "A unique identifier for this object.",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "belief",
+                        "@id"
+                    ],
+                    "type": "object"
+                },
+                "conditionType": {
+                    "const": "general",
+                    "description": "The kind of condition, from the list the roll or the kind of feature allows.",
+                    "type": "string",
+                    "ontology": "crm:P2 has type"
+                },
+                "description": {
+                    "description": "A free-text description of the condition, providing details beyond the type classification.",
+                    "type": "string",
+                    "ontology": "crm:P3 has note"
+                },
+                "@type": {
+                    "const": "ConditionState",
+                    "description": "The type discriminator for this object.",
+                    "type": "string",
+                    "ontology": "rdf:type"
+                }
+            },
+            "required": [
+                "conditionType",
+                "@type"
+            ],
+            "type": "object"
+        },
         "ObjectAssumption<ConditionState<(\"detaching\"|\"ripped\")>>": {
             "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain.",
             "properties": {
@@ -1502,6 +1569,55 @@
             ],
             "type": "object"
         },
+        "ObjectAssumption<Instrument>": {
+            "description": "An object assumption wraps a complex object with an optional annotation. Used for structured values (e.g. persons, conditions) whose properties may be uncertain.",
+            "properties": {
+                "@annotation": {
+                    "description": "An optional annotation expressing a belief about this assumption. Uses the JSON-LD-star `@annotation` mechanism to attach epistemic metadata (certainty and reasons) to any triple.",
+                    "properties": {
+                        "belief": {
+                            "$ref": "#/definitions/Belief",
+                            "description": "The belief held about the annotated statement.",
+                            "ontology": "crminf:J4i is subject of"
+                        },
+                        "@id": {
+                            "description": "A unique identifier for this object.",
+                            "type": "string"
+                        }
+                    },
+                    "required": [
+                        "belief",
+                        "@id"
+                    ],
+                    "type": "object"
+                },
+                "condition": {
+                    "$ref": "#/definitions/ObjectAssumption%3CConditionState%3C%22general%22%3E%3E",
+                    "ontology": "crm:P44 has condition"
+                },
+                "name": {
+                    "description": "The name, e.g. \"Grünfeld, Alfred\", \"Wien\", \"M. Welte & Söhne\".",
+                    "type": "string",
+                    "ontology": "rdfs:label"
+                },
+                "sameAs": {
+                    "description": "Authority records for the same thing: GND, Wikidata, geonames or similar.",
+                    "examples": [
+                        "https://d-nb.info/gnd/116888652"
+                    ],
+                    "items": {
+                        "type": "string"
+                    },
+                    "type": "array",
+                    "ontology": "owl:sameAs"
+                }
+            },
+            "required": [
+                "name",
+                "sameAs"
+            ],
+            "type": "object"
+        },
         "ObjectAssumption<PaperSpeed>": {
             "anyOf": [
                 {
@@ -1984,6 +2100,14 @@
         "RollCopy": {
             "description": "A physical copy of a roll, held at a specific location. Each roll copy has its own set of features, measurements, conditions, and modifications. Multiple copies of the same roll may exist across different archives or collections.",
             "properties": {
+                "carries": {
+                    "description": "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.",
+                    "items": {
+                        "$ref": "#/definitions/ReferenceAssumption"
+                    },
+                    "type": "array",
+                    "ontology": "crm:P128 carries"
+                },
                 "conditions": {
                     "description": "Condition assessments of this roll copy (e.g. paper stretch, general wear). Each condition is an assumption annotatable with a belief.",
                     "items": {
@@ -2002,7 +2126,7 @@
                 },
                 "keeper": {
                     "$ref": "#/definitions/Agent",
-                    "description": "The institution or person holding this copy.",
+                    "description": "The institution or person holding this copy. Left out where it is not known, as for a copy known only from a recording.",
                     "ontology": "crm:P50 has current keeper"
                 },
                 "measurements": {
@@ -2146,6 +2270,11 @@
                     "type": "string",
                     "ontology": "crm:P138i has representation"
                 },
+                "siglum": {
+                    "description": "A short siglum to identify the copy, e.g. \"W1\" or \"S2\". A copy without one is named by its keeper.",
+                    "type": "string",
+                    "ontology": "reo:siglum"
+                },
                 "@id": {
                     "description": "A unique identifier for this object.",
                     "type": "string"
@@ -2161,7 +2290,6 @@
                 "conditions",
                 "features",
                 "@id",
-                "keeper",
                 "measurements",
                 "modifications",
                 "ops",
@@ -2188,11 +2316,31 @@
             ],
             "type": "object"
         },
+        "Software": {
+            "description": "Software a capture ran, such as the transcriber that read a recording into notes or the emulator that wrote a MIDI file.",
+            "properties": {
+                "name": {
+                    "type": "string",
+                    "ontology": "rdfs:label"
+                },
+                "version": {
+                    "description": "The release, or the model checkpoint of a transcriber.",
+                    "type": "string",
+                    "ontology": "owl:versionInfo"
+                }
+            },
+            "required": [
+                "name"
+            ],
+            "type": "object",
+            "ontology": "crmdig:D14 Software"
+        },
         "SourceKind": {
             "enum": [
                 "roll",
                 "scan",
                 "analysis",
+                "reading",
                 "emulation",
                 "recording"
             ],

package/lib/spec/context.json

@@ -60,7 +60,13 @@
         },
         "inference": {
             "@id": "crminf:I5_Inference_Making",
-            "@context": { "note": "crm:P3_has_note" }
+            "@context": {
+                "note": "crm:P3_has_note",
+                "used": {
+                    "@id": "crm:P16_used_specific_object",
+                    "@type": "@id"
+                }
+            }
         },
         "beliefAdoption": {
             "@id": "crminf:I7_Belief_Adoption",
@@ -168,6 +174,7 @@
         "factor": "rdf:value",
         "keeper": "crm:P50_has_current_keeper",
         "features": "crm:P56_bears_feature",
+        "carries": "crm:P128_carries",
         "modifications": "crm:P31i_was_modified_by",
         "scan": {
             "@id": "crm:P138i_has_representation",
@@ -190,6 +197,11 @@
                     "@type": "@id"
                 },
                 "device": "crmdig:L12_happened_on_device",
+                "software": {
+                    "@id": "crmdig:L23_used_software_or_firmware",
+                    "@context": { "version": "owl:versionInfo" }
+                },
+                "instrument": "crm:P16_used_specific_object",
                 "note": "crm:P3_has_note"
             }
         },

package/lib/witnesses.d.ts

@@ -0,0 +1,42 @@
+import { Belief, Certainty } from "./Assumption";
+import { EditionView } from "./EditionView";
+export type WitnessBy = 'carriers' | 'statement';
+/** A copy that bears witness to a version, and how. */
+export interface Witness {
+    /** The copy, by id. */
+    copy: string;
+    /** Whether the copy's features carry what the version inserts, or the copy states that it carries the version. */
+    by: WitnessBy;
+    /** How certainly a statement is held. Carriage through features is no statement and holds none. */
+    certainty?: Certainty;
+    /** The belief a statement rests on, where it states one. */
+    belief?: Belief;
+}
+/**
+ * The copies that bear witness to the version: those whose features carry
+ * a symbol the version's own edits insert, and those that state they carry
+ * it, with the certainty each statement is held with.
+ *
+ * What a version inherits is carried by nearly every copy of the roll, so
+ * only what it inserts tells its witnesses apart. A version whose edits
+ * are not stated is witnessed by statement alone.
+ */
+export declare const witnessesOf: (view: EditionView, versionId: string) => Witness[];
+/**
+ * The versions the copy bears witness to, each with how, in the order the
+ * edition lists its versions.
+ */
+export declare const versionsWitnessedBy: (view: EditionView, copyId: string) => (Witness & {
+    version: string;
+})[];
+export type CarriageProblem = {
+    copy: string;
+    version: string;
+    problem: 'stated-beside-carriers' | 'version-missing';
+};
+/**
+ * Where a copy's statement that it carries a version cannot stand: one
+ * made although the copy's features carry symbols, which say by
+ * themselves what it carries, and one naming a version the edition lacks.
+ */
+export declare const carriageProblems: (view: EditionView) => CarriageProblem[];

package/lib/witnesses.js

@@ -0,0 +1,58 @@
+import { certaintyOf, idOf, idsOf } from "./Assumption";
+import { insertedBy } from "./Version";
+/** The copies whose features carry any of the symbols. */
+const copiesCarrying = (view, symbols) => new Set(symbols
+    .flatMap(symbol => idsOf(symbol.carriers))
+    .flatMap(id => {
+    const copy = view.copyOf(id);
+    return copy ? [copy.id] : [];
+}));
+/**
+ * The copies that bear witness to the version: those whose features carry
+ * a symbol the version's own edits insert, and those that state they carry
+ * it, with the certainty each statement is held with.
+ *
+ * What a version inherits is carried by nearly every copy of the roll, so
+ * only what it inserts tells its witnesses apart. A version whose edits
+ * are not stated is witnessed by statement alone.
+ */
+export const witnessesOf = (view, versionId) => {
+    const version = view.get(versionId);
+    if (!version)
+        return [];
+    const carrying = copiesCarrying(view, insertedBy(version));
+    const byCarriers = view.edition.copies
+        .filter(copy => carrying.has(copy.id))
+        .map((copy) => ({ copy: copy.id, by: 'carriers' }));
+    const byStatement = view.edition.copies
+        .filter(copy => !carrying.has(copy.id))
+        .flatMap(copy => (copy.carries ?? [])
+        .filter(statement => idOf(statement) === versionId)
+        .map((statement) => {
+        const belief = statement['@annotation']?.belief;
+        return { copy: copy.id, by: 'statement', certainty: certaintyOf(statement), ...(belief && { belief }) };
+    }));
+    return [...byCarriers, ...byStatement];
+};
+/**
+ * The versions the copy bears witness to, each with how, in the order the
+ * edition lists its versions.
+ */
+export const versionsWitnessedBy = (view, copyId) => view.edition.versions.flatMap(version => witnessesOf(view, version.id)
+    .filter(witness => witness.copy === copyId)
+    .map(witness => ({ ...witness, version: version.id })));
+/**
+ * Where a copy's statement that it carries a version cannot stand: one
+ * made although the copy's features carry symbols, which say by
+ * themselves what it carries, and one naming a version the edition lacks.
+ */
+export const carriageProblems = (view) => {
+    const carrying = copiesCarrying(view, view.edition.versions.flatMap(insertedBy));
+    return view.edition.copies.flatMap(copy => (copy.carries ?? []).flatMap((statement) => {
+        const version = idOf(statement);
+        return [
+            ...(carrying.has(copy.id) ? [{ copy: copy.id, version, problem: 'stated-beside-carriers' }] : []),
+            ...(view.get(version)?.type === 'Version' ? [] : [{ copy: copy.id, version, problem: 'version-missing' }])
+        ];
+    }));
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {