glossarist 0.4.49 → 0.4.51

package/src/gcr-writer.ts

@@ -1,97 +0,0 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
-import JSZip from 'jszip';
-import { conceptSerializer } from './concept-serializer.js';
-import { InvalidInputError } from './errors.js';
-import { compiledPath, isKnownFormat } from './compiled-format.js';
-import { GcrMetadata } from './models/gcr-metadata.js';
-import { GcrStatistics } from './models/gcr-statistics.js';
-
-export class GcrWriter {
-  static async createBuffer(options) {
-    if (!options || !options.concepts || typeof options.concepts[Symbol.iterator] !== 'function') {
-      throw new InvalidInputError(
-        'GcrWriter requires { concepts: Concept[] }',
-        'object with concepts array',
-      );
-    }
-
-    const zip = new JSZip();
-
-    if (options.metadata) {
-      const meta = GcrWriter._normalizeMetadata(options.metadata, options.concepts);
-      zip.file('metadata.yaml', conceptSerializer.toRegisterYaml(meta));
-    }
-    if (options.register) {
-      zip.file('register.yaml', conceptSerializer.toRegisterYaml(options.register));
-    }
-
-    for (const concept of options.concepts) {
-      const y = options.format === 'canonical'
-        ? conceptSerializer.toCanonicalYaml(concept)
-        : options.format === 'managed'
-          ? conceptSerializer.toManagedYaml(concept, options.uuidFn)
-          : conceptSerializer.toYaml(concept, options.uuidFn);
-      zip.file(`concepts/${concept.id}.yaml`, y);
-    }
-
-    if (options.compiledFormats) {
-      GcrWriter._writeCompiledFormats(zip, options.compiledFormats);
-    }
-
-    if (options.bibliography) {
-      const bib = options.bibliography;
-      const yamlStr = bib.toYAML ? bib.toYAML() : String(bib);
-      zip.file('bibliography.yaml', yamlStr);
-    }
-
-    if (options.images) {
-      GcrWriter._writeImages(zip, options.images);
-    }
-
-    return zip.generateAsync({ type: 'uint8array' });
-  }
-
-  static _normalizeMetadata(metadata, concepts) {
-    if (metadata instanceof GcrMetadata) {
-      const meta = metadata.clone();
-      if (!meta.statistics && concepts.length > 0) {
-        meta.statistics = GcrStatistics.fromConcepts(concepts);
-      }
-      if (!meta.conceptCount) meta.conceptCount = concepts.length;
-      return meta.toJSON();
-    }
-
-    const data = { ...metadata };
-    if (!data.statistics && concepts.length > 0) {
-      data.statistics = GcrStatistics.fromConcepts(concepts).toJSON();
-    }
-    if (!data.concept_count && concepts.length > 0) {
-      data.concept_count = concepts.length;
-    }
-    return data;
-  }
-
-  static _writeCompiledFormats(zip, compiledFormats) {
-    for (const [format, entries] of Object.entries(compiledFormats)) {
-      if (!isKnownFormat(format)) {
-        throw new RangeError(`Unknown compiled format: ${format}`);
-      }
-      const map = entries instanceof Map ? entries : new Map(Object.entries(entries));
-      for (const [id, content] of map) {
-        zip.file(compiledPath(format, id), content);
-      }
-    }
-  }
-
-  static _writeImages(zip, images) {
-    const map = images instanceof Map ? images : new Map(Object.entries(images));
-    for (const [path, content] of map) {
-      const fullPath = path.startsWith('images/') ? path : `images/${path}`;
-      zip.file(fullPath, content);
-    }
-  }
-}
-
-export async function createGcr(concepts, metadata) {
-  return GcrWriter.createBuffer({ concepts, metadata });
-}

package/src/index.d.ts

