@rahmantech/knl-view 0.0.0-stage → 0.1.0

package/server/config.js

@@ -0,0 +1,263 @@
+import { promises as fs } from 'node:fs'
+import fsSync from 'node:fs'
+import path from 'node:path'
+
+// Two-layer knl-view config:
+// - Global: ~/.knlview/knl-config.json holds the "anchordb" block (URL, token,
+//   sync). That connection belongs to the machine/user, not the repo, so all
+//   projects using AnchorDB share the same server.
+// - Per project: knl-config.json at the project root (gitignored) holds
+//   path/port/host and the "models" map (role -> AnchorDB model name; names
+//   may be random, the map records what each name is for).
+//
+// A missing or broken file must never bring the viewer down. Final values
+// are chosen by resolveSettings in the order: CLI flag > config > default.
+
+const PROJECT_CONFIG_FILE = 'knl-config.json'
+const GLOBAL_CONFIG_DIR = '.knlview'
+const GLOBAL_CONFIG_FILE = 'knl-config.json'
+const MAX_CONFIG_BYTES = 64 * 1024
+
+export const DEFAULT_SETTINGS = { path: '.knowledges', port: '8085', host: '127.0.0.1' }
+export const DEFAULT_MODEL = 'knowledges'
+
+// Causal relations /api/anchordb/trace follows when the config sets none.
+export const DEFAULT_RELATIONS = ['supersedes', 'affects_knowledge', 'depends_on']
+
+export function globalConfigPath(home = process.env.HOME) {
+  return path.join(home || '', GLOBAL_CONFIG_DIR, GLOBAL_CONFIG_FILE)
+}
+
+/**
+ * Location of the mirror of the last synced edges for one model:
+ * ~/.knlview/sync-state/<model>.json. Incremental sync compares the local
+ * graph against this mirror, not against the server contents (the server
+ * offers no edge enumeration over the wire protocol).
+ */
+export function syncStatePath(model, home = process.env.HOME) {
+  const safe = String(model || 'model').toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^-+|-+$/g, '') || 'model'
+  return path.join(home || '', GLOBAL_CONFIG_DIR, 'sync-state', `${safe}.json`)
+}
+
+/**
+ * Read the global config ~/.knlview/knl-config.json (anchordb block).
+ * @returns {Promise<{config: object|null, error: string|null}>}
+ */
+export async function readGlobalConfig(home = process.env.HOME) {
+  return readConfigFile(globalConfigPath(home), normalizeGlobalConfig)
+}
+
+/**
+ * Read the per-project config: knl-config.json at the project root.
+ * @returns {Promise<{config: object|null, error: string|null}>}
+ */
+export async function readProjectConfig(cwd = process.cwd()) {
+  return readConfigFile(path.join(cwd, PROJECT_CONFIG_FILE), normalizeProjectConfig)
+}
+
+async function readConfigFile(abs, normalize) {
+  let stat
+  try {
+    stat = await fs.stat(abs)
+  } catch {
+    return { config: null, error: null }
+  }
+  if (!stat.isFile()) return { config: null, error: null }
+  if (stat.size > MAX_CONFIG_BYTES) {
+    return { config: null, error: `size exceeds ${MAX_CONFIG_BYTES} bytes` }
+  }
+  let parsed
+  try {
+    parsed = JSON.parse(await fs.readFile(abs, 'utf8'))
+  } catch (err) {
+    return { config: null, error: `invalid JSON: ${err.message}` }
+  }
+  return { config: normalize(parsed), error: null }
+}
+
+/**
+ * Filter the project config down to known fields. Invalid values are dropped
+ * (not fatal) so resolveSettings falls back to the CLI flag or the default.
+ *
+ * `models` is the role → AnchorDB model name map (names may be random; this
+ * map is what records what each name is for). The legacy `model: "x"` shape
+ * is still accepted as shorthand for models.knowledges.
+ */
+export function normalizeProjectConfig(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const config = {}
+  const configPath = cleanString(raw.path)
+  if (configPath) config.path = configPath
+  const port = toPort(raw.port)
+  if (port != null) config.port = String(port)
+  const host = cleanString(raw.host)
+  if (host) config.host = host
+  const models = normalizeModels(raw.models)
+  if (models) config.models = models
+  const model = cleanString(raw.model)
+  if (model) config.model = model
+  const labelDir = cleanString(raw.labelDir)
+  if (labelDir) config.labelDir = labelDir
+  return config
+}
+
+const MODEL_NAME_RE = /^[A-Za-z0-9][A-Za-z0-9._-]*$/
+const MODEL_ROLE_RE = /^[a-z][a-z0-9_-]*$/
+
+/**
+ * Filter the models map: keys = roles (lowercase slugs), values = model names.
+ * Invalid entries are dropped, not fatal.
+ */
+export function normalizeModels(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const models = {}
+  for (const [role, name] of Object.entries(raw)) {
+    const roleSlug = String(role).trim().toLowerCase()
+    const nameStr = cleanString(name)
+    if (!MODEL_ROLE_RE.test(roleSlug) || !MODEL_NAME_RE.test(nameStr)) continue
+    models[roleSlug] = nameStr
+  }
+  return Object.keys(models).length ? models : null
+}
+
+/**
+ * Model name for one role, verbatim from the map. No automatic namespacing:
+ * model names deliberately stay stable even when the project/folder is
+ * renamed. Returns null when the role is unmapped (the caller supplies the
+ * "run knl-view model new <role>" hint).
+ */
+export function resolveModel(models, role = DEFAULT_MODEL) {
+  const name = models?.[role]
+  return typeof name === 'string' && name ? name : null
+}
+
+/**
+ * Filter the global config: only the anchordb block matters here.
+ */
+export function normalizeGlobalConfig(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const anchordb = normalizeAnchordb(raw.anchordb)
+  return anchordb ? { anchordb } : null
+}
+
+/**
+ * Normalize the anchordb block shape: a "wire://host:port?token=..." string
+ * or a full object. Returns null when unusable.
+ */
+export function normalizeAnchordb(raw) {
+  if (typeof raw === 'string') raw = { url: raw }
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) return null
+  const url = cleanString(raw.url)
+  if (!url || !/^(wire|tcp):\/\//i.test(url)) return null
+  const anchordb = { url }
+  const token = cleanString(raw.token)
+  if (token) anchordb.token = token
+  const model = cleanString(raw.model)
+  if (model) anchordb.model = model
+  // Present means active (including graph sync on start); sync: false to opt out.
+  anchordb.sync = raw.sync !== false
+  if (Array.isArray(raw.relations)) {
+    const relations = raw.relations.map((r) => cleanString(r)).filter(Boolean)
+    if (relations.length) anchordb.relations = relations
+  }
+  return anchordb
+}
+
+/**
+ * Project name for the model registry entry: the package.json "name" field
+ * when present, otherwise the project folder name. Cleaned into a safe slug.
+ */
+export function projectSlug(cwd = process.cwd()) {
+  let name = null
+  try {
+    const parsed = JSON.parse(fsSync.readFileSync(path.join(cwd, 'package.json'), 'utf8'))
+    if (typeof parsed?.name === 'string') name = parsed.name
+  } catch {
+    // Without a package.json, the project folder name is used.
+  }
+  if (!name || !name.trim()) name = path.basename(path.resolve(cwd))
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
+  return slug || 'project'
+}
+
+/**
+ * Merge CLI flags, project config, global config, and defaults.
+ *
+ * - path/port/host: CLI > project config > default
+ * - anchordb: --anchordb flag > global config; fully off when neither exists
+ *   (a project without global config never touches AnchorDB)
+ * - model: taken from the project config `models` map (knowledges role).
+ *   The name in the URL (?model=) is only used when the map does not set it.
+ */
+export function resolveSettings({ cli = {}, project = null, global: globalConfig = null } = {}) {
+  const p = project || {}
+  const g = globalConfig || {}
+  const anchordb = cli.anchordb !== undefined
+    ? normalizeAnchordb(cli.anchordb)
+    : normalizeAnchordb(g.anchordb)
+
+  // Legacy "model": "x" shape still counts as models.knowledges.
+  const models = { ...(p.models || {}) }
+  if (!models[DEFAULT_MODEL] && typeof p.model === 'string' && p.model.trim()) {
+    models[DEFAULT_MODEL] = p.model.trim()
+  }
+  const hasModels = Object.keys(models).length > 0
+
+  if (anchordb) {
+    anchordb.model = (hasModels && resolveModel(models)) || cleanString(anchordb.model) || null
+  }
+
+  const labelDir = pickString(cli.labelDir, p.labelDir)
+
+  return {
+    path: pickString(cli.path, p.path) ?? DEFAULT_SETTINGS.path,
+    port: pickString(cli.port, p.port) ?? DEFAULT_SETTINGS.port,
+    host: pickString(cli.host, p.host) ?? DEFAULT_SETTINGS.host,
+    models: hasModels ? models : null,
+    labelDir: labelDir ?? null,
+    anchordb
+  }
+}
+
+/**
+ * Build AnchorWire client options from the already-resolved anchordb block.
+ * Config fields win over values in the URL query.
+ */
+export function anchordbClientOptions(anchordb) {
+  if (!anchordb?.url) return null
+  const normalized = anchordb.url.replace(/^(wire|tcp):\/\//i, 'http://')
+  let parsed
+  try {
+    parsed = new URL(normalized.startsWith('http') ? normalized : `http://${normalized}`)
+  } catch {
+    return null
+  }
+  const options = {}
+  if (parsed.hostname) options.host = parsed.hostname.replace(/^\[|\]$/g, '')
+  if (parsed.port) {
+    const port = Number.parseInt(parsed.port, 10)
+    if (Number.isInteger(port) && port > 0 && port <= 65535) options.port = port
+  }
+  options.token = anchordb.token || parsed.searchParams.get('token') || ''
+  // The model name comes from the project map (already resolved by
+  // resolveSettings) or the URL query for a one-off session. Deliberately no
+  // default: a model with no clear name must not silently create a generic
+  // "knowledges" model.
+  options.model = anchordb.model || parsed.searchParams.get('model') || ''
+  return options
+}
+
+function pickString(cliValue, configValue) {
+  if (typeof cliValue === 'string' && cliValue.trim()) return cliValue.trim()
+  if (typeof configValue === 'string' && configValue.trim()) return configValue.trim()
+  return null
+}
+
+function cleanString(value) {
+  return typeof value === 'string' ? value.trim() : ''
+}
+
+function toPort(value) {
+  const n = Number(value)
+  return Number.isInteger(n) && n >= 1 && n <= 65535 ? n : null
+}

package/server/consensus.js

@@ -0,0 +1,175 @@
+import { promises as fs } from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+
+// Consensus: agreement and conflict between claims, stored purely in
+// AnchorDB as a second model (the "consensus" role in the project's models
+// map). Claims relate only to other claims, never to decisions or files.
+//
+// A claim is content-addressed: id = "c-" + the first 16 hex chars of the
+// statement's SHA-256, so the same statement is the same id on every
+// machine. AnchorDB schemas only admit float32 attributes, so the statement
+// text cannot live in the server; the local index below is a convenience
+// cache (same nature as the sync mirror), never the source of the
+// consensus structure.
+//
+// Relation types are fixed so status derivation stays meaningful:
+//   agrees_with: the source claim supports the target claim
+//   contradicts: the source claim opposes the target claim
+
+export const CONSENSUS_RELATIONS = ['agrees_with', 'contradicts']
+
+/**
+ * Content-addressed claim id from the statement text.
+ * @param {string} text
+ * @returns {string} "c-" plus 16 hex characters
+ */
+export function claimId(text) {
+  const normalized = String(text || '').trim().toLowerCase().replace(/\s+/g, ' ')
+  const hash = crypto.createHash('sha256').update(normalized).digest('hex')
+  return `c-${hash.slice(0, 16)}`
+}
+
+/**
+ * Derive consensus status for one claim from who points at it.
+ * Any objection outweighs support: a single contradicts makes the claim
+ * disputed even if many agree with it.
+ * @returns {'disputed'|'consensus'|'uncontested'}
+ */
+export function deriveStatus(supporters, objectors) {
+  if (objectors.length > 0) return 'disputed'
+  if (supporters.length > 0) return 'consensus'
+  return 'uncontested'
+}
+
+/** Local cache path for claim statements: ~/.knlview/claims/<model>.json */
+export function claimsIndexPath(model, home = process.env.HOME) {
+  return path.join(home || '', '.knlview', 'claims', `${model}.json`)
+}
+
+/**
+ * Read the claim index. Missing file = empty index, not an error.
+ * @returns {Promise<{claims: object, error: string|null}>}
+ */
+export async function readClaimsIndex(model, home = process.env.HOME) {
+  try {
+    const parsed = JSON.parse(await fs.readFile(claimsIndexPath(model, home), 'utf8'))
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      return { claims: {}, error: 'claim index is not an object' }
+    }
+    const claims = {}
+    for (const [id, entry] of Object.entries(parsed)) {
+      if (entry && typeof entry === 'object' && typeof entry.text === 'string') {
+        claims[id] = entry
+      }
+    }
+    return { claims, error: null }
+  } catch (err) {
+    if (err?.code === 'ENOENT') return { claims: {}, error: null }
+    return { claims: {}, error: err.message }
+  }
+}
+
+/**
+ * Register a claim statement in the local index. Content-addressed, so
+ * re-registering the same statement is an idempotent update.
+ */
+export async function recordClaim(model, text, home = process.env.HOME) {
+  const id = claimId(text)
+  const { claims, error } = await readClaimsIndex(model, home)
+  if (error) return { id, written: false, error }
+  if (!claims[id]) claims[id] = { text: String(text).trim(), createdAt: new Date().toISOString() }
+  try {
+    const file = claimsIndexPath(model, home)
+    await fs.mkdir(path.dirname(file), { recursive: true })
+    await fs.writeFile(file, JSON.stringify(claims, null, 2) + '\n', 'utf8')
+    return { id, written: true, error: null }
+  } catch (err) {
+    return { id, written: false, error: err.message }
+  }
+}
+
+// Consensus mirror
+// The wire protocol only walks edges forward (causalChain), but "who agrees
+// with this claim?" is an inbound question. So every successful link/unlink
+// also updates a local mirror of the consensus model's edges, the same
+// pattern the knowledges graph already uses. The mirror is a read model:
+// losing it only degrades inbound queries, never the server's data.
+
+export function consensusEdgeKey(from, type, to) {
+  return `${from}\u0000${type}\u0000${to}`
+}
+
+/**
+ * Read the consensus mirror for one model. Returns the edge key list, or
+ * null when there is no mirror (never synced, or wiped).
+ */
+export async function readConsensusMirror(model, home = process.env.HOME) {
+  try {
+    const file = path.join(home || '', '.knlview', 'sync-state', `${model}.json`)
+    const parsed = JSON.parse(await fs.readFile(file, 'utf8'))
+    if (parsed?.model !== model || !Array.isArray(parsed.edges)) return null
+    return parsed.edges
+  } catch {
+    return null
+  }
+}
+
+/**
+ * Apply one change to the consensus mirror. Best effort: a failed mirror
+ * write is reported but never blocks the server mutation that already
+ * succeeded.
+ */
+export async function updateConsensusMirror(model, change, home = process.env.HOME) {
+  const edges = new Set(await readConsensusMirror(model, home) || [])
+  if (change.op === 'link') edges.add(consensusEdgeKey(change.from, change.type, change.to))
+  if (change.op === 'unlink') {
+    edges.delete(consensusEdgeKey(change.from, 'agrees_with', change.to))
+    edges.delete(consensusEdgeKey(change.from, 'contradicts', change.to))
+  }
+  try {
+    const file = path.join(home || '', '.knlview', 'sync-state', `${model}.json`)
+    await fs.mkdir(path.dirname(file), { recursive: true })
+    await fs.writeFile(file, JSON.stringify({
+      model,
+      syncedAt: new Date().toISOString(),
+      edges: Array.from(edges)
+    }), 'utf8')
+    return { error: null }
+  } catch (err) {
+    return { error: err.message }
+  }
+}
+
+/**
+ * Inbound half of consensus status, walked backwards over the mirror:
+ * supporters (incoming agrees_with) and objectors (incoming contradicts).
+ * @returns {{ supporters: string[], objectors: string[] }}
+ */
+export function inboundConsensus(mirrorEdges, targetId) {
+  const supporters = []
+  const objectors = []
+  for (const key of mirrorEdges || []) {
+    const [from, type, to] = key.split('\u0000')
+    if (to !== targetId) continue
+    if (type === 'agrees_with') supporters.push(from)
+    else if (type === 'contradicts') objectors.push(from)
+  }
+  return { supporters, objectors }
+}
+
+/**
+ * Outbound half: the claim's own stance, walked forward over the mirror.
+ * @returns {{ agrees: string[], contradicts: string[] }}
+ */
+export function outboundConsensus(mirrorEdges, sourceId) {
+  const agrees = []
+  const contradicts = []
+  for (const key of mirrorEdges || []) {
+    const [from, type, to] = key.split('\u0000')
+    if (from !== sourceId) continue
+    if (type === 'agrees_with') agrees.push(to)
+    else if (type === 'contradicts') contradicts.push(to)
+  }
+  return { agrees, contradicts }
+}

