@hippo-digital/hippocampus 1.0.0-rc.1

package/lib/load-knowledge.js

@@ -0,0 +1,629 @@
+const fs = require('fs')
+const path = require('path')
+const { KnowledgeSchema } = require('./schema')
+const { readMeta, migrateInMemory } = require('./schema-version')
+
+const files = {
+  project: 'project.json',
+  projectContext: 'project-context.json',
+  users: 'users.json',
+  needs: 'needs.json',
+  scenarios: 'scenarios.json',
+  journeys: 'journeys.json',
+  screens: 'screens.json',
+  evidence: 'evidence.json',
+  decisions: 'decisions.json',
+  assumptions: 'assumptions.json',
+  researchRounds: 'research-rounds.json',
+  participants: 'participants.json',
+  insights: 'insights.json',
+  designActions: 'design-actions.json',
+  relationships: 'relationships.json'
+}
+
+function createKnowledgeStore (paths) {
+function readJson (filename) {
+  return JSON.parse(fs.readFileSync(path.join(paths.knowledgeSourceDir, filename), 'utf8'))
+}
+
+// A collection file that does not exist yet is an empty collection, not a
+// crash. A freshly initialised project has project.json and little else, and
+// every command it might run should still work.
+function readCollection (filename) {
+  const filePath = path.join(paths.knowledgeSourceDir, filename)
+  if (!fs.existsSync(filePath)) return []
+  return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+}
+
+// A project that has been initialised but never had its context imported gets a
+// stub derived from project.json rather than a missing-file error. The viewer
+// then shows an almost-empty context page, which is the truth.
+function readProjectContext (filename, project) {
+  const filePath = path.join(paths.knowledgeSourceDir, filename)
+  if (fs.existsSync(filePath)) return JSON.parse(fs.readFileSync(filePath, 'utf8'))
+  return {
+    id: `${project.id}-context`,
+    title: project.name,
+    summary: project.description
+  }
+}
+
+function loadKnowledgeData () {
+  const knowledge = {}
+  for (const [key, filename] of Object.entries(files)) {
+    if (key === 'project') knowledge[key] = readJson(filename)
+    else if (key === 'projectContext') knowledge[key] = readProjectContext(filename, knowledge.project)
+    else knowledge[key] = readCollection(filename)
+  }
+  return knowledge
+}
+
+function getKnowledge () {
+  const meta = readMeta(paths.knowledgeSourceDir)
+  const { data, version, warnings } = migrateInMemory(loadKnowledgeData(), meta)
+  const knowledge = KnowledgeSchema.parse(data)
+  knowledge.meta = { schemaVersion: version, implicit: meta.implicit, warnings }
+  knowledge.index = buildIndex(knowledge)
+  return knowledge
+}
+
+function buildIndex (knowledge) {
+  const index = {
+    users: byId(knowledge.users),
+    needs: byId(knowledge.needs),
+    scenarios: byId(knowledge.scenarios),
+    journeys: byId(knowledge.journeys),
+    screens: byId(knowledge.screens),
+    evidence: byId(knowledge.evidence),
+    decisions: byId(knowledge.decisions),
+    assumptions: byId(knowledge.assumptions),
+    researchRounds: byId(knowledge.researchRounds),
+    participants: byId(knowledge.participants),
+    insights: byId(knowledge.insights),
+    designActions: byId(knowledge.designActions),
+    relationships: byId(knowledge.relationships)
+  }
+  index.entities = buildEntityIndex(knowledge)
+  return index
+}
+
+function byId (items) {
+  return Object.fromEntries(items.map((item) => [item.id, item]))
+}
+
+function buildEntityIndex (knowledge) {
+  const entityCollections = {
+    users: { type: 'User', labelKey: 'label' },
+    needs: { type: 'Need', labelKey: 'statement' },
+    scenarios: { type: 'Scenario', labelKey: 'title' },
+    journeys: { type: 'Journey', labelKey: 'title' },
+    screens: { type: 'Screen', labelKey: 'title' },
+    evidence: { type: 'Evidence', labelKey: 'title' },
+    decisions: { type: 'Decision', labelKey: 'title' },
+    assumptions: { type: 'Assumption', labelKey: 'statement' },
+    researchRounds: { type: 'Research round', labelKey: 'title' },
+    participants: { type: 'Participant', labelKey: 'label' },
+    insights: { type: 'Insight', labelKey: 'title' },
+    designActions: { type: 'Design action', labelKey: 'title' }
+  }
+
+  const entities = {}
+  for (const [collection, config] of Object.entries(entityCollections)) {
+    for (const item of knowledge[collection] || []) {
+      entities[item.id] = {
+        id: item.id,
+        type: config.type,
+        label: item[config.labelKey],
+        collection,
+        item
+      }
+    }
+  }
+  return entities
+}
+
+function getJourney (journeyId) {
+  const knowledge = getKnowledge()
+  return knowledge.index.journeys[journeyId]
+}
+
+function getUserKnowledgeGraph (userId) {
+  const knowledge = getKnowledge()
+  const user = knowledge.index.users[userId]
+  if (!user) return null
+
+  const needs = knowledge.needs.filter((need) => need.userId === user.id)
+  const scenarios = knowledge.scenarios.filter((scenario) => scenario.userId === user.id)
+  const journeys = knowledge.journeys.filter((journey) => {
+    const scenario = knowledge.index.scenarios[journey.scenarioId]
+    return scenario && scenario.userId === user.id
+  })
+
+  const needIds = new Set(needs.map((need) => need.id))
+  const evidenceIds = new Set(needs.flatMap((need) => need.evidenceIds || []))
+  const screenIds = new Set()
+  const decisionIds = new Set()
+
+  for (const journey of journeys) {
+    for (const step of journey.steps || []) {
+      for (const needId of step.needIds || []) needIds.add(needId)
+      for (const evidenceId of step.evidenceIds || []) evidenceIds.add(evidenceId)
+      for (const screenId of step.screenIds || []) screenIds.add(screenId)
+      for (const decisionId of step.decisionIds || []) decisionIds.add(decisionId)
+    }
+  }
+
+  for (const scenario of scenarios) {
+    for (const needId of scenario.needIds || []) needIds.add(needId)
+  }
+
+  for (const needId of needIds) {
+    const need = knowledge.index.needs[needId]
+    if (!need) continue
+    for (const evidenceId of need.evidenceIds || []) evidenceIds.add(evidenceId)
+  }
+
+  const linkedNeeds = sortByLabel([...needIds].map((id) => knowledge.index.needs[id]).filter(Boolean), 'statement')
+  const linkedEvidence = sortByLabel([...evidenceIds].map((id) => knowledge.index.evidence[id]).filter(Boolean), 'title')
+  const screens = sortByLabel([...screenIds].map((id) => knowledge.index.screens[id]).filter(Boolean), 'title')
+  const decisions = sortByLabel([...decisionIds].map((id) => knowledge.index.decisions[id]).filter(Boolean), 'title')
+
+  return {
+    user,
+    scenarios,
+    needs: linkedNeeds,
+    evidence: linkedEvidence,
+    journeys,
+    screens,
+    decisions,
+    assumptions: knowledge.assumptions,
+    graph: buildUserGraph({ user, scenarios, needs: linkedNeeds, evidence: linkedEvidence, journeys, screens, decisions })
+  }
+}
+
+function getGraphExplorer () {
+  const knowledge = getKnowledge()
+  const relationships = enrichRelationships(knowledge, knowledge.relationships)
+  const entityIds = new Set(relationships.flatMap((relationship) => [relationship.from, relationship.to]))
+  const nodes = [...entityIds].map((id) => knowledge.index.entities[id]).filter(Boolean)
+  const relationshipTypes = [...new Set(relationships.map((relationship) => relationship.type))].sort()
+
+  return {
+    nodes: sortByLabel(nodes, 'label'),
+    relationships,
+    relationshipTypes
+  }
+}
+
+function getTraceExplorer (entityType, entityId) {
+  const knowledge = getKnowledge()
+  const relationships = enrichRelationships(knowledge, knowledge.relationships)
+  const nodes = sortByTypeThenLabel(Object.values(knowledge.index.entities))
+  const entityTypes = [...new Set(nodes.map((node) => node.type))].sort()
+  const filteredNodes = entityType ? nodes.filter((node) => node.type === entityType) : []
+  const selectedCandidate = entityId ? knowledge.index.entities[entityId] : null
+  const selected = selectedCandidate && (!entityType || selectedCandidate.type === entityType) ? selectedCandidate : null
+
+  if (!selected) {
+    return {
+      nodes,
+      entityTypes,
+      entityType,
+      filteredNodes,
+      selected: null,
+      upstream: [],
+      downstream: []
+    }
+  }
+
+  return {
+    nodes,
+    entityTypes,
+    entityType: selected.type,
+    filteredNodes: nodes.filter((node) => node.type === selected.type),
+    selected: decorateTraceEntity(selected),
+    upstream: buildTraceBranches(knowledge, relationships, selected.id, 'upstream'),
+    downstream: buildTraceBranches(knowledge, relationships, selected.id, 'downstream')
+  }
+}
+
+function getEvidenceImpact (evidenceId) {
+  const knowledge = getKnowledge()
+  const evidence = knowledge.index.evidence[evidenceId]
+  if (!evidence) return null
+
+  const relationships = enrichRelationships(knowledge, knowledge.relationships)
+  const dependents = findDependents(evidenceId, relationships)
+  const impactedEntities = [...dependents].map((id) => knowledge.index.entities[id]).filter(Boolean)
+
+  return {
+    evidence,
+    directRelationships: relationships.filter((relationship) => relationship.from === evidenceId || relationship.to === evidenceId),
+    impactedEntities: sortByTypeThenLabel(impactedEntities),
+    relationships: relationships.filter((relationship) => dependents.has(relationship.from) || dependents.has(relationship.to))
+  }
+}
+
+function getResearchViewModel () {
+  const knowledge = getKnowledge()
+
+  return {
+    rounds: knowledge.researchRounds.map((round) => ({
+      ...round,
+      participants: knowledge.participants.filter((participant) => participant.roundIds.includes(round.id)),
+      insights: knowledge.insights.filter((insight) => insight.roundId === round.id),
+      designActions: knowledge.designActions.filter((action) => {
+        const roundInsightIds = new Set(knowledge.insights.filter((insight) => insight.roundId === round.id).map((insight) => insight.id))
+        return action.insightIds.some((insightId) => roundInsightIds.has(insightId))
+      })
+    })),
+    participants: knowledge.participants,
+    insights: knowledge.insights,
+    designActions: knowledge.designActions
+  }
+}
+
+function enrichRelationships (knowledge, relationships) {
+  return relationships
+    .map((relationship) => {
+      const fromEntity = knowledge.index.entities[relationship.from]
+      const toEntity = knowledge.index.entities[relationship.to]
+      if (!fromEntity || !toEntity) return null
+      return {
+        ...relationship,
+        label: relationshipLabel(relationship.type),
+        fromLabel: fromEntity.label,
+        fromType: fromEntity.type,
+        toLabel: toEntity.label,
+        toType: toEntity.type
+      }
+    })
+    .filter(Boolean)
+}
+
+function findDependents (entityId, relationships) {
+  const dependents = new Set()
+  const queue = [entityId]
+
+  while (queue.length) {
+    const current = queue.shift()
+    for (const relationship of relationships) {
+      if (relationship.to !== current || dependents.has(relationship.from)) continue
+      dependents.add(relationship.from)
+      queue.push(relationship.from)
+    }
+  }
+
+  return dependents
+}
+
+function buildTraceBranches (knowledge, relationships, entityId, direction, visited = new Set([entityId]), depth = 0) {
+  if (depth >= 6) return []
+
+  const relevantRelationships = relationships.filter((relationship) => {
+    if (direction === 'upstream') return relationship.to === entityId
+    return relationship.from === entityId
+  })
+
+  return relevantRelationships.map((relationship) => {
+    const nextId = direction === 'upstream' ? relationship.from : relationship.to
+    const entity = knowledge.index.entities[nextId]
+    const seen = visited.has(nextId)
+    const nextVisited = new Set(visited)
+    nextVisited.add(nextId)
+
+    return {
+      relationship,
+      entity: decorateTraceEntity(entity),
+      seen,
+      children: seen ? [] : buildTraceBranches(knowledge, relationships, nextId, direction, nextVisited, depth + 1)
+    }
+  }).filter((branch) => branch.entity).sort(sortTraceBranches)
+}
+
+function decorateTraceEntity (entity) {
+  return {
+    ...entity,
+    date: getEntityDate(entity),
+    typeSlug: entity.type.toLowerCase().replace(/\s+/g, '-')
+  }
+}
+
+function getEntityDate (entity) {
+  const item = entity.item || {}
+  return item.date || item.createdAt || item.updatedAt || item.importedAt || item.promotedAt || null
+}
+
+function sortTraceBranches (a, b) {
+  return `${a.entity.date || '9999'}:${a.entity.label}`.localeCompare(`${b.entity.date || '9999'}:${b.entity.label}`)
+}
+
+function buildUserGraph ({ user, scenarios, needs, evidence, journeys, screens, decisions }) {
+  const nodes = [
+    { id: user.id, label: user.label, type: 'User' },
+    ...scenarios.map((scenario) => ({ id: scenario.id, label: scenario.title, type: 'Scenario' })),
+    ...needs.map((need) => ({ id: need.id, label: need.statement, type: 'Need' })),
+    ...evidence.map((item) => ({ id: item.id, label: item.title, type: 'Evidence' })),
+    ...journeys.map((journey) => ({ id: journey.id, label: journey.title, type: 'Journey' })),
+    ...screens.map((screen) => ({ id: screen.id, label: screen.title, type: 'Screen' })),
+    ...decisions.map((decision) => ({ id: decision.id, label: decision.title, type: 'Decision' }))
+  ]
+
+  const edges = []
+  for (const scenario of scenarios) {
+    edges.push({ from: user.id, to: scenario.id, label: 'has scenario' })
+    for (const needId of scenario.needIds || []) edges.push({ from: scenario.id, to: needId, label: 'tests need' })
+  }
+
+  for (const need of needs) {
+    edges.push({ from: user.id, to: need.id, label: 'has need' })
+    for (const evidenceId of need.evidenceIds || []) edges.push({ from: need.id, to: evidenceId, label: 'supported by' })
+  }
+
+  for (const journey of journeys) {
+    edges.push({ from: knowledgeScenarioId(journey), to: journey.id, label: 'drives journey' })
+    for (const step of journey.steps || []) {
+      for (const needId of step.needIds || []) edges.push({ from: journey.id, to: needId, label: 'covers' })
+      for (const screenId of step.screenIds || []) edges.push({ from: journey.id, to: screenId, label: 'renders screen' })
+      for (const evidenceId of step.evidenceIds || []) edges.push({ from: journey.id, to: evidenceId, label: 'uses evidence' })
+      for (const decisionId of step.decisionIds || []) edges.push({ from: journey.id, to: decisionId, label: 'records decision' })
+    }
+  }
+
+  const graphNodes = uniqueById(nodes)
+  const nodeLabels = Object.fromEntries(graphNodes.map((node) => [node.id, node.label]))
+
+  return {
+    nodes: graphNodes,
+    edges: uniqueEdges(edges)
+      .filter((edge) => nodeLabels[edge.from] && nodeLabels[edge.to])
+      .map((edge) => ({
+        ...edge,
+        fromLabel: nodeLabels[edge.from],
+        toLabel: nodeLabels[edge.to]
+      }))
+  }
+}
+
+function knowledgeScenarioId (journey) {
+  return journey.scenarioId
+}
+
+function buildBlueprintViewModel (journeyId) {
+  const knowledge = getKnowledge()
+  const journey = knowledge.index.journeys[journeyId]
+  if (!journey) return null
+
+  const scenario = knowledge.index.scenarios[journey.scenarioId]
+  const steps = journey.steps.map((step) => ({
+    id: step.id,
+    label: step.label,
+    channel: step.channel,
+    userAction: step.userAction,
+    frontstage: step.frontstage,
+    backstage: step.backstage,
+    supportProcesses: step.supportProcesses,
+    dataDependencies: step.dataDependencies,
+    securityAndGovernance: step.securityAndGovernance,
+    painPoints: step.painPoints,
+    exceptionHandling: step.exceptionHandling,
+    futureState: step.futureState,
+    screens: (step.screenIds || []).map((id) => knowledge.index.screens[id]).filter(Boolean),
+    evidence: (step.evidenceIds || []).map((id) => knowledge.index.evidence[id]).filter(Boolean),
+    decisions: (step.decisionIds || []).map((id) => knowledge.index.decisions[id]).filter(Boolean),
+    userNeeds: (step.needIds || []).map((id) => knowledge.index.needs[id]).filter(Boolean)
+  }))
+
+  return {
+    meta: {
+      serviceTitle: knowledge.project.name,
+      serviceDescription: knowledge.project.description,
+      journeyTitle: journey.title,
+      scenarioTitle: scenario ? scenario.title : ''
+    },
+    journey,
+    scenario,
+    steps,
+    lanes: [
+      { key: 'screens', label: 'Prototype screens', boundaryAfter: false, lenses: ['executive'] },
+      { key: 'userAction', label: 'User action', boundaryAfter: false, lenses: ['executive', 'technical'] },
+      { key: 'frontstage', label: 'Frontstage', boundaryAfter: 'Line of visibility', lenses: ['executive', 'technical'] },
+      { key: 'backstage', label: 'Backstage', boundaryAfter: false, lenses: ['technical'] },
+      { key: 'supportProcesses', label: 'Support processes', boundaryAfter: 'Line of internal interaction', lenses: ['technical'] },
+      { key: 'dataDependencies', label: 'Data dependencies', boundaryAfter: false, lenses: ['technical', 'risk'] },
+      { key: 'securityAndGovernance', label: 'Security and governance', boundaryAfter: 'Governance boundary', lenses: ['risk'] },
+      { key: 'painPoints', label: 'Pain points', boundaryAfter: false, lenses: ['executive', 'risk'] },
+      { key: 'exceptionHandling', label: 'Exceptions', boundaryAfter: false, lenses: ['risk'] },
+      { key: 'futureState', label: 'Future state / proposed changes', boundaryAfter: false, lenses: ['executive'] },
+      { key: 'evidence', label: 'Evidence and decisions', boundaryAfter: false, lenses: ['executive'] }
+    ]
+  }
+}
+
+// An honest "we don't know" placeholder used when promoting the NHS Notify
+// blueprint (see decision-promote-representative-subset) - not a real
+// exception, so it shouldn't render as a branching path in the flow diagram.
+const NO_EXCEPTION_CAPTURED_TEXT = 'No exception path was captured for this step in the source blueprint'
+
+function buildJourneyFlowDiagram (journeyId) {
+  const knowledge = getKnowledge()
+  const journey = knowledge.index.journeys[journeyId]
+  if (!journey) return null
+
+  const stepNodeId = (step) => `step_${mermaidId(step.id)}`
+  const lines = ['flowchart TD']
+
+  journey.steps.forEach((step) => {
+    lines.push(`  ${stepNodeId(step)}["${escapeMermaidLabel(step.label)}"]`)
+  })
+
+  for (let index = 0; index < journey.steps.length - 1; index++) {
+    lines.push(`  ${stepNodeId(journey.steps[index])} --> ${stepNodeId(journey.steps[index + 1])}`)
+  }
+
+  const exceptionNodeIds = []
+  journey.steps.forEach((step) => {
+    const realExceptions = (step.exceptionHandling || []).filter((text) => text !== NO_EXCEPTION_CAPTURED_TEXT)
+    realExceptions.forEach((text, index) => {
+      const exceptionId = `exc_${mermaidId(step.id)}_${index}`
+      exceptionNodeIds.push(exceptionId)
+      lines.push(`  ${exceptionId}["${escapeMermaidLabel(truncateForDiagram(text))}"]`)
+      lines.push(`  ${stepNodeId(step)} -.->|exception| ${exceptionId}`)
+    })
+  })
+
+  if (exceptionNodeIds.length) {
+    lines.push('  classDef exception fill:#fdf3e6,stroke:#8e5300,color:#8e5300')
+    lines.push(`  class ${exceptionNodeIds.join(',')} exception`)
+  }
+
+  return {
+    meta: { journeyTitle: journey.title },
+    journey,
+    mermaidSource: lines.join('\n')
+  }
+}
+
+function mermaidId (value) {
+  return value.replace(/[^a-zA-Z0-9]/g, '_')
+}
+
+function escapeMermaidLabel (value) {
+  return value.replace(/"/g, "'").replace(/\s+/g, ' ').trim()
+}
+
+function truncateForDiagram (value, maxLength = 90) {
+  if (value.length <= maxLength) return value
+  return `${value.slice(0, maxLength - 1).trim()}…`
+}
+
+function validateKnowledge () {
+  const errors = []
+  let knowledge
+
+  try {
+    knowledge = loadKnowledgeData()
+  } catch (error) {
+    return { valid: false, errors: [`Could not load knowledge data: ${error.message}`] }
+  }
+
+  const schemaResult = KnowledgeSchema.safeParse(knowledge)
+  if (!schemaResult.success) {
+    return {
+      valid: false,
+      errors: schemaResult.error.issues.map((issue) => {
+        const fieldPath = issue.path.length ? issue.path.join('.') : 'knowledge'
+        return `${fieldPath}: ${issue.message}`
+      })
+    }
+  }
+
+  knowledge = schemaResult.data
+  knowledge.index = buildIndex(knowledge)
+
+  const index = knowledge.index
+
+  for (const collectionName of Object.keys(index)) {
+    const source = knowledge[collectionName]
+    if (!Array.isArray(source)) continue
+    const ids = new Set()
+    for (const item of source) {
+      if (!item.id) errors.push(`${collectionName}: item missing id`)
+      if (ids.has(item.id)) errors.push(`${collectionName}: duplicate id ${item.id}`)
+      ids.add(item.id)
+    }
+  }
+
+  for (const need of knowledge.needs) {
+    requireRef(errors, 'need', need.id, 'userId', need.userId, index.users)
+    for (const evidenceId of need.evidenceIds || []) {
+      requireRef(errors, 'need', need.id, 'evidenceIds', evidenceId, index.evidence)
+    }
+  }
+
+  for (const scenario of knowledge.scenarios) {
+    requireRef(errors, 'scenario', scenario.id, 'userId', scenario.userId, index.users)
+    for (const needId of scenario.needIds || []) {
+      requireRef(errors, 'scenario', scenario.id, 'needIds', needId, index.needs)
+    }
+  }
+
+  for (const journey of knowledge.journeys) {
+    requireRef(errors, 'journey', journey.id, 'scenarioId', journey.scenarioId, index.scenarios)
+    for (const step of journey.steps || []) {
+      for (const needId of step.needIds || []) requireRef(errors, 'journey step', step.id, 'needIds', needId, index.needs)
+      for (const screenId of step.screenIds || []) requireRef(errors, 'journey step', step.id, 'screenIds', screenId, index.screens)
+      for (const evidenceId of step.evidenceIds || []) requireRef(errors, 'journey step', step.id, 'evidenceIds', evidenceId, index.evidence)
+      for (const decisionId of step.decisionIds || []) requireRef(errors, 'journey step', step.id, 'decisionIds', decisionId, index.decisions)
+    }
+  }
+
+  for (const screen of knowledge.screens) {
+    for (const needId of screen.needIds || []) requireRef(errors, 'screen', screen.id, 'needIds', needId, index.needs)
+  }
+
+  for (const participant of knowledge.participants) {
+    for (const roundId of participant.roundIds || []) requireRef(errors, 'participant', participant.id, 'roundIds', roundId, index.researchRounds)
+  }
+
+  for (const insight of knowledge.insights) {
+    requireRef(errors, 'insight', insight.id, 'roundId', insight.roundId, index.researchRounds)
+    for (const participantId of insight.participantIds || []) requireRef(errors, 'insight', insight.id, 'participantIds', participantId, index.participants)
+    for (const evidenceId of insight.evidenceIds || []) requireRef(errors, 'insight', insight.id, 'evidenceIds', evidenceId, index.evidence)
+  }
+
+  for (const action of knowledge.designActions) {
+    for (const insightId of action.insightIds || []) requireRef(errors, 'design action', action.id, 'insightIds', insightId, index.insights)
+  }
+
+  for (const relationship of knowledge.relationships) {
+    requireRef(errors, 'relationship', relationship.id, 'from', relationship.from, index.entities)
+    requireRef(errors, 'relationship', relationship.id, 'to', relationship.to, index.entities)
+  }
+
+  return { valid: errors.length === 0, errors }
+}
+
+function requireRef (errors, type, id, field, value, lookup) {
+  if (!lookup[value]) errors.push(`${type} ${id}: ${field} references missing id ${value}`)
+}
+
+function sortByLabel (items, key) {
+  return items.sort((a, b) => a[key].localeCompare(b[key]))
+}
+
+function sortByTypeThenLabel (items) {
+  return items.sort((a, b) => `${a.type}:${a.label}`.localeCompare(`${b.type}:${b.label}`))
+}
+
+function relationshipLabel (type) {
+  return type.replace(/-/g, ' ')
+}
+
+function uniqueById (items) {
+  return Object.values(Object.fromEntries(items.map((item) => [item.id, item])))
+}
+
+function uniqueEdges (edges) {
+  return Object.values(Object.fromEntries(edges.map((edge) => [`${edge.from}:${edge.label}:${edge.to}`, edge])))
+}
+
+return {
+  getKnowledge,
+  getJourney,
+  getUserKnowledgeGraph,
+  getGraphExplorer,
+  getTraceExplorer,
+  getEvidenceImpact,
+  getResearchViewModel,
+  buildBlueprintViewModel,
+  buildJourneyFlowDiagram,
+  validateKnowledge
+}
+}
+
+// No default store. A store is always built from an explicitly resolved root,
+// so nothing can quietly read the wrong project.
+module.exports = {
+  createKnowledgeStore
+}

package/lib/package-paths.js

@@ -0,0 +1,32 @@
+const fs = require('fs')
+const path = require('path')
+
+// Paths to files the PACKAGE owns - views, stylesheets, client JS, the scripts
+// one script spawns another by. Deliberately named nothing like the host paths
+// in paths.js: conflating "where the library lives" with "where the project
+// lives" is the bug this whole refactor exists to remove, and two similar names
+// would invite it straight back.
+
+function findPackageRoot (from) {
+  let dir = path.resolve(from)
+  for (;;) {
+    if (fs.existsSync(path.join(dir, 'package.json'))) return dir
+    const parent = path.dirname(dir)
+    if (parent === dir) {
+      throw new Error(`Could not find the Hippocampus package root above ${from}`)
+    }
+    dir = parent
+  }
+}
+
+const packageRoot = findPackageRoot(__dirname)
+
+module.exports = {
+  packageRoot,
+  viewsDir: path.join(packageRoot, 'views'),
+  assetsDir: path.join(packageRoot, 'assets'),
+  scriptsDir: path.join(packageRoot, 'scripts'),
+  templatesDir: path.join(packageRoot, 'templates'),
+  skillsDir: path.join(packageRoot, 'skills'),
+  docsDir: path.join(packageRoot, 'docs')
+}

package/lib/paths.js

@@ -0,0 +1,33 @@
+const path = require('path')
+
+// Paths to files the HOST project owns. Every one of them is derived from a
+// root that was resolved explicitly - there is deliberately no default export
+// and no module-level projectRoot, because a baked-in default is silently
+// wrong the moment this library is installed into somebody else's project.
+// Package-owned paths live in package-paths.js under different names.
+
+function createPaths ({ root, dataDir = 'hippocampus', artefactsDir = 'artefacts' }) {
+  if (!root) throw new Error('createPaths requires a resolved root - see resolve-root.js')
+
+  const hippocampusDir = path.isAbsolute(dataDir) ? dataDir : path.join(root, dataDir)
+  const manifestsDir = path.join(hippocampusDir, 'manifests')
+
+  return {
+    root,
+    hippocampusDir,
+    artefactsDir: path.isAbsolute(artefactsDir) ? artefactsDir : path.join(root, artefactsDir),
+    knowledgeSourceDir: path.join(hippocampusDir, 'source'),
+    sourceArtefactsDir: path.join(hippocampusDir, 'source-artefacts'),
+    templatesDir: path.join(hippocampusDir, 'templates'),
+    projectInboxDir: path.join(hippocampusDir, 'inbox/project'),
+    projectImportsDir: path.join(hippocampusDir, 'imports/project'),
+    researchInboxDir: path.join(hippocampusDir, 'inbox/research'),
+    researchImportsDir: path.join(hippocampusDir, 'imports/research'),
+    manifestsDir,
+    researchManifestsDir: manifestsDir,
+    projectManifestPath: path.join(manifestsDir, 'project.json'),
+    researchManifestPath: path.join(manifestsDir, 'research.json')
+  }
+}
+
+module.exports = { createPaths }