@@ -1,124 +0,0 @@
-// Models
-export {
-  GlossaristModel,
-  RegistrableModel,
-  Concept, LocalizedConcept,
-  Designation, Expression, Abbreviation, Symbol, LetterSymbol, GraphicalSymbol,
-  Citation, ConceptRef, ConceptSource, RelatedConcept,
-  DesignationRelationship, ConceptReference, ConceptDate,
-  DetailedDefinition, NonVerbRep, NON_VERBAL_TYPES,
-  NonVerbalEntity, SharedNonVerbalEntity,
-  Figure, FigureImage, Table, Formula,
-  NonVerbalReference, FigureReference, TableReference, FormulaReference,
-  BibliographyEntry, BibliographyData,
-  GcrMetadata, GcrStatistics,
-  RELATIONSHIP_TYPES, DESIGNATION_RELATIONSHIP_TYPES, DATE_TYPES,
-  PartitiveHyperedge, PARTITIVE_ENUMERATION, PARTITIVE_ENUMERATION_VALUES,
-  PLURALITY_MARKER, PLURALITY_MARKER_VALUES,
-} from './models/index';
-
-// Concept diff
-export {
-  diffConcepts,
-  diffLocalizedConcepts,
-  diffText,
-  diffList,
-  diffSet,
-  ConceptDiff,
-  ConceptLevelDiff,
-  LocalizedConceptDiff,
-  MetadataDiff,
-  DiffStats,
-  ListDiff,
-  TextDiff,
-  TextHunk,
-  Change,
-  Added,
-  Removed,
-  Changed,
-} from './diff/index';
-
-// GCR reader
-export { loadGcr, GcrPackage, parseConceptYaml, naturalSort } from './gcr-reader';
-
-// GCR writer
-export { createGcr, GcrWriter } from './gcr-writer';
-
-// Concept reader
-export { readConcepts, readConcept, listConceptIds, readRegister } from './concept-reader';
-
-// Concept writer
-export { writeConcept, writeConcepts } from './concept-writer';
-
-// Collections
-export { ConceptCollection } from './concept-collection';
-export { ManagedConceptCollection } from './managed-concept-collection';
-
-// Validators
-export {
-  validateConcept, validateRegister, validateGcrPackage,
-  createConceptValidator,
-  ValidationError, ValidationRule, ValidationResult,
-  RegisterValidator, GcrValidator,
-  NonVerbalRefIntegrityRule, OrphanedImagesRule,
-} from './validators/index';
-export { AssetIndex } from './validators/asset-index';
-
-// UUID
-export { conceptUuid, localizedConceptUuid, uuidV5 } from './uuid';
-
-// Reference resolution
-export {
-  ReferenceResolver, Reference, referenceResolver,
-  resolveBibliographyRecord, findNonVerbalEntity,
-} from './reference-resolver';
-
-export type MentionParseResult = {
-  kind: 'cite-ref' | 'urn-ref' | 'fig-ref' | 'table-ref' | 'formula-ref'
-      | 'numeric' | 'designation' | 'unresolved';
-  key?: string;
-  uri?: string;
-  label?: string | null;
-  id?: string;
-  raw: string;
-};
-
-export function parseMention(raw: string): MentionParseResult;
-
-export function fetchLocalizedString(
-  hash: Record<string, string> | null,
-  lang: string,
-  fallback?: string,
-): string | null;
-export function localizedStringIsEmpty(hash: Record<string, string> | null): boolean;
-export function localizedStringIsPresent(hash: Record<string, string> | null): boolean;
-
-// V1 support
-export { V1Reader, migrateV1ToV2 } from './v1-reader';
-
-// Errors
-export { GlossaristError, InvalidInputError, YamlParseError } from './errors';
-
-// Compiled format registry
-export const COMPILED_EXTENSIONS: ReadonlyMap<string, string>;
-export const COMPILED_FORMATS: readonly string[];
-export function isKnownFormat(format: string): boolean;
-export function compiledFilename(format: string, id: string): string;
-export function compiledPath(format: string, id: string): string;
-export function parseCompiledPath(zipPath: string): { format: string; id: string } | null;
-
-// Dataset asset registry
-export const DATASET_ASSETS: readonly { path: string; type: string }[];
-export const FILE_ASSETS: readonly { path: string; type: string }[];
-export const DIRECTORY_ASSETS: readonly { path: string; type: string }[];
-export function findFileAsset(path: string): { path: string; type: string } | undefined;
-export function findDirectoryAssetPath(zipPath: string): { path: string; type: string } | undefined;
-export function isDatasetAssetPath(zipPath: string): boolean;
-
-// Entity directory registry
-export const ENTITY_DIRECTORIES: ReadonlyMap<string, string>;
-export const ENTITY_TYPES: readonly string[];
-export function entityDir(type: string): string;
-export function entityPath(type: string, id: string): string;
-export function isKnownEntityType(type: string): boolean;
-export function parseEntityPath(zipPath: string): { type: string; id: string } | null;

package/src/managed-concept-collection.ts

