glossarist 0.4.28 → 0.4.29

package/package.json

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

package/src/models/abstract-nary-relation.js

@@ -0,0 +1,119 @@
+// AbstractNaryRelation — shared base for n-ary concept-system
+// relations (PartitiveRelation, GenericRelation, future
+// SequentialRelation, AssociativeRelation).
+//
+// Carries the common shape:
+//   - comprehensive: ConceptRef
+//   - members: 2+ MECE dimensioned concept refs (≥2 per ISO 704)
+//   - completeness: complete | partial
+//   - criterion: localized subdivision criterion (ISO 12620)
+//   - sources / notes / status: administrative metadata
+//
+// Concrete leaves add type-specific fields if needed (currently none).
+// See docs/design/abstract-nary-relation.md (concept-model repo).
+
+import { GlossaristModel } from './base.js';
+import { ConceptRef } from './concept-ref.js';
+import {
+  COMPLETENESS,
+  DEFAULT_COMPLETENESS,
+  isValidCompleteness,
+} from './completeness.js';
+
+export class AbstractNaryRelation extends GlossaristModel {
+  constructor(data = {}) {
+    super();
+    this.comprehensive = _ensureComprehensive(data.comprehensive);
+    this.members = _ensureMembers(data.members, this.constructor.name);
+    this.completeness = _resolveCompleteness(data.completeness);
+    this.criterion = _normalizeCriterion(data.criterion);
+    this.sources = Array.isArray(data.sources) ? [...data.sources] : [];
+    this.notes = data.notes ?? null;
+    this.status = data.status ?? null;
+
+    _assertNoSelfLoop(this.comprehensive, this.members);
+  }
+
+  get isComplete() { return this.completeness === COMPLETENESS.COMPLETE; }
+  get isPartial() { return this.completeness === COMPLETENESS.PARTIAL; }
+  get isCoordinate() { return this.members.length >= 2; }
+
+  hasCriterion() { return this.criterion != null; }
+
+  identity() {
+    return this.constructor.identityOf(this);
+  }
+
+  toJSON() {
+    const obj = {
+      comprehensive: this.comprehensive.toJSON(),
+      members: this.members.map(m => m.toJSON()),
+      completeness: this.completeness,
+    };
+    if (this.criterion != null) obj.criterion = { ...this.criterion };
+    if (this.sources.length > 0) obj.sources = [...this.sources];
+    if (this.notes != null) obj.notes = { ...this.notes };
+    if (this.status != null) obj.status = this.status;
+    return obj;
+  }
+}
+
+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 ' +
+      '(source, id, or text required)',
+    );
+  }
+  return ref;
+}
+
+function _ensureMembers(values, typeName) {
+  if (!Array.isArray(values)) {
+    throw new Error(
+      `${typeName}.members must be an array (got ${typeof values})`,
+    );
+  }
+  if (values.length < 2) {
+    throw new Error(
+      `${typeName} requires ≥2 partitives (ISO 704); got ${values.length}`,
+    );
+  }
+  return values;
+}
+
+function _resolveCompleteness(value) {
+  const c = value ?? DEFAULT_COMPLETENESS;
+  if (!isValidCompleteness(c)) {
+    throw new Error(
+      `${c === value ? 'completeness' : 'completeness'} has invalid value ${JSON.stringify(value)}`,
+    );
+  }
+  return c;
+}
+
+function _normalizeCriterion(value) {
+  if (value == null) return null;
+  if (typeof value === 'string') {
+    return value.length > 0 ? { default: value } : null;
+  }
+  if (typeof value === 'object') {
+    const entries = Object.entries(value).filter(([, v]) => typeof v === 'string');
+    return entries.length > 0 ? Object.fromEntries(entries) : null;
+  }
+  return null;
+}
+
+function _assertNoSelfLoop(comprehensive, members) {
+  const cKey = `${comprehensive.source ?? ''}:${comprehensive.id ?? ''}`;
+  for (const m of members) {
+    const ref = m.ref;
+    const pKey = `${ref?.source ?? ''}:${ref?.id ?? ''}`;
+    if (pKey === cKey && (ref?.source || ref?.id)) {
+      throw new Error(
+        'Relation.members cannot include the comprehensive (no self-loops)',
+      );
+    }
+  }
+}

package/src/models/concept-system-member.js

