@directory-builder/core 0.1.0 → 0.1.1

package/src/pipeline/steps/match.js

@@ -0,0 +1,212 @@
+import { sparqlSelect } from "@foerderfunke/sem-ops-utils"
+import { COMMON_PREFIXES, writeTurtleFile } from "../write-turtle.js"
+import { MAPPED_GRAPH } from "./map.js"
+import { CDP } from "../../utils.js"
+import { token_set_ratio } from "fuzzball"
+import { DataFactory } from "n3"
+import { createHash } from "crypto"
+
+const df = DataFactory
+
+export const MATCH_GRAPH = df.namedNode("urn:matched")
+export const HAS_MEMBER  = df.namedNode(CDP + "hasMember")
+
+const RDF_TYPE      = df.namedNode("http://www.w3.org/1999/02/22-rdf-syntax-ns#type")
+const MATCH_CLUSTER = df.namedNode(CDP + "MatchCluster")
+
+// token_set_ratio computes a ratio over the intersection of token sets, which
+// is robust to legal-form noise ("gGmbH", "e.V."), sub-unit specifiers, and
+// word-order variations. Returns 0–100; we normalise to 0–1. The algorithm
+// name is recorded in the evidence graph so old similarity numbers stay
+// interpretable across algorithm swaps.
+const SIMILARITY_ALGORITHM = "token_set_ratio"
+const similarity = (a, b) => token_set_ratio(a ?? "", b ?? "") / 100
+
+export const runMatch = async ({ store, defStore, abs }, outPath) => {
+    // One match rule per target schema; each rule scores its own fields, mints
+    // with its own prefix, and clusters only subjects of its :targetClass.
+    const rules = await sparqlSelect(`
+        PREFIX : <${CDP}>
+        SELECT ?match ?targetClass ?ns ?prefix ?minScore WHERE {
+            ?match a :MatchRule ;
+                :forTarget           ?target ;
+                :targetNamespace     ?ns ;
+                :mintedSubjectPrefix ?prefix .
+            ?target :targetClass ?targetClass .
+            OPTIONAL { ?match :minScore ?minScore }
+        } ORDER BY ?match`, [defStore])
+    if (!rules.length) throw new Error(":MatchRule config missing in federation.ttl")
+
+    const criteriaRows = await sparqlSelect(`
+        PREFIX : <${CDP}>
+        SELECT ?match ?on ?weight ?minSim WHERE {
+            ?match a :MatchRule ; :hasWeightedCriterion ?c .
+            ?c :on ?on ; :weight ?weight .
+            OPTIONAL { ?c :minSimilarity ?minSim }
+        }`, [defStore])
+    // Hard criteria: fields that must be identical in both records (pass/fail gates).
+    const hardRows = await sparqlSelect(`
+        PREFIX : <${CDP}>
+        SELECT ?match ?on WHERE {
+            ?match a :MatchRule ; :hasHardCriterion ?h . ?h :on ?on .
+        }`, [defStore])
+    // Criteria keyed by their owning rule, so each pass scores on its own fields.
+    const criteriaByMatch = new Map()
+    for (const r of criteriaRows) {
+        if (!criteriaByMatch.has(r.match)) criteriaByMatch.set(r.match, [])
+        criteriaByMatch.get(r.match).push({
+            pred:   df.namedNode(r.on),
+            weight: parseFloat(r.weight),
+            minSim: r.minSim != null ? parseFloat(r.minSim) : null,
+        })
+    }
+    const hardByMatch = new Map()
+    for (const r of hardRows) {
+        if (!hardByMatch.has(r.match)) hardByMatch.set(r.match, [])
+        hardByMatch.get(r.match).push({ pred: df.namedNode(r.on) })
+    }
+    // owl:sameAs assertions are shared; each pass only acts on the pairs whose
+    // endpoints are in its own subject set (gated by parent.has below).
+    const sameAsRows = await sparqlSelect(`
+        PREFIX owl: <http://www.w3.org/2002/07/owl#>
+        SELECT ?a ?b WHERE { ?a owl:sameAs ?b }`, [defStore])
+
+    const MATCH_EVIDENCE     = df.namedNode(CDP + "MatchEvidence")
+    const HAS_MATCH_EVIDENCE = df.namedNode(CDP + "hasMatchEvidence")
+    const PAIR               = df.namedNode(CDP + "pair")
+    const ON_CRITERION       = df.namedNode(CDP + "onCriterion")
+    const ON                 = df.namedNode(CDP + "on")
+    const SIMILARITY         = df.namedNode(CDP + "similarity")
+    const SIM_ALGORITHM      = df.namedNode(CDP + "similarityAlgorithm")
+    const WEIGHT             = df.namedNode(CDP + "weight")
+    const VALUE_A            = df.namedNode(CDP + "valueA")
+    const VALUE_B            = df.namedNode(CDP + "valueB")
+    const AGGREGATE_SCORE    = df.namedNode(CDP + "aggregateScore")
+    const VIA_MANUAL_MATCH   = df.namedNode(CDP + "viaManualMatch")
+    const XSD_DECIMAL        = df.namedNode("http://www.w3.org/2001/XMLSchema#decimal")
+    const XSD_BOOLEAN        = df.namedNode("http://www.w3.org/2001/XMLSchema#boolean")
+
+    for (const rule of rules) {
+        const namespace    = rule.ns
+        const mintedPrefix = rule.prefix
+        const minScore     = parseFloat(rule.minScore)
+        const hard     = hardByMatch.get(rule.match) ?? []
+        const weighted = criteriaByMatch.get(rule.match) ?? []
+
+        // Subjects of this rule's target class only — passes never cross types.
+        const subjects = [...new Set(store.getQuads(null, RDF_TYPE, df.namedNode(rule.targetClass), MAPPED_GRAPH)
+            .filter(qu => qu.subject.termType === "NamedNode")
+            .map(qu => qu.subject.value))]
+
+        const valOf = (s, pred) => {
+            const qs = store.getQuads(df.namedNode(s), pred, null, MAPPED_GRAPH)
+            return qs.length ? qs[0].object.value : null
+        }
+        const hardVals     = new Map(subjects.map(s => [s, hard.map(h => valOf(s, h.pred))]))
+        const weightedVals = new Map(subjects.map(s => [s, weighted.map(c => valOf(s, c.pred))]))
+
+        // A pair matches when every hard criterion is present and identical in both,
+        // and the weighted criteria's aggregate (sum of sim·weight, each optionally
+        // floored by :minSimilarity) clears :minScore. No criteria at all → every
+        // subject stays its own cluster.
+        const matches = (a, b) => {
+            if (!hard.length && !weighted.length) return null
+            const ha = hardVals.get(a), hb = hardVals.get(b)
+            for (let i = 0; i < hard.length; i++) {
+                if (ha[i] == null || hb[i] == null || ha[i] !== hb[i]) return null
+            }
+            const va = weightedVals.get(a), vb = weightedVals.get(b)
+            const scores = []
+            let weightedSum = 0
+            for (let i = 0; i < weighted.length; i++) {
+                if (va[i] == null || vb[i] == null) return null
+                const c = weighted[i]
+                const sim = similarity(va[i], vb[i])
+                if (c.minSim != null && sim < c.minSim) return null
+                scores.push({ pred: c.pred, sim, weight: c.weight, valueA: va[i], valueB: vb[i] })
+                weightedSum += sim * c.weight
+            }
+            if (weighted.length && weightedSum < minScore) return null
+            return { scores, aggregate: weightedSum }
+        }
+
+        const parent = new Map(subjects.map(s => [s, s]))
+        const find = (x) => {
+            let r = x
+            while (parent.get(r) !== r) r = parent.get(r)
+            let c = x
+            while (parent.get(c) !== r) { const n = parent.get(c); parent.set(c, r); c = n }
+            return r
+        }
+        const union = (a, b) => {
+            const ra = find(a), rb = find(b)
+            if (ra !== rb) parent.set(ra, rb)
+        }
+
+        const evidence = []
+        let sameAsUnions = 0
+        for (const { a, b } of sameAsRows) {
+            if (parent.has(a) && parent.has(b)) { union(a, b); sameAsUnions++; evidence.push({ a, b, manual: true }) }
+        }
+
+        for (let i = 0; i < subjects.length; i++) {
+            for (let j = i + 1; j < subjects.length; j++) {
+                const m = matches(subjects[i], subjects[j])
+                if (m) { union(subjects[i], subjects[j]); evidence.push({ a: subjects[i], b: subjects[j], ...m }) }
+            }
+        }
+
+        const clusters = new Map()
+        for (const s of subjects) {
+            const root = find(s)
+            if (!clusters.has(root)) clusters.set(root, [])
+            clusters.get(root).push(s)
+        }
+        const clusterMembers = [...clusters.values()]
+            .map(m => [...m].sort())
+            .sort((a, b) => b.length - a.length || a[0].localeCompare(b[0]))
+
+        let multiSource = 0
+        const clusterIriByRoot = new Map()
+        for (const members of clusterMembers) {
+            const id = createHash("sha1").update(members.join("|")).digest("hex").slice(0, 12)
+            const minted = df.namedNode(namespace + mintedPrefix + id)
+            clusterIriByRoot.set(find(members[0]), minted)
+            if (members.length > 1) multiSource++
+            store.addQuad(df.quad(minted, RDF_TYPE, MATCH_CLUSTER, MATCH_GRAPH))
+            for (const s of members) {
+                store.addQuad(df.quad(minted, HAS_MEMBER, df.namedNode(s), MATCH_GRAPH))
+            }
+        }
+
+        for (const ev of evidence) {
+            const evNode = df.blankNode()
+            const cluster = clusterIriByRoot.get(find(ev.a))
+            store.addQuad(df.quad(cluster, HAS_MATCH_EVIDENCE, evNode, MATCH_GRAPH))
+            store.addQuad(df.quad(evNode, RDF_TYPE, MATCH_EVIDENCE, MATCH_GRAPH))
+            store.addQuad(df.quad(evNode, PAIR, df.namedNode(ev.a), MATCH_GRAPH))
+            store.addQuad(df.quad(evNode, PAIR, df.namedNode(ev.b), MATCH_GRAPH))
+            if (ev.manual) {
+                store.addQuad(df.quad(evNode, VIA_MANUAL_MATCH, df.literal("true", XSD_BOOLEAN), MATCH_GRAPH))
+            } else {
+                store.addQuad(df.quad(evNode, AGGREGATE_SCORE, df.literal(ev.aggregate.toFixed(3), XSD_DECIMAL), MATCH_GRAPH))
+                store.addQuad(df.quad(evNode, SIM_ALGORITHM, df.literal(SIMILARITY_ALGORITHM), MATCH_GRAPH))
+                for (const s of ev.scores) {
+                    const cNode = df.blankNode()
+                    store.addQuad(df.quad(evNode, ON_CRITERION, cNode, MATCH_GRAPH))
+                    store.addQuad(df.quad(cNode, ON, s.pred, MATCH_GRAPH))
+                    store.addQuad(df.quad(cNode, SIMILARITY, df.literal(s.sim.toFixed(3), XSD_DECIMAL), MATCH_GRAPH))
+                    store.addQuad(df.quad(cNode, WEIGHT, df.literal(s.weight.toFixed(2), XSD_DECIMAL), MATCH_GRAPH))
+                    store.addQuad(df.quad(cNode, VALUE_A, df.literal(s.valueA), MATCH_GRAPH))
+                    store.addQuad(df.quad(cNode, VALUE_B, df.literal(s.valueB), MATCH_GRAPH))
+                }
+            }
+        }
+
+        console.log(`match: ${rule.match.split("#").pop()} ${subjects.length} entities → ${clusters.size} clusters (${multiSource} multi-source, ${sameAsUnions} sameAs unions)`)
+    }
+
+    const matchQuads = store.getQuads(null, null, null, MATCH_GRAPH)
+    await writeTurtleFile(abs(outPath), matchQuads, { cdp: CDP, cdf: rules[0].ns, ...COMMON_PREFIXES })
+    console.log(`match: wrote cluster log → ${outPath}`)
+}

