fix(reference): separate local filesystem diagnostics from graph commitments

src/reference/ReferenceSourceReaderErrors.ts

@@ -52,18 +52,31 @@ const FILESYSTEM_ERROR_CODES = new Set([
   "EROFS",
 ]);
 
-/** Preserve actionable operating-system detail while leaving invariants visible. */
+export interface FilesystemFailureDetail {
+  /** Relocation-independent operation and parsed errno; location lives in entry.path. */
+  readonly message: string;
+  /** Exact host diagnostic, retained separately from semantic graph commitments. */
+  readonly localDiagnostic?: string;
+}
+
+/** Parse known filesystem failures once, separating semantics from host presentation. */
 export const filesystemFailureDetail = (
   cause: unknown,
   operation: string,
-): string | undefined => {
+): FilesystemFailureDetail | undefined => {
   if (!(cause instanceof Error)) return undefined;
   const code: unknown = Reflect.get(cause, "code");
-  if (code === "ENAMETOOLONG")
-    return `${operation}: ENAMETOOLONG (entry path exceeds the operating system path limit)`;
-  return typeof code === "string" && FILESYSTEM_ERROR_CODES.has(code)
-    ? `${operation}: ${cause.message}`
-    : undefined;
+  if (typeof code !== "string" || !FILESYSTEM_ERROR_CODES.has(code))
+    return undefined;
+  const message =
+    code === "ENAMETOOLONG"
+      ? `${operation}: ENAMETOOLONG (entry path exceeds the operating system path limit)`
+      : `${operation}: ${code}`;
+  const localDiagnostic = `${operation}: ${cause.message}`;
+  return {
+    message,
+    ...(localDiagnostic === message ? {} : { localDiagnostic }),
+  };
 };
 
 /** Preserve root I/O detail while separating bad selections from access failures. */
@@ -87,12 +100,13 @@ export const rootFilesystemFailure = (
 };
 
 export const entryFailure = (
-  ...[path, kind, code, message, size]: readonly [
+  ...[path, kind, code, message, size, localDiagnostic]: readonly [
     string,
     Extract<ReferenceSourceEntry, { status: "failed" }>["kind"],
     ReferenceSourceFailureCode,
     string,
     size?: number,
+    localDiagnostic?: string,
   ]
 ): ReferenceSourceEntry => ({
   status: "failed",
@@ -101,4 +115,5 @@ export const entryFailure = (
   code,
   message,
   ...(size === undefined ? {} : { size }),
+  ...(localDiagnostic === undefined ? {} : { localDiagnostic }),
 });