internal/pkg/ir: document reason for avoiding ident cache

This got brought up earlier today as a potential optimisation. This change documents why it is not viable, and hopefully clears up some performance implications of using IRDecoder, namely that its decoding costs do not amortise.

Signed-off-by: Ophestra <cat@gensokyo.uk>

internal/pkg/ir.go

@@ -310,6 +310,13 @@ type (
 	// verbose logging is enabled. Artifacts may only depend on artifacts
 	// previously described in the IR stream.
 	//
+	// IRDecoder rejects an IR stream on the first decoding error, it does not
+	// check against nonzero reserved ancillary data or incorrectly ordered or
+	// redundant unstructured dependencies. An invalid IR stream as such will
+	// yield [Artifact] values with identifiers disagreeing with those computed
+	// by IRDecoder. For this reason, IRDecoder does not access the ident cache
+	// to avoid putting [Cache] into an inconsistent state.
+	//
 	// Methods of IRDecoder are not safe for concurrent use.
 	IRDecoder struct {
 		// Address of underlying [Cache], must not be exposed directly.