package/src/pipeline/steps/merge.js

@@ -0,0 +1,59 @@
+import { sparqlSelect } from "@foerderfunke/sem-ops-utils"
+import { COMMON_PREFIXES, writeTurtleFile } from "../write-turtle.js"
+import { HAS_MEMBER, MATCH_GRAPH } from "./match.js"
+import { MAPPED_GRAPH } from "./map.js"
+import { CDP } from "../../utils.js"
+import { DataFactory } from "n3"
+
+const df = DataFactory
+
+export const MERGED_GRAPH = df.namedNode("urn:merged")
+
+const RDF_REIFIES = df.namedNode("http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies")
+
+export const runMerge = async ({ store, defStore, abs }, outPath, provOutPath) => {
+    const [cfg] = await sparqlSelect(`
+        PREFIX : <${CDP}>
+        SELECT ?ns ?originPred WHERE {
+            ?match a :MatchRule ; :targetNamespace ?ns .
+            ?merge a :MergeRule ; :originPredicate ?originPred .
+        }`, [defStore])
+    if (!cfg) throw new Error(":MergeRule / :MatchRule config missing in federation.ttl")
+    const { ns: namespace, originPred } = cfg
+
+    const memberQuads = store.getQuads(null, HAS_MEMBER, null, MATCH_GRAPH)
+    const mintedFor = new Map()
+    for (const mq of memberQuads) mintedFor.set(mq.object.value, mq.subject)
+
+    const fedQuads = store.getQuads(null, null, null, MAPPED_GRAPH)
+    const originPredNode = df.namedNode(originPred)
+    const provQuads = []
+    for (const qu of fedQuads) {
+        const minted = mintedFor.get(qu.subject.value)
+        if (!minted) continue
+        // Rewrite IRI objects that are themselves matched subjects to their minted
+        // cluster IRI, so inter-entity links (e.g. schema:provider) point at the
+        // merged entity rather than the pre-merge source IRI.
+        const object = qu.object.termType === "NamedNode" && mintedFor.has(qu.object.value)
+            ? mintedFor.get(qu.object.value)
+            : qu.object
+        store.addQuad(df.quad(minted, qu.predicate, object, MERGED_GRAPH))
+        // One reifier per derivation occurrence (RDF 1.2: triple terms are only
+        // legal as objects, via rdf:reifies) — the provenance hangs off it, and
+        // per-derivation metadata (time, confidence) has a home when needed.
+        const reifier = df.blankNode()
+        provQuads.push(df.quad(reifier, RDF_REIFIES, df.quad(minted, qu.predicate, object)))
+        provQuads.push(df.quad(reifier, originPredNode, qu.subject))
+    }
+
+    const mergedQuads = store.getQuads(null, null, null, MERGED_GRAPH)
+
+    await writeTurtleFile(abs(outPath), mergedQuads, { ...COMMON_PREFIXES, cdp: CDP, cdf: namespace })
+    console.log(`merge: wrote ${mergedQuads.length} triples → ${outPath}`)
+
+    await writeTurtleFile(abs(provOutPath), provQuads, {
+        ...COMMON_PREFIXES, cdp: CDP, cdf: namespace, prov: "http://www.w3.org/ns/prov#",
+        rdf: "http://www.w3.org/1999/02/22-rdf-syntax-ns#",
+    })
+    console.log(`merge: wrote ${provQuads.length / 2} provenance annotations → ${provOutPath}`)
+}

