@glossarist/concept-browser 0.7.88 → 0.7.90

package/src/adapters/model-bridge/entity-refs.ts

@@ -0,0 +1,49 @@
+/**
+ * Non-verbal entity reference normalization.
+ *
+ * Normalizes JSON-LD structural entity refs (`gl:figureRef` /
+ * `gl:tableRef` / `gl:formulaRef`) into the shape
+ * `NonVerbalReference.fromJSON` expects.
+ *
+ * Accepts three wire forms:
+ *   - bare string ID
+ *   - `{ "@id": "../kind/foo" }`
+ *   - `{ "@id": "../kind/foo", "gl:display": "Figure 3" }`
+ *
+ * Emits the canonical `{ ref, display? }` shape. The path's last
+ * segment is the entity id; the field name (`figureRef` vs `tableRef`
+ * vs `formulaRef`) is the kind discriminator upstream.
+ */
+import { GL } from '../wire-keys';
+
+export function normalizeEntityRefs(raw: unknown): unknown[] {
+  if (!Array.isArray(raw)) return [];
+  return raw.map(normalizeOneEntityRef).filter((v): v is Record<string, string> => v !== null);
+}
+
+function normalizeOneEntityRef(entry: unknown): Record<string, string> | null {
+  if (typeof entry === 'string') {
+    const trimmed = entry.trim();
+    return trimmed ? { ref: trimmed } : null;
+  }
+  if (!entry || typeof entry !== 'object') return null;
+  const obj = entry as Record<string, unknown>;
+  const atId = typeof obj['@id'] === 'string' ? (obj['@id'] as string) : null;
+  const explicitRef = typeof obj.ref === 'string' ? obj.ref
+    : typeof obj.entityId === 'string' ? obj.entityId
+    : typeof obj.entity_id === 'string' ? obj.entity_id
+    : null;
+  const entityId = (atId ? lastPathSegment(atId) : null) ?? explicitRef;
+  if (!entityId) return null;
+  const out: Record<string, string> = { ref: entityId };
+  const displayRaw = obj[GL.DISPLAY] ?? obj['gloss:display'] ?? obj.display;
+  if (typeof displayRaw === 'string') out.display = displayRaw;
+  return out;
+}
+
+function lastPathSegment(p: string): string | null {
+  const cleaned = p.replace(/[?#].*$/, '').replace(/\/+$/, '');
+  const segments = cleaned.split('/');
+  const last = segments[segments.length - 1];
+  return last ? decodeURIComponent(last) : null;
+}

package/src/adapters/model-bridge/index.ts

@@ -0,0 +1,46 @@
+/**
+ * Model bridge: converts between wire-format JSON and glossarist-js
+ * model instances.
+ *
+ * Supports two input formats:
+ * 1. JSON-LD (gl:-prefixed) — format produced by generate-data.mjs
+ * 2. Glossarist native — snake_case format from glossarist-js Concept.toJSON()
+ *
+ * Public API is re-exported here. Internal organization:
+ *   - jsonld-types.ts  — wire-format interface declarations
+ *   - bridges.ts       — WeakMap bridges for fields not yet in glossarist-js
+ *   - mappers.ts       — JSON-LD → snake_case mappers
+ *   - partitive.ts     — PartitiveRelation mapping + MECE migration
+ *   - entity-refs.ts   — non-verbal entity reference normalization
+ *   - concept.ts       — top-level Concept orchestration + URI construction
+ */
+export {
+  conceptFromJson,
+  conceptToSummary,
+  conceptUri,
+} from './concept';
+
+export {
+  getAnnotations,
+  getDesignationTarget,
+  getRefText,
+  getRelatedSourceId,
+  getRelatedCitation,
+} from './bridges';
+
+export type {
+  JsonLdConcept,
+  JsonLdLocalizedConcept,
+  JsonLdPartitiveMember,
+  JsonLdPartitiveRelation,
+  JsonLdDesignation,
+  JsonLdSource,
+  JsonLdOrigin,
+  JsonLdRelated,
+  JsonLdRef,
+  JsonLdLocality,
+  JsonLdDate,
+  JsonLdContent,
+  JsonLdPronunciation,
+  JsonLdGrammarInfo,
+} from './jsonld-types';

package/src/adapters/model-bridge/jsonld-types.ts

@@ -0,0 +1,169 @@
+/**
+ * JSON-LD wire-format types for the model-bridge.
+ *
+ * Extracted from model-bridge.ts to keep the mapper/bridge logic
+ * scannable. The 'gl:' prefix is the Glossarist JSON-LD namespace —
+ * see data/concept-model/ontologies/glossarist.context.jsonld.
+ *
+ * Wire format is dictated by glossarist-js's JSON-LD context, which
+ * is stable. Schema changes are rare and reviewable.
+ */
+
+export interface JsonLdContent {
+  'gl:content'?: string;
+}
+
+export interface JsonLdDate {
+  'gl:date'?: string;
+  'gl:dateType'?: string;
+}
+
+export interface JsonLdPronunciation {
+  'gl:content'?: string;
+  'gl:language'?: string;
+  'gl:script'?: string;
+  'gl:system'?: string;
+  'gl:country'?: string;
+}
+
+export interface JsonLdGrammarInfo {
+  'gl:gender'?: string;
+  'gl:number'?: string;
+  'gl:partOfSpeech'?: string;
+  'gl:noun'?: boolean;
+  'gl:verb'?: boolean;
+  'gl:adj'?: boolean;
+  'gl:adverb'?: boolean;
+  'gl:preposition'?: boolean;
+  'gl:participle'?: boolean;
+}
+
+export interface JsonLdRef {
+  'gl:source'?: string;
+  'gl:id'?: string;
+  'gl:version'?: string;
+  'gl:text'?: string;
+  source?: string;
+  id?: string;
+  version?: string;
+}
+
+export interface JsonLdLocality {
+  'gl:localityType'?: string;
+  'gl:referenceFrom'?: string;
+  'gl:referenceTo'?: string;
+  type?: string;
+  reference_from?: string;
+  reference_to?: string;
+}
+
+export interface JsonLdOrigin {
+  'gl:ref'?: string | JsonLdRef;
+  'gl:locality'?: JsonLdLocality;
+  'gl:link'?: string;
+  'gl:id'?: string;
+  'gl:version'?: string;
+  'gl:source'?: string;
+}
+
+export interface JsonLdSource {
+  'gl:id'?: string;
+  'gl:sourceType'?: string;
+  'gl:sourceStatus'?: string;
+  'gl:modification'?: string;
+  'gl:origin'?: JsonLdOrigin;
+  'gl:sourcedFrom'?: JsonLdOrigin[];
+  'gl:sourced_from'?: JsonLdOrigin[];
+}
+
+export interface JsonLdRelated {
+  'gl:relationshipType'?: string;
+  'gl:ref'?: JsonLdRef;
+  '@id'?: string;
+  'gl:term'?: string;
+  'gl:target'?: string;
+  'gl:sourceId'?: string;
+  'gl:citation'?: JsonLdOrigin;
+}
+
+export interface JsonLdDesignation {
+  '@type'?: string;
+  'gl:term'?: string;
+  'gl:normativeStatus'?: string;
+  'gl:absent'?: unknown;
+  'gl:fieldOfApplication'?: string;
+  'gl:usageInfo'?: string;
+  'gl:geographicalArea'?: string;
+  'gl:language'?: string;
+  'gl:script'?: string;
+  'gl:system'?: string;
+  'gl:international'?: boolean;
+  'gl:termType'?: string;
+  'gl:pronunciation'?: JsonLdPronunciation[];
+  'gl:source'?: JsonLdSource[];
+  'gl:related'?: JsonLdRelated[];
+  'gl:prefix'?: string;
+  'gl:gender'?: string;
+  'gl:grammarInfo'?: JsonLdGrammarInfo[];
+}
+
+export interface JsonLdLocalizedConcept {
+  'gl:languageCode'?: string;
+  'gl:entryStatus'?: string;
+  'gl:classification'?: string;
+  'gl:reviewType'?: string;
+  'gl:domain'?: string;
+  'gl:release'?: string;
+  'gl:lineageSourceSimilarity'?: number;
+  'gl:script'?: string;
+  'gl:system'?: string;
+  'gl:designation'?: JsonLdDesignation[];
+  'gl:definition'?: JsonLdContent[];
+  'gl:notes'?: JsonLdContent[];
+  'gl:annotations'?: JsonLdContent[];
+  'gl:examples'?: JsonLdContent[];
+  'gl:source'?: JsonLdSource[];
+  'gl:dates'?: JsonLdDate[];
+  'gl:references'?: JsonLdRelated[];
+  'gl:reviewDate'?: string;
+  'gl:reviewDecisionDate'?: string;
+  'gl:reviewDecisionEvent'?: string;
+  'gl:reviewStatus'?: string;
+  'gl:reviewDecision'?: string;
+  'gl:reviewDecisionNotes'?: string;
+}
+
+export interface JsonLdPartitiveMember {
+  'gl:ref'?: JsonLdRef;
+  /** ISO 704:2022 MECE: presence (required | optional) */
+  'gl:presence'?: string;
+  /** ISO 704:2022 MECE: count (exactly_one | at_least_one | multiple) */
+  'gl:count'?: string;
+  /** ISO 704:2022: delimiting part (3× stroke width in diagrams) */
+  'gl:isDelimiting'?: boolean;
+  /** Legacy v3 field — one-string multiplicity, split into presence+count */
+  'gl:multiplicity'?: string;
+  /** Legacy v2 field — migrated to presence+count */
+  'gl:certainty'?: string;
+}
+
+export interface JsonLdPartitiveRelation {
+  'gl:comprehensive'?: JsonLdRef;
+  'gl:hasPartitive'?: JsonLdPartitiveMember[];
+  'gl:completeness'?: string;
+  'gl:criterion'?: Record<string, string> | string;
+}
+
+export interface JsonLdConcept {
+  '@type'?: string;
+  '@id'?: string;
+  'gl:identifier'?: string | number;
+  'gl:term'?: string;
+  'gl:localizedConcept'?: Record<string, JsonLdLocalizedConcept>;
+  'gl:related'?: JsonLdRelated[];
+  'gl:partitiveRelations'?: JsonLdPartitiveRelation[];
+  'gl:tags'?: string[];
+  'gl:figureRef'?: unknown[];
+  'gl:tableRef'?: unknown[];
+  'gl:formulaRef'?: unknown[];
+}

package/src/adapters/model-bridge/mappers.ts

@@ -0,0 +1,277 @@
+/**
+ * JSON-LD → Glossarist native mapping functions.
+ *
+ * Each mapper reads the wire-format JSON-LD (gl:-prefixed keys, see
+ * src/adapters/wire-keys.ts for the SSOT) and emits the snake_case
+ * dict that glossarist-js's Model.fromJSON constructors expect.
+ *
+ * Mappers are pure functions — no side effects, no global state.
+ * Bridge machinery (WeakMaps) lives in bridges.ts.
+ */
+import { GL } from '../wire-keys';
+import { DESIGNATION_REL_TYPES } from './bridges';
+import type {
+  JsonLdDesignation,
+  JsonLdRef,
+  JsonLdLocality,
+  JsonLdOrigin,
+  JsonLdSource,
+  JsonLdRelated,
+  JsonLdLocalizedConcept,
+  JsonLdConcept,
+} from './jsonld-types';
+
+export function isJsonLd(doc: Record<string, unknown>): boolean {
+  return '@type' in doc && GL.LOCALIZED_CONCEPT in doc;
+}
+
+export function mapDesignationFromJsonLd(d: JsonLdDesignation): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  const rawType = d['@type'] || '';
+
+  if (rawType.includes('Abbreviation')) result.type = 'abbreviation';
+  else if (rawType.includes('LetterSymbol')) result.type = 'letter_symbol';
+  else if (rawType.includes('GraphicalSymbol')) result.type = 'graphical_symbol';
+  else if (rawType.includes('Symbol')) result.type = 'symbol';
+  else result.type = 'expression';
+
+  result.designation = d[GL.TERM] ?? '';
+  result.normative_status = d[GL.NORMATIVE_STATUS] ?? null;
+
+  if (d[GL.ABSENT] != null) result.absent = d[GL.ABSENT];
+  if (d[GL.FIELD_OF_APPLICATION]) result.field_of_application = d[GL.FIELD_OF_APPLICATION];
+  if (d[GL.USAGE_INFO]) result.usage_info = d[GL.USAGE_INFO];
+  if (d[GL.GEOGRAPHICAL_AREA]) result.geographical_area = d[GL.GEOGRAPHICAL_AREA];
+  if (d[GL.LANGUAGE]) result.language = d[GL.LANGUAGE];
+  if (d[GL.SCRIPT]) result.script = d[GL.SCRIPT];
+  if (d[GL.SYSTEM]) result.system = d[GL.SYSTEM];
+  if (d[GL.INTERNATIONAL] != null) result.international = d[GL.INTERNATIONAL];
+  if (d[GL.TERM_TYPE]) result.term_type = d[GL.TERM_TYPE];
+
+  const pronunciation = d[GL.PRONUNCIATION];
+  if (pronunciation?.length) {
+    result.pronunciation = pronunciation.map(p => ({
+      content: p[GL.CONTENT] ?? null,
+      language: p[GL.LANGUAGE] ?? null,
+      script: p[GL.SCRIPT] ?? null,
+      system: p[GL.SYSTEM] ?? null,
+      country: p[GL.COUNTRY] ?? null,
+    }));
+  }
+
+  const sources = d[GL.SOURCE];
+  if (sources?.length) {
+    result.sources = sources.map(mapSourceFromJsonLd);
+  }
+
+  const related = d[GL.RELATED];
+  if (related?.length) {
+    result.related = related.map(r => {
+      const relType = r[GL.RELATIONSHIP_TYPE] ?? 'references';
+      if (DESIGNATION_REL_TYPES.has(relType) && r[GL.TARGET]) {
+        return { type: relType, target: r[GL.TARGET] };
+      }
+      return mapRelatedFromJsonLd(r);
+    });
+  }
+
+  if (d[GL.PREFIX] != null) result.prefix = d[GL.PREFIX];
+  if (d[GL.GENDER]) {
+    result.grammar_info = [{ gender: d[GL.GENDER] }];
+  }
+  const grammarInfo = d[GL.GRAMMAR_INFO];
+  if (grammarInfo?.length) {
+    result.grammar_info = grammarInfo.map(gi => ({
+      gender: gi[GL.GENDER] ?? null,
+      number: gi[GL.NUMBER] ?? null,
+      part_of_speech: gi[GL.PART_OF_SPEECH] ?? null,
+      noun: gi[GL.NOUN] ?? false,
+      verb: gi[GL.VERB] ?? false,
+      adj: gi[GL.ADJ] ?? false,
+      adverb: gi[GL.ADVERB] ?? false,
+      preposition: gi[GL.PREPOSITION] ?? false,
+      participle: gi[GL.PARTICIPLE] ?? false,
+    }));
+  }
+
+  return result;
+}
+
+export function mapRefFromJsonLd(rawRef: JsonLdRef | string | undefined): Record<string, unknown> | null {
+  if (!rawRef) return null;
+  if (typeof rawRef === 'string') return { source: rawRef };
+  const refObj: Record<string, unknown> = {};
+  // gl:-prefixed keys take precedence over unprefixed keys
+  refObj.source = rawRef[GL.SOURCE] ?? rawRef.source;
+  refObj.id = rawRef[GL.LOCAL_ID] ?? rawRef.id;
+  refObj.version = rawRef[GL.VERSION] ?? rawRef.version;
+  if (rawRef[GL.TEXT]) refObj.text = rawRef[GL.TEXT];
+  return (refObj.source ?? refObj.id ?? refObj.version ?? refObj.text) != null
+    ? refObj : null;
+}
+
+/**
+ * Map JSON-LD locality to glossarist's snake_case format.
+ * Always uses snake_case (reference_from/reference_to) for consistency
+ * with the glossarist model.
+ */
+export function mapLocalityFromJsonLd(rawLoc: JsonLdLocality | undefined): Record<string, unknown> | null {
+  if (!rawLoc) return null;
+  const locObj: Record<string, unknown> = {};
+  locObj.type = rawLoc[GL.LOCALITY_TYPE] ?? rawLoc.type;
+  locObj.reference_from = rawLoc[GL.REFERENCE_FROM] ?? rawLoc.reference_from;
+  locObj.reference_to = rawLoc[GL.REFERENCE_TO] ?? rawLoc.reference_to;
+  return (locObj.type ?? locObj.reference_from ?? locObj.reference_to) != null
+    ? locObj : null;
+}
+
+export function mapDetailedDefinitionFromJsonLd(d: any): Record<string, unknown> {
+  const result: Record<string, unknown> = { content: d[GL.CONTENT] ?? '' };
+  if (d[GL.EXAMPLES]?.length) {
+    result.examples = d[GL.EXAMPLES].map(mapDetailedDefinitionFromJsonLd);
+  }
+  return result;
+}
+
+export function mapOriginFromJsonLd(o: JsonLdOrigin): Record<string, unknown> {
+  const origin: Record<string, unknown> = {};
+  const ref = mapRefFromJsonLd(o[GL.REF]);
+  if (ref) origin.ref = ref;
+  const loc = mapLocalityFromJsonLd(o[GL.LOCALITY]);
+  if (loc) origin.locality = loc;
+  if (o[GL.LINK]) origin.link = o[GL.LINK];
+  if (o[GL.LOCAL_ID]) origin.id = o[GL.LOCAL_ID];
+  if (o[GL.VERSION]) origin.version = o[GL.VERSION];
+  if (o[GL.SOURCE]) origin.source = o[GL.SOURCE];
+  return origin;
+}
+
+export function mapSourceFromJsonLd(s: JsonLdSource): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  // JsonLdSource uses GL.LOCAL_ID ('gl:id') for the source's local id,
+  // distinct from JSON-LD's '@id' (the concept IRI).
+  if (s[GL.LOCAL_ID]) result.id = s[GL.LOCAL_ID];
+  if (s[GL.SOURCE_TYPE]) result.type = s[GL.SOURCE_TYPE];
+  if (s[GL.SOURCE_STATUS]) result.status = s[GL.SOURCE_STATUS];
+  if (s[GL.MODIFICATION]) result.modification = s[GL.MODIFICATION];
+
+  const origin = s[GL.ORIGIN];
+  if (origin) {
+    result.origin = mapOriginFromJsonLd(origin);
+  }
+
+  const sf = s[GL.SOURCED_FROM] ?? s[GL.SOURCED_FROM_ALT];
+  if (sf?.length) {
+    result.sourced_from = sf.map(item => mapOriginFromJsonLd(item));
+  }
+
+  return result;
+}
+
+export function mapRelatedFromJsonLd(r: JsonLdRelated): Record<string, unknown> {
+  const result: Record<string, unknown> = { type: 'references' };
+
+  if (r[GL.RELATIONSHIP_TYPE]) {
+    result.type = r[GL.RELATIONSHIP_TYPE];
+  }
+
+  if (r[GL.REF]) {
+    const ref = mapRefFromJsonLd(r[GL.REF]);
+    if (ref) result.ref = ref;
+  }
+
+  if (!result.ref && r['@id']) {
+    const uri = r['@id'];
+    const idMatch = uri.match(/\/concept\/([^/]+)$/);
+    result.ref = idMatch
+      ? { source: uri.split('/').slice(-3, -2)[0] || '', id: idMatch[1] }
+      : { source: uri, id: null };
+  }
+  if (r[GL.TERM]) result.content = r[GL.TERM];
+
+  // Bridged fields — stored in raw dict, extracted by attachBridges()
+  if (r[GL.SOURCE_ID]) result.sourceId = r[GL.SOURCE_ID];
+  const rawCitation = r[GL.CITATION];
+  if (rawCitation) {
+    const c = rawCitation;
+    const citation: Record<string, unknown> = {};
+    if (c[GL.REF]) {
+      const cr = mapRefFromJsonLd(c[GL.REF]);
+      if (cr) citation.ref = cr;
+    }
+    const loc = mapLocalityFromJsonLd(c[GL.LOCALITY]);
+    if (loc) citation.locality = loc;
+    if (c[GL.LINK]) citation.link = c[GL.LINK];
+    if (Object.keys(citation).length > 0) result.citation = citation;
+  }
+
+  return result;
+}
+
+export function mapLocalizedFromJsonLd(lc: JsonLdLocalizedConcept): Record<string, unknown> {
+  const data: Record<string, unknown> = {};
+
+  if (lc[GL.LANGUAGE_CODE]) data.language_code = lc[GL.LANGUAGE_CODE];
+  if (lc[GL.ENTRY_STATUS]) data.entry_status = lc[GL.ENTRY_STATUS];
+  if (lc[GL.CLASSIFICATION]) data.classification = lc[GL.CLASSIFICATION];
+  if (lc[GL.REVIEW_TYPE]) data.review_type = lc[GL.REVIEW_TYPE];
+  if (lc[GL.DOMAIN]) data.domain = lc[GL.DOMAIN];
+  if (lc[GL.RELEASE]) data.release = lc[GL.RELEASE];
+  if (lc[GL.LINEAGE_SOURCE_SIMILARITY] != null) data.lineage_source_similarity = lc[GL.LINEAGE_SOURCE_SIMILARITY];
+  if (lc[GL.SCRIPT]) data.script = lc[GL.SCRIPT];
+  if (lc[GL.SYSTEM]) data.system = lc[GL.SYSTEM];
+
+  const designation = lc[GL.DESIGNATION];
+  if (designation?.length) {
+    data.terms = designation.map(mapDesignationFromJsonLd);
+  }
+
+  const definition = lc[GL.DEFINITION];
+  if (definition?.length) {
+    data.definition = definition.map(mapDetailedDefinitionFromJsonLd);
+  }
+
+  const notes = lc[GL.NOTES];
+  if (notes?.length) {
+    data.notes = notes.map(mapDetailedDefinitionFromJsonLd);
+  }
+
+  const annotations = lc[GL.ANNOTATIONS];
+  if (annotations?.length) {
+    data.annotations = annotations.map(mapDetailedDefinitionFromJsonLd);
+  }
+
+  const examples = lc[GL.EXAMPLES];
+  if (examples?.length) {
+    data.examples = examples.map(mapDetailedDefinitionFromJsonLd);
+  }
+
+  const lcSources = lc[GL.SOURCE];
+  if (lcSources?.length) {
+    data.sources = lcSources.map(mapSourceFromJsonLd);
+  }
+
+  const dates = lc[GL.DATES];
+  if (dates?.length) {
+    data.dates = dates.map(d => ({
+      date: d[GL.DATE] ?? null,
+      type: d[GL.DATE_TYPE] ?? null,
+    }));
+  }
+
+  const lcReferences = lc[GL.REFERENCES];
+  if (lcReferences?.length) {
+    data.related = lcReferences.map(mapRelatedFromJsonLd);
+  }
+
+  if (lc[GL.REVIEW_DATE]) data.review_date = lc[GL.REVIEW_DATE];
+  if (lc[GL.REVIEW_DECISION_DATE]) data.review_decision_date = lc[GL.REVIEW_DECISION_DATE];
+  if (lc[GL.REVIEW_DECISION_EVENT]) data.review_decision_event = lc[GL.REVIEW_DECISION_EVENT];
+  if (lc[GL.REVIEW_STATUS]) data.review_status = lc[GL.REVIEW_STATUS];
+  if (lc[GL.REVIEW_DECISION]) data.review_decision = lc[GL.REVIEW_DECISION];
+  if (lc[GL.REVIEW_DECISION_NOTES]) data.review_decision_notes = lc[GL.REVIEW_DECISION_NOTES];
+
+  return data;
+}
+
+export type { JsonLdConcept };

