# Nisaba Developer Guide

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](#1-architecture-overview)
2. [Adding New Language Support](#2-adding-new-language-support)
3. [Creating Corpus Connectors](#3-creating-corpus-connectors)
4. [Extending the Annotation Type System](#4-extending-the-annotation-type-system)
5. [Contributing Concept Mappings](#5-contributing-concept-mappings)
6. [Testing Guide](#6-testing-guide)
7. [API Reference](#7-api-reference)
8. [CI/CD and Release](#8-cicd-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.

```
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.

```
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/`

```
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:

```
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:

```
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:

```
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/`:

```
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.

```
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:

```
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:

```
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:**

```
┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐
│  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._