package/src/pipeline/steps/resolve.js

@@ -0,0 +1,54 @@
+import { sparqlSelect } from "@foerderfunke/sem-ops-utils"
+import { COMMON_PREFIXES, writeTurtleFile } from "../write-turtle.js"
+import { MERGED_GRAPH } from "./merge.js"
+import { CDP } from "../../utils.js"
+import { DataFactory } from "n3"
+
+const df = DataFactory
+
+// One value per (subject, predicate). schema:identifier and cdp:fromSource
+// are dropped — final.ttl is the consumer-facing artifact, source attribution
+// lives in provenance.ttl.
+const STRATEGIES = {
+    alphabeticFirst: (quads) => [...quads].sort((a, b) => a.object.value.localeCompare(b.object.value))[0],
+    concatenateAll:  (quads) => df.quad(quads[0].subject, quads[0].predicate,
+        df.literal([...new Set(quads.map(q => q.object.value))].sort().join(", "))),
+}
+const RESOLVE_EXCLUDE = new Set(["http://schema.org/identifier", `${CDP}fromSource`])
+
+const lookupStrategy = (iri) => {
+    const fn = STRATEGIES[iri.split("#").pop()]
+    if (!fn) throw new Error(`Unknown resolve strategy ${iri}`)
+    return fn
+}
+
+export const runResolve = async ({ store, defStore, abs }, outPath) => {
+    const [cfg] = await sparqlSelect(`
+        PREFIX : <${CDP}>
+        SELECT ?strategy ?ns WHERE {
+            ?resolve a :ResolveRule ; :defaultStrategy ?strategy .
+            ?match   a :MatchRule   ; :targetNamespace ?ns .
+        }`, [defStore])
+    if (!cfg) throw new Error(":ResolveRule config missing in federation.ttl")
+    const defaultPick = lookupStrategy(cfg.strategy)
+
+    const overrideRows = await sparqlSelect(`
+        PREFIX : <${CDP}>
+        SELECT ?on ?strategy WHERE {
+            ?resolve a :ResolveRule ; :hasOverride [ :on ?on ; :strategy ?strategy ] .
+        }`, [defStore])
+    const overrides = new Map(overrideRows.map(r => [r.on, lookupStrategy(r.strategy)]))
+
+    const groups = new Map()
+    for (const q of store.getQuads(null, null, null, MERGED_GRAPH)) {
+        if (RESOLVE_EXCLUDE.has(q.predicate.value)) continue
+        const k = `${q.subject.value}\t${q.predicate.value}`
+        if (!groups.has(k)) groups.set(k, [])
+        groups.get(k).push(q)
+    }
+    const finalQuads = [...groups.values()].map(quads =>
+        (overrides.get(quads[0].predicate.value) ?? defaultPick)(quads))
+
+    await writeTurtleFile(abs(outPath), finalQuads, { ...COMMON_PREFIXES, cdf: cfg.ns })
+    console.log(`resolve: wrote ${finalQuads.length} triples → ${outPath}`)
+}