@@ -1,95 +0,0 @@
-// @ts-nocheck — TEMPORARY during TS migration. TODO(Phase 2e): remove and type fully.
-import { ConceptCollection } from './concept-collection.js';
-import { readConcepts, readRegister } from './concept-reader.js';
-import { writeConcepts } from './concept-writer.js';
-import { loadGcr } from './gcr-reader.js';
-import { GcrWriter } from './gcr-writer.js';
-import { BibliographyData } from './models/bibliography-data.js';
-
-export class ManagedConceptCollection {
-  constructor() {
-    this._concepts = new ConceptCollection();
-    this._register = null;
-    this._bibliography = null;
-    this._images = null;
-  }
-
-  get concepts() { return this._concepts; }
-  get register() { return this._register; }
-  get bibliography() { return this._bibliography; }
-  get images() { return this._images; }
-
-  loadFromDirectory(dir) {
-    this._concepts = new ConceptCollection(readConcepts(dir));
-    this._register = readRegister(dir);
-    return this;
-  }
-
-  async loadFromGcr(input) {
-    const pkg = await loadGcr(input);
-    this._concepts = new ConceptCollection(await pkg.allConcepts());
-    this._register = await pkg.register();
-    this._bibliography = await pkg.bibliography();
-    this._images = await pkg.allImageFiles();
-    return this;
-  }
-
-  saveToDirectory(dir, options = {}) {
-    writeConcepts(dir, this._concepts, {
-      register: this._register ?? undefined,
-      format: options.format,
-    });
-  }
-
-  async saveToGcr(options = {}) {
-    return GcrWriter.createBuffer({
-      concepts: this._concepts,
-      metadata: options.metadata,
-      register: this._register,
-      format: options.format,
-      compiledFormats: options.compiledFormats,
-      bibliography: this._bibliography,
-      images: this._images,
-    });
-  }
-
-  add(concept) {
-    const existing = this._concepts.byId(concept.id);
-    if (existing) {
-      const idx = this._concepts.indexOf(existing);
-      this._concepts.set(idx, concept);
-    } else {
-      this._concepts.push(concept);
-    }
-    return this;
-  }
-
-  remove(id) {
-    const idx = this._concepts.findIndex(c => c.id === id);
-    if (idx >= 0) this._concepts.splice(idx, 1);
-    return this;
-  }
-
-  setRegister(data) {
-    this._register = data;
-    return this;
-  }
-
-  setBibliography(bib) {
-    if (bib instanceof BibliographyData) {
-      this._bibliography = bib;
-    } else if (typeof bib === 'string') {
-      this._bibliography = BibliographyData.fromYAML(bib);
-    } else if (bib == null) {
-      this._bibliography = null;
-    } else {
-      this._bibliography = new BibliographyData(bib);
-    }
-    return this;
-  }
-
-  setImages(images) {
-    this._images = images instanceof Map ? images : new Map(Object.entries(images));
-    return this;
-  }
-}

package/src/migration/hyperedge-migrator.ts

