@lucern/graph-primitives 0.1.0-alpha.2

package/dist/epistemicLinking.js

@@ -0,0 +1,1391 @@
+import { v } from 'convex/values';
+import { componentsGeneric, mutationGeneric, anyApi } from 'convex/server';
+
+// src/epistemicLinking.ts
+componentsGeneric();
+var internal = anyApi;
+var mutation = mutationGeneric;
+
+// src/graphTypes.ts
+var EDGE_TYPE_TO_REL = {
+  // === THE SIX CANONICAL EPISTEMIC EDGE TYPES ===
+  supports: "SUPPORTS",
+  // L3↔L3: belief bears on belief (weight -1 to +1)
+  informs: "INFORMS",
+  // L2→L3: evidence bears on belief
+  depends_on: "DEPENDS_ON",
+  // L3→L3, Q→Q: structural gate
+  derived_from: "DERIVED_FROM",
+  // Any→Any: provenance chain (fork, synthesis, extraction, answer)
+  contains: "CONTAINS",
+  // Any→Any: hierarchy, scoping, membership
+  tests: "TESTS",
+  // Q→L3: question interrogates belief
+  // === L4 DECISION EDGES (derived_from with derivationType=decision) ===
+  // Kept as separate Neo4j relationship types for backward compat with L4 queries.
+  // New code should use derived_from + metadata.
+  based_on_belief: "BASED_ON_BELIEF",
+  based_on_question: "BASED_ON_QUESTION",
+  blocked_by_contradiction: "BLOCKED_BY_CONTRADICTION",
+  informed_by_theme: "INFORMED_BY_THEME",
+  // === ONTOLOGICAL EDGES (tenant-extensible, managed by ontology system) ===
+  works_at: "WORKS_AT",
+  invested_in: "INVESTED_IN",
+  competes_with: "COMPETES_WITH",
+  participates_in: "PARTICIPATES_IN",
+  founded_by: "FOUNDED_BY",
+  evaluates: "EVALUATES",
+  performs: "PERFORMS",
+  function_in: "FUNCTION_IN",
+  impacts: "IMPACTS",
+  raised_from: "RAISED_FROM",
+  mentioned_in: "MENTIONED_IN",
+  perspective_on: "PERSPECTIVE_ON",
+  about_entity: "ABOUT_ENTITY",
+  entity_referenced_in: "ENTITY_REFERENCED_IN"
+};
+var CANONICAL_EPISTEMIC_TYPES = /* @__PURE__ */ new Set([
+  "supports",
+  "informs",
+  "depends_on",
+  "derived_from",
+  "contains",
+  "tests"
+]);
+function isDeprecatedEdgeType(edgeType) {
+  if (CANONICAL_EPISTEMIC_TYPES.has(edgeType)) return false;
+  if (edgeType in EDGE_TYPE_TO_REL) return false;
+  return true;
+}
+
+// src/epistemicHelpers.ts
+function getNodeLayer(nodeType) {
+  switch (nodeType) {
+    // L4: Audit targets
+    case "decision":
+      return "L4";
+    // L3: Traversal anchors
+    case "belief":
+    case "question":
+    case "theme":
+    case "deal":
+      return "L3";
+    // L2: Compression boundary
+    case "claim":
+    case "evidence":
+    case "synthesis":
+    case "answer":
+      return "L2";
+    // L1: Terminal leaves
+    case "atomic_fact":
+    case "excerpt":
+    case "source":
+      return "L1";
+    // Ontological entities
+    case "company":
+    case "person":
+    case "investor":
+    case "function":
+    case "value_chain":
+      return "ontological";
+    // Organizational containers
+    case "topic":
+      return "organizational";
+    default:
+      console.warn(
+        `[EpistemicLayer] Unknown nodeType: ${nodeType}, defaulting to L2`
+      );
+      return "L2";
+  }
+}
+var EDGE_LAYER_RULES = {
+  // === L4 Decision Edges ===
+  based_on_belief: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision \u2192 Belief (L4 \u2192 L3)"
+  },
+  based_on_question: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision \u2192 Question (L4 \u2192 L3)"
+  },
+  blocked_by_contradiction: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision \u2192 Contradiction (L4 \u2192 L3)"
+  },
+  informed_by_theme: {
+    from: ["L4"],
+    to: ["L3"],
+    description: "Decision \u2192 Theme (L4 \u2192 L3)"
+  },
+  // === Evidence Flow (L2 → L3, L2 → L1) ===
+  derived_from: {
+    from: ["L2", "L3", "L4"],
+    to: ["L1", "L2", "L3"],
+    description: "A was produced from B (provenance chain)"
+  },
+  answers: {
+    from: ["L2"],
+    to: ["L3"],
+    description: "Evidence \u2192 Question (L2 \u2192 L3)"
+  },
+  responds_to: {
+    from: ["L2"],
+    to: ["L3"],
+    description: "Answer \u2192 Question (L2 \u2192 L3)"
+  },
+  informs: {
+    from: ["L2"],
+    to: ["L3"],
+    description: "Evidence \u2192 Belief (L2 \u2192 L3)"
+  },
+  qualifies: {
+    from: ["L2"],
+    to: ["L3"],
+    description: "Evidence \u2192 Belief (L2 \u2192 L3)"
+  },
+  // === Question → Belief (L3 → L3) ===
+  tests: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Question \u2192 Belief (L3 \u2192 L3)"
+  },
+  explores: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Question \u2192 Belief assumption (L3 \u2192 L3)"
+  },
+  // === Synthesis (L2 → L2, L2 → L1) ===
+  based_on: {
+    from: ["L2"],
+    to: ["L2", "L1"],
+    description: "Synthesis \u2192 Evidence/Source (L2 \u2192 L2/L1)"
+  },
+  // === Theme Relationships (L3 → L3) ===
+  relates_to_thesis: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief \u2192 Theme (L3 \u2192 L3)"
+  },
+  belongs_to: {
+    from: ["L3", "L2"],
+    // Can belong to theme from L3 or L2
+    to: ["L3"],
+    description: "Any \u2192 Theme (L3/L2 \u2192 L3)"
+  },
+  plays_theme: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Deal \u2192 Theme (L3 \u2192 L3)"
+  },
+  // === Topic Hierarchy (L3 → organizational) ===
+  scoped_by: {
+    from: ["L3"],
+    to: ["organizational"],
+    description: "Belief/Question \u2192 Topic (L3 \u2192 organizational)"
+  },
+  // === Deal/Company ===
+  evaluates: {
+    from: ["L3"],
+    to: ["ontological"],
+    description: "Deal \u2192 Company (L3 \u2192 ontological)"
+  },
+  // === People (ontological → ontological, ontological → L3) ===
+  perspective_on: {
+    from: ["ontological"],
+    to: ["L3"],
+    description: "Person \u2192 Belief/Theme (ontological \u2192 L3)"
+  },
+  works_at: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Person \u2192 Company (ontological \u2192 ontological)"
+  },
+  // === Value Chain (ontological) ===
+  participates_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company \u2192 ValueChain (ontological \u2192 ontological)"
+  },
+  performs: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company \u2192 Function (ontological \u2192 ontological)"
+  },
+  function_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Function \u2192 ValueChain (ontological \u2192 ontological)"
+  },
+  impacts: {
+    from: ["L3"],
+    to: ["ontological"],
+    description: "Theme \u2192 ValueChain (L3 \u2192 ontological)"
+  },
+  // === Investment (ontological) ===
+  invested_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Investor \u2192 Company (ontological \u2192 ontological)"
+  },
+  raised_from: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company \u2192 Investor (ontological \u2192 ontological)"
+  },
+  // === Entity↔Belief Bridge (OE-B) ===
+  about_entity: {
+    from: ["L3"],
+    to: ["ontological"],
+    description: "Belief/Question/Theme \u2192 Entity (L3 \u2192 ontological)"
+  },
+  entity_referenced_in: {
+    from: ["ontological"],
+    to: ["L2"],
+    description: "Entity \u2192 Evidence (ontological \u2192 L2)"
+  },
+  mentioned_in: {
+    from: ["ontological"],
+    to: ["L1"],
+    description: "Entity \u2192 Source document (ontological \u2192 L1)"
+  },
+  founded_by: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company \u2192 Person (ontological \u2192 ontological)"
+  },
+  competes_with: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company \u2192 Company (ontological \u2192 ontological)"
+  },
+  contains: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "ValueChain \u2192 Function (ontological \u2192 ontological)"
+  },
+  // === Lifecycle (same layer only) ===
+  supersedes: {
+    from: ["L4", "L3", "L2", "L1", "ontological", "organizational"],
+    to: ["L4", "L3", "L2", "L1", "ontological", "organizational"],
+    description: "NewNode \u2192 OldNode (same layer only - validated separately)"
+  },
+  same_as: {
+    from: ["L4", "L3", "L2", "L1", "ontological", "organizational"],
+    to: ["L4", "L3", "L2", "L1", "ontological", "organizational"],
+    description: "Duplicate detection (same layer only - validated separately)"
+  },
+  // === Same-Type: Belief ↔ Belief (L3 → L3) ===
+  depends_on: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief B requires Belief A (L3 \u2192 L3)"
+  },
+  reinforces: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Beliefs strengthen each other (L3 \u2192 L3)"
+  },
+  parent_of: {
+    from: ["L3", "organizational"],
+    to: ["L3", "organizational"],
+    description: "A is higher-level than B (L3 \u2192 L3, organizational \u2192 organizational)"
+  },
+  child_of: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief A is more specific (L3 \u2192 L3)"
+  },
+  // === Same-Type: Question ↔ Question (L3 → L3) ===
+  prerequisite_for: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Question A must be answered first (L3 \u2192 L3)"
+  },
+  parallel_to: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Same topic, different angles (L3 \u2192 L3)"
+  },
+  // === Same-Type: Evidence ↔ Evidence (L2 → L2) ===
+  corroborates: {
+    from: ["L2"],
+    to: ["L2"],
+    description: "Independent support (L2 \u2192 L2)"
+  },
+  extends: {
+    from: ["L2"],
+    to: ["L2"],
+    description: "Adds depth (L2 \u2192 L2)"
+  },
+  same_source_as: {
+    from: ["L2"],
+    to: ["L2"],
+    description: "Same document/study (L2 \u2192 L2)"
+  },
+  same_theme_as: {
+    from: ["L2"],
+    to: ["L2"],
+    description: "Same topic/entity (L2 \u2192 L2)"
+  },
+  // === NEW: Deep Epistemic Analysis Edges (Phase: Schema Upgrade) ===
+  assumes: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Hidden dependency - Belief B implicitly assumes Belief A (L3 \u2192 L3)"
+  },
+  would_predict: {
+    from: ["L3"],
+    to: ["L2"],
+    description: "Pre-registered prediction - If Belief true, expect Evidence (L3 \u2192 L2)"
+  },
+  analogous_to: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Explicit analogy - Belief A is like Belief B (L3 \u2192 L3)"
+  },
+  independent_of: {
+    from: ["L2"],
+    to: ["L2"],
+    description: "True evidence independence - Evidence A independent of B (L2 \u2192 L2)"
+  }
+  // NOTE: Deprecated edge types (supports, contradicts, derived_from, cites,
+  // summarizes, related_to, partially_answers, blocks, refines, branches_from)
+  // have been REMOVED from the system. Use compliant alternatives instead.
+};
+function validateEdgeLayers(edgeType, fromLayer, toLayer) {
+  const rules = EDGE_LAYER_RULES[edgeType];
+  if (!rules) {
+    console.warn(
+      `[EdgeValidation] Unknown edge type: ${edgeType}, allowing by default`
+    );
+    return { valid: true };
+  }
+  if (edgeType === "supersedes") {
+    if (fromLayer !== toLayer) {
+      return {
+        valid: false,
+        reason: `${edgeType} edges must be between nodes of the same layer. Got ${fromLayer} \u2192 ${toLayer}`
+      };
+    }
+    return { valid: true };
+  }
+  if (!rules.from.includes(fromLayer)) {
+    return {
+      valid: false,
+      reason: `Edge type '${edgeType}' does not allow source layer ${fromLayer}. Allowed: ${rules.from.join(", ")}`
+    };
+  }
+  if (!rules.to.includes(toLayer)) {
+    return {
+      valid: false,
+      reason: `Edge type '${edgeType}' does not allow target layer ${toLayer}. Allowed: ${rules.to.join(", ")}`
+    };
+  }
+  return { valid: true };
+}
+var api = anyApi;
+componentsGeneric();
+
+// ../access-control/src/topicProjectOverlay.ts
+var LEGACY_SCOPE_FIELD = "graphScopeProjectId";
+function readNonEmptyString(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function readStringArray(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((entry) => readNonEmptyString(entry)).filter((entry) => Boolean(entry));
+}
+function readMetadata(topic) {
+  return topic.metadata && typeof topic.metadata === "object" ? topic.metadata : {};
+}
+function readLegacyProjectId(value) {
+  if (!value) {
+    return;
+  }
+  return readNonEmptyString(value[LEGACY_SCOPE_FIELD]);
+}
+function coerceVisibility(value) {
+  return value === "private" || value === "team" || value === "firm" || value === "external" || value === "public" ? value : void 0;
+}
+function coerceStatus(value) {
+  return value === "active" || value === "archived" || value === "watching" ? value : void 0;
+}
+function mapProjectType(topic, metadata) {
+  const explicit = readNonEmptyString(metadata.projectType);
+  if (explicit) {
+    return explicit;
+  }
+  if (topic.type === "theme") {
+    return "thematic";
+  }
+  return readNonEmptyString(topic.type) || "general";
+}
+function isProjectLikeTopic(topic) {
+  const metadata = readMetadata(topic);
+  return topic.type === "theme" || topic.type === "thematic" || topic.type === "deal" || topic.type === "monitoring" || readLegacyProjectId(topic) !== void 0 || readNonEmptyString(metadata.projectType) !== void 0;
+}
+async function resolveTopicDoc(ctx, scopeId) {
+  if (ctx?.db && typeof ctx.db.get === "function") {
+    try {
+      const directTopic = await ctx.db.get(scopeId);
+      if (directTopic) {
+        return directTopic;
+      }
+    } catch {
+    }
+  }
+  if (typeof ctx.runQuery !== "function") {
+    return null;
+  }
+  try {
+    const topic = await ctx.runQuery(api.topics.get, {
+      id: String(scopeId)
+    });
+    if (topic?.name !== void 0 && topic?.type !== void 0) {
+      return topic;
+    }
+  } catch {
+  }
+  try {
+    const topic = await ctx.runQuery(api.topics.getByLegacyScopeId, {
+      projectId: String(scopeId)
+    });
+    if (topic?.name !== void 0 && topic?.type !== void 0) {
+      return topic;
+    }
+  } catch {
+  }
+  return null;
+}
+function materializeTopicProjectOverlay(topic, idMode = "legacy") {
+  const metadata = readMetadata(topic);
+  const topicId = String(topic._id);
+  const legacyProjectId = readLegacyProjectId(topic) || readLegacyProjectId(metadata) || readNonEmptyString(metadata.legacyProjectId);
+  const storageProjectId = legacyProjectId || topicId;
+  const outwardId = idMode === "topic" ? topicId : storageProjectId;
+  const visibility = coerceVisibility(topic.visibility) || coerceVisibility(metadata.visibility) || "private";
+  const status = coerceStatus(topic.status) || coerceStatus(metadata.status) || "active";
+  const createdAt = typeof topic.createdAt === "number" ? topic.createdAt : typeof topic._creationTime === "number" ? topic._creationTime : 0;
+  const updatedAt = typeof topic.updatedAt === "number" ? topic.updatedAt : typeof metadata.updatedAt === "number" ? metadata.updatedAt : createdAt;
+  return {
+    ...metadata,
+    _id: outwardId,
+    projectId: outwardId,
+    topicId,
+    storageProjectId,
+    legacyProjectId,
+    name: readNonEmptyString(topic.name) || "Untitled Theme",
+    type: mapProjectType(topic, metadata),
+    description: readNonEmptyString(topic.description),
+    ownerId: readNonEmptyString(metadata.ownerId) || readNonEmptyString(topic.createdBy) || "system",
+    sharedWith: readStringArray(metadata.sharedWith),
+    visibility,
+    tenantId: readNonEmptyString(topic.tenantId) || readNonEmptyString(metadata.tenantId),
+    workspaceId: readNonEmptyString(topic.workspaceId) || readNonEmptyString(metadata.workspaceId),
+    status,
+    tags: readStringArray(metadata.tags),
+    chatCount: typeof metadata.chatCount === "number" ? metadata.chatCount : 0,
+    artifactCount: typeof metadata.artifactCount === "number" ? metadata.artifactCount : 0,
+    lastActivityAt: typeof metadata.lastActivityAt === "number" ? metadata.lastActivityAt : updatedAt,
+    _creationTime: typeof topic._creationTime === "number" ? topic._creationTime : createdAt,
+    createdAt,
+    updatedAt
+  };
+}
+async function resolveTopicProjectOverlay(ctx, scopeId, options = {}) {
+  const topic = await resolveTopicDoc(ctx, scopeId);
+  if (!topic) {
+    return null;
+  }
+  if (options.projectLikeOnly !== false && !isProjectLikeTopic(topic)) {
+    return null;
+  }
+  return materializeTopicProjectOverlay(topic, options.idMode);
+}
+async function listTopicProjectOverlays(ctx, options = {}) {
+  let allTopics = [];
+  if (ctx?.db?.query && typeof ctx.db.query === "function") {
+    try {
+      allTopics = await ctx.db.query("topics").collect();
+    } catch {
+      allTopics = [];
+    }
+  }
+  if (allTopics.length === 0 && typeof ctx.runQuery === "function") {
+    allTopics = (await ctx.runQuery(api.topics.list, {}) ?? []) || [];
+  }
+  return allTopics.filter(
+    (topic) => options.projectLikeOnly === false || isProjectLikeTopic(topic)
+  ).map((topic) => materializeTopicProjectOverlay(topic, options.idMode));
+}
+
+// ../access-control/src/projectGrantsBridge.ts
+var PROJECT_GRANT_STATUSES = ["active", "revoked", "expired"];
+function normalizeString(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : void 0;
+}
+async function resolveGrantScopeIds(ctx, args) {
+  const topicId = normalizeString(args.topicId);
+  const projectId = normalizeString(args.projectId);
+  for (const scopeId of [topicId, projectId]) {
+    if (!scopeId) {
+      continue;
+    }
+    try {
+      const overlay = await resolveTopicProjectOverlay(ctx, scopeId, {
+        idMode: "legacy",
+        projectLikeOnly: false
+      });
+      if (overlay) {
+        return {
+          topicId: normalizeString(overlay.topicId) ?? topicId,
+          projectId: normalizeString(overlay.projectId) ?? projectId ?? scopeId
+        };
+      }
+    } catch {
+    }
+  }
+  return { topicId, projectId };
+}
+async function normalizeProjectGrantRow(ctx, row) {
+  const scope = await resolveGrantScopeIds(ctx, {
+    topicId: row.topicId,
+    projectId: row.projectId
+  });
+  return {
+    ...row,
+    ...scope.topicId ? { topicId: scope.topicId } : {},
+    ...scope.projectId ?? scope.topicId ? { projectId: scope.projectId ?? scope.topicId } : {}
+  };
+}
+async function normalizeProjectGrantRows(ctx, rows) {
+  return await Promise.all(rows.map((row) => normalizeProjectGrantRow(ctx, row)));
+}
+async function listProjectGrantsByPrincipal(ctx, principalId) {
+  const rows = await Promise.all(
+    PROJECT_GRANT_STATUSES.map(
+      (status) => ctx.db.query("projectGrants").withIndex(
+        "by_principal_status",
+        (q) => q.eq("principalId", principalId).eq("status", status)
+      ).collect()
+    )
+  );
+  return await normalizeProjectGrantRows(ctx, rows.flat());
+}
+async function listProjectGrantsByGroup(ctx, groupId) {
+  const rows = await Promise.all(
+    PROJECT_GRANT_STATUSES.map(
+      (status) => ctx.db.query("projectGrants").withIndex(
+        "by_group_status",
+        (q) => q.eq("groupId", groupId).eq("status", status)
+      ).collect()
+    )
+  );
+  return await normalizeProjectGrantRows(ctx, rows.flat());
+}
+function buildScopeMatchers(inputScopeId, resolved) {
+  return new Set(
+    [inputScopeId, resolved.topicId, resolved.projectId].map((value) => normalizeString(value)).filter((value) => Boolean(value))
+  );
+}
+function matchesResolvedScope(row, scopeIds) {
+  const rowTopicId = normalizeString(row.topicId);
+  const rowProjectId = normalizeString(row.projectId);
+  return rowTopicId !== void 0 && scopeIds.has(rowTopicId) || rowProjectId !== void 0 && scopeIds.has(rowProjectId);
+}
+async function bridgeListProjectGrantsByTopicAndPrincipal(ctx, topicId, principalId) {
+  const resolved = await resolveGrantScopeIds(ctx, { topicId });
+  const scopeIds = buildScopeMatchers(topicId, resolved);
+  const rows = await listProjectGrantsByPrincipal(ctx, principalId);
+  return rows.filter((row) => matchesResolvedScope(row, scopeIds));
+}
+async function bridgeListProjectGrantsByTopicAndGroup(ctx, topicId, groupId) {
+  const resolved = await resolveGrantScopeIds(ctx, { topicId });
+  const scopeIds = buildScopeMatchers(topicId, resolved);
+  const rows = await listProjectGrantsByGroup(ctx, groupId);
+  return rows.filter((row) => matchesResolvedScope(row, scopeIds));
+}
+async function bridgeListProjectGrantsByPrincipalStatus(ctx, principalId, status) {
+  const rows = await listProjectGrantsByPrincipal(ctx, principalId);
+  return rows.filter((row) => row.status === status);
+}
+async function bridgeListProjectGrantsByGroupStatus(ctx, groupId, status) {
+  const rows = await listProjectGrantsByGroup(ctx, groupId);
+  return rows.filter((row) => row.status === status);
+}
+async function bridgeInsertProjectGrant(ctx, value) {
+  const resolved = await resolveGrantScopeIds(ctx, value);
+  return await ctx.db.insert("projectGrants", {
+    ...value,
+    ...resolved.topicId ? { topicId: resolved.topicId } : {},
+    ...resolved.projectId ?? resolved.topicId ? { projectId: resolved.projectId ?? resolved.topicId } : {}
+  });
+}
+
+// ../access-control/src/resolvers.ts
+async function findUserByClerkId(ctx, clerkId) {
+  const normalizedClerkId = clerkId.trim();
+  if (!normalizedClerkId) {
+    return null;
+  }
+  if (typeof ctx.runQuery === "function") {
+    try {
+      const bridgedUser = await ctx.runQuery(api.users.getUserByClerkId, {
+        clerkId: normalizedClerkId
+      });
+      if (bridgedUser) {
+        return bridgedUser;
+      }
+    } catch {
+    }
+  }
+  try {
+    const users = await ctx.db.query("users").collect();
+    return users.find((user) => String(user.clerkId ?? "") === normalizedClerkId) ?? null;
+  } catch {
+    return null;
+  }
+}
+async function findUserByPrincipalId(ctx, principalId) {
+  const normalizedPrincipalId = principalId.trim();
+  if (!normalizedPrincipalId) {
+    return null;
+  }
+  try {
+    const users = await ctx.db.query("users").collect();
+    return users.find(
+      (user) => String(user.defaultPrincipalId ?? "") === normalizedPrincipalId
+    ) ?? null;
+  } catch {
+    return null;
+  }
+}
+async function findAgentByPrincipalId(ctx, principalId) {
+  const normalizedPrincipalId = principalId.trim();
+  if (!normalizedPrincipalId) {
+    return null;
+  }
+  if (typeof ctx.runQuery === "function") {
+    try {
+      const bridgedAgent = await ctx.runQuery(
+        api.agents.getAgentByPrincipalId,
+        {
+          principalId: normalizedPrincipalId
+        }
+      );
+      if (bridgedAgent) {
+        return bridgedAgent;
+      }
+    } catch {
+    }
+  }
+  try {
+    const agents = await ctx.db.query("agents").collect();
+    return agents.find(
+      (agent) => String(agent.principalId ?? "") === normalizedPrincipalId
+    ) ?? null;
+  } catch {
+    return null;
+  }
+}
+function defaultResolvers() {
+  return {
+    async getProject(ctx, topicId) {
+      return await resolveTopicProjectOverlay(ctx, topicId, {
+        idMode: "legacy",
+        projectLikeOnly: false
+      });
+    },
+    async listTopics(ctx) {
+      return await listTopicProjectOverlays(ctx, { idMode: "legacy" });
+    },
+    async listTopicsByOwner(ctx, ownerId) {
+      const topics = await listTopicProjectOverlays(ctx, { idMode: "legacy" });
+      return topics.filter((topic) => topic.ownerId === ownerId);
+    },
+    async listTopicsByVisibility(ctx, visibility) {
+      const topics = await listTopicProjectOverlays(ctx, { idMode: "legacy" });
+      return topics.filter((topic) => topic.visibility === visibility);
+    },
+    async listProjectGrantsByProjectAndPrincipal(ctx, topicId, principalId) {
+      return await bridgeListProjectGrantsByTopicAndPrincipal(
+        ctx,
+        topicId,
+        principalId
+      );
+    },
+    async listProjectGrantsByProjectAndGroup(ctx, topicId, groupId) {
+      return await bridgeListProjectGrantsByTopicAndGroup(ctx, topicId, groupId);
+    },
+    async listProjectGrantsByPrincipalStatus(ctx, principalId, status) {
+      return await bridgeListProjectGrantsByPrincipalStatus(
+        ctx,
+        principalId,
+        status
+      );
+    },
+    async listProjectGrantsByGroupStatus(ctx, groupId, status) {
+      return await bridgeListProjectGrantsByGroupStatus(ctx, groupId, status);
+    },
+    async insertProjectGrant(ctx, value) {
+      return await bridgeInsertProjectGrant(ctx, value);
+    },
+    async getAgentByPrincipalId(ctx, principalId) {
+      return await findAgentByPrincipalId(ctx, principalId);
+    },
+    async getUserByClerkId(ctx, clerkId) {
+      return await findUserByClerkId(ctx, clerkId);
+    },
+    async getUserByPrincipalId(ctx, principalId) {
+      return await findUserByPrincipalId(ctx, principalId);
+    }
+  };
+}
+var resolverOverrides = {};
+function resolveAccessControlAppResolvers(_ctx) {
+  return {
+    ...defaultResolvers(),
+    ...resolverOverrides
+  };
+}
+
+// ../access-control/src/principalContext.ts
+function requireCanonicalResolvedUser(user, clerkId) {
+  const resolved = user;
+  if (!resolved) {
+    throw new Error(
+      `[AccessControl] Canonical user identity required for ${clerkId}. Sync users.upsertUser before user-bound access checks.`
+    );
+  }
+  const { mcRole, defaultTenantId, defaultWorkspaceId, defaultPrincipalId } = resolved;
+  if (mcRole !== "platform_admin" && mcRole !== "tenant_admin" && mcRole !== "workspace_admin" && mcRole !== "editor" && mcRole !== "viewer" && mcRole !== "auditor" && mcRole !== "service_agent") {
+    throw new Error(
+      `[AccessControl] Canonical MC role required for ${clerkId}. Re-sync Master Control identity before user-bound access checks.`
+    );
+  }
+  if (typeof defaultTenantId !== "string" || defaultTenantId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical home tenant required for ${clerkId}. Re-sync Master Control identity before user-bound access checks.`
+    );
+  }
+  if (typeof defaultWorkspaceId !== "string" || defaultWorkspaceId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical home workspace required for ${clerkId}. Re-sync Master Control identity before user-bound access checks.`
+    );
+  }
+  if (typeof defaultPrincipalId !== "string" || defaultPrincipalId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical federated principal required for ${clerkId}. Re-sync Master Control identity before user-bound access checks.`
+    );
+  }
+  return {
+    mcRole,
+    defaultTenantId: defaultTenantId.trim(),
+    defaultWorkspaceId: defaultWorkspaceId.trim(),
+    defaultPrincipalId: defaultPrincipalId.trim()
+  };
+}
+function isPrincipalIdInput(value) {
+  return value.startsWith("user:") || value.startsWith("group:") || value.startsWith("service:") || value.startsWith("agent:") || value.startsWith("external_viewer:");
+}
+async function resolveCanonicalUserRecord(ctx, actorId) {
+  const normalizedActorId = actorId.trim();
+  const clerkId = isPrincipalIdInput(normalizedActorId) && normalizedActorId.startsWith("user:") ? normalizedActorId.slice("user:".length) : normalizedActorId;
+  const resolvers = resolveAccessControlAppResolvers();
+  const resolvedByClerkId = await resolvers.getUserByClerkId(ctx, clerkId);
+  if (resolvedByClerkId) {
+    return {
+      resolvedUser: resolvedByClerkId,
+      clerkId,
+      contextClerkId: clerkId
+    };
+  }
+  const resolvedByPrincipalId = await resolvers.getUserByPrincipalId(
+    ctx,
+    normalizedActorId
+  );
+  return {
+    resolvedUser: resolvedByPrincipalId ?? null,
+    clerkId,
+    contextClerkId: normalizedActorId.startsWith("user:") && clerkId.length > 0 ? clerkId : normalizedActorId
+  };
+}
+function uniqRoles(roles) {
+  const roleSet = /* @__PURE__ */ new Set();
+  for (const role of roles) {
+    if (role === "platform_admin" || role === "tenant_admin" || role === "workspace_admin" || role === "editor" || role === "viewer" || role === "auditor" || role === "service_agent") {
+      roleSet.add(role);
+    }
+  }
+  return [...roleSet];
+}
+function normalizeGroupIds(value) {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return [...new Set(
+    value.filter((entry) => typeof entry === "string").map((entry) => entry.trim()).filter(Boolean)
+  )];
+}
+function requireServiceAgentUser(user, actorId) {
+  const canonicalUser = requireCanonicalResolvedUser(user, actorId);
+  if (canonicalUser.mcRole !== "service_agent") {
+    throw new Error(
+      `[AccessControl] Canonical service_agent identity required for ${actorId}. Sync users.upsertUser before agent-bound access checks.`
+    );
+  }
+  return canonicalUser;
+}
+function requireCanonicalResolvedAgent(agent, actorId) {
+  const resolved = agent;
+  if (!resolved) {
+    throw new Error(
+      `[AccessControl] Agent "${actorId}" not found in agents or users table.`
+    );
+  }
+  if (typeof resolved.principalId !== "string" || resolved.principalId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical agent principalId required for ${actorId}.`
+    );
+  }
+  if (typeof resolved.tenantId !== "string" || resolved.tenantId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical home tenant required for ${actorId}.`
+    );
+  }
+  if (typeof resolved.workspaceId !== "string" || resolved.workspaceId.trim().length === 0) {
+    throw new Error(
+      `[AccessControl] Canonical home workspace required for ${actorId}.`
+    );
+  }
+  return {
+    principalId: resolved.principalId.trim(),
+    tenantId: resolved.tenantId.trim(),
+    workspaceId: resolved.workspaceId.trim(),
+    roles: uniqRoles(Array.isArray(resolved.roles) ? resolved.roles : []) ?? ["service_agent"],
+    groupIds: normalizeGroupIds(resolved.groupIds)
+  };
+}
+async function resolvePrincipalContext(ctx, actorId) {
+  if (actorId.startsWith("agent:")) {
+    const resolvers = resolveAccessControlAppResolvers();
+    const resolvedAgent = await resolvers.getAgentByPrincipalId(ctx, actorId);
+    if (resolvedAgent) {
+      const agent = requireCanonicalResolvedAgent(
+        resolvedAgent,
+        actorId
+      );
+      return {
+        principalId: agent.principalId,
+        principalType: "service",
+        clerkId: actorId,
+        tenantId: agent.tenantId,
+        workspaceId: agent.workspaceId,
+        roles: agent.roles.length > 0 ? agent.roles : ["service_agent"],
+        groupIds: agent.groupIds,
+        isPlatformAdmin: false,
+        isTenantAdmin: false,
+        isWorkspaceAdmin: false,
+        isSystemFallback: false
+      };
+    }
+    const resolvedUser2 = await resolvers.getUserByClerkId(
+      ctx,
+      actorId
+    );
+    if (!resolvedUser2) {
+      throw new Error(
+        `[AccessControl] Agent "${actorId}" not found in agents or users table.`
+      );
+    }
+    const user2 = requireServiceAgentUser(
+      resolvedUser2,
+      actorId
+    );
+    console.warn(
+      `[AccessControl] Deprecated legacy service-agent fallback for ${actorId}; migrate this principal into identity.agents.`
+    );
+    return {
+      principalId: user2.defaultPrincipalId,
+      principalType: "service",
+      clerkId: actorId,
+      tenantId: user2.defaultTenantId,
+      workspaceId: user2.defaultWorkspaceId,
+      roles: ["service_agent"],
+      groupIds: normalizeGroupIds(resolvedUser2?.principalGroupIds),
+      isPlatformAdmin: false,
+      isTenantAdmin: false,
+      isWorkspaceAdmin: false,
+      isSystemFallback: false
+    };
+  }
+  const {
+    resolvedUser,
+    contextClerkId
+  } = await resolveCanonicalUserRecord(ctx, actorId);
+  const user = requireCanonicalResolvedUser(
+    resolvedUser,
+    contextClerkId
+  );
+  if (!user.defaultPrincipalId) {
+    throw new Error(
+      `[AccessControl] Canonical federated principal required for ${contextClerkId}. Re-sync Master Control identity before user-bound access checks.`
+    );
+  }
+  if (user.mcRole === "service_agent") {
+    return {
+      principalId: user.defaultPrincipalId,
+      principalType: "service",
+      clerkId: contextClerkId,
+      tenantId: user.defaultTenantId,
+      workspaceId: user.defaultWorkspaceId,
+      roles: ["service_agent"],
+      groupIds: normalizeGroupIds(resolvedUser?.principalGroupIds),
+      isPlatformAdmin: false,
+      isTenantAdmin: false,
+      isWorkspaceAdmin: false,
+      isSystemFallback: false
+    };
+  }
+  const principalId = user.defaultPrincipalId;
+  const effectiveRole = user.mcRole;
+  const roles = effectiveRole === "platform_admin" ? ["platform_admin", "tenant_admin"] : effectiveRole === "tenant_admin" ? ["tenant_admin"] : [effectiveRole];
+  const tenantId = user.defaultTenantId;
+  const workspaceId = user.defaultWorkspaceId;
+  const isPlatformAdmin = effectiveRole === "platform_admin";
+  return {
+    principalId,
+    principalType: "user",
+    clerkId: contextClerkId,
+    tenantId,
+    workspaceId,
+    roles: uniqRoles(roles),
+    groupIds: normalizeGroupIds(resolvedUser?.principalGroupIds),
+    isPlatformAdmin,
+    isTenantAdmin: isPlatformAdmin || effectiveRole === "tenant_admin",
+    isWorkspaceAdmin: isPlatformAdmin || effectiveRole === "tenant_admin" || effectiveRole === "workspace_admin",
+    isSystemFallback: false
+  };
+}
+
+// ../access-control/src/access.ts
+function isTopicInPrincipalTenant(topic, principalTenantId) {
+  if (!topic.tenantId) {
+    return false;
+  }
+  if (!principalTenantId) {
+    return false;
+  }
+  return String(topic.tenantId) === String(principalTenantId);
+}
+function isTopicInPrincipalWorkspace(topic, principalWorkspaceId) {
+  if (!topic.workspaceId) {
+    return false;
+  }
+  if (!principalWorkspaceId) {
+    return false;
+  }
+  return String(topic.workspaceId) === String(principalWorkspaceId);
+}
+function isLegacyUnscopedTopic(topic) {
+  return !topic.tenantId || !topic.workspaceId;
+}
+function isGrantScopeAlignedToTopic(topic, grant) {
+  if (topic.tenantId && grant.tenantId && String(topic.tenantId) !== String(grant.tenantId)) {
+    return false;
+  }
+  if (topic.workspaceId && grant.workspaceId && String(topic.workspaceId) !== String(grant.workspaceId)) {
+    return false;
+  }
+  return true;
+}
+function isGrantSourceAllowedForVisibility(visibility, source) {
+  if (source !== "external_share") {
+    return true;
+  }
+  return visibility === "external" || visibility === "public";
+}
+function isGrantActive(grant) {
+  if (grant.status !== "active") {
+    return false;
+  }
+  if (grant.expiresAt !== void 0 && grant.expiresAt <= Date.now()) {
+    return false;
+  }
+  return true;
+}
+async function hasPrincipalGrant(ctx, args) {
+  const grants = await resolveAccessControlAppResolvers().listProjectGrantsByProjectAndPrincipal(
+    ctx,
+    args.topic._id,
+    args.principalId
+  );
+  if (grants.some(
+    (grant) => isGrantActive(grant) && isGrantScopeAlignedToTopic(args.topic, grant) && isGrantSourceAllowedForVisibility(
+      args.topic.visibility,
+      grant.source
+    ) && (!args.principalIsExternal || args.topic.visibility === "public" || grant.source === "external_share")
+  )) {
+    return true;
+  }
+  return false;
+}
+async function hasGroupGrant(ctx, args) {
+  if (args.groupIds.length === 0) {
+    return false;
+  }
+  for (const groupId of args.groupIds) {
+    const grants = await resolveAccessControlAppResolvers().listProjectGrantsByProjectAndGroup(ctx, args.topic._id, groupId);
+    if (grants.some(
+      (grant) => isGrantActive(grant) && isGrantScopeAlignedToTopic(args.topic, grant) && isGrantSourceAllowedForVisibility(
+        args.topic.visibility,
+        grant.source
+      )
+    )) {
+      return true;
+    }
+  }
+  return false;
+}
+function isExternalPrincipal(_ctx, _args) {
+  return false;
+}
+async function evaluateTopicAccessDetailed(ctx, args) {
+  if (args.legacyUserId) {
+    return {
+      hasAccess: true,
+      isAdmin: false,
+      isOwner: false,
+      isShared: false,
+      hasGrant: true,
+      isFirmVisible: true,
+      isExternalVisible: false,
+      isPublicVisible: false,
+      isTenantScopeMatch: true,
+      isWorkspaceScopeMatch: true,
+      isPrincipalExternal: false
+    };
+  }
+  const topic = await resolveAccessControlAppResolvers().getProject(
+    ctx,
+    args.topicId
+  );
+  if (!topic) {
+    return {
+      hasAccess: false,
+      isAdmin: false,
+      isOwner: false,
+      isShared: false,
+      hasGrant: false,
+      isFirmVisible: false,
+      isExternalVisible: false,
+      isPublicVisible: false,
+      isTenantScopeMatch: false,
+      isWorkspaceScopeMatch: false,
+      isPrincipalExternal: false
+    };
+  }
+  const { principalContext, legacyUserId } = args;
+  const userIsAdmin = principalContext.isPlatformAdmin;
+  const isOwner = topic.ownerId === legacyUserId;
+  const isShared = (topic.sharedWith ?? []).includes(legacyUserId);
+  const principalIsExternal = await isExternalPrincipal(ctx, {
+    groupIds: principalContext.groupIds,
+    topicTenantId: topic.tenantId,
+    topicWorkspaceId: topic.workspaceId
+  });
+  const hasPrincipalGrantResult = await hasPrincipalGrant(ctx, {
+    topic,
+    principalId: principalContext.principalId,
+    principalIsExternal
+  });
+  const hasGroupGrantResult = await hasGroupGrant(ctx, {
+    topic,
+    groupIds: principalContext.groupIds
+  });
+  const hasGrant = isShared || hasPrincipalGrantResult || hasGroupGrantResult;
+  const legacyUnscoped = isLegacyUnscopedTopic(topic);
+  const tenantScopeMatch = isTopicInPrincipalTenant(
+    topic,
+    principalContext.tenantId
+  );
+  const workspaceScopeMatch = isTopicInPrincipalWorkspace(
+    topic,
+    principalContext.workspaceId
+  );
+  const isPublicVisible = topic.visibility === "public";
+  const isFirmVisible = topic.visibility === "firm" && !legacyUnscoped && tenantScopeMatch && workspaceScopeMatch && !principalIsExternal;
+  const hasScopedGrant = hasGrant && (legacyUnscoped || tenantScopeMatch && workspaceScopeMatch);
+  const isExternalVisible = topic.visibility === "external" && hasScopedGrant;
+  const hasAccess = userIsAdmin || isOwner || hasScopedGrant || isPublicVisible || isFirmVisible;
+  return {
+    hasAccess,
+    isAdmin: userIsAdmin,
+    isOwner,
+    isShared,
+    hasGrant,
+    isFirmVisible,
+    isExternalVisible,
+    isPublicVisible,
+    isTenantScopeMatch: tenantScopeMatch,
+    isWorkspaceScopeMatch: workspaceScopeMatch,
+    isPrincipalExternal: principalIsExternal
+  };
+}
+async function checkTopicAccessDetailed(ctx, topicId, userId) {
+  const principalContext = await resolvePrincipalContext(ctx, userId);
+  return evaluateTopicAccessDetailed(ctx, {
+    topicId,
+    legacyUserId: userId,
+    principalContext
+  });
+}
+async function checkTopicAccess(ctx, topicId, userId) {
+  const result = await checkTopicAccessDetailed(ctx, topicId, userId);
+  return result.hasAccess;
+}
+var checkProjectAccess = checkTopicAccess;
+var permissiveReturn = v.optional(v.any());
+var looseJsonObject = v.record(v.string(), v.any());
+var looseJsonArray = v.array(v.any());
+v.union(
+  v.string(),
+  v.number(),
+  v.boolean(),
+  v.null(),
+  looseJsonObject,
+  looseJsonArray
+);
+
+// src/epistemicLinking.ts
+var RELATION_TO_EDGE_TYPE = {
+  // Cross-type: Evidence → Belief
+  supports: "informs",
+  // with weight > 0
+  contradicts: "informs",
+  // with weight < 0
+  // Cross-type: Question → Belief
+  tests: "tests",
+  // Cross-type: Evidence → Question
+  answers: "derived_from",
+  partial: "derived_from",
+  // with lower weight
+  context: "derived_from",
+  // with even lower weight
+  // Same-type: Belief ↔ Belief
+  depends_on: "depends_on",
+  reinforces: "supports",
+  parent: "contains",
+  child: "contains",
+  // Same-type: Question ↔ Question
+  prerequisite: "prerequisite_for",
+  parallel: "parallel_to",
+  // Same-type: Evidence ↔ Evidence
+  corroborates: "corroborates",
+  extends: "extends",
+  same_source: "same_source_as",
+  same_theme: "same_theme_as",
+  // Generic
+  adjacent: "related_to",
+  related: "related_to",
+  informs: "informs"
+};
+function getEdgeWeight(relation) {
+  switch (relation) {
+    case "supports":
+    case "corroborates":
+      return 0.7;
+    case "contradicts":
+      return -0.7;
+    case "qualifies":
+    case "partial":
+      return 0.4;
+    case "context":
+    case "adjacent":
+      return 0.2;
+    case "depends_on":
+    case "parent":
+    case "prerequisite":
+      return 0.8;
+    case "child":
+      return 0.6;
+    case "parallel":
+    case "extends":
+    case "same_theme":
+    case "same_source":
+      return 0.5;
+    default:
+      return 0.5;
+  }
+}
+function buildDeterministicEdgeGlobalId(fromGlobalId, toGlobalId, edgeType) {
+  return `edge_link_${edgeType}_${fromGlobalId}_${toGlobalId}`;
+}
+var linkBeliefToBelief = mutation({
+  args: {
+    fromBeliefId: v.id("epistemicNodes"),
+    toBeliefId: v.id("epistemicNodes"),
+    relation: v.string(),
+    // "depends_on" | "supports" | "contains" | "contradicts" | "adjacent"
+    userId: v.string(),
+    rationale: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const fromBelief = await ctx.db.get(args.fromBeliefId);
+    const toBelief = await ctx.db.get(args.toBeliefId);
+    if (!fromBelief || !toBelief || fromBelief.nodeType !== "belief" || toBelief.nodeType !== "belief") {
+      throw new Error("One or both beliefs not found");
+    }
+    if (fromBelief.projectId) {
+      const hasAccess = await checkProjectAccess(
+        ctx,
+        fromBelief.projectId,
+        args.userId
+      );
+      if (!hasAccess) {
+        throw new Error("No permission to link these beliefs");
+      }
+    }
+    const fromNode = fromBelief;
+    const toNode = toBelief;
+    if (fromNode && toNode) {
+      const edgeType = RELATION_TO_EDGE_TYPE[args.relation] || "related_to";
+      const weight = getEdgeWeight(args.relation);
+      const fromLayer = fromNode.epistemicLayer || getNodeLayer(fromNode.nodeType);
+      const toLayer = toNode.epistemicLayer || getNodeLayer(toNode.nodeType);
+      const validation = validateEdgeLayers(edgeType, fromLayer, toLayer);
+      if (!validation.valid) {
+        console.warn(
+          `[EpistemicLinking] Invalid edge blocked: ${validation.reason}`
+        );
+      } else if (isDeprecatedEdgeType(edgeType)) {
+        console.error(
+          `[EpistemicLinking] FORBIDDEN edge type '${edgeType}' blocked. Use compliant edge types.`
+        );
+      } else {
+        const edgeGlobalId = buildDeterministicEdgeGlobalId(
+          fromNode.globalId,
+          toNode.globalId,
+          edgeType
+        );
+        await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+          globalId: edgeGlobalId,
+          fromGlobalId: fromNode.globalId,
+          toGlobalId: toNode.globalId,
+          edgeType,
+          weight,
+          context: args.rationale || `Linked as ${args.relation}`,
+          topicId: fromBelief.projectId ? String(fromBelief.projectId) : void 0,
+          createdBy: args.userId,
+          fromNodeType: "belief",
+          toNodeType: "belief",
+          fromLayer,
+          toLayer
+        });
+      }
+    }
+    return { success: true };
+  }
+});
+var linkQuestionToQuestion = mutation({
+  args: {
+    fromQuestionId: v.id("epistemicNodes"),
+    toQuestionId: v.id("epistemicNodes"),
+    relation: v.string(),
+    // "parent" | "child" | "prerequisite" | "parallel" | "contradicts" | "adjacent"
+    userId: v.string(),
+    rationale: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (_ctx, _args) => {
+    console.log(
+      "[EpistemicLinking] Question-to-question linking is deprecated and disabled."
+    );
+    return { success: true, deprecated: true };
+  }
+});
+var linkEvidenceToEvidence = mutation({
+  args: {
+    fromInsightId: v.id("epistemicNodes"),
+    toInsightId: v.id("epistemicNodes"),
+    relation: v.string(),
+    // "corroborates" | "contradicts" | "extends" | "same_source" | "same_theme" | "adjacent"
+    userId: v.string(),
+    rationale: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const fromInsight = await ctx.db.get(args.fromInsightId);
+    const toInsight = await ctx.db.get(args.toInsightId);
+    if (!fromInsight || !toInsight) {
+      throw new Error("One or both insights not found");
+    }
+    if (fromInsight.projectId) {
+      const hasAccess = await checkProjectAccess(
+        ctx,
+        fromInsight.projectId,
+        args.userId
+      );
+      if (!hasAccess) {
+        throw new Error("No permission to link these evidence items");
+      }
+    }
+    const fromNode = fromInsight.nodeType === "evidence" ? fromInsight : null;
+    const toNode = toInsight.nodeType === "evidence" ? toInsight : null;
+    if (fromNode && toNode) {
+      const edgeType = RELATION_TO_EDGE_TYPE[args.relation] || "related_to";
+      const weight = getEdgeWeight(args.relation);
+      const fromLayer = fromNode.epistemicLayer || getNodeLayer(fromNode.nodeType);
+      const toLayer = toNode.epistemicLayer || getNodeLayer(toNode.nodeType);
+      const validation = validateEdgeLayers(edgeType, fromLayer, toLayer);
+      if (!validation.valid) {
+        console.warn(
+          `[EpistemicLinking] Invalid edge blocked: ${validation.reason}`
+        );
+      } else if (isDeprecatedEdgeType(edgeType)) {
+        console.error(
+          `[EpistemicLinking] FORBIDDEN edge type '${edgeType}' blocked. Use compliant edge types.`
+        );
+      } else {
+        const edgeGlobalId = buildDeterministicEdgeGlobalId(
+          fromNode.globalId,
+          toNode.globalId,
+          edgeType
+        );
+        await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+          globalId: edgeGlobalId,
+          fromGlobalId: fromNode.globalId,
+          toGlobalId: toNode.globalId,
+          edgeType,
+          weight,
+          context: args.rationale || `Linked as ${args.relation}`,
+          topicId: fromInsight.projectId ? String(fromInsight.projectId) : void 0,
+          createdBy: args.userId,
+          fromNodeType: "evidence",
+          toNodeType: "evidence",
+          fromLayer,
+          toLayer
+        });
+      }
+    }
+    return { success: true };
+  }
+});
+
+export { linkBeliefToBelief, linkEvidenceToEvidence, linkQuestionToQuestion };
+//# sourceMappingURL=epistemicLinking.js.map
+//# sourceMappingURL=epistemicLinking.js.map