glossarist 0.4.31 → 0.4.32

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.4.31",
+  "version": "0.4.32",
   "description": "JavaScript SDK for Glossarist GCR packages — read, write, validate, and manage terminology concepts",
   "type": "module",
   "main": "src/index.js",

package/src/concept-parser.js

@@ -5,13 +5,16 @@ import { migrateHyperedgeToRelation } from './migration/partitive-relation-migra
 import { InvalidInputError, YamlParseError } from './errors.js';
 
 // Structural keys are reserved at the concept level and excluded
-// from language localization discovery. Updated for v2:
-// `partitive_relations` is the v2 wire name; `partitive_hyperedges`
-// is accepted as v1 backward-compat input.
+// from language localization discovery. The unified `relations`
+// key, the v2 typed keys (`partitive_relations`, `generic_relations`),
+// and the v1 backward-compat key (`partitive_hyperedges`) are all
+// reserved.
 const STRUCTURAL_KEYS = new Set([
   'termid', 'term', 'figures', 'tables', 'formulas',
+  'relations',
   'partitive_hyperedges', 'partitiveHyperedges',
   'partitive_relations', 'partitiveRelations',
+  'generic_relations', 'genericRelations',
 ]);
 
 export class ConceptParser {
@@ -67,7 +70,7 @@ export class ConceptParser {
       figures: doc.figures,
       tables: doc.tables,
       formulas: doc.formulas,
-      partitiveRelations: _resolvePartitiveData(doc),
+      relations: _resolveNaryData(doc),
       raw: doc,
     });
   }
@@ -84,14 +87,20 @@ export class ConceptParser {
       localizations[lang] = lcData;
     }
 
