glossarist 0.4.34 → 0.4.36

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.4.34",
+  "version": "0.4.36",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",
@@ -65,14 +65,16 @@
   },
   "scripts": {
     "lint": "eslint src/ test/",
+    "typecheck": "tsc --noEmit",
+    "build": "tsc",
     "sync:model": "node scripts/sync-concept-model.mjs",
     "gen:predicates": "node scripts/gen-predicates.mjs",
     "prebuild": "npm run gen:predicates",
     "pretest": "node test/fixtures/build-fixtures.js",
-    "test": "find test -name '*.test.js' | sort | xargs node --test",
-    "test:verbose": "find test -name '*.test.js' | sort | xargs node --test --test-reporter spec",
-    "test:coverage": "find test -name '*.test.js' | sort | xargs node --test --experimental-test-coverage",
-    "prepublishOnly": "npm test"
+    "test": "find test \\( -name '*.test.js' -o -name '*.test.ts' \\) | sort | xargs node --import tsx --test",
+    "test:verbose": "find test \\( -name '*.test.js' -o -name '*.test.ts' \\) | sort | xargs node --import tsx --test --test-reporter spec",
+    "test:coverage": "find test \\( -name '*.test.js' -o -name '*.test.ts' \\) | sort | xargs node --import tsx --test --experimental-test-coverage",
+    "prepublishOnly": "npm run typecheck && npm test"
   },
   "keywords": [
     "glossarist",
@@ -108,7 +110,14 @@
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
+    "@rdfjs/types": "^2.0.1",
+    "@types/node": "^26.1.2",
+    "@typescript-eslint/eslint-plugin": "^8.65.0",
+    "@typescript-eslint/parser": "^8.65.0",
     "eslint": "^10.3.0",
-    "globals": "^17.6.0"
+    "globals": "^17.6.0",
+    "tsx": "^4.23.1",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.65.0"
   }
 }

package/src/models/base.ts

@@ -0,0 +1,93 @@
+/**
+ * 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.
+ */
+
+export abstract class GlossaristModel {
+  /** Wire-shape serialization. Subclasses MUST override. */
+  toJSON(): object {
+    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,
+      );
+    }
+  }
+}

package/src/models/{completeness.js → completeness.ts}

@@ -5,14 +5,11 @@
 // ISO 704 depicts this as the rake's backline: a backline ending with
 // a tooth is complete; a backline continuing without a tooth is
 // partial.
-//
-// Renamed from the v1 `PartitiveEnumeration` (closed|open) per
-// TODO.partitive-relation-v2 item 02. The semantic claim being
-// expressed is completeness of the decomposition, not "enumeration"
-// (which is a neutral-sounding word that doesn't convey the claim).
 
 import { makeEnum } from './enum.js';
 
