linked-rolls 0.70.0 → 0.72.0

package/README.md

@@ -1,5 +1,7 @@
 # linked-rolls
 
+[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23270944.svg)](https://doi.org/10.5281/zenodo.23270944)
+
 A TypeScript library for digital editions of piano rolls. It reads roll
 copies from scans and analysis files, collates them into versions,
 records editorial assumptions together with the beliefs behind them,
@@ -39,6 +41,13 @@ const symbols = snapshotOf(edition, childId)
 const document = asJsonLd(edition)
 ```
 
+The [API reference](https://pfefferniels.github.io/linked-rolls/api/)
+documents the public interface, and the
+[recipes](https://pfefferniels.github.io/linked-rolls/api/documents/Recipes.html)
+show how to read an edition, get the text of a version, see what a
+version changed, play it and write a change back. What the reference
+leaves out is internal and may change in any release.
+
 What is read off an edition, such as `snapshotOf`, `placeOf`,
 `versionIn` or `pathIn`, is worked out once for each state of it and
 kept for as long as the state is. Every change through `produce` yields
@@ -88,14 +97,50 @@ const midi = midiOf(events, welteT100System.name, welteT100System.defaultOptions
 The systems are `linked-rolls/welte-t100` (red Welte),
 `linked-rolls/welte-t98` (green Welte) and `linked-rolls/welte-licensee`.
 
+## Proposing a stemma
+
+Which versions there are, lost ones included, how they derive from each
+other and which edits belong to which can be proposed from the copies
+alone. `proposeStemma` collates the transcribed copies all at once,
+notes which copies have, lack or cannot show each reading, and scores
+every stemma the copies admit, up to seven copies. A reading arising
+costs ten times a reading lost. Losses count for less where the
+editorial principles of an edition say they are weak evidence: a
+redundancy cleaned up, or what a re-cut for another system lacks. On
+the best stemma, each reading arises in the latest version all copies
+carrying it descend from.
+
+```ts
+import { produce } from 'immer'
+import { adoptStemma, proposeStemma, stemmaChanges } from 'linked-rolls'
+
+const proposal = proposeStemma(edition)
+proposal.notation   // '*(St1(*(Ne1,St2(Bo1,Ch1))),Wi1)' for WM 225
+proposal.supports   // by how much the copies decide each grouping
+
+const adopted = produce(edition, adoptStemma(proposal))
+const changes = stemmaChanges(edition, adopted)
+```
+
+Adopting keeps what the edition holds wherever the proposal stands for
+it: the ids of versions and symbols, a derivation's belief, and the
+edits the editor wrote, which hold their versions to what they insert
+and delete. Motivations, beliefs and versions known only from a
+recording remain the editor's to state.
+
+The costs are those with which the stemma of WM 225 comes out of its
+six copies. They were found by searching for such values, so they show
+that the stemma is consistent with these principles, not that the
+principles confirm it.
+
 ## Format
 
 The export uses the Roll Edition Ontology (REO), namespace
 `https://w3id.org/reo/`, together with CIDOC CRM, LRMoo and CRMinf. The
 ontology is in `ontology/`. It is published with its context and the
 documentation of the format at
-https://pfefferniels.github.io/linked-rolls/ (the w3id.org identifiers are
-not registered yet).
+https://pfefferniels.github.io/linked-rolls/, to which the w3id.org
+identifiers redirect.
 
 Beliefs are written as JSON-LD-star annotations (`@annotation`), so you
 need a processor that supports JSON-LD-star to read them.
@@ -107,10 +152,66 @@ npm ci
 npm test
 npm run lint
 npm run build
