Eve library

Nisaba Developer Guide

Guide

Revision 1

On this page

A comprehensive guide for engineers extending, contributing to, or integrating with the Nisaba ancient text analysis platform.

Version: 1.0 Last Updated: 2026-03-02


Table of Contents#

  1. Architecture Overview
  2. Adding New Language Support
  3. Creating Corpus Connectors
  4. Extending the Annotation Type System
  5. Contributing Concept Mappings
  6. Testing Guide
  7. API Reference
  8. CI/CD and Release

1. Architecture Overview#

1.1 Monorepo Structure#

Nisaba lives within the Oshun Nx monorepo under libs/nisaba/. Each sub-directory is an independently publishable package following the @nisaba/<package> naming convention.

text
libs/nisaba/
├── schemas/          # @nisaba/schemas — Zod validation schemas for all domain entities
├── core/             # @nisaba/core — Core types, constants, utilities, error types
├── languages/        # @nisaba/languages — Ancient language handlers (script processing)
├── annotations/      # @nisaba/annotations — W3C WADM standoff annotations
├── assistant/        # @nisaba/assistant — AI-powered translation commentary & variant evaluation
├── canon/            # @nisaba/canon — Canonical text reference systems (all traditions)
├── client/           # @nisaba/client — API client + React hooks (framework-agnostic)
├── comparative/      # @nisaba/comparative — Cross-tradition concept mapping & parallels
├── corpora/          # @nisaba/corpora — Corpus connectors & ingestion pipeline
├── criticism/        # @nisaba/criticism — Textual criticism: collation, stemma, apparatus
├── database/         # @nisaba/database — Database client & migrations
├── editions/         # @nisaba/editions — Critical edition project management
├── geotemporal/      # @nisaba/geotemporal — Geographic timeline & provenance mapping
├── paleography/      # @nisaba/paleography — ML-assisted manuscript analysis
├── philology/        # @nisaba/philology — Linguistic analysis (etymology, semantics, stylometry)
├── standards/        # @nisaba/standards — TEI, Linked Data, encoding standard compliance
├── translations/     # @nisaba/translations — Translation comparison, alignment, divergence
└── workspace/        # @nisaba/workspace — Research environment, split-pane layout, search

1.2 Package Dependency Graph#

The dependency graph is strictly layered. Lower layers never import from higher layers. This ensures that foundation packages remain stable and that domain packages can be used independently.

text
Layer 0 (Foundation):
  @nisaba/schemas     ← Zod schemas, zero Nisaba deps (depends only on zod)
  @nisaba/core        ← Core types, constants, utilities (zero external deps)

Layer 1 (Language Engine):
  @nisaba/languages   ← Depends on @nisaba/core

Layer 2 (Domain Libraries):
  @nisaba/annotations ← Depends on @nisaba/core, @nisaba/schemas
  @nisaba/canon       ← Depends on @nisaba/core
  @nisaba/corpora     ← Depends on @nisaba/core, @nisaba/schemas
  @nisaba/criticism   ← Depends on @nisaba/core, @nisaba/schemas, @nisaba/languages
  @nisaba/editions    ← Depends on @nisaba/core, @nisaba/schemas
  @nisaba/translations← Depends on @nisaba/core, @nisaba/languages
  @nisaba/comparative ← Depends on @nisaba/core
  @nisaba/philology   ← Depends on @nisaba/core, @nisaba/languages
  @nisaba/paleography ← Depends on @nisaba/core
  @nisaba/geotemporal ← Depends on @nisaba/core
  @nisaba/standards   ← Depends on @nisaba/core, @nisaba/schemas
  @nisaba/assistant   ← Depends on @nisaba/core, @nisaba/translations, @nisaba/criticism

Layer 3 (Integration):
  @nisaba/workspace   ← Depends on multiple Layer 2 packages
  @nisaba/database    ← Depends on @nisaba/schemas

Layer 4 (Client):
  @nisaba/client      ← Depends on @nisaba/core (types only)

Rule: A package may only import from packages in the same or lower layers. Cross-layer imports upward are forbidden and enforced by lint rules.

1.3 Core Abstractions#

Three packages form the foundation upon which everything else is built:

@nisaba/core#

Defines the type vocabulary shared across the entire domain:

  • Writing systems (WritingSystem enum): ISO 15924 script codes for every supported writing system, from Sumerian Cuneiform (Xsux) to Runic (Runr).
  • Script metadata (SCRIPT_METADATA): Per-writing-system metadata including Unicode ranges, script direction, display name, and language family.
  • Morphological types (MorphologicalFeatures, PartOfSpeech, VerbStem, NounState, etc.): Language-agnostic morphological categories used across all language handlers.
  • Reference types (CanonicalReference, TextPassage, ReferenceRange): The canonical URI scheme for identifying any passage in any tradition.
  • Tradition types (Tradition, TraditionFamily): Enumeration of all religious and philosophical traditions.
  • Utility functions: Unicode normalization (normalizeNFC), date parsing, confidence scoring, offset arithmetic, and citation formatting.
  • Error types (NisabaError, ValidationError, NotFoundError): Typed error hierarchy for consistent error handling.

Location: libs/nisaba/core/src/

text
core/src/
├── types/
│   ├── writing-systems.ts   # WritingSystem enum, ScriptDirection
│   ├── morphology.ts        # MorphologicalFeatures, PartOfSpeech, etc.
│   ├── reference.ts         # CanonicalReference, TextPassage
│   ├── traditions.ts        # Tradition, TraditionFamily
│   ├── manuscript.ts        # WitnessMetadata, ManuscriptDescription
│   ├── apparatus.ts         # ApparatusEntry, VariantReading
│   ├── annotations.ts       # AnnotationType, AnnotationLayer
│   ├── lexicon.ts           # LexiconEntry, SemanticDomain
│   ├── transliteration.ts   # TransliterationScheme, TranslitResult
│   ├── comparative.ts       # ConceptMapping, ParallelPassage
│   └── index.ts             # Re-exports
├── constants/
│   ├── script-metadata.ts   # SCRIPT_METADATA registry
│   ├── unicode-ranges.ts    # UNICODE_RANGES per writing system
│   ├── tradition-metadata.ts# TRADITION_METADATA registry
│   └── index.ts
├── utils/
│   ├── unicode.ts           # normalizeNFC, isInRange, detectScript
│   ├── offsets.ts           # Byte/char offset conversions
│   ├── dates.ts             # Approximate date parsing (BCE/CE)
│   ├── confidence.ts        # Confidence scoring utilities
│   ├── citations.ts         # Citation formatting
│   ├── references.ts        # Canonical URI parsing and construction
│   └── index.ts
├── errors.ts                # NisabaError hierarchy
└── index.ts                 # Public API surface

@nisaba/schemas#

Zod validation schemas that provide runtime type checking for all domain entities. Every data structure that crosses a trust boundary (API input/output, database read/write, file import/export) has a corresponding Zod schema here.

typescript
// Example: manuscript schema usage
import { ManuscriptWitnessSchema } from '@nisaba/schemas';

const result = ManuscriptWitnessSchema.safeParse(rawData);
if (!result.success) {
  console.error('Validation failed:', result.error.issues);
}

Schema modules:

Module Contents
manuscript.ts Witness metadata, siglum, provenance, dating
variant.ts Variant readings, collation results
apparatus.ts Critical apparatus entries, apparatus formats
annotation.ts W3C Web Annotation Data Model schemas
reference.ts Canonical reference, passage range
tradition.ts Cross-tradition concept mappings
corpus.ts Corpus metadata, document records
geotemporal.ts Geographic coordinates, temporal ranges

@nisaba/languages#

The language engine that makes everything else possible. Each ancient writing system has a ScriptHandler implementation providing character classification, cluster decomposition, vocalization analysis, and normalization.

The package contains:

  • An interfaces/ directory defining the ScriptHandler contract and its extensions (CantillatedScriptHandler, KetivQereScriptHandler).
  • Per-language subdirectories each implementing the handler for that writing system (e.g., hebrew/, ancient-greek/, arabic/, coptic/, cuneiform/, etc.).
  • Cross-cutting modules for tokenization/, transliteration/, and lexicon/ integration.

1.4 Domain Libraries#

Each domain library addresses a specific scholarly workflow:

@nisaba/criticism -- The textual criticism engine. Contains:

  • collation-engine.ts: CollateX-compatible automatic collation using Dekker's variant graph model.
  • fuzzy-matching.ts: Orthographic variant detection with language-specific normalization.
  • block-alignment.ts: Large-scale structural variant detection.
  • apparatus-generation.ts: Automatic apparatus entry generation from collation data.
  • apparatus-typography.ts: Print-quality apparatus formatting.
  • cbgm-analysis.ts: Coherence-Based Genealogical Method implementation.
  • lachmannian-reconstruction.ts: Classical stemmatic reconstruction.
  • stemma-visualization.ts: Interactive stemma rendering.
  • neighbornet.ts: NeighborNet algorithm for split-graph visualization.
  • contamination-detection.ts: Detecting mixed manuscript traditions.
  • scribal-error-taxonomy.ts: Classifying scribal errors by probable cause.
  • manual-collation.ts: Scholar-reviewed collation with accept/reject.
  • siglum-management.ts: Witness siglum registry and shorthand notation.
  • leiden-conventions.ts: Leiden convention markup for epigraphic texts.
  • lacuna-registry.ts: Tracking physical damage and proposed restorations.
  • iiif-linking.ts: IIIF manifest integration for manuscript images.
  • collation-export.ts: Export in TEI-XML, JSON, and other formats.
  • reconstruction-proposals.ts: Proposed restorations for damaged text.

