@lucern/graph-primitives 1.0.0 → 1.0.1

package/dist/epistemicEdges.mutations.js

@@ -0,0 +1,1365 @@
+import { v } from 'convex/values';
+import { requireProjectAccess } from '@lucern/access-control/access';
+import { permissiveReturn } from '@lucern/contracts/schema-helpers/validators';
+import { componentsGeneric, anyApi, mutationGeneric } from 'convex/server';
+
+// src/epistemicEdges.mutations.ts
+v.union(
+  v.literal("L4"),
+  v.literal("L3"),
+  v.literal("L2"),
+  v.literal("L1"),
+  v.literal("ontological"),
+  v.literal("organizational")
+);
+var subjectiveOpinionValidator = v.object({
+  b: v.number(),
+  d: v.number(),
+  u: v.number(),
+  a: v.number()
+});
+var edgeTypeValidator = v.union(
+  // --- L4 Decision Edges (Phase 2A) ---
+  v.literal("based_on_belief"),
+  v.literal("based_on_question"),
+  v.literal("blocked_by_contradiction"),
+  v.literal("informed_by_theme"),
+  // --- Evidence Flow (L2 → L3, L2 → L1) ---
+  v.literal("derived_from"),
+  v.literal("responds_to"),
+  v.literal("informs"),
+  v.literal("tests"),
+  v.literal("explores"),
+  v.literal("qualifies"),
+  // --- Synthesis (L2 → L2, L2 → L1) ---
+  // "based_on" removed — use "derived_from" instead
+  // --- Theme Relationships (L3 → L3) ---
+  v.literal("relates_to_thesis"),
+  v.literal("belongs_to"),
+  v.literal("plays_theme"),
+  v.literal("scoped_by"),
+  // --- Deal/Company ---
+  v.literal("evaluates"),
+  // --- People (ontological → ontological, ontological → L3) ---
+  v.literal("perspective_on"),
+  v.literal("works_at"),
+  v.literal("mentioned_in"),
+  v.literal("founded_by"),
+  // --- Value Chain (ontological → ontological) ---
+  v.literal("participates_in"),
+  v.literal("performs"),
+  v.literal("function_in"),
+  v.literal("impacts"),
+  // --- Investment (ontological → ontological) ---
+  v.literal("invested_in"),
+  v.literal("raised_from"),
+  // --- Lifecycle (same layer only) ---
+  v.literal("supersedes"),
+  v.literal("same_as"),
+  // --- Same-Type Relationships: Belief ↔ Belief (L3 → L3) ---
+  v.literal("depends_on"),
+  v.literal("supports"),
+  v.literal("contains"),
+  // --- Belief Cluster Mapping (L3 → L3) ---
+  v.literal("counterfactual_of"),
+  v.literal("cascade_to"),
+  v.literal("cascade_from"),
+  v.literal("mutually_exclusive"),
+  v.literal("correlates_with"),
+  v.literal("amplifies"),
+  v.literal("precondition_for"),
+  v.literal("in_tension_with"),
+  // --- Belief ↔ Belief: Epistemic Impact (Confidence Propagation) ---
+  v.literal("falsified_by"),
+  v.literal("exclusive_with"),
+  v.literal("contradicts"),
+  v.literal("collapses_if"),
+  v.literal("strengthened_by"),
+  v.literal("weakened_by"),
+  v.literal("alternative_to"),
+  v.literal("subsumes"),
+  v.literal("validated_by"),
+  v.literal("required_for"),
+  v.literal("blocks"),
+  // --- Same-Type Relationships: Question ↔ Question (L3 → L3) ---
+  v.literal("prerequisite_for"),
+  v.literal("parallel_to"),
+  // --- Same-Type Relationships: Evidence ↔ Evidence (L2 → L2) ---
+  v.literal("corroborates"),
+  v.literal("extends"),
+  v.literal("same_source_as"),
+  v.literal("same_theme_as"),
+  // --- NEW: Deep Epistemic Analysis Edges (Phase: Schema Upgrade) ---
+  v.literal("assumes"),
+  v.literal("would_predict"),
+  v.literal("analogous_to"),
+  v.literal("independent_of"),
+  // --- Entity↔Belief Bridge (OE-B) ---
+  v.literal("competes_with")
+);
+function buildEdgeStatusSuccessResult() {
+  return { success: true };
+}
+function buildEdgeNotFoundResult() {
+  const result = {};
+  result.success = false;
+  result.error = "Edge not found";
+  return result;
+}
+
+// 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"
+};
+function getNodeLayer(nodeType) {
+  const L4_TYPES = ["decision"];
+  const L3_TYPES = ["belief", "question", "theme", "deal"];
+  const L2_TYPES = ["claim", "evidence", "synthesis", "answer"];
+  const L1_TYPES = ["atomic_fact", "excerpt", "source"];
+  const ONTOLOGICAL_TYPES = [
+    "company",
+    "person",
+    "investor",
+    "function",
+    "value_chain"
+  ];
+  const ORGANIZATIONAL_TYPES = ["topic"];
+  if (L4_TYPES.includes(nodeType)) {
+    return "L4";
+  }
+  if (L3_TYPES.includes(nodeType)) {
+    return "L3";
+  }
+  if (L2_TYPES.includes(nodeType)) {
+    return "L2";
+  }
+  if (L1_TYPES.includes(nodeType)) {
+    return "L1";
+  }
+  if (ONTOLOGICAL_TYPES.includes(nodeType)) {
+    return "ontological";
+  }
+  if (ORGANIZATIONAL_TYPES.includes(nodeType)) {
+    return "organizational";
+  }
+  console.warn(`[GraphTypes] Unknown nodeType "${nodeType}", defaulting to L2`);
+  return "L2";
+}
+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;
+}
+var api = anyApi;
+componentsGeneric();
+var internal = anyApi;
+var mutation = mutationGeneric;
+
+// src/debug.ts
+function isGraphPrimitiveDebugEnabled() {
+  const env = globalThis.process?.env;
+  return env?.LUCERN_COMPAT_FALLBACK_DEBUG === "1" || env?.LUCERN_GRAPH_DEBUG === "1";
+}
+function debugGraphPrimitiveFallback(message, context) {
+  if (!isGraphPrimitiveDebugEnabled()) {
+    return;
+  }
+  console.debug(message, context ?? {});
+}
+
+// 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;
+}
+function isMissingLucernChildComponentError(error) {
+  const message = getErrorMessage(error);
+  return message.includes(
+    'Child component ComponentName(Identifier("lucern")) not found'
+  ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+}
+function getErrorMessage(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  return "unknown error";
+}
+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 (error) {
+      debugGraphPrimitiveFallback(
+        "[topicProjectOverlay] Failed to resolve topic by direct ID",
+        {
+          error,
+          scopeId
+        }
+      );
+    }
+  }
+  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 (error) {
+    debugGraphPrimitiveFallback(
+      "[topicProjectOverlay] Failed to resolve topic by ID query",
+      {
+        error,
+        scopeId
+      }
+    );
+  }
+  try {
+    const topic = await ctx.runQuery(api.topics.getByLegacyScopeId, {
+      projectId: String(scopeId)
+    });
+    if (topic?.name !== void 0 && topic?.type !== void 0) {
+      return topic;
+    }
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicProjectOverlay] Failed to resolve topic by legacy scope ID",
+      { error, scopeId }
+    );
+  }
+  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 (error) {
+      debugGraphPrimitiveFallback(
+        "[topicProjectOverlay] Failed to read topics table; falling back to API",
+        { error }
+      );
+      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));
+}
+async function patchTopicProjectOverlay(ctx, scopeId, value) {
+  const topic = await resolveTopicDoc(ctx, scopeId);
+  if (!topic) {
+    return null;
+  }
+  const nextMetadata = { ...readMetadata(topic) };
+  const patch = {};
+  const topicUpdateArgs = {
+    id: String(topic._id)
+  };
+  for (const [key, rawValue] of Object.entries(value)) {
+    switch (key) {
+      case "_id":
+      case "projectId":
+      case "topicId":
+      case "legacyProjectId":
+      case "storageProjectId":
+        break;
+      case "name":
+      case "description":
+        patch[key] = rawValue;
+        topicUpdateArgs[key] = rawValue;
+        break;
+      case "tenantId":
+      case "workspaceId":
+      case "ownerId":
+        throw new Error(
+          `patchTopicProjectOverlay cannot mutate ${key} via component-owned topics`
+        );
+      case "status": {
+        const status = coerceStatus(rawValue);
+        if (status) {
+          patch.status = status;
+          topicUpdateArgs.status = status;
+        }
+        break;
+      }
+      case "visibility": {
+        const visibility = coerceVisibility(rawValue);
+        if (visibility) {
+          patch.visibility = visibility;
+          topicUpdateArgs.visibility = visibility;
+        }
+        break;
+      }
+      case "type": {
+        const projectType = readNonEmptyString(rawValue);
+        if (projectType) {
+          nextMetadata.projectType = projectType;
+        } else {
+          delete nextMetadata.projectType;
+        }
+        break;
+      }
+      case "updatedAt":
+      case "createdAt":
+        break;
+      default:
+        if (rawValue === void 0) {
+          delete nextMetadata[key];
+        } else {
+          nextMetadata[key] = rawValue;
+        }
+    }
+  }
+  patch.updatedAt = Date.now();
+  patch.metadata = nextMetadata;
+  topicUpdateArgs.metadata = nextMetadata;
+  if (typeof ctx.runMutation === "function") {
+    try {
+      await ctx.runMutation(api.topics.update, topicUpdateArgs);
+    } catch (error) {
+      if (!isMissingLucernChildComponentError(error) || !ctx?.db || typeof ctx.db.patch !== "function") {
+        throw error;
+      }
+      await ctx.db.patch(String(topic._id), patch);
+    }
+  } else if (ctx?.db && typeof ctx.db.patch === "function") {
+    await ctx.db.patch(String(topic._id), patch);
+  } else {
+    throw new Error(
+      "Cannot patch topic without component adapter (ctx.runMutation unavailable)"
+    );
+  }
+  return materializeTopicProjectOverlay({
+    ...topic,
+    ...patch,
+    metadata: nextMetadata
+  });
+}
+
+// src/resolvers.ts
+function isMissingLucernChildComponentError2(error) {
+  const message = getErrorMessage2(error);
+  return message.includes(
+    'Child component ComponentName(Identifier("lucern")) not found'
+  ) || message.includes("Child component") && message.includes("lucern") && message.includes("not found");
+}
+function getErrorMessage2(error) {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  if (typeof error === "object" && error !== null && "message" in error && typeof error.message === "string") {
+    return error.message;
+  }
+  return "unknown error";
+}
+function isAdvisoryTopicPatch(value) {
+  const advisoryKeys = /* @__PURE__ */ new Set(["lastActivityAt", "updatedAt"]);
+  const keys = Object.keys(value);
+  return keys.length > 0 && keys.every((key) => advisoryKeys.has(key));
+}
+async function patchProjectWithTolerance(ctx, projectId, value) {
+  try {
+    await patchTopicProjectOverlay(ctx, projectId, value);
+  } catch (error) {
+    if (!isAdvisoryTopicPatch(value) || !isMissingLucernChildComponentError2(error)) {
+      throw error;
+    }
+    console.warn(
+      "[lucern graph-primitives] Non-fatal advisory topic patch failure",
+      {
+        projectId,
+        keys: Object.keys(value),
+        error: getErrorMessage2(error)
+      }
+    );
+  }
+}
+function defaultResolvers() {
+  return {
+    getProject: (ctx, projectId) => resolveTopicProjectOverlay(ctx, projectId, {
+      idMode: "legacy",
+      projectLikeOnly: false
+    }),
+    patchProject: (ctx, projectId, value) => patchProjectWithTolerance(ctx, projectId, value),
+    listTopics: (ctx) => listTopicProjectOverlays(ctx, {
+      idMode: "legacy"
+    }),
+    getFinalArtifact: (ctx, artifactId) => ctx.db.get(artifactId)
+  };
+}
+var resolverOverrides = {};
+function resolveGraphPrimitivesAppResolvers(_ctx) {
+  return {
+    ...defaultResolvers(),
+    ...resolverOverrides
+  };
+}
+var LEGACY_SCOPE_FIELD2 = "graphScopeProjectId";
+function asMappedProjectId(topic) {
+  if (!topic) {
+    return;
+  }
+  const directLegacyProjectId = normalizeScopeValue(topic[LEGACY_SCOPE_FIELD2]);
+  if (directLegacyProjectId) {
+    return directLegacyProjectId;
+  }
+  const metadata = topic.metadata || {};
+  const candidate = metadata[LEGACY_SCOPE_FIELD2] || metadata.legacyProjectId || metadata.projectId || metadata.scopeProjectId;
+  return candidate ? candidate : void 0;
+}
+function normalizeScopeValue(value) {
+  if (typeof value !== "string") {
+    return;
+  }
+  const normalized = value.trim();
+  return normalized.length > 0 ? normalized : void 0;
+}
+function pickPrimaryTopic(candidates) {
+  return [...candidates].sort((a, b) => {
+    const depthA = a.depth ?? 9999;
+    const depthB = b.depth ?? 9999;
+    if (depthA !== depthB) {
+      return depthA - depthB;
+    }
+    const createdA = a.createdAt ?? Number.MAX_SAFE_INTEGER;
+    const createdB = b.createdAt ?? Number.MAX_SAFE_INTEGER;
+    if (createdA !== createdB) {
+      return createdA - createdB;
+    }
+    return String(a.name || "").localeCompare(String(b.name || ""));
+  })[0];
+}
+async function findTopicsByScopeAlias(ctx, scopeId) {
+  try {
+    return await ctx.db.query("topics").withIndex(
+      "by_graph_scope_project",
+      (q) => q.eq(LEGACY_SCOPE_FIELD2, scopeId)
+    ).collect();
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] Failed to resolve scope alias via index",
+      {
+        error,
+        scopeId
+      }
+    );
+    const topics = await ctx.db.query("topics").collect();
+    return topics.filter((topic) => {
+      const normalizedGlobalId = normalizeScopeValue(topic.globalId);
+      const mappedProjectId = asMappedProjectId(topic);
+      return String(topic._id) === scopeId || normalizedGlobalId === scopeId || mappedProjectId === scopeId;
+    });
+  }
+}
+async function tryResolveHostTopicById(ctx, topicId) {
+  if (typeof ctx.runQuery !== "function") {
+    return null;
+  }
+  try {
+    return await ctx.runQuery(api.topics.get, {
+      id: topicId
+    }) ?? null;
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] Failed to resolve topic by host query",
+      {
+        error,
+        topicId
+      }
+    );
+    return null;
+  }
+}
+async function tryResolveHostTopicByLegacyScope(ctx, legacyScopeId) {
+  if (typeof ctx.runQuery !== "function") {
+    return null;
+  }
+  try {
+    return await ctx.runQuery(api.topics.getByLegacyScopeId, {
+      projectId: legacyScopeId
+    }) ?? null;
+  } catch (error) {
+    debugGraphPrimitiveFallback(
+      "[topicScope] Failed to resolve topic by legacy scope",
+      {
+        error,
+        legacyScopeId
+      }
+    );
+    return null;
+  }
+}
+async function resolveInheritedWorkspaceScope(ctx, topic) {
+  const MAX_DEPTH = 10;
+  let tenantId = normalizeScopeValue(topic.tenantId);
+  let workspaceId = normalizeScopeValue(topic.workspaceId);
+  if (tenantId && workspaceId) {
+    return { tenantId, workspaceId };
+  }
+  let current = topic;
+  for (let i = 0; i < MAX_DEPTH && current?.parentTopicId; i++) {
+    current = await ctx.db.get(current.parentTopicId);
+    if (!current) break;
+    if (!tenantId) {
+      tenantId = normalizeScopeValue(current.tenantId);
+    }
+    if (!workspaceId) {
+      workspaceId = normalizeScopeValue(current.workspaceId);
+    }
+    if (tenantId && workspaceId) break;
+  }
+  return { tenantId, workspaceId };
+}
+async function resolveTopicProjectScope(ctx, args) {
+  if (args.topicId) {
+    let topic = null;
+    try {
+      topic = await ctx.db.get(
+        args.topicId
+      );
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[topicScope] Failed to load topic by direct id",
+        {
+          error,
+          topicId: args.topicId
+        }
+      );
+    }
+    if (!topic) {
+      topic = await tryResolveHostTopicById(ctx, String(args.topicId));
+    }
+    if (!topic) {
+      topic = pickPrimaryTopic(
+        await findTopicsByScopeAlias(ctx, String(args.topicId))
+      ) ?? null;
+    }
+    if (!topic) {
+      throw new Error(`Topic not found: ${String(args.topicId)}`);
+    }
+    const inherited = await resolveInheritedWorkspaceScope(ctx, topic);
+    const mapped = asMappedProjectId(topic);
+    if (mapped) {
+      return {
+        topicId: topic._id,
+        projectId: mapped,
+        tenantId: inherited.tenantId,
+        workspaceId: inherited.workspaceId,
+        source: "topic"
+      };
+    }
+    return {
+      topicId: topic._id,
+      tenantId: inherited.tenantId,
+      workspaceId: inherited.workspaceId,
+      source: "topic"
+    };
+  }
+  if (args.projectId) {
+    let directTopic = null;
+    try {
+      directTopic = await ctx.db.get(
+        args.projectId
+      );
+    } catch (error) {
+      debugGraphPrimitiveFallback(
+        "[topicScope] Failed to load direct project topic",
+        {
+          error,
+          projectId: args.projectId
+        }
+      );
+    }
+    if (directTopic) {
+      const inherited = await resolveInheritedWorkspaceScope(ctx, directTopic);
+      const mapped = asMappedProjectId(directTopic);
+      return {
+        topicId: directTopic._id,
+        projectId: mapped ?? args.projectId,
+        tenantId: inherited.tenantId,
+        workspaceId: inherited.workspaceId,
+        source: "topic_inferred"
+      };
+    }
+    directTopic = await tryResolveHostTopicByLegacyScope(ctx, args.projectId);
+    if (directTopic) {
+      const inherited = await resolveInheritedWorkspaceScope(ctx, directTopic);
+      const mapped = asMappedProjectId(directTopic);
+      return {
+        topicId: directTopic._id,
+        projectId: mapped ?? args.projectId,
+        tenantId: inherited.tenantId,
+        workspaceId: inherited.workspaceId,
+        source: "topic_inferred"
+      };
+    }
+    const topics = await findTopicsByScopeAlias(ctx, args.projectId);
+    const primary = pickPrimaryTopic(topics);
+    if (primary) {
+      const inherited = await resolveInheritedWorkspaceScope(ctx, primary);
+      return {
+        topicId: primary._id,
+        projectId: args.projectId,
+        tenantId: inherited.tenantId,
+        workspaceId: inherited.workspaceId,
+        source: "project_mapped_topic"
+      };
+    }
+    throw new Error(
+      `Legacy project scope ${String(args.projectId)} has no mapped topic.`
+    );
+  }
+  throw new Error(
+    "Missing scope: provide topicId (preferred) or legacy projectId alias."
+  );
+}
+var optionalScopeArgs = {
+  projectId: v.optional(v.string()),
+  topicId: v.optional(v.string())
+};
+
+// src/edgeValidation.ts
+function getLayerDepth(layer) {
+  switch (layer) {
+    case "L4":
+      return 4;
+    case "L3":
+      return 3;
+    case "L2":
+      return 2;
+    case "L1":
+      return 1;
+    case "ontological":
+      return 0;
+    default:
+      return -1;
+  }
+}
+function isValidLayerConnection(fromLayer, toLayer) {
+  if (fromLayer === toLayer) {
+    return true;
+  }
+  if (fromLayer === "ontological" && toLayer === "ontological") {
+    return true;
+  }
+  if (fromLayer === "ontological" && (toLayer === "L3" || toLayer === "L2" || toLayer === "L1")) {
+    return true;
+  }
+  if ((fromLayer === "L3" || fromLayer === "L2" || fromLayer === "L1") && toLayer === "ontological") {
+    return true;
+  }
+  if (fromLayer === "L2" && toLayer === "L1") {
+    return true;
+  }
+  if (fromLayer === "L2" && toLayer === "L3") {
+    return true;
+  }
+  if (fromLayer === "L3" && toLayer === "L2") {
+    return true;
+  }
+  if (fromLayer === "L3" && toLayer === "L4") {
+    return true;
+  }
+  if (fromLayer === "L4" && toLayer === "L3") {
+    return true;
+  }
+  if (fromLayer === "L3" && toLayer === "organizational") {
+    return true;
+  }
+  if (fromLayer === "organizational" && toLayer === "L3") {
+    return true;
+  }
+  const fromDepth = getLayerDepth(fromLayer);
+  const toDepth = getLayerDepth(toLayer);
+  if (Math.abs(fromDepth - toDepth) > 1) {
+    return false;
+  }
+  return true;
+}
+var EDGE_LAYER_RULES = {
+  // === 6 Canonical Epistemic Types ===
+  supports: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief bears on Belief (weight: +1 supports, -1 contradicts)"
+  },
+  informs: {
+    from: ["L2"],
+    to: ["L3"],
+    description: "Evidence -> Belief (L2 -> L3)"
+  },
+  depends_on: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief B requires Belief A (structural gate)"
+  },
+  derived_from: {
+    from: ["L2", "L3", "L4"],
+    to: ["L1", "L2", "L3"],
+    description: "A was produced from B (provenance chain)"
+  },
+  contains: {
+    from: ["L3", "L4", "ontological"],
+    to: ["L2", "L3", "ontological"],
+    description: "A scopes/aggregates B (hierarchy)"
+  },
+  tests: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Question -> Belief (L3 -> L3)"
+  },
+  // === Structural / Lifecycle ===
+  supersedes: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "NewNode -> OldNode (fork lineage)"
+  },
+  responds_to: {
+    from: ["L2", "L3"],
+    to: ["L3"],
+    description: "Answer -> Question (L2/L3 -> L3)"
+  },
+  belongs_to: {
+    from: ["L2", "L3", "ontological"],
+    to: ["L3"],
+    description: "Membership (migrating to contains)"
+  },
+  relates_to_thesis: {
+    from: ["L3"],
+    to: ["L3"],
+    description: "Belief -> Theme (L3 -> L3)"
+  },
+  // === Ontological (entity-entity or entity-epistemic bridge) ===
+  works_at: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Person -> Company"
+  },
+  invested_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Investor -> Company"
+  },
+  competes_with: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company -> Company"
+  },
+  participates_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company -> ValueChain"
+  },
+  founded_by: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company -> Person"
+  },
+  evaluates: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Deal -> Company"
+  },
+  performs: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company -> Function"
+  },
+  function_in: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Function -> ValueChain"
+  },
+  impacts: {
+    from: ["ontological", "L3"],
+    to: ["ontological"],
+    description: "Theme/Entity -> ValueChain"
+  },
+  raised_from: {
+    from: ["ontological"],
+    to: ["ontological"],
+    description: "Company -> Investor"
+  },
+  mentioned_in: {
+    from: ["ontological"],
+    to: ["L1", "L2"],
+    description: "Entity -> Source/Evidence"
+  },
+  perspective_on: {
+    from: ["ontological"],
+    to: ["L3"],
+    description: "Person -> Belief/Theme"
+  },
+  plays_theme: {
+    from: ["ontological"],
+    to: ["L3"],
+    description: "Deal -> Theme"
+  }
+};
+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} -> ${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(", ")}`
+    };
+  }
+  if (!isValidLayerConnection(fromLayer, toLayer)) {
+    return {
+      valid: false,
+      reason: `Layer transition ${fromLayer} -> ${toLayer} is not permitted`
+    };
+  }
+  return { valid: true };
+}
+
+// src/epistemicEdges.mutations.ts
+var create = mutation({
+  args: {
+    globalId: v.string(),
+    fromNodeId: v.id("epistemicNodes"),
+    toNodeId: v.id("epistemicNodes"),
+    edgeType: edgeTypeValidator,
+    weight: v.optional(v.number()),
+    confidence: v.optional(v.number()),
+    context: v.optional(v.string()),
+    derivationType: v.optional(v.string()),
+    createdBy: v.string(),
+    ...optionalScopeArgs,
+    skipLayerValidation: v.optional(v.boolean())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const fromNode = await ctx.db.get(args.fromNodeId);
+    const toNode = await ctx.db.get(args.toNodeId);
+    if (!fromNode || !toNode) {
+      throw new Error("One or both nodes not found");
+    }
+    const resolvedScope = args.topicId || args.projectId ? await resolveTopicProjectScope(ctx, {
+      topicId: args.topicId,
+      projectId: args.projectId
+    }) : void 0;
+    const resolvedProjectId = resolvedScope?.projectId ?? args.projectId;
+    if (resolvedProjectId) {
+      await requireProjectAccess(ctx, resolvedProjectId, args.createdBy);
+    }
+    const fromLayer = fromNode.epistemicLayer || getNodeLayer(fromNode.nodeType);
+    const toLayer = toNode.epistemicLayer || getNodeLayer(toNode.nodeType);
+    if (!args.skipLayerValidation) {
+      const validation = validateEdgeLayers(args.edgeType, fromLayer, toLayer);
+      if (!validation.valid) {
+        throw new Error(
+          `[EdgeValidation] Invalid edge: ${validation.reason}. Attempted: ${args.edgeType} from ${fromNode.nodeType}(${fromLayer}) \u2192 ${toNode.nodeType}(${toLayer})`
+        );
+      }
+    }
+    if (isDeprecatedEdgeType(args.edgeType)) {
+      throw new Error(
+        `FORBIDDEN: Edge type '${args.edgeType}' has been removed from StackOS schema.`
+      );
+    }
+    const existing = await ctx.db.query("epistemicEdges").withIndex(
+      "by_from_to",
+      (q) => q.eq("fromNodeId", args.fromNodeId).eq("toNodeId", args.toNodeId)
+    ).collect();
+    const duplicateEdge = existing.find((e) => e.edgeType === args.edgeType);
+    if (duplicateEdge) {
+      return { edgeId: duplicateEdge._id, isDuplicate: true };
+    }
+    await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+      globalId: args.globalId,
+      fromGlobalId: fromNode.globalId,
+      toGlobalId: toNode.globalId,
+      edgeType: args.edgeType,
+      weight: args.weight,
+      confidence: args.confidence,
+      context: args.context,
+      derivationType: args.derivationType,
+      createdBy: args.createdBy,
+      topicId: resolvedProjectId ? String(resolvedProjectId) : void 0,
+      fromNodeType: fromNode.nodeType,
+      toNodeType: toNode.nodeType,
+      fromLayer,
+      toLayer
+    });
+    const auditProjectId = resolvedProjectId || fromNode.projectId;
+    if (auditProjectId) {
+      await ctx.db.insert("epistemicAudit", {
+        entityType: "edge",
+        entityId: args.globalId,
+        changeType: "edge_added",
+        changedAt: Date.now(),
+        changedBy: args.createdBy,
+        isAgent: false,
+        newState: {
+          edgeType: args.edgeType,
+          fromNodeId: String(args.fromNodeId),
+          toNodeId: String(args.toNodeId),
+          weight: args.weight
+        },
+        projectId: auditProjectId
+      });
+      await resolveGraphPrimitivesAppResolvers().patchProject(
+        ctx,
+        auditProjectId,
+        {
+          lastActivityAt: Date.now()
+        }
+      );
+    }
+    return { edgeGlobalId: args.globalId, isDuplicate: false };
+  }
+});
+var update = mutation({
+  args: {
+    edgeId: v.id("epistemicEdges"),
+    weight: v.optional(v.number()),
+    confidence: v.optional(v.number()),
+    context: v.optional(v.string()),
+    derivationType: v.optional(v.string()),
+    userId: v.optional(v.string()),
+    constraint: v.optional(v.string()),
+    propagation: v.optional(v.string()),
+    blocking: v.optional(v.boolean()),
+    implicit: v.optional(v.boolean()),
+    conditionalA: v.optional(subjectiveOpinionValidator),
+    conditionalNotA: v.optional(subjectiveOpinionValidator),
+    containment: v.optional(v.string()),
+    interrogation: v.optional(v.string()),
+    reasoningMethod: v.optional(v.string()),
+    analogyBasis: v.optional(v.string()),
+    disanalogies: v.optional(v.array(v.string())),
+    analogyStrength: v.optional(v.number()),
+    causal: v.optional(v.boolean()),
+    predictionFulfilled: v.optional(v.boolean()),
+    predictionFulfilledAt: v.optional(v.number()),
+    predictionFulfilledBy: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const { edgeId, userId, ...updates } = args;
+    const edge = await ctx.db.get(edgeId);
+    if (!edge) {
+      throw new Error("Edge not found");
+    }
+    if (edge.projectId && userId) {
+      await requireProjectAccess(ctx, edge.projectId, userId);
+    }
+    const cleanUpdates = {};
+    for (const [key, value] of Object.entries(updates)) {
+      if (value !== void 0) {
+        cleanUpdates[key] = value;
+      }
+    }
+    await ctx.db.patch(edgeId, cleanUpdates);
+    if (edge.projectId) {
+      await ctx.db.insert("epistemicAudit", {
+        entityType: "edge",
+        entityId: edge.globalId,
+        changeType: "updated",
+        changedAt: Date.now(),
+        changedBy: userId || edge.createdBy,
+        isAgent: false,
+        previousState: {
+          weight: edge.weight,
+          confidence: edge.confidence,
+          context: edge.context
+        },
+        newState: cleanUpdates,
+        projectId: edge.projectId
+      });
+    }
+    return buildEdgeStatusSuccessResult();
+  }
+});
+var remove = mutation({
+  args: {
+    edgeId: v.id("epistemicEdges"),
+    userId: v.optional(v.string())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const edge = await ctx.db.get(args.edgeId);
+    if (!edge) {
+      return buildEdgeNotFoundResult();
+    }
+    if (edge.projectId && args.userId) {
+      await requireProjectAccess(ctx, edge.projectId, args.userId);
+    }
+    if (edge.projectId) {
+      await ctx.db.insert("epistemicAudit", {
+        entityType: "edge",
+        entityId: edge.globalId,
+        changeType: "edge_removed",
+        changedAt: Date.now(),
+        changedBy: args.userId || edge.createdBy,
+        isAgent: false,
+        previousState: {
+          edgeType: edge.edgeType,
+          fromNodeId: String(edge.fromNodeId),
+          toNodeId: edge.toNodeId ? String(edge.toNodeId) : void 0,
+          weight: edge.weight
+        },
+        projectId: edge.projectId
+      });
+      await resolveGraphPrimitivesAppResolvers().patchProject(
+        ctx,
+        edge.projectId,
+        {
+          lastActivityAt: Date.now()
+        }
+      );
+    }
+    await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.deleteEdge, {
+      globalId: edge.globalId
+    });
+    await ctx.db.delete(args.edgeId);
+    return buildEdgeStatusSuccessResult();
+  }
+});
+var removeBetween = mutation({
+  args: {
+    fromNodeId: v.id("epistemicNodes"),
+    toNodeId: v.id("epistemicNodes"),
+    edgeType: v.optional(edgeTypeValidator)
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const edges = await ctx.db.query("epistemicEdges").withIndex(
+      "by_from_to",
+      (q) => q.eq("fromNodeId", args.fromNodeId).eq("toNodeId", args.toNodeId)
+    ).collect();
+    let deleted = 0;
+    for (const edge of edges) {
+      if (!args.edgeType || edge.edgeType === args.edgeType) {
+        await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.deleteEdge, {
+          globalId: edge.globalId
+        });
+        await ctx.db.delete(edge._id);
+        deleted++;
+      }
+    }
+    return { deleted };
+  }
+});
+var batchCreate = mutation({
+  args: {
+    edges: v.array(
+      v.object({
+        globalId: v.string(),
+        fromNodeId: v.id("epistemicNodes"),
+        toNodeId: v.id("epistemicNodes"),
+        edgeType: edgeTypeValidator,
+        weight: v.optional(v.number()),
+        confidence: v.optional(v.number()),
+        context: v.optional(v.string()),
+        derivationType: v.optional(v.string()),
+        createdBy: v.string(),
+        ...optionalScopeArgs
+      })
+    ),
+    skipLayerValidation: v.optional(v.boolean())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const results = [];
+    const errors = [];
+    for (const edge of args.edges) {
+      const fromNode = await ctx.db.get(edge.fromNodeId);
+      const toNode = await ctx.db.get(edge.toNodeId);
+      if (!fromNode || !toNode) {
+        errors.push({
+          globalId: edge.globalId,
+          error: "One or both nodes not found"
+        });
+        continue;
+      }
+      const fromLayer = fromNode.epistemicLayer || getNodeLayer(fromNode.nodeType);
+      const toLayer = toNode.epistemicLayer || getNodeLayer(toNode.nodeType);
+      if (!args.skipLayerValidation) {
+        const validation = validateEdgeLayers(edge.edgeType, fromLayer, toLayer);
+        if (!validation.valid) {
+          errors.push({
+            globalId: edge.globalId,
+            error: validation.reason || "Invalid layer combination"
+          });
+          continue;
+        }
+      }
+      if (isDeprecatedEdgeType(edge.edgeType)) {
+        errors.push({
+          globalId: edge.globalId,
+          error: `FORBIDDEN: Edge type '${edge.edgeType}' has been removed from StackOS schema.`
+        });
+        continue;
+      }
+      await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.createEdge, {
+        globalId: edge.globalId,
+        fromGlobalId: fromNode.globalId,
+        toGlobalId: toNode.globalId,
+        edgeType: edge.edgeType,
+        weight: edge.weight,
+        confidence: edge.confidence,
+        context: edge.context,
+        derivationType: edge.derivationType,
+        createdBy: edge.createdBy,
+        topicId: edge.projectId ? String(edge.projectId) : void 0,
+        fromNodeType: fromNode.nodeType,
+        toNodeType: toNode.nodeType,
+        fromLayer,
+        toLayer
+      });
+      results.push({ globalId: edge.globalId, edgeGlobalId: edge.globalId });
+    }
+    const projectIds = new Set(
+      args.edges.flatMap(
+        (edge) => typeof edge.projectId === "string" ? [edge.projectId] : []
+      )
+    );
+    for (const pid of projectIds) {
+      if (pid) {
+        await resolveGraphPrimitivesAppResolvers().patchProject(ctx, pid, {
+          lastActivityAt: Date.now()
+        });
+      }
+    }
+    return { created: results.length, results, errors };
+  }
+});
+var cleanupDeprecatedEdges = mutation({
+  args: {
+    ...optionalScopeArgs,
+    dryRun: v.optional(v.boolean())
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const DEPRECATED_TYPES = ["contradicts"];
+    const scopeId = args.topicId || args.projectId;
+    const allEdges = scopeId ? await ctx.db.query("epistemicEdges").withIndex("by_topic", (q) => q.eq("topicId", scopeId)).collect() : [];
+    const deprecatedEdges = allEdges.filter(
+      (edge) => DEPRECATED_TYPES.includes(edge.edgeType)
+    );
+    if (args.dryRun) {
+      return {
+        dryRun: true,
+        found: deprecatedEdges.length,
+        edges: deprecatedEdges.map((e) => ({
+          id: e._id,
+          type: e.edgeType,
+          from: e.fromNodeId,
+          to: e.toNodeId,
+          description: typeof e.context === "object" && e.context && "description" in e.context ? e.context.description : e.description
+        })),
+        message: `Would delete ${deprecatedEdges.length} deprecated edges`
+      };
+    }
+    for (const edge of deprecatedEdges) {
+      await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.deleteEdge, {
+        globalId: edge.globalId
+      });
+      await ctx.db.delete(edge._id);
+    }
+    return {
+      dryRun: false,
+      deleted: deprecatedEdges.length,
+      edges: deprecatedEdges.map((e) => ({
+        id: e._id,
+        type: e.edgeType
+      })),
+      message: `Deleted ${deprecatedEdges.length} deprecated edges`
+    };
+  }
+});
+var deleteEdges = mutation({
+  args: {
+    edgeIds: v.array(v.id("epistemicEdges"))
+  },
+  returns: permissiveReturn,
+  handler: async (ctx, args) => {
+    const deleted = [];
+    const notFound = [];
+    for (const edgeId of args.edgeIds) {
+      const edge = await ctx.db.get(edgeId);
+      if (edge) {
+        await ctx.scheduler.runAfter(0, internal.neo4jEdgeAPI.deleteEdge, {
+          globalId: edge.globalId
+        });
+        await ctx.db.delete(edgeId);
+        deleted.push(edgeId);
+      } else {
+        notFound.push(edgeId);
+      }
+    }
+    return {
+      deleted: deleted.length,
+      notFound: notFound.length,
+      message: `Deleted ${deleted.length} edges, ${notFound.length} not found`
+    };
+  }
+});
+
+export { batchCreate, cleanupDeprecatedEdges, create, deleteEdges, remove, removeBetween, update };
+//# sourceMappingURL=epistemicEdges.mutations.js.map
+//# sourceMappingURL=epistemicEdges.mutations.js.map