glossarist 0.4.31 → 0.4.33

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "glossarist",
-  "version": "0.4.31",
+  "version": "0.4.33",
   "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

@@ -1,19 +1,41 @@
 import * as yaml from 'js-yaml';
 import { Concept } from './models/concept.js';
 import { RelatedConcept } from './models/related-concept.js';
+import { HyperedgeRegistry } from './models/hyperedge-registry.js';
 import { migrateHyperedgeToRelation } from './migration/partitive-relation-migrator.js';
 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 set is derived from
+// HyperedgeRegistry — every registered hyperedge class contributes
+// its wireKey and any v1WireKeys to the reserved set. Adding a new
+// hyperedge type means the parser reserves its wire key automatically;
+// no edits here.
 const STRUCTURAL_KEYS = new Set([
   'termid', 'term', 'figures', 'tables', 'formulas',
-  'partitive_hyperedges', 'partitiveHyperedges',
-  'partitive_relations', 'partitiveRelations',
+  'related', 'relatedConcepts',
+  'relations',
+  ..._registryStructuralKeys(),
 ]);
 
+function _registryStructuralKeys() {
+  const out = [];
+  for (const cls of HyperedgeRegistry.allClasses()) {
+    out.push(cls.wireKey);
+    out.push(_camelCase(cls.wireKey));
+    for (const k of cls.v1WireKeys ?? []) {
+      out.push(k);
+      out.push(_camelCase(k));
+    }
+  }
+  return out;
+}
+
+function _camelCase(s) {
+  if (typeof s !== 'string' || !s.includes('_')) return s;
+  return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+}
+
 export class ConceptParser {
   parse(raw, context) {
     const label = context ?? 'concept';
@@ -67,7 +89,7 @@ export class ConceptParser {
       figures: doc.figures,
       tables: doc.tables,
       formulas: doc.formulas,
-      partitiveRelations: _resolvePartitiveData(doc),
+      relations: _resolveHyperedgeData(doc),
       raw: doc,
     });
   }
@@ -84,14 +106,23 @@ export class ConceptParser {
       localizations[lang] = lcData;
     }
 
