Emit cache evidence for dependency search packets

Author: GTrunSec

schemas/semantic-search-packet.v1.schema.json

@@ -144,6 +144,9 @@
     "runtimeCost": {
       "$ref": "#/$defs/runtimeCost"
     },
+    "cache": {
+      "$ref": "#/$defs/cache"
+    },
     "searchSynthesis": {
       "$ref": "#/$defs/searchSynthesis"
     },
@@ -1186,6 +1189,43 @@
         }
       }
     },
+    "cache": {
+      "type": "object",
+      "description": "Provider-owned cache invalidation facts for replay-safe search packets. Providers decide which workspace files affect the packet; clients only validate and compare these hashes.",
+      "additionalProperties": false,
+      "required": [
+        "fileHashes"
+      ],
+      "properties": {
+        "fileHashes": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/fileHash"
+          }
+        },
+        "rawSourceStored": {
+          "const": false
+        }
+      }
+    },
+    "fileHash": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "path",
+        "sha256"
+      ],
+      "properties": {
+        "path": {
+          "$ref": "#/$defs/projectPath"
+        },
+        "sha256": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        }
+      }
+    },
     "queryScope": {
       "type": "object",
       "additionalProperties": false,

src/cli/semantic-search/dependency.ts

@@ -2,6 +2,10 @@
  * Packet payload builders for dependency and deps semantic-search views.
  */
 
+import crypto from "node:crypto";
+import fs from "node:fs";
+import path from "node:path";
+
 import type { TypeScriptHarnessReport } from "../../model.js";
 import {
   dependencyApiHit,
@@ -25,7 +29,12 @@ import {
   ownersForHits,
   packageRootFromSpecifier,
 } from "./hits.js";
-import type { SemanticSearchBuildOptions, SemanticSearchPacketPayload } from "./types.js";
+import type {
+  SemanticSearchBuildOptions,
+  SemanticSearchCache,
+  SemanticSearchHit,
+  SemanticSearchPacketPayload,
+} from "./types.js";
 
 export function buildDependencyPacketPayload(
   report: TypeScriptHarnessReport,
@@ -45,6 +54,7 @@ export function buildDependencyPacketPayload(
     report,
     matches.map((match) => dependencyHit(report, match)),
   );
+  const cache = dependencySearchCache(report, hits);
   return {
     header: {
       kind: "search-dependency",
@@ -64,6 +74,7 @@ export function buildDependencyPacketPayload(
     ],
     edges,
     owners,
+    ...(cache ? { cache } : {}),
     hits,
     findings: [],
     nextActions: [
@@ -134,6 +145,11 @@ export function buildDepsPacketPayload(
         ];
   const edges = matches.map((match) => dependencyEdge(report, match));
   const owners = ownersForHits(report, hits);
+  const cache = dependencySearchCache(
+    report,
+    hits,
+    dependencyWorkspaceVersionPaths(workspaceVersion.workspaceVersionSource),
+  );
   return {
     header: {
       kind: "search-deps",
@@ -174,6 +190,7 @@ export function buildDepsPacketPayload(
           ],
     edges,
     owners,
+    ...(cache ? { cache } : {}),
     hits,
     findings: [],
     nextActions:
@@ -222,3 +239,59 @@ export function buildDepsPacketPayload(
     ],
   };
 }
+
+function dependencySearchCache(
+  report: TypeScriptHarnessReport,
+  hits: readonly SemanticSearchHit[],
+  extraPaths: readonly string[] = [],
+): SemanticSearchCache | undefined {
+  const paths = new Set<string>();
+  for (const hit of hits) {
+    paths.add(hit.location.path);
+  }
+  for (const extraPath of extraPaths) {
+    paths.add(extraPath);
+  }
+  const fileHashes = [...paths].sort().flatMap((relativePath) => {
+    const fileHash = hashWorkspaceFile(report.reasoningTree.projectRoot, relativePath);
+    return fileHash === undefined ? [] : [fileHash];
+  });
+  if (fileHashes.length === 0) return undefined;
+  return { fileHashes, rawSourceStored: false };
+}
+
+function dependencyWorkspaceVersionPaths(
+  source: "package-lock" | "package-json" | undefined,
+): readonly string[] {
+  switch (source) {
+    case "package-lock":
+      return ["package-lock.json"];
+    case "package-json":
+      return ["package.json"];
+    default:
+      return [];
+  }
+}
+
+function hashWorkspaceFile(
+  projectRoot: string,
+  relativePath: string,
+): { readonly path: string; readonly sha256: string } | undefined {
+  const normalizedPath = relativePath.split(path.sep).join("/");
+  if (!isSafeRelativePath(normalizedPath)) return undefined;
+  const root = path.resolve(projectRoot);
+  const absolutePath = path.resolve(root, normalizedPath);
+  if (absolutePath !== root && !absolutePath.startsWith(`${root}${path.sep}`)) {
+    return undefined;
+  }
+  if (!fs.existsSync(absolutePath) || !fs.statSync(absolutePath).isFile()) {
+    return undefined;
+  }
+  const sha256 = crypto.createHash("sha256").update(fs.readFileSync(absolutePath)).digest("hex");
+  return { path: normalizedPath, sha256 };
+}
+
+function isSafeRelativePath(value: string): boolean {
+  if (value === "" || value.startsWith("/") || value.includes("\0")) return false;
+  return value.split("/").every((segment) => segment !== "" && segment !== "." && segment !== "..");
+}

src/cli/semantic-search/packet-base.ts

@@ -65,6 +65,7 @@ export function basePacket(
     ...(packet.avoidNextActions ? { avoidNextActions: packet.avoidNextActions } : {}),
     ...(options.runtimeCost ? { runtimeCost: options.runtimeCost } : {}),
     ...(packet.runtimeCost ? { runtimeCost: packet.runtimeCost } : {}),
+    ...(packet.cache ? { cache: packet.cache } : {}),
     header: packet.header,
     ...(packet.inputDetection ? { inputDetection: packet.inputDetection } : {}),
     ...(packet.packages ? { packages: packet.packages } : {}),

src/cli/semantic-search/types.ts

@@ -68,6 +68,7 @@ export interface SemanticSearchPacket {
   readonly searchSynthesis?: SemanticSearchSynthesis;
   readonly avoidNextActions?: readonly SemanticSearchAvoidNextAction[];
   readonly runtimeCost?: SemanticSearchRuntimeCost;
+  readonly cache?: SemanticSearchCache;
   readonly header: SemanticSearchHeader;
   readonly inputDetection?: SemanticSearchInputDetection;
   readonly packages?: readonly SemanticSearchFact[];
@@ -94,6 +95,7 @@ export interface SemanticSearchPacketPayload {
   readonly searchSynthesis?: SemanticSearchSynthesis;
   readonly avoidNextActions?: readonly SemanticSearchAvoidNextAction[];
   readonly runtimeCost?: SemanticSearchRuntimeCost;
+  readonly cache?: SemanticSearchCache;
   readonly nodes: readonly SemanticSearchNode[];
   readonly edges: readonly SemanticSearchEdge[];
   readonly owners: readonly SemanticSearchOwner[];
@@ -254,6 +256,16 @@ export interface SemanticSearchRuntimeCost {
   readonly fields?: SemanticSearchFields;
 }
 
+export interface SemanticSearchCache {
+  readonly fileHashes: readonly SemanticSearchFileHash[];
+  readonly rawSourceStored?: false;
+}
+
+export interface SemanticSearchFileHash {
+  readonly path: string;
+  readonly sha256: string;
+}
+
 export type SemanticSearchFieldValue =
   | string
   | number

tests/unit/cli_dependency_search.test.ts

@@ -219,6 +219,10 @@ test("CLI searches external dependency usage", () => {
         readonly versionScope?: string;
       };
     }[];
+    readonly cache?: {
+      readonly rawSourceStored?: false;
+      readonly fileHashes: readonly { readonly path: string; readonly sha256: string }[];
+    };
   };
   assert.equal(depsPacket.method, "search/deps");
   assert.equal(depsPacket.view, "deps");
@@ -245,6 +249,15 @@ test("CLI searches external dependency usage", () => {
         hit.fields.versionScope === "current",
     ),
   );
+  assert.equal(depsPacket.cache?.rawSourceStored, false);
+  assert.deepEqual(depsPacket.cache?.fileHashes.map((fileHash) => fileHash.path).sort(), [
+    "package-lock.json",
+    "package.json",
+    "src/index.ts",
+  ]);
+  assert.ok(
+    depsPacket.cache?.fileHashes.every((fileHash) => /^[a-f0-9]{64}$/u.test(fileHash.sha256)),
+  );
 
   const mismatch = runCliCapture(["search", "deps", "react@18.0.0::jsx", "--json", "."], root);
   assert.equal(mismatch.exitCode, 0);

tests/unit/semantic_search_schema_assertions.ts

@@ -73,6 +73,9 @@ export function assertSemanticSearchPacket(
   if (packet.searchSynthesis !== undefined) {
     assertSearchSynthesis(record(packet.searchSynthesis), record(defs.searchSynthesis));
   }
+  if (packet.cache !== undefined) {
+    assertCache(record(packet.cache), record(defs.cache));
+  }
   assertArray(packet.packages, "packet.packages", (fact, context) =>
     assertFact(fact, record(defs.fact), context),
   );
@@ -179,6 +182,19 @@ function assertSearchSynthesis(searchSynthesis: JsonObject, schema: JsonObject):
   }
 }
 
+function assertCache(cache: JsonObject, schema: JsonObject): void {
+  assertSchemaObject(cache, schema, "cache");
+  assertArray(cache.fileHashes, "cache.fileHashes", (fileHash, context) => {
+    const entry = record(fileHash, context);
+    assertString(entry.path, `${context}.path`);
+    assertString(entry.sha256, `${context}.sha256`);
+    assert.match(String(entry.sha256), /^[a-f0-9]{64}$/u, `${context}.sha256 must be sha256`);
+  });
+  if (cache.rawSourceStored !== undefined) {
+    assert.equal(cache.rawSourceStored, false, "cache.rawSourceStored must be false");
+  }
+}
+
 function assertStringArray(value: unknown, context: string): void {
   if (value === undefined) return;
   assert.ok(Array.isArray(value), `${context} must be an array`);