@nisaba/translations -- Translation comparison engine. Contains:

  • alignment/: Sentence and word alignment algorithms (Gale-Church, IBM models, neural alignment).
  • divergence/: Semantic divergence scoring, theological divergence flagging, omission/addition detection, paraphrase scoring.
  • views/: Display mode rendering (side-by-side, synoptic, interlinear, reverse interlinear, parallel text).
  • types/: Type definitions for alignment, divergence, and view state.

@nisaba/comparative -- Cross-tradition analysis. Contains:

  • concept-equivalence.ts: Curated concept mapping registry with CRUD, similarity taxonomy, and evidence grading.
  • parallel-passage-detection.ts: Algorithms for detecting thematic parallels across traditions using semantic similarity, motif matching, and structural analysis.
  • motif-theme-tracking.ts: Universal motif catalog with attestation tracking and timeline visualization.
  • influence-network.ts: Directed influence graph with evidence-graded edges.

@nisaba/workspace -- The research environment. Contains:

  • research-environment.ts: Research project management (lifecycle, roles, milestones), split-pane reading environment (layout, sync, fonts, themes, keybindings), and unified cross-corpora search (lemma-aware, morphology-aware, Boolean, proximity, field-restricted).
  • personal-library-export.ts: Reading lists, bookmarks, highlights, and citation manager integration.

1.5 Client SDK Architecture#

The @nisaba/client package provides a typed API client and framework-agnostic state containers.

API Client (api-client.ts):

  • Zero-dependency, pure TypeScript HTTP client using native fetch.
  • Full typed interfaces for every Nisaba API endpoint.
  • Automatic retry with exponential backoff and jitter.
  • Request/response interceptor pipeline.
  • In-memory response cache with configurable TTL.
  • Pagination support (offset-based and cursor-based).
  • Streaming support for large result sets.
  • Structured error types (NisabaApiError) with error codes.
typescript
import { NisabaClient } from '@nisaba/client';

const client = new NisabaClient({
  baseUrl: 'https://api.nisaba.example.com/v1',
  apiKey: 'your-api-key',
  timeout: 30_000,
  retryConfig: { maxRetries: 3, baseDelayMs: 500 },
});

// Typed API calls
const corpus = await client.corpora.get('etcsl');
const results = await client.search.execute({
  query: 'lemma:λόγος',
  corpus: 'na28',
});

React Hooks (react-hooks.ts):

Not React-specific despite the name. Each "hook" is a factory function returning a Subscription<T> -- a framework-agnostic state container with getState/subscribe/destroy semantics. Works with React (via useSyncExternalStore), Solid, Svelte, Vue, or any other UI framework.

typescript
import { createCorpusSearchStore } from '@nisaba/client';

// Create a search store
const store = createCorpusSearchStore(client, {
  query: 'lemma:חסד',
  corpus: 'bhs',
});

// Subscribe to state changes
const unsubscribe = store.subscribe(() => {
  const state = store.getState();
  console.log('Results:', state.results);
});

// With React
function SearchResults() {
  const state = useSyncExternalStore(
    store.subscribe,
    store.getState,
  );
  return <div>{state.results.map(r => <ResultCard key={r.id} result={r} />)}</div>;
}

// Clean up
store.destroy();

2. Adding New Language Support#

This section walks through the complete process of adding support for a new ancient writing system to Nisaba. We use a hypothetical example -- Old South Arabian (Musnad script) -- to illustrate every step.

2.1 Overview of the Process#

Adding a new language involves the following steps:

  1. Add Unicode range constants to @nisaba/core.
  2. Register script metadata in @nisaba/core.
  3. Create the language handler directory in @nisaba/languages.
  4. Implement the ScriptHandler interface.
  5. Add morphological features (if the language has inflection).
  6. Register the handler in the languages index.
  7. Write comprehensive tests.

2.2 Step 1: Add Unicode Ranges#

Every writing system is identified by its Unicode block(s). Add the ranges to libs/nisaba/core/src/constants/unicode-ranges.ts:

typescript
// In libs/nisaba/core/src/constants/unicode-ranges.ts

export const UNICODE_RANGES = {
  // ... existing ranges ...

  // Old South Arabian (Musnad)
  OLD_SOUTH_ARABIAN: {
    start: 0x10a60,
    end: 0x10a7f,
    name: 'Old South Arabian',
  },
} as const;

The range must correspond to the official Unicode block allocation. Check the Unicode Character Database at https://www.unicode.org/charts/ for the correct range.

2.3 Step 2: Register Script Metadata#

Add an entry to the WritingSystem enum in libs/nisaba/core/src/types/writing-systems.ts:

typescript
// In libs/nisaba/core/src/types/writing-systems.ts

export enum WritingSystem {
  // ... existing entries ...

  /** Old South Arabian (Musnad) script */
  OLD_SOUTH_ARABIAN = 'Sarb',
}

Use the ISO 15924 script code as the enum value. For Old South Arabian, this is Sarb.

Then register the metadata in libs/nisaba/core/src/constants/script-metadata.ts:

typescript
// In libs/nisaba/core/src/constants/script-metadata.ts

import { WritingSystem } from '../types/writing-systems.js';
import { UNICODE_RANGES } from './unicode-ranges.js';

export const SCRIPT_METADATA: Record<WritingSystem, WritingSystemMetadata> = {
  // ... existing entries ...

  [WritingSystem.OLD_SOUTH_ARABIAN]: {
    writingSystem: WritingSystem.OLD_SOUTH_ARABIAN,
    displayName: 'Old South Arabian',
    nativeName: 'Musnad (𐩣𐩪𐩬𐩵)',
    iso15924: 'Sarb',
    direction: 'rtl' as ScriptDirection,
    unicodeRanges: [UNICODE_RANGES.OLD_SOUTH_ARABIAN],
    languageFamily: 'Semitic',
    historicalPeriod: { start: -800, end: 600 },
    hasVocalization: false,
    hasCantillation: false,
    primaryLanguages: ['Sabaean', 'Minaean', 'Qatabanian', 'Hadramitic'],
  },
};

The WritingSystemMetadata interface requires the following fields:

Field Type Description
writingSystem WritingSystem Enum value for this writing system
displayName string English display name
nativeName string Name in the script itself (where possible)
iso15924 string ISO 15924 four-letter code
direction ScriptDirection 'ltr', 'rtl', or 'ttb'
unicodeRanges UnicodeRange[] Array of Unicode block ranges for this script
languageFamily string Linguistic family (Semitic, Indo-European, etc.)
historicalPeriod { start, end } Approximate date range of use (negative = BCE)
hasVocalization boolean Whether the script has vowel pointing marks
hasCantillation boolean Whether the script has cantillation/accent marks
primaryLanguages string[] Languages written in this script

2.4 Step 3: Create the Language Handler Directory#

Create the directory structure for the new handler:

text
libs/nisaba/languages/src/old-south-arabian/
├── __tests__/
│   ├── classifier.test.ts
│   ├── clusters.test.ts
│   ├── handler.test.ts
│   └── transliteration.test.ts
├── classifier.ts          # Character classification
├── clusters.ts            # Cluster decomposition
├── constants/
│   └── characters.ts      # Character constants (codepoints, names)
├── handler.ts             # Main ScriptHandler implementation
├── index.ts               # Public exports
├── transliteration.ts     # Transliteration to/from Roman
└── vocalization.ts        # Vocalization analysis (if applicable)

2.5 Step 4: Implement the ScriptHandler Interface#

The ScriptHandler interface is defined in libs/nisaba/languages/src/interfaces/script-handler.ts. Every language handler must implement it. The core interface requires these methods:

typescript
interface ScriptHandler {
  /** Which writing system this handler processes */
  readonly writingSystem: WritingSystem;

  /** Script metadata from the core registry */
  readonly metadata: WritingSystemMetadata;

  /** Script direction: 'ltr', 'rtl', or 'ttb' */
  readonly direction: ScriptDirection;

  /**
   * Classify a single character.
   * Returns CharacterInfo with category, Unicode name, and phonetic value.
   * Returns null if the character does not belong to this script.
   */
  classifyCharacter(char: string): CharacterInfo | null;

  /**
   * Test whether a single character belongs to this script.
   */
  isScriptCharacter(char: string): boolean;

  /**
   * Test whether a string contains any characters from this script.
   */
  containsScript(text: string): boolean;

  /**
   * Decompose text into clusters. A cluster is the minimal grapheme unit:
   * a base character plus all its combining marks (vowels, modifiers, etc.).
   * Returns an array of CharacterCluster objects with offset information.
   */
  decomposeClusters(text: string): CharacterCluster[];

  /**
   * Analyze the vocalization (vowel pointing) of the text.
   * Returns information about which vocalization system is used,
   * coverage ratio, and confidence score.
   */
  analyzeVocalization(text: string): VocalizationAnalysis;

  /**
   * Remove vocalization marks, returning consonantal text.
   */
  stripVocalization(text: string): string;

  /**
   * Apply NFC normalization and script-specific canonical form.
   */
  normalize(text: string): string;
}

Here is a skeleton implementation for Old South Arabian:

typescript
// libs/nisaba/languages/src/old-south-arabian/handler.ts

import {
  WritingSystem,
  type WritingSystemMetadata,
  type ScriptDirection,
  SCRIPT_METADATA,
  normalizeNFC,
} from '@nisaba/core';

import type {
  ScriptHandler,
  CharacterInfo,
  CharacterCluster,
  VocalizationAnalysis,
} from '../interfaces/script-handler.js';