@@ -1,104 +0,0 @@
-// v1 → v2 PartitiveHyperedge migration.
-//
-// Pure function: takes a v1 PartitiveHyperedge hash, returns a v2
-// PartitiveHyperedge hash. Idempotent.
-
-export interface V1HyperedgeHash {
-  comprehensive?: { source?: string; id?: string; text?: string };
-  parts?: ReadonlyArray<{ source?: string; id?: string }>;
-  enumeration?: string;
-  content?: string | null;
-  markers?: ReadonlyArray<string>;
-}
-
-export interface V2HyperedgeHash {
-  comprehensive: { source?: string; id?: string };
-  partitives: ReadonlyArray<{
-    ref: { source?: string; id?: string };
-    presence: string;
-    count: string;
-  }>;
-  completeness: string;
-  migrationWarning?: string;
-}
-
-export function migrateHyperedgeToRelation(
-  v1Hash: V1HyperedgeHash | ReadonlyArray<V1HyperedgeHash> | null,
-): V2HyperedgeHash | ReadonlyArray<V2HyperedgeHash | null> | null {
-  if (v1Hash == null) return null;
-  if (Array.isArray(v1Hash)) {
-    return v1Hash.map(migrateHyperedgeToRelation) as ReadonlyArray<V2HyperedgeHash | null>;
-  }
-
-  const h = v1Hash as V1HyperedgeHash;
-  const out: Partial<V2HyperedgeHash> = {
-    comprehensive: { ...(h.comprehensive ?? {}) },
-  };
-
-  const parts = Array.isArray(h.parts) ? h.parts : [];
-  out.partitives = parts.map((ref) => ({
-    ref: { ...ref },
-    presence: 'required',
-    count: 'exactly_one',
-  }));
-
-  out.completeness = _migrateEnumeration(h.enumeration);
-
-  if (parts.length < 2) {
-    out.migrationWarning =
-      `v1 PartitiveHyperedge had ${parts.length} part(s); v2 requires ≥2. ` +
-      `Either add more partitives or convert to a binary has_part edge.`;
-  }
-
-  if (h.content != null) {
-    out.migrationWarning = (out.migrationWarning ?? '') +
-      ` v1 'content' field was dropped (v2 PartitiveHyperedge carries no prose; ` +
-      `move valuable text to the comprehensive concept's notes).`;
-  }
-
-  if (Array.isArray(h.markers) && h.markers.length > 0) {
-    out.migrationWarning = (out.migrationWarning ?? '') +
-      ` v1 'markers' field (${h.markers.join(', ')}) was dropped; ` +
-      `v2 uses per-member 'multiplicity' + 'is_delimiting'. Reviewer ` +
-      `should set these per partitive based on ISO 704:2022 notation.`;
-  }
-
-  return out as V2HyperedgeHash;
-}
-
-export function downgradeRelationToHyperedge(
-  v2Hash: Partial<V2HyperedgeHash> | ReadonlyArray<Partial<V2HyperedgeHash>> | null,
-): unknown {
-  if (v2Hash == null) return null;
-  if (Array.isArray(v2Hash)) {
-    return v2Hash.map(downgradeRelationToHyperedge);
-  }
-
-  const v2 = v2Hash as V2HyperedgeHash;
-  const out: {
-    comprehensive: { source?: string; id?: string };
-    parts: Array<{ source?: string; id?: string }>;
-    enumeration: string;
-  } = {
-    comprehensive: { ...(v2.comprehensive ?? {}) },
-    parts: [],
-    enumeration: '',
-  };
-
-  out.parts = (v2.partitives ?? []).map((m) => ({ ...(m.ref ?? {}) }));
-  out.enumeration = _downgradeCompleteness(v2.completeness);
-
-  return out;
-}
-
-function _migrateEnumeration(value: string | undefined): string {
-  if (value === 'open') return 'partial';
-  if (value === 'closed') return 'complete';
-  if (value == null) return 'complete';
-  return 'complete';
-}
-
-function _downgradeCompleteness(value: string | undefined): string {
-  if (value === 'partial') return 'open';
-  return 'closed';
-}

package/src/models/abstract-hyperedge.ts