package/server/graph/anchordb_client.js

@@ -0,0 +1,253 @@
+import { connectWire } from '@rahmantech/anchorwire'
+
+/**
+ * Optional bridge module to the AnchorDB backend via the AnchorWire protocol
+ * (wire://). Follows the KISS principle: active only when configured, with
+ * graceful fallback.
+ */
+
+/**
+ * Open an AnchorWire client connection.
+ * @param {string|object} urlOrOptions - Example: 'wire://127.0.0.1:7448?model=knowledges'
+ */
+export async function createAnchorWireClient(urlOrOptions) {
+  try {
+    const client = await connectWire(urlOrOptions)
+    return client
+  } catch (err) {
+    const target = typeof urlOrOptions === 'string'
+      ? urlOrOptions
+      : `${urlOrOptions?.host || '?'}:${urlOrOptions?.port || '?'}`
+    throw new Error(`Failed to connect to AnchorDB (${target}): ${err.message}`)
+  }
+}
+
+/**
+ * Stable key for one edge, for diffing and the mirror: "from\x00type\x00to".
+ * NUL is used because it cannot appear in healthy markdown IDs.
+ */
+export function edgeKey(from, type, to) {
+  return `${from}\u0000${type}\u0000${to}`
+}
+
+/**
+ * Collect the set of unique edges from a DirectedGraph. Duplicate edges in
+ * markdown (one decision writing supersedes twice, say) only need to be sent
+ * to the server once.
+ * @param {import('./model.js').DirectedGraph} graph
+ * @returns {string[]} sorted edge keys
+ */
+export function edgesOfGraph(graph) {
+  const set = new Set()
+  for (const edge of graph?.edges ?? []) {
+    if (edge?.from && edge?.type && edge?.to) set.add(edgeKey(edge.from, edge.type, edge.to))
+  }
+  return Array.from(set).sort()
+}
+
+/**
+ * Diff two edge sets: what must be sent as link and unlink.
+ * @param {string[]} desired - edges that should exist (the current local graph)
+ * @param {string[]|null} previous - edges per the last sync mirror;
+ *   null means no mirror (the server is assumed empty → full link)
+ * @returns {{toLink: string[], toUnlink: string[]}}
+ */
+export function diffEdges(desired, previous) {
+  const now = new Set(desired)
+  if (!previous) return { toLink: [...now], toUnlink: [] }
+  const before = new Set(previous)
+  return {
+    toLink: desired.filter((k) => !before.has(k)),
+    toUnlink: previous.filter((k) => !now.has(k))
+  }
+}
+
+function isEdgeNotFound(err) {
+  return /edge not found/i.test(err?.message || '')
+}
+
+/**
+ * Cheap check that the server still recognizes one sample edge from the
+ * mirror. If the sample edge does not show up in causalChain, the server is
+ * considered different (reinstalled, wiped, model reset) and the mirror must
+ * be discarded so the sync becomes a full link. Link is an upsert, so a full
+ * link is always safe; what is dangerous is trusting a mirror against an
+ * empty server.
+ */
+export async function mirrorStillValid(client, previousEdges) {
+  if (!Array.isArray(previousEdges) || previousEdges.length === 0) return Boolean(previousEdges)
+  const [from, type, to] = previousEdges[0].split('\u0000')
+  try {
+    const results = await client.causalChain([from], type, 5)
+    return results.some((item) => item?.word === to)
+  } catch {
+    return false
+  }
+}
+
+/**
+ * Sync the graph to AnchorDB INCREMENTALLY: only new edges are linked, edges
+ * missing from markdown are unlinked, the rest are left alone. The server
+ * offers no edge enumeration, so the comparator is the mirror of the last
+ * sync (`previousEdges` from the local sync-state), and the mirror is
+ * verified with one causal probe before being trusted.
+ *
+ * Unlinking an edge that no longer exists on the server is treated as
+ * success (case: the container/server was reinstalled but the mirror remains).
+ *
+ * @param {import('@rahmantech/anchorwire').AnchorWireClient} client
+ * @param {import('./model.js').DirectedGraph} graph
+ * @param {string[]|null} previousEdges - mirror of the last sync (null = full sync)
+ * @returns {Promise<{linked: number, unlinked: number, kept: number, failed: number, edges: string[]}>}
+ *   `edges` = the full edge set after the sync, to be written to the mirror
+ *   ONLY when `failed === 0`. On partial failure the mirror is not written so
+ *   the next start retries the failed part.
+ */
+export async function syncGraphToAnchorDB(client, graph, previousEdges = null) {
+  if (!client || !graph) return { linked: 0, unlinked: 0, kept: 0, failed: 0, edges: [] }
+
+  const edges = edgesOfGraph(graph)
+  if (previousEdges && !(await mirrorStillValid(client, previousEdges))) {
+    previousEdges = null
+  }
+  const { toLink, toUnlink } = diffEdges(edges, previousEdges)
+  let linked = 0
+  let unlinked = 0
+  let failed = 0
+
+  for (const key of toLink) {
+    const [from, type, to] = key.split('\u0000')
+    try {
+      await client.link(from, type, to, 1.0)
+      linked += 1
+    } catch {
+      failed += 1
+    }
+  }
+
+  for (const key of toUnlink) {
+    const [from, type, to] = key.split('\u0000')
+    try {
+      await client.unlink(from, type, to)
+      unlinked += 1
+    } catch (err) {
+      // The edge no longer exists on the server: the end state equals what
+      // we want, so it counts as success.
+      if (isEdgeNotFound(err)) unlinked += 1
+      else failed += 1
+    }
+  }
+
+  return { linked, unlinked, kept: edges.length - linked, failed, edges }
+}
+
+/**
+ * Distributed multi-hop causal chain trace on the AnchorDB server.
+ *
+ * The AnchorWire client uses a relations array as an ORDERED CHAIN of hops
+ * (the second hop goes through the second relation), not "any one of". For
+ * the knowledge graphs we want to trace a UNION of relations (DEC
+ * --supersedes--> X or --affects_knowledge--> Y), each relation is traced
+ * separately per hop and then merged: dedupe per node, highest score wins,
+ * and each next hop's score is multiplied by its parent's.
+ *
+ * @param {import('@rahmantech/anchorwire').AnchorWireClient} client
+ * @param {string} seedId - id of the center node of the query
+ * @param {string|string[]} relations - relations to follow (e.g. ['supersedes', 'affects_knowledge', 'depends_on'])
+ * @param {number} limitK - result limit per server call
+ * @param {number} maxHops - trace hop radius
+ */
+export async function traceCausalChain(client, seedId, relations = ['supersedes', 'affects_knowledge', 'depends_on'], limitK = 20, maxHops = 2) {
+  if (!client) throw new Error('AnchorWire client unavailable.')
+  const rels = (Array.isArray(relations) ? relations : [relations]).filter(Boolean)
+  if (!rels.length) return []
+
+  const best = new Map() // word -> { word, score }
+  let frontier = [{ word: seedId, score: 1 }]
+
+  for (let hop = 1; hop <= Math.max(1, maxHops) && frontier.length; hop++) {
+    const nextFrontier = []
+    for (const { word, score } of frontier) {
+      const perRelation = await Promise.all(
+        rels.map((rel) => client.causalChain([word], rel, limitK).catch(() => []))
+      )
+      for (const results of perRelation) {
+        for (const item of results) {
+          if (!item?.word || item.word === seedId) continue
+          const reached = { word: item.word, score: score * (item.score || 1) }
+          const prev = best.get(reached.word)
+          if (!prev || reached.score > prev.score) {
+            best.set(reached.word, reached)
+            nextFrontier.push(reached)
+          }
+        }
+      }
+    }
+    frontier = nextFrontier
+  }
+
+  return Array.from(best.values()).sort((a, b) => b.score - a.score)
+}
+
+/**
+ * Reverse traversal over the local sync mirror: the inbound half of
+ * two-way lineage. The wire protocol has no "who points at X" query, but
+ * the mirror holds every edge this project ever linked, which is exactly
+ * the inbound map for this project's model. Entries carry score 1: the
+ * server's relevance scoring only exists for forward chains.
+ *
+ * @param {string[]} mirrorEdges - edge keys "from\x00type\x00to" from the sync mirror
+ * @param {string} seedId - id of the node to trace inbound from
+ * @param {string[]} relations - relation types to follow
+ * @param {number} maxHops - traversal radius
+ * @returns {Array<{word: string, score: number}>}
+ */
+export function traceInboundFromMirror(mirrorEdges, seedId, relations, maxHops = 2) {
+  if (!Array.isArray(mirrorEdges) || !mirrorEdges.length || !seedId) return []
+  const wanted = new Set(relations.filter(Boolean))
+
+  // Reverse adjacency: target node -> list of { source, type }.
+  const inbound = new Map()
+  for (const key of mirrorEdges) {
+    const [from, type, to] = key.split('\u0000')
+    if (!from || !to) continue
+    if (wanted.size && !wanted.has(type)) continue
+    if (!inbound.has(to)) inbound.set(to, [])
+    inbound.get(to).push(from)
+  }
+
+  const best = new Map() // word -> depth reached (BFS, first reach wins)
+  let frontier = [seedId]
+  best.set(seedId, 0)
+
+  for (let hop = 1; hop <= Math.max(1, maxHops) && frontier.length; hop++) {
+    const nextFrontier = []
+    for (const word of frontier) {
+      for (const source of inbound.get(word) || []) {
+        if (source === seedId || best.has(source)) continue
+        best.set(source, hop)
+        nextFrontier.push(source)
+      }
+    }
+    frontier = nextFrontier
+  }
+
+  best.delete(seedId)
+  return Array.from(best.keys()).map((word) => ({ word, score: 1 }))
+}
+
+/**
+ * Merge forward (server-scored) and inbound (mirror) results into one
+ * ranked list. A word reached both ways keeps the higher, meaningful score.
+ */
+export function mergeLineage(forward, inbound) {
+  const merged = new Map()
+  for (const { word, score } of forward) {
+    merged.set(word, { word, score })
+  }
+  for (const { word, score } of inbound) {
+    const prev = merged.get(word)
+    if (!prev || score > prev.score) merged.set(word, { word, score })
+  }
+  return Array.from(merged.values()).sort((a, b) => b.score - a.score)
+}