import {
  classifyCharacter,
  containsOldSouthArabian,
  isOSACharacter,
} from './classifier.js';
import { decomposeClusters } from './clusters.js';

export class OldSouthArabianScriptHandler implements ScriptHandler {
  readonly writingSystem = WritingSystem.OLD_SOUTH_ARABIAN;
  readonly metadata: WritingSystemMetadata;
  readonly direction: ScriptDirection = 'rtl';

  constructor() {
    this.metadata = SCRIPT_METADATA[WritingSystem.OLD_SOUTH_ARABIAN];
  }

  classifyCharacter(char: string): CharacterInfo | null {
    return classifyCharacter(char);
  }

  isScriptCharacter(char: string): boolean {
    const cp = char.codePointAt(0);
    return cp !== undefined && isOSACharacter(cp);
  }

  containsScript(text: string): boolean {
    return containsOldSouthArabian(text);
  }

  decomposeClusters(text: string): CharacterCluster[] {
    return decomposeClusters(text);
  }

  analyzeVocalization(text: string): VocalizationAnalysis {
    // Old South Arabian is a consonantal script without vocalization marks.
    // Return an unvocalized analysis for any input.
    return {
      system: 'unvocalized' as const,
      confidence: 1.0,
      coverage: 0,
      totalConsonants: text.length,
      vocalizedConsonants: 0,
      vowelMarks: [],
    };
  }

  stripVocalization(text: string): string {
    // No vocalization to strip in Old South Arabian.
    return text;
  }

  normalize(text: string): string {
    return normalizeNFC(text);
  }
}

Implementing the Classifier#

The classifier maps each Unicode code point to a CharacterInfo object. For Old South Arabian:

typescript
// libs/nisaba/languages/src/old-south-arabian/classifier.ts

import {
  CharacterCategory,
  type CharacterInfo,
} from '../interfaces/script-handler.js';
import { UNICODE_RANGES } from '@nisaba/core';

const OSA_RANGE = UNICODE_RANGES.OLD_SOUTH_ARABIAN;

/** Character name and phonetic data for each Old South Arabian letter */
const OSA_CHARACTERS: ReadonlyMap<number, { name: string; phonetic: string }> =
  new Map([
    [0x10a60, { name: 'OLD SOUTH ARABIAN LETTER HE', phonetic: 'h' }],
    [0x10a61, { name: 'OLD SOUTH ARABIAN LETTER LAMEDH', phonetic: 'l' }],
    [0x10a62, { name: 'OLD SOUTH ARABIAN LETTER HETH', phonetic: 'ḥ' }],
    [0x10a63, { name: 'OLD SOUTH ARABIAN LETTER MEM', phonetic: 'm' }],
    // ... continue for all 32 letters (0x10a60 - 0x10a7c) ...
    [0x10a7d, { name: 'OLD SOUTH ARABIAN NUMBER ONE', phonetic: '1' }],
    [0x10a7e, { name: 'OLD SOUTH ARABIAN NUMBER FIFTY', phonetic: '50' }],
  ]);

export function isOSACharacter(codePoint: number): boolean {
  return codePoint >= OSA_RANGE.start && codePoint <= OSA_RANGE.end;
}

export function containsOldSouthArabian(text: string): boolean {
  for (const char of text) {
    const cp = char.codePointAt(0);
    if (cp !== undefined && isOSACharacter(cp)) return true;
  }
  return false;
}

export function classifyCharacter(char: string): CharacterInfo | null {
  const cp = char.codePointAt(0);
  if (cp === undefined || !isOSACharacter(cp)) return null;

  const data = OSA_CHARACTERS.get(cp);
  if (!data) {
    return {
      character: char,
      codePoint: cp,
      unicodeName: `OLD SOUTH ARABIAN U+${cp.toString(16).toUpperCase()}`,
      category: CharacterCategory.UNKNOWN,
      isCombining: false,
    };
  }

  const isNumeral = cp >= 0x10a7d;

  return {
    character: char,
    codePoint: cp,
    unicodeName: data.name,
    category: isNumeral
      ? CharacterCategory.NUMERAL
      : CharacterCategory.CONSONANT,
    isCombining: false,
    phonetic: data.phonetic,
  };
}

Implementing Cluster Decomposition#

Old South Arabian is a purely consonantal script without combining marks, so cluster decomposition is straightforward: each character is its own cluster. For scripts with combining marks (like Hebrew or Arabic), this is where you handle the grouping of base characters with their vowel points, modifiers, and cantillation marks.

typescript
// libs/nisaba/languages/src/old-south-arabian/clusters.ts

import type { CharacterCluster } from '../interfaces/script-handler.js';
import { classifyCharacter, isOSACharacter } from './classifier.js';

export function decomposeClusters(text: string): CharacterCluster[] {
  const clusters: CharacterCluster[] = [];
  let offset = 0;

  for (const char of text) {
    const cp = char.codePointAt(0);
    if (cp === undefined) {
      offset += char.length;
      continue;
    }

    const info = classifyCharacter(char);
    const isScript = isOSACharacter(cp);

    clusters.push({
      text: char,
      offset,
      length: char.length,
      base: isScript && info ? info : undefined,
      modifiers: [],
      vowels: [],
      cantillation: [],
      isValid: isScript,
    });

    offset += char.length;
  }

  return clusters;
}

2.6 Step 5: Add Morphological Features#

If the language has inflectional morphology, you need to define its morphological categories. Create a morphology/ directory within the handler:

text
libs/nisaba/languages/src/old-south-arabian/morphology/
├── features.ts      # Language-specific morphological enums
├── parser.ts        # Morphological analysis implementation
└── index.ts         # Public exports

Old South Arabian has basic Semitic root-pattern morphology. Define the features:

typescript
// libs/nisaba/languages/src/old-south-arabian/morphology/features.ts

/** Verb forms attested in Old South Arabian inscriptions */
export enum OSAVerbForm {
  /** Basic G-stem (comparable to Hebrew Qal) */
  GROUND = 'G',
  /** D-stem (comparable to Hebrew Piel) */
  D_STEM = 'D',
  /** Causative H-stem (comparable to Hebrew Hiphil) */
  H_STEM = 'H',
  /** T-stem reflexive/passive */
  T_STEM = 'tG',
  /** tD-stem */
  TD_STEM = 'tD',
}

/** Noun states */
export enum OSANounState {
  ABSOLUTE = 'ABSOLUTE',
  CONSTRUCT = 'CONSTRUCT',
  DETERMINED = 'DETERMINED',
}

/** Case endings (South Arabian languages retained case markers longer) */
export enum OSACase {
  NOMINATIVE = 'NOMINATIVE',
  ACCUSATIVE = 'ACCUSATIVE',
  GENITIVE = 'GENITIVE',
}

2.7 Step 6: Register the Handler#

Add the new handler to the languages package index:

typescript
// libs/nisaba/languages/src/index.ts

// ... existing exports ...

// Old South Arabian
export { OldSouthArabianScriptHandler } from './old-south-arabian/handler.js';
export * from './old-south-arabian/index.js';

2.8 Step 7: Write Tests#

Every language handler requires comprehensive test coverage. The minimum test requirements are:

  1. Character classification tests: Verify that every character in the Unicode range is correctly classified (category, name, phonetic value).
  2. Boundary tests: Verify that characters just outside the Unicode range return null.
  3. Cluster decomposition tests: Verify correct grouping of base characters and combining marks.
  4. Vocalization analysis tests: Verify detection of vocalization systems.
  5. Normalization tests: Verify that normalize produces canonical forms.
  6. Script detection tests: Verify containsScript and isScriptCharacter.
  7. Round-trip transliteration tests: If transliteration is implemented, verify that transliterate(detransliterate(text)) === text.

Example test file:

typescript
// libs/nisaba/languages/src/old-south-arabian/__tests__/handler.test.ts

import { describe, it, expect } from 'vitest';
import { OldSouthArabianScriptHandler } from '../handler.js';
import { CharacterCategory } from '../../interfaces/script-handler.js';

describe('OldSouthArabianScriptHandler', () => {
  const handler = new OldSouthArabianScriptHandler();

  describe('classifyCharacter', () => {
    it('classifies Old South Arabian he as a consonant', () => {
      const info = handler.classifyCharacter('\u{10A60}');
      expect(info).not.toBeNull();
      expect(info!.category).toBe(CharacterCategory.CONSONANT);
      expect(info!.phonetic).toBe('h');
    });

    it('classifies number characters as numerals', () => {
      const info = handler.classifyCharacter('\u{10A7D}');
      expect(info).not.toBeNull();
      expect(info!.category).toBe(CharacterCategory.NUMERAL);
    });

    it('returns null for non-OSA characters', () => {
      expect(handler.classifyCharacter('A')).toBeNull();
      expect(handler.classifyCharacter('א')).toBeNull();
    });
  });

  describe('isScriptCharacter', () => {
    it('returns true for OSA characters', () => {
      expect(handler.isScriptCharacter('\u{10A60}')).toBe(true);
      expect(handler.isScriptCharacter('\u{10A7E}')).toBe(true);
    });

    it('returns false for non-OSA characters', () => {
      expect(handler.isScriptCharacter('A')).toBe(false);
      expect(handler.isScriptCharacter('ב')).toBe(false);
    });
  });

  describe('containsScript', () => {
    it('detects OSA in mixed text', () => {
      expect(handler.containsScript('Text with \u{10A60}\u{10A61}')).toBe(true);
    });

    it('returns false for text without OSA', () => {
      expect(handler.containsScript('No Old South Arabian here')).toBe(false);
    });
  });

  describe('decomposeClusters', () => {
    it('decomposes each character as its own cluster', () => {
      const text = '\u{10A60}\u{10A61}\u{10A62}';
      const clusters = handler.decomposeClusters(text);
      expect(clusters).toHaveLength(3);
      expect(clusters[0].text).toBe('\u{10A60}');
      expect(clusters[0].offset).toBe(0);
      expect(clusters[0].isValid).toBe(true);
    });
  });

  describe('analyzeVocalization', () => {
    it('always returns unvocalized for OSA text', () => {
      const analysis = handler.analyzeVocalization('\u{10A60}\u{10A61}');
      expect(analysis.system).toBe('unvocalized');
      expect(analysis.confidence).toBe(1.0);
      expect(analysis.coverage).toBe(0);
    });
  });

  describe('normalize', () => {
    it('applies NFC normalization', () => {
      const text = '\u{10A60}';
      expect(handler.normalize(text)).toBe(text);
    });
  });
});

