glossarist 0.4.32 → 0.4.33

package/src/models/concept.js

@@ -2,10 +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 { GenericRelation } from './generic-relation.js';
-import { AbstractNaryRelation } from './abstract-nary-relation.js';
-import { TYPE_TO_CLASS } from './relation-type-registry.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';
@@ -38,16 +36,18 @@ export class Concept extends GlossaristModel {
 
     this.relatedConcepts = _mapInstances(data.relatedConcepts ?? data.related ?? data.related_concepts ?? [], RelatedConcept);
 
-    // 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.
+    // 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).
     //
-    // 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);
+    // 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)
@@ -72,16 +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; }
+  // 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);
@@ -222,16 +223,13 @@ export class Concept extends GlossaristModel {
     if (this.relatedConcepts.length > 0) {
       obj.related = this.relatedConcepts.map(rc => rc.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());
+    // 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());
@@ -262,72 +260,147 @@ function _mapInstances(arr, Cls) {
   return arr.map(item => item instanceof Cls ? item : new Cls(item));
 }
 
-// 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)
+// Resolve the unified hyperedge array from any input shape.
 //
-// Hash dispatch uses TYPE_TO_CLASS from relation-type-registry.js —
-// the single source of truth shared with the per-file loader.
+// Three input categories are accepted; mixing them throws (audit C4 —
+// silent drop was a footgun):
 //
-// 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) {
+//   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).
+//
+// 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 data.relations
-      .map(r => _coerceRelation(r))
-      .filter(r => r != null);
+    return _dedupeOrThrow(data.relations.map(r => _coerceHyperedge(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);
+  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 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);
+  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 _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).`,
+    );
+  }
+}
 
-  const v1 = data.partitiveHyperedges ?? data.partitive_hyperedges;
-  if (Array.isArray(v1)) {
-    for (const h of v1) {
-      const hash = h instanceof PartitiveHyperedge ? h.toJSON() : h;
-      const migrated = migrateHyperedgeToRelation(hash);
-      if (migrated) out.push(new PartitiveRelation(migrated));
+// 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;
+}
 
-  return out;
+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 _coerceRelation(value, fallbackClass) {
+function _coerceHyperedge(value, fallbackClass) {
   if (value == null) return null;
-  if (value instanceof AbstractNaryRelation) return value;
+  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);
+  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;
+  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 };