+export type Completeness = 'complete' | 'partial';
+
 export const COMPLETENESS = makeEnum('COMPLETENESS', {
   COMPLETE: 'complete',
   PARTIAL: 'partial',
@@ -21,4 +18,4 @@ export const COMPLETENESS = makeEnum('COMPLETENESS', {
 export const COMPLETENESS_VALUES = COMPLETENESS.VALUES;
 export const isValidCompleteness = COMPLETENESS.isValid;
 
-export const DEFAULT_COMPLETENESS = COMPLETENESS.COMPLETE;
+export const DEFAULT_COMPLETENESS: Completeness = COMPLETENESS.COMPLETE;

package/src/models/concept-date.ts

@@ -0,0 +1,48 @@
+import { GlossaristModel } from './base.js';
+
+export type ConceptDateType = 'accepted' | 'amended' | 'retired' | string;
+
+export const DATE_TYPES: ReadonlyArray<string> = Object.freeze([
+  'accepted',
+  'amended',
+  'retired',
+]);
+
+export interface ConceptDateJson {
+  date?: string | null;
+  type?: ConceptDateType | null;
+}
+
+export class ConceptDate extends GlossaristModel {
+  readonly date: string | null;
+  readonly type: ConceptDateType | null;
+
+  constructor(data: ConceptDateJson = {}) {
+    super();
+    this.date = data.date ?? null;
+    this.type = data.type ?? null;
+  }
+
+  get parsedDate(): Date | null {
+    return this.date ? new Date(this.date) : null;
+  }
+
+  static identityOf(value: { type?: ConceptDateType | null } | null | undefined): string {
+    return value?.type ?? '';
+  }
+
+  override identity(): string {
+    return ConceptDate.identityOf(this);
+  }
+
+  override toJSON(): ConceptDateJson {
+    const obj: ConceptDateJson = {};
+    if (this.date != null) obj.date = this.date;
+    if (this.type != null) obj.type = this.type;
+    return obj;
+  }
+
+  static override fromJSON(data: ConceptDateJson): ConceptDate {
+    return new ConceptDate(data);
+  }
+}

package/src/models/concept-ref.ts

@@ -0,0 +1,64 @@
+import { GlossaristModel } from './base.js';
+
+/**
+ * Wire shape for ConceptRef. All three fields are optional on input
+ * (any one is enough to identify a concept; usually source+id pair).
+ * `text` is a free-form fallback for references that have no
+ * machine-readable source.
+ */
+export interface ConceptRefJson {
+  source?: string | null;
+  id?: string | null;
+  text?: string | null;
+}
+
+/**
+ * ConceptRef — a reference to a concept by (source, id) pair, or by
+ * free-form text when no machine-readable source exists.
+ *
+ * Identity: `${source ?? ''}|${id ?? ''}`. Two refs with the same
+ * (source, id) are equal regardless of `text`.
+ */
+export class ConceptRef extends GlossaristModel {
+  readonly source: string | null;
+  readonly id: string | null;
+  readonly text: string | null;
+
+  constructor(data: ConceptRefJson = {}) {
+    super();
+    this.source = data.source ?? null;
+    this.id = data.id ?? null;
+    this.text = data.text ?? null;
+  }
+
+  override toString(): string {
+    const parts: string[] = [];
+    if (this.source) parts.push(this.source);
+    if (this.id) parts.push(this.id);
+    const base = parts.join(' ');
+    if (this.text && base) return `${base} (${this.text})`;
+    if (this.text) return this.text;
+    return base;
+  }
+
+  override toJSON(): ConceptRefJson {
+    const obj: ConceptRefJson = {};
+    if (this.source != null) obj.source = this.source;
+    if (this.id != null) obj.id = this.id;
+    if (this.text != null) obj.text = this.text;
+    return obj;
+  }
+
+  override identity(): string {
+    return `${this.source ?? ''}|${this.id ?? ''}`;
+  }
+
+  static override fromJSON(data: ConceptRefJson): ConceptRef {
+    return new ConceptRef(data);
+  }
+
+  /** Convenience constructor for the common `(source, id)` form. */
+  static fromPair(source: string, id: string): ConceptRef {
+    return new ConceptRef({ source, id });
+  }
+}

package/src/models/concept-source.ts

@@ -0,0 +1,96 @@
+import { GlossaristModel } from './base.js';
+import { Citation } from './citation.js';
+
+/**
+ * Local Citation wire-shape alias. Until `citation.ts` lands (Phase
+ * 2b), Citation is untyped JS; this alias gives the cross-references
+ * a typed shape without forcing the conversion order. When
+ * `citation.ts` exports its own `CitationJson`, replace this with
+ * `import type { CitationJson } from './citation.js'`.
+ */
+export interface CitationJson {
+  ref?: { source?: string | null; id?: string | null; text?: string | null } | null;
+}
+
+export interface ConceptSourceJson {
+  id?: string | null;
+  status?: string | null;
+  type?: string | null;
+  origin?: CitationJson | Citation | null;
+  modification?: string | null;
+  sourcedFrom?: ReadonlyArray<CitationJson | Citation> | null;
+  sourced_from?: ReadonlyArray<CitationJson | Citation> | null;
+}
+
+export class ConceptSource extends GlossaristModel {
+  readonly id: string | null;
+  readonly status: string | null;
+  readonly type: string | null;
+  readonly origin: Citation | null;
+  readonly modification: string | null;
+  readonly sourcedFrom: ReadonlyArray<Citation>;
+
+  constructor(data: ConceptSourceJson = {}) {
+    super();
+    this.id = data.id ?? null;
+    this.status = data.status ?? null;
+    this.type = data.type ?? null;
+    this.origin = data.origin
+      ? data.origin instanceof Citation
+        ? data.origin
+        : new Citation(data.origin)
+      : null;
+    this.modification = data.modification ?? null;
+    const sourcedRaw = data.sourcedFrom ?? data.sourced_from ?? [];
+    this.sourcedFrom = sourcedRaw.map((c) =>
+      c instanceof Citation ? c : new Citation(c),
+    );
+  }
+
+  /**
+   * Backward-compat alias for callers using the snake_case JS field
+   * name. Prefer `.sourcedFrom` going forward; the wire name remains
+   * `sourced_from` (see toJSON).
+   */
+  get sourced_from(): ReadonlyArray<Citation> {
+    return this.sourcedFrom;
+  }
+
+  override toJSON(): ConceptSourceJson {
+    const obj: ConceptSourceJson = {};
+    if (this.id != null) obj.id = this.id;
+    if (this.status != null) obj.status = this.status;
+    if (this.type != null) obj.type = this.type;
+    if (this.origin != null) obj.origin = this.origin.toJSON();
+    if (this.modification != null) obj.modification = this.modification;
+    if (this.sourcedFrom.length > 0) {
+      obj.sourced_from = this.sourcedFrom.map((c) => c.toJSON());
+    }
+    return obj;
+  }
+
+  static identityOf(
+    value: {
+      type?: string | null;
+      origin?: CitationJson | Citation | { ref?: { source?: string; id?: string } | null } | null;
+    } | null | undefined,
+  ): string {
+    const v = value ?? {};
+    const origin = v.origin as CitationJson | Citation | { ref?: { source?: string; id?: string } | null } | null | undefined;
+    const ref =
+      origin instanceof Citation
+        ? origin.ref
+        : origin && typeof origin === 'object'
+          ? (origin as { ref?: { source?: string; id?: string } | null }).ref
+          : null;
+    return `${v.type ?? ''}|${ref?.source ?? ''}|${ref?.id ?? ''}`;
+  }
+
+  override identity(): string {
+    return ConceptSource.identityOf(this);
+  }
+
+  static override fromJSON(data: ConceptSourceJson): ConceptSource {
+    return new ConceptSource(data);
+  }
+}

package/src/models/concept-system-type.ts

@@ -0,0 +1,39 @@
+// ConceptSystemType — ISO 12620 A.7.1 concept system type enum.
+//
+// Permissible instances per ISO 12620:
+//   generic     — species are part of the extension of the genus
+//   partitive   — based on whole-part relations
+//   sequential  — based on spatial and temporal relations
+//   associative — based on thematic or pragmatic relations
+//   mixed       — two or more of the above (the realistic case)
+
+export type ConceptSystemType =
+  | 'generic'
+  | 'partitive'
+  | 'sequential'
+  | 'associative'
+  | 'mixed';
+
+export const CONCEPT_SYSTEM_TYPE: Readonly<
+  Record<'GENERIC' | 'PARTITIVE' | 'SEQUENTIAL' | 'ASSOCIATIVE' | 'MIXED', ConceptSystemType>
+> = Object.freeze({
+  GENERIC: 'generic',
+  PARTITIVE: 'partitive',
+  SEQUENTIAL: 'sequential',
+  ASSOCIATIVE: 'associative',
+  MIXED: 'mixed',
+});
+
+export const CONCEPT_SYSTEM_TYPE_VALUES: ReadonlyArray<ConceptSystemType> =
+  Object.freeze(Object.values(CONCEPT_SYSTEM_TYPE));
+
+export function isValidConceptSystemType(
+  value: unknown,
+): value is ConceptSystemType {
+  return (
+    typeof value === 'string' &&
+    (CONCEPT_SYSTEM_TYPE_VALUES as readonly string[]).includes(value)
+  );
+}
+
+export default CONCEPT_SYSTEM_TYPE;

package/src/models/concept-system.js

@@ -0,0 +1,117 @@
+// ConceptSystem — first-class concept system entity per ISO 12620 A.7.
+//
+// Promotes the previously-implicit concept system (domains + tags +
+// relation graph) to an explicit first-class entity. Per-file at
+// `concept-systems/<id>.yaml`.
+//
+// See docs/design/concept-systems.md (concept-model repo).
+
+import { GlossaristModel } from './base.js';
+import { ConceptRef } from './concept-ref.js';
+import {
+  CONCEPT_SYSTEM_TYPE,
+  CONCEPT_SYSTEM_TYPE_VALUES,
+  isValidConceptSystemType,
+} from './concept-system-type.js';
+
+export class ConceptSystem extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.id = _ensureNonEmptyString(data.id, 'id');
+    this.name = _ensureName(data.name);
+    this.type = _resolveType(data.type);
+    this.domain = data.domain ?? null;
+    this.purpose = data.purpose ?? null;
+    this.members = _ensureMembers(data.members);
+    this.hyperedges = Array.isArray(data.hyperedges) ? [...data.hyperedges] : [];
+    this.rootConcepts = Array.isArray(data.rootConcepts)
+      ? data.rootConcepts.map(c => c instanceof ConceptRef ? c : new ConceptRef(c))
+      : [];
+    this.sources = Array.isArray(data.sources) ? [...data.sources] : [];
+    this.status = data.status ?? null;
+  }
+
+  get isGeneric()     { return this.type === CONCEPT_SYSTEM_TYPE.GENERIC; }
+  get isPartitive()   { return this.type === CONCEPT_SYSTEM_TYPE.PARTITIVE; }
+  get isSequential()  { return this.type === CONCEPT_SYSTEM_TYPE.SEQUENTIAL; }
+  get isAssociative() { return this.type === CONCEPT_SYSTEM_TYPE.ASSOCIATIVE; }
+  get isMixed()       { return this.type === CONCEPT_SYSTEM_TYPE.MIXED; }
+
+  hasHyperedge(edgeId) {
+    return this.hyperedges.includes(edgeId);
+  }
+
+  hasMember(refOrUri) {
+    const uri = typeof refOrUri === 'string' ? refOrUri : _refUri(refOrUri);
+    return this.members.some(m => _refUri(m) === uri);
+  }
+
+  identity() {
+    return this.id;
+  }
+
+  toJSON() {
+    const obj = {
+      id: this.id,
+      name: { ...this.name },
+      type: this.type,
+      members: this.members.map(m => m.toJSON()),
+    };
+    if (this.domain != null) obj.domain = this.domain;
+    if (this.purpose != null) obj.purpose = { ...this.purpose };
+    if (this.hyperedges.length > 0) obj.hyperedges = [...this.hyperedges];
+    if (this.rootConcepts.length > 0) obj.rootConcepts = this.rootConcepts.map(c => c.toJSON());
+    if (this.sources.length > 0) obj.sources = [...this.sources];
+    if (this.status != null) obj.status = this.status;
+    return obj;
+  }
+
+  static fromJSON(data) {
+    return new ConceptSystem(data);
+  }
+}
+
+function _ensureNonEmptyString(value, fieldName) {
+  if (typeof value !== 'string' || value.length === 0) {
+    throw new Error(`ConceptSystem#${fieldName} must be a non-empty string`);
+  }
+  return value;
+}
+
+function _ensureName(value) {
+  if (value == null) return {};
+  if (typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error('ConceptSystem#name must be a localized object (e.g. { eng: "..." })');
+  }
+  return { ...value };
+}
+
+function _resolveType(value) {
+  if (value == null) {
+    throw new Error(
+      'ConceptSystem#type is required; one of ' +
+      CONCEPT_SYSTEM_TYPE_VALUES.join(', '),
+    );
+  }
+  if (!isValidConceptSystemType(value)) {
+    throw new Error(
+      `ConceptSystem#type ${JSON.stringify(value)} invalid; ` +
+      `must be one of: ${CONCEPT_SYSTEM_TYPE_VALUES.join(', ')}`,
+    );
+  }
+  return value;
+}
+
+function _ensureMembers(values) {
+  if (!Array.isArray(values) || values.length === 0) {
+    throw new Error('ConceptSystem#members must be a non-empty array');
+  }
+  return values.map(v => v instanceof ConceptRef ? v : new ConceptRef(v));
+}
+
+function _refUri(ref) {
+  const r = ref?.ref ?? ref ?? {};
+  return `${r.source ?? ''}:${r.id ?? ''}`;
+}
+
+export default ConceptSystem;

package/src/models/concept-type.ts

@@ -0,0 +1,33 @@
+// ConceptType — ISO 704:2022 §5.2-5.3 general vs individual concept.
+//
+//   general    — concept corresponds to a category of objects
+//                (designated by terms or symbols)
+//   individual — concept corresponds to a unique object
+//                (designated by proper names / appellations)
+//
+// Individual concepts occupy the bottom rung of a concept ladder
+// and cannot be subdivided into more specific concepts, but CAN be
+// subdivided into parts via a partitive relation.
+
+export type ConceptType = 'general' | 'individual';
+
+export const CONCEPT_TYPE: Readonly<Record<'GENERAL' | 'INDIVIDUAL', ConceptType>> =
+  Object.freeze({
+    GENERAL: 'general',
+    INDIVIDUAL: 'individual',
+  });
+
+export const CONCEPT_TYPE_VALUES: ReadonlyArray<ConceptType> = Object.freeze(
+  Object.values(CONCEPT_TYPE),
+);
+
+export const DEFAULT_CONCEPT_TYPE: ConceptType = CONCEPT_TYPE.GENERAL;
+
+export function isValidConceptType(value: unknown): value is ConceptType {
+  return (
+    typeof value === 'string' &&
+    (CONCEPT_TYPE_VALUES as readonly string[]).includes(value)
+  );
+}
+
+export default CONCEPT_TYPE;

package/src/models/{dataset-color.js → dataset-color.ts}

@@ -5,27 +5,34 @@
 //   - an explicit { light, dark } pair
 //
 // Round-trips through Register.toJSON unchanged so the data lives in
-// the GCR package. Consumers call resolvedColor(mode) to pick the
+// the GCR package. Consumers call resolveColor(mode) to pick the
 // right hex for the current UI mode.
 
-/**
- * @typedef {string} DatasetColorSpec
- * @typedef {{ light: string, dark: string }} DatasetColorPair
- * @typedef {DatasetColorSpec | DatasetColorPair} DatasetColor
- */
+export type ColorMode = 'light' | 'dark';
 
-export const COLOR_MODES = Object.freeze(['light', 'dark']);
+export type DatasetColorSpec = string;
+
+export interface DatasetColorPair {
+  light?: string;
+  dark?: string;
+}
+
+export type DatasetColor = DatasetColorSpec | DatasetColorPair;
+
+export const COLOR_MODES: ReadonlyArray<ColorMode> = Object.freeze([
+  'light',
+  'dark',
+]);
 
 /**
  * Returns the right hex for the given mode. Falls back to the single
  * hex when the spec is a string. Returns null when the spec is null
  * or when the requested mode is missing from a pair.
- *
- * @param {DatasetColor | null | undefined} color
- * @param {'light' | 'dark'} mode
- * @returns {string | null}
  */
-export function resolveColor(color, mode) {
+export function resolveColor(
+  color: DatasetColor | null | undefined,
+  mode: ColorMode,
+): string | null {
   if (color == null) return null;
   if (typeof color === 'string') return color;
   if (typeof color === 'object') {
@@ -37,10 +44,10 @@ export function resolveColor(color, mode) {
 
 /**
  * True when the spec declares an explicit {light, dark} object.
- * Lets callers distinguish "single hex" from "per-mode pair" without
- * repeating the typeof check.
  */
-export function isColorPair(color) {
+export function isColorPair(
+  color: DatasetColor | null | undefined,
+): color is DatasetColorPair {
   return color != null && typeof color === 'object';
 }
 
@@ -52,7 +59,9 @@ export function isColorPair(color) {
  *
  * Returns null when valid, or an error message describing the issue.
  */
-export function validateColor(color) {
+export function validateColor(
+  color: DatasetColor | null | undefined,
+): string | null {
   if (color == null) return null;
   if (typeof color === 'string') return hexError(color);
   if (typeof color === 'object') {
@@ -73,7 +82,7 @@ export function validateColor(color) {
 }
 
 const HEX_RE = /^#[0-9a-fA-F]{3,8}$/;
-function hexError(s) {
+function hexError(s: unknown): string | null {
   if (typeof s !== 'string') return `expected string, got ${typeof s}`;
   return HEX_RE.test(s) ? null : `not a valid hex color: ${JSON.stringify(s)}`;
 }

package/src/models/{definition-type.js → definition-type.ts}

@@ -7,6 +7,12 @@
 
 import { makeEnum } from './enum.js';
 
+export type DefinitionType =
+  | 'intensional'
+  | 'extensional'
+  | 'partitive'
+  | 'translated';
+
 export const DEFINITION_TYPE = makeEnum('DEFINITION_TYPE', {
   INTENSIONAL: 'intensional',
   EXTENSIONAL: 'extensional',
@@ -14,4 +20,5 @@ export const DEFINITION_TYPE = makeEnum('DEFINITION_TYPE', {
   TRANSLATED: 'translated',
 });
 
-export const DEFAULT_DEFINITION_TYPE = DEFINITION_TYPE.INTENSIONAL;
+export const DEFAULT_DEFINITION_TYPE: DefinitionType =
+  DEFINITION_TYPE.INTENSIONAL;

package/src/models/enum.ts

@@ -0,0 +1,60 @@
+// Enum factory — produces a frozen KEY/VALUES bundle, a frozen values
+// array, and an isValid predicate from a single `makeEnum` call.
+//
+// Adding a new enum means one line:
+//
+//   export const COLOR = makeEnum('COLOR', { RED: 'red', BLUE: 'blue' });
+//
+// The factory returns an object that exposes both the per-value
+// constants (COLOR.RED, COLOR.BLUE) and the VALUES list + isValid
+// predicate. The bundle is itself frozen.
+
+/**
+ * Output of {@link makeEnum}. Captures both the original key→value
+ * pairs (so `MY_ENUM.MY_KEY` is the literal string value) and the
+ * helper properties (`name`, `VALUES`, `isValid`).
+ */
+export type EnumBundle<TValues extends Readonly<Record<string, string>>> = {
+  readonly name: string;
+  readonly VALUES: ReadonlyArray<TValues[keyof TValues]>;
+  readonly isValid: (value: unknown) => value is TValues[keyof TValues];
+} & { readonly [K in keyof TValues]: TValues[K] };
+
+/**
+ * Build a frozen enum bundle.
+ *
+ * @param name Human-readable name used in error messages.
+ * @param values Object whose keys are the constant names and whose
+ *   string values are the wire representations.
+ */
+export function makeEnum<const TValues extends Readonly<Record<string, string>>>(
+  name: string,
+  values: TValues,
+): EnumBundle<TValues> {
+  if (typeof name !== 'string') {
+    throw new Error(`makeEnum: name must be a string, got ${typeof name}`);
+  }
+  if (typeof values !== 'object' || values === null) {
+    throw new Error(`makeEnum: values must be an object, got ${typeof values}`);
+  }
+  for (const [k, v] of Object.entries(values)) {
+    if (typeof v !== 'string') {
+      throw new Error(
+        `makeEnum(${name}): value for ${k} must be a string, got ${typeof v}`,
+      );
+    }
+  }
+
+  const frozen = Object.freeze({ ...values });
+  const valuesArr = Object.freeze(Object.values(frozen)) as ReadonlyArray<
+    TValues[keyof TValues]
+  >;
+  const isValid = (v: unknown): v is TValues[keyof TValues] =>
+    typeof v === 'string' && (valuesArr as readonly string[]).includes(v);
+
+  return Object.assign(Object.create(null) as object, frozen, {
+    name,
+    VALUES: valuesArr,
+    isValid,
+  }) as EnumBundle<TValues>;
+}

package/src/models/equivalence-degree.ts

@@ -0,0 +1,34 @@
+// EquivalenceDegree — ISO 704:2022 §7.7.3 cross-language equivalence.
+//
+//   full        — equivalent intension across languages (default)
+//   partial     — overlapping but not identical intension
+//   none        — no corresponding concept in this language
+//   directional — monodirectional equivalence (see equivalence_note)
+
+export type EquivalenceDegree =
+  | 'full'
+  | 'partial'
+  | 'none'
+  | 'directional';
+
+export const EQUIVALENCE_DEGREE: Readonly<Record<Uppercase<EquivalenceDegree>, EquivalenceDegree>> = Object.freeze({
+  FULL: 'full',
+  PARTIAL: 'partial',
+  NONE: 'none',
+  DIRECTIONAL: 'directional',
+});
+
+export const EQUIVALENCE_DEGREE_VALUES: ReadonlyArray<EquivalenceDegree> =
+  Object.freeze(Object.values(EQUIVALENCE_DEGREE));
+
+export const DEFAULT_EQUIVALENCE_DEGREE: EquivalenceDegree =
+  EQUIVALENCE_DEGREE.FULL;
+
+export function isValidEquivalenceDegree(value: unknown): value is EquivalenceDegree {
+  return (
+    typeof value === 'string' &&
+    (EQUIVALENCE_DEGREE_VALUES as readonly string[]).includes(value)
+  );
+}
+
+export default EQUIVALENCE_DEGREE;

package/src/models/{multiplicity.js → multiplicity.ts}

@@ -18,34 +18,47 @@
 // mapping. Both MULTIPLICITY constants and MULTIPLICITY_VALUES are
 // derived from this single table; no duplicate string literals.
 
-import { PARTITIVE_PRESENCE } from './partitive-presence.js';
-import { PARTITIVE_COUNT } from './partitive-count.js';
+import type { PartitivePresence } from './partitive-presence.js';
+import type { PartitiveCount } from './partitive-count.js';
 
-const NAME_BY_PAIR = Object.freeze({
-  [`${PARTITIVE_PRESENCE.REQUIRED}:${PARTITIVE_COUNT.EXACTLY_ONE}`]:  'compulsory',
-  [`${PARTITIVE_PRESENCE.OPTIONAL}:${PARTITIVE_COUNT.EXACTLY_ONE}`]:  'optional',
-  [`${PARTITIVE_PRESENCE.REQUIRED}:${PARTITIVE_COUNT.MULTIPLE}`]:     'compulsory_multiple',
-  [`${PARTITIVE_PRESENCE.OPTIONAL}:${PARTITIVE_COUNT.MULTIPLE}`]:     'optional_multiple',
-  [`${PARTITIVE_PRESENCE.REQUIRED}:${PARTITIVE_COUNT.AT_LEAST_ONE}`]: 'compulsory_at_least_one',
+export type MultiplicityName =
+  | 'compulsory'
+  | 'optional'
+  | 'compulsory_multiple'
+  | 'optional_multiple'
+  | 'compulsory_at_least_one';
+
+const NAME_BY_PAIR: Readonly<Record<string, MultiplicityName>> = Object.freeze({
+  'required:exactly_one': 'compulsory',
+  'optional:exactly_one': 'optional',
+  'required:multiple': 'compulsory_multiple',
+  'optional:multiple': 'optional_multiple',
+  'required:at_least_one': 'compulsory_at_least_one',
 });
 
-const PAIR_BY_NAME = Object.freeze(
+const PAIR_BY_NAME: Readonly<Record<MultiplicityName, string>> = Object.freeze(
   Object.fromEntries(
     Object.entries(NAME_BY_PAIR).map(([pair, name]) => [name, pair]),
-  ),
+  ) as Record<MultiplicityName, string>,
 );
 
-export const MULTIPLICITY = Object.freeze(
-  Object.fromEntries(
-    Object.values(NAME_BY_PAIR).map(name => [name.toUpperCase(), name]),
-  ),
-);
+export const MULTIPLICITY: Readonly<Record<Uppercase<MultiplicityName>, MultiplicityName>> =
+  Object.freeze(
+    Object.fromEntries(
+      Object.values(NAME_BY_PAIR).map((name) => [name.toUpperCase(), name]),
+    ),
+  ) as Readonly<Record<Uppercase<MultiplicityName>, MultiplicityName>>;
 
-export const MULTIPLICITY_VALUES = Object.freeze(Object.values(NAME_BY_PAIR));
+export const MULTIPLICITY_VALUES: ReadonlyArray<MultiplicityName> = Object.freeze(
+  Object.values(NAME_BY_PAIR),
+);
 
-export const DEFAULT_MULTIPLICITY = MULTIPLICITY.COMPULSORY;
+export const DEFAULT_MULTIPLICITY: MultiplicityName = MULTIPLICITY.COMPULSORY;
 
-export function multiplicityFromPair(presence, count) {
+export function multiplicityFromPair(
+  presence: PartitivePresence,
+  count: PartitiveCount,
+): MultiplicityName {
   const name = NAME_BY_PAIR[`${presence}:${count}`];
   if (name == null) {
     throw invalidCombinationError(presence, count);
@@ -53,28 +66,43 @@ export function multiplicityFromPair(presence, count) {
   return name;
 }
 
-// Canonical error message for the invalid (presence, count) combination.
-// Single source of truth — hyperedge-member.js delegates to this so the
-// error string doesn't drift across the two files. Phase 8 of
-// TODO.abstract-hyperedge.
-export function invalidCombinationError(presence, count) {
+/**
+ * Canonical error for the invalid (presence, count) combination.
+ * Single source of truth — hyperedge-member.ts delegates to this so
+ * the error string doesn't drift across the two files.
+ */
+export function invalidCombinationError(
+  presence: unknown,
+  count: unknown,
+): Error {
   return new Error(
     `Invalid multiplicity combination: presence=${presence}, count=${count}. ` +
     `(optional + at_least_one collapses to optional + multiple — use count=multiple.)`,
   );
 }
 
-export function pairFromMultiplicity(name) {
+export function pairFromMultiplicity(
+  name: MultiplicityName,
+): { presence: PartitivePresence; count: PartitiveCount } {
   const pair = PAIR_BY_NAME[name];
   if (pair == null) {
     throw new Error(`Unknown multiplicity: ${JSON.stringify(name)}`);
   }
-  const [presence, count] = pair.split(':');
+  const [presence, count] = pair.split(':') as [PartitivePresence, PartitiveCount];
   return { presence, count };
 }
 
-export function isValidMultiplicity(name) {
-  return Object.prototype.hasOwnProperty.call(PAIR_BY_NAME, name);
+export function isValidMultiplicity(name: unknown): name is MultiplicityName {
+  return (
+    typeof name === 'string' &&
+    Object.prototype.hasOwnProperty.call(PAIR_BY_NAME, name)
+  );
+}
+
+interface MemberWithMultiplicity {
+  presence?: PartitivePresence;
+  count?: PartitiveCount;
+  multiplicity?: string;
 }
 
 /**
@@ -93,7 +121,9 @@ export function isValidMultiplicity(name) {
  * rather than silently returning 'compulsory' (which would mask the
  * data corruption).
  */
-export function resolveMultiplicity(member) {
+export function resolveMultiplicity(
+  member: MemberWithMultiplicity | null | undefined,
+): MultiplicityName | string {
   if (member?.presence && member?.count) {
     return multiplicityFromPair(member.presence, member.count);
   }
@@ -102,4 +132,3 @@ export function resolveMultiplicity(member) {
   }
   return DEFAULT_MULTIPLICITY;
 }
-

package/src/models/{partitive-count.js → partitive-count.ts}

@@ -9,6 +9,8 @@
 
 import { makeEnum } from './enum.js';
 
+export type PartitiveCount = 'exactly_one' | 'at_least_one' | 'multiple';
+
 export const PARTITIVE_COUNT = makeEnum('PARTITIVE_COUNT', {
   EXACTLY_ONE: 'exactly_one',
   AT_LEAST_ONE: 'at_least_one',
@@ -16,5 +18,5 @@ export const PARTITIVE_COUNT = makeEnum('PARTITIVE_COUNT', {
 });
 
 export const PARTITIVE_COUNT_VALUES = PARTITIVE_COUNT.VALUES;
-export const DEFAULT_COUNT = PARTITIVE_COUNT.EXACTLY_ONE;
+export const DEFAULT_COUNT: PartitiveCount = PARTITIVE_COUNT.EXACTLY_ONE;
 export const isValidCount = PARTITIVE_COUNT.isValid;

package/src/models/partitive-enumeration.ts

@@ -0,0 +1,27 @@
+// PartitiveEnumeration — allowed values for PartitiveHyperedge#enumeration.
+//
+//   closed — the encoded parts are ALL the parts of the comprehensive.
+//            Adding or removing a part would change the relationship.
+//   open   — the encoded parts are SOME of the parts; others may exist
+//            but are not encoded.
+
+export type PartitiveEnumeration = 'closed' | 'open';
+
+export const PARTITIVE_ENUMERATION: Readonly<
+  Record<'CLOSED' | 'OPEN', PartitiveEnumeration>
+> = Object.freeze({
+  CLOSED: 'closed',
+  OPEN: 'open',
+});
+
+export const PARTITIVE_ENUMERATION_VALUES: ReadonlyArray<PartitiveEnumeration> =
+  Object.freeze([PARTITIVE_ENUMERATION.CLOSED, PARTITIVE_ENUMERATION.OPEN]);
+
+export function isValidPartitiveEnumeration(
+  value: unknown,
+): value is PartitiveEnumeration {
+  return (
+    typeof value === 'string' &&
+    (PARTITIVE_ENUMERATION_VALUES as readonly string[]).includes(value)
+  );
+}

package/src/models/{partitive-presence.js → partitive-presence.ts}

@@ -8,11 +8,13 @@
 
 import { makeEnum } from './enum.js';
 
+export type PartitivePresence = 'required' | 'optional';
+
 export const PARTITIVE_PRESENCE = makeEnum('PARTITIVE_PRESENCE', {
   REQUIRED: 'required',
   OPTIONAL: 'optional',
 });
 
 export const PARTITIVE_PRESENCE_VALUES = PARTITIVE_PRESENCE.VALUES;
-export const DEFAULT_PRESENCE = PARTITIVE_PRESENCE.REQUIRED;
+export const DEFAULT_PRESENCE: PartitivePresence = PARTITIVE_PRESENCE.REQUIRED;
 export const isValidPresence = PARTITIVE_PRESENCE.isValid;

package/src/models/{plurality-marker.js → plurality-marker.ts}

@@ -9,16 +9,23 @@
 // Orthogonal to PartitiveEnumeration — both may be set on the same
 // hyperedge.
 
-export const PLURALITY_MARKER = Object.freeze({
+export type PluralityMarker = 'double' | 'dashed';
+
+export const PLURALITY_MARKER: Readonly<
+  Record<'DOUBLE' | 'DASHED', PluralityMarker>
+> = Object.freeze({
   DOUBLE: 'double',
   DASHED: 'dashed',
 });
 
-export const PLURALITY_MARKER_VALUES = Object.freeze([
-  PLURALITY_MARKER.DOUBLE,
-  PLURALITY_MARKER.DASHED,
-]);
+export const PLURALITY_MARKER_VALUES: ReadonlyArray<PluralityMarker> =
+  Object.freeze([PLURALITY_MARKER.DOUBLE, PLURALITY_MARKER.DASHED]);
 
-export function isValidPluralityMarker(value) {
-  return PLURALITY_MARKER_VALUES.includes(value);
+export function isValidPluralityMarker(
+  value: unknown,
+): value is PluralityMarker {
+  return (
+    typeof value === 'string' &&
+    (PLURALITY_MARKER_VALUES as readonly string[]).includes(value)
+  );
 }

package/src/models/sequential-hyperedge.js

@@ -0,0 +1,56 @@
+// SequentialHyperedge — an ISO 12620 A.6.3 / ISO 704:2022 §5.5.5
+// sequential relation connecting a comprehensive concept to two or
+// more subordinate concepts in an ORDERED sequence (temporal,
+// spatial, causal, developmental).
+//
+// Mirror of PartitiveHyperedge and GenericHyperedge. Member array
+// order IS significant — reversing the array reverses the sequence.
+// Use cases: manufacturing process steps, biological life cycles,
+// software release lifecycles, supply chain stages, geological eras.
+//
+// See docs/design/abstract-nary-relation.md (concept-model repo).
+
+import { AbstractHyperedge } from './abstract-hyperedge.js';
+import { SequentialMember } from './sequential-member.js';
+import { HyperedgeRegistry } from './hyperedge-registry.js';
+
+export class SequentialHyperedge extends AbstractHyperedge {
+  // Per-class metadata block — the OCP contract.
+  static wireKey     = 'sequential_relations';
+  static typeTag     = 'sequential_relation';
+  static rdfType     = 'gloss:SequentialRelation';
+  static memberClass = SequentialMember;
+  static v1WireKeys  = [];
+  static kindLabel   = 'SEQ';
+
+  constructor(data = {}) {
+    super(data);
+    this.members = data?.members == null
+      ? this.members
+      : (Array.isArray(data.members)
+          ? data.members.map(m =>
+              m instanceof SequentialMember ? m : new SequentialMember(m))
+          : this.members);
+  }
+
+  static identityOf(value) {
+    const v = value ?? {};
+    const c = v.comprehensive ?? {};
+    // For sequential, member order IS significant — do NOT sort.
+    const memberKeys = Array.isArray(v.members)
+      ? v.members.map(m => {
+          const r = m?.ref ?? m ?? {};
+          return `${r.source ?? ''}:${r.id ?? ''}`;
+        })
+      : [];
+    return `${c.source ?? ''}:${c.id ?? ''}|${memberKeys.join('|')}`;
+  }
+
+  static fromJSON(data) {
+    return new SequentialHyperedge(data);
+  }
+}
+
+export default SequentialHyperedge;
+
+HyperedgeRegistry.register(SequentialHyperedge);

package/src/models/sequential-member.js

@@ -0,0 +1,13 @@
+// SequentialMember — one member of a SequentialHyperedge. Inherits
+// the MECE shape from HyperedgeMember. Distinct leaf class for type
+// safety. Member array order IS significant for sequential hyperedges.
+//
+// See docs/design/abstract-nary-relation.md (concept-model repo).
+
+import { HyperedgeMember } from './hyperedge-member.js';
+
+export class SequentialMember extends HyperedgeMember {
+  // Inherits all attributes and validations from HyperedgeMember.
+}
+
+export default SequentialMember;

package/src/models/base.js

@@ -1,32 +0,0 @@
-export class GlossaristModel {
-  toJSON() {
-    throw new Error(`${this.constructor.name} must implement toJSON()`);
-  }
-
-  static fromJSON() {
-    throw new Error(`${this.name} must implement fromJSON()`);
-  }
-
-  equals(other) {
-    if (!(other instanceof this.constructor)) return false;
-    return JSON.stringify(this.toJSON()) === JSON.stringify(other.toJSON());
-  }
-
-  clone() {
-    return this.constructor.fromJSON(JSON.parse(JSON.stringify(this.toJSON())));
-  }
-
-  _lazy(cacheKey, rawKey, wrapFn) {
-    if (this[cacheKey] === null) {
-      this[cacheKey] = this[rawKey].map(wrapFn);
-    }
-    return this[cacheKey];
-  }
-
-  _serialize(obj, jsonKey, cacheKey, rawKey) {
-    const items = this[cacheKey] ?? (this[rawKey].length > 0 ? this[rawKey] : []);
-    if (items.length > 0) {
-      obj[jsonKey] = items.map(i => (i instanceof GlossaristModel) ? i.toJSON() : i);
-    }
-  }
-}

package/src/models/concept-date.js

@@ -1,36 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export const DATE_TYPES = Object.freeze([
-  'accepted', 'amended', 'retired',
-]);
-
-export class ConceptDate extends GlossaristModel {
-  constructor(data = {}) {
-    super();
-    this.date = data.date ?? null;
-    this.type = data.type ?? null;
-  }
-
-  get parsedDate() {
-    return this.date ? new Date(this.date) : null;
-  }
-
-  static identityOf(value) {
-    return value?.type ?? '';
-  }
-
-  identity() {
-    return ConceptDate.identityOf(this);
-  }
-
-  toJSON() {
-    const obj = {};
-    if (this.date != null) obj.date = this.date;
-    if (this.type != null) obj.type = this.type;
-    return obj;
-  }
-
-  static fromJSON(data) {
-    return new ConceptDate(data);
-  }
-}

package/src/models/concept-ref.js

@@ -1,36 +0,0 @@
-import { GlossaristModel } from './base.js';
-
-export class ConceptRef extends GlossaristModel {
-  constructor(data = {}) {
-    super();
-    this.source = data.source ?? null;
-    this.id = data.id ?? null;
-    this.text = data.text ?? null;
-  }
-
-  toString() {
-    const parts = [];
-    if (this.source) parts.push(this.source);
-    if (this.id) parts.push(this.id);
-    const base = parts.join(' ');
-    if (this.text && base) return `${base} (${this.text})`;
-    if (this.text) return this.text;
-    return base;
-  }
-
-  toJSON() {
-    const obj = {};
-    if (this.source != null) obj.source = this.source;
-    if (this.id != null) obj.id = this.id;
-    if (this.text != null) obj.text = this.text;
-    return obj;
-  }
-
-  identity() {
-    return `${this.source ?? ''}|${this.id ?? ''}`;
-  }
-
-  static fromJSON(data) {
-    return new ConceptRef(data);
-  }
-}

package/src/models/concept-source.js

@@ -1,52 +0,0 @@
-import { GlossaristModel } from './base.js';
-import { Citation } from './citation.js';
-
-export class ConceptSource extends GlossaristModel {
-  constructor(data = {}) {
-    super();
-    this.id = data.id ?? null;
-    this.status = data.status ?? null;
-    this.type = data.type ?? null;
-    this.origin = data.origin
-      ? (data.origin instanceof Citation ? data.origin : new Citation(data.origin))
-      : null;
-    this.modification = data.modification ?? null;
-    this.sourcedFrom = (data.sourcedFrom ?? data.sourced_from ?? []).map(
-      c => c instanceof Citation ? c : new Citation(c)
-    );
-  }
-
-  // Backward-compat alias for callers using the snake_case JS field name.
-  // Prefer `.sourcedFrom` going forward; the wire name remains
-  // `sourced_from` (see toJSON).
-  get sourced_from() {
-    return this.sourcedFrom;
-  }
-
-  toJSON() {
-    const obj = {};
-    if (this.id != null) obj.id = this.id;
-    if (this.status != null) obj.status = this.status;
-    if (this.type != null) obj.type = this.type;
-    if (this.origin != null) obj.origin = this.origin.toJSON();
-    if (this.modification != null) obj.modification = this.modification;
-    if (this.sourcedFrom.length > 0) {
-      obj.sourced_from = this.sourcedFrom.map(c => c.toJSON());
-    }
-    return obj;
-  }
-
-  static identityOf(value) {
-    const v = value ?? {};
-    const ref = v?.origin?.ref ?? (v?.origin instanceof Citation ? v.origin.ref : null);
-    return `${v.type ?? ''}|${ref?.source ?? ''}|${ref?.id ?? ''}`;
-  }
-
-  identity() {
-    return ConceptSource.identityOf(this);
-  }
-
-  static fromJSON(data) {
-    return new ConceptSource(data);
-  }
-}

package/src/models/enum.js

@@ -1,42 +0,0 @@
-// Enum factory — produces a frozen KEY/VALUES bundle, a frozen values
-// array, and an isValid* predicate from a single `makeEnum` call.
-//
-// Adding a new enum means one line:
-//
-//   export const COLOR = makeEnum('COLOR', { RED: 'red', BLUE: 'blue' });
-//
-// The factory returns:
-//   {
-//     CLOSED: 'closed',           // exposed by destructuring
-//     OPEN:   'open',
-//     VALUES: ['closed', 'open'],  // frozen array
-//     isValid: (v) => boolean,     // predicate
-//   }
-//
-// We attach the bundle via Object.assign on a frozen object so the
-// bundle is itself frozen and exposes both the per-value constants
-// (CLOSED, OPEN, ...) and the VALUES list + isValid predicate.
-
-export function makeEnum(name, values) {
-  if (typeof name !== 'string') {
-    throw new Error(`makeEnum: name must be a string, got ${typeof name}`);
-  }
-  if (typeof values !== 'object' || values === null) {
-    throw new Error(`makeEnum: values must be an object, got ${typeof values}`);
-  }
-  for (const [k, v] of Object.entries(values)) {
-    if (typeof v !== 'string') {
-      throw new Error(`makeEnum(${name}): value for ${k} must be a string, got ${typeof v}`);
-    }
-  }
-
-  const frozen = Object.freeze({ ...values });
-  const valuesArr = Object.freeze(Object.values(frozen));
-  const isValid = (v) => valuesArr.includes(v);
-
-  return Object.assign(Object.create(null), frozen, {
-    name,
-    VALUES: valuesArr,
-    isValid,
-  });
-}

package/src/models/partitive-enumeration.js

@@ -1,23 +0,0 @@
-// PartitiveEnumeration — allowed values for PartitiveHyperedge#enumeration.
-//
-//   closed — the encoded parts are ALL the parts of the comprehensive.
-//            Adding or removing a part would change the relationship.
-//   open   — the encoded parts are SOME of the parts; others may exist
-//            but are not encoded.
-//
-// See concept-model/TODO.hyperedge/00-design-overview.md for the design
-// rationale and the open/closed distinction.
-
-export const PARTITIVE_ENUMERATION = Object.freeze({
-  CLOSED: 'closed',
-  OPEN: 'open',
-});
-
-export const PARTITIVE_ENUMERATION_VALUES = Object.freeze([
-  PARTITIVE_ENUMERATION.CLOSED,
-  PARTITIVE_ENUMERATION.OPEN,
-]);
-
-export function isValidPartitiveEnumeration(value) {
-  return PARTITIVE_ENUMERATION_VALUES.includes(value);
-}