@@ -1,164 +0,0 @@
-// AbstractHyperedge — shared base for directed 1→N hyperedges
-// (PartitiveHyperedge, GenericHyperedge, SequentialHyperedge, future
-// AssociativeHyperedge, etc.).
-//
-// Carries the common shape:
-//   - comprehensive: ConceptRef
-//   - members: 2+ MECE dimensioned concept refs (≥2 per ISO 704)
-//   - completeness: complete | partial
-//   - criterion: localized subdivision criterion (ISO 12620)
-//   - sources / notes / status: administrative metadata
-//
-// See docs/design/abstract-hyperedge.md (concept-model repo).
-
-import { GlossaristModel } from './base.js';
-import { ConceptRef } from './concept-ref.js';
-import type { ConceptRefJson } from './concept-ref.js';
-import { DEFAULT_COMPLETENESS, isValidCompleteness } from './completeness.js';
-import type { Completeness } from './completeness.js';
-import type { HyperedgeMember } from './hyperedge-member.js';
-import type { LocalizedString } from './generic-member.js';
-
-export interface AbstractHyperedgeJson {
-  comprehensive: ConceptRefJson;
-  members: ReadonlyArray<unknown>;
-  completeness: Completeness;
-  criterion?: LocalizedString;
-  sources?: ReadonlyArray<unknown>;
-  notes?: Record<string, unknown> | null;
-  status?: string | null;
-  /** PartitiveHyperedge wire alias (only present on PartitiveHyperedge JSON). */
-  partitives?: ReadonlyArray<unknown>;
-}
-
-export type CriterionInput = string | LocalizedString | null | undefined;
-
-export abstract class AbstractHyperedge extends GlossaristModel {
-  readonly comprehensive: ConceptRef;
-  readonly members: ReadonlyArray<HyperedgeMember>;
-  readonly completeness: Completeness;
-  readonly criterion: LocalizedString | null;
-  readonly sources: ReadonlyArray<unknown>;
-  readonly notes: Record<string, unknown> | null;
-  readonly status: string | null;
-
-  constructor(
-    data: AbstractHyperedgeJson = {
-      comprehensive: {},
-      members: [],
-      completeness: 'complete',
-    },
-  ) {
-    super();
-    this.comprehensive = _ensureComprehensive(data.comprehensive);
-    this.members = _ensureMembers(
-      data.members,
-      this.constructor.name,
-    ) as ReadonlyArray<HyperedgeMember>;
-    this.completeness = _resolveCompleteness(data.completeness);
-    this.criterion = _normalizeCriterion(data.criterion);
-    this.sources = Array.isArray(data.sources) ? [...data.sources] : [];
-    this.notes = (data.notes as Record<string, unknown> | null) ?? null;
-    this.status = data.status ?? null;
-
-    _assertNoSelfLoop(this.comprehensive, this.members);
-  }
-
-  get isComplete(): boolean { return this.completeness === 'complete'; }
-  get isPartial(): boolean { return this.completeness === 'partial'; }
-  get isCoordinate(): boolean { return this.members.length >= 2; }
-
-  hasCriterion(): boolean { return this.criterion != null; }
-
-  override identity(): string {
-    const Ctor = this.constructor as unknown as { identityOf: (v: unknown) => string };
-    return Ctor.identityOf(this);
-  }
-
-  override toJSON(): AbstractHyperedgeJson {
-    const obj: AbstractHyperedgeJson = {
-      comprehensive: this.comprehensive.toJSON(),
-      members: this.members.map((m) => m.toJSON()),
-      completeness: this.completeness,
-    };
-    if (this.criterion != null) obj.criterion = { ...this.criterion };
-    if (this.sources.length > 0) obj.sources = [...this.sources];
-    if (this.notes != null) obj.notes = { ...this.notes };
-    if (this.status != null) obj.status = this.status;
-    return obj;
-  }
-}
-
-function _ensureComprehensive(
-  value: ConceptRefJson | ConceptRef | null | undefined,
-): ConceptRef {
-  const ref = value instanceof ConceptRef ? value : new ConceptRef(value ?? {});
-  if (!ref.source && !ref.id && !ref.text) {
-    throw new Error(
-      'AbstractHyperedge.comprehensive must be a non-empty ConceptReference ' +
-      '(source, id, or text required)',
-    );
-  }
-  return ref;
-}
-
-function _ensureMembers(
-  values: ReadonlyArray<unknown> | null | undefined,
-  typeName: string,
-): ReadonlyArray<unknown> {
-  if (!Array.isArray(values)) {
-    throw new Error(
-      `${typeName}.members must be an array (got ${values === null ? 'null' : typeof values})`,
-    );
-  }
-  if (values.length < 2) {
-    throw new Error(
-      `${typeName} requires ≥2 partitives (ISO 704); got ${values.length}`,
-    );
-  }
-  return values;
-}
-
-function _resolveCompleteness(
-  value: Completeness | null | undefined,
-): Completeness {
-  const c = value ?? DEFAULT_COMPLETENESS;
-  if (!isValidCompleteness(c)) {
-    throw new Error(
-      `completeness has invalid value ${JSON.stringify(value)}`,
-    );
-  }
-  return c;
-}
-
-function _normalizeCriterion(value: CriterionInput): LocalizedString | null {
-  if (value == null) return null;
-  if (typeof value === 'string') {
-    return value.length > 0 ? { default: value } : null;
-  }
-  if (typeof value === 'object') {
-    const entries = Object.entries(value).filter(
-      ([, v]) => typeof v === 'string',
-    );
-    return entries.length > 0
-      ? (Object.fromEntries(entries) as LocalizedString)
-      : null;
-  }
-  return null;
-}
-
-function _assertNoSelfLoop(
-  comprehensive: ConceptRef,
-  members: ReadonlyArray<{ ref?: { source?: string | null; id?: string | null } }>,
-): void {
-  const cKey = `${comprehensive.source ?? ''}:${comprehensive.id ?? ''}`;
-  for (const m of members) {
-    const ref = m.ref;
-    const pKey = `${ref?.source ?? ''}:${ref?.id ?? ''}`;
-    if (pKey === cKey && (ref?.source || ref?.id)) {
-      throw new Error(
-        'Relation.members cannot include the comprehensive (no self-loops)',
-      );
-    }
-  }
-}