-    assertConceptLevelOnly(mc, ['related', 'partitive_relations', 'partitive_hyperedges']);
+    // The hyperedge wire keys are reserved at concept level (top-level
+    // of the managed concept YAML), not under data:. Derive the list
+    // from the registry so adding a type doesn't require an edit here.
+    const conceptLevelOnlyKeys = [
+      'related',
+      'relations',
+      ...HyperedgeRegistry.allWireAndLegacyKeys(),
+    ];
+
+    assertConceptLevelOnly(mc, conceptLevelOnlyKeys);
 
     return new Concept({
       id: String(mc.data.identifier),
       term: null,
       localizations,
       related: _normalizeRelated(mc.related),
-      partitiveRelations: _resolvePartitiveData(mc),
+      relations: _resolveHyperedgeData(mc),
       domains: mc.data.domains,
       groups: mc.data.groups,
       dates: mc.dates ?? mc.data?.dates,
@@ -109,7 +140,7 @@ export class ConceptParser {
 function assertConceptLevelOnly(mc, keys) {
   const conceptId = mc?.data?.identifier ?? '<unknown>';
   for (const key of keys) {
-    const camelKey = key.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
+    const camelKey = _camelCase(key);
     if (mc?.data?.[key] != null && mc[key] == null && mc[camelKey] == null) {
       throw new InvalidInputError(
         `'${key}' must live at concept level (top-level of the managed ` +
@@ -121,26 +152,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 hyperedge data from any input shape into a single unified
+// array. Iterates HyperedgeRegistry — for each registered class:
+//   - read its wireKey from the container (e.g. partitive_relations)
+//   - read any v1WireKeys (e.g. partitive_hyperedges) and migrate
+//   - tag each entry with the class's typeTag
+//
+// Returns null when no relation data is present, so Concept's
+// `_resolveHyperedges` falls back to the empty-array default.
 //
-// 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;
-
-  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);
+// Adding a new hyperedge type means: declare it on a class, register.
+// The parser picks it up automatically — no edits here.
+function _resolveHyperedgeData(container) {
+  if (!container) return null;
+
+  if (Array.isArray(container.relations)) {
+    return container.relations;
+  }
+
+  const out = [];
+
+  for (const cls of HyperedgeRegistry.allClasses()) {
+    // v2 wire key (e.g. partitive_relations)
+    const arr = container[cls.wireKey] ?? container[_camelCase(cls.wireKey)];
+    if (Array.isArray(arr)) {
+      for (const r of arr) {
+        const tagged = _addTypeIfMissing(r, cls.typeTag);
+        if (tagged != null) out.push(tagged);
+      }
+    }
+
+    // v1 legacy wire keys (e.g. partitive_hyperedges) — migrated.
+    // The migration helper produces a v2 hash; we tag it with the
+    // typeTag so Concept's registry dispatch finds the right class.
+    for (const v1Key of cls.v1WireKeys ?? []) {
+      const v1Arr = container[v1Key] ?? container[_camelCase(v1Key)];
+      if (!Array.isArray(v1Arr)) continue;
+      for (const h of v1Arr) {
+        const hash = h?.toJSON && typeof h.toJSON === 'function' ? h.toJSON() : h;
+        const migrated = migrateHyperedgeToRelation(hash);
+        if (migrated) out.push({ ...migrated, type: cls.typeTag });
+      }
+    }
+  }
+
+  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-reader.js

@@ -2,6 +2,7 @@ import fs from 'fs';
 import path from 'path';
 import * as yaml from 'js-yaml';
 import { conceptParser } from './concept-parser.js';
+import { RelationLoader } from './models/relation-loader.js';
 import { naturalSort } from './sort.js';
 import { InvalidInputError } from './errors.js';
 import { Register } from './models/register.js';
@@ -13,7 +14,15 @@ function assertDir(dir, fnName) {
 }
 
 /**
- * Read all v2 glossarist concept YAML files from a directory.
+ * Read all v2 glossarist concept YAML files from a directory, then
+ * merge in any per-file hyperedge YAMLs from `<dir>/relations/`.
+ *
+ * Per-file hyperedge storage (concept-model PR #83): each file at
+ * `relations/<comprehensive-id>/<slug>.yaml` is loaded and merged
+ * into the corresponding Concept.relations array. If the directory
+ * does not exist, no per-file hyperedges are loaded (concepts still
+ * get any inline hyperedges from their own YAML).
+ *
  * @param {string} dir - path to directory containing concept YAML files
  * @returns {import('./models/concept.js').Concept[]}
  * @throws {InvalidInputError} if dir is missing or empty
@@ -36,11 +45,16 @@ export function readConcepts(dir) {
       concepts.push(concept);
     }
   }
+
+  _mergePerFileHyperedges(dir, concepts);
   return concepts;
 }
 
 /**
- * Read a single concept file by ID from a directory.
+ * Read a single concept file by ID from a directory, then merge in
+ * any per-file hyperedge YAMLs for that concept from
+ * `<dir>/relations/<id>/`.
+ *
  * @param {string} dir - path to directory containing concept YAML files
  * @param {string} id - concept identifier (filename without .yaml)
  * @returns {import('./models/concept.js').Concept | null}
@@ -58,7 +72,49 @@ export function readConcept(dir, id) {
   const filePath = path.join(dir, `${id}.yaml`);
   if (!fs.existsSync(filePath)) return null;
   const raw = fs.readFileSync(filePath, 'utf8');
-  return conceptParser.parse(raw, `${id}.yaml`);
+  const concept = conceptParser.parse(raw, `${id}.yaml`);
+  _mergePerFileHyperedges(dir, [concept]);
+  return concept;
+}
+
+// Load `relations/` directory and merge per-file hyperedges into the
+// matching Concept.relations arrays. Concepts are matched by id.
+// Inline hyperedges from the concept YAML are preserved alongside the
+// per-file ones (audit: this is the contract — the two sources are
+// additive, not exclusive).
+//
+// Throws if a per-file hyperedge fails to construct (bad YAML, missing
+// type, invalid members) — surfaces corruption loudly per the
+// RelationLoader contract.
+function _mergePerFileHyperedges(dir, concepts) {
+  const relationsDir = path.join(dir, 'relations');
+  if (!fs.existsSync(relationsDir)) return;
+
+  const byComprehensive = RelationLoader.loadAll(relationsDir);
+  if (byComprehensive.size === 0) return;
+
+  for (const concept of concepts) {
+    const rels = byComprehensive.get(concept.id);
+    if (!rels || rels.length === 0) continue;
+    // Merge per-file hyperedges with any inline ones from the concept
+    // YAML. Per-file wins on identity collision — they're the newer,
+    // more authoritative source.
+    const inline = concept.relations;
+    const merged = [...inline];
+    for (const r of rels) {
+      const exists = inline.some(x => _sameHyperedge(x, r));
+      if (!exists) merged.push(r);
+    }
+    concept.relations = merged;
+  }
+}
+
+function _sameHyperedge(a, b) {
+  const aCls = a?.constructor;
+  const bCls = b?.constructor;
+  if (aCls !== bCls) return false;
+  if (typeof aCls.identityOf !== 'function') return false;
+  return aCls.identityOf(a) === bCls.identityOf(b);
 }
 
 /**

package/src/concept-serializer.js

@@ -1,18 +1,30 @@
 import * as yaml from 'js-yaml';
+import { PartitiveHyperedge } from './models/partitive-hyperedge.js';
+import { GenericHyperedge } from './models/generic-hyperedge.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 PartitiveHyperedge);
+  const genericRels = concept.relations.filter(r => r instanceof GenericHyperedge);
+  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 { PartitiveHyperedge } from '../models/partitive-hyperedge.js';
+import { GenericHyperedge } from '../models/generic-hyperedge.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 (PartitiveHyperedge + GenericHyperedge). */
+  get relations() { return this._relations; }
+  /**
+   * Filtered view of `relations` containing only PartitiveHyperedge
+   * entries. Backward compat for callers that read .partitiveRelations
+   * directly on a ConceptLevelDiff.
+   */
+  get partitiveRelations() {
+    return filterListDiffByType(this._relations, PartitiveHyperedge);
+  }
+  /** @deprecated use .relations */ get partitiveHyperedges() { return this.partitiveRelations; }
+  /**
+   * Filtered view of `relations` containing only GenericHyperedge
+   * entries. Backward compat for callers that read .genericRelations
+   * directly on a ConceptLevelDiff.
+   */
+  get genericRelations() {
+    return filterListDiffByType(this._relations, GenericHyperedge);
+  }
   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 PartitiveHyperedge
+// and GenericHyperedge (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

@@ -4,7 +4,7 @@ import { ConceptDate } from '../models/concept-date.js';
 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 { HyperedgeRegistry } from '../models/hyperedge-registry.js';
 import { Added, Removed, Changed } from './change.js';
 import { ListDiff } from './list-diff.js';
 import { TextDiff, TextHunk } from './text-diff.js';
@@ -67,9 +67,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 +106,25 @@ 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 hyperedge diff → typed wire keys. Iterate the registry;
+  // for each registered class, partition the unified diff by that
+  // class and apply to the class's wireKey. Adding a new hyperedge
+  // type means this loop picks it up automatically — no edits here.
+  for (const cls of HyperedgeRegistry.allClasses()) {
+    const partition = partitionListDiff(conceptDiff.relations, cls);
+    if (!partition.hasChanges) continue;
+    const wireKey = cls.wireKey;
+    // v1 wire keys (partitive_hyperedges) on the input are migrated
+    // to v2 wire key here: read from either, write to v2 only.
+    const v1ReadKeys = cls.v1WireKeys ?? [];
+    const existing = v1ReadKeys
+      .map(k => json[k])
+      .find(arr => Array.isArray(arr)) ?? json[wireKey] ?? [];
+    json[wireKey] = applyListPatch(existing, partition, cls.identityOf);
+    for (const k of v1ReadKeys) {
+      if (json[k] != null && json[wireKey] != null) delete json[k];
+    }
   }
 
   json.tags = applyListPatch(json.tags ?? [], conceptDiff.tags);
@@ -233,3 +241,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 PartitiveHyperedge, new is GenericHyperedge) 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 => {
+  // PartitiveHyperedge exposes .partitives as the wire alias for
+  // .members; GenericHyperedge 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,13 @@ function relationLabel(r) {
   const criterion = r.criterion
     ? ` / ${Object.values(r.criterion)[0] ?? ''}`
     : '';
-  return `${head} → {${partitives}}${completeness}${criterion}`;
+  // Each hyperedge leaf declares a short static kindLabel (PART, GEN, …).
+  // Read it via the constructor so adding a new hyperedge type needs no
+  // renderer edit. The blank-string default keeps backward-compat with
+  // any AbstractHyperedge subclass that doesn't declare kindLabel.
+  const kindLabel = r?.constructor?.kindLabel ?? '';
+  const typeTag = kindLabel ? `${kindLabel} ` : '';
+  return `${typeTag}${head} → {${memberText}}${completeness}${criterion}`;
 }
 
 // Aggregate multiplicity + delimiting stats across a concept's

package/src/index.js

@@ -63,7 +63,8 @@ export {
   fetchLocalizedString, localizedStringIsEmpty, localizedStringIsPresent,
   GcrMetadata, GcrStatistics,
   RELATIONSHIP_TYPES, DESIGNATION_RELATIONSHIP_TYPES, DATE_TYPES,
-  PartitiveHyperedge, PARTITIVE_ENUMERATION, PARTITIVE_ENUMERATION_VALUES,
+  PartitiveHyperedge,
+  PARTITIVE_ENUMERATION, PARTITIVE_ENUMERATION_VALUES,
   PLURALITY_MARKER, PLURALITY_MARKER_VALUES,
 } from './models/index.js';
 

package/src/migration/partitive-relation-migrator.js

@@ -1,7 +1,7 @@
-// v1 → v2 PartitiveRelation migration.
+// v1 → v2 PartitiveHyperedge migration.
 //
 // Pure function: takes a v1 PartitiveHyperedge hash, returns a v2
-// PartitiveRelation hash. Idempotent. Used by the parser when loading
+// PartitiveHyperedge hash. Idempotent. Used by the parser when loading
 // legacy YAML; available as a public API for one-shot dataset migrations.
 //
 // Field mapping (per TODO.partitive-relation-v2 items 01–05 and the
@@ -69,7 +69,7 @@ export function migrateHyperedgeToRelation(v1Hash) {
 
   if (v1Hash.content != null) {
     out.migrationWarning = (out.migrationWarning ?? '') +
-      ` v1 'content' field was dropped (v2 PartitiveRelation carries no prose; ` +
+      ` v1 'content' field was dropped (v2 PartitiveHyperedge carries no prose; ` +
       `move valuable text to the comprehensive concept's notes).`;
   }
 

package/src/models/{abstract-nary-relation.js → abstract-hyperedge.js}

@@ -1,5 +1,5 @@
-// AbstractNaryRelation — shared base for n-ary concept-system
-// relations (PartitiveRelation, GenericRelation, future
+// AbstractHyperedge — shared base for n-ary concept-system
+// relations (PartitiveHyperedge, GenericHyperedge, future
 // SequentialRelation, AssociativeRelation).
 //
 // Carries the common shape:
@@ -20,7 +20,7 @@ import {
   isValidCompleteness,
 } from './completeness.js';
 
-export class AbstractNaryRelation extends GlossaristModel {
+export class AbstractHyperedge extends GlossaristModel {
   constructor(data = {}) {
     super();
     this.comprehensive = _ensureComprehensive(data.comprehensive);
@@ -62,7 +62,7 @@ function _ensureComprehensive(value) {
   const ref = value instanceof ConceptRef ? value : new ConceptRef(value ?? {});
   if (!ref.source && !ref.id && !ref.text) {
     throw new Error(
-      'AbstractNaryRelation.comprehensive must be a non-empty ConceptReference ' +
+      'AbstractHyperedge.comprehensive must be a non-empty ConceptReference ' +
       '(source, id, or text required)',
     );
   }