Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

40.1 KB
Raw Blame
// Copyright 2026 Ix Infrastructure Inc.

import * as crypto from 'node:crypto';
import * as nodePath from 'node:path';
import type { GraphPatchPayload, PatchOp } from './types.js';
import { resolveEdges } from './index.js';
import type { FileParseResult, ParsedEntity, ResolutionTier, ResolvedEdge } from './index.js';

// ---------------------------------------------------------------------------
// Deterministic UUID from a string (matches existing CLI convention)
// ---------------------------------------------------------------------------

function deterministicId(input: string): string {
  const hash = crypto.createHash('sha256').update(input).digest('hex');
  return [
    hash.slice(0, 8),
    hash.slice(8, 12),
    hash.slice(12, 16),
    hash.slice(16, 20),
    hash.slice(20, 32),
  ].join('-');
}

function normalizePath(filePath: string): string {
  return filePath.replace(/\\/g, '/').toLowerCase();
}

/**
 * Identity helpers bound to a single workspace. Folding `workspaceId` into every
 * id keeps the same relative path in two different workspaces from colliding on
 * a shared backend, while staying stable within a workspace. Binding it once via
 * a factory means every call site below is scoped automatically (no per-call
 * threading to forget). `workspaceId` is empty only for callers that have not
 * adopted workspace-scoped identity yet.
 */
function makeIds(workspaceId: string) {
  const ns = workspaceId ? `${workspaceId}:` : '';
  return {
    nodeId: (filePath: string, name: string): string =>
      deterministicId(`${ns}${normalizePath(filePath)}:${name}`),

    edgeId: (filePath: string, src: string, dst: string, predicate: string): string =>
      deterministicId(`${ns}${normalizePath(filePath)}:${src}:${dst}:${predicate}`),

    // Chunk id is keyed on file + kind + name + start line to survive minor edits.
    chunkId: (filePath: string, chunkKind: string, name: string | null, startLine: number): string =>
      deterministicId(`${ns}${normalizePath(filePath)}:chunk:${chunkKind}:${name ?? 'file_body'}:${startLine}`),

    // patchId for a (filePath, sourceHash, extractorVersion) triple.
    computePatchId: (filePath: string, sourceHash: string, extractor: string): string =>
      deterministicId(`${ns}${normalizePath(filePath)}:${sourceHash}:${extractor}`),

    // Legacy patchId (pre-1.1 scheme, no extractor suffix).
    legacyPatchId: (filePath: string, sourceHash: string): string =>
      deterministicId(`${ns}${filePath}:${sourceHash}`),
  };
}

/**
 * The node id of a file's `file` node, for a SOLO ingest (no member prefix).
 * Exposed so the Path-2 stitcher (CLI) can reference a repo's entry node and its
 * importing nodes by the SAME id buildPatch produces — never a recomputed guess.
 * Mirrors buildPatch: the file node's key is the file entity name = basename.
 */
export function fileNodeId(workspaceId: string, filePath: string): string {
  return makeIds(workspaceId).nodeId(filePath, nodePath.basename(filePath));
}

/**
 * The node id of a symbol (function/class/...) in a SOLO ingest, by its qualified
 * key (`name`, or `container.name` for a member). Lets the Path-2 symbol-level
 * stitcher reference a provider's exported symbol and a consumer's calling symbol
 * by the SAME id buildPatch produces — so cross-repo CALL edges land on real nodes.
 */
export function symbolNodeId(workspaceId: string, filePath: string, qualifiedKey: string): string {
  return makeIds(workspaceId).nodeId(filePath, qualifiedKey);
}

// ---------------------------------------------------------------------------
// Source type from file extension
// ---------------------------------------------------------------------------

function sourceType(filePath: string): string {
  const normalized = filePath.replace(/\\/g, '/');
  const fileName = normalized.slice(normalized.lastIndexOf('/') + 1).toLowerCase();
  if (fileName === 'dockerfile' || fileName.endsWith('.dockerfile')) return 'config';
  const dotIndex = fileName.lastIndexOf('.');
  const ext = dotIndex === -1 ? '' : fileName.slice(dotIndex);
  if (['.json', '.yaml', '.yml', '.toml', '.ini', '.conf', '.env'].includes(ext)) return 'config';
  if (['.md', '.mdx', '.rst', '.txt'].includes(ext)) return 'doc';
  return 'code';
}

/**
 * Keep each logical edge once per patch. Parsers can emit the same relationship
 * more than once (for example, every declaration in a Python @overload group).
 * Edge ids intentionally collapse those declarations to one graph edge, so
 * forwarding every occurrence would send duplicate physical keys to ArangoDB.
 * A repeated id with different endpoints is an identity bug, not a duplicate;
 * fail before commit rather than silently disconnecting part of the graph.
 */
function deduplicateUpsertEdges(ops: PatchOp[]): PatchOp[] {
  const deduplicated: PatchOp[] = [];
  const edgeIndexById = new Map<string, number>();
  for (const op of ops) {
    if (op.type !== 'UpsertEdge') {
      deduplicated.push(op);
      continue;
    }
    const edgeId = op.id;
    if (typeof edgeId !== 'string') {
      deduplicated.push(op);
      continue;
    }
    const existingIndex = edgeIndexById.get(edgeId);
    if (existingIndex === undefined) {
      edgeIndexById.set(edgeId, deduplicated.length);
      deduplicated.push(op);
      continue;
    }
    const existing = deduplicated[existingIndex];
    if (existing.src !== op.src || existing.dst !== op.dst || existing.predicate !== op.predicate) {
      throw new Error(`Conflicting UpsertEdge identity for deterministic id ${edgeId}`);
    }
    // Exact logical duplicate: retain the last operation's attributes.
    deduplicated[existingIndex] = op;
  }
  return deduplicated;
}