Run tests with:

bash
npx vitest run libs/nisaba/languages/src/old-south-arabian/__tests__/

2.9 Testing Requirements Summary#

Test Category Minimum Tests Requirement
Character classification 1 per char Every codepoint in the range must be tested
Boundary conditions 4 Characters at range edges and just outside
Cluster decomposition 10 Simple text, mixed scripts, combining marks, empty input
Vocalization analysis 5 Each vocalization system variant + unvocalized
Normalization 5 NFC, presentation forms, mixed content
Script detection 5 Pure script, mixed, empty, non-script
Transliteration 10 Round-trip for representative characters

3. Creating Corpus Connectors#

Corpus connectors bring external text repositories into Nisaba. Each connector transforms source-specific data formats into Nisaba's canonical internal representation.

3.1 Connector Architecture#

The connector system has three stages:

text
Source Repository → Connector → Ingestion Pipeline → Nisaba Corpus Store
                    (fetch +     (chunk + normalize    (indexed, searchable,
                     parse)       + metadata extract)    annotatable)

Connector (libs/nisaba/corpora/src/): Responsible for fetching raw data from an external source and parsing it into Nisaba's internal document representation.

Ingestion Pipeline (libs/nisaba/corpora/src/ingestion-pipeline.ts): Receives parsed documents and applies chunking, metadata normalization, and synchronization scheduling.

Existing connectors are organized by tradition:

  • religious-corpus-connectors.ts: SWORD (Bible modules), USFM, OSIS, Sefaria
  • classical-corpus-connectors.ts: Perseus, TLG, PHI, ETCSL, CDLI, ORACC
  • specialized-corpus-connectors.ts: SuttaCentral, CBETA, SARIT, CTP, GRETIL

3.2 Implementing a New Connector#

To add a connector for a new data source, implement the CorpusConnector interface:

typescript
/** Interface that all corpus connectors must implement */
export interface CorpusConnector {
  /** Unique identifier for this connector */
  readonly connectorId: string;

  /** Human-readable name */
  readonly displayName: string;

  /** The tradition(s) this connector serves */
  readonly traditions: readonly Tradition[];

  /** Source format identifier */
  readonly sourceFormat: SourceFormat;

  /**
   * Discover available documents in the source repository.
   * Returns a list of document metadata records without fetching full text.
   */
  discover(options?: DiscoveryOptions): Promise<readonly DocumentMetadata[]>;

  /**
   * Fetch and parse a single document by its source-specific identifier.
   * Returns the document in Nisaba's canonical representation.
   */
  fetch(sourceId: string, options?: FetchOptions): Promise<ParsedDocument>;

  /**
   * Fetch and parse multiple documents (batch operation).
   * Implementations should respect rate limits and handle pagination.
   */
  fetchBatch(
    sourceIds: readonly string[],
    options?: FetchBatchOptions
  ): AsyncIterable<ParsedDocument>;

  /**
   * Check whether a document has been updated since the last sync.
   * Used by the synchronization scheduler for incremental updates.
   */
  hasUpdates(
    sourceId: string,
    lastSyncHash: string
  ): Promise<{ updated: boolean; newHash: string }>;
}

Source Formats#

Nisaba supports the following source formats, each with a dedicated parser:

Format Parser Location Description
TEI-XML tei-xml-parser.ts Text Encoding Initiative P5 XML
USFM scripture-format-parsers.ts United Bible Societies markup
OSIS scripture-format-parsers.ts Open Scripture Information Standard
ATF atf-parser.ts ASCII Transliteration Format
JSON (inline in each connector) Various API response formats
Plain Text (inline in each connector) UTF-8 with minimal structure

3.3 Example: Creating a Connector for a Digital Library#

Suppose we want to create a connector for a hypothetical "Digital Avestan Corpus" (DAC) that exposes an HTTP JSON API.

typescript
// libs/nisaba/corpora/src/avestan-corpus-connector.ts

import type {
  CorpusConnector,
  DiscoveryOptions,
  DocumentMetadata,
  FetchOptions,
  FetchBatchOptions,
  ParsedDocument,
} from './types.js';
import { Tradition } from '@nisaba/core';

/** Configuration for the DAC connector */
export interface DACConnectorConfig {
  readonly baseUrl: string;
  readonly apiKey?: string;
  readonly timeout?: number;
}

export class DigitalAvestanCorpusConnector implements CorpusConnector {
  readonly connectorId = 'dac' as const;
  readonly displayName = 'Digital Avestan Corpus';
  readonly traditions = [Tradition.ZOROASTRIANISM] as const;
  readonly sourceFormat = 'json' as const;

  private readonly baseUrl: string;
  private readonly apiKey?: string;
  private readonly timeout: number;

  constructor(config: DACConnectorConfig) {
    this.baseUrl = config.baseUrl.replace(/\/+$/, '');
    this.apiKey = config.apiKey;
    this.timeout = config.timeout ?? 30_000;
  }

  async discover(
    options?: DiscoveryOptions
  ): Promise<readonly DocumentMetadata[]> {
    const url = new URL('/api/v1/texts', this.baseUrl);
    if (options?.language) url.searchParams.set('language', options.language);
    if (options?.limit) url.searchParams.set('limit', String(options.limit));

    const response = await this.fetchWithTimeout(url.toString());
    const data = await response.json();

    return data.texts.map((text: Record<string, unknown>) => ({
      sourceId: String(text.id),
      title: String(text.title),
      language: 'avestan',
      tradition: 'ZOROASTRIANISM',
      dateRange: { start: text.dateStart, end: text.dateEnd },
      genre: String(text.genre ?? 'unknown'),
      sourceUrl: `${this.baseUrl}/texts/${text.id}`,
    }));
  }

  async fetch(
    sourceId: string,
    options?: FetchOptions
  ): Promise<ParsedDocument> {
    const url = `${this.baseUrl}/api/v1/texts/${sourceId}`;
    const response = await this.fetchWithTimeout(url);
    const data = await response.json();

    return {
      id: `dac:${sourceId}`,
      sourceConnector: this.connectorId,
      sourceId,
      title: String(data.title),
      language: 'avestan',
      writingSystem: 'Avst',
      tradition: 'ZOROASTRIANISM',
      text: String(data.content),
      metadata: {
        author: data.author ?? null,
        dateRange: data.dateRange ?? null,
        genre: data.genre ?? null,
        references: data.references ?? [],
      },
      contentHash: await this.computeHash(String(data.content)),
      fetchedAt: new Date().toISOString(),
    };
  }

  async *fetchBatch(
    sourceIds: readonly string[],
    options?: FetchBatchOptions
  ): AsyncIterable<ParsedDocument> {
    const concurrency = options?.concurrency ?? 3;
    const queue = [...sourceIds];

    while (queue.length > 0) {
      const batch = queue.splice(0, concurrency);
      const results = await Promise.all(batch.map((id) => this.fetch(id)));
      for (const result of results) {
        yield result;
      }
    }
  }

  async hasUpdates(
    sourceId: string,
    lastSyncHash: string
  ): Promise<{ updated: boolean; newHash: string }> {
    const doc = await this.fetch(sourceId);
    return {
      updated: doc.contentHash !== lastSyncHash,
      newHash: doc.contentHash,
    };
  }

  // --- Private helpers ---

  private async fetchWithTimeout(url: string): Promise<Response> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), this.timeout);

    try {
      const headers: Record<string, string> = {
        Accept: 'application/json',
      };
      if (this.apiKey) {
        headers['Authorization'] = `Bearer ${this.apiKey}`;
      }

      const response = await fetch(url, {
        headers,
        signal: controller.signal,
      });

      if (!response.ok) {
        throw new Error(
          `DAC API error: ${response.status} ${response.statusText}`
        );
      }

      return response;
    } finally {
      clearTimeout(timer);
    }
  }

  private async computeHash(content: string): Promise<string> {
    const bytes = new TextEncoder().encode(content);
    const digest = await crypto.subtle.digest('SHA-256', bytes);
    return Array.from(new Uint8Array(digest))
      .map((byte) => byte.toString(16).padStart(2, '0'))
      .join('');
  }
}

3.4 Integrating with the Ingestion Pipeline#

After creating the connector, register it with the ingestion pipeline:

typescript
import { DigitalAvestanCorpusConnector } from './avestan-corpus-connector.js';
import { IngestionPipeline } from './ingestion-pipeline.js';

const connector = new DigitalAvestanCorpusConnector({
  baseUrl: 'https://api.digital-avestan-corpus.org',
  apiKey: process.env.DAC_API_KEY,
});

