internal/pkg: implementation revisions

This enables changing the behaviour of an artifact implementation without changing its IR structure. Unfortunately this changes the IR header structure resulting in many rebuilds.

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

internal/pkg/pkg.go

@@ -16,6 +16,7 @@ import (
 	"io"
 	"io/fs"
 	"maps"
+	"math"
 	"os"
 	"os/signal"
 	"path/filepath"
@@ -520,6 +521,28 @@ type FileArtifact interface {
 	Artifact
 }
 
+// RevisionArtifact is optionally implemented by an artifact that had undergone
+// internal changes affecting its behaviour while retaining its IR structure.
+type RevisionArtifact interface {
+	// Revision returns the revision number of [Artifact]. This value is always
+	// represented in the IR. An IR stream produced from the same [Kind] with
+	// differing revision is rejected.
+	//
+	// Result must remain identical across multiple invocations.
+	Revision() uint64
+
+	Artifact
+}
+
+// GetRevision returns the revision number of an [Artifact].
+func GetRevision(a Artifact) (revision uint64) {
+	revision = math.MaxUint64
+	if r, ok := a.(RevisionArtifact); ok {
+		revision = r.Revision()
+	}
+	return
+}
+
 // reportName returns a string describing [Artifact] presented to the user.
 func reportName(a Artifact, id unique.Handle[ID]) string {
 	r := Encode(id.Value())