package/src/models/base.ts

@@ -1,110 +0,0 @@
-/**
- * GlossaristModel — abstract base for every domain model.
- *
- * Subclasses implement `toJSON()` (wire shape) and `identity()`
- * (stable string key for diff/dedupe). `equals()` and `clone()`
- * default to comparing via JSON serialization; subclasses may
- * override for performance.
- */
-
-/**
- * Any value that can be the output of `JSON.stringify`. Used as the
- * return type of {@link GlossaristModel.toJSON} so subclasses with
- * non-object JSON output (e.g. `NonVerbalReference.toJSON()` returns
- * a bare string for the no-display case) can override without
- * breaking variance. The object case accepts any object to avoid
- * forcing `<Model>Json` interfaces to declare explicit string index
- * signatures (TS interfaces don't have implicit index signatures).
- */
-export type JsonValue =
-  | string
-  | number
-  | boolean
-  | null
-  | JsonValue[]
-  | object;
-
-export abstract class GlossaristModel {
-  /** Wire-shape serialization. Subclasses MUST override. */
-  toJSON(): JsonValue {
-    throw new Error(`${this.constructor.name} must implement toJSON()`);
-  }
-
-  /** Stable identity string for diff, dedupe, registry keys. */
-  identity(): string {
-    throw new Error(`${this.constructor.name} must implement identity()`);
-  }
-
-  /** Default: structural equality via JSON. Override for semantic equality. */
-  equals(other: this): boolean {
-    if (!(other instanceof this.constructor)) return false;
-    return JSON.stringify(this.toJSON()) === JSON.stringify(other.toJSON());
-  }
-
-  /** Deep clone via JSON round-trip. Subclasses with non-JSON-safe
-   *  fields must override. */
-  clone(): this {
-    const Ctor = this.constructor as new (data: unknown) => this;
-    return new Ctor(JSON.parse(JSON.stringify(this.toJSON())));
-  }
-
-  /**
-   * Subclasses MUST override. Declared on the abstract base so callers
-   * who only have `typeof GlossaristModel` get a typed call site
-   * (rather than the static disappearing under `abstract`).
-   */
-  static fromJSON(_data: unknown): GlossaristModel {
-    throw new Error(`${this.name} must implement fromJSON()`);
-  }
-
-  /**
-   * Lazily wrap a raw array (plain hashes) into model instances.
-   * Used by Concept's lazy `figures`/`tables`/`formulas` getters so
-   * the wrap cost is only paid on first access.
-   *
-   * `cacheKey` and `rawKey` are private field names on `this`. The
-   * bracket access here is the only legitimate reflective pattern in
-   * the codebase (lazy field init). It is bracket-typed through a
-   * local alias rather than the public surface.
-   *
-   * Underscore-prefixed (not `protected`) so JS subclasses during the
-   * TS migration transition can call it without TS4094 on anonymous
-   * class expressions. Once all subclasses are .ts this can move to
-   * `protected`.
-   */
-  _lazy<TItem>(
-    cacheKey: string,
-    rawKey: string,
-    wrapFn: (raw: unknown) => TItem,
-  ): TItem[] {
-    const cache = this as unknown as Record<string, TItem[] | null | undefined>;
-    const raw = this as unknown as Record<string, unknown[] | undefined>;
-    if (cache[cacheKey] === null || cache[cacheKey] === undefined) {
-      const rawArr = raw[rawKey] ?? [];
-      cache[cacheKey] = rawArr.map((r) => wrapFn(r));
-    }
-    return cache[cacheKey] ?? [];
-  }
-
-  /**
-   * Helper for `toJSON()`: serialize a lazy-or-raw array under
-   * `jsonKey` only when it has items. Model instances go through
-   * `toJSON()`; primitives pass through.
-   */
-  _serialize(
-    obj: Record<string, unknown>,
-    jsonKey: string,
-    cacheKey: string,
-    rawKey: string,
-  ): void {
-    const self = this as unknown as Record<string, unknown[] | null | undefined>;
-    const cached = self[cacheKey];
-    const raw = self[rawKey];
-    const items = cached ?? (Array.isArray(raw) && raw.length > 0 ? raw : []);
-    if (items.length > 0) {
-      obj[jsonKey] = items.map((i) =>
-        i instanceof GlossaristModel ? i.toJSON() : i,
-      );
-    }
-  }
-}