glossarist 0.4.31 → 0.4.33

package/src/models/completeness.js

@@ -1,4 +1,4 @@
-// Completeness — whether a PartitiveRelation's encoded partitives
+// Completeness — whether a PartitiveHyperedge's encoded partitives
 // constitute the whole comprehensive (complete) or only some of it
 // (partial).
 //

package/src/models/concept.js

@@ -2,7 +2,8 @@ import { GlossaristModel } from './base.js';
 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 { AbstractHyperedge } from './abstract-hyperedge.js';
+import { HyperedgeRegistry, groupHyperedgesByWireKey } from './hyperedge-registry.js';
 import { migrateHyperedgeToRelation } from '../migration/partitive-relation-migrator.js';
 import { ConceptReference } from './concept-reference.js';
 import { ConceptDate } from './concept-date.js';
@@ -34,12 +35,20 @@ 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 hyperedge array. Every n-ary relation (PartitiveHyperedge,
+    // GenericHyperedge, future TemporalHyperedge / AssociativeHyperedge /
+    // SequentialHyperedge) lives here. The single public API is
+    // `.relations`; external systems that need to filter by type use
+    // `concept.relations.filter(r => r instanceof X)` or dispatch via
+    // HyperedgeRegistry (preferred — see Phases 6 and 11).
+    //
+    // Throws on ambiguous input (caller passed both `relations` and any
+    // typed wire key) and on duplicate relations (same identity twice).
+    // Silent drop / silent dedupe are footguns the audit (C4, C6)
+    // flagged; explicit throws make corruption loud.
+    this.relations = _resolveHyperedges(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,18 @@ export class Concept extends GlossaristModel {
 
   get termid() { return this.id; }
 
+  // No typed projections. Use concept.relations directly and filter
+  // by instanceof, or dispatch via HyperedgeRegistry. The old
+  // .partitiveRelations / .genericRelations / .partitiveHyperedges
+  // getters were removed per TODO Phase 4 — they were footguns
+  // (audit C3: .partitiveHyperedges returned v2 instances but callers
+  // expected v1 shape; multiple validators silently no-op'd).
+  //
+  // Snippet migration guide:
+  //   concept.partitiveRelations      → concept.relations.filter(r => r instanceof PartitiveHyperedge)
+  //   concept.genericRelations        → concept.relations.filter(r => r instanceof GenericHyperedge)
+  //   concept.partitiveHyperedges     → concept.relations.filter(r => r instanceof PartitiveHyperedge)
+
   get languages() {
     return Object.keys(this._rawLocalizations);
   }
@@ -202,8 +223,13 @@ 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 per-type wire keys from the unified relations array,
+    // partitioned via HyperedgeRegistry. Adding a new hyperedge type
+    // means its wire key appears here automatically — no edits to
+    // Concept.toJSON.
+    const grouped = groupHyperedgesByWireKey(this.relations);
+    for (const [wireKey, rels] of Object.entries(grouped)) {
+      if (rels.length > 0) obj[wireKey] = rels.map(r => r.toJSON());
     }
     if (this.domains.length > 0) {
       obj.domains = this.domains.map(d => d.toJSON());
@@ -234,31 +260,147 @@ 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)
-//   3. data.partitiveHyperedges / data.partitive_hyperedges (v1, migrated)
+// Resolve the unified hyperedge array from any input shape.
+//
+// Three input categories are accepted; mixing them throws (audit C4 —
+// silent drop was a footgun):
+//
+//   1. data.relations               — preferred unified shape. Entries
+//                                     are typed instances or hashes
+//                                     carrying a `type` discriminator
+//                                     (looked up via HyperedgeRegistry).
+//   2. Per-type v2 wire keys        — one of HyperedgeRegistry.allWireKeys()
+//                                     (partitive_relations, generic_relations).
+//   3. Per-type v1 legacy keys      — declared on each class via
+//                                     `static v1WireKeys` (e.g.
+//                                     partitive_hyperedges → 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));
+// Adding a new hyperedge type means: declare the leaf class with its
+// metadata block, register it. Concept, parser, serializer, diff,
+// patch, renderer, RDF emitter do not change. (Phase 11 OCP contract.)
+function _resolveHyperedges(data) {
+  _assertNoAmbiguousInput(data);
+
+  if (Array.isArray(data.relations)) {
+    return _dedupeOrThrow(data.relations.map(r => _coerceHyperedge(r)).filter(r => r != null));
   }
-  if (Array.isArray(data.partitive_relations)) {
-    return data.partitive_relations.map(r => new PartitiveRelation(r));
+
+  const out = [];
+
+  for (const cls of HyperedgeRegistry.allClasses()) {
+    const arr = data[cls.wireKey] ?? data[_camelCase(cls.wireKey)];
+    if (!Array.isArray(arr)) continue;
+    for (const r of arr) {
+      const coerced = _coerceHyperedge(r, cls);
+      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 cls of HyperedgeRegistry.allClasses()) {
+    for (const v1Key of cls.v1WireKeys ?? []) {
+      const camelV1 = _camelCase(v1Key);
+      const arr = data[v1Key] ?? data[camelV1];
+      if (!Array.isArray(arr)) continue;
+      for (const h of arr) {
+        const migrated = _migrateV1Hash(cls, v1Key, h);
+        if (migrated) out.push(new cls(migrated));
+      }
+    }
   }
-  return [];
+
+  return _dedupeOrThrow(out);
+}
+
+// Audit C4: silent drop on mixed input is a footgun. Throw instead.
+// Allows `relations` alone, or any combination of typed keys alone —
+// but not both at once.
+function _assertNoAmbiguousInput(data) {
+  if (!Array.isArray(data.relations)) return;
+  const typedKeys = [];
+  for (const cls of HyperedgeRegistry.allClasses()) {
+    if (Array.isArray(data[cls.wireKey])) typedKeys.push(cls.wireKey);
+    const camelWire = _camelCase(cls.wireKey);
+    if (camelWire !== cls.wireKey && Array.isArray(data[camelWire])) {
+      typedKeys.push(camelWire);
+    }
+    for (const v1 of cls.v1WireKeys ?? []) {
+      if (Array.isArray(data[v1])) typedKeys.push(v1);
+      const camelV1 = _camelCase(v1);
+      if (camelV1 !== v1 && Array.isArray(data[camelV1])) typedKeys.push(camelV1);
+    }
+  }
+  if (typedKeys.length > 0) {
+    throw new Error(
+      `Concept input is ambiguous: pass either 'relations' (unified) ` +
+      `or typed wire keys (${typedKeys.join(', ')}), not both. ` +
+      ` Mixing them silently drops the typed keys, which has caused ` +
+      ` data loss in production (see audit C4).`,
+    );
+  }
+}
+
+// Audit C6: do NOT silently dedupe. Duplicate relations indicate a bug
+// in the caller; surface it. The identity function delegates to each
+// class's static identityOf (polymorphic — handles mixed types).
+function _dedupeOrThrow(relations) {
+  const seen = new Map();
+  for (const r of relations) {
+    const id = _hyperedgeIdentity(r);
+    if (seen.has(id)) {
+      throw new Error(
+        `Concept input has duplicate hyperedge (identity=${id}). ` +
+        `Passing the same relation twice is a bug — the parser and ` +
+        `serializer would silently emit it twice on disk. ` +
+        `Audit C6 requires we surface this loudly instead.`,
+      );
+    }
+    seen.set(id, r);
+  }
+  return relations;
+}
+
+function _hyperedgeIdentity(r) {
+  if (r == null) return '';
+  const Cls = r.constructor;
+  if (typeof Cls?.identityOf === 'function') {
+    return `${Cls.name}::${Cls.identityOf(r)}`;
+  }
+  return String(r);
+}
+
+function _coerceHyperedge(value, fallbackClass) {
+  if (value == null) return null;
+  if (value instanceof AbstractHyperedge) 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 HyperedgeRegistry.forTypeTag(type);
+}
+
+// v1 → v2 migration for hashes from legacy wire keys. Currently only
+// PartitiveHyperedge has v1 wire keys (partitive_hyperedges). Future
+// types extend this dispatch — but it lives here in the migration
+// helper, not in the model classes, since v1 is a legacy concern.
+function _migrateV1Hash(cls, v1Key, hash) {
+  if (cls === PartitiveHyperedge && v1Key === 'partitive_hyperedges') {
+    const normalized = hash;
+    return migrateHyperedgeToRelation(normalized);
+  }
+  return null;
+}
+
+// snake_case → camelCase
+function _camelCase(s) {
+  if (typeof s !== 'string' || !s.includes('_')) return s;
+  return s.replace(/_([a-z])/g, (_, c) => c.toUpperCase());
 }
 
 const CONCEPT_WIRE_NAMES = Object.freeze({

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

@@ -1,18 +1,28 @@
-// GenericRelation — an ISO 704 / ISO 1087-1 / ISO 12620 generic
+// GenericHyperedge — an ISO 704 / ISO 1087-1 / ISO 12620 generic
 // relation connecting a comprehensive concept (the genus) to two
 // or more specific concepts (the species) which together constitute
 // a decomposition by some criterion of subdivision.
 //
-// Mirror of PartitiveRelation. Multiple GenericRelations on the same
+// Mirror of PartitiveHyperedge. Multiple GenericRelations on the same
 // comprehensive distinguished by `criterion` is the OIML pattern
 // (5.1 measurement standard has 6 criterion groups).
 //
 // See docs/design/generic-relation.md (concept-model repo).
 
-import { AbstractNaryRelation } from './abstract-nary-relation.js';
+import { AbstractHyperedge } from './abstract-hyperedge.js';
 import { GenericMember } from './generic-member.js';
+import { HyperedgeRegistry } from './hyperedge-registry.js';
+
+export class GenericHyperedge extends AbstractHyperedge {
+  // Per-class metadata block — the OCP contract. See PartitiveHyperedge
+  // for field documentation.
+  static wireKey     = 'generic_relations';
+  static typeTag     = 'generic_relation';
+  static rdfType     = 'gloss:GenericRelation';
+  static memberClass = GenericMember;
+  static v1WireKeys  = [];
+  static kindLabel   = 'GEN';
 
-export class GenericRelation extends AbstractNaryRelation {
   constructor(data = {}) {
     super(data);
     this.members = data?.members == null
@@ -36,8 +46,10 @@ export class GenericRelation extends AbstractNaryRelation {
   }
 
   static fromJSON(data) {
-    return new GenericRelation(data);
+    return new GenericHyperedge(data);
   }
 }
 
-export default GenericRelation;
+export default GenericHyperedge;
+
+HyperedgeRegistry.register(GenericHyperedge);

package/src/models/generic-member.js

@@ -1,15 +1,15 @@
-// GenericMember — one member of a GenericRelation. Inherits the
-// ISO 704:2022 MECE shape from ConceptSystemMember. Declared as a
+// GenericMember — one member of a GenericHyperedge. Inherits the
+// ISO 704:2022 MECE shape from HyperedgeMember. Declared as a
 // distinct leaf class for type safety and to leave room for
 // generic-specific extensions.
 //
 // See docs/design/abstract-nary-relation.md and
 // docs/design/generic-relation.md (concept-model repo).
 
-import { ConceptSystemMember } from './concept-system-member.js';
+import { HyperedgeMember } from './hyperedge-member.js';
 
-export class GenericMember extends ConceptSystemMember {
-  // Inherits all attributes and validations from ConceptSystemMember.
+export class GenericMember extends HyperedgeMember {
+  // Inherits all attributes and validations from HyperedgeMember.
 }
 
 export default GenericMember;

package/src/models/hyperedge-index.js

@@ -0,0 +1,87 @@
+// HyperedgeIndex — directional index over a hyperedge set.
+//
+// A hyperedge is 1→N (one comprehensive, many members). The forward
+// query ("which hyperedges have X as comprehensive?") and the reverse
+// query ("which hyperedges have Y as a member?") are both useful. The
+// reverse query is the load-bearing one: OIML V 2-200:2010 concept
+// 5.13 is a member of one of 5.1's hyperedges AND the comprehensive
+// of its own 2 hyperedges — without an index, every "find hyperedges
+// mentioning X" turns into an O(N) walk over every hyperedge.
+//
+// The index is built on demand from a flat hyperedge list (typically
+// Concept.relations or the union of all concepts' relations in a
+// collection). It does not store state on Concept — Concept stays a
+// simple value object.
+//
+// Identity key matches HyperedgeRegistry / ConceptRef conventions:
+//   `${source}:${id}`   (empty source or id is rejected)
+//
+// See TODO Phase 9.
+
+export class HyperedgeIndex {
+  constructor(hyperedges = []) {
+    this._byComprehensive = new Map();
+    this._byMember = new Map();
+
+    for (const h of hyperedges) {
+      const cKey = _qualifiedId(h?.comprehensive);
+      if (cKey) _addToMapList(this._byComprehensive, cKey, h);
+      const members = Array.isArray(h?.members) ? h.members : [];
+      for (const m of members) {
+        const mKey = _qualifiedId(m?.ref ?? m);
+        if (mKey) _addToMapList(this._byMember, mKey, h);
+      }
+    }
+  }
+
+  // Hyperedges where the given concept is the comprehensive (the "1" side).
+  forComprehensive(qualifiedId) {
+    return this._byComprehensive.get(qualifiedId) ?? [];
+  }
+
+  // Hyperedges where the given concept appears as a member (the "many" side).
+  forMember(qualifiedId) {
+    return this._byMember.get(qualifiedId) ?? [];
+  }
+
+  // All concepts that appear as a comprehensive in any indexed hyperedge.
+  comprehensives() {
+    return [...this._byComprehensive.keys()];
+  }
+
+  // All concepts that appear as a member in any indexed hyperedge.
+  members() {
+    return [...this._byMember.keys()];
+  }
+
+  get size() {
+    return this._byComprehensive.size;
+  }
+}
+
+// Build a HyperedgeIndex across multiple Concepts' relations arrays
+// (a dataset-wide view). Each Concept contributes its own .relations.
+// Helper for the most common pattern: index once at collection load,
+// query many times.
+export function buildDatasetIndex(concepts = []) {
+  const all = [];
+  for (const concept of concepts) {
+    for (const h of concept.relations ?? []) {
+      all.push(h);
+    }
+  }
+  return new HyperedgeIndex(all);
+}
+
+function _qualifiedId(ref) {
+  if (!ref) return null;
+  const source = ref.source ?? '';
+  const id = ref.id ?? '';
+  if (!source && !id) return null;
+  return `${source}:${id}`;
+}
+
+function _addToMapList(map, key, value) {
+  if (!map.has(key)) map.set(key, []);
+  map.get(key).push(value);
+}

package/src/models/{concept-system-member.js → hyperedge-member.js}

@@ -1,4 +1,4 @@
-// ConceptSystemMember — abstract base shape for members of any
+// HyperedgeMember — abstract base shape for members of any
 // n-ary concept-system relation (PartitiveMember, GenericMember,
 // future AssociativeMember, SequentialMember).
 //
@@ -18,20 +18,13 @@ import {
   isValidPresence,
 } from './partitive-presence.js';
 import {
-  PARTITIVE_COUNT,
   PARTITIVE_COUNT_VALUES,
   DEFAULT_COUNT,
   isValidCount,
 } from './partitive-count.js';
+import { multiplicityFromPair } from './multiplicity.js';
 
-// Module-private (not exported). Single source of truth for the
-// invalid (presence, count) combination rejected at construction.
-const INVALID_PRESENCE_COUNT_COMBO = {
-  presence: PARTITIVE_PRESENCE.OPTIONAL,
-  count: PARTITIVE_COUNT.AT_LEAST_ONE,
-};
-
-export class ConceptSystemMember extends GlossaristModel {
+export class HyperedgeMember extends GlossaristModel {
   constructor(data = {}) {
     super();
     this.ref = _ensureRef(data.ref);
@@ -47,7 +40,7 @@ export class ConceptSystemMember extends GlossaristModel {
   get isDelimiting() { return this.is_delimiting === true; }
 
   identity() {
-    return ConceptSystemMember.identityOf(this);
+    return HyperedgeMember.identityOf(this);
   }
 
   toJSON() {
@@ -65,7 +58,7 @@ export class ConceptSystemMember extends GlossaristModel {
   }
 
   static fromJSON(data) {
-    return new ConceptSystemMember(data);
+    return new HyperedgeMember(data);
   }
 }
 
@@ -73,7 +66,7 @@ function _ensureRef(value) {
   const ref = value instanceof ConceptRef ? value : new ConceptRef(value ?? {});
   if (!ref.source && !ref.id && !ref.text) {
     throw new Error(
-      'ConceptSystemMember.ref must be a non-empty ConceptRef ' +
+      'HyperedgeMember.ref must be a non-empty ConceptRef ' +
       '(source, id, or text required)',
     );
   }
@@ -106,21 +99,16 @@ function _resolveDelimiting(value) {
   if (value == null) return false;
   if (typeof value !== 'boolean') {
     throw new Error(
-      `ConceptSystemMember.is_delimiting must be boolean; got ${typeof value}`,
+      `HyperedgeMember.is_delimiting must be boolean; got ${typeof value}`,
     );
   }
   return value;
 }
 
 function _assertValidPair(presence, count) {
-  if (
-    presence === INVALID_PRESENCE_COUNT_COMBO.presence &&
-    count === INVALID_PRESENCE_COUNT_COMBO.count
-  ) {
-    throw new Error(
-      'ConceptSystemMember presence=optional + count=at_least_one is invalid — ' +
-      'it collapses to optional + multiple (zero or more). ' +
-      'Use presence: optional, count: multiple instead.',
-    );
-  }
+  // Delegate to the multiplicity SSOT (Phase 8 of TODO.abstract-hyperedge).
+  // The canonical error string lives in one place: multiplicity.js.
+  // Calling multiplicityFromPair throws on the invalid combination;
+  // we don't need to duplicate the error message here.
+  multiplicityFromPair(presence, count);
 }

package/src/models/hyperedge-registry.js

@@ -0,0 +1,115 @@
+// HyperedgeRegistry — single source of truth for hyperedge type dispatch.
+//
+// Each hyperedge leaf class (PartitiveHyperedge, GenericHyperedge, future
+// TemporalHyperedge, AssociativeHyperedge, etc.) registers itself once at
+// module load. External systems (parser, serializer, diff, RDF emitter,
+// validators) read from this registry instead of branching on instanceof
+// or hardcoding per-type tables.
+//
+// Adding a new hyperedge type:
+//   1. Declare the leaf class with the 6-field metadata block
+//      (wireKey, typeTag, rdfType, memberClass, v1WireKeys, kindLabel).
+//   2. Call HyperedgeRegistry.register(MyClass) at the bottom of the file.
+//
+// Nothing else in the codebase changes. That is the OCP contract.
+//
+// Three indexes support three lookup patterns:
+//   byWireKey  — parser/serializer/diff-patch dispatch by YAML/JSON key
+//   byTypeTag  — per-file loader dispatch by `type: ...` discriminator
+//   byRdfType  — RDF emitter dispatch by ontology class IRI
+//
+// The abstract base (AbstractHyperedge) has no wireKey and is skipped
+// by register() — it cannot be instantiated through the registry.
+
+class HyperedgeRegistry {
+  static _byWireKey = new Map();
+  static _byTypeTag = new Map();
+  static _byRdfType = new Map();
+
+  static register(cls) {
+    if (!cls || !cls.wireKey || !cls.typeTag || !cls.rdfType) return false;
+    if (this._byWireKey.has(cls.wireKey)) {
+      throw new Error(
+        `HyperedgeRegistry: duplicate wireKey '${cls.wireKey}' ` +
+        `(trying to register ${cls.name}; already registered to ` +
+        `${this._byWireKey.get(cls.wireKey).name})`,
+      );
+    }
+    if (this._byTypeTag.has(cls.typeTag)) {
+      throw new Error(
+        `HyperedgeRegistry: duplicate typeTag '${cls.typeTag}' ` +
+        `(trying to register ${cls.name})`,
+      );
+    }
+    if (this._byRdfType.has(cls.rdfType)) {
+      throw new Error(
+        `HyperedgeRegistry: duplicate rdfType '${cls.rdfType}' ` +
+        `(trying to register ${cls.name})`,
+      );
+    }
+    this._byWireKey.set(cls.wireKey, cls);
+    this._byTypeTag.set(cls.typeTag, cls);
+    this._byRdfType.set(cls.rdfType, cls);
+    return true;
+  }
+
+  // Test-only. Removes a class from all three indexes. Used by the OCP
+  // spec to clean up mock types it adds during a test run.
+  static unregister(cls) {
+    if (!cls) return false;
+    const r1 = this._byWireKey.delete(cls.wireKey);
+    const r2 = this._byTypeTag.delete(cls.typeTag);
+    const r3 = this._byRdfType.delete(cls.rdfType);
+    return r1 || r2 || r3;
+  }
+
+  static forWireKey(key) { return this._byWireKey.get(key) ?? null; }
+  static forTypeTag(tag) { return this._byTypeTag.get(tag) ?? null; }
+  static forRdfType(type) { return this._byRdfType.get(type) ?? null; }
+
+  static allClasses() {
+    // Dedup in case the same class is reachable via multiple indexes.
+    const seen = new Set();
+    const out = [];
+    for (const cls of this._byTypeTag.values()) {
+      if (!seen.has(cls)) {
+        seen.add(cls);
+        out.push(cls);
+      }
+    }
+    return out;
+  }
+
+  static allWireKeys()  { return [...this._byWireKey.keys()]; }
+  static allTypeTags()  { return [...this._byTypeTag.keys()]; }
+
+  // Snapshot of every registered wire-shape identifier (v2 wireKey plus
+  // any v1 legacy keys). Used by the parser to reserve STRUCTURAL_KEYS
+  // and to know which top-level YAML keys to walk for hyperedge data.
+  static allWireAndLegacyKeys() {
+    const out = [];
+    for (const cls of this.allClasses()) {
+      out.push(cls.wireKey);
+      for (const k of cls.v1WireKeys ?? []) out.push(k);
+    }
+    return out;
+  }
+}
+
+// Helper: partition a unified hyperedge array by wire key. Used by
+// Concept.toJSON, ConceptSerializer, and diff-patch to emit per-type
+// wire keys without per-type branching in those files. Adding a new
+// hyperedge type "just works" because the group is keyed by the
+// class's static wireKey.
+export function groupHyperedgesByWireKey(hyperedges) {
+  const out = {};
+  for (const h of hyperedges ?? []) {
+    const key = h?.constructor?.wireKey;
+    if (!key) continue;
+    if (!out[key]) out[key] = [];
+    out[key].push(h);
+  }
+  return out;
+}
+
+export { HyperedgeRegistry };