package/src/adapters/model-bridge/partitive.ts

@@ -0,0 +1,79 @@
+/**
+ * Partitive relation mapping: JSON-LD → glossarist-js PartitiveRelation.
+ *
+ * Handles ISO 704:2022 MECE axes (presence × count) plus legacy
+ * migration from the 5-value `multiplicity` enum and the 2-value
+ * `certainty` field. See BRIDGES.md for the migration contract.
+ */
+import { GL } from '../wire-keys';
+import { isPartitivePresence, isPartitiveCount } from '../../utils/partitive-multiplicity';
+import { mapRefFromJsonLd } from './mappers';
+import type { JsonLdPartitiveRelation } from './jsonld-types';
+
+export function mapPartitiveRelationFromJsonLd(r: JsonLdPartitiveRelation): Record<string, unknown> | null {
+  const comprehensive = r[GL.COMPREHENSIVE] ? mapRefFromJsonLd(r[GL.COMPREHENSIVE]) : null;
+  if (!comprehensive) return null;
+
+  const partitives = (r[GL.HAS_PARTITIVE] ?? [])
+    .map((m): Record<string, unknown> | null => {
+      const ref = m[GL.REF] ? mapRefFromJsonLd(m[GL.REF]) : null;
+      if (!ref) return null;
+      const out: Record<string, unknown> = { ref };
+      // ISO 704:2022 MECE: prefer presence × count from JSON-LD. Fall back
+      // to migrating the legacy one-string `multiplicity` or v2 `certainty`
+      // so data in transit from older glossarist versions still loads.
+      const presence = m[GL.PRESENCE];
+      const count = m[GL.COUNT];
+      if (isPartitivePresence(presence) && isPartitiveCount(count)) {
+        out.presence = presence;
+        out.count = count;
+      } else {
+        const raw = m[GL.MULTIPLICITY] ?? splitLegacyCertainty(m[GL.CERTAINTY]);
+        if (raw) {
+          const parts = splitMultiplicity(raw);
+          out.presence = parts.presence;
+          out.count = parts.count;
+        }
+      }
+      if (m[GL.IS_DELIMITING] === true) out.is_delimiting = true;
+      return out;
+    })
+    .filter((m): m is Record<string, unknown> => m !== null);
+
+  // ISO 704 requires ≥2 partitives. Skip malformed relations rather
+  // than letting the constructor throw and break the whole concept.
+  if (partitives.length < 2) return null;
+
+  const out: Record<string, unknown> = {
+    comprehensive,
+    partitives,
+  };
+
+  if (r[GL.COMPLETENESS]) out.completeness = r[GL.COMPLETENESS];
+
+  if (r[GL.CRITERION]) {
+    out.criterion = typeof r[GL.CRITERION] === 'string'
+      ? { default: r[GL.CRITERION] }
+      : r[GL.CRITERION];
+  }
+
+  return out;
+}
+
+/** Migrate legacy v2 certainty → old v3 multiplicity string. */
+function splitLegacyCertainty(certainty: string | undefined): string | null {
+  if (!certainty) return null;
+  return certainty === 'possible' ? 'optional' : 'compulsory';
+}
+
+/** Split the legacy one-string multiplicity into MECE presence × count. */
+function splitMultiplicity(m: string): { presence: 'required' | 'optional'; count: 'exactly_one' | 'at_least_one' | 'multiple' } {
+  const LEGACY_MAP: Record<string, { presence: 'required' | 'optional'; count: 'exactly_one' | 'at_least_one' | 'multiple' }> = {
+    compulsory:               { presence: 'required', count: 'exactly_one' },
+    optional:                 { presence: 'optional', count: 'exactly_one' },
+    compulsory_multiple:      { presence: 'required', count: 'multiple' },
+    optional_multiple:        { presence: 'optional', count: 'multiple' },
+    compulsory_at_least_one:  { presence: 'required', count: 'at_least_one' },
+  };
+  return LEGACY_MAP[m] ?? { presence: 'required', count: 'exactly_one' };
+}