diff --git a/packages/cli/src/producer/generate.ts b/packages/cli/src/producer/generate.ts
index 9ac54b4..3bdf871 100644
--- a/packages/cli/src/producer/generate.ts
+++ b/packages/cli/src/producer/generate.ts
@@ -298,6 +298,8 @@ export async function generateWorkspaceJson(
   //
   // The reason itself was already being computed and thrown away — the
   // diagnostics object exists for exactly this and was not passed.
+  // The diagnostics object is passed rather than defaulted: the refusal reason
+  // is computed inside the mining pass and would otherwise be discarded there.
   const refreshDiagnostics: { refusal?: string } = {};
   const minedHistory =
     options.mineHistory === true ? await mineHistoryBlock(resolvedRoot, refreshDiagnostics) : undefined;
diff --git a/packages/mining-core/src/project.ts b/packages/mining-core/src/project.ts
index 55bb2fc..91fbb02 100644
--- a/packages/mining-core/src/project.ts
+++ b/packages/mining-core/src/project.ts
@@ -85,6 +85,8 @@ export type ProjectionResult =
  * spelling a producer is permitted to write, which is what makes two
  * independent producers byte-comparable.
  */
+// `compareUtf8`, never bare `<`: the two disagree above the BMP and the emitted
+// bytes are what a second producer is compared against.
 function canonicalPair(files: readonly [string, string]): [string, string] {
   return compareUtf8(files[0], files[1]) <= 0 ? [files[0], files[1]] : [files[1], files[0]];
 }