package/src/pipeline/write-turtle.js

@@ -0,0 +1,30 @@
+import { newStore } from "@foerderfunke/sem-ops-utils"
+import { DataFactory, Writer } from "n3"
+import path from "path"
+import fs from "fs"
+
+const df = DataFactory
+
+export const COMMON_PREFIXES = {
+    schema: "http://schema.org/",
+    foaf:   "http://xmlns.com/foaf/0.1/",
+    dct:    "http://purl.org/dc/terms/",
+}
+
+// Dedupe via a Store and sort by subject so the Writer can emit grouped
+// "subject p1 o1; p2 o2." blocks instead of repeating subjects. Strips
+// graph names (writes triples, not quads).
+export const writeTurtleFile = (filePath, quads, prefixes = {}) => new Promise((resolve, reject) => {
+    const store = newStore()
+    for (const q of quads) store.addQuad(df.quad(q.subject, q.predicate, q.object))
+    const dedup = store.getQuads(null, null, null, null)
+        .sort((a, b) => a.subject.value.localeCompare(b.subject.value))
+    const writer = new Writer({ prefixes })
+    for (const q of dedup) writer.addQuad(q)
+    writer.end((err, result) => {
+        if (err) return reject(err)
+        fs.mkdirSync(path.dirname(filePath), { recursive: true })
+        fs.writeFileSync(filePath, result)
+        resolve()
+    })
+})

