linked-rolls 0.27.0 → 0.29.0

package/README.md

@@ -88,9 +88,12 @@ 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.
+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/RollCopy.d.ts

@@ -273,6 +273,12 @@ export interface RollCopy extends WithType<'RollCopy'>, WithId {
      * @see crm:P44 has condition
      */
     conditions: RollConditionAssignment[];
+    /**
+     * 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.

package/lib/Version.d.ts

@@ -1,25 +1,9 @@
 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";
-export declare const versionTypes: readonly [
-/**
- * The roll is in a state where it is (possibly) used as
- * the master roll for several new reproductions.
- */
-'edition', 
-/**
- * A version that exists only on one specific copy of a roll.
- */
-'unicum'];
-/**
- * The type of a version. An 'edition' version may serve as the
- * master for several roll copies; a 'unicum' version exists only
- * on one specific copy.
- */
-export type VersionType = typeof versionTypes[number];
 /**
  * A motivation provides a reason or rationale for an editorial change.
  * Motivations are defined at the version level and referenced by edits.
@@ -96,13 +80,6 @@ export interface Version extends WithId, WithType<'Version'> {
      * @see crm:P2 has type
      */
     system: Concept;
-    /**
-     * Whether the version served as a master for reproductions
-     * 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;
     /**
      * The versions this one is held to derive from, each under the
      * belief it rests on. The text is read against the principal one
@@ -136,10 +113,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

@@ -1,16 +1,5 @@
 import { certainties, certaintyOf, idOf } from "./Assumption";
 import { defaultCollationTolerance } from "./Collation";
-export const versionTypes = [
-    /**
-     * The roll is in a state where it is (possibly) used as
-     * the master roll for several new reproductions.
-     */
-    'edition',
-    /**
-     * A version that exists only on one specific copy of a roll.
-     */
-    'unicum'
-];
 /** 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. */
@@ -19,8 +8,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

@@ -44,6 +44,8 @@ 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

package/lib/editionOps.js

@@ -83,7 +83,6 @@ export const createVersion = (siglum, copy) => draft => {
         id: v4(),
         siglum,
         system: systemOf(bar),
-        versionType: 'edition',
         edits: asSymbols(copy.features, bar).map(insertion),
         motivations: []
     });