const pipeline = new IngestionPipeline();
pipeline.registerConnector(connector);

// Discover and ingest all available texts
const documents = await connector.discover();
for (const doc of documents) {
  await pipeline.ingest(connector, doc.sourceId, {
    chunkingStrategy: 'verse-aware',
    tradition: 'ZOROASTRIANISM',
    language: 'avestan',
  });
}

3.5 Chunking Strategies#

The ingestion pipeline applies a chunking strategy to split large documents into searchable, annotatable segments. Available strategies:

Strategy Best For Behavior
verse-aware Scripture, poetry Splits on verse/stanza boundaries
pericope-aware Narrative texts Splits on narrative unit boundaries
section-aware Prose treatises, philosophical works Splits on chapter/section boundaries
parallel-preserving Synoptic texts (Gospels, parallel suttas) Maintains alignment across parallel documents
fixed-size Fallback for unstructured text Fixed token-count chunks with configurable overlap
semantic Any text requiring semantic coherence within chunks Uses NLP to detect topic boundaries

3.6 Format Parsers#

If your source uses a standard format, you can use an existing parser:

TEI-XML Parser (tei-xml-parser.ts):

Handles TEI P5 XML documents with full support for header metadata extraction, structural parsing, critical apparatus, named entities, linguistic annotations, manuscript descriptions, and bibliographic data. Supports EpiDoc variant for epigraphic and papyrological texts.

typescript
import { parseTEI } from './tei-xml-parser.js';

const document = parseTEI(xmlString, {
  profile: 'STANDARD',
  extractEntities: true,
  parseApparatus: true,
});

ATF Parser (atf-parser.ts):

Handles ASCII Transliteration Format used for cuneiform texts (CDLI, ORACC). Parses transliterations, translations, comments, and structural markers.

typescript
import { parseATF } from './atf-parser.js';

const document = parseATF(atfString, {
  signListVersion: 'MZL',
  includeTranslations: true,
});

Scripture Format Parsers (scripture-format-parsers.ts):

Handles USFM, USX, and OSIS formats for biblical texts. Extracts verse-level structure, footnotes, cross-references, and formatting markers.


4. Extending the Annotation Type System#

4.1 Annotation Schema Overview#

Nisaba's annotation system is built on the W3C Web Annotation Data Model (WADM). Annotations are stored as standoff data: they reference the base text by position selectors but never modify the source text.

The core annotation architecture lives in libs/nisaba/annotations/src/:

text
annotations/src/
├── standoff-annotations.ts    # W3C WADM storage, selectors, type registry
├── collaborative-annotations.ts # Real-time collaboration, conflict resolution
├── annotation-exports.ts      # Export annotations in various formats
└── __tests__/
    ├── standoff-annotations.test.ts
    └── collaborative-annotations.test.ts

Each annotation has:

  • Target: A reference to the text being annotated, specified by selectors (TextPositionSelector, TextQuoteSelector, or FragmentSelector).
  • Body: The content of the annotation (text, structured data, or a link).
  • Motivation: Why the annotation was created (commenting, classifying, tagging, etc.) per the W3C vocabulary.
  • Type: A Nisaba-specific scholarly annotation type from the type registry.
  • Layer: The annotation layer this belongs to (textual, linguistic, translation, critical, comparative, structural, pedagogical, or custom).

4.2 Creating New Annotation Types#

The annotation type system uses a registry pattern. To add a new type, you define the type metadata and register it.

Example: Adding a "Syntactic Tree" annotation type.

This type would allow scholars to annotate a text passage with a syntactic parse tree, useful for linguistic analysis of ancient language syntax.

Step 1: Define the annotation body schema:

typescript
// In your module or in standoff-annotations.ts

/** Body content for a syntactic tree annotation */
export interface SyntacticTreeBody {
  readonly kind: 'syntactic-tree';
  /** The syntactic parse tree in bracketed notation */
  readonly tree: string;
  /** The parser or method used to generate this tree */
  readonly parser: string;
  /** Language of the parsed text */
  readonly language: string;
  /** Node labels used (e.g., 'S', 'NP', 'VP', 'PP') */
  readonly labels: readonly string[];
  /** Optional confidence score (0-1) if ML-generated */
  readonly confidence?: number;
  /** Optional freeform notes by the annotator */
  readonly notes?: string;
}

Step 2: Register the type in the annotation type registry:

typescript
import {
  AnnotationTypeRegistry,
  type AnnotationTypeDefinition,
} from '../standoff-annotations.js';

const syntacticTreeType: AnnotationTypeDefinition = {
  typeId: 'syntactic-tree',
  displayName: 'Syntactic Tree',
  description:
    'A syntactic parse tree annotation showing the hierarchical ' +
    'phrase structure of a text passage.',
  category: 'linguistic',
  motivation: 'classifying',
  applicableLayers: ['linguistic', 'pedagogical'],
  bodySchema: {
    kind: 'syntactic-tree',
    requiredFields: ['tree', 'parser', 'language', 'labels'],
    optionalFields: ['confidence', 'notes'],
  },
  subtypes: [
    { id: 'constituency', displayName: 'Constituency Parse' },
    { id: 'dependency', displayName: 'Dependency Parse' },
    { id: 'functional', displayName: 'Functional Grammar' },
  ],
  defaultLayer: 'linguistic',
};

// Register with the global registry
AnnotationTypeRegistry.register(syntacticTreeType);

Step 3: Create annotations of this type:

typescript
import { AnnotationStore, createAnnotation } from '../standoff-annotations.js';

const store = new AnnotationStore();

const annotation = createAnnotation({
  target: {
    source: 'nisaba://bible/gen/1:1',
    selector: {
      type: 'TextPositionSelector',
      start: 0,
      end: 24,
    },
  },
  body: {
    kind: 'syntactic-tree',
    tree: '[S [PP [P בְּרֵאשִׁית] [VP [V בָּרָא] [NP אֱלֹהִים] [NP [Det אֵת] [NP הַשָּׁמַיִם] [Conj וְ] [Det אֵת] [NP הָאָרֶץ]]]]',
    parser: 'manual',
    language: 'hebrew',
    labels: ['S', 'PP', 'P', 'VP', 'V', 'NP', 'Det', 'Conj'],
    notes:
      'Initial prepositional phrase followed by verb-subject-object structure.',
  } satisfies SyntacticTreeBody,
  motivation: 'classifying',
  type: 'syntactic-tree',
  layer: 'linguistic',
  creator: 'scholar@university.edu',
});

store.add(annotation);

4.3 Annotation Layer Configuration#

Custom layers can be created to organize annotations beyond the seven defaults. Each layer has a unique identifier, display name, color, and visibility default.

typescript
import { AnnotationLayerConfig } from '../standoff-annotations.js';

const prosodyLayer: AnnotationLayerConfig = {
  layerId: 'prosody',
  displayName: 'Meter and Prosody',
  description:
    'Annotations related to poetic meter, rhythm, and prosodic features.',
  color: '#8B5CF6', // Purple
  defaultVisible: false, // Hidden by default; scholars toggle it on when needed
  applicableTypes: [
    'metrical-analysis',
    'strophic-structure',
    'prosodic-feature',
  ],
};

4.4 Annotation Storage Contracts#

Annotations must be serializable to JSON for API transport and database storage. The AnnotationStore provides an in-memory store with these contracts:

typescript
interface AnnotationStore {
  /** Add an annotation, returning the stored version with generated ID */
  add(annotation: CreateAnnotationInput): StoredAnnotation;

  /** Retrieve an annotation by ID */
  get(id: string): StoredAnnotation | undefined;

  /** Update an annotation's body or metadata */
  update(id: string, patch: AnnotationPatch): StoredAnnotation;

  /** Delete an annotation by ID */
  delete(id: string): boolean;

  /** Query annotations by target (passage reference) */
  queryByTarget(
    source: string,
    range?: OffsetRange
  ): readonly StoredAnnotation[];

  /** Query annotations by type */
  queryByType(typeId: string): readonly StoredAnnotation[];

  /** Query annotations by layer */
  queryByLayer(layerId: string): readonly StoredAnnotation[];

  /** Query annotations by creator */
  queryByCreator(creatorId: string): readonly StoredAnnotation[];

  /** Export all annotations as a W3C Web Annotation collection */
  exportAsWADM(): WADMAnnotationCollection;
}

All operations are immutable. The add method returns a new object; the original input is never mutated.


5. Contributing Concept Mappings#

5.1 Concept Mapping Data Format#

Cross-tradition concept mappings live in @nisaba/comparative and follow a structured format. Each mapping connects two or more concepts from different traditions and documents the nature and evidence of their relationship.

typescript
// From libs/nisaba/comparative/src/concept-equivalence.ts

export interface ConceptMapping {
  /** Unique identifier for this mapping */
  readonly id: string;

  /** The central concept being mapped */
  readonly centralConcept: ConceptDefinition;

  /** Related concepts from other traditions */
  readonly equivalents: readonly ConceptEquivalent[];

  /** Classification of the overall mapping */
  readonly similarityType: SimilarityType;

  /** Evidence grade for the strongest link in the mapping */
  readonly evidenceGrade: EvidenceGrade;

  /** Level of scholarly consensus */
  readonly consensusLevel: ConsensusLevel;

  /** Primary sources cited as evidence */
  readonly primarySources: readonly SourceCitation[];

  /** Secondary scholarly literature */
  readonly scholarlyReferences: readonly BibliographicReference[];

  /** The scholar who contributed this mapping */
  readonly contributor: ContributorInfo;