/**
 * Part of every patch id, and the backend skips a patch id it has already
 * applied. Bump it whenever the same source would now produce different nodes
 * or edges, or re-ingesting an unchanged file (`ix ingest --force`) yields the
 * old id and the new output never lands -- 1.26: JS/TS calls resolve by scope,
 * not name alone, and helper-loaded / dist/ imports link to their sources.
 * 1.27: Python, Rust and PHP bare calls no longer resolve to another file's
 * class member. 1.28: no edge is written without a node at both ends (calls
 * that resolve nowhere go on their caller as `unresolved_calls`), and
 * cross-file edges carry `confidence` and `tier`. 1.29: cross-file resolution
 * no longer depends on how files are split into batches, TypeScript gaps
 * (overload signatures, generic type references) are extracted, and files
 * carry `parse_errors` and their role.
 *
 * `ix map` skips files whose mtime or source hash is unchanged, which would
 * keep the old extractor's edges on them, so the ingest baseline records this
 * name and a run that finds a different one re-ingests every file once.
 */
/**
 * Actor stamped on ingestion patches. A kOS cloud backend binds a patch's actor
 * to the verified principal and REJECTS a non-empty actor that differs from it
 * (403 "body actor ... conflicts with verified principal"), so a cloud ingest
 * must send an empty actor (IX_PATCH_ACTOR="") and let the server stamp the
 * authenticated identity. Local/OSS backends keep the historical default.
 */
export function patchActor(): string {
  return process.env.IX_PATCH_ACTOR ?? 'ix/ingestion';
}

export function extractorName(): string {
  return `tree-sitter/1.30`;
}

/** Previous extractor versions — their patches are superseded when re-ingesting. */
export const PREVIOUS_EXTRACTORS = ['tree-sitter/1.29', 'tree-sitter/1.28', 'tree-sitter/1.27', 'tree-sitter/1.26', 'tree-sitter/1.25', 'tree-sitter/1.24', 'tree-sitter/1.23', 'tree-sitter/1.22', 'tree-sitter/1.21', 'tree-sitter/1.20', 'tree-sitter/1.19', 'tree-sitter/1.18', 'tree-sitter/1.17', 'tree-sitter/1.16', 'tree-sitter/1.15', 'tree-sitter/1.14', 'tree-sitter/1.13', 'tree-sitter/1.12', 'tree-sitter/1.11', 'tree-sitter/1.10', 'tree-sitter/1.9', 'tree-sitter/1.8', 'tree-sitter/1.7', 'tree-sitter/1.6', 'tree-sitter/1.5', 'tree-sitter/1.4', 'tree-sitter/1.3', 'tree-sitter/1.2', 'tree-sitter/1.1'];

/** Patch ids that may own the active graph entities for a stored source hash. */
export function sourcePatchIdCandidates(
  filePath: string,
  sourceHash: string,
  workspaceId: string,
): string[] {
  const { computePatchId, legacyPatchId } = makeIds(workspaceId);
  return [
    computePatchId(filePath, sourceHash, extractorName()),
    ...PREVIOUS_EXTRACTORS.map(extractor => computePatchId(filePath, sourceHash, extractor)),
    legacyPatchId(filePath, sourceHash),
  ];
}

// nodeId / edgeId / chunkId / computePatchId / legacyPatchId are produced by
// makeIds(workspaceId) above so every id is scoped to its workspace.

/**
 * In a multi-repo co-ingest, file paths are workspace-relative AND repo-prefixed:
 * the first path segment is the member repo directory (see `repoOf` in the CLI).
 * Node / edge / chunk IDENTITY is folded over the MEMBER-relative path (that prefix
 * stripped) paired with the member's own workspace_id, so a repo's ids are
 * byte-identical whether it is ingested alone or as part of a system. PROVENANCE
 * (source_uri / file_uri / patch id) deliberately keeps the full workspace-relative
 * path so reads can reconstruct an absolute path under the workspace root. Edge
 * *matching* (resolvedEdges keyed on srcFilePath) also uses the full path, and
 * repoWorkspaceOf is given the full path to identify the owning repo. Single-repo
 * ingest (no multiRepo) is unchanged (idPath === filePath).
 */
function toMemberRelativePath(filePath: string, multiRepo?: MultiRepoContext): string {
  if (!multiRepo) return filePath;
  const norm = filePath.replace(/\\/g, '/');
  const slash = norm.indexOf('/');
  return slash >= 0 ? norm.slice(slash + 1) : norm;
}

/** Most unresolved callee names kept on one node; the count covers them all. */
export const UNRESOLVED_CALLS_CAP = 20;

/**
 * Calls that wrote no edge, by the node that makes them. An edge needs a node
 * at both ends, so a call to a builtin, a library or a name that resolved
 * nowhere leaves no trace in the graph but these attrs, which is what `ix
 * explain` reads to say which calls it could not follow:
 *
 *  - `unresolved_calls`: the distinct callee names as written at the call
 *    site, in first-seen (source) order, at most UNRESOLVED_CALLS_CAP;
 *  - `unresolved_call_count`: how many distinct names there were, so a cut
 *    list is visible as one.
 *
 * A call goes on the function, method or class that makes it; one from
 * module-level code, or from a caller no node was written for, on the file.
 * Nodes with none get neither attr.
 */