@@ -135,6 +134,14 @@ 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. */
@@ -641,7 +648,6 @@ export const deriveVersion = (versionId, editIds) => onVersion(versionId, (versi
         id: v4(),
         siglum: `${version.siglum}_derived`,
         system: stateOf(version).system,
-        versionType: 'unicum',
         basedOn: [assignReference(versionId)],
         edits: moved,
         motivations: []

package/lib/migrate.js

@@ -3,8 +3,7 @@ import { rollConditions } from "./RollCopy";
 import { systemIdIn, systemOf, translationBetween } from "./TrackerBar";
 import { trackerBars } from "./systems";
 import { welteT100 } from "./systems/welteT100/bar";
-import { versionTypes } from "./Version";
-const versionTypeValues = new Set(versionTypes);
+const retiredVersionTypes = new Set(['edition', 'unicum']);
 const conditionTypeValues = new Set([...rollConditions, ...Object.values(conditions).flat()]);
 const renamedKeys = {
     productionEvent: 'production',
@@ -17,14 +16,21 @@ const withRenamedKeys = (node) => Object.keys(node).some(key => Object.hasOwn(re
     ? Object.fromEntries(Object.entries(node).map(([key, value]) => [renamedKeys[key] ?? key, value]))
     : node;
 const withTypology = (node) => {
-    if (versionTypeValues.has(node['@type'])) {
-        return { ...node, '@type': 'Version', versionType: node['@type'] };
+    if (retiredVersionTypes.has(node['@type'])) {
+        return { ...node, '@type': 'Version' };
     }
     if (conditionTypeValues.has(node['@type'])) {
         return { ...node, '@type': 'ConditionState', conditionType: node['@type'] };
     }
     return node;
 };
+/** A version once stated whether it served as a master or stood on one copy. */
+const withoutVersionType = (node) => {
+    if (!Object.hasOwn(node, 'versionType'))
+        return node;
+    const { versionType: _retired, ...rest } = node;
+    return rest;
+};
 const withReferences = (node) => referenceKeys.reduce((result, key) => {
     const reference = result[key];
     if (reference && typeof reference === 'object' && '@value' in reference) {
@@ -88,7 +94,7 @@ const withoutEmptyKeeper = (node) => {
     const { keeper: _unnamed, ...rest } = node;
     return rest;
 };
-const migrateNode = (node) => [withRenamedKeys, withTypology, withReferences, withKeeper, withoutEmptyKeeper, withProductionNodes, withScale,
+const migrateNode = (node) => [withRenamedKeys, withTypology, withoutVersionType, 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. */

package/lib/reservations.d.ts

@@ -24,7 +24,7 @@ export interface Reservation<T extends string = ReservationType> {
  * 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 declare const versionReservationTypes: readonly ['text-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

@@ -102,17 +102,12 @@ const checks = [
 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') ? {
@@ -120,6 +115,6 @@ const witnessedByFeatures = (view, version) => {
         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];
+const versionChecks = [textStated, 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) ?? []);

package/lib/schema.json

@@ -2270,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"
@@ -2450,11 +2455,6 @@
                     "description": "The reproducing system this version is coded for. One roll was often issued for several of them, and a version is a reading in one system's words: its expression types are that system's vocabulary and its notes sit on that bar's positions. A system the type vocabulary knows carries the IRI of its concept as `id`, from which the export takes the system's own context.",
                     "ontology": "crm:P2 has type"
                 },
-                "versionType": {
-                    "$ref": "#/definitions/VersionType",
-                    "description": "Whether the version served as a master for reproductions or exists on one copy only. Left out where that is not known, as for a version only a secondary witness hints at.",
-                    "ontology": "crm:P2 has type"
-                },
                 "@id": {
                     "description": "A unique identifier for this object.",
                     "type": "string"
@@ -2498,14 +2498,6 @@
             "type": "object",
             "ontology": "lrmoo:F28 Expression Creation"
         },
-        "VersionType": {
-            "description": "The type of a version. An 'edition' version may serve as the master for several roll copies; a 'unicum' version exists only on one specific copy.",
-            "enum": [
-                "edition",
-                "unicum"
-            ],
-            "type": "string"
-        },
         "VerticalSpan": {
             "description": "Describes the vertical extent of a feature on the roll, measured in track numbers. Track numbers correspond to positions on the tracker bar.",
             "properties": {

package/lib/spec/context.json

@@ -249,11 +249,6 @@
             "@context": { "@vocab": "https://w3id.org/reo/type/" }
         },
         "siglum": "reo:siglum",
-        "versionType": {
-            "@id": "crm:P2_has_type",
-            "@type": "@vocab",
-            "@context": { "@vocab": "https://w3id.org/reo/type/" }
-        },
         "basedOn": "lrmoo:R76_is_derivative_of",
         "edits": "reo:involvedEdit",
         "motivations": "@included",

package/lib/witnesses.d.ts

@@ -1,4 +1,4 @@
-import { Certainty } from "./Assumption";
+import { Belief, Certainty } from "./Assumption";
 import { EditionView } from "./EditionView";
 export type WitnessBy = 'carriers' | 'statement';
 /** A copy that bears witness to a version, and how. */
@@ -9,6 +9,8 @@ export interface Witness {
     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
@@ -20,6 +22,13 @@ export interface Witness {
  * 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;

package/lib/witnesses.js

@@ -28,9 +28,19 @@ export const witnessesOf = (view, versionId) => {
         .filter(copy => !carrying.has(copy.id))
         .flatMap(copy => (copy.carries ?? [])
         .filter(statement => idOf(statement) === versionId)
-        .map((statement) => ({ copy: copy.id, by: 'statement', certainty: certaintyOf(statement) })));
+        .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

package/package.json

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