linked-rolls 0.25.1 → 0.27.0

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": {
@@ -2161,7 +2285,6 @@
                 "conditions",
                 "features",
                 "@id",
-                "keeper",
                 "measurements",
                 "modifications",
                 "ops",
@@ -2188,11 +2311,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"
             ],
@@ -2270,8 +2413,11 @@
             "description": "A version is defined by the sum of edits applied to the version it is based on. For simple identification, a siglum is given to each version.",
             "properties": {
                 "basedOn": {
-                    "$ref": "#/definitions/Derivation",
-                    "description": "If no derivation is defined, it is assumed that this version represents the mother roll.",
+                    "description": "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.",
+                    "items": {
+                        "$ref": "#/definitions/Derivation"
+                    },
+                    "type": "array",
                     "ontology": "lrmoo:R76 is derivative of"
                 },
                 "creation": {
@@ -2280,7 +2426,7 @@
                     "ontology": "lrmoo:R17i was created by"
                 },
                 "edits": {
-                    "description": "The list of edits that, applied to the base version, produce this version.",
+                    "description": "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.",
                     "items": {
                         "$ref": "#/definitions/Edit"
                     },
@@ -2306,7 +2452,7 @@
                 },
                 "versionType": {
                     "$ref": "#/definitions/VersionType",
-                    "description": "Whether the version served as a master for reproductions or exists on one copy only.",
+                    "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": {
@@ -2321,13 +2467,11 @@
                 }
             },
             "required": [
-                "edits",
                 "@id",
                 "motivations",
                 "siglum",
                 "system",
-                "@type",
-                "versionType"
+                "@type"
             ],
             "type": "object",
             "ontology": "lrmoo:F2 Expression"

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,33 @@
+import { 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 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[];
+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,48 @@
+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) => ({ copy: copy.id, by: 'statement', certainty: certaintyOf(statement) })));
+    return [...byCarriers, ...byStatement];
+};
+/**
+ * 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.25.1",
+  "version": "0.27.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {