linked-rolls 0.25.0 → 0.26.0

package/README.md

@@ -24,6 +24,16 @@ https://pfefferniels.github.io/linked-rolls/reo/; the w3id.org
 identifiers are not registered yet. `ontology/README.md` records the
 naming decisions.
 
+Beliefs travel as JSON-LD-star annotations (`@annotation`), which state
+the triple they annotate. A reference the edition holds possible,
+unlikely or false is therefore written as an embedded node beside the
+document: RDF names the statement without stating it, and
+`importJsonLd` puts it back where it stood. A doubted value, such as a
+date or an attribution, stays annotated in place for now. Reading the
+beliefs needs a processor that implements JSON-LD-star, such as the
+Ruby `json-ld` gem; jsonld.js ignores `@annotation`, and every belief
+with it.
+
 ## Format revisions
 
 Files written by linked-rolls 0.1 load unchanged: `importJsonLd`
@@ -33,6 +43,19 @@ 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

package/lib/Assumption.d.ts

@@ -6,6 +6,15 @@ export declare const certainties: readonly ['true', 'likely', 'possible', 'unlik
  * and some values in between.
  */
 export type Certainty = typeof certainties[number];
+/**
+ * Whether a statement held with this certainty is stated as a fact when
+ * the edition is read as RDF. One held possible, unlikely or false is
+ * only quoted, so that a reader who leaves the beliefs aside does not
+ * 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.

package/lib/Assumption.js

@@ -5,6 +5,15 @@ export const certainties = [
     'unlikely',
     'false'
 ];
+/**
+ * Whether a statement held with this certainty is stated as a fact when
+ * the edition is read as RDF. One held possible, unlikely or false is
+ * only quoted, so that a reader who leaves the beliefs aside does not
+ * 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";
@@ -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/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,4 +1,6 @@
 import { systemIdIn } from "./TrackerBar";
+import { certaintyOf, isAsserted } from "./Assumption";
+import context from "./spec/context.json";
 export const exportDate = (date) => {
     const year = date.getFullYear();
     const month = String(date.getMonth() + 1).padStart(2, "0");
@@ -62,9 +64,76 @@ const withSystemContexts = (node) => {
         ? { '@context': `https://w3id.org/reo/${system}/context.jsonld`, ...walked }
         : walked;
 };
+const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Terms the context sets to null, which say nothing when the edition is read as RDF. */
+const silentTerms = new Set(Object.entries(context['@context'])
+    .filter(([, definition]) => definition === null)
+    .map(([term]) => term));
+/**
+ * A reference its belief does not hold to be so: it names a node, states
+ * nothing RDF would read besides, and its belief is below likely.
+ */
+const isDoubtedReference = (value) => isRecord(value)
+    && typeof value['@id'] === 'string'
+    && isRecord(value['@annotation'])
+    && !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
+ * node: the triple is named without being stated, and the belief is
+ * about it. The annotation's own id goes along under a key RDF does not
+ * read, so that an import can put it back.
+ */
+const quote = (subject, key, reference, listed) => {
+    const { '@annotation': { '@id': annotation, ...about }, ...object } = reference;
+    return { '@id': { '@id': subject, [key]: listed ? [object] : object }, annotation, ...about };
+};
+/** The value a node states under a key, less the doubted references, and those references quoted. */
+const quotingValue = (subject, key, value) => {
+    if (Array.isArray(value)) {
+        return {
+            node: value.filter(item => !isDoubtedReference(item)),
+            quoted: value.filter(isDoubtedReference).map(item => quote(subject, key, item, true))
+        };
+    }
+    return isDoubtedReference(value)
+        ? { node: undefined, quoted: [quote(subject, key, value, false)] }
+        : { node: value, quoted: [] };
+};
+/**
+ * The document with every doubted reference taken off the node that
+ * states it, and quoted instead.
+ *
+ * An `@annotation` in JSON-LD-star states the triple it annotates and
+ * then says something about it, so a statement the edition holds
+ * possible, unlikely or false would reach RDF as a fact. Only references
+ * between nodes are quoted, since only they can be put back where they
+ * stood; a doubted date or attribution stays annotated in place.
+ */
+const withDoubtedReferencesQuoted = (value) => {
+    if (Array.isArray(value)) {
+        const quotings = value.map(withDoubtedReferencesQuoted);
+        return { node: quotings.map(({ node }) => node), quoted: quotings.flatMap(({ quoted }) => quoted) };
+    }
+    if (!isRecord(value))
+        return { node: value, quoted: [] };
+    const subject = value['@id'];
+    const entries = Object.entries(value).map(([key, child]) => {
+        const own = typeof subject === 'string' && !key.startsWith('@')
+            ? quotingValue(subject, key, child)
+            : { node: child, quoted: [] };
+        const below = withDoubtedReferencesQuoted(own.node);
+        return { key, node: below.node, quoted: [...own.quoted, ...below.quoted] };
+    });
+    return {
+        node: Object.fromEntries(entries.filter(({ node }) => node !== undefined).map(({ key, node }) => [key, node])),
+        quoted: entries.flatMap(({ quoted }) => quoted)
+    };
+};
 export const asJsonLd = (edition) => {
+    const { node, quoted } = withDoubtedReferencesQuoted(withSystemContexts(asJsonLdEntity(edition)));
     // The context is the export's own; one carried in from an import must not override it.
-    const { base, '@context': carried, ...rest } = withSystemContexts(asJsonLdEntity(edition));
+    const { base, '@context': carried, ...rest } = node;
     return {
         '@context': [
             'https://w3id.org/reo/context.jsonld',
@@ -74,6 +143,7 @@ export const asJsonLd = (edition) => {
         ],
         '@type': "Edition",
         '@id': edition.base,
-        ...rest
+        ...rest,
+        ...(quoted.length > 0 && { '@included': quoted })
     };
 };

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
@@ -99,7 +99,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 +111,29 @@ 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, and a hypothesis that something derives from it goes.
+ */
 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.

package/lib/editionOps.js

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

package/lib/migrate.js

@@ -69,7 +69,10 @@ const withScale = (node) => {
     const factor = (node.conditions ?? []).find(isPaperStretch)?.factor;
     return factor === undefined ? node : { ...node, measurements: { ...node.measurements, scale: factor } };
 };
-const migrateNode = (node) => [withRenamedKeys, withTypology, withReferences, withKeeper, withProductionNodes, withScale]
+/** A derivation written as a single one, before a version could name several. */
+const isSingleDerivation = (basedOn) => basedOn !== null && typeof basedOn === 'object' && !Array.isArray(basedOn);
+const withDerivationList = (node) => isSingleDerivation(node.basedOn) ? { ...node, basedOn: [node.basedOn] } : node;
+const migrateNode = (node) => [withRenamedKeys, withTypology, withReferences, withKeeper, withProductionNodes, withScale, withDerivationList]
     .reduce((result, step) => step(result), node);
 /** The items each walked, or the very same list where the walk changed none. */
 const walked = (items) => {
@@ -181,7 +184,7 @@ const withSystems = (edition) => {
 const withEditors = (edition) => !edition.creation || edition.creation.editors
     ? edition
     : { ...edition, creation: { ...edition.creation, editors: [] } };
-const statesNoTolerance = (version) => version.basedOn && !version.basedOn.collationTolerance;
+const statesNoTolerance = (version) => isSingleDerivation(version.basedOn) && !version.basedOn.collationTolerance;
 /**
  * The collation tolerance was the edition's before it was stated on
  * each derivation. An edition written then collated every version at
@@ -200,5 +203,51 @@ const withDerivationTolerance = (edition) => {
             : version)
     };
 };
-const editionSteps = [withSystems, withEditors, withDerivationTolerance];
+/** A statement an export quoted rather than stated: an included node whose id is a triple. */
+const isQuotedStatement = (node) => node !== null && typeof node === 'object' && node['@id'] !== null && typeof node['@id'] === 'object';
+/** The reference a quoted statement made, annotated again with the belief the export set beside it. */
+const referenceOf = (statement) => {
+    const { '@id': { '@id': subject, ...made }, annotation, ...about } = statement;
+    const [key, value] = Object.entries(made)[0];
+    const listed = Array.isArray(value);
+    return {
+        subject,
+        key,
+        listed,
+        reference: {
+            ...(listed ? value[0] : value),
+            '@annotation': { ...(annotation !== undefined && { '@id': annotation }), ...about }
+        }
+    };
+};
+/** The document with each quoted reference back on the node that makes it, a node being what has a type. */
+const withReferencesOn = (value, bySubject) => {
+    if (Array.isArray(value))
+        return value.map(item => withReferencesOn(item, bySubject));
+    if (!value || typeof value !== 'object')
+        return value;
+    const walked = Object.fromEntries(Object.entries(value).map(([key, child]) => [key, withReferencesOn(child, bySubject)]));
+    const references = typeof value['@id'] === 'string' && value['@type'] !== undefined
+        ? bySubject.get(value['@id']) ?? []
+        : [];
+    return references.reduce((node, { key, listed, reference }) => ({ ...node, [key]: listed ? [...(node[key] ?? []), reference] : reference }), walked);
+};
+/**
+ * Puts back what an export quoted. A reference the edition doubts goes
+ * out as a JSON-LD-star embedded node beside the document, so that RDF
+ * does not state it; in the edition it belongs on the node that makes
+ * it, under its belief. In a list it comes back after the references
+ * that were stated.
+ */
+const withQuotedStatementsInPlace = (edition) => {
+    const included = Array.isArray(edition['@included']) ? edition['@included'] : [];
+    const statements = included.filter(isQuotedStatement);
+    if (statements.length === 0)
+        return edition;
+    const others = included.filter(node => !isQuotedStatement(node));
+    const { '@included': _quoted, ...rest } = edition;
+    const bySubject = Map.groupBy(statements.map(referenceOf), ({ subject }) => subject);
+    return withReferencesOn({ ...rest, ...(others.length > 0 && { '@included': others }) }, bySubject);
+};
+const editionSteps = [withQuotedStatementsInPlace, withSystems, withEditors, withDerivationTolerance];
 export const migrate = (edition) => walk(editionSteps.reduce((result, step) => step(result), edition));

package/lib/reservations.d.ts

@@ -1,17 +1,19 @@
 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'];
 export type ReservationType = typeof reservationTypes[number];
 /**
- * Something an edition cannot vouch for in one of its copies.
+ * Something an edition cannot vouch for in one of its copies or
+ * versions.
  *
- * A reservation is worked out from what the copy states about itself
- * and is never written into the edition: it says that knowledge of
- * the copy is incomplete, so filling in what is missing makes it go
- * away. Nothing here describes the state of the paper, which is a
+ * A reservation is worked out from what the copy or version states
+ * about itself and is never written into the edition: it says that
+ * knowledge of it is incomplete, so filling in what is missing makes it
+ * go away. Nothing here describes the state of the paper, which is a
  * condition of the copy.
  */
-export interface Reservation {
-    type: ReservationType;
+export interface Reservation<T extends string = ReservationType> {
+    type: T;
     /** What the reservation means for a reader, in one sentence. */
     note: string;
 }
@@ -21,3 +23,7 @@ export interface Reservation {
  * the measurement leaves open.
  */
 export declare const reservationsAbout: (copy: RollCopy) => Reservation[];
+export declare const versionReservationTypes: readonly ['text-not-stated', 'type-not-stated'];
+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>[];

package/lib/reservations.js

@@ -73,3 +73,18 @@ const checks = [
  * the measurement leaves open.
  */
 export const reservationsAbout = (copy) => checks.flatMap(check => check(copy) ?? []);
+export const versionReservationTypes = [
+    'text-not-stated',
+    'type-not-stated'
+];
+const textStated = 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 : {
+    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];
+/** 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) ?? []);

package/lib/schema.json

@@ -2270,8 +2270,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 +2283,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 +2309,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 +2324,11 @@
                 }
             },
             "required": [
-                "edits",
                 "@id",
                 "motivations",
                 "siglum",
                 "system",
-                "@type",
-                "versionType"
+                "@type"
             ],
             "type": "object",
             "ontology": "lrmoo:F2 Expression"

package/lib/spec/context.json

@@ -84,6 +84,7 @@
             "@type": "xsd:date"
         },
         "collationTolerance": null,
+        "annotation": null,
         "roll": "lrmoo:R3i_realises",
         "catalogueNumber": "dcterms:identifier",
         "system": "crm:P2_has_type",
@@ -117,7 +118,12 @@
         "role": {
             "@id": "crm:P2_has_type",
             "@type": "@vocab",
-            "@context": { "@vocab": "https://w3id.org/reo/type/" }
+            "@context": {
+                "@vocab": "https://w3id.org/reo/type/",
+                "pianist": "https://w3id.org/reo/type/pianist",
+                "publisher": "https://w3id.org/reo/type/publisher",
+                "transcription": "https://w3id.org/reo/type/transcription"
+            }
         },
         "ops": null,
         "measurements": {
@@ -173,7 +179,11 @@
                 "kind": {
                     "@id": "crm:P2_has_type",
                     "@type": "@vocab",
-                    "@context": { "@vocab": "https://w3id.org/reo/type/" }
+                    "@context": {
+                        "@vocab": "https://w3id.org/reo/type/",
+                        "roll": "https://w3id.org/reo/type/roll",
+                        "scan": "https://w3id.org/reo/type/scan"
+                    }
                 },
                 "output": {
                     "@id": "crmdig:L11_had_output",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "linked-rolls",
-  "version": "0.25.0",
+  "version": "0.26.0",
   "description": "Digital editions of piano rolls: import, collation, editorial assumptions, JSON-LD export, and emulation through a reproducing system",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,9 @@
     "build:docs": "node schema/docs/generate.ts src/schema.json docs/index.html"
   },
   "devDependencies": {
+    "@types/jsonld": "^1.5.15",
     "@types/node": "^24.13.3",
+    "jsonld": "^9.0.0",
     "ts-json-schema-generator": "^2.9.0",
     "typescript": "^7.0.2",
     "vite": "^8.2.2",