function unresolvedCallRecorder(knownNodeIds: ReadonlySet<string>, fileNodeId: string) {
  const byNode = new Map<string, Set<string>>();
  return {
    add(srcNodeId: string, calleeName: string): void {
      const owner = knownNodeIds.has(srcNodeId) ? srcNodeId : fileNodeId;
      let names = byNode.get(owner);
      if (!names) { names = new Set<string>(); byNode.set(owner, names); }
      names.add(calleeName);
    },
    /** Write the attrs onto the UpsertNode ops already in `ops`. */
    applyTo(ops: PatchOp[]): void {
      if (byNode.size === 0) return;
      for (const op of ops) {
        if (op.type !== 'UpsertNode') continue;
        const names = byNode.get(op.id as string);
        if (!names) continue;
        op.attrs = {
          ...((op.attrs as Record<string, unknown> | undefined) ?? {}),
          unresolved_calls: [...names].slice(0, UNRESOLVED_CALLS_CAP),
          unresolved_call_count: names.size,
        };
      }
    },
  };
}

// ---------------------------------------------------------------------------
// Build a GraphPatchPayload from a FileParseResult
// ---------------------------------------------------------------------------

export function buildPatch(
  result: FileParseResult,
  sourceHash: string,
  workspaceId: string,
  previousSourceHash?: string,
  multiRepo?: MultiRepoContext,
): GraphPatchPayload {
  const { entities, chunks } = result;
  // A typed receiver call is resolved even within one file: its exact member
  // decides whether a receiver-only relationship becomes an edge at all.
  if (result.relationships.some(r => r.receiverType || r.receiverFactory)) {
    return buildPatchWithResolution(result, sourceHash, workspaceId, resolveEdges([result]), previousSourceHash, multiRepo);
  }
  // A helper-literal import is inferred and only means something once resolved
  // to a tracked file; without resolution it would be a dangling edge.
  const relationships = result.relationships.filter(r => r.importVia !== 'helper');
  // Two paths, deliberately distinct (see toMemberRelativePath):
  //  - filePath (workspace-relative, repo-prefixed in a co-ingest) is PROVENANCE:
  //    source_uri / file_uri / patch id. Reads reconstruct an absolute path by
  //    joining it to the workspace root, so it must stay relative to that root.
  //  - idPath (member-relative) is IDENTITY: node / edge / chunk ids fold it so a
  //    member's ids are byte-identical whether ingested alone or in a system.
  // Single repo: idPath === filePath.
  const filePath = result.filePath;
  const idPath = toMemberRelativePath(result.filePath, multiRepo);
  const { nodeId, edgeId, chunkId, computePatchId, legacyPatchId } = makeIds(workspaceId);
  const ops: PatchOp[] = [];

  // Build a qualified-key map so that same-named entities in different
  // enclosing classes within the same file get distinct nodeIds.
  // e.g.  ClassA.update  vs  ClassB.update  instead of both being "update".
  const entityQKey = new Map<ParsedEntity, string>();
  for (const e of entities) {
    entityQKey.set(e, e.container ? `${e.container}.${e.name}` : e.name);
  }

  // Reverse lookup: plain name → list of qualified keys (for edge resolution).
  const nameToQKeys = new Map<string, string[]>();
  for (const [e, qk] of entityQKey) {
    const list = nameToQKeys.get(e.name) ?? [];
    list.push(qk);
    nameToQKeys.set(e.name, list);
  }

  // Set of all qualified keys defined in this file — used to distinguish same-file
  // dotted calls (e.g. "Foo.bar" where Foo is defined here) from external qualified
  // calls (e.g. "dplyr.filter" from R's pkg::func syntax) that would produce phantoms.
  const allQKeys = new Set<string>(entityQKey.values());

  // Resolve a relationship endpoint to the best qualified key.
  // For unambiguous names (appear once), returns the single qualified key.
  // For ambiguous names (appear multiple times), falls back to the plain name
  // so that the edge still points to *something* deterministic.
  function resolveKey(name: string, container?: string): string {
    const rawKeys = nameToQKeys.get(name);
    if (!rawKeys) return name;
    // Deduplicate: @overload in Python (and similar patterns in other languages)
    // produces multiple definitions with identical qualified keys. A Set collapses
    // these so we don't mistake three `Session.execute` overloads for ambiguity.
    const keys = [...new Set(rawKeys)];
    if (keys.length === 1) return keys[0];
    // More than one distinct entity with this name — try to pick by container
    if (container) {
      const qualified = `${container}.${name}`;
      if (keys.includes(qualified)) return qualified;
    }
    // Ambiguous: return plain name so we don't silently drop the edge
    return name;
  }

  // UpsertNode for each entity (deduplicated by id — last occurrence wins)
  const seenNodeIds = new Set<string>();
  for (const e of entities) {
    const qk = entityQKey.get(e)!;
    const id = nodeId(idPath, qk);
    if (!seenNodeIds.has(id)) {
      seenNodeIds.add(id);
      const roleAttrs = e.kind === 'file'
        ? { role: result.fileRole.role, role_confidence: result.fileRole.role_confidence, role_signals: result.fileRole.role_signals, ...(result.hasParseErrors ? { parse_errors: true } : {}) }
        : { role: result.fileRole.role, role_source: 'inherited_from_file' };
      ops.push({
        type: 'UpsertNode',
        id,
        kind: e.kind,
        name: e.name,
        attrs: {
          line_start: e.lineStart,
          line_end: e.lineEnd,
          language: e.language,
          ...roleAttrs,
        },
      });
    }
  }

  // UpsertNode + edges for each chunk
  const fileNodeId = nodeId(idPath, entities.find(e => e.kind === 'file')?.name ?? idPath);
  for (const chunk of chunks) {
    const cid = chunkId(idPath, chunk.chunkKind, chunk.name, chunk.lineStart);
    const chunkName = chunk.name ?? `file_body:${chunk.lineStart}`;
    const chunkNodeKind = chunk.chunkKind === 'section' ? 'section' : 'chunk';
    ops.push({
      type: 'UpsertNode',
      id: cid,
      kind: chunkNodeKind,
      name: chunkName,
      attrs: {
        file_uri: filePath,
        language: chunk.language,
        chunk_kind: chunk.chunkKind,
        start_line: chunk.lineStart,
        end_line: chunk.lineEnd,
        start_byte: chunk.startByte,
        end_byte: chunk.endByte,
        content_hash: chunk.contentHash,
        parser_version: extractorName(),
      },
    });
    // File -[CONTAINS]-> Chunk
    ops.push({
      type: 'UpsertEdge',
      id: edgeId(idPath, fileNodeId, cid, 'CONTAINS_CHUNK'),
      src: fileNodeId,
      dst: cid,
      predicate: 'CONTAINS_CHUNK',
      attrs: {},
    });
    // Chunk -[DEFINES]-> Symbol (only for named chunks whose symbol this patch
    // writes; any other would point at a node that does not exist)
    if (chunk.name !== null) {
      const symbolKey = chunk.container ? `${chunk.container}.${chunk.name}` : chunk.name;
      const symbolNid = nodeId(idPath, symbolKey);
      if (seenNodeIds.has(symbolNid)) ops.push({
        type: 'UpsertEdge',
        id: edgeId(idPath, cid, symbolNid, 'DEFINES'),
        src: cid,
        dst: symbolNid,
        predicate: 'DEFINES',
        attrs: {},
      });
    }
  }

  // NEXT edges for source-order chunk adjacency
  for (let i = 0; i + 1 < chunks.length; i++) {
    const a = chunks[i];
    const b = chunks[i + 1];
    // Only link top-level chunks (no container) to avoid intra-class ordering noise
    if (a.container == null && b.container == null) {
      const aid = chunkId(idPath, a.chunkKind, a.name, a.lineStart);
      const bid = chunkId(idPath, b.chunkKind, b.name, b.lineStart);
      ops.push({
        type: 'UpsertEdge',
        id: edgeId(idPath, aid, bid, 'NEXT'),
        src: aid,
        dst: bid,
        predicate: 'NEXT',
        attrs: {},
      });
    }
  }

  // UpsertEdge for each relationship -- only those with a node at both ends; see
  // `keepEdge` in buildPatchWithResolution. Without resolution, that means a
  // node this patch writes or an external node it mints.
  const seenExternalNodes = new Set<string>();
  const unresolvedCalls = unresolvedCallRecorder(seenNodeIds, fileNodeId);
  for (const r of relationships) {
    // For CONTAINS edges, srcName is the container of dstName — use that to disambiguate.
    const srcKey = resolveKey(r.srcName);
    const dstKey = r.predicate === 'CONTAINS'
      ? resolveKey(r.dstName, r.srcName)
      : resolveKey(r.dstName);
    const external = r.predicate === 'CALLS' && dstKey.includes('::') && !allQKeys.has(dstKey);
    if (!seenNodeIds.has(nodeId(idPath, srcKey)) || (!external && !seenNodeIds.has(nodeId(idPath, dstKey)))) {
      if (r.predicate === 'CALLS') unresolvedCalls.add(nodeId(idPath, srcKey), r.dstName);
      continue;
    }

    let dstNid: string;
    if (external) {
      const sep = dstKey.indexOf('::');
      const pkgName = dstKey.slice(0, sep);
      const funcName = dstKey.slice(sep + 2);
      const extPath = `external://${pkgName}`;
      dstNid = nodeId(extPath, dstKey);
      if (!seenExternalNodes.has(dstNid)) {
        seenExternalNodes.add(dstNid);
        ops.push({
          type: 'UpsertNode',
          id: dstNid,
          kind: 'function',
          name: funcName,
          attrs: { package: pkgName, external: true, language: result.language },
        });
      }
    } else {
      dstNid = nodeId(idPath, dstKey);
    }

    ops.push({
      type: 'UpsertEdge',
      id: edgeId(idPath, srcKey, dstKey, r.predicate),
      src: nodeId(idPath, srcKey),
      dst: dstNid,
      predicate: r.predicate,
      attrs: {},
    });
  }
  unresolvedCalls.applyTo(ops);

  // AssertClaim for each relationship (feeds the confidence/conflict engine)
  // phpCallKind splits the relationship dedup key, so `handle(); $obj->handle();`
  // arrives as two relationships that produce byte-identical claims. The kind is
  // not part of a claim, so nothing downstream can tell them apart.
  const emittedClaims = new Set<string>();
  for (const r of relationships) {
    const srcKey = resolveKey(r.srcName);
    const entityId = nodeId(idPath, srcKey);
    const field = `${r.predicate.toLowerCase()}:${r.dstName}`;
    const claimIdentity = `${entityId}\x00${field}`;
    if (emittedClaims.has(claimIdentity)) continue;
    emittedClaims.add(claimIdentity);
    ops.push({
      type: 'AssertClaim',
      entityId,
      field,
      value: r.dstName,
      confidence: null,
    });
  }

  // patchId is deterministic: same file + same content + same extractor → same id.
  const extractor = extractorName();
  const patchId = computePatchId(filePath, sourceHash, extractor);
  // When re-ingesting with new extractor version, replace the old patch so the
  // server accepts the new ops rather than deduplicating on the old patchId.
  const previousPatchId = previousSourceHash
    ? computePatchId(filePath, previousSourceHash, extractor)
    : legacyPatchId(filePath, sourceHash);
  // Also supersede any patches created by previous extractor versions for the same file+content.
  const replaces = [previousPatchId, ...PREVIOUS_EXTRACTORS.map(prev => computePatchId(filePath, sourceHash, prev))];

  return {
    patchId,
    actor: patchActor(),
    timestamp: new Date().toISOString(),
    source: {
      uri: filePath,
      sourceHash,
      extractor,
      sourceType: sourceType(filePath),
      workspaceId,
      ...(multiRepo?.systemId ? { systemId: multiRepo.systemId } : {}),
      ...(multiRepo?.repoId ? { repoId: multiRepo.repoId } : {}),
    },
    baseRev: 0,
    ops: deduplicateUpsertEdges(ops),
    replaces,
    intent: `Parsed ${nodePath.basename(filePath)}`,
  };
}