  /** Review status in the editorial pipeline */
  readonly reviewStatus: ReviewStatus;
}

export interface ConceptDefinition {
  readonly name: string;
  readonly originalScript: string;
  readonly transliteration: string;
  readonly tradition: Tradition;
  readonly definition: string;
  readonly keyTexts: readonly string[]; // Canonical URIs
}

export interface ConceptEquivalent {
  readonly concept: ConceptDefinition;
  readonly similarityType: SimilarityType;
  readonly similarityScore: number; // 0.0 - 1.0
  readonly evidenceGrade: EvidenceGrade;
  readonly justification: string;
  readonly primarySources: readonly SourceCitation[];
}

5.2 Evidence Requirements#

Every concept mapping must meet the following evidence requirements before it can be accepted:

Requirement Minimum
Primary source citations At least 2 per tradition involved
Scholarly references At least 1 peer-reviewed source supporting the mapping
Justification text 200+ words explaining the basis for the claimed parallel
Chronological plausibility Must address dating (earlier text cannot borrow from later)
Counter-evidence Must acknowledge major scholarly objections if they exist

5.3 Quality Standards#

Concept mappings undergo editorial review. Quality standards include:

  1. Specificity: Mappings must be specific enough to be falsifiable. "Both traditions have a concept of God" is too broad. "The Zoroastrian concept of Asha (ṛta, cosmic order) parallels the Vedic concept of Rta as both derive from Proto-Indo-Iranian religious vocabulary" is appropriately specific.

  2. Evidence grading: Use the EvidenceGrade enum honestly:

    • DOCUMENTED: Reserved for cases with explicit historical attestation of influence (e.g., a Greek philosopher citing an Egyptian source).
    • STRONG: Strong textual, linguistic, or archaeological evidence from multiple independent scholars.
    • PROBABLE: Majority scholarly view with good circumstantial evidence.
    • POSSIBLE: Proposed by credible scholars but debated.
    • SPECULATIVE: Novel proposals awaiting peer review.
  3. Similarity type accuracy: Do not confuse genetic (historical) influence with typological (independent) parallels. These have fundamentally different scholarly implications.

  4. Neutrality: Mappings must not privilege any tradition or suggest that one tradition's version is "more original" or "superior" unless there is clear chronological evidence of priority.

5.4 Review Process#

  1. Submission: Create a mapping using the ConceptEquivalenceRegistry API or submit through the Nisaba web interface.
  2. Automated checks: The system validates required fields, checks for duplicate mappings, and verifies that cited references exist in the bibliography.
  3. Peer review: At least one domain expert (tagged by tradition) reviews the mapping.
  4. Editorial decision: An editor approves, requests revisions, or rejects the mapping.
  5. Publication: Approved mappings become visible to all users and appear in concept map visualizations.

5.5 Example: Contributing a Cross-Tradition Concept Mapping#

Here is a complete example of contributing a new concept mapping programmatically:

typescript
import {
  ConceptEquivalenceRegistry,
  Tradition,
  SimilarityType,
  EvidenceGrade,
  ConsensusLevel,
} from '@nisaba/comparative';

const registry = new ConceptEquivalenceRegistry();

const mapping = registry.createMapping({
  centralConcept: {
    name: 'Kenosis',
    originalScript: 'κένωσις',
    transliteration: 'kenosis',
    tradition: Tradition.CHRISTIANITY,
    definition:
      'The self-emptying of the divine, drawn from Philippians 2:7 where Christ ' +
      '"emptied himself" (ἑαυτὸν ἐκένωσεν). In mystical theology, the voluntary ' +
      'relinquishing of divine prerogatives or self-will.',
    keyTexts: ['nisaba://bible/phil/2:5-11', 'nisaba://bible/john/17:5'],
  },
  equivalents: [
    {
      concept: {
        name: 'Fana',
        originalScript: 'فناء',
        transliteration: 'fanāʾ',
        tradition: Tradition.SUFISM,
        definition:
          'Annihilation of the self (nafs) in the divine presence. The mystic ceases ' +
          'to be aware of individual selfhood and exists only in and through God.',
        keyTexts: ['nisaba://quran/2:156', 'nisaba://quran/55:26-27'],
      },
      similarityType: SimilarityType.TYPOLOGICAL,
      similarityScore: 0.72,
      evidenceGrade: EvidenceGrade.PROBABLE,
      justification:
        'Both kenosis and fana describe the voluntary dissolution of the self-will ' +
        'or ego in the divine. However, they arise from independent theological ' +
        'traditions: kenosis from Pauline Christology and fana from Sufi mystical ' +
        'practice influenced by Neoplatonism. The parallel is typological rather ' +
        'than genetic, as the earliest Sufi formulations of fana (al-Junayd, ' +
        'ninth century) developed independently of detailed knowledge of Pauline ' +
        'theology, though later medieval exchanges between Christian and Muslim ' +
        'mystics may have created indirect cross-pollination.',
      primarySources: [
        {
          text: 'nisaba://bible/phil/2:5-11',
          tradition: Tradition.CHRISTIANITY,
        },
        { text: 'nisaba://quran/55:26-27', tradition: Tradition.SUFISM },
      ],
    },
    {
      concept: {
        name: 'Bittul HaYesh',
        originalScript: 'ביטול היש',
        transliteration: 'bittul ha-yesh',
        tradition: Tradition.JUDAISM,
        definition:
          'Nullification of the existent self. In Hasidic and Kabbalistic thought, ' +
          'the dissolution of the sense of independent selfhood to become a vessel ' +
          'for divine presence.',
        keyTexts: ['nisaba://zohar/1/18b'],
      },
      similarityType: SimilarityType.GENETIC,
      similarityScore: 0.65,
      evidenceGrade: EvidenceGrade.STRONG,
      justification:
        'Bittul ha-yesh shares a genetic relationship with kenosis through their ' +
        'common roots in Hellenistic Jewish mysticism. The Pauline concept of ' +
        'self-emptying draws on Jewish Wisdom tradition, while Kabbalistic bittul ' +
        'develops through medieval Jewish Neoplatonism. Both are mediated by the ' +
        'broader Hellenistic philosophical vocabulary of self-transcendence.',
      primarySources: [
        { text: 'nisaba://zohar/1/18b', tradition: Tradition.JUDAISM },
      ],
    },
  ],
  similarityType: SimilarityType.TYPOLOGICAL,
  evidenceGrade: EvidenceGrade.PROBABLE,
  consensusLevel: ConsensusLevel.MAJORITY_VIEW,
  primarySources: [
    { text: 'nisaba://bible/phil/2:5-11', tradition: Tradition.CHRISTIANITY },
    { text: 'nisaba://quran/55:26-27', tradition: Tradition.SUFISM },
    { text: 'nisaba://zohar/1/18b', tradition: Tradition.JUDAISM },
  ],
  scholarlyReferences: [
    {
      author: 'Sells, Michael',
      title: 'Mystical Languages of Unsaying',
      year: 1994,
      publisher: 'University of Chicago Press',
    },
    {
      author: 'McGinn, Bernard',
      title: 'The Foundations of Mysticism',
      year: 1991,
      publisher: 'Crossroad Publishing',
    },
  ],
  contributor: {
    name: 'Scholar Name',
    email: 'scholar@university.edu',
    affiliation: 'University Department',
    orcid: '0000-0000-0000-0000',
  },
});

// Submit for review
await registry.submitForReview(mapping.id);

6. Testing Guide#

6.1 Unit Test Patterns#

All Nisaba packages use Vitest as the test runner. Tests live in __tests__/ directories within each package's src/ directory.

Running tests:

bash
# Run tests for a specific package
npx vitest run libs/nisaba/languages/src/__tests__/

# Run tests for a specific file
npx vitest run libs/nisaba/languages/src/hebrew/__tests__/handler.test.ts

# Run tests in watch mode during development
npx vitest watch libs/nisaba/languages/src/

# Run all Nisaba tests
npx vitest run libs/nisaba/

Test file naming: <module-name>.test.ts or <module-name>.spec.ts.

Standard test structure:

typescript
import { describe, it, expect, beforeEach } from 'vitest';
import { ModuleUnderTest } from '../module-under-test.js';

describe('ModuleUnderTest', () => {
  let instance: ModuleUnderTest;

  beforeEach(() => {
    instance = new ModuleUnderTest();
  });

  describe('methodName', () => {
    it('describes what the method does in this scenario', () => {
      const result = instance.methodName(input);
      expect(result).toEqual(expectedOutput);
    });

    it('handles edge case correctly', () => {
      expect(instance.methodName('')).toEqual(emptyResult);
    });

    it('throws on invalid input', () => {
      expect(() => instance.methodName(null as any)).toThrow();
    });
  });
});

Testing immutable operations:

Since all Nisaba data structures are immutable, verify that operations return new objects without mutating the original:

typescript
it('returns a new object without mutating the original', () => {
  const original = createSomeEntity({ name: 'original' });
  const modified = updateEntity(original, { name: 'modified' });

  expect(modified.name).toBe('modified');
  expect(original.name).toBe('original');
  expect(modified).not.toBe(original);
});

6.2 Integration Test Patterns#

Integration tests verify that multiple modules work together correctly. They are placed in __integration__/ directories.

text
libs/nisaba/schemas/src/__integration__/
libs/nisaba/criticism/src/__integration__/

Integration tests may:

  • Test that schemas correctly validate data produced by domain modules.
  • Test that the ingestion pipeline correctly processes data from connectors.
  • Test that the collation engine produces correct apparatus entries.
