linked-rolls 0.65.0 → 0.67.0

package/README.md

@@ -55,6 +55,14 @@ between the two. What the alignments say about the paper of the copies,
 how far each has stretched and how the papers of the systems relate, is
 worked out by `paperOf`.
 
+What is worked out is not stated. Where the edition holds to the ratio a
+re-cut gave the paper of its version, the creation of the version states
+it (`lengthRatio`, as `lengthRatioOf` gives it), so that others can take
+it as a premise. A measured value, such as that ratio, a copy's
+dimensions and hole separation, or the setting of its perforator, is
+held on the strength of a measurement, which names what it was taken
+on, the program and its version, and the day.
+
 Documents written by earlier releases are brought up to date on import.
 To check a document against the schema:
 

package/lib/analysis/paper.d.ts

@@ -1,6 +1,7 @@
 import { Edition } from "../model/Edition.js";
 import { Strain } from "../model/RollCopy.js";
-import { Percent } from "../model/Quantity.js";
+import { LengthRatio } from "../model/Version.js";
+import { MetersPerMinute, Percent } from "../model/Quantity.js";
 /**
  * How far the paper of one copy is taken to have stretched or shrunk
  * along the roll, as a standard deviation, where the edition has too few
@@ -120,6 +121,16 @@ export type AlignmentProblem = {
      */
     by?: number;
 };
+/**
+ * The speed the version's paper starts at, as the copies of its own system
+ * that bear witness to it at first hand state they were cut for: the mean
+ * of the speeds the edition holds true or likely. A stated speed is the
+ * speed at the beginning of the roll, as a tempo marking gives it. Nothing
+ * where no such copy states one; in particular, a copy that reaches the
+ * version only through a later one says nothing about it, since the later
+ * one may have been cut for another speed.
+ */
+export declare const paperSpeedOf: (edition: Edition, versionId: string) => MetersPerMinute | undefined;
 /**
  * Where the alignments of the edition's copies, or what they say about
  * the paper, want looking into. None of it is recomputed, so it is cheap
@@ -127,3 +138,19 @@ export type AlignmentProblem = {
  * is `alignmentFor`'s to say.
  */
 export declare const alignmentProblems: (edition: Pick<Edition, 'copies' | 'referenceCopy'>) => AlignmentProblem[];
+/**
+ * How long the version's paper runs for a length of the paper of the
+ * version it derives from, as the alignments give it: the ratio of the
+ * two versions' systems' papers, with its uncertainty. It is what the
+ * creation of the version states where the edition holds to it
+ * (`VersionCreation.lengthRatio`).
+ *
+ * The reading pools the copies of a system, so the ratio is only given
+ * for a version that one of those copies bears witness to: a second
+ * re-cut for the same system, whose copies measure no paper, is not
+ * credited with the first one's ratio. Where the reading has copies of
+ * two versions re-cut for one system, the ratio is theirs together.
+ * Nothing is given for a version that derives from none, or from one on
+ * its own system, whose paper it keeps.
+ */
+export declare const lengthRatioOf: (edition: Edition, versionId: string) => LengthRatio | undefined;

package/lib/analysis/paper.js

@@ -1,7 +1,11 @@
 import { referenceCopyOf } from "../model/Edition.js";
 import { barOf, featuresOf, paperStretchOf } from "../model/RollCopy.js";
