@anokye-labs/kbexplorer-engine 0.1.0

package/dist/store.cjs

@@ -0,0 +1,1112 @@
+'use strict';
+
+var module$1 = require('module');
+var kbexplorerCore = require('@anokye-labs/kbexplorer-core');
+var initSqlJs = require('sql.js');
+var marked = require('marked');
+var sanitizeHtml = require('sanitize-html');
+require('yaml');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+function _interopDefault (e) { return e && e.__esModule ? e : { default: e }; }
+
+var initSqlJs__default = /*#__PURE__*/_interopDefault(initSqlJs);
+var sanitizeHtml__default = /*#__PURE__*/_interopDefault(sanitizeHtml);
+
+var __defProp = Object.defineProperty;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __esm = (fn, res, err) => function __init() {
+  if (err) throw err[0];
+  try {
+    return fn && (res = (0, fn[__getOwnPropNames(fn)[0]])(fn = 0)), res;
+  } catch (e) {
+    throw err = [e], e;
+  }
+};
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+
+// src/store/node-wasm.ts
+var node_wasm_exports = {};
+__export(node_wasm_exports, {
+  nodeLocateFile: () => nodeLocateFile
+});
+function nodeLocateFile() {
+  const require2 = module$1.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('store.cjs', document.baseURI).href)));
+  return (file) => require2.resolve(`sql.js/dist/${file}`);
+}
+var init_node_wasm = __esm({
+  "src/store/node-wasm.ts"() {
+  }
+});
+
+// src/store/config.ts
+function resolveGraphStoreOptions(env) {
+  const engineEnv = env ?? {};
+  const raw = engineEnv.VITE_KB_GRAPH_STORE;
+  const value = typeof raw === "string" ? raw.trim().toLowerCase() : "";
+  if (!value || value === "off" || value === "false" || value === "0") {
+    return { mode: "off" };
+  }
+  if (value === "sqlite") return { mode: "sqlite" };
+  throw new Error(`Unsupported VITE_KB_GRAPH_STORE value: ${String(raw)}`);
+}
+function isGraphStoreEnabled(env) {
+  return resolveGraphStoreOptions(env).mode === "sqlite";
+}
+var GRAPH_STORE_DERIVATION_VERSION = "template-graph-derivation-v3";
+var GRAPH_STORE_PROVIDER_ID = "provider-pipeline";
+function buildProviderResultCacheKey(source, config, data, providerId = GRAPH_STORE_PROVIDER_ID, previousContentHash) {
+  return contentHashFor({
+    apiVersion: kbexplorerCore.GRAPH_STORE_API_VERSION,
+    cacheKeyVersion: kbexplorerCore.GRAPH_STORE_CACHE_KEY_VERSION,
+    derivationVersion: GRAPH_STORE_DERIVATION_VERSION,
+    sourceId: source.id,
+    providerId,
+    previousContentHash,
+    config,
+    data: stableProviderData(data, providerId)
+  }).then((contentHash) => ({
+    scope: "provider-result",
+    providerId,
+    sourceId: sourceIdFor(source, config),
+    contentHash,
+    variant: [
+      kbexplorerCore.GRAPH_STORE_API_VERSION,
+      kbexplorerCore.GRAPH_STORE_CACHE_KEY_VERSION,
+      GRAPH_STORE_DERIVATION_VERSION
+    ].join(":")
+  }));
+}
+function hashProviderResultPrefix(providerId, nodes) {
+  return contentHashFor({
+    apiVersion: kbexplorerCore.GRAPH_STORE_API_VERSION,
+    cacheKeyVersion: kbexplorerCore.GRAPH_STORE_CACHE_KEY_VERSION,
+    derivationVersion: GRAPH_STORE_DERIVATION_VERSION,
+    providerId,
+    nodes
+  });
+}
+function sourceIdFor(source, config) {
+  const sourceConfig = config.source;
+  return [
+    source.id,
+    sourceConfig.owner,
+    sourceConfig.repo,
+    sourceConfig.branch ?? "main",
+    sourceConfig.path ?? ""
+  ].join(":");
+}
+async function contentHashFor(value) {
+  const crypto = globalThis.crypto?.subtle;
+  if (!crypto) {
+    throw new Error("Graph store hashing requires Web Crypto SubtleCrypto support.");
+  }
+  const bytes = new TextEncoder().encode(stableStringify(value));
+  const digest = await crypto.digest("SHA-256", bytes);
+  return {
+    algorithm: "sha256",
+    digest: bytesToHex(new Uint8Array(digest)),
+    encoding: "hex"
+  };
+}
+function bytesToHex(bytes) {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function stableRepoData(data) {
+  return {
+    repo: data.repo,
+    tree: data.tree.map((item) => ({
+      path: item.path,
+      mode: item.mode,
+      type: item.type,
+      sha: item.sha,
+      size: item.size
+    })),
+    authoredContent: data.authoredContent,
+    nodemapRaw: data.nodemapRaw,
+    nodemapFiles: data.nodemapFiles,
+    nodemapDirs: data.nodemapDirs,
+    issues: data.issues.map((issue) => ({
+      number: issue.number,
+      title: issue.title,
+      body: issue.body,
+      state: issue.state,
+      labels: issue.labels,
+      assignees: issue.assignees,
+      user: issue.user,
+      html_url: issue.html_url,
+      created_at: issue.created_at,
+      updated_at: issue.updated_at
+    })),
+    pullRequests: data.pullRequests,
+    commits: data.commits,
+    branches: data.branches,
+    repoMetadata: data.repoMetadata,
+    releases: data.releases,
+    structuralFiles: data.structuralFiles,
+    structuredNodeMapRaw: data.structuredNodeMapRaw,
+    contentModel: data.contentModel,
+    readme: data.readme
+  };
+}
+function stableProviderData(data, providerId) {
+  switch (providerId) {
+    case "files":
+      return {
+        repo: data.repo,
+        tree: data.tree.map((item) => ({
+          path: item.path,
+          mode: item.mode,
+          type: item.type,
+          sha: item.sha,
+          size: item.size
+        }))
+      };
+    case "authored":
+      return {
+        authoredContent: data.authoredContent,
+        nodemapRaw: data.nodemapRaw,
+        nodemapFiles: data.nodemapFiles,
+        nodemapDirs: data.nodemapDirs
+      };
+    case "work":
+      return {
+        issues: data.issues.map((issue) => ({
+          number: issue.number,
+          title: issue.title,
+          body: issue.body,
+          state: issue.state,
+          labels: issue.labels,
+          assignees: issue.assignees,
+          user: issue.user,
+          html_url: issue.html_url,
+          created_at: issue.created_at,
+          updated_at: issue.updated_at
+        })),
+        pullRequests: data.pullRequests,
+        commits: data.commits,
+        branches: data.branches,
+        repoMetadata: data.repoMetadata,
+        releases: data.releases
+      };
+    case "content-model":
+      return {
+        contentModel: data.contentModel
+      };
+    case "person":
+      return {
+        issues: data.issues.map((issue) => ({
+          number: issue.number,
+          title: issue.title,
+          state: issue.state,
+          assignees: issue.assignees,
+          user: issue.user
+        })),
+        pullRequests: data.pullRequests.map((pr) => ({
+          number: pr.number,
+          title: pr.title,
+          state: pr.state,
+          html_url: pr.html_url,
+          user: pr.user,
+          assignees: pr.assignees
+        }))
+      };
+    case "structural":
+      return {
+        structuralFiles: data.structuralFiles,
+        structuredNodeMapRaw: data.structuredNodeMapRaw
+      };
+    default:
+      return stableRepoData(data);
+  }
+}
+function stableStringify(value) {
+  return JSON.stringify(normalizeForJson(value));
+}
+function normalizeForJson(value) {
+  if (Array.isArray(value)) return value.map(normalizeForJson);
+  if (!value || typeof value !== "object") return value;
+  const out = {};
+  for (const key of Object.keys(value).sort()) {
+    const item = value[key];
+    if (typeof item !== "function" && item !== void 0) {
+      out[key] = normalizeForJson(item);
+    }
+  }
+  return out;
+}
+var DB_NAME = "kbexplorer-graph-store";
+var STORE_NAME = "sqlite";
+var DB_KEY = "graph-store.sqlite";
+var sqlModuleCache = /* @__PURE__ */ new Map();
+async function loadSqlJs(locateFile) {
+  const cacheKey = locateFile ?? "default";
+  const cached = sqlModuleCache.get(cacheKey);
+  if (cached) return cached;
+  const promise = (async () => {
+    if (locateFile) {
+      return initSqlJs__default.default({ locateFile });
+    }
+    if (typeof process !== "undefined" && process.versions?.node) {
+      const { nodeLocateFile: nodeLocateFile2 } = await Promise.resolve().then(() => (init_node_wasm(), node_wasm_exports));
+      return initSqlJs__default.default({ locateFile: nodeLocateFile2() });
+    }
+    return initSqlJs__default.default();
+  })();
+  sqlModuleCache.set(cacheKey, promise);
+  return promise;
+}
+async function openPersistedDatabase(byteStore = new IndexedDbSqliteByteStore(), locateFile) {
+  const SQL = await loadSqlJs(locateFile);
+  const bytes = await byteStore.load();
+  const db = bytes ? new SQL.Database(bytes) : new SQL.Database();
+  return {
+    db,
+    persist: async () => {
+      await byteStore.save(db.export());
+    }
+  };
+}
+var MemorySqliteByteStore = class {
+  bytes;
+  async load() {
+    return this.bytes ? new Uint8Array(this.bytes) : void 0;
+  }
+  async save(bytes) {
+    this.bytes = new Uint8Array(bytes);
+  }
+};
+var IndexedDbSqliteByteStore = class {
+  async load() {
+    const db = await openIndexedDb();
+    return requestToPromise(
+      db.transaction(STORE_NAME, "readonly").objectStore(STORE_NAME).get(DB_KEY)
+    ).finally(() => db.close());
+  }
+  async save(bytes) {
+    const db = await openIndexedDb();
+    await requestToPromise(
+      db.transaction(STORE_NAME, "readwrite").objectStore(STORE_NAME).put(bytes, DB_KEY)
+    ).finally(() => db.close());
+  }
+};
+function openIndexedDb() {
+  if (!globalThis.indexedDB) {
+    throw new Error("Graph store SQLite persistence requires IndexedDB support.");
+  }
+  return new Promise((resolve, reject) => {
+    const request = globalThis.indexedDB.open(DB_NAME, 1);
+    request.onupgradeneeded = () => {
+      request.result.createObjectStore(STORE_NAME);
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error("Failed to open graph store IndexedDB database."));
+  });
+}
+function requestToPromise(request) {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error ?? new Error("IndexedDB graph store request failed."));
+  });
+}
+
+// src/store/sqlite-graph-store.ts
+var SQLITE_SCHEMA_VERSION = "sqlite-graph-store-v1";
+var SQLiteGraphStore = class _SQLiteGraphStore {
+  db;
+  persist;
+  constructor(db, persist) {
+    this.db = db;
+    this.persist = persist;
+    this.migrate();
+  }
+  static async create(byteStore, locateFile) {
+    const { db, persist } = await openPersistedDatabase(byteStore, locateFile);
+    return new _SQLiteGraphStore(db, persist);
+  }
+  async get(key) {
+    const row = this.selectEntry(kbexplorerCore.formatGraphStoreCacheKey(key));
+    if (!row) return void 0;
+    const entry = rowToEntry(row);
+    if (kbexplorerCore.formatGraphStoreCacheKey(entry.key) !== kbexplorerCore.formatGraphStoreCacheKey(key)) {
+      return void 0;
+    }
+    return entry;
+  }
+  async put(entry) {
+    const now = (/* @__PURE__ */ new Date()).toISOString();
+    const createdAt = entry.createdAt ?? now;
+    const updatedAt = entry.updatedAt ?? now;
+    this.db.run(
+      `insert into entries (
+        cache_key, key_json, scope, provider_id, source_id, variant, content_hash,
+        value_json, dependencies_json, metadata_json, created_at, updated_at
+      ) values (
+        $cache_key, $key_json, $scope, $provider_id, $source_id, $variant, $content_hash,
+        $value_json, $dependencies_json, $metadata_json, $created_at, $updated_at
+      )
+      on conflict(cache_key) do update set
+        key_json = excluded.key_json,
+        scope = excluded.scope,
+        provider_id = excluded.provider_id,
+        source_id = excluded.source_id,
+        variant = excluded.variant,
+        content_hash = excluded.content_hash,
+        value_json = excluded.value_json,
+        dependencies_json = excluded.dependencies_json,
+        metadata_json = excluded.metadata_json,
+        updated_at = excluded.updated_at`,
+      {
+        $cache_key: kbexplorerCore.formatGraphStoreCacheKey(entry.key),
+        $key_json: JSON.stringify(entry.key),
+        $scope: entry.key.scope,
+        $provider_id: entry.key.providerId,
+        $source_id: entry.key.sourceId ?? null,
+        $variant: entry.key.variant ?? null,
+        $content_hash: kbexplorerCore.formatContentHash(entry.key.contentHash),
+        $value_json: JSON.stringify(entry.value),
+        $dependencies_json: JSON.stringify(entry.dependencies ?? []),
+        $metadata_json: JSON.stringify(entry.metadata ?? {}),
+        $created_at: createdAt,
+        $updated_at: updatedAt
+      }
+    );
+    await this.persist();
+  }
+  async delete(key) {
+    const cacheKey = kbexplorerCore.formatGraphStoreCacheKey(key);
+    const before = this.countEntries();
+    this.db.run("delete from entries where cache_key = $cache_key", { $cache_key: cacheKey });
+    const deleted = this.countEntries() < before;
+    if (deleted) await this.persist();
+    return deleted;
+  }
+  async invalidate(match) {
+    const rows = this.selectEntries();
+    let deleted = 0;
+    for (const row of rows) {
+      const entry = rowToEntry(row);
+      if (matchesInvalidation(entry, match)) {
+        this.db.run("delete from entries where cache_key = $cache_key", { $cache_key: row.cache_key });
+        deleted++;
+      }
+    }
+    if (deleted > 0) await this.persist();
+    return deleted;
+  }
+  migrate() {
+    this.db.run(`
+      create table if not exists metadata (
+        key text primary key,
+        value text not null
+      );
+      create table if not exists entries (
+        cache_key text primary key,
+        key_json text not null,
+        scope text not null,
+        provider_id text not null,
+        source_id text,
+        variant text,
+        content_hash text not null,
+        value_json text not null,
+        dependencies_json text not null,
+        metadata_json text not null,
+        created_at text not null,
+        updated_at text not null
+      );
+      create index if not exists idx_entries_scope on entries(scope);
+      create index if not exists idx_entries_provider on entries(provider_id);
+      create index if not exists idx_entries_source on entries(source_id);
+      create index if not exists idx_entries_variant on entries(variant);
+      create index if not exists idx_entries_content_hash on entries(content_hash);
+    `);
+    this.setMetadata("sqlite_schema_version", SQLITE_SCHEMA_VERSION);
+    this.setMetadata("graph_store_api_version", kbexplorerCore.GRAPH_STORE_API_VERSION);
+    this.setMetadata("graph_store_cache_key_version", kbexplorerCore.GRAPH_STORE_CACHE_KEY_VERSION);
+    this.setMetadata("graph_store_derivation_version", GRAPH_STORE_DERIVATION_VERSION);
+  }
+  setMetadata(key, value) {
+    this.db.run(
+      `insert into metadata (key, value) values ($key, $value)
+       on conflict(key) do update set value = excluded.value`,
+      { $key: key, $value: value }
+    );
+  }
+  selectEntry(cacheKey) {
+    const statement = this.db.prepare(
+      `select cache_key, key_json, value_json, dependencies_json, metadata_json, created_at, updated_at
+       from entries where cache_key = $cache_key limit 1`
+    );
+    try {
+      statement.bind({ $cache_key: cacheKey });
+      if (!statement.step()) return void 0;
+      return statement.getAsObject();
+    } finally {
+      statement.free();
+    }
+  }
+  selectEntries() {
+    const statement = this.db.prepare(
+      "select cache_key, key_json, value_json, dependencies_json, metadata_json, created_at, updated_at from entries"
+    );
+    const rows = [];
+    try {
+      while (statement.step()) {
+        rows.push(statement.getAsObject());
+      }
+      return rows;
+    } finally {
+      statement.free();
+    }
+  }
+  countEntries() {
+    const statement = this.db.prepare("select count(*) as count from entries");
+    try {
+      if (!statement.step()) return 0;
+      const row = statement.getAsObject();
+      return row.count;
+    } finally {
+      statement.free();
+    }
+  }
+};
+function rowToEntry(row) {
+  try {
+    return {
+      key: JSON.parse(row.key_json),
+      value: JSON.parse(row.value_json),
+      dependencies: JSON.parse(row.dependencies_json) ?? [],
+      metadata: JSON.parse(row.metadata_json),
+      createdAt: row.created_at,
+      updatedAt: row.updated_at
+    };
+  } catch (err) {
+    throw new Error(`Failed to deserialize graph store entry ${row.cache_key}: ${err instanceof Error ? err.message : String(err)}`, {
+      cause: err
+    });
+  }
+}
+function matchesInvalidation(entry, match) {
+  if (match.scope && entry.key.scope !== match.scope) return false;
+  if (match.providerId && entry.key.providerId !== match.providerId) return false;
+  if (match.sourceId && entry.key.sourceId !== match.sourceId) {
+    const dependencyMatch = entry.dependencies?.some((dep) => dep.sourceId === match.sourceId) ?? false;
+    if (!dependencyMatch) return false;
+  }
+  if (match.variant && entry.key.variant !== match.variant) return false;
+  if (match.contentHash) {
+    const hash = kbexplorerCore.formatContentHash(match.contentHash);
+    const keyMatch = kbexplorerCore.formatContentHash(entry.key.contentHash) === hash;
+    const dependencyMatch = entry.dependencies?.some((dep) => kbexplorerCore.formatContentHash(dep.contentHash) === hash) ?? false;
+    if (!keyMatch && !dependencyMatch) return false;
+  }
+  return true;
+}
+var SANITIZE_OPTIONS = {
+  allowedTags: [
+    // Blocks / structure
+    "p",
+    "br",
+    "hr",
+    "h1",
+    "h2",
+    "h3",
+    "h4",
+    "h5",
+    "h6",
+    "ul",
+    "ol",
+    "li",
+    "blockquote",
+    "pre",
+    "code",
+    "div",
+    "span",
+    // Inline formatting
+    "em",
+    "strong",
+    "del",
+    "a",
+    "img",
+    // Tables (GFM)
+    "table",
+    "thead",
+    "tbody",
+    "tr",
+    "td",
+    "th",
+    // Collapsible sections + theme-aware images (used in real issue/PR/README HTML)
+    "details",
+    "summary",
+    "picture",
+    "source",
+    // GFM task-list checkboxes are markdown-generated (`- [ ]` / `- [x]`)
+    "input"
+  ],
+  allowedAttributes: {
+    a: ["href", "title"],
+    img: ["src", "alt", "title", "width", "height"],
+    source: ["srcset", "media", "type", "sizes"],
+    // `start` is markdown-generated for ordered lists that don't begin at 1
+    // (`4.` → `<ol start="4">`); `reversed`/`type` are safe presentational
+    // siblings. Dropping `start` would silently reset list numbering.
+    ol: ["start", "reversed", "type"],
+    // GFM column alignment renders as `align` on the header/data cells
+    // (`|:-:|` → `<th align="center">`); the rest are safe structural/a11y
+    // attributes real HTML tables use. All are presentational — no script sink.
+    th: ["align", "colspan", "rowspan", "scope"],
+    td: ["align", "colspan", "rowspan"],
+    // Only the attributes marked emits for task-list checkboxes — no `on*`,
+    // no `src`/`formaction`, so an allowed `<input>` is inert.
+    input: ["type", "checked", "disabled"],
+    // `class` carries `language-*` on fenced code, which the diagram/mermaid
+    // detection and syntax styling read. Kept minimal — no `style`, no `id`.
+    code: ["class"],
+    pre: ["class"],
+    span: ["class"],
+    div: ["class"]
+  },
+  // URL schemes permitted on href/src/srcset after entity + whitespace
+  // normalization. Relative targets (no scheme) are always allowed; anything
+  // with a `javascript:`/`data:`/`vbscript:`/etc. scheme is dropped.
+  allowedSchemes: ["http", "https", "mailto"],
+  allowedSchemesAppliedToAttributes: ["href", "src", "srcset"],
+  // Reject protocol-relative (`//host/…`) targets — they inherit the page
+  // scheme and can point at an arbitrary host.
+  allowProtocolRelative: false,
+  // Non-allowlisted tags become visible escaped text rather than being dropped,
+  // preserving the previous renderer's "hostile markup shows as inert text"
+  // property for tags like <script>/<style>/<iframe>/<svg>.
+  disallowedTagsMode: "escape"
+};
+var markdown = new marked.Marked();
+function renderSafeMarkdown(body) {
+  const html = markdown.parse(body, { async: false });
+  return sanitizeHtml__default.default(html, SANITIZE_OPTIONS);
+}
+var TEMPLATE_SENSITIVE_CLASSIFICATIONS = /* @__PURE__ */ new Set(["restricted", "confidential", "unknown"]);
+var TEMPLATE_SENSITIVE_VISIBILITIES = /* @__PURE__ */ new Set(["private"]);
+var TEMPLATE_KNOWN_CLASSIFICATIONS = /* @__PURE__ */ new Set(["public", "internal", "confidential", "restricted", "unknown"]);
+var TEMPLATE_CORE_EXCLUSION = kbexplorerCore.resolveAccessExclusion(kbexplorerCore.DEFAULT_ACCESS_EXCLUSION);
+function normalizeAccessValue(value) {
+  return kbexplorerCore.normalizeAccessLabel(value) ?? kbexplorerCore.coerceAccessLabel(value);
+}
+function isTemplateCoreExcluded(label) {
+  if (!label) return false;
+  const classification = label.classification?.trim().toLowerCase();
+  if (classification && !TEMPLATE_KNOWN_CLASSIFICATIONS.has(classification)) {
+    return false;
+  }
+  return kbexplorerCore.isExcludedByDefault(label, TEMPLATE_CORE_EXCLUSION);
+}
+function isAccessWithheld(node) {
+  const access = node.access;
+  if (!access) return false;
+  const label = normalizeAccessValue(access);
+  if (!label) return false;
+  const classification = label.classification?.trim().toLowerCase();
+  if (classification && TEMPLATE_SENSITIVE_CLASSIFICATIONS.has(classification)) {
+    return true;
+  }
+  const visibility = label.visibility?.trim().toLowerCase();
+  if (visibility && TEMPLATE_SENSITIVE_VISIBILITIES.has(visibility)) {
+    return true;
+  }
+  return isTemplateCoreExcluded(label);
+}
+function filterAccessWithheld(nodes) {
+  const kept = nodes.filter((n) => !isAccessWithheld(n));
+  return kept.length === nodes.length ? nodes : kept;
+}
+
+// src/parser.ts
+function extractIssueRefs(body) {
+  if (!body) return [];
+  const matches = body.matchAll(/#(\d+)/g);
+  return [...matches].map((m) => Number(m[1]));
+}
+function splitIntoSections(parentId, parentTitle, rawContent, cluster, emoji, source, allNodes) {
+  const lines = rawContent.split("\n");
+  const sections = [];
+  let currentSection = null;
+  const introLines = [];
+  for (const line of lines) {
+    const headingMatch = line.match(/^##\s+(.+)/);
+    if (headingMatch) {
+      if (currentSection) sections.push(currentSection);
+      currentSection = { title: headingMatch[1].trim(), lines: [] };
+    } else if (currentSection) {
+      currentSection.lines.push(line);
+    } else {
+      introLines.push(line);
+    }
+  }
+  if (currentSection) sections.push(currentSection);
+  if (sections.length < 2) return [];
+  const result = [];
+  const introContent = introLines.join("\n").trim();
+  const introHtml = introContent ? renderSafeMarkdown(introContent) : "";
+  const sectionIds = sections.map((s, i) => `${parentId}/${slugify(s.title, i)}`);
+  const parentNode = {
+    id: parentId,
+    title: parentTitle,
+    cluster,
+    content: introHtml,
+    rawContent: introContent,
+    emoji,
+    nodeType: "parent",
+    connections: sectionIds.map((sid) => ({ to: sid, type: "contains", description: "Contains", source: "inferred" })),
+    source
+  };
+  const lower = rawContent.toLowerCase();
+  for (const n of allNodes) {
+    if (n.id === parentId) continue;
+    const titleWords = n.title.toLowerCase().split(/\s+/).filter((w) => w.length > 3);
+    if (titleWords.length === 0) continue;
+    const matchCount = titleWords.filter((w) => lower.includes(w)).length;
+    if (matchCount >= Math.ceil(titleWords.length * 0.6)) {
+      parentNode.connections.push({ to: n.id, type: "mentions", description: "Mentions", source: "inferred" });
+    }
+  }
+  result.push(parentNode);
+  for (let i = 0; i < sections.length; i++) {
+    const s = sections[i];
+    const sectionId = sectionIds[i];
+    const sectionBody = s.lines.join("\n").trim();
+    const sectionHtml = sectionBody ? renderSafeMarkdown(sectionBody) : "";
+    const sectionNode = {
+      id: sectionId,
+      title: s.title,
+      cluster,
+      content: sectionHtml,
+      rawContent: sectionBody,
+      emoji,
+      parent: parentId,
+      nodeType: "section",
+      connections: [],
+      source
+    };
+    const sLower = sectionBody.toLowerCase();
+    const refs = extractIssueRefs(sectionBody);
+    for (const num of refs) {
+      const refId = `issue-${num}`;
+      if (allNodes.some((n) => n.id === refId)) {
+        sectionNode.connections.push({ to: refId, type: "cross_references", description: `References #${num}`, source: "inline" });
+      }
+    }
+    for (const n of allNodes) {
+      if (n.source.type === "file") {
+        const dirName = n.title.replace(/\/$/, "").toLowerCase();
+        if (sLower.includes(`${dirName}/`) || sLower.includes(`\`${dirName}\``)) {
+          sectionNode.connections.push({ to: n.id, type: "references", description: `References ${n.title}`, source: "inferred" });
+        }
+      }
+    }
+    result.push(sectionNode);
+  }
+  return result;
+}
+function slugify(title, idx) {
+  const slug = title.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+  return slug || `section-${idx}`;
+}
+function extractClusters(nodes, config) {
+  const configClusters = new Map(
+    Object.entries(config.clusters).map(([id, c]) => [id, { id, ...c }])
+  );
+  const palette = [
+    "#E8A838",
+    "#4A9CC8",
+    "#8CB050",
+    "#C07840",
+    "#D4A050",
+    "#5A98A8",
+    "#9A8A78",
+    "#C04040",
+    "#A86FDF",
+    "#39FF14",
+    "#FF6B6B",
+    "#4ECDC4"
+  ];
+  let colorIdx = 0;
+  const seenIds = /* @__PURE__ */ new Set();
+  for (const node of nodes) {
+    if (!seenIds.has(node.cluster)) {
+      seenIds.add(node.cluster);
+      if (!configClusters.has(node.cluster)) {
+        configClusters.set(node.cluster, {
+          id: node.cluster,
+          name: node.cluster.split(/[-_]/).map((w) => w.length <= 3 ? w.toUpperCase() : w.charAt(0).toUpperCase() + w.slice(1)).join(" "),
+          color: palette[colorIdx % palette.length]
+        });
+        colorIdx++;
+      }
+    }
+  }
+  return [...configClusters.values()];
+}
+
+// src/edge-weights.ts
+var EDGE_TYPE_WEIGHTS = {
+  contains: 5,
+  derived_from: 3,
+  imports: 2,
+  references: 2,
+  frontmatter: 1.5,
+  cross_references: 1.5,
+  modifies: 1,
+  closes: 2,
+  mentions: 0.5,
+  related: 0.3
+};
+function getEdgeWeight(type) {
+  return EDGE_TYPE_WEIGHTS[type ?? "related"] ?? 1;
+}
+
+// src/node-types/registry.ts
+var registry = /* @__PURE__ */ new Map();
+var BUILT_IN_NODE_TYPES = [
+  { id: "authored", layer: "content", label: "Authored" },
+  { id: "readme", layer: "content", label: "README" },
+  { id: "derived", layer: "content", label: "Derived" },
+  { id: "section", layer: "content", label: "Section" },
+  { id: "structured", layer: "content", label: "Structured" },
+  { id: "issue", layer: "work", label: "Issue" },
+  { id: "pull_request", layer: "work", label: "Pull Request" },
+  { id: "commit", layer: "work", label: "Commit" },
+  { id: "branch", layer: "work", label: "Branch" },
+  { id: "workflow", layer: "work", label: "Workflow" },
+  { id: "repository", layer: "work", label: "Repository" },
+  { id: "release", layer: "work", label: "Release", cluster: "releases", description: "A GitHub release (tag, name, release notes)." },
+  // Person nodes derived from GitHub activity (#235)
+  { id: "person", layer: "work", label: "Person", cluster: "person", description: "A person derived from GitHub activity or a content-model descriptor." },
+  { id: "file", layer: "file", label: "File" },
+  { id: "external", layer: "file", label: "External" }
+];
+function registerBuiltInNodeTypes() {
+  for (const def of BUILT_IN_NODE_TYPES) {
+    if (!registry.has(def.id)) registry.set(def.id, def);
+  }
+}
+function resolveNodeLayer(node) {
+  const byEntity = node.entityType ? registry.get(node.entityType) : void 0;
+  if (byEntity?.layer) return byEntity.layer;
+  const bySource = registry.get(node.source.type);
+  if (bySource?.layer) return bySource.layer;
+  return "file";
+}
+registerBuiltInNodeTypes();
+
+// src/graph.ts
+function buildGraph(nodes, clusters) {
+  nodes = filterAccessWithheld(nodes);
+  for (const node of nodes) {
+    node.layer = resolveNodeLayer(node);
+  }
+  const nodeMap = /* @__PURE__ */ new Map();
+  for (const n of nodes) {
+    const prev = nodeMap.get(n.id);
+    if (prev && (prev.provider ?? "(none)") !== (n.provider ?? "(none)")) {
+      console.warn(
+        `[kbexplorer] cross-provider id collision: "${n.id}" is produced by provider "${prev.provider ?? "(none)"}" and provider "${n.provider ?? "(none)"}" \u2014 edge/related resolution will last-win on the latter. Give one a distinct id.`
+      );
+    }
+    nodeMap.set(n.id, n);
+  }
+  const edges = buildEdges(nodes, nodeMap);
+  const connected = /* @__PURE__ */ new Set();
+  for (const e of edges) {
+    connected.add(e.from);
+    connected.add(e.to);
+  }
+  const orphans = nodes.filter((n) => !connected.has(n.id));
+  if (orphans.length > 0) {
+    const degrees = /* @__PURE__ */ new Map();
+    for (const n of nodes) degrees.set(n.id, 0);
+    for (const e of edges) {
+      degrees.set(e.from, (degrees.get(e.from) ?? 0) + 1);
+      degrees.set(e.to, (degrees.get(e.to) ?? 0) + 1);
+    }
+    let hubId = nodes[0]?.id;
+    let hubDeg = 0;
+    for (const [id, deg] of degrees) {
+      if (deg > hubDeg) {
+        hubDeg = deg;
+        hubId = id;
+      }
+    }
+    for (const orphan of orphans) {
+      const sibling = nodes.find((n) => n.id !== orphan.id && n.cluster === orphan.cluster && connected.has(n.id));
+      const targetId = sibling?.id ?? hubId;
+      if (targetId && targetId !== orphan.id) {
+        edges.push({ from: targetId, to: orphan.id, type: "related", description: "Related", source: "inferred", weight: EDGE_TYPE_WEIGHTS.related });
+        connected.add(orphan.id);
+      }
+    }
+  }
+  const related = computeRelated(nodes, edges);
+  return { nodes, edges, clusters, related };
+}
+function buildEdges(nodes, nodeMap) {
+  const edgeSet = /* @__PURE__ */ new Map();
+  const addEdge = (edge) => {
+    const key = edgeKey(edge);
+    if (!edgeSet.has(key)) {
+      edgeSet.set(key, edge);
+    }
+  };
+  for (const node of nodes) {
+    for (const conn of node.connections) {
+      if (nodeMap.has(conn.to)) {
+        const edgeType = conn.type ?? "references";
+        addEdge({
+          from: node.id,
+          to: conn.to,
+          type: edgeType,
+          description: conn.description,
+          source: conn.source ?? "frontmatter",
+          weight: conn.weight ?? getEdgeWeight(edgeType),
+          ...conn.relation ? { relation: conn.relation } : {}
+        });
+      }
+    }
+    if (node.parent && nodeMap.has(node.parent)) {
+      addEdge({
+        from: node.parent,
+        to: node.id,
+        type: "contains",
+        description: "Contains",
+        source: "inferred",
+        weight: EDGE_TYPE_WEIGHTS.contains
+      });
+    }
+  }
+  return [...edgeSet.values()];
+}
+function edgeKey(edge) {
+  return `${edge.from}\0${edge.to}\0${edge.type}\0${edge.relation ?? ""}`;
+}
+function computeRelated(nodes, edges) {
+  const adj = /* @__PURE__ */ new Map();
+  for (const node of nodes) {
+    adj.set(node.id, /* @__PURE__ */ new Map());
+  }
+  for (const edge of edges) {
+    const fwd = adj.get(edge.from);
+    const rev = adj.get(edge.to);
+    if (fwd && (!fwd.has(edge.to) || edge.weight > (fwd.get(edge.to) ?? 0))) {
+      fwd.set(edge.to, edge.weight);
+    }
+    if (rev && (!rev.has(edge.from) || edge.weight > (rev.get(edge.from) ?? 0))) {
+      rev.set(edge.from, edge.weight);
+    }
+  }
+  const degree = /* @__PURE__ */ new Map();
+  for (const [id, neighbors] of adj) {
+    degree.set(id, neighbors.size);
+  }
+  const related = {};
+  for (const [id, neighbors] of adj) {
+    related[id] = [...neighbors.entries()].sort((a, b) => {
+      const weightDiff = b[1] - a[1];
+      if (Math.abs(weightDiff) > 0.01) return weightDiff;
+      return (degree.get(b[0]) ?? 0) - (degree.get(a[0]) ?? 0);
+    }).map(([neighborId]) => neighborId).slice(0, 12);
+  }
+  return related;
+}
+
+// src/transforms.ts
+function selectIssueNodes(nodes) {
+  return nodes.filter((n) => n.source.type === "issue");
+}
+function selectDirNodes(nodes) {
+  return nodes.filter((n) => n.provider === "files");
+}
+var readmeTransform = {
+  name: "readme",
+  apply(nodes, ctx) {
+    if (!ctx.readme) return nodes;
+    const readme = ctx.readme;
+    const issueNodes = selectIssueNodes(nodes);
+    const dirNodes = selectDirNodes(nodes);
+    const readmeConns = [];
+    const lower = readme.toLowerCase();
+    const issueRefs = extractIssueRefs(readme);
+    for (const num of issueRefs) {
+      const id = `issue-${num}`;
+      if (issueNodes.some((n) => n.id === id)) {
+        readmeConns.push({ to: id, description: `References #${num}` });
+      }
+    }
+    for (const node of issueNodes) {
+      if (readmeConns.some((c) => c.to === node.id)) continue;
+      const titleWords = node.title.toLowerCase().split(/\s+/).filter((w) => w.length > 3);
+      if (titleWords.length === 0) continue;
+      const matchCount = titleWords.filter((w) => lower.includes(w)).length;
+      if (matchCount >= Math.ceil(titleWords.length * 0.6)) {
+        readmeConns.push({ to: node.id, description: "Mentions" });
+      }
+    }
+    for (const dir of dirNodes) {
+      const dirName = dir.title.replace(/\/$/, "");
+      if (lower.includes(`${dirName}/`) || lower.includes(`\`${dirName}\``)) {
+        readmeConns.push({ to: dir.id, description: `References ${dirName}/` });
+      }
+    }
+    readmeConns.push({ to: "repo-root", description: "Documents" });
+    const readmeConnectedTo = new Set(readmeConns.map((c) => c.to));
+    for (const m of readme.matchAll(/\[([^\]]+)\]\(([^)]+)\)/g)) {
+      const target = m[2].trim();
+      if (target.startsWith("http") || target.startsWith("#") || target.startsWith("/")) continue;
+      if (target.match(/\.(png|jpg|jpeg|gif|svg|webp|md)$/i)) continue;
+      if (readmeConnectedTo.has(target)) continue;
+      readmeConns.push({ to: target, description: m[1] });
+      readmeConnectedTo.add(target);
+    }
+    const html = renderSafeMarkdown(readme);
+    nodes.push({
+      id: "readme",
+      title: "README",
+      cluster: "docs",
+      content: html,
+      rawContent: readme,
+      emoji: "Document",
+      parent: "repo-root",
+      identity: "urn:content:readme",
+      connections: readmeConns,
+      source: { type: "readme" }
+    });
+    return nodes;
+  }
+};
+var issueDirectoryLinkTransform = {
+  name: "issue-directory-link",
+  apply(nodes) {
+    const issueNodes = selectIssueNodes(nodes);
+    const dirNodes = selectDirNodes(nodes);
+    const dirNames = dirNodes.map((d) => d.title.replace(/\/$/, ""));
+    for (const node of issueNodes) {
+      for (let i = 0; i < dirNames.length; i++) {
+        const dir = dirNames[i];
+        if (node.rawContent && (node.rawContent.includes(`${dir}/`) || node.rawContent.includes(`\`${dir}\``) || node.rawContent.toLowerCase().includes(dir.toLowerCase()))) {
+          node.connections.push({ to: dirNodes[i].id, description: `References ${dir}/` });
+        }
+      }
+    }
+    return nodes;
+  }
+};
+var issueSplitTransform = {
+  name: "issue-split",
+  apply(nodes) {
+    const issueNodes = selectIssueNodes(nodes);
+    const dirNodes = selectDirNodes(nodes);
+    const expandedIssues = [];
+    for (const node of issueNodes) {
+      const sectionNodes = splitIntoSections(
+        node.id,
+        node.title,
+        node.rawContent,
+        node.cluster,
+        node.emoji ?? "Pin",
+        node.source,
+        [...issueNodes, ...dirNodes]
+      );
+      if (sectionNodes.length > 0) {
+        const idx = nodes.indexOf(node);
+        if (idx >= 0) nodes.splice(idx, 1);
+        expandedIssues.push(...sectionNodes);
+      }
+    }
+    nodes.push(...expandedIssues);
+    return nodes;
+  }
+};
+var DEFAULT_TRANSFORMS = [
+  readmeTransform,
+  issueDirectoryLinkTransform,
+  issueSplitTransform
+];
+function applyTransforms(nodes, ctx, transforms = DEFAULT_TRANSFORMS) {
+  let current = nodes;
+  for (const transform of transforms) {
+    current = transform.apply(current, ctx);
+  }
+  return current;
+}
+async function orchestrateWithProviderResultStore(registry2, config, ctx, store, buildCacheKey, transforms = DEFAULT_TRANSFORMS) {
+  const providers = registry2.getExecutionOrder();
+  let allNodes = [];
+  let previousContentHash;
+  for (const provider of providers) {
+    const key = await buildCacheKey(provider.id, previousContentHash);
+    const cached = await store.get(key);
+    if (cached) {
+      allNodes = cloneProviderResult(
+        validateProviderResult(cached.value, `cached graph store entry for ${provider.id}`)
+      ).nodes;
+      previousContentHash = await hashProviderResultPrefix(provider.id, allNodes);
+      continue;
+    }
+    const result = await provider.resolve(config, allNodes);
+    allNodes.push(...result.nodes);
+    const value = cloneProviderResult({ nodes: allNodes, edges: [] });
+    await store.put({
+      key,
+      value,
+      dependencies: [dependencyFor(key, previousContentHash)],
+      metadata: {
+        graphStoreApiVersion: kbexplorerCore.GRAPH_STORE_API_VERSION,
+        graphStoreCacheKeyVersion: kbexplorerCore.GRAPH_STORE_CACHE_KEY_VERSION,
+        graphStoreDerivationVersion: GRAPH_STORE_DERIVATION_VERSION,
+        providerId: provider.id
+      }
+    });
+    previousContentHash = await hashProviderResultPrefix(provider.id, allNodes);
+  }
+  const transformed = applyTransforms(allNodes, ctx, transforms);
+  return buildGraph(transformed, extractClusters(transformed, config));
+}
+function dependencyFor(key, previousContentHash) {
+  return {
+    href: previousContentHash ? `${key.sourceId ?? key.providerId}#previous` : key.sourceId ?? key.providerId,
+    contentHash: previousContentHash ?? key.contentHash,
+    ...key.sourceId !== void 0 ? { sourceId: key.sourceId } : {}
+  };
+}
+function cloneProviderResult(value) {
+  if (typeof structuredClone === "function") {
+    return structuredClone(value);
+  }
+  return JSON.parse(JSON.stringify(value));
+}
+function validateProviderResult(value, label) {
+  if (!value || !Array.isArray(value.nodes) || !Array.isArray(value.edges)) {
+    throw new Error(`Invalid ${label}: expected ProviderResult with nodes and edges arrays.`);
+  }
+  for (const node of value.nodes) {
+    validateNode(node, label);
+  }
+  return value;
+}
+function validateNode(node, label) {
+  if (!node || typeof node.id !== "string" || typeof node.title !== "string" || typeof node.cluster !== "string" || !Array.isArray(node.connections)) {
+    throw new Error(`Invalid ${label}: malformed KBNode.`);
+  }
+}
+
+exports.GRAPH_STORE_DERIVATION_VERSION = GRAPH_STORE_DERIVATION_VERSION;
+exports.GRAPH_STORE_PROVIDER_ID = GRAPH_STORE_PROVIDER_ID;
+exports.IndexedDbSqliteByteStore = IndexedDbSqliteByteStore;
+exports.MemorySqliteByteStore = MemorySqliteByteStore;
+exports.SQLiteGraphStore = SQLiteGraphStore;
+exports.buildProviderResultCacheKey = buildProviderResultCacheKey;
+exports.isGraphStoreEnabled = isGraphStoreEnabled;
+exports.loadSqlJs = loadSqlJs;
+exports.openPersistedDatabase = openPersistedDatabase;
+exports.orchestrateWithProviderResultStore = orchestrateWithProviderResultStore;
+exports.resolveGraphStoreOptions = resolveGraphStoreOptions;