// ---------------------------------------------------------------------------
// buildPatchWithResolution — like buildPatch but fixes CALLS edge dst to point
// to the actual defining file for cross-file calls resolved by resolveCallEdges.
// ---------------------------------------------------------------------------

/**
 * Multi-repo co-ingest context (Ix#225 Path 1). When several repos are ingested
 * as one system, each repo keeps its OWN workspace_id (so a repo's node ids are
 * stable whether ingested alone or in a system), all share a systemId, and each
 * file carries its repoId. A cross-repo resolved edge's dst node lives in another
 * repo whose ids are folded with ITS workspace_id, so dst ids must be resolved in
 * that repo's namespace via repoWorkspaceOf. Absent => single-repo, unchanged.
 */
export interface MultiRepoContext {
  systemId?: string;
  repoId?: string;
  /** filePath (workspace-relative, repo-prefixed) -> that file's repo workspace_id. */
  repoWorkspaceOf?: (filePath: string) => string | undefined;
}

/** Build a patch that retires every entity previously emitted for a deleted file. */
export function buildDeletionPatch(
  filePath: string,
  previousSourceHash: string,
  deletionToken: string,
  workspaceId: string,
  ops: PatchOp[],
  multiRepo?: MultiRepoContext,
): GraphPatchPayload {
  const extractor = extractorName();
  const deletionHash = crypto
    .createHash('sha256')
    .update(`deleted:${previousSourceHash}:${deletionToken}`)
    .digest('hex');
  const { computePatchId } = makeIds(workspaceId);

  return {
    patchId: computePatchId(filePath, deletionHash, extractor),
    actor: patchActor(),
    timestamp: new Date().toISOString(),
    source: {
      uri: filePath,
      sourceHash: deletionHash,
      extractor,
      sourceType: sourceType(filePath),
      workspaceId,
      ...(multiRepo?.systemId ? { systemId: multiRepo.systemId } : {}),
      ...(multiRepo?.repoId ? { repoId: multiRepo.repoId } : {}),
    },
    baseRev: 0,
    ops,
    replaces: sourcePatchIdCandidates(filePath, previousSourceHash, workspaceId),
    intent: `Deleted ${nodePath.basename(filePath)}`,
  };
}