@@ -0,0 +1,126 @@
+// ConceptSystemMember — abstract base shape for members of any
+// n-ary concept-system relation (PartitiveMember, GenericMember,
+// future AssociativeMember, SequentialMember).
+//
+// Carries the shared ISO 704:2022 MECE dimensions: presence × count,
+// plus the orthogonal is_delimiting flag.
+//
+// Concrete leaf classes extend this with type-specific fields if
+// needed (currently none). See docs/design/abstract-nary-relation.md
+// (concept-model repo).
+
+import { GlossaristModel } from './base.js';
+import { ConceptRef } from './concept-ref.js';
+import {
+  PARTITIVE_PRESENCE,
+  PARTITIVE_PRESENCE_VALUES,
+  DEFAULT_PRESENCE,
+  isValidPresence,
+} from './partitive-presence.js';
+import {
+  PARTITIVE_COUNT,
+  PARTITIVE_COUNT_VALUES,
+  DEFAULT_COUNT,
+  isValidCount,
+} from './partitive-count.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 {
+  constructor(data = {}) {
+    super();
+    this.ref = _ensureRef(data.ref);
+    this.presence = _resolvePresence(data.presence);
+    this.count = _resolveCount(data.count);
+    this.is_delimiting = _resolveDelimiting(data.is_delimiting);
+
+    _assertValidPair(this.presence, this.count);
+  }
+
+  get isRequired() { return this.presence === PARTITIVE_PRESENCE.REQUIRED; }
+  get isOptional() { return this.presence === PARTITIVE_PRESENCE.OPTIONAL; }
+  get isDelimiting() { return this.is_delimiting === true; }
+
+  identity() {
+    return ConceptSystemMember.identityOf(this);
+  }
+
+  toJSON() {
+    const obj = { ref: this.ref.toJSON() };
+    if (this.presence !== DEFAULT_PRESENCE) obj.presence = this.presence;
+    if (this.count !== DEFAULT_COUNT) obj.count = this.count;
+    if (this.is_delimiting) obj.is_delimiting = true;
+    return obj;
+  }
+
+  static identityOf(value) {
+    const v = value ?? {};
+    const ref = v.ref ?? {};
+    return `${ref.source ?? ''}:${ref.id ?? ''}`;
+  }
+
+  static fromJSON(data) {
+    return new ConceptSystemMember(data);
+  }
+}
+
+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 ' +
+      '(source, id, or text required)',
+    );
+  }
+  return ref;
+}
+
+function _resolvePresence(value) {
+  const p = value ?? DEFAULT_PRESENCE;
+  if (!isValidPresence(p)) {
+    throw new Error(
+      `invalid presence ${JSON.stringify(value)}; ` +
+      `must be one of: ${PARTITIVE_PRESENCE_VALUES.join(', ')}`,
+    );
+  }
+  return p;
+}
+
+function _resolveCount(value) {
+  const c = value ?? DEFAULT_COUNT;
+  if (!isValidCount(c)) {
+    throw new Error(
+      `invalid count ${JSON.stringify(value)}; ` +
+      `must be one of: ${PARTITIVE_COUNT_VALUES.join(', ')}`,
+    );
+  }
+  return c;
+}
+
+function _resolveDelimiting(value) {
+  if (value == null) return false;
+  if (typeof value !== 'boolean') {
+    throw new Error(
+      `ConceptSystemMember.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.',
+    );
+  }
+}

package/src/models/definition-type.js

@@ -0,0 +1,17 @@
+// DefinitionType — ISO 704:2022 §5.3 definition strategy enum.
+//
+//   intensional (default): genus + differentiae
+//   extensional:           enumerate instances or species
+//   partitive:             describe composition
+//   translated:            translated from another language
+
+import { makeEnum } from './enum.js';
+
+export const DEFINITION_TYPE = makeEnum('DEFINITION_TYPE', {
+  INTENSIONAL: 'intensional',
+  EXTENSIONAL: 'extensional',
+  PARTITIVE: 'partitive',
+  TRANSLATED: 'translated',
+});
+
+export const DEFAULT_DEFINITION_TYPE = DEFINITION_TYPE.INTENSIONAL;

package/src/models/generic-member.js

@@ -0,0 +1,15 @@
+// GenericMember — one member of a GenericRelation. Inherits the
+// ISO 704:2022 MECE shape from ConceptSystemMember. 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';
+
+export class GenericMember extends ConceptSystemMember {
+  // Inherits all attributes and validations from ConceptSystemMember.
+}
+
+export default GenericMember;

package/src/models/generic-relation.js

@@ -0,0 +1,43 @@
+// GenericRelation — 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
+// 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 { GenericMember } from './generic-member.js';
+
+export class GenericRelation extends AbstractNaryRelation {
+  constructor(data = {}) {
+    super(data);
+    this.members = data?.members == null
+      ? this.members
+      : (Array.isArray(data.members)
+          ? data.members.map(m =>
+              m instanceof GenericMember ? m : new GenericMember(m))
+          : this.members);
+  }
+
+  static identityOf(value) {
+    const v = value ?? {};
+    const c = v.comprehensive ?? {};
+    const memberKeys = Array.isArray(v.members)
+      ? v.members.map(m => {
+          const r = m?.ref ?? m ?? {};
+          return `${r.source ?? ''}:${r.id ?? ''}`;
+        }).sort()
+      : [];
+    return `${c.source ?? ''}:${c.id ?? ''}|${memberKeys.join('|')}`;
+  }
+
+  static fromJSON(data) {
+    return new GenericRelation(data);
+  }
+}
+
+export default GenericRelation;

package/src/models/index.d.ts

@@ -328,6 +328,71 @@ export class PartitiveHyperedge extends GlossaristModel {
   static fromJSON(data: Record<string, unknown>): PartitiveHyperedge;
 }
 
+// v2 PartitiveRelation + GenericRelation (MECE per-member model).
+// These supersede the v1 PartitiveHyperedge model above. New code
+// should use v2 exclusively; the v1 model is kept for backward-compat
+// input.
+export class ConceptSystemMember extends GlossaristModel {
+  readonly ref: ConceptRef;
+  readonly presence: 'required' | 'optional';
+  readonly count: 'exactly_one' | 'at_least_one' | 'multiple';
+  readonly is_delimiting: boolean;
+  required(): boolean;
+  optional(): boolean;
+  delimiting(): boolean;
+  identity(): string;
+  toJSON(): Record<string, unknown>;
+  static fromJSON(data: Record<string, unknown>): ConceptSystemMember;
+  static identityOf(value: unknown): string;
+}
+
+export class PartitiveMember extends ConceptSystemMember {}
+
+export class GenericMember extends ConceptSystemMember {}
+
+export class AbstractNaryRelation extends GlossaristModel {
+  readonly comprehensive: ConceptRef;
+  readonly members: ConceptSystemMember[];
+  readonly completeness: 'complete' | 'partial';
+  readonly criterion: Record<string, string> | null;
+  readonly sources: ConceptSource[];
+  readonly notes: Record<string, string> | null;
+  readonly status: string | null;
+  readonly isComplete: boolean;
+  readonly isPartial: boolean;
+  readonly isCoordinate: boolean;
+  toJSON(): Record<string, unknown>;
+  static fromJSON(data: Record<string, unknown>): AbstractNaryRelation;
+  static identityOf(value: unknown): string;
+}
+
+export class PartitiveRelation extends AbstractNaryRelation {
+  /** @deprecated use {@link members} — kept for v1/v2 wire compat. */
+  readonly partitives: ConceptSystemMember[];
+  static fromJSON(data: Record<string, unknown>): PartitiveRelation;
+  static identityOf(value: unknown): string;
+}
+
+export class GenericRelation extends AbstractNaryRelation {
+  static fromJSON(data: Record<string, unknown>): GenericRelation;
+  static identityOf(value: unknown): string;
+}
+
+export type DefinitionType = 'intensional' | 'extensional' | 'partitive' | 'translated';
+export const DEFINITION_TYPE: Readonly<Record<string, DefinitionType>>;
+export const DEFAULT_DEFINITION_TYPE: DefinitionType;
+export const DEFINITION_TYPE_VALUES: readonly DefinitionType[];
+
+export const RELATION_TYPE_TO_CLASS: Readonly<Record<string, typeof AbstractNaryRelation>>;
+export class RelationLoadError extends Error {
+  readonly path: string;
+  constructor(path: string, message: string);
+}
+export const RelationLoader: {
+  loadAll(relationsDir: string): Map<string, AbstractNaryRelation[]>;
+  loadOne(path: string): AbstractNaryRelation | null;
+};
+
 export const DESIGNATION_RELATIONSHIP_TYPES: readonly string[];
 export class DesignationRelationship extends GlossaristModel {
   readonly type: string | null;

package/src/models/index.js

@@ -38,6 +38,22 @@ export {
 // backward-compat input. New code should use v2 exclusively.
 export { PartitiveRelation } from './partitive-relation.js';
 export { PartitiveMember } from './partitive-member.js';
+
+// v2 GenericRelation models (per-file relation storage). Mirrors
+// PartitiveRelation shape; uses the same MECE member shape.
+export { AbstractNaryRelation } from './abstract-nary-relation.js';
+export { ConceptSystemMember } from './concept-system-member.js';
+export { GenericRelation } from './generic-relation.js';
+export { GenericMember } from './generic-member.js';
+export {
+  DEFINITION_TYPE,
+  DEFAULT_DEFINITION_TYPE,
+} from './definition-type.js';
+
+// Per-file relation loader (Node-side runtime; not browser-bundled).
+// Walks a relations/ directory and dispatches to PartitiveRelation /
+// GenericRelation by file type.
+export { RelationLoader, RelationLoadError, TYPE_TO_CLASS as RELATION_TYPE_TO_CLASS } from './relation-loader.js';
 export {
   PARTITIVE_PRESENCE,
   PARTITIVE_PRESENCE_VALUES,

package/src/models/partitive-member.js

@@ -1,7 +1,9 @@
-// PartitiveMember — one member of a PartitiveRelation.
+// PartitiveMember — one member of a PartitiveRelation. Inherits the
+// ISO 704:2022 MECE shape from ConceptSystemMember; the `comprehensive`
+// of its parent PartitiveRelation denotes the whole concept.
 //
-// Carries a ConceptRef (the subordinate concept partitive) plus
-// ISO 704:2022 presence + count + is_delimiting.
+// Distinct leaf class for type safety and to leave room for
+// Partitive-specific extensions.
 //
 // Matches concept-model/models/concepts/PartitiveMember.lutaml exactly:
 //   +ref            — ConceptRef [1]
@@ -12,94 +14,13 @@
 // The combination (optional, at_least_one) is invalid: if a part is
 // optional, the at-least-one constraint is vacuous and collapses to
 // (optional, multiple). Rejected at construction.
-//
-// ISO 704 "name" strings (compulsory, optional, etc.) are NOT part of
-// the model — they're a display concern handled by multiplicityFromPair
-// in the renderer/viewer layer. The model is purely presence + count.
-
-import { GlossaristModel } from './base.js';
-import { ConceptRef } from './concept-ref.js';
-import {
-  PARTITIVE_PRESENCE,
-  DEFAULT_PRESENCE,
-  PARTITIVE_PRESENCE_VALUES,
-  isValidPresence,
-} from './partitive-presence.js';
-import {
-  DEFAULT_COUNT,
-  PARTITIVE_COUNT_VALUES,
-  isValidCount,
-} from './partitive-count.js';
-
-export class PartitiveMember extends GlossaristModel {
-  constructor(data = {}) {
-    super();
-    this.ref = data.ref instanceof ConceptRef
-      ? data.ref
-      : new ConceptRef(data.ref ?? {});
-    this.presence = _resolvePresence(data.presence);
-    this.count = _resolveCount(data.count);
-    this.is_delimiting = data.is_delimiting === true;
-
-    _assertNonEmptyRef(this.ref);
-    _assertValidCombination(this.presence, this.count);
-  }
-
-  get isRequired() { return this.presence === PARTITIVE_PRESENCE.REQUIRED; }
-  get isOptional() { return this.presence === PARTITIVE_PRESENCE.OPTIONAL; }
-  get isDelimiting() { return this.is_delimiting === true; }
-
-  identity() {
-    return PartitiveMember.identityOf(this);
-  }
-
-  toJSON() {
-    const obj = { ref: this.ref.toJSON() };
-    if (this.presence !== DEFAULT_PRESENCE) obj.presence = this.presence;
-    if (this.count !== DEFAULT_COUNT) obj.count = this.count;
-    if (this.is_delimiting === true) obj.is_delimiting = true;
-    return obj;
-  }
 
-  static identityOf(value) {
-    const v = value ?? {};
-    const ref = v.ref ?? {};
-    return `${ref.source ?? ''}:${ref.id ?? ''}`;
-  }
+import { ConceptSystemMember } from './concept-system-member.js';
 
-  static fromJSON(data) {
-    return new PartitiveMember(data);
-  }
+export class PartitiveMember extends ConceptSystemMember {
+  // Inherits all attributes and validations from ConceptSystemMember.
+  // Declared as a distinct class for type safety and to leave room
+  // for future partitive-specific extensions.
 }
 
-function _resolvePresence(value) {
-  if (value == null) return DEFAULT_PRESENCE;
-  if (!isValidPresence(value)) {
-    throw new Error(`invalid presence ${JSON.stringify(value)}; must be one of ${PARTITIVE_PRESENCE_VALUES.join(', ')}`);
-  }
-  return value;
-}
-
-function _resolveCount(value) {
-  if (value == null) return DEFAULT_COUNT;
-  if (!isValidCount(value)) {
-    throw new Error(`invalid count ${JSON.stringify(value)}; must be one of ${PARTITIVE_COUNT_VALUES.join(', ')}`);
-  }
-  return value;
-}
-
-function _assertNonEmptyRef(ref) {
-  if (!ref.source && !ref.id && !ref.text) {
-    throw new Error('PartitiveMember#ref must be a non-empty ConceptRef (source, id, or text required)');
-  }
-}
-
-function _assertValidCombination(presence, count) {
-  if (presence === 'optional' && count === 'at_least_one') {
-    throw new Error(
-      'PartitiveMember presence=optional + count=at_least_one is invalid — ' +
-      'it collapses to optional + multiple (zero or more). ' +
-      'Use presence: optional, count: multiple instead.',
-    );
-  }
-}
+export default PartitiveMember;

package/src/models/partitive-relation.js

@@ -4,6 +4,10 @@
 // concepts (subordinate concepts partitive) which fitted together
 // constitute the comprehensive.
 //
+// Extends AbstractNaryRelation; the leaf-specific concern is the
+// PartitiveMember type for `members`. The wire-level field name
+// stays `partitives` for v1/v2 backward compat.
+//
 // ISO 704:2022 rake diagram semantics:
 //
 //   comprehensive concept
@@ -22,142 +26,51 @@
 // principle, and the criterion of subdivision used
 // (ISO 704:2022 §5.5.4.2.1).
 //
-// Field renames (v1 → v2):
-//   parts [1..*]              → partitives [2..*]  (as PartitiveMember)
-//   enumeration: closed|open  → completeness: complete|partial
-//   markers: [double, dashed] → (per-member multiplicity + is_delimiting)
-//   content: LocalizedString  → (dropped — structural edges carry no prose)
-//   plural-positive is_shared / is_uncertain → multiplicity (ISO 704:2022)
-//
 // Distinguished from binary `has_part` / `is_part_of` edges, which
 // express pairwise part-of assertions without completeness,
 // multiplicity, or criterion claims. A single partitive should be
 // expressed as a binary edge, not a PartitiveRelation (ISO requires
 // "two or more").
 
-import { GlossaristModel } from './base.js';
-import { ConceptRef } from './concept-ref.js';
+import { AbstractNaryRelation } from './abstract-nary-relation.js';
 import { PartitiveMember } from './partitive-member.js';
-import {
-  COMPLETENESS,
-  COMPLETENESS_VALUES,
-  DEFAULT_COMPLETENESS,
-  isValidCompleteness,
-} from './completeness.js';
 
-export class PartitiveRelation extends GlossaristModel {
+export class PartitiveRelation extends AbstractNaryRelation {
   constructor(data = {}) {
-    super();
-    this.comprehensive = _ensureComprehensive(data.comprehensive);
-    this.partitives = _ensurePartitives(data.partitives);
-    this.completeness = _resolveCompleteness(data.completeness);
-    this.criterion = _normalizeCriterion(data.criterion);
-
-    _assertNoSelfLoop(this.comprehensive, this.partitives);
+    const members = data?.members ?? data?.partitives;
+    super({ ...data, members });
+    this.members = members == null
+      ? this.members
+      : (Array.isArray(members)
+          ? members.map(m =>
+              m instanceof PartitiveMember ? m : new PartitiveMember(m))
+          : this.members);
   }
 
-  get isComplete() { return this.completeness === COMPLETENESS.COMPLETE; }
-  get isPartial() { return this.completeness === COMPLETENESS.PARTIAL; }
-
-  // ISO 12620 coordinate-concept predicate: a relation is "coordinate"
-  // when it has ≥2 partitives (all partitives within one relation are
-  // coordinate concepts by definition).
-  get isCoordinate() { return this.partitives.length >= 2; }
-
-  hasCriterion() { return this.criterion != null; }
-
-  identity() {
-    return PartitiveRelation.identityOf(this);
-  }
+  get partitives() { return this.members; }
 
   toJSON() {
-    const obj = {
-      comprehensive: this.comprehensive.toJSON(),
-      partitives: this.partitives.map(p => p.toJSON()),
-      completeness: this.completeness,
-    };
-    if (this.criterion != null) obj.criterion = { ...this.criterion };
-    return obj;
+    const base = super.toJSON();
+    const { members, ...rest } = base;
+    return { ...rest, partitives: members };
   }
 
-  // Stable identity for diffing: same comprehensive + same partitive
-  // set (by ref identity) = same relation. Changes to completeness,
-  // multiplicity, is_delimiting, or criterion produce "changed"
-  // entries rather than add+remove.
   static identityOf(value) {
     const v = value ?? {};
     const c = v.comprehensive ?? {};
-    const partitiveKeys = Array.isArray(v.partitives)
-      ? v.partitives.map(p => {
+    const partKeys = Array.isArray(v.partitives ?? v.members)
+      ? (v.partitives ?? v.members).map(p => {
           const r = p?.ref ?? p ?? {};
           return `${r.source ?? ''}:${r.id ?? ''}`;
         }).sort()
       : [];
-    return `${c.source ?? ''}:${c.id ?? ''}|${partitiveKeys.join('|')}`;
+    return `${c.source ?? ''}:${c.id ?? ''}|${partKeys.join('|')}`;
   }
 
   static fromJSON(data) {
-    return new PartitiveRelation(data);
-  }
-}
-
-function _ensureComprehensive(value) {
-  const ref = value instanceof ConceptRef ? value : new ConceptRef(value ?? {});
-  if (!ref.source && !ref.id && !ref.text) {
-    throw new Error(
-      'PartitiveRelation.comprehensive must be a non-empty ConceptReference ' +
-      '(source, id, or text required)',
-    );
+    const normalized = { ...(data ?? {}), members: data?.partitives ?? data?.members };
+    return new PartitiveRelation(normalized);
   }
-  return ref;
 }
 
-function _ensurePartitives(values) {
-  if (!Array.isArray(values)) {
-    throw new Error(
-      `PartitiveRelation.partitives must be an array (got ${typeof values})`,
-    );
-  }
-  if (values.length < 2) {
-    throw new Error(
-      `PartitiveRelation requires ≥2 partitives (ISO 704); got ${values.length}`,
-    );
-  }
-  return values.map(v => v instanceof PartitiveMember ? v : new PartitiveMember(v));
-}
-
-function _resolveCompleteness(value) {
-  const c = value ?? DEFAULT_COMPLETENESS;
-  if (!isValidCompleteness(c)) {
-    throw new Error(
-      `PartitiveRelation.completeness has invalid value ${JSON.stringify(value)}; ` +
-      `must be one of: ${COMPLETENESS_VALUES.join(', ')}`,
-    );
-  }
-  return c;
-}
-
-function _normalizeCriterion(value) {
-  if (value == null) return null;
-  if (typeof value === 'string') {
-    return value.length > 0 ? { default: value } : null;
-  }
-  if (typeof value === 'object') {
-    const entries = Object.entries(value).filter(([, v]) => typeof v === 'string');
-    return entries.length > 0 ? Object.fromEntries(entries) : null;
-  }
-  return null;
-}
-
-function _assertNoSelfLoop(comprehensive, partitives) {
-  const cKey = `${comprehensive.source ?? ''}:${comprehensive.id ?? ''}`;
-  for (const p of partitives) {
-    const ref = p.ref;
-    const pKey = `${ref.source ?? ''}:${ref.id ?? ''}`;
-    if (pKey === cKey && (ref.source || ref.id)) {
-      throw new Error(
-        'PartitiveRelation.partitives cannot include the comprehensive (no self-loops)',
-      );
-    }
-  }
-}
+export default PartitiveRelation;

package/src/models/relation-loader.js

@@ -0,0 +1,107 @@
+// RelationLoader — runtime loader for per-file n-ary relation YAMLs.
+//
+// Walks a `relations/<comprehensive-id>/<slug>.yaml` directory and
+// dispatches each file to the appropriate class (PartitiveRelation
+// or GenericRelation) based on its `type` field.
+//
+// The wire-shape contract is owned by the JSON Schema at
+// `schemas/v3/relation.yaml` (concept-model repo) — this loader
+// produces the corresponding JS model instances. See
+// docs/design/relations-as-files.md (concept-model).
+//
+// This is the runtime equivalent of concept-model's
+// CheckPartitiveRelationCoherence#each_relation /
+// CheckGenericRelationCoherence#each_relation validators.
+// Both readers and validators must agree on the type-dispatch
+// table (TYPE_TO_CLASS). Keep them in sync via the JSON Schema.
+
+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';
+
+/**
+ * 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.
+ */
+export const TYPE_TO_CLASS = Object.freeze({
+  partitive_relation: PartitiveRelation,
+  generic_relation: GenericRelation,
+});
+
+/**
+ * Thrown by `loadAll` when a relation file has an unknown `type`,
+ * malformed structure, or a class that fails to instantiate.
+ */
+export class RelationLoadError extends Error {
+  constructor(path, message) {
+    super(`relation-loader: ${path}: ${message}`);
+    this.path = path;
+  }
+}
+
+/**
+ * Walk a `relations/` directory and load every relation file,
+ * returning a Map keyed by comprehensive-id.
+ *
+ * Returns an empty Map if `relationsDir` doesn't exist or is empty.
+ *
+ * @param {string} relationsDir — path to a `relations/` directory
+ *   containing `<comprehensive-id>/<slug>.yaml` files (per the
+ *   schema in schemas/v3/relation.yaml).
+ * @returns {Map<string, Array<AbstractNaryRelation>>} — for each
+ *   comprehensive id, the list of relations that have it as their
+ *   comprehensive. Type-discriminated (PartitiveRelation or
+ *   GenericRelation).
+ */
+export function loadAll(relationsDir) {
+  const result = new Map();
+  if (!relationsDir) return result;
+  if (!existsSync(relationsDir)) return result;
+
+  const entries = readdirSync(relationsDir, { withFileTypes: true });
+  for (const compEntry of entries) {
+    if (!compEntry.isDirectory()) continue;
+    const compId = compEntry.name;
+    const compDir = `${relationsDir}/${compId}`;
+    if (!result.has(compId)) result.set(compId, []);
+    const files = readdirSync(compDir)
+      .filter(f => f.endsWith('.yaml') || f.endsWith('.yml'))
+      .sort();
+    for (const file of files) {
+      const path = `${compDir}/${file}`;
+      const rel = loadOne(path);
+      if (rel) result.get(compId).push(rel);
+    }
+  }
+  return result;
+}
+
+/**
+ * Namespace bundle for the loader — callers import it as
+ * `import { RelationLoader } from './relation-loader.js'` and call
+ * `RelationLoader.loadAll(dir)`. The individual functions are also
+ * exported directly for tree-shakeable single-call sites.
+ */
+export const RelationLoader = Object.freeze({ loadAll });
+
+/**
+ * Load a single relation file. Returns null if the file is missing,
+ * unreadable, or doesn't have a recognized `type` field. Throws
+ * `RelationLoadError` on malformed content (e.g., invalid `members`
+ * count, wrong comprehensive shape, YAML parse error).
+ */
+export function loadOne(path) {
+  let doc;
+  try {
+    doc = yaml.load(readFileSync(path, 'utf8'));
+  } catch (e) {
+    throw new RelationLoadError(path, `YAML parse failed: ${e.message}`);
+  }
+  if (!doc || typeof doc !== 'object') return null;
+  if (!doc.type) return null;
+  const Cls = TYPE_TO_CLASS[doc.type];
+  if (!Cls) return null;  // Unknown type — let the validator report it
+  return Cls.fromJSON(doc);
+}