refactor!: enforce canonical evidence and provider boundaries

Deliver complete Evidence directly through MCP with required nullable analysis profiles and immutable per-server delivery settings. Bind selected environments at construction and require typed cleanup outcomes with retained retry ownership.

Remove test-only routing, duplicate session and snapshot metadata, producer-field repairs, and ambiguous provider arguments. Separate artifact byte identity from occurrence classification and retain typed source-map and partial native facts across CLI, MCP, and verifier consumers.

BREAKING CHANGE: obsolete Evidence envelopes, session aliases, incomplete snapshots, and missing normalized producer facts are no longer accepted.

src/domain/javascript/javascriptSourceMapPaths.ts

@@ -1,47 +1,104 @@
 import { posix } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 
-interface SourceMapPath {
-  readonly value: string;
-  readonly scope: "artifact-relative" | "suffix";
-}
+import { z } from "zod";
+
+/** Map-scoped source declaration and its path interpretation for matching. */
+export const javascriptSourceMapReferenceSchema = z.strictObject({
+  source_name: z.string(),
+  source_root: z.string().nullable(),
+  map_path: z.string().min(1),
+  resolution: z.discriminatedUnion("kind", [
+    z.strictObject({
+      kind: z.enum(["artifact-relative", "suffix"]),
+      path: z.string().min(1),
+    }),
+    z.strictObject({
+      kind: z.literal("unresolved"),
+      reason: z.string().min(1),
+    }),
+  ]),
+});
+
+/** Typed source-map context retained through graph serialization. */
+export type JavaScriptSourceMapReference = z.infer<
+  typeof javascriptSourceMapReferenceSchema
+>;
+
+/** Interpret a declaration once at the source-map ingestion boundary. */
+export const resolveJavaScriptSourceMapReference = (
+  sourceName: string,
+  sourceRoot: string | null,
+  mapPath: string,
+): JavaScriptSourceMapReference => {
+  // TraceMap's producer prefixes sourceRoot before resolving the URL reference.
+  const reference = `${sourceRoot ? `${sourceRoot}/` : ""}${sourceName}`;
+  return {
+    source_name: sourceName,
+    source_root: sourceRoot,
+    map_path: mapPath,
+    resolution: resolveJavaScriptSourceMapPath(reference, mapPath),
+  };
+};
 
 /** Resolve a source-map URL reference without changing its recorded identity. */
-export const resolveJavaScriptSourceMapPath = (
+const resolveJavaScriptSourceMapPath = (
   source: string,
-  mapPath?: string,
-): SourceMapPath | null => {
+  mapPath: string,
+): JavaScriptSourceMapReference["resolution"] => {
   const portable = source.replaceAll("\\", "/");
   const windowsPath = /^[a-z]:\//iu.test(portable) || source.startsWith("\\\\");
   // Preserve parent traversal rather than letting URL resolution clamp at '/'.
   const anchor = `/${"source/".repeat(portable.split("/").length + 1)}`;
   const directory = posix.join(
     anchor,
-    posix.dirname(mapPath?.replaceAll("\\", "/") ?? "."),
+    posix.dirname(mapPath.replaceAll("\\", "/")),
   );
   const base = pathToFileURL(`${directory}/`, { windows: false });
   const absolute = windowsPath ? windowsFileUrl(source) : URL.parse(source);
   const resolved = windowsPath ? absolute : URL.parse(source, base);
-  if (
-    resolved === null ||
-    !resolved.pathname.startsWith("/") ||
-    resolved.pathname.endsWith("/")
-  )
-    return null;
+  if (resolved === null)
+    return {
+      kind: "unresolved",
+      reason: "Source reference is not a valid URL or filesystem path.",
+    };
+  if (!resolved.pathname.startsWith("/"))
+    return {
+      kind: "unresolved",
+      reason:
+        "Source reference uses a non-hierarchical URL without a file pathname.",
+    };
+  if (resolved.pathname.endsWith("/"))
+    return {
+      kind: "unresolved",
+      reason: "Source reference names a directory rather than a file.",
+    };
+  // Encoded separators must not manufacture a different filesystem hierarchy.
+  if (/%(?:2f|5c)/iu.test(resolved.pathname))
+    return {
+      kind: "unresolved",
+      reason: "Source reference contains an encoded path separator.",
+    };
   const relative =
     absolute === null
       ? !portable.startsWith("/")
       : absolute.href !== resolved.href;
   const path = decodedUrlPath(resolved);
-  if (path === null) return null;
+  if (path === null)
+    return {
+      kind: "unresolved",
+      reason:
+        "Source reference has malformed URL encoding or an invalid file URL.",
+    };
   const value = relative
     ? posix.relative(anchor, path)
     : path.replace(/^\/+/, "");
-  if (value === "" || value === ".." || value.startsWith("../")) return null;
-  return {
-    value,
-    scope: relative && mapPath !== undefined ? "artifact-relative" : "suffix",
-  };
+  if (value === "" || value === ".." || value.startsWith("../"))
+    return {
+      kind: "unresolved",
+      reason: "Source reference resolves outside the inventoried artifact.",
+    };
+  return { path: value, kind: relative ? "artifact-relative" : "suffix" };
 };
 
 const windowsFileUrl = (path: string): URL | null => {
@@ -54,8 +111,6 @@ const windowsFileUrl = (path: string): URL | null => {
 };
 
 const decodedUrlPath = (url: URL): string | null => {
-  // Encoded separators must not manufacture a different filesystem hierarchy.
-  if (/%(?:2f|5c)/iu.test(url.pathname)) return null;
   try {
     if (url.protocol === "file:")
       return fileURLToPath(url, {