-import { certaintyOf, isAsserted } from "../model/Assumption.js";
-import { inMetersPerMinute, percent } from "../model/Quantity.js";
+import { certaintyOf, idOf, isAsserted } from "../model/Assumption.js";
+import { principalDerivationOf } from "../model/Version.js";
+import { versionIn } from "../lookup/lookup.js";
+import { witnessesOf } from "./witnesses.js";
+import { inMetersPerMinute, mean, percent } from "../model/Quantity.js";
+import { defaultTrackerBar, trackerBarOf } from "../systems/index.js";
 /**
  * How far the paper of one copy is taken to have stretched or shrunk
  * along the roll, as a standard deviation, where the edition has too few
@@ -213,6 +217,27 @@ const statedSpeed = (copy) => {
     const speed = copy.production?.speed;
     return speed && isAsserted(certaintyOf(speed)) ? inMetersPerMinute(speed) : undefined;
 };
+/**
+ * The speed the version's paper starts at, as the copies of its own system
+ * that bear witness to it at first hand state they were cut for: the mean
+ * of the speeds the edition holds true or likely. A stated speed is the
+ * speed at the beginning of the roll, as a tempo marking gives it. Nothing
+ * where no such copy states one; in particular, a copy that reaches the
+ * version only through a later one says nothing about it, since the later
+ * one may have been cut for another speed.
+ */
+export const paperSpeedOf = (edition, versionId) => {
+    const version = versionIn(edition, versionId);
+    if (!version)
+        return undefined;
+    const system = (trackerBarOf(version.system) ?? defaultTrackerBar).id;
+    const speeds = witnessesOf(edition, versionId)
+        .filter(witness => witness.through === undefined)
+        .flatMap(witness => edition.copies.filter(copy => copy.id === witness.copy && barOf(copy).id === system))
+        .map(statedSpeed)
+        .filter(speed => speed !== undefined);
+    return speeds.length > 0 ? mean(speeds) : undefined;
+};
 /** The speed the reference copy was cut at: as stated for it, or as its system runs. */
 const referenceSpeed = (reference) => {
     const system = barOf(reference).paperSpeed;
@@ -258,3 +283,36 @@ export const alignmentProblems = (edition) => {
     });
     return [...unaligned, ...elsewhere, ...beyond, ...speeds];
 };
+/**
+ * How long the version's paper runs for a length of the paper of the
+ * version it derives from, as the alignments give it: the ratio of the
+ * two versions' systems' papers, with its uncertainty. It is what the
+ * creation of the version states where the edition holds to it
+ * (`VersionCreation.lengthRatio`).
+ *
+ * The reading pools the copies of a system, so the ratio is only given
+ * for a version that one of those copies bears witness to: a second
+ * re-cut for the same system, whose copies measure no paper, is not
+ * credited with the first one's ratio. Where the reading has copies of
+ * two versions re-cut for one system, the ratio is theirs together.
+ * Nothing is given for a version that derives from none, or from one on
+ * its own system, whose paper it keeps.
+ */
+export const lengthRatioOf = (edition, versionId) => {
+    const version = versionIn(edition, versionId);
+    const derivation = version && principalDerivationOf(version);
+    const base = derivation && versionIn(edition, idOf(derivation));
+    const reading = paperOf(edition);
+    if (!version || !base || !reading)
+        return undefined;
+    const systemOf = (of) => reading.systems.find(paper => paper.system === trackerBarOf(of.system)?.id);
+    const own = systemOf(version);
+    const theirs = systemOf(base);
+    if (!own || !theirs || own.system === theirs.system)
+        return undefined;
+    const witnesses = new Set(witnessesOf(edition, versionId).map(witness => witness.copy));
+    if (!own.copies.some(copy => witnesses.has(copy)))
+        return undefined;
+    const value = own.ratio / theirs.ratio;
+    return { value, uncertainty: value * Math.hypot(own.ratioError / own.ratio, theirs.ratioError / theirs.ratio) };
+};

package/lib/analysis/reservations.js

@@ -1,5 +1,5 @@
 import { bearsPhysicalEvidence, isMeasured, sourceLabels } from "../model/FeatureSource.js";
