@glossarist/concept-browser 0.7.88 → 0.7.90

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glossarist/concept-browser",
-  "version": "0.7.88",
+  "version": "0.7.90",
   "description": "Vue SPA for browsing Glossarist terminology datasets with cross-reference resolution, graph visualization, and multi-language support",
   "type": "module",
   "bin": {

package/scripts/__tests__/bibliography.test.mjs

@@ -0,0 +1,29 @@
+import { describe, it, expect } from 'vitest';
+import { normalizeBibliography } from '../lib/bibliography.mjs';
+
+describe('normalizeBibliography', () => {
+  it('wraps a bare array into { bibliography: [...] }', () => {
+    const entries = [{ id: 'ISO1' }, { id: 'ISO2' }];
+    expect(normalizeBibliography(entries)).toEqual({ bibliography: entries });
+  });
+
+  it('passes through an already-wrapped object', () => {
+    const wrapped = { bibliography: [{ id: 'ISO1' }] };
+    expect(normalizeBibliography(wrapped)).toBe(wrapped);
+  });
+
+  it('returns an empty wrapper for null/undefined', () => {
+    expect(normalizeBibliography(null)).toEqual({ bibliography: [] });
+    expect(normalizeBibliography(undefined)).toEqual({ bibliography: [] });
+  });
+
+  it('returns an empty wrapper for junk input (non-array, non-wrapped)', () => {
+    expect(normalizeBibliography('string')).toEqual({ bibliography: [] });
+    expect(normalizeBibliography(42)).toEqual({ bibliography: [] });
+    expect(normalizeBibliography({ other: 'shape' })).toEqual({ bibliography: [] });
+  });
+
+  it('handles empty array input', () => {
+    expect(normalizeBibliography([])).toEqual({ bibliography: [] });
+  });
+});

package/scripts/generate-data.mjs

@@ -14,6 +14,7 @@ import { buildVersionHistoryTurtle } from './lib/version-turtle.mjs';
 import { buildBibliographyTurtle } from './lib/bibliography-turtle.mjs';
 import { ttlLit } from './lib/turtle-escape.mjs';
 import { firstNonEmpty } from './lib/first-non-empty.mjs';
+import { normalizeBibliography } from './lib/bibliography.mjs';
 
 // MECE partitive multiplicity: 2 independent axes (ISO 704:2022).
 //   presence × count
@@ -1296,9 +1297,10 @@ async function processDataset(dir, register, opts) {
   // Copy bibliography.yaml → bibliography.json
   const bibPath = path.join(sourceRoot, 'bibliography.yaml');
   if (fs.existsSync(bibPath)) {
-    const bibData = readYaml(bibPath);
+    const rawBib = readYaml(bibPath);
+    const bibData = normalizeBibliography(rawBib);
     writeJson(path.join(DATA, register, 'bibliography.json'), bibData);
-    const bibCount = Array.isArray(bibData?.bibliography) ? bibData.bibliography.length : 0;
+    const bibCount = bibData.bibliography.length;
     console.log(`  Copied bibliography (${bibCount} entries)`);
   }
 

package/scripts/lib/bibliography.mjs

@@ -0,0 +1,18 @@
+/**
+ * Normalize bibliography data into the { bibliography: [...] } shape
+ * expected by BibliographyData.fromJSON.
+ *
+ * Accepts either:
+ *   - A bare array of entries (the canonical YAML source form).
+ *   - An already-wrapped { bibliography: [...] } object.
+ *   - Anything else (treated as empty).
+ *
+ * Ported from origin/fix/bibliography-yaml-array-wrap (2026-06-25).
+ * That branch fell 153 commits behind main and was deleted in the
+ * 2026-07-29 stale-branch purge; this is the unmerged work.
+ */
+export function normalizeBibliography(raw) {
+  if (Array.isArray(raw)) return { bibliography: raw };
+  if (raw && Array.isArray(raw.bibliography)) return raw;
+  return { bibliography: [] };
+}

package/src/__tests__/cross-repo-multiplicity-contract.test.ts

@@ -0,0 +1,84 @@
+/**
+ * Cross-repo MECE multiplicity table SSOT spec.
+ *
+ * Audit (AUDIT-2026-07-29 P2-1): pin that the multiplicity mapping
+ * table is consistent with glossarist-js's SSOT (multiplicityFromPair).
+ *
+ * The concept-browser doesn't redefine the table — it re-exports
+ * `multiplicityFromPair` from glossarist-js via
+ * `src/utils/partitive-multiplicity.ts`. This spec ensures that
+ * re-export stays correct, and that the 5 valid combinations and
+ * the 1 invalid combination match the documented contract.
+ *
+ * Sister specs:
+ *   - glossarist-js test/models/partitive-relation-v4.test.js
+ *   - glossarist-ruby spec/unit/v3/multiplicity_spec.rb
+ *   - concept-model spec/multiplicity_spec.rb
+ *
+ * All four must agree. This spec is the concept-browser side of
+ * that cross-repo contract.
+ */
+import { describe, it, expect } from 'vitest';
+import {
+  partitiveMultiplicityName,
+  rakeStrokeStyle,
+  type PartitivePresence,
+  type PartitiveCount,
+} from '../utils/partitive-multiplicity';
+
+describe('cross-repo MECE multiplicity SSOT contract', () => {
+  // The 5 valid combinations are the source of truth. Any change
+  // here MUST be mirrored in:
+  //   - glossarist-js src/models/multiplicity.js (NAME_BY_PAIR)
+  //   - glossarist-ruby lib/glossarist/v3/multiplicity.rb (NAME_BY_PAIR)
+  //   - concept-model lib/glossarist/concept_model/multiplicity.rb (MAPPING)
+  //   - concept-model schemas/v3/concept.yaml (partitive_member.not.allOf)
+  //   - concept-model ontologies/shapes/glossarist.shacl.ttl (VacuousComboShape)
+  const VALID_COMBINATIONS: Array<{
+    presence: PartitivePresence;
+    count: PartitiveCount;
+    iso704Name: string;
+  }> = [
+    { presence: 'required', count: 'exactly_one',  iso704Name: 'compulsory' },
+    { presence: 'optional', count: 'exactly_one',  iso704Name: 'optional' },
+    { presence: 'required', count: 'multiple',     iso704Name: 'compulsory_multiple' },
+    { presence: 'optional', count: 'multiple',     iso704Name: 'optional_multiple' },
+    { presence: 'required', count: 'at_least_one', iso704Name: 'compulsory_at_least_one' },
+  ];
+
+  it('maps the 5 valid (presence, count) pairs to ISO 704 names', () => {
+    for (const { presence, count, iso704Name } of VALID_COMBINATIONS) {
+      expect(partitiveMultiplicityName(presence, count)).toBe(iso704Name);
+    }
+  });
+
+  it('rejects the vacuous (optional, at_least_one) combination', () => {
+    // This combination is invalid because "may exist, ≥1 if it does"
+    // collapses to "may exist in any number" = (optional, multiple).
+    // The model rejects it at construction; multiplicityFromPair
+    // rejects it at name lookup. Both must surface the error.
+    expect(() => partitiveMultiplicityName('optional', 'at_least_one'))
+      .toThrow(/Invalid multiplicity combination/);
+  });
+
+  it('every valid combination produces a renderable rakeStrokeStyle', () => {
+    // The renderer must accept every valid combination — no missing
+    // branches in the switch. If multiplicityFromPair succeeds,
+    // rakeStrokeStyle must succeed too.
+    for (const { presence, count } of VALID_COMBINATIONS) {
+      const style = rakeStrokeStyle(presence, count, false);
+      expect(style.lineCount).toBeGreaterThanOrEqual(1);
+      expect(style.lineCount).toBeLessThanOrEqual(2);
+      expect(style.strokeWidth).toBeGreaterThan(0);
+    }
+  });
+
+  it('the table has exactly 5 entries (no drift)', () => {
+    expect(VALID_COMBINATIONS).toHaveLength(5);
+  });
+
+  it('no two pairs map to the same ISO 704 name', () => {
+    const names = VALID_COMBINATIONS.map(c => c.iso704Name);
+    expect(new Set(names).size).toBe(names.length);
+  });
+});

package/src/__tests__/model-bridge-partitive-migration.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Bridge reverse-map round-trip specs.
+ *
+ * Audit (AUDIT-2026-07-29 P2-1): pin that loading legacy
+ * gl:multiplicity (or older gl:certainty) wire data produces a
+ * glossarist-js v4 model with the correct MECE presence × count
+ * fields. The migration path lives in model-bridge.ts and must
+ * agree with multiplicityFromPair(p, c) at the SSOT level.
+ *
+ * This spec also covers the invalid-combination case: legacy data
+ * carrying the vacuous (optional, at_least_one) combo via
+ * gl:multiplicity cannot exist — there's no ISO 704 name for it —
+ * so we don't test that path here.
+ */
+import { describe, it, expect } from 'vitest';
+import { conceptFromJson } from '../adapters/model-bridge';
+
+interface PartitiveMemberLike {
+  presence: string;
+  count: string;
+  is_delimiting: boolean;
+}
+
+function loadPartitives(doc: Record<string, unknown>): PartitiveMemberLike[] {
+  const concept = conceptFromJson(doc as any);
+  const relations = (concept as any).partitiveRelations ?? [];
+  return relations.flatMap((r: any) =>
+    (r.partitives ?? []).map((m: any) => ({
+      presence: m.presence,
+      count: m.count,
+      is_delimiting: m.is_delimiting,
+    })),
+  );
+}
+
+const BASE_DOC = {
+  '@type': 'gl:Concept',
+  '@id': 'https://example.org/vim/concept/1.3',
+  'gl:identifier': '1.3',
+  'gl:localizedConcept': {},
+};
+
+function docWithRelation(members: unknown[]) {
+  return {
+    ...BASE_DOC,
+    'gl:partitiveRelations': [
+      {
+        'gl:comprehensive': { 'gl:source': 'VIM', 'gl:id': '1.3' },
+        'gl:hasPartitive': members,
+        'gl:completeness': 'complete',
+      },
+    ],
+  };
+}
+
+describe('bridge reverse-map: legacy gl:multiplicity → MECE presence × count', () => {
+  it('compulsory → required + exactly_one', () => {
+    const doc = docWithRelation([
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.4' }, 'gl:multiplicity': 'compulsory' },
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.5' }, 'gl:multiplicity': 'compulsory' },
+    ]);
+    const members = loadPartitives(doc);
+    expect(members[0]).toEqual({ presence: 'required', count: 'exactly_one', is_delimiting: false });
+    expect(members[1]).toEqual({ presence: 'required', count: 'exactly_one', is_delimiting: false });
+  });
+
+  it('optional → optional + exactly_one', () => {
+    const doc = docWithRelation([
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.4' }, 'gl:multiplicity': 'optional' },
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.5' }, 'gl:multiplicity': 'compulsory' },
+    ]);
+    const members = loadPartitives(doc);
+    expect(members[0]).toEqual({ presence: 'optional', count: 'exactly_one', is_delimiting: false });
+  });
+
+  it('compulsory_multiple → required + multiple', () => {
+    const doc = docWithRelation([
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.4' }, 'gl:multiplicity': 'compulsory_multiple' },
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.5' }, 'gl:multiplicity': 'compulsory' },
+    ]);
+    const members = loadPartitives(doc);
+    expect(members[0]).toEqual({ presence: 'required', count: 'multiple', is_delimiting: false });
+  });
+
+  it('optional_multiple → optional + multiple', () => {
+    const doc = docWithRelation([
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.4' }, 'gl:multiplicity': 'optional_multiple' },
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.5' }, 'gl:multiplicity': 'compulsory' },
+    ]);
+    const members = loadPartitives(doc);
+    expect(members[0]).toEqual({ presence: 'optional', count: 'multiple', is_delimiting: false });
+  });
+
+  it('compulsory_at_least_one → required + at_least_one', () => {
+    const doc = docWithRelation([
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.4' }, 'gl:multiplicity': 'compulsory_at_least_one' },
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.5' }, 'gl:multiplicity': 'compulsory' },
+    ]);
+    const members = loadPartitives(doc);
+    expect(members[0]).toEqual({ presence: 'required', count: 'at_least_one', is_delimiting: false });
+  });
+
+  it('legacy gl:certainty confirmed → required + exactly_one (v2 wire)', () => {
+    const doc = docWithRelation([
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.4' }, 'gl:certainty': 'confirmed' },
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.5' }, 'gl:certainty': 'confirmed' },
+    ]);
+    const members = loadPartitives(doc);
+    expect(members[0]).toEqual({ presence: 'required', count: 'exactly_one', is_delimiting: false });
+  });
+
+  it('legacy gl:certainty possible → optional + exactly_one (v2 wire)', () => {
+    const doc = docWithRelation([
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.4' }, 'gl:certainty': 'possible' },
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.5' }, 'gl:certainty': 'confirmed' },
+    ]);
+    const members = loadPartitives(doc);
+    expect(members[0]).toEqual({ presence: 'optional', count: 'exactly_one', is_delimiting: false });
+  });
+});
+
+describe('bridge: native MECE gl:presence + gl:count passes through', () => {
+  it('presence=optional + count=multiple loads natively', () => {
+    const doc = docWithRelation([
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.4' }, 'gl:presence': 'optional', 'gl:count': 'multiple' },
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.5' }, 'gl:presence': 'required', 'gl:count': 'exactly_one' },
+    ]);
+    const members = loadPartitives(doc);
+    expect(members[0]).toEqual({ presence: 'optional', count: 'multiple', is_delimiting: false });
+    expect(members[1]).toEqual({ presence: 'required', count: 'exactly_one', is_delimiting: false });
+  });
+
+  it('gl:isDelimiting=true preserved', () => {
+    const doc = docWithRelation([
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.4' }, 'gl:isDelimiting': true },
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.5' } },
+    ]);
+    const members = loadPartitives(doc);
+    expect(members[0].is_delimiting).toBe(true);
+    expect(members[1].is_delimiting).toBe(false);
+  });
+});
+
+describe('bridge: defaults when no multiplicity fields present', () => {
+  it('member with no presence/count/multiplicity/certainty defaults to required + exactly_one', () => {
+    const doc = docWithRelation([
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.4' } },
+      { 'gl:ref': { 'gl:source': 'VIM', 'gl:id': '1.5' } },
+    ]);
+    const members = loadPartitives(doc);
+    expect(members[0]).toEqual({ presence: 'required', count: 'exactly_one', is_delimiting: false });
+  });
+});

package/src/__tests__/wire-keys.test.ts

@@ -0,0 +1,65 @@
+/**
+ * Wire-key SSOT contract.
+ *
+ * Audit-driven (AUDIT-2026-07-29 P1-3).
+ *
+ * The GL record is the single source of truth for the JSON-LD wire-format
+ * keys used across src/adapters/. This spec pins:
+ *
+ *   - Every entry is a string starting with 'gl:' (or '@' for JSON-LD core)
+ *   - No two entries share the same value (injectivity — one key, one name)
+ *   - The set of values matches what's declared in jsonld-types.ts
+ *     (catches drift if someone adds a key to one but not the other)
+ */
+import { describe, it, expect } from 'vitest';
+import { GL } from '../adapters/wire-keys';
+
+describe('GL wire-key SSOT', () => {
+  it('every value is a non-empty string', () => {
+    for (const value of Object.values(GL)) {
+      expect(typeof value).toBe('string');
+      expect(value.length).toBeGreaterThan(0);
+    }
+  });
+
+  it('every value starts with gl: or @ (JSON-LD namespace)', () => {
+    for (const value of Object.values(GL)) {
+      expect(value.startsWith('gl:') || value.startsWith('@')).toBe(true);
+    }
+  });
+
+  it('no two entries share the same value (injectivity)', () => {
+    const values = Object.values(GL);
+    expect(new Set(values).size).toBe(values.length);
+  });
+
+  it('MECE keys are present (presence, count, isDelimiting, multiplicity, certainty)', () => {
+    expect(GL.PRESENCE).toBe('gl:presence');
+    expect(GL.COUNT).toBe('gl:count');
+    expect(GL.IS_DELIMITING).toBe('gl:isDelimiting');
+    expect(GL.MULTIPLICITY).toBe('gl:multiplicity');
+    expect(GL.CERTAINTY).toBe('gl:certainty');
+  });
+
+  it('JSON-LD core keys are present', () => {
+    expect(GL.ID).toBe('@id');
+    expect(GL.TYPE).toBe('@type');
+  });
+
+  it('LOCAL_ID is distinct from ID (one is gl:id, the other @id)', () => {
+    // Both represent "id" but in different namespaces:
+    //   GL.ID (@id)        — JSON-LD IRI for the concept
+    //   GL.LOCAL_ID (gl:id) — source-local id within ConceptSource/Origin/Ref
+    expect(GL.ID).toBe('@id');
+    expect(GL.LOCAL_ID).toBe('gl:id');
+    expect(GL.ID).not.toBe(GL.LOCAL_ID);
+  });
+
+  it('count matches documented set (no drift)', () => {
+    // Update this number when adding a new key.
+    // The point of this test: when adding a key, you remember to update
+    // the count; when removing, you notice the test fails. Catches
+    // accidental drift in either direction.
+    expect(Object.keys(GL).length).toBe(87);
+  });
+});

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

@@ -0,0 +1,159 @@
+/**
+ * WeakMap bridges for fields not yet in glossarist-js's published d.ts.
+ *
+ * Each bridge attaches data the model doesn't expose via typed
+ * properties. Getters retrieve it; attachBridges() populates it after
+ * Concept.fromJSON creates the model instances.
+ *
+ * Remove each bridge when glossarist-js publishes native support
+ * (tracked by PR glossarist/glossarist-js#31 and BRIDGES.md).
+ */
+import {
+  Concept,
+  LocalizedConcept,
+  ConceptRef,
+  Citation,
+  DetailedDefinition,
+} from 'glossarist';
+
+// Annotations: LocalizedConcept.annotations
+const extraAnnotations = new WeakMap<LocalizedConcept, DetailedDefinition[]>();
+
+export function getAnnotations(lc: LocalizedConcept): DetailedDefinition[] {
+  return extraAnnotations.get(lc) ?? [];
+}
+
+// Designation relationship targets: RelatedConcept.target (string)
+const designationTargets = new WeakMap<object, string>();
+
+export function getDesignationTarget(rc: { type?: string | null; content?: string | null; target?: string | null; ref?: any }): string | null {
+  return designationTargets.get(rc) ?? rc.target ?? null;
+}
+
+// ConceptRef text: human-readable label alongside source/id
+const refTexts = new WeakMap<ConceptRef, string>();
+
+export function getRefText(ref: ConceptRef): string | null {
+  return refTexts.get(ref) ?? null;
+}
+
+// RelatedConcept.sourceId: links a citation reference back to its source entry
+const relatedSourceIds = new WeakMap<object, string>();
+
+export function getRelatedSourceId(rc: object): string | null {
+  return relatedSourceIds.get(rc) ?? null;
+}
+
+// RelatedConcept.citation: embedded citation data for cite-ref references
+const relatedCitations = new WeakMap<object, Record<string, unknown>>();
+
+export function getRelatedCitation(rc: object): Record<string, unknown> | null {
+  return relatedCitations.get(rc) ?? null;
+}
+
+// Relationship types whose target is a designation string, not a concept ref.
+export const DESIGNATION_REL_TYPES = new Set(['abbreviated_form_for', 'short_form_for']);
+
+export function attachSourcedFromToSources(
+  sources: readonly { sourced_from?: unknown }[],
+  rawSources: unknown,
+): void {
+  if (!Array.isArray(rawSources)) return;
+  for (let i = 0; i < sources.length && i < rawSources.length; i++) {
+    const raw = rawSources[i] as Record<string, unknown> | undefined;
+    if (raw?.sourced_from && Array.isArray(raw.sourced_from)) {
+      (sources[i] as { sourced_from: unknown }).sourced_from = raw.sourced_from.map(
+        (sf: unknown) => sf instanceof Citation ? sf : Citation.fromJSON(sf as Record<string, unknown>)
+      );
+    }
+  }
+}
+
+/**
+ * Attach bridged fields (ref text, sourceId, citation) to RelatedConcept instances
+ * from the raw deserialized data. Called after Concept.fromJSON creates the model
+ * instances, since RelatedConcept.fromJSON only reads type/content/ref.
+ */
+function attachRelatedBridges(
+  modelRelated: Array<{ type?: string | null; content?: Record<string, string> | string | null; ref?: any; related?: any[] }>,
+  rawRelated: unknown[],
+): void {
+  for (const rawRel of rawRelated) {
+    if (!rawRel || typeof rawRel !== 'object') continue;
+    const rel = rawRel as Record<string, unknown>;
+    const relType = rel.type as string | undefined;
+    const rc = relType ? modelRelated.find(r => r.type === relType) : undefined;
+    if (!rc) continue;
+
+    // Ref text
+    if (rc.ref) {
+      const rawRef = rel.ref as Record<string, unknown> | undefined;
+      if (rawRef?.text && typeof rawRef.text === 'string') {
+        refTexts.set(rc.ref, rawRef.text);
+      }
+    }
+
+    // Designation target
+    if (rel.target && typeof rel.target === 'string') {
+      designationTargets.set(rc, rel.target);
+    }
+
+    // Source ID — links citation reference back to the ConceptSource entry
+    if (rel.sourceId && typeof rel.sourceId === 'string') {
+      relatedSourceIds.set(rc, rel.sourceId);
+    }
+
+    // Citation — embedded origin data for cite-ref references
+    if (rel.citation && typeof rel.citation === 'object') {
+      relatedCitations.set(rc, rel.citation as Record<string, unknown>);
+    }
+  }
+}
+
+export function attachBridges(concept: Concept, localizations: Record<string, unknown>): void {
+  for (const lang of concept.languages) {
+    const lc = concept.localization(lang);
+    const raw = localizations[lang];
+    if (!lc || !raw || typeof raw !== 'object') continue;
+    const rawObj = raw as Record<string, unknown>;
+
+    // Attach sourced_from to localization-level sources
+    attachSourcedFromToSources(lc.sources as unknown as { sourced_from?: unknown }[], rawObj.sources);
+
+    // Annotations
+    const annList = rawObj.annotations;
+    if (Array.isArray(annList) && annList.length > 0) {
+      extraAnnotations.set(lc, annList.map((a: Record<string, unknown>) =>
+        DetailedDefinition.fromJSON({ content: (a.content as string) ?? '' }) as DetailedDefinition,
+      ));
+    }
+
+    // Designation-level relationship targets, ref text, sourceId, citation
+    const rawTerms = rawObj.terms;
+    if (Array.isArray(rawTerms)) {
+      for (let ti = 0; ti < rawTerms.length; ti++) {
+        const rawTerm = rawTerms[ti];
+        if (!rawTerm || typeof rawTerm !== 'object') continue;
+        const rawT = rawTerm as Record<string, unknown>;
+        const rawDesignation = rawT.designation as string | undefined;
+        if (!rawDesignation) continue;
+        const designation = lc.terms.find(d => d.designation === rawDesignation);
+        if (!designation) continue;
+        const rawRelated = rawT.related;
+        if (!Array.isArray(rawRelated)) continue;
+        attachRelatedBridges(designation.related, rawRelated);
+        // Attach sourced_from to designation-level sources
+        attachSourcedFromToSources(
+          designation.sources as unknown as { sourced_from?: unknown }[],
+          rawT.sources,
+        );
+      }
+    }
+
+    // Localization-level related concepts
+    const rawRelated = rawObj.related;
+    if (Array.isArray(rawRelated)) {
+      attachRelatedBridges(lc.related, rawRelated);
+    }
+  }
+}

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

@@ -0,0 +1,87 @@
+/**
+ * Top-level Concept loading: JSON-LD detection, Concept.fromJSON
+ * orchestration, summary projection, URI construction.
+ *
+ * This module is the orchestration layer — mappers, bridges, and
+ * partitive mapping live in their respective sibling modules.
+ */
+import { Concept } from 'glossarist';
+import type { ConceptSummary } from '../types';
+import { ConceptIdentity } from '../concept-identity';
+import { GL } from '../wire-keys';
+import { isJsonLd, mapLocalizedFromJsonLd, mapRelatedFromJsonLd } from './mappers';
+import { mapPartitiveRelationFromJsonLd } from './partitive';
+import { normalizeEntityRefs } from './entity-refs';
+import { attachBridges, attachSourcedFromToSources } from './bridges';
+import type { JsonLdConcept } from './jsonld-types';
+
+function conceptFromJsonLd(doc: JsonLdConcept): Concept {
+  const id = String(doc[GL.IDENTIFIER] ?? doc['@id']?.split('/').pop() ?? '');
+  const localizations: Record<string, unknown> = {};
+
+  const rawLc = doc[GL.LOCALIZED_CONCEPT] ?? {};
+  for (const [lang, lc] of Object.entries(rawLc)) {
+    if (lc && typeof lc === 'object') {
+      localizations[lang] = mapLocalizedFromJsonLd(lc);
+    }
+  }
+
+  const related = (doc[GL.RELATED] ?? []).map(mapRelatedFromJsonLd);
+  const partitiveRelations = (doc[GL.PARTITIVE_RELATIONS] ?? [])
+    .map(mapPartitiveRelationFromJsonLd)
+    .filter((r): r is Record<string, unknown> => r !== null);
+  const tagsArr = doc[GL.TAGS];
+  const tags = Array.isArray(tagsArr) ? [...tagsArr] : [];
+
+  const concept = Concept.fromJSON({
+    id,
+    term: doc[GL.TERM] ?? null,
+    uri: doc['@id'] ?? null,
+    localizations,
+    related,
+    partitive_relations: partitiveRelations,
+    tags,
+    figures: normalizeEntityRefs(doc[GL.FIGURE_REF]),
+    tables: normalizeEntityRefs(doc[GL.TABLE_REF]),
+    formulas: normalizeEntityRefs(doc[GL.FORMULA_REF]),
+    status: null,
+  });
+
+  attachBridges(concept, localizations);
+  return concept;
+}
+
+export function conceptFromJson(doc: Record<string, unknown>): Concept {
+  if (isJsonLd(doc)) {
+    return conceptFromJsonLd(doc as JsonLdConcept);
+  }
+  const concept = Concept.fromJSON(doc);
+  const locs = (doc as Record<string, unknown>).localizations as Record<string, unknown> | undefined;
+  if (locs) attachBridges(concept, locs);
+  attachSourcedFromToSources(
+    concept.sources as unknown as { sourced_from?: unknown }[],
+    (doc as Record<string, unknown>).sources,
+  );
+  return concept;
+}
+
+export function conceptToSummary(concept: Concept): ConceptSummary {
+  const designations: Record<string, string> = {};
+  for (const lang of concept.languages) {
+    const lc = concept.localization(lang);
+    if (lc?.primaryDesignation) {
+      designations[lang] = lc.primaryDesignation;
+    }
+  }
+  return {
+    id: concept.id,
+    designations,
+    eng: designations.eng || Object.values(designations)[0] || '',
+    status: concept.status ?? 'valid',
+  };
+}
+
+export function conceptUri(concept: Concept, registerId: string, uriBase: string): string {
+  if (concept.uri) return concept.uri;
+  return new ConceptIdentity(concept.id, registerId, uriBase).uri;
+}