From c7028c1727bc78bde330660d4bb0e8fe78e7d84e Mon Sep 17 00:00:00 2001
From: Dead-Bytes <143434285+Dead-Bytes@users.noreply.github.com>
Date: Fri, 10 Jul 2026 00:12:02 +0530
Subject: [PATCH] feat: units path migrate

---
 packages/ingest-core/src/index.ts    |  2 +-
 packages/ingest-core/src/path-map.ts | 16 ++++++++++++++++
 2 files changed, 17 insertions(+), 1 deletion(-)

diff --git a/packages/ingest-core/src/index.ts b/packages/ingest-core/src/index.ts
index de6652d..c08b7bd 100644
--- a/packages/ingest-core/src/index.ts
+++ b/packages/ingest-core/src/index.ts
@@ -195,7 +195,7 @@ export {
   PATH_MAP_RELATIVE_PATH,
   PATH_MAP_SCHEMA_VERSION,
 } from "#src/path-map.ts";
-export type { PathMap } from "#src/path-map.ts";
+export type { PathMap, PathMapUnitEntry } from "#src/path-map.ts";
 export type { ScanManifest, ScanManifestEntry, ScanManifestSummary, ScanEntryKind } from "#src/scan-manifest.ts";
 export { writeEligibleFiles, ELIGIBLE_FILES_RELATIVE_PATH } from "#src/eligible-files.ts";
 export type { EligibleFilesDocument, WriteEligibleFilesInput } from "#src/eligible-files.ts";
diff --git a/packages/ingest-core/src/path-map.ts b/packages/ingest-core/src/path-map.ts
index 580ac1a..8b02ae2 100644
--- a/packages/ingest-core/src/path-map.ts
+++ b/packages/ingest-core/src/path-map.ts
@@ -17,6 +17,16 @@ import type { MetaPaths } from "#src/types/meta-paths.ts";
 export const PATH_MAP_RELATIVE_PATH = "path-map.json";
 export const PATH_MAP_SCHEMA_VERSION = 1;
 
+/** One code unit's identity + on-disk location, recorded so `unit → file` is an explicit lookup. */
+export interface PathMapUnitEntry {
+  /** `metaId(qualifiedName)` — the unit's dir name under `<file|big-file>-analysis/<fileMetaId>/codeUnits/`. */
+  unitHash: string;
+  qualifiedName: string;
+  unitId: string;
+  /** Analysis window for a big-file unit (1-based); `null` for a small file. Not part of the storage path. */
+  chunkNumber: number | null;
+}
+
 export interface PathMap {
   version: number;
   algo: "sha256";
@@ -24,6 +34,12 @@ export interface PathMap {
   files: Record<string, string>;
   /** `metaId(folderPath) → folderPath` for every ancestor folder; the repo root is `"__ROOT__" → ""`. */
   folders: Record<string, string>;
+  /**
+   * `metaId(relativePath) → units of that file` (same key as `files`). OPTIONAL: added by a post-analysis
+   * augmentation (units are unknown when `buildPathMap` runs from the scan manifest). Answers "which units
+   * belong to this file?" in O(1); each unit's records live at `<...>-analysis/<key>/codeUnits/<unitHash>/`.
+   */
+  unitsByFile?: Record<string, PathMapUnitEntry[]>;
 }
 
 /** PURE. Builds the `id → path` map for every file in the manifest plus every ancestor folder. */