-import { calibrationOf, featuresOf } from "../model/RollCopy.js";
+import { calibrationOf, featuresOf, measuringSoftwareOf } from "../model/RollCopy.js";
 import { trackerBarOf } from "../systems/index.js";
 import { witnessesOf } from "./witnesses.js";
 export const reservationTypes = [
@@ -49,7 +49,7 @@ const physicalEvidence = copy => copy.readFrom && !bearsPhysicalEvidence(copy.re
     type: 'no-physical-evidence',
     note: 'Punch diameter, hole separation, punching pattern, marks and writings cannot be observed on this source.'
 } : undefined;
-const measurementDocumented = copy => !copy.measurements.measuredBy && copy.readFrom?.kind !== 'roll' ? {
+const measurementDocumented = copy => measuringSoftwareOf(copy).length === 0 && copy.readFrom?.kind !== 'roll' ? {
     type: 'measurement-undocumented',
     note: 'No measuring software is recorded for this copy.'
 } : undefined;

package/lib/emulation/Emulation.js

@@ -1,12 +1,15 @@
 import { MIDIControlEvents } from "midifile-ts";
-import { idOf } from "../model/Assumption.js";
+import { certaintyOf, idOf, isAsserted } from "../model/Assumption.js";
 import { isCommand, pairsAmong, placementsOf } from "../model/Symbol.js";
+import { principalDerivationOf } from "../model/Version.js";
 import { add, mean, mm, seconds, subtract } from "../model/Quantity.js";
 import { punchDiameterOf } from "../model/RollCopy.js";
 import { toOwnPaperOf } from "../analysis/ownPaper.js";
+import { paperSpeedOf } from "../analysis/paper.js";
+import { defaultTrackerBar, trackerBarOf } from "../systems/index.js";
 import { negotiatedEventOf } from "./negotiation.js";
 import { placedCarriersOf, snapshotOf } from "../analysis/text.js";
-import { copyOfFeature, symbolIn } from "../lookup/lookup.js";
+import { copyOfFeature, symbolIn, versionIn } from "../lookup/lookup.js";
 /** The punch diameter the edition's copies report, where any of them does. */
 const meanPunchDiameterOf = (edition) => {
     const measured = edition.copies
@@ -14,10 +17,62 @@ const meanPunchDiameterOf = (edition) => {
         .filter(value => value !== undefined);
     return measured.length > 0 ? mean(measured) : undefined;
 };
+/** The version this one derives from, where it names one the edition has. */
+const baseOf = (edition, version) => {
+    const derivation = principalDerivationOf(version);
+    return derivation && versionIn(edition, idOf(derivation));
+};
+const onOneSystem = (one, other) => (trackerBarOf(one.system) ?? defaultTrackerBar).id === (trackerBarOf(other.system) ?? defaultTrackerBar).id;
+/**
+ * The speed the version starts at, as far as the edition states one: as
+ * its own copies state it (`paperSpeedOf`), or else as stated for the
+ * version it derives from on the same system, whose paper it keeps.
+ */
+const statedSpeedOf = (edition, version, seen = new Set()) => {
+    const own = paperSpeedOf(edition, version.id);
+    if (own !== undefined || seen.has(version.id))
+        return own;
+    const base = baseOf(edition, version);
+    return base && onOneSystem(base, version)
+        ? statedSpeedOf(edition, base, new Set([...seen, version.id]))
+        : undefined;
+};
+/**
+ * How long the version's paper runs for a length of the paper of the
+ * version it derives from: as its creation states it where the edition
+ * holds to that, else as the papers the two are performed on relate. That
+ * is what the alignments give for the two systems (`toOwnPaperOf`), which
+ * a performance credits every version of a system with, whether or not its
+ * own copies measure the paper (cf. `lengthRatioOf`).
+ */
+const lengthRatioIn = (edition, version, base) => {
+    const stated = version.creation?.lengthRatio;
+    if (stated && isAsserted(certaintyOf(stated)))
+        return stated.value;
+    const own = toOwnPaperOf(edition, version);
+    const theirs = toOwnPaperOf(edition, base);
+    return own !== undefined && theirs !== undefined ? own / theirs : undefined;
+};
+/**
+ * The roll a re-cut was made from, as far as its timing goes: the length
+ * ratio, and the speed stated for the original. Nothing for a version that
+ * derives from none, or from one on its own system.
+ */
+const recutFromOf = (edition, version) => {
+    const base = baseOf(edition, version);
+    if (!base || onOneSystem(base, version))
+        return undefined;
+    const lengthRatio = lengthRatioIn(edition, version, base);
+    if (lengthRatio === undefined)
+        return undefined;
+    const paperSpeed = statedSpeedOf(edition, base);
+    return { lengthRatio, ...(paperSpeed !== undefined && { paperSpeed }) };
+};
 const propertiesOf = (edition, version) => ({
     punchDiameter: meanPunchDiameterOf(edition),
-    tempo: edition.tempoAdjustment,
-    toOwnPaper: toOwnPaperOf(edition, version)
+    toOwnPaper: toOwnPaperOf(edition, version),
+    paperSpeed: statedSpeedOf(edition, version),
+    recutFrom: recutFromOf(edition, version)
 });
 /** The onset a symbol has on each copy carrying it, by the copy's id, as the mean of its chains there. */
 const onsetsByCopy = (edition, symbolId) => {

package/lib/io/migrate.js

@@ -1,3 +1,4 @@
+import { v4 } from "uuid";
 import { systemIdIn, systemOf, translationBetween } from "../systems/TrackerBar.js";
 import { trackerBars } from "../systems/index.js";
 import { welteT100 } from "../systems/welteT100/bar.js";
@@ -451,9 +452,61 @@ const withTimeSpanDates = (node) => {
     const { '@value': within, '@type': _typed, ...rest } = node;
     return { ...rest, within };
 };
+/** The values a copy's one `measuredBy` stood for, of those the edition exports: what the analysis it named had given. */
+const measuredByCovered = ['dimensions', 'holeSeparation'];
+/** A day written as a date, of a date written with or without its time. */
+const dayOf = (date) => typeof date === 'string' && /^\d{4}-\d{2}-\d{2}/.test(date) ? date.slice(0, 10) : undefined;
+/**
+ * A copy once named one program for all its measurements, beside values
+ * that could not say what took them. Each value the edition exports now
+ * carries the measurement it rests on, so the program, its version and
+ * the day go into the reasons of the dimensions and the hole separation,
+ * which the analysis it named had given. The scan resolution is read
+ * off the file rather than measured, and the margins are not exported;
+ * nothing is said of them. The ids are the copy's, so that migrating a
+ * file twice writes the same document.
+ */
+const withMeasuredByInReasons = (node) => {
+    const measurements = node?.measurements;
+    if (!measurements || typeof measurements !== 'object' || !Object.hasOwn(measurements, 'measuredBy'))
+        return node;
+    const { measuredBy, ...rest } = measurements;
+    const day = dayOf(measuredBy?.date);
+    const reason = measuredBy?.software && {
+        '@type': 'measurement',
+        software: [{ name: measuredBy.software, ...(measuredBy.version && { version: measuredBy.version }) }],
+        ...(day && { date: { within: day } })
+    };
+    const owner = typeof node['@id'] === 'string' ? plainCopyId(node['@id']) : v4();
+    const withReason = (key, value) => {
+        if (!reason || !value || typeof value !== 'object')
+            return value;
+        const annotation = value['@annotation'];
+        if (annotation?.belief) {
+            return { ...value, '@annotation': { ...annotation, belief: { ...annotation.belief, reasons: [...(annotation.belief.reasons ?? []), reason] } } };
+        }
+        return {
+            ...value,
+            '@annotation': {
+                '@id': `${owner}-${key}-annotation`,
+                belief: { '@type': 'belief', '@id': `${owner}-${key}-belief`, certainty: 'true', reasons: [reason] }
+            }
+        };
+    };
+    return {
+        ...node,
+        measurements: {
+            ...rest,
+            ...Object.fromEntries(measuredByCovered
+                .filter(key => Object.hasOwn(rest, key))
+                .map(key => [key, withReason(key, rest[key])]))
+        }
+    };
+};
 const nodeSteps = [withRenamedKeys, withRenamedEditType, withTypology, withRenamedType, withoutVersionType, withoutVersionSiglum, withLowerCaseTerms, withSplitMethod, withReferences, withKeeper, withoutEmptyKeeper,
     withPerforator, withProductionNodes, withTypedPerforator, withScale, withoutOps, withDerivationList, withReadingKind, withTimeSpanDates,
-    withoutFeatureKind, withBorneFeaturesNamed, withFeaturesInActs, withOwnPlaces, withDriveOfStaggering, withoutPattern, withoutBearings, withoutEntailedType];
+    withoutFeatureKind, withBorneFeaturesNamed, withFeaturesInActs, withOwnPlaces, withDriveOfStaggering, withoutPattern, withoutBearings, withoutEntailedType,
+    withMeasuredByInReasons];
 const migrateNode = (node) => nodeSteps.reduce((result, step) => step(result), node);
 /** The value with every node in it migrated, a node before its children; the very same value where nothing changed. */
 const walk = (value) => {
@@ -591,6 +644,18 @@ const withoutFormatVersion = (edition) => {
     const { formatVersion: _stated, ...rest } = edition;
     return rest;
 };
+/**
+ * An edition once stated one tempo for the roll, which cannot hold where the
+ * roll was issued for systems whose papers run at different speeds. A copy
+ * states the speed it was cut for, and a re-cut's follows from its original's
+ * and the length ratio, so the edition's goes.
+ */
+const withoutTempoAdjustment = (edition) => {
+    if (!Object.hasOwn(edition, 'tempoAdjustment'))
+        return edition;
+    const { tempoAdjustment: _stated, ...rest } = edition;
+    return rest;
+};
 /** Whether the copy states features, in either shape. */
 const hasFeatures = (copy) => [copy?.features, copy?.production?.produced, copy?.productionEvent?.produced]
     .some(features => Array.isArray(features) && features.length > 0);
@@ -611,5 +676,5 @@ const withReferenceCopy = (edition) => {
         ? { ...edition, referenceCopy: plainCopyId(reference['@id']) }
         : edition;
 };
-const editionSteps = [withoutFormatVersion, withoutEditionType, withSystems, withEditors, withDerivationTolerance, withReferenceCopy];
+const editionSteps = [withoutFormatVersion, withoutTempoAdjustment, withoutEditionType, withSystems, withEditors, withDerivationTolerance, withReferenceCopy];
 export const migrate = (edition) => walk(editionSteps.reduce((result, step) => step(result), edition));

package/lib/model/Agent.d.ts

@@ -78,4 +78,21 @@ export interface Place extends Named {
  * @see crm:E55 Type
  */
 export type Concept = (WithId & Partial<Named>) | (Named & Partial<WithId>);
+/**
+ * Software that captured a copy or measured it: the transcriber that
+ * read a recording into notes, the emulator that wrote a MIDI file, the
+ * program that found the holes on a scan or aligned two copies.
+ * @see crmdig:D14 Software
+ */
+export interface Software {
+    /**
+     * @see rdfs:label
+     */
+    name: string;
+    /**
+     * The release, the commit, or the model checkpoint of a transcriber.
+     * @see owl:versionInfo
+     */
+    version?: string;
+}
 export {};

package/lib/model/Assumption.d.ts

@@ -1,5 +1,5 @@
 import { WithNote, WithId } from "../shared/utils.js";
-import { Person, WithActor } from "./Agent.js";
+import { Concept, Person, Software, WithActor } from "./Agent.js";
 export declare const certainties: readonly ['true', 'likely', 'possible', 'unlikely', 'false'];
 /**
  * Certainty levels for beliefs, ranging from 'true' to 'false'
@@ -102,6 +102,11 @@ export interface BeliefAdoption extends Argumentation<'beliefAdoption'> {
  * premises. CRMinf counts observations, and a measurement is one, among
  * the ways a belief comes about, so the value does not have to be
  * passed off as an inference.
+ *
+ * A measurement a program took names the program and its version, so
+ * that the value can be taken again and a value taken by a program
+ * later found wanting can be told from the rest. Naming software makes
+ * it a digital measurement event in the sense of CRMdig.
  * @see crmsci:S21 Measurement
  */
 export interface Measurement extends Argumentation<'measurement'> {
@@ -111,6 +116,24 @@ export interface Measurement extends Argumentation<'measurement'> {
      * @see crm:P16 used specific object
      */
     used?: string[];
+    /**
+     * The method followed, where it has a name apart from the program
+     * that carries it out, such as a line of Theil and Sen through the
+     * matched notes of two copies.
+     * @see crm:P33 used specific technique
+     */
+    procedure?: Concept;
+    /**
+     * The programs that took the measurement, each with its version.
+     * @see crmdig:L23 used software or firmware
+     */
+    software?: Software[];
+    /**
+     * When the measurement was taken. It is part of the reason and
+     * carries no belief of its own.
+     * @see crm:P4 has time-span
+     */
+    date?: TimeSpan;
 }
 /**
  * An argumentation can be either a plain argumentation, a
@@ -185,7 +208,6 @@ export type ObjectAssumption<O extends object> = Assumption & O;
  * annotated with a belief about its certainty.
  */
 export type ActorAssignment = ObjectAssumption<Person>;
-/** The day an event falls within. */
 interface DateWithin {
     /**
      * The day the event falls within.
@@ -194,8 +216,7 @@ interface DateWithin {
      */
     within: Date;
 }
-/** The bounds an event lies between. */
-interface DateBounds {
+interface DateAfter {
     /**
      * The earliest day the event can have happened on: it did not
      * happen before it.
@@ -203,6 +224,22 @@ interface DateBounds {
      * @see crm:P82a begin of the begin
      */
     after: Date;
+    /**
+     * The latest day the event can have happened on: it did not
+     * happen after it.
+     * @format date
+     * @see crm:P82b end of the end
+     */
+    before?: Date;
+}
+interface DateBefore {
+    /**
+     * The earliest day the event can have happened on: it did not
+     * happen before it.
+     * @format date
+     * @see crm:P82a begin of the begin
+     */
+    after?: Date;
     /**
      * The latest day the event can have happened on: it did not
      * happen after it.
@@ -212,12 +249,20 @@ interface DateBounds {
     before: Date;
 }
 /**
- * When something happened, as far as the edition can state it: the day
- * it falls `within`, or the bounds it lies between. A bound nobody can
- * give is left out, so `after` alone says "not before".
+ * When something happened: the day it falls `within`, or the bounds it
+ * lies between. A bound nobody can give is left out, so `after` alone
+ * says "not before".
+ * @see crm:E52 Time-Span
+ */
+export type TimeSpan = DateWithin | DateAfter | DateBefore;
+/**
+ * When something happened, as far as the edition can state it, and as
+ * an assumption, so that a dating can carry the belief it rests on: the
+ * day it falls `within`, or the bounds it lies between. A bound nobody
+ * can give is left out, so `after` alone says "not before".
  * @see crm:E52 Time-Span
  */
-export type DateAssignment = Assumption & (DateWithin | (Pick<DateBounds, 'after'> & Partial<Pick<DateBounds, 'before'>>) | (Pick<DateBounds, 'before'> & Partial<Pick<DateBounds, 'after'>>));
+export type DateAssignment = Assumption & TimeSpan;
 export declare function valueOf<ValueT>(assumption: ValueAssumption<ValueT>): ValueT;
 export declare function valuesOf<ValueT>(assumptions: ValueAssumption<ValueT>[]): ValueT[];
 export declare function idOf(assumption: ReferenceAssumption): string;

package/lib/model/Edition.d.ts

@@ -1,8 +1,7 @@
 import { RollCopy } from "./RollCopy.js";
 import { Version } from "./Version.js";
-import { DateAssignment, ObjectAssumption } from "./Assumption.js";
+import { DateAssignment } from "./Assumption.js";
 import { Editor, Person, Place } from "./Agent.js";
-import { RollTempo } from "../systems/ReproducingSystem.js";
 /**
  * This type describes the creation of an edition,
  * i.e. the editor, publisher, and publication date.
@@ -145,12 +144,6 @@ export interface Edition {
      * @see lrmoo:R75 incorporates
      */
     versions: Version[];
-    /**
-     * An optional tempo adjustment for playback of the roll,
-     * annotatable with a belief about its correctness.
-     * @see reo:tempo
-     */
-    tempoAdjustment?: ObjectAssumption<RollTempo>;
 }
 export type EditionMetadata = Pick<Edition, 'base' | 'title' | 'license' | 'creation' | 'roll'>;
 /**

package/lib/model/FeatureSource.d.ts

@@ -1,5 +1,5 @@
 import { ActorAssignment, DateAssignment, ObjectAssumption } from "./Assumption.js";
-import { Concept, Named } from "./Agent.js";
+import { Concept, Named, Software } from "./Agent.js";
 import { ConditionState } from "./ConditionState.js";
 import { WithNote } from "../shared/utils.js";
 /**
@@ -25,22 +25,7 @@ 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;
-}
+export type { Software } from "./Agent.js";
 /**
  * An instrument a copy was played on to be recorded. How it was
  * regulated, where that is known, is its condition.