-    assertConceptLevelOnly(mc, ['related', 'partitive_relations', 'partitive_hyperedges']);
+    assertConceptLevelOnly(mc, [
+      'related',
+      'relations',
+      'partitive_relations',
+      'partitive_hyperedges',
+      'generic_relations',
+    ]);
 
     return new Concept({
       id: String(mc.data.identifier),
       term: null,
       localizations,
       related: _normalizeRelated(mc.related),
-      partitiveRelations: _resolvePartitiveData(mc),
+      relations: _resolveNaryData(mc),
       domains: mc.data.domains,
       groups: mc.data.groups,
       dates: mc.dates ?? mc.data?.dates,
@@ -121,26 +130,63 @@ function assertConceptLevelOnly(mc, keys) {
   }
 }
 
-// Resolves partitive relation data from any of three input shapes:
-//   v2 wire:    { partitive_relations: [...] }
-//   v2 camel:   { partitiveRelations: [...] }
-//   v1 wire:    { partitive_hyperedges: [...] }   ← migrated to v2
-//   v1 camel:   { partitiveHyperedges: [...] }    ← migrated to v2
+// Resolve n-ary relation data from any input shape into a single
+// unified array. Accepts:
 //
-// Returns null when no partitive data is present, so Concept's
-// `_resolvePartitiveRelations` falls back to the empty-array default.
-function _resolvePartitiveData(container) {
-  const v2 = container?.partitive_relations ?? container?.partitiveRelations;
-  if (Array.isArray(v2)) return v2;
+//   unified wire:  { relations: [...] }                     (hashes with `type`)
+//   v2 partitive:  { partitive_relations: [...] }           (hashes)
+//   v2 generic:    { generic_relations: [...] }             (hashes)
+//   v1 partitive:  { partitive_hyperedges: [...] }           ← migrated
+//
+// Returns null when no relation data is present, so Concept's
+// `_resolveNaryRelations` falls back to the empty-array default.
+function _resolveNaryData(container) {
+  if (!container) return null;
+
+  if (Array.isArray(container.relations)) {
+    return container.relations;
+  }
+
+  const out = [];
+
+  const v2Partitive = container.partitive_relations ?? container.partitiveRelations;
+  if (Array.isArray(v2Partitive)) {
+    for (const r of v2Partitive) {
+      const tagged = _addTypeIfMissing(r, 'partitive_relation');
+      if (tagged != null) out.push(tagged);
+    }
+  }
+
+  const v2Generic = container.generic_relations ?? container.genericRelations;
+  if (Array.isArray(v2Generic)) {
+    for (const r of v2Generic) {
+      const tagged = _addTypeIfMissing(r, 'generic_relation');
+      if (tagged != null) out.push(tagged);
+    }
+  }
 
-  const v1 = container?.partitive_hyperedges ?? container?.partitiveHyperedges;
+  const v1 = container.partitive_hyperedges ?? container.partitiveHyperedges;
   if (Array.isArray(v1)) {
-    return v1
-      .map(h => (h?.toJSON && typeof h.toJSON === 'function') ? h.toJSON() : h)
-      .map(migrateHyperedgeToRelation)
-      .filter(h => h != null);
+    for (const h of v1) {
+      const hash = h?.toJSON && typeof h.toJSON === 'function' ? h.toJSON() : h;
+      const migrated = migrateHyperedgeToRelation(hash);
+      if (migrated) out.push({ ...migrated, type: 'partitive_relation' });
+    }
+  }
+
+  return out.length > 0 ? out : null;
+}
+
+function _addTypeIfMissing(value, type) {
+  if (value == null) return null;
+  if (typeof value.toJSON === 'function') {
+    const hash = value.toJSON();
+    return hash.type ? hash : { ...hash, type };
+  }
+  if (typeof value === 'object') {
+    return value.type ? value : { ...value, type };
   }
-  return null;
+  return value;
 }
 
 function _normalizeRelated(arr) {

package/src/concept-serializer.js

@@ -1,18 +1,30 @@
 import * as yaml from 'js-yaml';
+import { PartitiveRelation } from './models/partitive-relation.js';
+import { GenericRelation } from './models/generic-relation.js';
 
 const DUMP_OPTS = { lineWidth: -1, noRefs: true, sortKeys: false, skipInvalid: true };
 
+// Partition the unified relations array by concrete type and emit
+// each type under its own wire key. Concept.relations holds mixed
+// types; the wire format stays split for backward compat with
+// existing consumers and the JSON Schema in concept-model.
+function _emitTypedRelations(concept) {
+  const partitiveRels = concept.relations.filter(r => r instanceof PartitiveRelation);
+  const genericRels = concept.relations.filter(r => r instanceof GenericRelation);
+  return {
+    partitive: partitiveRels.map(r => r.toJSON()),
+    generic: genericRels.map(r => r.toJSON()),
+  };
+}
+
 export class ConceptSerializer {
   toCanonicalYaml(concept) {
     const doc = { termid: concept.id };
     if (concept.term) doc.term = concept.term;
 
-    // v2: emit partitive_relations (was partitive_hyperedges in v1).
-    // Concept.partitiveRelations is the canonical v2 property; the
-    // v1 alias `partitiveHyperedges` points at the same array.
-    if (concept.partitiveRelations && concept.partitiveRelations.length > 0) {
-      doc.partitive_relations = concept.partitiveRelations.map(r => r.toJSON());
-    }
+    const { partitive, generic } = _emitTypedRelations(concept);
+    if (partitive.length > 0) doc.partitive_relations = partitive;
+    if (generic.length > 0) doc.generic_relations = generic;
 
     for (const lang of concept.languages) {
       const lc = concept.localization(lang);
@@ -53,10 +65,9 @@ export class ConceptSerializer {
     if (concept.relatedConcepts.length > 0) {
       mainDoc.related = concept.relatedConcepts.map(rc => rc.toJSON());
     }
-    // v2 wire name. Concept loads both v1 and v2 input but emits only v2.
-    if (concept.partitiveRelations && concept.partitiveRelations.length > 0) {
-      mainDoc.partitive_relations = concept.partitiveRelations.map(r => r.toJSON());
-    }
+    const { partitive, generic } = _emitTypedRelations(concept);
+    if (partitive.length > 0) mainDoc.partitive_relations = partitive;
+    if (generic.length > 0) mainDoc.generic_relations = generic;
     if (concept.sources.length > 0) {
       mainDoc.sources = concept.sources.map(s => s.toJSON());
     }

package/src/diff/concept-diff.js

@@ -1,4 +1,6 @@
 import { GlossaristModel } from '../models/base.js';
+import { PartitiveRelation } from '../models/partitive-relation.js';
+import { GenericRelation } from '../models/generic-relation.js';
 import { Added, Removed, Changed } from './change.js';
 import { ListDiff, diffList, diffSet } from './list-diff.js';
 import { identityOf } from './identity.js';
@@ -99,11 +101,17 @@ export class ConceptLevelDiff extends GlossaristModel {
     this._sources = wrapListDiff(data.sources);
     this._dates = wrapListDiff(data.dates);
     this._relatedConcepts = wrapListDiff(data.relatedConcepts ?? data.related_concepts);
-    // v2 canonical name is partitiveRelations. Accept v1 names
-    // (partitiveHyperedges / partitive_hyperedges) for backward compat
-    // with diffs serialized by older glossarist-js versions.
-    this._partitiveRelations = wrapListDiff(
-      data.partitiveRelations
+    // Unified n-ary relations diff. Accepts:
+    //   - data.relations                   (new unified shape)
+    //   - data.partitiveRelations /
+    //     data.partitive_relations /
+    //     data.partitiveHyperedges /
+    //     data.partitive_hyperedges        (legacy partitive-only shape)
+    // Old diffs only had partitive, so the legacy fallback treats them
+    // as a unified list with one type present.
+    this._relations = wrapListDiff(
+      data.relations
+        ?? data.partitiveRelations
         ?? data.partitive_relations
         ?? data.partitiveHyperedges
         ?? data.partitive_hyperedges,
@@ -119,8 +127,25 @@ export class ConceptLevelDiff extends GlossaristModel {
   get sources() { return this._sources; }
   get dates() { return this._dates; }
   get relatedConcepts() { return this._relatedConcepts; }
-  get partitiveRelations() { return this._partitiveRelations; }
-  /** @deprecated use partitiveRelations */ get partitiveHyperedges() { return this._partitiveRelations; }
+  /** Unified n-ary relations diff (PartitiveRelation + GenericRelation). */
+  get relations() { return this._relations; }
+  /**
+   * Filtered view of `relations` containing only PartitiveRelation
+   * entries. Backward compat for callers that read .partitiveRelations
+   * directly on a ConceptLevelDiff.
+   */
+  get partitiveRelations() {
+    return filterListDiffByType(this._relations, PartitiveRelation);
+  }
+  /** @deprecated use .relations */ get partitiveHyperedges() { return this.partitiveRelations; }
+  /**
+   * Filtered view of `relations` containing only GenericRelation
+   * entries. Backward compat for callers that read .genericRelations
+   * directly on a ConceptLevelDiff.
+   */
+  get genericRelations() {
+    return filterListDiffByType(this._relations, GenericRelation);
+  }
   get groups() { return this._groups; }
   get sections() { return this._sections; }
   get tags() { return this._tags; }
@@ -130,7 +155,7 @@ export class ConceptLevelDiff extends GlossaristModel {
     return this._sources.hasChanges
       || this._dates.hasChanges
       || this._relatedConcepts.hasChanges
-      || this._partitiveRelations.hasChanges
+      || this._relations.hasChanges
       || this._groups.hasChanges
       || this._sections.hasChanges
       || this._tags.hasChanges
@@ -141,7 +166,7 @@ export class ConceptLevelDiff extends GlossaristModel {
     yield* walkList('concept.sources', this._sources);
     yield* walkList('concept.dates', this._dates);
     yield* walkList('concept.relatedConcepts', this._relatedConcepts);
-    yield* walkList('concept.partitiveRelations', this._partitiveRelations);
+    yield* walkList('concept.relations', this._relations);
     yield* walkList('concept.groups', this._groups);
     yield* walkList('concept.sections', this._sections);
     yield* walkList('concept.tags', this._tags);
@@ -153,7 +178,7 @@ export class ConceptLevelDiff extends GlossaristModel {
       sources: this._sources.toJSON(),
       dates: this._dates.toJSON(),
       related_concepts: this._relatedConcepts.toJSON(),
-      partitive_relations: this._partitiveRelations.toJSON(),
+      relations: this._relations.toJSON(),
       groups: this._groups.toJSON(),
       sections: this._sections.toJSON(),
       tags: this._tags.toJSON(),
@@ -428,7 +453,7 @@ function diffConceptLevel(oldConcept, newConcept) {
       sources: fullListDiff(c.sources ?? [], Direction),
       dates: fullListDiff(c.dates ?? [], Direction),
       relatedConcepts: fullListDiff(c.relatedConcepts ?? [], Direction),
-      partitiveRelations: fullListDiff(c.partitiveRelations ?? c.partitiveHyperedges ?? [], Direction),
+      relations: fullListDiff(c.relations ?? [], Direction),
       groups: fullListDiff(c.groups ?? [], Direction),
       sections: fullListDiff(c.sections ?? [], Direction),
       tags: fullListDiff(c.tags ?? [], Direction),
@@ -440,9 +465,9 @@ function diffConceptLevel(oldConcept, newConcept) {
     sources: diffSources(oldConcept.sources ?? [], newConcept.sources ?? []),
     dates: diffDates(oldConcept.dates ?? [], newConcept.dates ?? []),
     relatedConcepts: diffRelatedConcepts(oldConcept.relatedConcepts ?? [], newConcept.relatedConcepts ?? []),
-    partitiveRelations: diffPartitiveRelations(
-      oldConcept.partitiveRelations ?? oldConcept.partitiveHyperedges ?? [],
-      newConcept.partitiveRelations ?? newConcept.partitiveHyperedges ?? [],
+    relations: diffNaryRelations(
+      oldConcept.relations ?? [],
+      newConcept.relations ?? [],
     ),
     groups: diffStringSet(oldConcept.groups ?? [], newConcept.groups ?? []),
     sections: diffStringSet(oldConcept.sections ?? [], newConcept.sections ?? []),
@@ -540,13 +565,40 @@ function diffRelatedConcepts(oldRC, newRC) {
   });
 }
 
-function diffPartitiveRelations(oldR, newR) {
+// Diff two unified n-ary relations arrays. Identity is polymorphic —
+// dispatches via value.constructor.identityOf so PartitiveRelation
+// and GenericRelation (and any future n-ary subclass) coexist in
+// the same list. Cross-type entries with matching identity are still
+// treated as different (because their constructor differs and they
+// live under different wire keys).
+function diffNaryRelations(oldR, newR) {
   return diffSet(oldR, newR, {
-    identityKey: identityOf,
+    identityKey: relationIdentityOf,
     textKey: relationText,
   });
 }
 
+function relationIdentityOf(value) {
+  if (value == null) return '';
+  const Cls = value.constructor;
+  if (typeof Cls?.identityOf === 'function') {
+    const typed = Cls.identityOf(value);
+    return `${Cls.name}::${typed}`;
+  }
+  return identityOf(value);
+}
+
+function filterListDiffByType(listDiff, Cls) {
+  if (!listDiff) return listDiff;
+  return new ListDiff({
+    added: listDiff.added.filter(e => e.value instanceof Cls),
+    removed: listDiff.removed.filter(e => e.value instanceof Cls),
+    changed: listDiff.changed.filter(e =>
+      (e.oldValue == null || e.oldValue instanceof Cls) &&
+      (e.newValue == null || e.newValue instanceof Cls)),
+  });
+}
+
 function relationText(r) {
   if (!r) return '';
   return canonicalJson(typeof r.toJSON === 'function' ? r.toJSON() : r);
@@ -598,8 +650,8 @@ function countConceptItems(oldConcept, newConcept, langs) {
   count += maxOf(oldConcept?.dates?.length, newConcept?.dates?.length);
   count += maxOf(oldConcept?.relatedConcepts?.length, newConcept?.relatedConcepts?.length);
   count += maxOf(
-    oldConcept?.partitiveRelations?.length ?? oldConcept?.partitiveHyperedges?.length,
-    newConcept?.partitiveRelations?.length ?? newConcept?.partitiveHyperedges?.length,
+    oldConcept?.relations?.length,
+    newConcept?.relations?.length,
   );
   count += maxOf(oldConcept?.groups?.length, newConcept?.groups?.length);
   count += maxOf(oldConcept?.sections?.length, newConcept?.sections?.length);

package/src/diff/diff-patch.js

@@ -5,6 +5,7 @@ import { RelatedConcept } from '../models/related-concept.js';
 import { Designation } from '../models/designation.js';
 import { DetailedDefinition } from '../models/detailed-definition.js';
 import { PartitiveRelation } from '../models/partitive-relation.js';
+import { GenericRelation } from '../models/generic-relation.js';
 import { Added, Removed, Changed } from './change.js';
 import { ListDiff } from './list-diff.js';
 import { TextDiff, TextHunk } from './text-diff.js';
@@ -67,9 +68,7 @@ export function reverseDiff(diff) {
     sources: reverseListDiff(diff.concept.sources),
     dates: reverseListDiff(diff.concept.dates),
     relatedConcepts: reverseListDiff(diff.concept.relatedConcepts),
-    partitiveRelations: reverseListDiff(
-      diff.concept.partitiveRelations ?? diff.concept.partitiveHyperedges,
-    ),
+    relations: reverseListDiff(diff.concept.relations),
     groups: reverseListDiff(diff.concept.groups),
     sections: reverseListDiff(diff.concept.sections),
     tags: reverseListDiff(diff.concept.tags),
@@ -108,15 +107,32 @@ function applyConceptLevelPatch(json, conceptDiff) {
   json.sources = applyListPatch(json.sources ?? [], conceptDiff.sources, ConceptSource.identityOf);
   json.dates = applyListPatch(json.dates ?? [], conceptDiff.dates, ConceptDate.identityOf);
   json.related = applyListPatch(json.related ?? [], conceptDiff.relatedConcepts, RelatedConcept.identityOf);
-  json.partitive_relations = applyListPatch(
-    json.partitive_relations ?? json.partitive_hyperedges ?? [],
-    conceptDiff.partitiveRelations ?? conceptDiff.partitiveHyperedges,
-    PartitiveRelation.identityOf,
-  );
-  // v1 wire key is removed once v2 has replaced it; otherwise leave
-  // v1 data in place for backward-compat readers.
-  if (json.partitive_relations != null && json.partitive_hyperedges != null) {
-    delete json.partitive_hyperedges;
+
+  // Unified relations diff → typed wire keys. Partition the unified
+  // diff by concrete class and apply each half to its own wire key.
+  // The wire format stays split (partitive_relations + generic_relations)
+  // for backward compat with consumers; the in-memory model is unified.
+  const partitiveDiff = partitionListDiff(conceptDiff.relations, PartitiveRelation);
+  const genericDiff = partitionListDiff(conceptDiff.relations, GenericRelation);
+
+  if (partitiveDiff.hasChanges) {
+    json.partitive_relations = applyListPatch(
+      json.partitive_relations ?? json.partitive_hyperedges ?? [],
+      partitiveDiff,
+      PartitiveRelation.identityOf,
+    );
+    // v1 wire key is removed once v2 has replaced it; otherwise leave
+    // v1 data in place for backward-compat readers.
+    if (json.partitive_relations != null && json.partitive_hyperedges != null) {
+      delete json.partitive_hyperedges;
+    }
+  }
+  if (genericDiff.hasChanges) {
+    json.generic_relations = applyListPatch(
+      json.generic_relations ?? [],
+      genericDiff,
+      GenericRelation.identityOf,
+    );
   }
 
   json.tags = applyListPatch(json.tags ?? [], conceptDiff.tags);
@@ -233,3 +249,19 @@ function toJsonValue(value) {
   if (typeof value.toJSON === 'function') return value.toJSON();
   return value;
 }
+
+// Project a unified relations ListDiff onto a single concrete class.
+// Entries whose value (old or new) is an instance of `Cls` survive;
+// everything else is filtered out. Cross-type changed entries (e.g.
+// old was PartitiveRelation, new is GenericRelation) are not yet
+// supported — those would need to surface as a remove + add pair.
+function partitionListDiff(listDiff, Cls) {
+  if (!listDiff) return new ListDiff({ added: [], removed: [], changed: [] });
+  return new ListDiff({
+    added: listDiff.added.filter(e => e.value instanceof Cls),
+    removed: listDiff.removed.filter(e => e.value instanceof Cls),
+    changed: listDiff.changed.filter(e =>
+      (e.oldValue == null || e.oldValue instanceof Cls) &&
+      (e.newValue == null || e.newValue instanceof Cls)),
+  });
+}

package/src/diff/diff-renderer.js

@@ -125,7 +125,10 @@ function renderConceptLevel(diff, colors) {
   lines.push(...renderListDiff('Sources', diff.sources, colors, itemLabel));
   lines.push(...renderListDiff('Dates', diff.dates, colors, itemLabel));
   lines.push(...renderListDiff('Related', diff.relatedConcepts, colors, itemLabel));
-  lines.push(...renderListDiff('Partitive relations', diff.partitiveRelations ?? diff.partitiveHyperedges, colors, relationLabel));
+  // Unified n-ary relations section. Replaces the per-type sections
+  // (Partitive relations, Generic relations) — the underlying diff
+  // is a single ListDiff over the unified .relations array.
+  lines.push(...renderListDiff('N-ary relations', diff.relations, colors, relationLabel));
   lines.push(...renderListDiff('Groups', diff.groups, colors, itemLabel));
   lines.push(...renderListDiff('Sections', diff.sections, colors, itemLabel));
   lines.push(...renderListDiff('Tags', diff.tags, colors, itemLabel));
@@ -203,8 +206,11 @@ function relationLabel(r) {
   if (!r) return '?';
   const c = r.comprehensive;
   const head = c?.id ?? c?.source ?? c?.text ?? '?';
-  const partitives = Array.isArray(r.partitives)
-    ? r.partitives.map(m => {
+  // PartitiveRelation exposes .partitives as the wire alias for
+  // .members; GenericRelation uses .members directly. Read both.
+  const members = Array.isArray(r.partitives) ? r.partitives : r.members;
+  const memberText = Array.isArray(members)
+    ? members.map(m => {
         const ref = m?.ref ?? m ?? {};
         let tail = '';
         const mult = resolveMultiplicity(m);
@@ -217,7 +223,8 @@ function relationLabel(r) {
   const criterion = r.criterion
     ? ` / ${Object.values(r.criterion)[0] ?? ''}`
     : '';
-  return `${head} → {${partitives}}${completeness}${criterion}`;
+  const typeTag = r?.constructor?.name === 'GenericRelation' ? 'GEN ' : '';
+  return `${typeTag}${head} → {${memberText}}${completeness}${criterion}`;
 }
 
 // Aggregate multiplicity + delimiting stats across a concept's

package/src/models/concept.js

@@ -3,6 +3,9 @@ import { LocalizedConcept } from './localized-concept.js';
 import { RelatedConcept } from './related-concept.js';
 import { PartitiveHyperedge } from './partitive-hyperedge.js';
 import { PartitiveRelation } from './partitive-relation.js';
+import { GenericRelation } from './generic-relation.js';
+import { AbstractNaryRelation } from './abstract-nary-relation.js';
+import { TYPE_TO_CLASS } from './relation-type-registry.js';
 import { migrateHyperedgeToRelation } from '../migration/partitive-relation-migrator.js';
 import { ConceptReference } from './concept-reference.js';
 import { ConceptDate } from './concept-date.js';
@@ -34,12 +37,18 @@ export class Concept extends GlossaristModel {
     this._cache = {};
 
     this.relatedConcepts = _mapInstances(data.relatedConcepts ?? data.related ?? data.related_concepts ?? [], RelatedConcept);
-    this.partitiveRelations = _resolvePartitiveRelations(data);
-    // Backward-compat alias: v1 callers reading .partitiveHyperedges
-    // get the v2 relations (the v1 model is preserved at
-    // ../partitive-hyperedge.js for direct instantiation, but Concept
-    // exposes only v2).
-    this.partitiveHyperedges = this.partitiveRelations;
+
+    // Unified n-ary relations array. Both PartitiveRelation and
+    // GenericRelation live here. Adding a new n-ary type (Sequential,
+    // Associative) = adding to _resolveNaryRelations, not editing
+    // Concept, parser, serializer, diff, patch, or renderer.
+    //
+    // Backward-compat getters (.partitiveRelations, .partitiveHyperedges,
+    // .genericRelations) filter this single array by type. Callers that
+    // use the typed getters see the same behavior; new callers should
+    // iterate .relations directly and dispatch via instanceof.
+    this.relations = _resolveNaryRelations(data);
+
     this.domains = _normalizeDomains(data.domains, data.groups);
     this.groups = Array.isArray(data.groups)
       ? data.groups.map(g => typeof g === 'string' ? g : (g?.id ?? g?.sectionId ?? null)).filter(Boolean)
@@ -63,6 +72,17 @@ export class Concept extends GlossaristModel {
 
   get termid() { return this.id; }
 
+  // Typed getters that filter the unified relations array. Backward
+  // compat for callers that read .partitiveRelations directly.
+  get partitiveRelations() {
+    return this.relations.filter(r => r instanceof PartitiveRelation);
+  }
+  get genericRelations() {
+    return this.relations.filter(r => r instanceof GenericRelation);
+  }
+  // v1 alias
+  get partitiveHyperedges() { return this.partitiveRelations; }
+
   get languages() {
     return Object.keys(this._rawLocalizations);
   }
@@ -202,8 +222,16 @@ export class Concept extends GlossaristModel {
     if (this.relatedConcepts.length > 0) {
       obj.related = this.relatedConcepts.map(rc => rc.toJSON());
     }
-    if (this.partitiveRelations.length > 0) {
-      obj.partitive_relations = this.partitiveRelations.map(r => r.toJSON());
+    // Emit typed wire keys from the unified relations array.
+    // Each relation type gets its own wire key so existing consumers
+    // see no wire-shape change.
+    const partitiveRels = this.relations.filter(r => r instanceof PartitiveRelation);
+    const genericRels = this.relations.filter(r => r instanceof GenericRelation);
+    if (partitiveRels.length > 0) {
+      obj.partitive_relations = partitiveRels.map(r => r.toJSON());
+    }
+    if (genericRels.length > 0) {
+      obj.generic_relations = genericRels.map(r => r.toJSON());
     }
     if (this.domains.length > 0) {
       obj.domains = this.domains.map(d => d.toJSON());
@@ -234,31 +262,72 @@ function _mapInstances(arr, Cls) {
   return arr.map(item => item instanceof Cls ? item : new Cls(item));
 }
 
-// Resolve partitive relations from any of three input shapes:
-//   1. data.partitiveRelations (v2, preferred)
-//   2. data.partitive_relations (v2 wire name)
+// Resolve the unified n-ary relations array from any input shape.
+// Order of precedence:
+//   1. data.relations (preferred unified shape — already typed instances
+//      or hashes carrying a `type` discriminator)
+//   2. data.partitiveRelations / data.partitive_relations (v2 typed)
+//      + data.genericRelations / data.generic_relations (v2 typed)
 //   3. data.partitiveHyperedges / data.partitive_hyperedges (v1, migrated)
 //
-// v1 input is auto-migrated to v2 via the migrator. v1 instances
-// already constructed (rare — only direct callers) are migrated field
-// by field. The parser produces plain hashes so the common path is (3).
-function _resolvePartitiveRelations(data) {
-  if (Array.isArray(data.partitiveRelations)) {
-    return data.partitiveRelations.map(r =>
-      r instanceof PartitiveRelation ? r : new PartitiveRelation(r));
+// Hash dispatch uses TYPE_TO_CLASS from relation-type-registry.js —
+// the single source of truth shared with the per-file loader.
+//
+// Adding a new n-ary relation type (Sequential, Associative, …) means
+// one entry in TYPE_TO_CLASS plus one new class — Concept, parser,
+// serializer, diff, patch, and renderer do not change.
+function _resolveNaryRelations(data) {
+  if (Array.isArray(data.relations)) {
+    return data.relations
+      .map(r => _coerceRelation(r))
+      .filter(r => r != null);
+  }
+
+  const out = [];
+
+  const v2Partitive = data.partitiveRelations ?? data.partitive_relations;
+  if (Array.isArray(v2Partitive)) {
+    for (const r of v2Partitive) {
+      const coerced = _coerceRelation(r, PartitiveRelation);
+      if (coerced) out.push(coerced);
+    }
   }
-  if (Array.isArray(data.partitive_relations)) {
-    return data.partitive_relations.map(r => new PartitiveRelation(r));
+
+  const v2Generic = data.genericRelations ?? data.generic_relations;
+  if (Array.isArray(v2Generic)) {
+    for (const r of v2Generic) {
+      const coerced = _coerceRelation(r, GenericRelation);
+      if (coerced) out.push(coerced);
+    }
   }
+
   const v1 = data.partitiveHyperedges ?? data.partitive_hyperedges;
   if (Array.isArray(v1)) {
-    return v1
-      .map(h => h instanceof PartitiveHyperedge ? h.toJSON() : h)
-      .map(migrateHyperedgeToRelation)
-      .filter(h => h != null)
-      .map(h => new PartitiveRelation(h));
+    for (const h of v1) {
+      const hash = h instanceof PartitiveHyperedge ? h.toJSON() : h;
+      const migrated = migrateHyperedgeToRelation(hash);
+      if (migrated) out.push(new PartitiveRelation(migrated));
+    }
   }
-  return [];
+
+  return out;
+}
+
+function _coerceRelation(value, fallbackClass) {
+  if (value == null) return null;
+  if (value instanceof AbstractNaryRelation) return value;
+
+  const hash = typeof value.toJSON === 'function' ? value.toJSON() : value;
+  const Cls = _classForHash(hash) ?? fallbackClass;
+  if (!Cls) return null;
+  return new Cls(hash);
+}
+
+function _classForHash(hash) {
+  if (!hash || typeof hash !== 'object') return null;
+  const type = hash.type;
+  if (typeof type !== 'string') return null;
+  return TYPE_TO_CLASS[type] ?? null;
 }
 
 const CONCEPT_WIRE_NAMES = Object.freeze({

package/src/models/relation-loader.js

@@ -17,18 +17,16 @@
 
 import { readdirSync, readFileSync, existsSync } from 'node:fs';
 import * as yaml from 'js-yaml';
-import { PartitiveRelation } from './partitive-relation.js';
-import { GenericRelation } from './generic-relation.js';
+import { TYPE_TO_CLASS } from './relation-type-registry.js';
 
 /**
- * Per-type class dispatch. Keys are the `type` field of the relation
- * file. Adding a new relation type (e.g. AssociativeRelation) means
- * one entry here plus one new class.
+ * Per-type class dispatch. Re-exported from the registry so the
+ * loader's old `TYPE_TO_CLASS` import path keeps working. The
+ * registry is the single source of truth — adding a relation type
+ * there makes it available to both the loader and Concept's
+ * unified relations array.
  */
-export const TYPE_TO_CLASS = Object.freeze({
-  partitive_relation: PartitiveRelation,
-  generic_relation: GenericRelation,
-});
+export { TYPE_TO_CLASS };
 
 /**
  * Thrown by `loadAll` when a relation file has an unknown `type`,

package/src/models/relation-type-registry.js

@@ -0,0 +1,25 @@
+// N-ary relation type registry. Single source of truth for the
+// `type` → class dispatch used by the parser, the per-file loader,
+// and Concept's unified relations resolver.
+//
+// Adding a new n-ary relation type (Sequential, Associative, …)
+// = one entry here plus one new class. Nothing else changes:
+// not Concept, not parser, not serializer, not diff, not patch,
+// not renderer.
+//
+// Lives in its own module (not relation-loader.js) because the loader
+// pulls in node:fs, which is off-limits on the browser-gcr path that
+// transitively imports this registry via Concept.
+
+import { PartitiveRelation } from './partitive-relation.js';
+import { GenericRelation } from './generic-relation.js';
+
+export const TYPE_TO_CLASS = Object.freeze({
+  partitive_relation: PartitiveRelation,
+  generic_relation: GenericRelation,
+});
+
+export function classForRelationType(type) {
+  if (typeof type !== 'string') return null;
+  return TYPE_TO_CLASS[type] ?? null;
+}