+npm run build:api   # the API reference, into docs/api
 ```
 
+TypeDoc runs from `tools/typedoc` with a TypeScript 5 of its own, as
+TypeScript 7 no longer has the compiler API it reads the source with.
+
 ## Releasing
 
-Raise the version in `package.json`, commit, and push a tag
-`v<version>`. The `publish.yml` workflow builds, tests and publishes to
-npm.
+Raise the version in `package.json` and in `CITATION.cff`, there with
+the day as `date-released`, commit, and push a tag `v<version>`. The
+`publish.yml` workflow builds, tests and publishes to npm, then makes a
+GitHub release of the tag, which Zenodo archives with a DOI. A test fails
+while the two versions differ.
+
+## About
+
+linked-rolls grew out of the dissertation *Grünfelds Geist.
+Rekonstruktion einer Welte-Mignon-Klavierrollenaufnahme* (Niels
+Pfeffer, Eberhard Karls Universität Tübingen, Musikwissenschaftliches
+Institut, 2026), which edits Alfred Grünfeld's 1905 recording of
+Schumann's *Träumerei*, Welte-Mignon roll 225, from its surviving
+copies. That edition is published at https://welte225.org/ and can be
+read in the [Roll Desk](https://rolldesk.welte225.org/).
+
+Its aim is a scholarly edition of a piano roll that treats the roll the
+way a critical edition treats a text: every copy is a witness, the
+differences between copies are collated into versions, and every
+editorial decision is recorded together with the evidence and the
+beliefs behind it, so that a reader can retrace and contest it. The
+data are meant to be reused outside the library, which is why the
+format is linked data built on CIDOC CRM rather than a file format of
+its own.
+
+### Related formats
+
+Several formats have been developed or used to represent piano rolls at
+different stages of processing:
+
+- **Scan images:** CIS and MRS, often accompanied by ANN metadata.
+- **Event lists:** Wayne Stahnke's RAW, WEB and BAR, PRF, SCN, ROL, and
+  the e-roll MIDI files of pneumatic readers.
+- **Symbolic descriptions:** the Roll Analysis files of the Stanford
+  University Piano Roll Archive, serialised as ATON.
+
+None of them is concerned with what a critical edition needs: an
+apparatus of the variants between copies, the traces a copy carries
+(handwritten notes, patches, perforations added later), a record of how
+and on what assumptions each reading came about, and identifiers by
+which all of this can be referred to and annotated. The dissertation
+surveys these formats in its chapter on variants.
+
+Editions of texts and of notated music are mostly encoded in TEI and
+MEI. A roll edition, however, is less a nested text document than a
+flat structure of roll events described in numbers, and its data should
+link to other domains, which is why the Roll Edition Format is JSON-LD
+built on CIDOC CRM and LRMoo.
+
+### Maintenance
+
+The library is maintained by Niels Pfeffer
+([ORCID 0000-0002-6210-7255](https://orcid.org/0000-0002-6210-7255)). It
+is released under the MIT licence, the ontology and its documentation
+under CC BY 4.0.

package/lib/analysis/constraints.d.ts

@@ -1,4 +1,10 @@
 import { Edition } from "../model/Edition.js";
+/**
+ * Where the edition cannot hold as stated, as `constraintProblems`
+ * reports it: the version and the symbol concerned, and what is wrong
+ * with it.
+ * @category Analysis
+ */
 export type ConstraintProblem = {
     version: string;
     symbol: string;
@@ -13,5 +19,6 @@ export type ConstraintProblem = {
  * expression the version's own bar cannot read, a carrier sitting on a
  * track that does not say what its symbol says, and a strike that takes
  * nothing out.
+ * @category Analysis
  */
 export declare const constraintProblems: (edition: Edition) => ConstraintProblem[];

package/lib/analysis/constraints.js

@@ -137,6 +137,7 @@ const strikesBitingNothing = (edition, version) => {
  * expression the version's own bar cannot read, a carrier sitting on a
  * track that does not say what its symbol says, and a strike that takes
  * nothing out.
+ * @category Analysis
  */
 export const constraintProblems = (edition) => {
     // What a symbol's carriers and the copies' paper say holds whichever

package/lib/analysis/ownPaper.d.ts

@@ -1,7 +1,10 @@
 import type { Version } from "../model/Version.js";
 import { PaperOfSystem } from "./paper.js";
 import { Edition } from "../model/Edition.js";
-/** What the alignments say about the paper of the version's own system, where they say anything. */
+/**
+ * What the alignments say about the paper of the version's own system, where they say anything.
+ * @category Analysis
+ */
 export declare const paperOfVersion: (edition: Edition, version: Readonly<Version>) => PaperOfSystem | undefined;
 /**
  * How a place on the edition's shared axis relates to the paper of
@@ -17,5 +20,6 @@ export declare const paperOfVersion: (edition: Edition, version: Readonly<Versio
  *
  * Nothing where no copy of the version's system measures its paper,
  * which leaves the performance on the axis.
+ * @category Analysis
  */
 export declare const toOwnPaperOf: (edition: Edition, version: Readonly<Version>) => number | undefined;

package/lib/analysis/ownPaper.js

@@ -1,6 +1,9 @@
 import { defaultTrackerBar, trackerBarOf } from "../systems/index.js";
 import { paperOf } from "./paper.js";
-/** What the alignments say about the paper of the version's own system, where they say anything. */
+/**
+ * What the alignments say about the paper of the version's own system, where they say anything.
+ * @category Analysis
+ */
 export const paperOfVersion = (edition, version) => {
     const system = (trackerBarOf(version.system) ?? defaultTrackerBar).id;
     return paperOf(edition)?.systems.find(paper => paper.system === system);
@@ -19,5 +22,6 @@ export const paperOfVersion = (edition, version) => {
  *
  * Nothing where no copy of the version's system measures its paper,
  * which leaves the performance on the axis.
+ * @category Analysis
  */
 export const toOwnPaperOf = (edition, version) => paperOfVersion(edition, version)?.toOwnPaper;

package/lib/analysis/paper.d.ts

@@ -8,15 +8,20 @@ import { MetersPerMinute, Percent } from "../model/Quantity.js";
  * copies of one system to say: the three red copies of Welte 225 spread
  * by 0.19 %. It includes the scanner's error along the roll, which the
  * alignment cannot tell from the paper's.
+ * @category Analysis
  */
 export declare const PAPER_SPREAD: Percent;
 /**
  * How far a paper speed a label or the literature states is taken to be
  * from the speed a copy was cut at: the literature gives the red roll's
  * three metres a minute as 2.9 as well (Bärtsch 2020), which is 3.4 %.
+ * @category Analysis
  */
 export declare const SPEED_TOLERANCE = 0.035;
-/** What the alignments say about one copy's paper. */
+/**
+ * What the alignments say about one copy's paper.
+ * @category Analysis
+ */
 export interface PaperOfCopy {
     copy: string;
     /** The system the copy was cut for, by the id of its bar. */
@@ -26,7 +31,10 @@ export interface PaperOfCopy {
     /** Whether a strain measured on the copy went into it, rather than the spread of paper alone. */
     measured: boolean;
 }
-/** What the alignments say about the paper the copies of one system were cut on. */
+/**
+ * What the alignments say about the paper the copies of one system were cut on.
+ * @category Analysis
+ */
 export interface PaperOfSystem {
     /** The system, by the id of its bar. */
     system: string;
@@ -50,7 +58,10 @@ export interface PaperOfSystem {
     /** The copies of the system it rests on. */
     copies: string[];
 }
-/** What the alignments of an edition say about the paper of its copies, and how surely. */
+/**
+ * What the alignments of an edition say about the paper of its copies, and how surely.
+ * @category Analysis
+ */
 export interface PaperReading {
     /** The copy whose millimetres are the axis. */
     reference: string;
@@ -93,9 +104,13 @@ export interface PaperReading {
  * Copies whose places are not places on the paper, such as a roll
  * reader's, say nothing about the paper and are left out. Nothing is
  * said where the edition has no reference copy.
+ * @category Analysis
  */
 export declare const paperOf: (edition: Pick<Edition, 'copies' | 'referenceCopy'>) => PaperReading | undefined;
-/** Where the alignments of the copies, or what they say about the paper, want looking into. */
+/**
+ * Where the alignments of the copies, or what they say about the paper, want looking into.
+ * @category Analysis
+ */
 export type AlignmentProblem = {
     copy: string;
     problem: 
@@ -129,6 +144,7 @@ export type AlignmentProblem = {
  * 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.
+ * @category Analysis
  */
 export declare const paperSpeedOf: (edition: Edition, versionId: string) => MetersPerMinute | undefined;
 /**
@@ -136,6 +152,7 @@ export declare const paperSpeedOf: (edition: Edition, versionId: string) => Mete
  * the paper, want looking into. None of it is recomputed, so it is cheap
  * to ask; whether an alignment would come out otherwise if found again
  * is `alignmentFor`'s to say.
+ * @category Analysis
  */
 export declare const alignmentProblems: (edition: Pick<Edition, 'copies' | 'referenceCopy'>) => AlignmentProblem[];
 /**
@@ -152,5 +169,6 @@ export declare const alignmentProblems: (edition: Pick<Edition, 'copies' | 'refe
  * 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.
+ * @category Analysis
  */
 export declare const lengthRatioOf: (edition: Edition, versionId: string) => LengthRatio | undefined;

package/lib/analysis/paper.js

@@ -12,12 +12,14 @@ import { defaultTrackerBar, trackerBarOf } from "../systems/index.js";
  * copies of one system to say: the three red copies of Welte 225 spread
  * by 0.19 %. It includes the scanner's error along the roll, which the
  * alignment cannot tell from the paper's.
+ * @category Analysis
  */
 export const PAPER_SPREAD = percent(0.2);
 /**
  * How far a paper speed a label or the literature states is taken to be
  * from the speed a copy was cut at: the literature gives the red roll's
  * three metres a minute as 2.9 as well (Bärtsch 2020), which is 3.4 %.
+ * @category Analysis
  */
 export const SPEED_TOLERANCE = 0.035;
 /** The kinds of source that give places on the paper, so that the length between two of them is the paper's. */
@@ -116,6 +118,7 @@ const inverse = (matrix) => {
  * Copies whose places are not places on the paper, such as a roll
  * reader's, say nothing about the paper and are left out. Nothing is
  * said where the edition has no reference copy.
+ * @category Analysis
  */
 export const paperOf = (edition) => {
     const reference = referenceCopyOf(edition);
@@ -225,6 +228,7 @@ const statedSpeed = (copy) => {
  * 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.
+ * @category Analysis
  */
 export const paperSpeedOf = (edition, versionId) => {
     const version = versionIn(edition, versionId);
@@ -248,6 +252,7 @@ const referenceSpeed = (reference) => {
  * the paper, want looking into. None of it is recomputed, so it is cheap
  * to ask; whether an alignment would come out otherwise if found again
  * is `alignmentFor`'s to say.
+ * @category Analysis
  */
 export const alignmentProblems = (edition) => {
     const reference = referenceCopyOf(edition);
@@ -297,6 +302,7 @@ export const alignmentProblems = (edition) => {
  * 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.
+ * @category Analysis
  */
 export const lengthRatioOf = (edition, versionId) => {
     const version = versionIn(edition, versionId);

package/lib/analysis/reservations.d.ts

@@ -1,7 +1,16 @@
 import { RollCopy } from "../model/RollCopy.js";
 import { Version } from "../model/Version.js";
 import { Edition } from "../model/Edition.js";
+/**
+ * The kinds of reservation the edition can have about a copy, in the
+ * order `reservationsAbout` checks for them.
+ * @category Analysis
+ */
 export declare const reservationTypes: readonly ['source-not-stated', 'source-undocumented', 'software-not-named', 'instrument-not-named', 'features-interpreted', 'no-physical-evidence', 'measurement-undocumented', 'not-calibrated', 'system-unknown', 'keeper-unknown'];
+/**
+ * A kind of reservation about a copy.
+ * @category Analysis
+ */
 export type ReservationType = typeof reservationTypes[number];
 /**
  * Something an edition cannot vouch for in one of its copies or
@@ -12,6 +21,7 @@ export type ReservationType = typeof reservationTypes[number];
  * 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.
+ * @category Analysis
  */
 export interface Reservation<T extends string = ReservationType> {
     type: T;
@@ -22,9 +32,22 @@ export interface Reservation<T extends string = ReservationType> {
  * What the edition cannot vouch for in a copy, in the order the
  * checks are listed: where its features came from first, then what
  * the measurement leaves open, then who holds it.
+ * @category Analysis
  */
 export declare const reservationsAbout: (copy: RollCopy) => Reservation[];
+/**
+ * The kinds of reservation the edition can have about a version, in the
+ * order `reservationsAboutVersion` checks for them.
+ * @category Analysis
+ */
 export declare const versionReservationTypes: readonly ['text-not-stated', 'witnessed-by-statement-only', 'no-direct-witness'];
+/**
+ * A kind of reservation about a version.
+ * @category Analysis
+ */
 export type VersionReservationType = typeof versionReservationTypes[number];
-/** What the edition cannot vouch for in a version, in the order the checks are listed. */
+/**
+ * What the edition cannot vouch for in a version, in the order the checks are listed.
+ * @category Analysis
+ */
 export declare const reservationsAboutVersion: (edition: Edition, version: Readonly<Version>) => Reservation<VersionReservationType>[];

package/lib/analysis/reservations.js

@@ -2,6 +2,11 @@ import { bearsPhysicalEvidence, isMeasured, sourceLabels } from "../model/Featur
 import { calibrationOf, featuresOf, measuringSoftwareOf } from "../model/RollCopy.js";
 import { trackerBarOf } from "../systems/index.js";
 import { witnessesOf } from "./witnesses.js";
+/**
+ * The kinds of reservation the edition can have about a copy, in the
+ * order `reservationsAbout` checks for them.
+ * @category Analysis
+ */
 export const reservationTypes = [
     'source-not-stated',
     'source-undocumented',
@@ -98,8 +103,14 @@ const checks = [
  * What the edition cannot vouch for in a copy, in the order the
  * checks are listed: where its features came from first, then what
  * the measurement leaves open, then who holds it.
+ * @category Analysis
  */
 export const reservationsAbout = (copy) => checks.flatMap(check => check(copy) ?? []);
+/**
+ * The kinds of reservation the edition can have about a version, in the
+ * order `reservationsAboutVersion` checks for them.
+ * @category Analysis
+ */
 export const versionReservationTypes = [
     'text-not-stated',
     'witnessed-by-statement-only',
@@ -129,5 +140,8 @@ const witnessedAtFirstHand = (edition, version) => {
     } : undefined;
 };
 const versionChecks = [textStated, witnessedByFeatures, witnessedAtFirstHand];
-/** What the edition cannot vouch for in a version, in the order the checks are listed. */
+/**
+ * What the edition cannot vouch for in a version, in the order the checks are listed.
+ * @category Analysis
+ */
 export const reservationsAboutVersion = (edition, version) => versionChecks.flatMap(check => check(edition, version) ?? []);

package/lib/analysis/sigla.d.ts

@@ -2,6 +2,7 @@ import { Edition } from '../model/Edition.js';
 /**
  * What the sigla are read off: the versions alone, or the edition, whose
  * copies tell which versions a witness shows.
+ * @category Versions and stemma
  */
 export type Stemma = Pick<Edition, 'versions'> | Edition;
 /**
@@ -17,7 +18,11 @@ export type Stemma = Pick<Edition, 'versions'> | Edition;
  *
  * A siglum is computed anew when the stemma or the copies change, so
  * nothing should cite one without saying which state it belongs to.
+ * @category Versions and stemma
  */
 export declare const siglaOf: (stemma: Stemma) => ReadonlyMap<string, string>;
-/** The siglum of one version as the stemma stands, or nothing where the edition holds no such version. */
+/**
+ * The siglum of one version as the stemma stands, or nothing where the edition holds no such version.
+ * @category Versions and stemma
+ */
 export declare const siglumOf: (stemma: Stemma, versionId: string) => string | undefined;

package/lib/analysis/sigla.js

@@ -111,9 +111,13 @@ const marking = (sigla, attested) => new Map([...sigla].map(([id, siglum]) => [i
  *
  * A siglum is computed anew when the stemma or the copies change, so
  * nothing should cite one without saying which state it belongs to.
+ * @category Versions and stemma
  */
 export const siglaOf = (stemma) => holdsCopies(stemma)
     ? marking(alongTheStemma(stemma.versions), attestedVersions(stemma))
     : alongTheStemma(stemma.versions);
-/** The siglum of one version as the stemma stands, or nothing where the edition holds no such version. */
+/**
+ * The siglum of one version as the stemma stands, or nothing where the edition holds no such version.
+ * @category Versions and stemma
+ */
 export const siglumOf = (stemma, versionId) => siglaOf(stemma).get(versionId);

package/lib/analysis/stemma.d.ts

@@ -6,9 +6,13 @@ import { Version } from "../model/Version.js";
  * version up to the root. A stemma that loops back on itself is walked
  * once round, so that an edition in that state can still be read and
  * repaired.
+ * @category Versions and stemma
  */
 export declare const lineageOf: (edition: Pick<Edition, 'versions'>, versionId: string) => Readonly<Version>[];
-/** The version the given one's text is read against, by its principal derivation. */
+/**
+ * The version the given one's text is read against, by its principal derivation.
+ * @category Versions and stemma
+ */
 export declare const predecessorOf: (edition: Pick<Edition, 'versions'>, versionId: string) => Readonly<Version> | undefined;
 /**
  * Every version with its generation: how many principal derivations
@@ -16,6 +20,7 @@ export declare const predecessorOf: (edition: Pick<Edition, 'versions'>, version
  * not hold counts as a root. In a stemma that loops, the loop is walked
  * once round, as `lineageOf` walks it, so that the stemma of an edition
  * in that state can still be drawn and repaired.
+ * @category Versions and stemma
  */
 export declare const withGenerations: (edition: Pick<Edition, 'versions'>) => Array<Version & {
     generation: number;

package/lib/analysis/stemma.js

@@ -6,6 +6,7 @@ import { versionIn } from "../lookup/lookup.js";
  * version up to the root. A stemma that loops back on itself is walked
  * once round, so that an edition in that state can still be read and
  * repaired.
+ * @category Versions and stemma
  */
 export const lineageOf = (edition, versionId) => {
     const lineage = [];
@@ -19,7 +20,10 @@ export const lineageOf = (edition, versionId) => {
     }
     return lineage;
 };
-/** The version the given one's text is read against, by its principal derivation. */
+/**
+ * The version the given one's text is read against, by its principal derivation.
+ * @category Versions and stemma
+ */
 export const predecessorOf = (edition, versionId) => {
     const v = versionIn(edition, versionId);
     const principal = v && principalDerivationOf(v);
@@ -31,6 +35,7 @@ export const predecessorOf = (edition, versionId) => {
  * not hold counts as a root. In a stemma that loops, the loop is walked
  * once round, as `lineageOf` walks it, so that the stemma of an edition
  * in that state can still be drawn and repaired.
+ * @category Versions and stemma
  */
 export const withGenerations = (edition) => edition.versions.map(version => ({
     ...version,

package/lib/analysis/text.d.ts

@@ -3,8 +3,17 @@ import { Edition } from "../model/Edition.js";
 import { FeatureOrPatch, HorizontalSpan, NestedFeature } from "../model/Feature.js";
 import { AnySymbol } from "../model/Symbol.js";
 import { Millimeters } from "../model/Quantity.js";
+/**
+ * The features carrying the symbol, on whichever copy they sit, those a
+ * patch bears included. A carrier the edition holds no feature for is
+ * left out.
+ * @category Lookups
+ */
 export declare const carriersOf: (edition: Pick<Edition, 'copies'>, symbol: AnySymbol) => Readonly<NestedFeature>[];
-/** The carriers that state a place of their own, which a feature on a patch does not. */
+/**
+ * The carriers that state a place of their own, which a feature on a patch does not.
+ * @category Lookups
+ */
 export declare const placedCarriersOf: (edition: Pick<Edition, 'copies'>, symbol: AnySymbol) => Readonly<FeatureOrPatch>[];
 /**
  * Where along the roll the symbol lies, as its carriers put it, or
@@ -23,14 +32,19 @@ export declare const placedCarriersOf: (edition: Pick<Edition, 'copies'>, symbol
  * symbol may be carried by copies of both — averaging a red carrier
  * on track 47 with a green one on 45 would give 46, a legal
  * position a semitone away on either bar.
+ * @category Lookups
  */
 export declare const placeOf: (edition: Pick<Edition, 'copies'>, symbol: AnySymbol) => Readonly<HorizontalSpan> | undefined;
-/** Where the symbol begins, as the median onset of its carriers, or nothing for a symbol without a place. */
+/**
+ * Where the symbol begins, as the median onset of its carriers, or nothing for a symbol without a place.
+ * @category Lookups
+ */
 export declare const onsetOf: (edition: Pick<Edition, 'copies'>, symbol: AnySymbol) => Millimeters | undefined;
 /**
  * The symbols the version shows: what it and its ancestors insert,
  * each version's deletions striking what it or its ancestors inserted.
  * They are worked out once for each state of the edition, and the list
  * is frozen, since everyone who asks is handed the same one.
+ * @category Lookups
  */
 export declare const snapshotOf: (edition: Edition, versionId: string) => readonly Readonly<AnySymbol>[];

package/lib/analysis/text.js

@@ -5,8 +5,17 @@ import { medianOf } from "../collation/statistics.js";
 import { featuresIn } from "../lookup/lookup.js";
 import { perState } from "../lookup/perState.js";
 import { lineageOf } from "./stemma.js";
+/**
+ * The features carrying the symbol, on whichever copy they sit, those a
+ * patch bears included. A carrier the edition holds no feature for is
+ * left out.
+ * @category Lookups
+ */
 export const carriersOf = (edition, symbol) => featuresIn(edition, idsOf(symbol.carriers));
-/** The carriers that state a place of their own, which a feature on a patch does not. */
+/**
+ * The carriers that state a place of their own, which a feature on a patch does not.
+ * @category Lookups
+ */
 export const placedCarriersOf = (edition, symbol) => carriersOf(edition, symbol).filter(isPlaced);
 /**
  * Where along the roll the symbol lies, as its carriers put it, or
@@ -25,6 +34,7 @@ export const placedCarriersOf = (edition, symbol) => carriersOf(edition, symbol)
  * symbol may be carried by copies of both — averaging a red carrier
  * on track 47 with a green one on 45 would give 46, a legal
  * position a semitone away on either bar.
+ * @category Lookups
  */
 export const placeOf = (edition, symbol) => {
     const carriers = placedCarriersOf(edition, symbol);
@@ -34,7 +44,10 @@ export const placeOf = (edition, symbol) => {
         return;
     return { unit: 'mm', from, to };
 };
-/** Where the symbol begins, as the median onset of its carriers, or nothing for a symbol without a place. */
+/**
+ * Where the symbol begins, as the median onset of its carriers, or nothing for a symbol without a place.
+ * @category Lookups
+ */
 export const onsetOf = (edition, symbol) => placeOf(edition, symbol)?.from;
 /** The symbols by onset, those without a place first; symbols at one place keep their order. */
 const inOrderOfPlace = (edition, symbols) => symbols
@@ -48,6 +61,7 @@ const snapshotsIn = perState((_) => new Map());
  * each version's deletions striking what it or its ancestors inserted.
  * They are worked out once for each state of the edition, and the list
  * is frozen, since everyone who asks is handed the same one.
+ * @category Lookups
  */
 export const snapshotOf = (edition, versionId) => {
     const known = snapshotsIn(edition);

package/lib/analysis/witnesses.d.ts

@@ -1,7 +1,16 @@
 import { Belief, Certainty } from "../model/Assumption.js";
 import { Edition } from "../model/Edition.js";
+/**
+ * How a copy bears witness to a version: its features carry what the
+ * version inserts (`carriers`), or it states that it carries the
+ * version (`statement`).
+ * @category Analysis
+ */
 export type WitnessBy = 'carriers' | 'statement';
-/** A copy that bears witness to a version, and how. */
+/**
+ * A copy that bears witness to a version, and how.
+ * @category Analysis
+ */
 export interface Witness {
     /** The copy, by id. */
     copy: string;
@@ -24,6 +33,7 @@ export interface Witness {
  * the latest state it bears. A version left out is reached only through
  * the versions derived from it, or is attested by statement alone, and
  * its text is a reconstruction rather than a reading.
+ * @category Analysis
  */
 export declare const attestedVersions: (edition: Edition) => ReadonlySet<string>;
 /**
@@ -43,15 +53,23 @@ export declare const attestedVersions: (edition: Edition) => ReadonlySet<string>
  * A statement is the editor's own about the version it names and is
  * reported as it stands. A version whose edits are not stated inserts
  * nothing and is witnessed by statement alone.
+ * @category Analysis
  */
 export declare const witnessesOf: (edition: Edition, versionId: string) => Witness[];
 /**
  * The versions the copy bears witness to, each with how, in the order the
  * edition lists its versions.
+ * @category Analysis
  */
 export declare const versionsWitnessedBy: (edition: Edition, copyId: string) => (Witness & {
     version: string;
 })[];
+/**
+ * A copy's statement that it carries a version, where the statement
+ * cannot stand (`carriageProblems`): it is made beside features that
+ * carry symbols, or it names a version the edition lacks.
+ * @category Analysis
+ */
 export type CarriageProblem = {
     copy: string;
     version: string;
@@ -61,5 +79,6 @@ export type CarriageProblem = {
  * 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.
+ * @category Analysis
  */
 export declare const carriageProblems: (edition: Edition) => CarriageProblem[];