package/src/pipeline.js

@@ -1,5 +1,5 @@
-import { ingest } from "./ingest.js"
-import { federate } from "./federate.js"
+import { ingest } from "./pipeline/ingest.js"
+import { federate } from "./pipeline/federate.js"
 
 // Programmatic entry: hold the instance root once, run the engines against it.
 // The CLI (bin/cli.js) is this same class with defaults — root = cwd.

package/src/utils.js

@@ -57,6 +57,7 @@ export const PATHS = {
     federation:     "config/federation.ttl",
     matchKnowledge: "config/match-knowledge.ttl",
     about:          "webapp/content/about.md",
+    query:          "webapp/content/query.sparql",
     fetchScript: (name) => `sources/${name}/fetch.js`,
     exporter:    (name) => `webapp/exporters/${name}.js`,
     staticDir:   (name) => `sources/${name}/static/`,
@@ -87,11 +88,6 @@ export const parseTtl = (turtle) => new Parser().parse(turtle)
 export const prefixesOf = (turtle) =>
     Object.fromEntries([...turtle.matchAll(/^\s*@?prefix\s+([\w-]*):\s*<([^>]*)>/gim)].map(([, p, ns]) => [p, ns]))
 
-// Turtle with RDF-star triple terms in subject position (the engine's
-// provenance annotations) — plain Turtle parsing disallows those, N3 mode
-// accepts them.
-export const parseTtlStar = (turtle) => new Parser({ format: "text/n3" }).parse(turtle)
-
 // {prefix: namespace} → "PREFIX p1: <ns1>\nPREFIX p2: <ns2>"
 export const buildPrefixBlock = (prefixMap) =>
     Object.entries(prefixMap).map(([p, ns]) => `PREFIX ${p}: <${ns}>`).join("\n")

package/webapp/src/App.jsx

@@ -1,6 +1,6 @@
 import { HashRouter, Routes, Route, NavLink } from "react-router-dom"
 import "./styles.css"
-import { repositoryUrl } from "./instanceData.js"
+import { federationLabel, repositoryUrl } from "./instanceData.js"
 import About from "./About.jsx"
 import React, { lazy, Suspense, useState } from "react"
 
@@ -16,6 +16,8 @@ const MergeTables = lazy(() => import("./MergeTables.jsx"))
 const Query       = lazy(() => import("./Query.jsx"))
 const Sources     = lazy(() => import("./Sources.jsx"))
 
+if (federationLabel) document.title = federationLabel
+
 const STORAGE_KEY = "showFederation"
 
 const initialShowFed = () => {

package/webapp/src/Card.jsx

@@ -1,13 +1,13 @@
 // Presentational building blocks: <Card> (titled box) and <KeyValueTable>.
 // Reads:  props (title, children, rows)
-// Does:   renders DOM; used by OrgCard and Sources
+// Does:   renders DOM; used by EntityCard and Sources
 
 import React from "react"
 
 export default function Card({ title, tag, children }) {
     return (
-        <div className="org-card">
-            <div className="org-card-header">
+        <div className="entity-card">
+            <div className="entity-card-header">
                 <code>{title}</code>
                 {tag && <span style={{ marginLeft: "0.6rem", fontSize: 11, color: "#888", fontFamily: "monospace" }}>{tag}</span>}
             </div>

package/webapp/src/ColumnGraph.jsx

@@ -246,7 +246,7 @@ export default function ColumnGraph({ nodes, edges, columns, colors, centerColum
     const [draggingId, setDraggingId] = useState(null)
     const [hoveredEdge, setHoveredEdge] = useState(null)
     const hoverCtx = useMemo(() => ({ id: hoveredEdge, set: setHoveredEdge }), [hoveredEdge])
-    // Sync edges when value labels change (e.g. selecting a different org) so
+    // Sync edges when value labels change (e.g. selecting a different entity) so
     // the user keeps any node positions they've dragged.
     useEffect(() => { setRfEdges(flowEdges) }, [flowEdges, setRfEdges])
 

package/webapp/src/Directory.jsx

@@ -1,15 +1,15 @@
-// Consumer-facing directory: one compact card per resolved organisation.
-// Reads:  finalOrgs from mergeOrgs.js (← data/pipeline/final.ttl)
-// Does:   renders the Directory page (list of compact <OrgCard>)
+// Consumer-facing directory: one compact card per resolved entity.
+// Reads:  finalEntities from mergeEntities.js (← data/pipeline/final.ttl)
+// Does:   renders the Directory page (list of compact <EntityCard>)
 
-import OrgCard from "./OrgCard.jsx"
-import { finalOrgs } from "./mergeOrgs.js"
+import EntityCard from "./EntityCard.jsx"
+import { finalEntities } from "./mergeEntities.js"
 import React from "react"
 
 export default function Directory() {
     return (
         <div className="page" style={{ overflowY: "auto", height: "100%" }}>
-            {finalOrgs.map((org) => <OrgCard key={org.iri} org={org} compact={true} highlight={false} />)}
+            {finalEntities.map((entity) => <EntityCard key={entity.iri} entity={entity} compact={true} highlight={false} />)}
         </div>
     )
 }

package/webapp/src/{OrgCard.jsx → EntityCard.jsx}

@@ -1,8 +1,8 @@
-// Renders one organisation as a card (narrow key/value, or wide per-source table)
+// Renders one entity as a card (narrow key/value, or wide per-source table)
 // with source tags and conflict highlighting. Also exports the conflict helpers.
 // Reads:  config/federation.ttl, data/ingest/ingest-log.ttl (via sourceMeta.js);
-//         org objects from loadMerge.js
-// Does:   renders <OrgCard>; exports EXPECTED_MULTI, isConflict (used by mergeOrgs, MergeTables)
+//         entity objects from loadMerge.js
+// Does:   renders <EntityCard>; exports EXPECTED_MULTI, isConflict (used by mergeEntities, MergeTables)
 
 import { federationTtl, ingestLogTtl as logTtl } from "./instanceData.js"
 import Card, { KeyValueTable } from "./Card.jsx"
@@ -10,7 +10,7 @@ import { loadHarvestBySource, loadSourceMeta } from "./sourceMeta.js"
 import { CDP, parseTtl } from "@directory-builder/core/utils"
 import React, { useState } from "react"
 
-// org.columns are one entry per contributing record (resolved in loadMerge); look
+// entity.columns are one entry per contributing record (resolved in loadMerge); look
 // up source display data in config (notation, label) and the harvest log (time).
 const sourceMeta = loadSourceMeta(federationTtl)
 const harvestBySource = loadHarvestBySource(logTtl)
@@ -81,12 +81,12 @@ function ValueCell({ values, highlight }) {
     )
 }
 
-function OrgCardNarrow({ org, highlight }) {
-    return <KeyValueTable rows={org.fields.map((f) => ({ key: f.predicate, label: f.predLabel, value: <ValueCell values={f.values} highlight={highlight && isConflict(f)} /> }))} />
+function EntityCardNarrow({ entity, highlight }) {
+    return <KeyValueTable rows={entity.fields.map((f) => ({ key: f.predicate, label: f.predLabel, value: <ValueCell values={f.values} highlight={highlight && isConflict(f)} /> }))} />
 }
 
-function OrgCardWide({ org, highlight }) {
-    const columns = org.columns
+function EntityCardWide({ entity, highlight }) {
+    const columns = entity.columns
     return (
         <table>
             <thead>
@@ -100,7 +100,7 @@ function OrgCardWide({ org, highlight }) {
                 </tr>
             </thead>
             <tbody>
-                {org.fields.map((f) => {
+                {entity.fields.map((f) => {
                     const conflict = highlight && isConflict(f) ? conflictStyle(f.values.length) : undefined
                     return (
                         <tr key={f.predicate}>
@@ -117,10 +117,10 @@ function OrgCardWide({ org, highlight }) {
     )
 }
 
-export default function OrgCard({ org, compact, highlight }) {
+export default function EntityCard({ entity, compact, highlight }) {
     return (
-        <Card title={org.label} tag={org.type}>
-            {compact ? <OrgCardNarrow org={org} highlight={highlight} /> : <OrgCardWide org={org} highlight={highlight} />}
+        <Card title={entity.label} tag={entity.type}>
+            {compact ? <EntityCardNarrow entity={entity} highlight={highlight} /> : <EntityCardWide entity={entity} highlight={highlight} />}
         </Card>
     )
 }

package/webapp/src/MapGraph.jsx

@@ -1,11 +1,11 @@
 // Map view: the source-schema → target-schema mapping graph, optionally animated
-// with one org's field values flowing through the transform nodes.
+// with one entity's field values flowing through the transform nodes.
 // Reads:  config/federation.ttl, data/pipeline/mapped.ttl,
 //         data/pipeline/cleaned/*.ttl (via loadMap.js + sourceMeta.js)
 // Does:   renders the Map page (horizontal <ColumnGraph>)
 
 import { federationTtl as ttl, mappedTtl, cleanedByPath } from "./instanceData.js"
-import { loadMap, loadSources, loadOrgsBySource, loadFieldValuesByOrg } from "./loadMap.js"
+import { loadMap, loadSources, loadEntitiesBySource, loadFieldValuesByEntity } from "./loadMap.js"
 import React, { useEffect, useMemo, useRef, useState } from "react"
 import { loadCleanedBySource } from "./sourceMeta.js"
 import { SkipBack, SkipForward } from "lucide-react"
@@ -27,10 +27,10 @@ const VALUE_LABEL_BG = {
 }
 
 const SOURCES = loadSources(ttl)
-const ORGS_BY_SOURCE = loadOrgsBySource(ttl, mappedTtl)
+const ENTITIES_BY_SOURCE = loadEntitiesBySource(ttl, mappedTtl)
 // Source-to-file mapping is resolved from config: instanceData enumerates the
 // cleaned TTLs from :hasSource, so a new source needs no edit here.
-const FIELD_VALUES = loadFieldValuesByOrg(ttl, mappedTtl, loadCleanedBySource(ttl, cleanedByPath))
+const FIELD_VALUES = loadFieldValuesByEntity(ttl, mappedTtl, loadCleanedBySource(ttl, cleanedByPath))
 
 function SourcesDropdown({ visible, onChange }) {
     const [open, setOpen] = useState(false)
@@ -81,7 +81,7 @@ function SourcesDropdown({ visible, onChange }) {
     )
 }
 
-function OrgCombobox({ orgs, value, onChange, disabled }) {
+function EntityCombobox({ entities, value, onChange, disabled }) {
     const [open, setOpen] = useState(false)
     const [filter, setFilter] = useState("")
     const ref = useRef(null)
@@ -93,9 +93,9 @@ function OrgCombobox({ orgs, value, onChange, disabled }) {
         return () => document.removeEventListener("mousedown", onDown)
     }, [open])
 
-    const selected = orgs.find(o => o.iri === value)
+    const selected = entities.find(o => o.iri === value)
     const f = filter.toLowerCase()
-    const filtered = f ? orgs.filter(o => o.id.toLowerCase().includes(f) || o.name.toLowerCase().includes(f)) : orgs
+    const filtered = f ? entities.filter(o => o.id.toLowerCase().includes(f) || o.name.toLowerCase().includes(f)) : entities
 
     return (
         <div ref={ref} style={{ position: "relative" }}>
@@ -103,7 +103,7 @@ function OrgCombobox({ orgs, value, onChange, disabled }) {
                 type="text"
                 disabled={disabled}
                 value={open ? filter : (selected?.name || selected?.id || "")}
-                placeholder={disabled ? "" : "Pick organisation…"}
+                placeholder={disabled ? "" : "Pick entity…"}
                 onChange={(e) => { setFilter(e.target.value); if (!open) setOpen(true) }}
                 onFocus={() => { setFilter(""); setOpen(true) }}
                 style={{
@@ -137,7 +137,7 @@ function OrgCombobox({ orgs, value, onChange, disabled }) {
 
 export default function MapGraph() {
     const [visible, setVisible] = useState(() => new Set(SOURCES.map(s => s.iri)))
-    const [selectedOrg, setSelectedOrg] = useState(null)
+    const [selectedEntity, setSelectedEntity] = useState(null)
     const [dataFlow, setDataFlow] = useState(false)
     const [showUnmapped, setShowUnmapped] = useState(false)
     const [showAllTargets, setShowAllTargets] = useState(false)
@@ -150,7 +150,7 @@ export default function MapGraph() {
 
     const oneActive = visible.size === 1
     const enabled = dataFlow && oneActive
-    const valueByField = enabled && selectedOrg ? FIELD_VALUES.get(selectedOrg) : null
+    const valueByField = enabled && selectedEntity ? FIELD_VALUES.get(selectedEntity) : null
     const edges = useMemo(() => {
         if (!valueByField) return rawEdges
         const typeOf = new Map(nodes.map(n => [n.id, n.type]))
@@ -171,29 +171,29 @@ export default function MapGraph() {
     }, [rawEdges, nodes, valueByField, showDirectFlows])
 
     // Remount when the visible node set changes (sources or unmapped-fields
-    // toggle). Org / data-flow changes only update edge labels in place.
+    // toggle). Entity / data-flow changes only update edge labels in place.
     const graphKey = useMemo(() => `${[...visible].sort().join("|")}::${showUnmapped ? "all" : "mapped"}::${showAllTargets ? "allT" : "mappedT"}`, [visible, showUnmapped, showAllTargets])
 
     const activeSource = oneActive ? [...visible][0] : null
-    const orgs = activeSource ? (ORGS_BY_SOURCE.get(activeSource) ?? []) : []
+    const entities = activeSource ? (ENTITIES_BY_SOURCE.get(activeSource) ?? []) : []
 
     useEffect(() => {
-        if (orgs.length > 0) {
-            if (!orgs.find(o => o.iri === selectedOrg)) setSelectedOrg(orgs[0].iri)
-        } else if (selectedOrg !== null) {
-            setSelectedOrg(null)
+        if (entities.length > 0) {
+            if (!entities.find(o => o.iri === selectedEntity)) setSelectedEntity(entities[0].iri)
+        } else if (selectedEntity !== null) {
+            setSelectedEntity(null)
         }
-    }, [orgs])
+    }, [entities])
 
     useEffect(() => {
         if (!oneActive && dataFlow) setDataFlow(false)
     }, [oneActive])
 
     const cycle = (delta) => {
-        if (orgs.length === 0) return
-        const idx = orgs.findIndex(o => o.iri === selectedOrg)
-        const next = ((idx < 0 ? 0 : idx + delta) + orgs.length) % orgs.length
-        setSelectedOrg(orgs[next].iri)
+        if (entities.length === 0) return
+        const idx = entities.findIndex(o => o.iri === selectedEntity)
+        const next = ((idx < 0 ? 0 : idx + delta) + entities.length) % entities.length
+        setSelectedEntity(entities[next].iri)
     }
 
     const disabledHint = !dataFlow
@@ -232,7 +232,7 @@ export default function MapGraph() {
                 </label>
                 <div style={{ display: "flex", alignItems: "center", gap: "0.25rem" }}>
                     <button disabled={!enabled} onClick={() => cycle(-1)} title={enabled ? "Previous" : disabledHint} style={iconBtnStyle}><SkipBack size={13} fill="currentColor" /></button>
-                    <OrgCombobox orgs={orgs} value={selectedOrg} onChange={setSelectedOrg} disabled={!enabled} />
+                    <EntityCombobox entities={entities} value={selectedEntity} onChange={setSelectedEntity} disabled={!enabled} />
                     <button disabled={!enabled} onClick={() => cycle(1)} title={enabled ? "Next" : disabledHint} style={iconBtnStyle}><SkipForward size={13} fill="currentColor" /></button>
                 </div>
             </div>