typescript
// libs/nisaba/criticism/src/__integration__/collation-to-apparatus.test.ts

import { describe, it, expect } from 'vitest';
import { CollationEngine } from '../collation-engine.js';
import { ApparatusGenerator } from '../apparatus-generation.js';
import { ApparatusEntrySchema } from '@nisaba/schemas';

describe('Collation to Apparatus integration', () => {
  it('generates valid apparatus entries from collation results', () => {
    const engine = new CollationEngine();
    const collation = engine.collate({
      baseText: 'ἐν ἀρχῇ ἦν ὁ λόγος',
      witnesses: [
        { siglum: 'P66', text: 'ἐν ἀρχῇ ἦν ὁ λόγος' },
        { siglum: 'P75', text: 'ἐν ἀρχῇ ὁ λόγος ἦν' },
      ],
    });

    const generator = new ApparatusGenerator();
    const entries = generator.generate(collation, { format: 'negative' });

    // Verify entries validate against the schema
    for (const entry of entries) {
      const result = ApparatusEntrySchema.safeParse(entry);
      expect(result.success).toBe(true);
    }

    // Verify the transposition was detected
    expect(entries.length).toBeGreaterThan(0);
  });
});

6.3 Performance Benchmark Expectations#

Performance-sensitive operations have benchmark expectations documented in test files. These are not enforced in CI (to avoid flaky tests from hardware variation) but serve as guidelines:

Operation Expected Performance
Character classification < 1 microsecond per character
Cluster decomposition < 10 microseconds per cluster
Collation (2 witnesses, 1000 tokens) < 500 milliseconds
Collation (10 witnesses, 1000 tokens) < 5 seconds
Apparatus generation < 100 milliseconds for 100 entries
Concept mapping search < 50 milliseconds for 10,000 entries
TEI-XML parsing (1 MB file) < 2 seconds

6.4 Test Data Management#

Test data for ancient languages is stored alongside the test files in __tests__/fixtures/ directories:

text
libs/nisaba/languages/src/hebrew/__tests__/
├── fixtures/
│   ├── genesis-1-1.txt        # בְּרֵאשִׁ֖ית בָּרָ֣א אֱלֹהִ֑ים
│   ├── psalm-23.txt           # Full Psalm 23 in BHS
│   └── mixed-vocalization.txt # Text with mixed pointing systems
├── classifier.test.ts
├── clusters.test.ts
└── handler.test.ts

For large test corpora, use factory functions that generate synthetic data rather than committing large files:

typescript
function generateTestWitness(
  siglum: string,
  baseText: string,
  variantRate: number
): Witness {
  // Generate a witness with random variants at the specified rate
  const words = baseText.split(' ');
  const modified = words.map((word) => {
    if (Math.random() < variantRate) {
      return applyRandomVariant(word);
    }
    return word;
  });
  return { siglum, text: modified.join(' ') };
}

7. API Reference#

7.1 OpenAPI Spec Location#

The Nisaba REST API is documented with an OpenAPI 3.1 specification located at:

text
apps/nisaba-api/openapi/nisaba-api.yaml

The specification covers all endpoints grouped by domain:

  • /api/v1/corpora/* -- Corpus browsing and document retrieval
  • /api/v1/search/* -- Full-text, lemma, and morphological search
  • /api/v1/translations/* -- Translation comparison and alignment
  • /api/v1/collation/* -- Textual criticism and collation
  • /api/v1/apparatus/* -- Critical apparatus management
  • /api/v1/annotations/* -- Annotation CRUD and querying
  • /api/v1/editions/* -- Critical edition lifecycle
  • /api/v1/comparative/* -- Cross-tradition concept mapping
  • /api/v1/paleography/* -- Manuscript analysis
  • /api/v1/references/* -- Canonical reference resolution
  • /api/v1/workspace/* -- Research project management

7.2 Client SDK Usage#

The @nisaba/client package provides a fully typed client for the REST API. See Section 1.5 for the architecture overview. Key usage patterns:

Initialization:

typescript
import { NisabaClient } from '@nisaba/client';

const client = new NisabaClient({
  baseUrl: process.env.NISABA_API_URL ?? 'https://api.nisaba.example.com/v1',
  apiKey: process.env.NISABA_API_KEY,
  timeout: 30_000,
  retryConfig: {
    maxRetries: 3,
    baseDelayMs: 500,
    maxDelayMs: 30_000,
    jitter: 0.25,
  },
  cacheConfig: {
    enabled: true,
    ttlMs: 300_000,
    maxEntries: 500,
  },
});

Corpus operations:

typescript
// List available corpora
const corpora = await client.corpora.list({ tradition: 'jewish' });

// Get a specific corpus
const bhs = await client.corpora.get('bhs');

// Search within a corpus
const results = await client.search.execute({
  query: 'lemma:חסד',
  corpus: 'bhs',
  morphologyFilter: 'noun.*',
  page: 1,
  pageSize: 50,
});

Collation operations:

typescript
// Run automatic collation
const collation = await client.collation.run({
  baseTextId: 'na28:john:1',
  witnessIds: ['p66', 'p75', 'sinaiticus', 'vaticanus'],
  options: {
    normalization: 'greek-default',
    fuzzyThreshold: 80,
    detectTranspositions: true,
  },
});

// Generate apparatus
const apparatus = await client.apparatus.generate({
  collationId: collation.id,
  format: 'negative',
  witnessGrouping: { Byz: ['E', 'F', 'G', 'H'] },
});

Annotation operations:

typescript
// Create an annotation
const annotation = await client.annotations.create({
  target: {
    source: 'nisaba://bible/gen/1:1',
    selector: { type: 'TextPositionSelector', start: 0, end: 11 },
  },
  body: {
    type: 'TextualBody',
    value: 'Note on bereshit',
    format: 'text/plain',
  },
  motivation: 'commenting',
  layer: 'textual',
});

// Query annotations for a passage
const annotations = await client.annotations.query({
  source: 'nisaba://bible/gen/1:1',
  layers: ['textual', 'linguistic'],
  page: 1,
  pageSize: 100,
});

Error handling:

typescript
import { NisabaApiError, NisabaErrorCode } from '@nisaba/client';

try {
  const result = await client.corpora.get('nonexistent');
} catch (error) {
  if (error instanceof NisabaApiError) {
    switch (error.code) {
      case NisabaErrorCode.NOT_FOUND:
        console.error('Corpus not found:', error.message);
        break;
      case NisabaErrorCode.RATE_LIMITED:
        console.error('Rate limited. Retry after:', error.retryAfterMs, 'ms');
        break;
      case NisabaErrorCode.VALIDATION_ERROR:
        console.error('Validation errors:', error.validationErrors);
        break;
      default:
        console.error('API error:', error.toJSON());
    }
  }
}

7.3 WebSocket Real-Time API#

Nisaba provides a WebSocket API for real-time features:

  • Collaborative annotation: Real-time sync of annotation changes across multiple scholars working on the same text.
  • Collation progress: Live progress updates during long-running collation operations.
  • Search notifications: Push notifications when saved searches match new corpus additions.

Connection:

typescript
const ws = new WebSocket('wss://api.nisaba.example.com/v1/ws');

ws.onopen = () => {
  // Authenticate
  ws.send(
    JSON.stringify({
      type: 'auth',
      token: 'your-api-key',
    })
  );

  // Subscribe to annotation changes for a project
  ws.send(
    JSON.stringify({
      type: 'subscribe',
      channel: 'annotations',
      projectId: 'project-123',
    })
  );
};

ws.onmessage = (event) => {
  const message = JSON.parse(event.data);
  switch (message.type) {
    case 'annotation.created':
      handleNewAnnotation(message.payload);
      break;
    case 'annotation.updated':
      handleAnnotationUpdate(message.payload);
      break;
    case 'annotation.deleted':
      handleAnnotationDeletion(message.payload);
      break;
    case 'collation.progress':
      updateProgressBar(message.payload.percent);
      break;
  }
};

Message types:

Channel Event Types
annotations annotation.created, annotation.updated, annotation.deleted
collation collation.started, collation.progress, collation.completed, collation.failed
editions edition.updated, edition.published, edition.review_requested
search search.new_matches

7.4 React Hook Patterns#

The @nisaba/client React hooks (actually framework-agnostic subscription stores) follow consistent patterns:

Basic store usage with React:

tsx
import { useSyncExternalStore } from 'react';
import { createAnnotationLayerStore } from '@nisaba/client';

function AnnotationPanel({ projectId, passage }: Props) {
  const store = useMemo(
    () => createAnnotationLayerStore(client, { projectId, passage }),
    [projectId, passage]
  );

  const state = useSyncExternalStore(store.subscribe, store.getState);

  useEffect(() => {
    return () => store.destroy();
  }, [store]);

  if (state.loading) return <Spinner />;
  if (state.error) return <ErrorDisplay error={state.error} />;

  return (
    <div>
      {state.layers.map((layer) => (
        <LayerToggle
          key={layer.id}
          layer={layer}
          onToggle={() => store.actions.toggleLayer(layer.id)}
        />
      ))}
      {state.annotations.map((ann) => (
        <AnnotationCard key={ann.id} annotation={ann} />
      ))}
    </div>
  );
}

Available store factories:

Factory Purpose
createCorpusSearchStore Full-text and lemma search with pagination
createTranslationComparisonStore Side-by-side translation with alignment
createCollationStore Collation workflow state
createApparatusStore Apparatus viewing and editing
createAnnotationLayerStore Annotation layer management
createConceptMapStore Cross-tradition concept map state
createEditionStore Critical edition project state
createWitnessRegistryStore Manuscript witness management
createPersonalLibraryStore Reading lists, bookmarks, highlights
createWorkspaceLayoutStore Split-pane layout configuration
createSearchHistoryStore Saved searches and notifications
createMorphologyPopupStore Morphological parse popup state
createAnnotationRealtimeStore Real-time annotation sync via WebSocket
createCollationProgressStore Real-time collation progress via WebSocket
createSearchNotificationStore Saved search match notifications

8. CI/CD and Release#

8.1 Pipeline Overview#

The Nisaba CI/CD pipeline runs on every push and pull request. It ensures code quality, correctness, and compatibility across the monorepo.

Pipeline stages:

text
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  Lint    │───→│  Build   │───→│  Test    │───→│ Publish  │
└──────────┘    └──────────┘    └──────────┘    └──────────┘
  1. Lint: Runs ESLint with the project's TypeScript-strict configuration. All warnings are treated as errors.
  2. Build: Compiles all Nisaba packages with tsc --noEmit for type checking and tsup for bundling.
  3. Test: Runs the full Vitest test suite for all Nisaba packages.
  4. Publish: On tagged releases, publishes updated packages to the npm registry.

8.2 Quality Gates#

Every pull request must pass the following gates before merge:

Gate Requirement
Type checking tsc --noEmit passes with zero errors
Linting ESLint passes with zero errors and zero warnings
Unit tests All tests pass with 100% of required suites
Integration tests All integration tests pass
Coverage threshold Minimum 80% line coverage for changed files
Build Package builds successfully with tsup
Schema validation All Zod schemas validate their corresponding fixtures
No circular dependencies No circular imports detected

8.3 Running Quality Checks Locally#

Before pushing, run the full quality check locally:

bash
# Type check (bypass Nx project graph issues from worktrees)
cd libs/nisaba/<package>
npx tsc --noEmit

# Run tests
npx vitest run libs/nisaba/<package>/src/

# Lint
npx eslint libs/nisaba/<package>/src/ --ext .ts

# Build (if the package has a tsup config)
npx tsup

For a full check across all Nisaba packages:

bash
# Type check all packages
for pkg in libs/nisaba/*/; do
  echo "Checking $pkg..."
  (cd "$pkg" && npx tsc --noEmit)