export function buildPatchWithResolution(
  result: FileParseResult,
  sourceHash: string,
  workspaceId: string,
  resolvedEdges: ResolvedEdge[],
  previousSourceHash?: string,
  multiRepo?: MultiRepoContext,
  /**
   * Set when an unchanged file is re-sent because what its edges resolve to
   * changed elsewhere (IN-11): a hash of its new resolution. The patch id must
   * differ from the one its unchanged bytes already have, or the backend
   * answers `Idempotent` and keeps the old edges.
   */
  resolutionSalt?: string,
): GraphPatchPayload {
  // Build lookup: `${srcName}:${predicate}:${dstName}` → { dstFilePath, dstQualifiedKey }
  // Callers should pass only edges for this file (pre-grouped) for best performance,
  // but we still tolerate the full array for backward compatibility.
  const edgeResolution = new Map<string, {
    dstFilePath: string;
    dstQualifiedKey: string;
    confidence: number;
    tier: ResolutionTier | undefined;
  }>();
  for (const edge of resolvedEdges) {
    if (edge.srcFilePath !== result.filePath) continue;
    const callKind = edge.phpCallKind ? `:${edge.phpCallKind}` : '';
    edgeResolution.set(`${edge.srcName}:${edge.predicate}:${edge.dstName}${callKind}`, {
      dstFilePath: edge.dstFilePath,
      dstQualifiedKey: edge.dstQualifiedKey,
      confidence: edge.confidence,
      tier: edge.tier,
    });
  }

  const { entities, chunks } = result;
  // A helper-literal import (see ParsedRelationship.importVia) is inferred from a
  // string, so it is emitted only when resolveEdges tied it to exactly one file.
  const resolvedHere = (r: (typeof result.relationships)[number]): boolean =>
    edgeResolution.has(`${r.srcName}:${r.predicate}:${r.dstName}`);
  const relationships = [
    ...result.relationships.filter(r => !r.receiverOnly && (r.importVia !== 'helper' || resolvedHere(r))),
    // A receiver-only typed call (see ParsedRelationship.receiverOnly) exists only
    // once resolved. Last, so an edge the call's own relationship already wrote
    // keeps its id and only takes the type tier.
    ...result.relationships.filter(r => r.receiverOnly && resolvedHere(r)),
  ];
  // filePath = workspace-relative PROVENANCE (source_uri / file_uri / patch id);
  // idPath = member-relative IDENTITY (node / edge / chunk ids) so a member's ids are
  // byte-identical solo vs. co-ingested. Edge matching still keys on the full
  // result.filePath above. Single-repo: idPath === filePath.
  const filePath = result.filePath;
  const idPath = toMemberRelativePath(result.filePath, multiRepo);
  const { nodeId, edgeId, chunkId, computePatchId, legacyPatchId } = makeIds(workspaceId);
  // Resolve a dst node id in the namespace of the repo that OWNS dstFilePath.
  // For same-repo (or single-repo) dsts this is just nodeId; for a cross-repo
  // edge it folds with the dst repo's workspace_id so the id matches the node
  // that repo's own ingest produced. repoWorkspaceOf needs the full (repo-prefixed)
  // dstFilePath to find the owning repo; the id itself uses the member-relative path.
  const crossRepoIdsCache = new Map<string, ReturnType<typeof makeIds>>();
  const dstNodeIdInRepo = (dstFilePath: string, key: string): string => {
    const ws = multiRepo?.repoWorkspaceOf?.(dstFilePath);
    const dstIdPath = toMemberRelativePath(dstFilePath, multiRepo);
    if (!ws || ws === workspaceId) return nodeId(dstIdPath, key);
    let ids = crossRepoIdsCache.get(ws);
    if (!ids) { ids = makeIds(ws); crossRepoIdsCache.set(ws, ids); }
    return ids.nodeId(dstIdPath, key);
  };
  const ops: PatchOp[] = [];

  const entityQKey = new Map<ParsedEntity, string>();
  for (const e of entities) {
    entityQKey.set(e, e.container ? `${e.container}.${e.name}` : e.name);
  }

  const nameToQKeys = new Map<string, string[]>();
  for (const [e, qk] of entityQKey) {
    const list = nameToQKeys.get(e.name) ?? [];
    list.push(qk);
    nameToQKeys.set(e.name, list);
  }

  const allQKeys2 = new Set<string>(entityQKey.values());

  function resolveKey(name: string, container?: string): string {
    const rawKeys = nameToQKeys.get(name);
    if (!rawKeys) return name;
    const keys = [...new Set(rawKeys)]; // deduplicate — @overload produces identical qks
    if (keys.length === 1) return keys[0];
    if (container) {
      const qualified = `${container}.${name}`;
      if (keys.includes(qualified)) return qualified;
    }
    return name;
  }

  const seenNodeIds2 = new Set<string>();
  for (const e of entities) {
    const qk = entityQKey.get(e)!;
    const id = nodeId(idPath, qk);
    if (!seenNodeIds2.has(id)) {
      seenNodeIds2.add(id);
      const roleAttrs = e.kind === 'file'
        ? { role: result.fileRole.role, role_confidence: result.fileRole.role_confidence, role_signals: result.fileRole.role_signals, ...(result.hasParseErrors ? { parse_errors: true } : {}) }
        : { role: result.fileRole.role, role_source: 'inherited_from_file' };
      ops.push({
        type: 'UpsertNode',
        id,
        kind: e.kind,
        name: e.name,
        attrs: { line_start: e.lineStart, line_end: e.lineEnd, language: e.language, ...roleAttrs },
      });
    }
  }

  // UpsertNode + edges for each chunk (same logic as buildPatch)
  const fileNodeId2 = nodeId(idPath, entities.find(e => e.kind === 'file')?.name ?? idPath);
  for (const chunk of chunks) {
    const cid = chunkId(idPath, chunk.chunkKind, chunk.name, chunk.lineStart);
    const chunkName = chunk.name ?? `file_body:${chunk.lineStart}`;
    const chunkNodeKind2 = chunk.chunkKind === 'section' ? 'section' : 'chunk';
    ops.push({
      type: 'UpsertNode',
      id: cid,
      kind: chunkNodeKind2,
      name: chunkName,
      attrs: {
        file_uri: filePath,
        language: chunk.language,
        chunk_kind: chunk.chunkKind,
        start_line: chunk.lineStart,
        end_line: chunk.lineEnd,
        start_byte: chunk.startByte,
        end_byte: chunk.endByte,
        content_hash: chunk.contentHash,
        parser_version: extractorName(),
      },
    });
    ops.push({
      type: 'UpsertEdge',
      id: edgeId(idPath, fileNodeId2, cid, 'CONTAINS_CHUNK'),
      src: fileNodeId2,
      dst: cid,
      predicate: 'CONTAINS_CHUNK',
      attrs: {},
    });
    if (chunk.name !== null) {
      const symbolKey = chunk.container ? `${chunk.container}.${chunk.name}` : chunk.name;
      const symbolNid = nodeId(idPath, symbolKey);
      if (seenNodeIds2.has(symbolNid)) ops.push({
        type: 'UpsertEdge',
        id: edgeId(idPath, cid, symbolNid, 'DEFINES'),
        src: cid,
        dst: symbolNid,
        predicate: 'DEFINES',
        attrs: {},
      });
    }
  }

  for (let i = 0; i + 1 < chunks.length; i++) {
    const a = chunks[i];
    const b = chunks[i + 1];
    if (a.container == null && b.container == null) {
      const aid = chunkId(idPath, a.chunkKind, a.name, a.lineStart);
      const bid = chunkId(idPath, b.chunkKind, b.name, b.lineStart);
      ops.push({
        type: 'UpsertEdge',
        id: edgeId(idPath, aid, bid, 'NEXT'),
        src: aid,
        dst: bid,
        predicate: 'NEXT',
        attrs: {},
      });
    }
  }

  const seenExternalNodes2 = new Set<string>();
  const emittedEdgeIdentities = new Map<string, PatchOp>();
  /** CALLS dropped for want of a destination node; recorded on their caller. */
  const unresolvedCalls = unresolvedCallRecorder(seenNodeIds2, fileNodeId2);
  const relationshipShapeCounts = new Map<string, number>();
  for (const relationship of relationships) {
    const key = `${relationship.srcName}:${relationship.predicate}:${relationship.dstName}`;
    relationshipShapeCounts.set(key, (relationshipShapeCounts.get(key) ?? 0) + 1);
  }
  /**
   * Where a relationship's destination lands, without emitting anything.
   *
   * Pure so the collision pre-pass below can ask the same question the emission
   * loop does. `externalPkg` is non-null exactly when the answer is an external
   * node the loop still has to mint, which keeps op order identical to before.
   */
  const resolveDst = (r: (typeof relationships)[number], dstKey: string): {
    dstNodeId: string;
    externalPkg: { pkgName: string; funcName: string } | null;
    /** Set when resolveEdges tied the edge to another file. */
    resolution: { confidence: number; tier: ResolutionTier | undefined } | null;
  } => {
    const baseKey = `${r.srcName}:${r.predicate}:${r.dstName}`;
    const salted = r.phpCallKind ? `${baseKey}:${r.phpCallKind}` : baseKey;
    const matched = edgeResolution.has(salted) ? salted : baseKey;

    if (edgeResolution.has(matched)) {
      // Cross-file resolved — use the defining file's nodeId, in the dst repo's
      // workspace namespace (matters only for cross-repo edges in a co-ingest).
      const { dstFilePath, dstQualifiedKey, confidence, tier } = edgeResolution.get(matched)!;
      return {
        dstNodeId: dstNodeIdInRepo(dstFilePath, dstQualifiedKey),
        externalPkg: null,
        resolution: { confidence, tier },
      };
    }
    if (r.predicate === 'CALLS' && dstKey.includes('::') && !allQKeys2.has(dstKey)) {
      const sep = dstKey.indexOf('::');
      const pkgName = dstKey.slice(0, sep);
      const funcName = dstKey.slice(sep + 2);
      return {
        dstNodeId: nodeId(`external://${pkgName}`, dstKey),
        externalPkg: { pkgName, funcName },
        resolution: null,
      };
    }
    return { dstNodeId: nodeId(idPath, dstKey), externalPkg: null, resolution: null };
  };

  /**
   * Whether the edge has a node at both ends. The source must be one this
   * patch upserts; the destination one this patch upserts, an external node it
   * mints, or a node in the file resolveEdges tied it to. Anything else used to
   * be written anyway, pointing at an id no patch ever creates: a call to a
   * builtin, a library, or a name that resolved nowhere. Those dangling edges
   * were over half the edges in a typical graph.
   */
  const keepEdge = (srcNodeId: string, dst: ReturnType<typeof resolveDst>): boolean =>
    seenNodeIds2.has(srcNodeId) &&
    (dst.resolution !== null || dst.externalPkg !== null || seenNodeIds2.has(dst.dstNodeId));

  const relationshipDstKey = (r: (typeof relationships)[number]): string =>
    r.predicate === 'CONTAINS' ? resolveKey(r.dstName, r.srcName) : resolveKey(r.dstName);

  const edgeIdTuple = (srcKey: string, edgeDstKey: string, predicate: string): string =>
    `${srcKey}\x00${edgeDstKey}\x00${predicate}`;

  /**
   * Edge ids fold the *unresolved* destination key, but an edge's identity is
   * its resolved `(src, dst, predicate)`. So when one destination key resolves
   * two ways inside a single file — one call site matched by `edgeResolution`,
   * another falling through to the local node — both edges are real and
   * distinct, yet they mint the same id. `deduplicateUpsertEdges` then sees one
   * id carrying two endpoints and throws, and the caller drops the whole file
   * (#554: 48 files on an ordinary npm dependency tree).
   *
   * Rather than fold the resolved id into every edge — which would rewrite the
   * id of every edge in every graph — salt only the tuples that genuinely
   * collide. Ids outside a collision group stay byte-identical to previous
   * versions, so no re-ingest is needed.
   */
  const collidingIdTuples = new Set<string>();
  {
    const dstsByTuple = new Map<string, Set<string>>();
    for (const r of relationships) {
      const srcKey = resolveKey(r.srcName);
      const dstKey = relationshipDstKey(r);
      const baseKey = `${r.srcName}:${r.predicate}:${r.dstName}`;
      const edgeDstKey = r.phpCallKind && (relationshipShapeCounts.get(baseKey) ?? 0) > 1
        ? `${dstKey}:${r.phpCallKind}`
        : dstKey;
      const dst = resolveDst(r, dstKey);
      // Only edges that are written can collide.
      if (!keepEdge(nodeId(idPath, srcKey), dst)) continue;
      const tuple = edgeIdTuple(srcKey, edgeDstKey, r.predicate);
      let seen = dstsByTuple.get(tuple);
      if (!seen) { seen = new Set<string>(); dstsByTuple.set(tuple, seen); }
      seen.add(dst.dstNodeId);
    }
    for (const [tuple, dsts] of dstsByTuple) {
      if (dsts.size > 1) collidingIdTuples.add(tuple);
    }
  }

  for (const r of relationships) {
    const srcKey = resolveKey(r.srcName);
    const dstKey = relationshipDstKey(r);

    const baseResolutionKey = `${r.srcName}:${r.predicate}:${r.dstName}`;
    const dst = resolveDst(r, dstKey);
    const { dstNodeId, externalPkg, resolution } = dst;
    if (!keepEdge(nodeId(idPath, srcKey), dst)) {
      if (r.predicate === 'CALLS') unresolvedCalls.add(nodeId(idPath, srcKey), r.dstName);
      continue;
    }
    if (externalPkg && !seenExternalNodes2.has(dstNodeId)) {
      seenExternalNodes2.add(dstNodeId);
      ops.push({
        type: 'UpsertNode',
        id: dstNodeId,
        kind: 'function',
        name: externalPkg.funcName,
        attrs: { package: externalPkg.pkgName, external: true, language: result.language },
      });
    }

    const edgeDstKey = r.phpCallKind && (relationshipShapeCounts.get(baseResolutionKey) ?? 0) > 1
      ? `${dstKey}:${r.phpCallKind}`
      : dstKey;
    // The phpCallKind salt above exists so `foo()` and `Bar::foo()` keep distinct
    // ids when they resolve to *different* targets. When they resolve to the same
    // node it instead mints two ids for one edge, and since the dedup downstream
    // keys on id, both commit. An edge is identified by (src, dst, predicate) —
    // two of those with empty attrs are indistinguishable in the graph.
    const edgeIdentity = `${nodeId(idPath, srcKey)}\x00${dstNodeId}\x00${r.predicate}`;
    const emitted = emittedEdgeIdentities.get(edgeIdentity);
    if (emitted) {
      // A typed relationship confirming an edge the call already wrote.
      if (r.receiverOnly && resolution) {
        emitted.attrs = { confidence: resolution.confidence, ...(resolution.tier ? { tier: resolution.tier } : {}) };
      }
      continue;
    }
    // Only a colliding tuple is salted, so every other edge keeps the id it
    // had before this change.
    const idDstKey = collidingIdTuples.has(edgeIdTuple(srcKey, edgeDstKey, r.predicate))
      ? `${edgeDstKey}\x00${dstNodeId}`
      : edgeDstKey;
    const edgeOp: PatchOp = {
      type: 'UpsertEdge',
      id: edgeId(idPath, srcKey, idDstKey, r.predicate),
      src: nodeId(idPath, srcKey),
      dst: dstNodeId,
      predicate: r.predicate,
      attrs: resolution
        ? { confidence: resolution.confidence, ...(resolution.tier ? { tier: resolution.tier } : {}) }
        : {},
    };
    emittedEdgeIdentities.set(edgeIdentity, edgeOp);
    ops.push(edgeOp);
  }
  unresolvedCalls.applyTo(ops);

  // phpCallKind splits the relationship dedup key, so `handle(); $obj->handle();`
  // arrives as two relationships that produce byte-identical claims. The kind is
  // not part of a claim, so nothing downstream can tell them apart.
  const emittedClaims = new Set<string>();
  for (const r of relationships) {
    // A receiver-only typed call claims nothing the call's own relationship does not.
    if (r.receiverOnly) continue;
    const srcKey = resolveKey(r.srcName);
    const entityId = nodeId(idPath, srcKey);
    const field = `${r.predicate.toLowerCase()}:${r.dstName}`;
    const claimIdentity = `${entityId}\x00${field}`;
    if (emittedClaims.has(claimIdentity)) continue;
    emittedClaims.add(claimIdentity);
    ops.push({
      type: 'AssertClaim',
      entityId,
      field,
      value: r.dstName,
      confidence: null,
    });
  }

  const extractor = extractorName();
  const patchId = computePatchId(filePath, sourceHash, resolutionSalt ? `${extractor}#r${resolutionSalt}` : extractor);
  const previousPatchId = previousSourceHash
    ? computePatchId(filePath, previousSourceHash, extractor)
    : legacyPatchId(filePath, sourceHash);
  const replaces = [previousPatchId, ...PREVIOUS_EXTRACTORS.map(prev => computePatchId(filePath, sourceHash, prev))];

  return {
    patchId,
    actor: patchActor(),
    timestamp: new Date().toISOString(),
    source: {
      uri: filePath,
      sourceHash,
      extractor,
      sourceType: sourceType(filePath),
      workspaceId,
      ...(multiRepo?.systemId ? { systemId: multiRepo.systemId } : {}),
      ...(multiRepo?.repoId ? { repoId: multiRepo.repoId } : {}),
    },
    baseRev: 0,
    ops: deduplicateUpsertEdges(ops),
    replaces,
    intent: `Parsed ${nodePath.basename(filePath)}`,
  };
}