done

# Test all packages
npx vitest run libs/nisaba/

8.4 Release Process#

Nisaba packages follow semantic versioning. The release process:

  1. Version bump: Update the version in the package's package.json. Follow semver:

    • Patch (0.0.x): Bug fixes, documentation updates.
    • Minor (0.x.0): New features, new language handlers, new annotation types. Backward-compatible.
    • Major (x.0.0): Breaking changes to public API, schema changes requiring migration.
  2. Changelog: Update the package's CHANGELOG.md with a summary of changes.

  3. Commit and tag: Commit with a conventional commit message and create a git tag:

    bash
    git tag @nisaba/languages@1.2.0
    git push origin main --tags
    
  4. Automated publish: The CI pipeline detects the tag and publishes the package to the npm registry.

8.5 Dependency Management#

Nisaba packages use the pnpm catalog in pnpm-workspace.yaml for shared dependency versions. When adding a new dependency:

  1. Add it to the catalog in pnpm-workspace.yaml if it will be used by multiple packages.
  2. Reference it with catalog: in the package's package.json.
  3. Run pnpm install to update the lockfile.
yaml
# pnpm-workspace.yaml (excerpt)
catalog:
  zod: ^3.23.0
  vitest: ^2.0.0
json
// libs/nisaba/schemas/package.json (excerpt)
{
  "dependencies": {
    "zod": "catalog:"
  }
}

Zero-dependency principle: Most Nisaba packages have zero external runtime dependencies. The exceptions are:

  • @nisaba/schemas: Depends on zod for runtime validation.
  • @nisaba/database: Depends on the database client library.

This principle ensures that Nisaba packages are lightweight, portable, and free from supply-chain risk.


Appendix A: Package Reference Table#

Package Purpose External Deps Key Exports
@nisaba/core Types, constants, utilities None WritingSystem, SCRIPT_METADATA, UNICODE_RANGES
@nisaba/schemas Zod validation schemas zod ManuscriptWitnessSchema, AnnotationSchema, etc.
@nisaba/languages Script handlers for ancient languages None BiblicalHebrewScriptHandler, AncientGreekScriptHandler, etc.
@nisaba/annotations W3C WADM standoff annotations None AnnotationStore, AnnotationTypeRegistry
@nisaba/canon Canonical text reference systems None resolveReference, mapVersification
@nisaba/corpora Corpus connectors and ingestion None TEIParser, ATFParser, IngestionPipeline
@nisaba/criticism Textual criticism and collation None CollationEngine, ApparatusGenerator
@nisaba/editions Critical edition management None EditionProject, ApparatusComposer
@nisaba/translations Translation comparison and alignment None AlignmentEngine, DivergenceDetector
@nisaba/comparative Cross-tradition analysis None ConceptEquivalenceRegistry, MotifTracker
@nisaba/philology Linguistic analysis None HapaxDetector, StyleAttribution
@nisaba/paleography Manuscript analysis None ScriptClassifier, HandIdentifier
@nisaba/geotemporal Geographic and temporal mapping None ProvenanceMapper, DiffusionTimeline
@nisaba/standards TEI and Linked Data compliance None TEIValidator, LinkedDataExporter
@nisaba/workspace Research environment and search None ResearchProject, UnifiedSearch
@nisaba/assistant AI-powered scholarly assistance None TranslationCommentary, VariantEvaluator
@nisaba/database Database client db driver NisabaDBClient
@nisaba/client API client and UI state stores None NisabaClient, createCorpusSearchStore

Appendix B: Coding Conventions#

Immutability#

All data structures use readonly fields. All operations return new objects. Never mutate function arguments.

typescript
// Correct
export interface Annotation {
  readonly id: string;
  readonly body: string;
  readonly target: readonly Selector[];
}

function updateBody(ann: Annotation, newBody: string): Annotation {
  return { ...ann, body: newBody };
}

// Incorrect - DO NOT do this
function updateBody(ann: Annotation, newBody: string): void {
  (ann as any).body = newBody; // FORBIDDEN
}

Zero External Dependencies#

Unless absolutely necessary (and approved), do not add external runtime dependencies. Use TypeScript's standard library and built-in browser/Node APIs.

Error Handling#

Use the NisabaError hierarchy from @nisaba/core. Never throw plain strings or generic Error objects.

typescript
import { NisabaValidationError, NisabaNotFoundError } from '@nisaba/core';

if (!input.siglum) {
  throw new NisabaValidationError('Witness siglum is required', {
    field: 'siglum',
  });
}

const witness = store.get(id);
if (!witness) {
  throw new NisabaNotFoundError(`Witness not found: ${id}`);
}

Module Documentation#

Every module must have a JSDoc header comment explaining:

  1. What the module does.
  2. Which task numbers it implements.
  3. The architectural approach (pure TypeScript, zero deps, immutable, etc.).
  4. The module's major sections/subsystems.
typescript
/**
 * Collation Engine for @nisaba/criticism
 *
 * Implements task 65.7.1: CollateX-compatible automatic collation using
 * Dekker's variant graph model. Supports token-based alignment with fuzzy
 * matching, transposition detection, and custom normalization.
 *
 * Pure TypeScript, zero external dependencies. All operations are immutable.
 *
 * @module @nisaba/criticism/collation-engine
 */

Naming Conventions#

Element Convention Example
Files kebab-case collation-engine.ts
Classes PascalCase CollationEngine
Interfaces PascalCase CharacterCluster
Enums PascalCase WritingSystem
Enum values SCREAMING_SNAKE SUMERIAN_CUNEIFORM
Functions camelCase decomposeClusters
Constants SCREAMING_SNAKE UNICODE_RANGES
Type aliases PascalCase AnnotationMotivation
Private fields camelCase this.listeners
Module version _MODULE_VERSION export const _MODULE_VERSION

Appendix C: Troubleshooting#

Nx Project Graph Conflicts from Worktrees#

If Nx fails with duplicate project errors due to .claude/worktrees/, do NOT delete the worktrees. Instead, bypass Nx:

bash
# Type check directly
cd libs/nisaba/<package>
npx tsc --noEmit

# Run tests directly
npx vitest run libs/nisaba/<package>/src/

# Build directly (if tsup config exists)
npx tsup

Unicode Rendering Issues#

If ancient scripts render as boxes or question marks in test output:

  1. Ensure your terminal supports Unicode (UTF-8). Most modern terminals do.
  2. For cuneiform and Egyptian hieroglyphs (Supplementary Multilingual Plane), ensure your terminal font includes SMP characters. Noto fonts provide comprehensive coverage.
  3. In test assertions, use Unicode escape sequences for clarity:
    typescript
    expect(handler.classifyCharacter('\u{10A60}')).not.toBeNull();
    

Circular Dependency Detection#

If you encounter circular imports, check the dependency layer rules (Section 1.2). A package in Layer 2 must never import from Layer 3 or Layer 4. Use the madge tool to visualize dependencies:

bash
npx madge --circular libs/nisaba/<package>/src/index.ts

Test Timeouts#

Some operations (collation of large witness sets, TEI parsing of large files) may exceed Vitest's default timeout. Increase the timeout for specific tests:

typescript
it('collates a large witness set', { timeout: 30_000 }, async () => {
  // Test body
});

Nisaba Developer Guide -- Contributing to the world's most comprehensive ancient text analysis platform.