feat(fingerprint): add hand-written projectV1 + golden vectors (PR A2)

Add the v1 projection layer beside the existing hashstructure path, additive
and not yet wired into ComputeIdentity:

- projectV1 + frozen nested sub-projectors, emitting measured fields by literal
  Go path under their frozen TOML emit-key
- canonicalizeForFingerprint: reflective nil-or-empty scalar-slice normalizer at
  the hash boundary, pruning at fingerprint:"-" edges (cycle-safe, no field
  inventory)
- fingerprint:"v1..*" tags on every measured field across the 10 fingerprinted
  structs; hazard comments on each '-'-pruned composite; Packages kept measured
- golden vectors with an append-only -update-golden guard; emission probe;
  composite-'!' placeholder gate; mandatory-tag decision test
- frozen maximalConfig vs growing emissionProbeConfig split + documented
  additive-field workflow and naming convention

No lock byte or scenario snapshot moves; hashstructure untouched.

Author: dmcilvaney

.github/instructions/go.instructions.md

@@ -98,17 +98,18 @@ description: "Instructions for working on the azldev Go codebase. IMPORTANT: Alw
     }
     ```
 
-## Component Fingerprinting — `fingerprint:"-"` Tags
+## Component Fingerprinting: version-set tags + `projectV1`
 
-Structs in `internal/projectconfig/` are hashed by `hashstructure.Hash()` to detect component changes. Fields **included by default** (safe: false positive > false negative).
+Structs in `internal/projectconfig/` feed the component fingerprint, and **every field must carry an explicit `fingerprint` tag** - an absent tag fails `TestAllFingerprintedFieldsHaveDecision`. (The live hash is still `hashstructure.Hash()`; the hand-written `projectV1` in `internal/fingerprint/project.go` is wired in parallel and replaces it at the reset.)
 
-When adding a new field to a fingerprinted struct, ask: **"Does changing this field change the build output?"**
-- **Yes** (build flags, spec source, defines, etc.) → do nothing, included automatically.
-- **No** (human docs, scheduling hints, CI policy, metadata, back-references) → add `fingerprint:"-"` to the struct tag and register the exclusion in `expectedExclusions` in `internal/projectconfig/fingerprint_test.go`.
+When adding a field to a fingerprinted struct, ask: **"Does changing this field change the build output?"**
+- **No** (human docs, scheduling hints, CI policy, metadata, back-references) → tag it `fingerprint:"-"` and register the exclusion in `expectedExclusions` in `internal/projectconfig/fingerprint_test.go`.
+- **Yes** (build flags, spec source, defines, etc.) → tag it `fingerprint:"v1..*"` (omit-if-zero) and wire it into `projectV1`: add its `emit`/sub-projector line, set it in `emissionProbeConfig`, then append a `<toml-key>-set` golden vector with `go test ./internal/fingerprint -run TestGoldenVectors -update-golden`. The golden table is append-only - never edit an existing digest. The full contract lives in `goldenConfigs`'s doc comment.
+- **Build-meaningful zero?** A field whose *zero value* changes the build (e.g. a `bool` where `false` is a deliberate setting) is tagged `fingerprint:"!v1..*"` (always-emit) and wired with `builder.emitAlways(...)`, **not** `builder.emit(...)`; it MUST get a golden vector at its zero value (the differ-from-`minimal` guard in `golden_internal_test.go` then proves it actually emits).
 
-If a parent struct field is already excluded (e.g. `Failure ComponentBuildFailureConfig ... fingerprint:"-"`), do **not** also tag the inner struct's fields — `hashstructure` skips the entire subtree.
+If a parent field is already excluded (e.g. `Failure ComponentBuildFailureConfig ... fingerprint:"-"`), do **not** tag the inner struct's fields - the excluded subtree is pruned from both the walk and `projectV1`.
 
-Run `mage unit` to verify — the guard test will catch unregistered exclusions or missing tags.
+Run `mage unit` to verify: the decision test catches a missing tag, the emission probe catches a measured-but-unemitted field, and the golden vectors catch a moved digest.
 
 ### Cmdline Returns
 

internal/fingerprint/golden_internal_test.go

@@ -0,0 +1,180 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package fingerprint
+
+import (
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"flag"
+	"fmt"
+	"os"
+	"testing"
+
+	"github.com/microsoft/azure-linux-dev-tools/internal/projectconfig"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+
+// updateGolden, when set, appends newly-named golden vectors to the frozen table.
+// It MUST NOT change an existing entry's digest - see goldenPath's header comment.
+// Bootstrap a missing table with: go test ./internal/fingerprint -run TestGoldenVectors -update-golden
+//
+//nolint:gochecknoglobals // a test flag must be a package-level var to register at init.
+var updateGolden = flag.Bool("update-golden", false, "append new golden fingerprint vectors")
+
+// goldenPath is the golden-vector file for the current content version. Each
+// version pins its own file (golden_v1.json, golden_v2.json, ...); a new version
+// adds a file rather than rewriting an existing one.
+//
+//nolint:gochecknoglobals // derived from currentContentVersion; cannot be const.
+var goldenPath = fmt.Sprintf("testdata/golden_v%d.json", currentContentVersion)
+
+// goldenConfigs is the freeze corpus for the current content version: one cutover
+// config (every measured field set) plus named edge configs the cutover case
+// cannot express at once.
+//
+// # Managing golden vectors (read before editing this map or testdata/golden_v<N>.json)
+//
+// A golden vector is a frozen (config -> digest) pair that pins a content
+// version's projection digest irreversibly. The freeze is append-only and these
+// rules are load-bearing because the encoding becomes a one-way door the moment a
+// version ships (see the lazy-schema-migration RFC):
+//
+//   - One file per content version: testdata/golden_v1.json pins v1, a future
+//     testdata/golden_v2.json pins v2, and so on. A new version ADDS its own file
+//     and never rewrites an existing one; this harness reads the file for
+//     currentContentVersion. (The future projection generator follows the same
+//     rule - it emits golden_v<N>.json for the version it adds and leaves older
+//     files untouched.)
+//   - NEVER edit an existing entry's digest in testdata/golden_v<N>.json. The
+//     -update-golden flag only APPENDS; a moved existing digest is a deliberate
+//     FATAL. If an existing digest moves, your change was NOT output-preserving for
+//     the fleet - that is a bug to fix, not a value to -update away.
+//   - cutoverFieldSet (the "maximal" vector) is FROZEN: it is a corpus config, so
+//     changing what it returns moves its pinned digest. Do not add fields to it.
+//   - emissionProbeConfig GROWS instead: it sets every measured field so the
+//     emission probe can assert each measured key is emitted. The two are split
+//     precisely because one config cannot be both frozen and growing.
+//
+// Adding an omit-if-zero field "foo" (fingerprint:"v<N>..*", no version bump):
+//  1. add the field + tag and its projectV<N> emit line;
+//  2. set foo non-zero in emissionProbeConfig (the probe fails until you do - that
+//     failure is the "you forgot to emit the new key" guard working);
+//  3. append a new named vector that sets foo in isolation, then run:
+//     go test ./internal/fingerprint -run TestGoldenVectors -update-golden
+//  4. confirm the run APPENDS ONLY - every existing digest must be byte-identical.
+//     Any movement of an existing entry is the bug, not the fix.
+//
+// NEVER retroactively measure a new field at a superseded version (e.g. editing a
+// frozen projectV<N> to read foo once v<N+1> exists). That changes the bytes that
+// version emitted in production, so every stored lock at that version becomes
+// unreproducible on replay (Problem 6) -> mass false-Stale. Omit-if-zero means no
+// pre-existing lock ever set foo, so each replays byte-identically without it; a
+// lock that later needs foo measured gets it by FORWARD migration, never by editing
+// the old version.
+//
+// Naming convention (semantic, not chronological - the date is already in git, and
+// a name must say what broke when a vector moves):
+//   - "maximal" / "minimal": the frozen baselines, never changed.
+//   - edge cases: name the property exercised ("defines-empty-value",
+//     "single-overlay", ...).
+//   - an additive field: "<toml-key>-set", one isolated vector per field.
+func goldenConfigs() map[string]projectconfig.ComponentConfig {
+	return map[string]projectconfig.ComponentConfig{
+		"maximal":             cutoverFieldSet(),
+		"minimal":             {},
+		"defines-empty-value": {Build: projectconfig.ComponentBuildConfig{Defines: map[string]string{"k": ""}}},
+		"single-overlay": {Overlays: []projectconfig.ComponentOverlay{{
+			Type: projectconfig.ComponentOverlayAddPatch, Filename: "p.patch",
+		}}},
+	}
+}
+
+// TestGoldenVectors pins the v1 projection encoding irreversibly. The expected
+// digests are append-only: a commit that changes an existing entry fails (a
+// frozen v1 vector cannot move - a new encoding is a new version, not an edit).
+func TestGoldenVectors(t *testing.T) {
+	computed := make(map[string]string)
+	for name, cfg := range goldenConfigs() {
+		computed[name] = projectionDigest(t, cfg)
+	}
+
+	// S2: every vector that sets a measured field must differ from the empty
+	// projection. A vector that collapses to `minimal` means a measured emit was
+	// dropped or mis-wired (e.g. a duplicate emit-key the global probe misses, or a
+	// '!' field that used emit instead of emitAlways and so dropped its zero value).
+	// A deliberately projected-empty vector (none today) would opt out here.
+	expectedEmptyProjection := map[string]bool{"minimal": true}
+	for name, digest := range computed {
+		if expectedEmptyProjection[name] {
+			continue
+		}
+
+		assert.NotEqualf(t, computed["minimal"], digest,
+			"golden vector %q collapsed to the empty projection - a measured emit was dropped or mis-wired", name)
+	}
+
+	frozen := loadGolden(t)
+
+	if *updateGolden {
+		for name, digest := range computed {
+			if old, ok := frozen[name]; ok && old != digest {
+				t.Fatalf("append-only violation: vector %q would change\n  from %s\n  to   %s\n"+
+					"a frozen v1 vector cannot move; introduce a new version instead", name, old, digest)
+			}
+
+			frozen[name] = digest
+		}
+
+		writeGolden(t, frozen)
+
+		return
+	}
+
+	for name, digest := range computed {
+		expected, ok := frozen[name]
+		require.Truef(t, ok, "golden vector %q is missing; bootstrap with -update-golden", name)
+		assert.Equalf(t, expected, digest, "v1 projection for %q changed - this is a frozen byte encoding", name)
+	}
+}
+
+func projectionDigest(t *testing.T, cfg projectconfig.ComponentConfig) string {
+	t.Helper()
+
+	digest := sha256.Sum256(mustProject(t, cfg))
+
+	return "sha256:" + hex.EncodeToString(digest[:])
+}
+
+func loadGolden(t *testing.T) map[string]string {
+	t.Helper()
+
+	data, err := os.ReadFile(goldenPath)
+	if os.IsNotExist(err) {
+		return make(map[string]string)
+	}
+
+	require.NoError(t, err)
+
+	golden := make(map[string]string)
+	require.NoError(t, json.Unmarshal(data, &golden))
+
+	return golden
+}
+
+func writeGolden(t *testing.T, golden map[string]string) {
+	t.Helper()
+
+	golden["_README"] = fmt.Sprintf("Frozen v%d projection digests. APPEND-ONLY: never edit an "+
+		"existing digest - a new encoding is a new content version, not an edit here. "+
+		"Management rules and the additive-field workflow live in goldenConfigs's doc "+
+		"comment in golden_internal_test.go.", currentContentVersion)
+
+	// json.Marshal emits map keys sorted, giving a stable diff.
+	data, err := json.MarshalIndent(golden, "", "  ")
+	require.NoError(t, err)
+
+	require.NoError(t, os.WriteFile(goldenPath, append(data, '\n'), 0o644)) //nolint:gosec // golden fixture, not a secret.
+}

internal/fingerprint/project.go

@@ -0,0 +1,87 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package fingerprint
+
+import (
+	"fmt"
+	"reflect"
+	"strings"
+
+	"github.com/microsoft/azure-linux-dev-tools/internal/projectconfig"
+)
+
+// currentContentVersion is the highest content version that exists. The reset
+// establishes v1, so projectV1 is the current (and only) projection and the tag
+// parser rejects any field that references a future version.
+const currentContentVersion = 1
+
+// FingerprintedStructTypes returns every struct type whose fields participate in
+// the component fingerprint. It is the single source of truth that both the
+// mandatory-tag decision test (`projectconfig.TestAllFingerprintedFieldsHaveDecision`)
+// and the emission probe (`measuredLeafEmitKeys`) walk - keeping it in one
+// exported place is what stops those two walks from drifting silently (a struct
+// dropped from one but not the other would weaken coverage with no failure).
+//
+// It is hand-maintained until the projection generator (which would derive it
+// from projectV1 directly) lands. When you add a new struct type to the
+// fingerprinted graph, add it here - and nowhere else.
+func FingerprintedStructTypes() []reflect.Type {
+	return []reflect.Type{
+		reflect.TypeFor[projectconfig.ComponentConfig](),
+		reflect.TypeFor[projectconfig.ComponentBuildConfig](),
+		reflect.TypeFor[projectconfig.CheckConfig](),
+		reflect.TypeFor[projectconfig.PackageConfig](),
+		reflect.TypeFor[projectconfig.ComponentOverlay](),
+		reflect.TypeFor[projectconfig.SpecSource](),
+		reflect.TypeFor[projectconfig.DistroReference](),
+		reflect.TypeFor[projectconfig.SourceFileReference](),
+		reflect.TypeFor[projectconfig.ReleaseConfig](),
+		reflect.TypeFor[projectconfig.ComponentRenderConfig](),
+	}
+}
+
+// ValidateFieldTag checks one fingerprinted struct field's tag at the current
+// content version. It enforces the mandatory-decision rule (an absent tag is an
+// error - every fingerprinted field must declare a version-set or exclusion),
+// rejects an unparseable / future-referencing tag, and requires a resolvable
+// emit-key for a measured field.
+//
+// It also gates the documented composite-'!' placeholder: a nested struct, map,
+// or slice-of-struct tagged with an always-emit range is not implemented at v1,
+// so it is rejected here rather than silently guessing an encoding.
+func ValidateFieldTag(field reflect.StructField) error {
+	set, err := parseVersionSet(field.Tag.Get(fingerprintTagName), currentContentVersion)
+	if err != nil {
+		return fmt.Errorf("field %#q:\n%w", field.Name, err)
+	}
+
+	if set.excluded {
+		return nil
+	}
+
+	if _, err := set.resolveEmitKey(tomlKeyOf(field)); err != nil {
+		return fmt.Errorf("field %#q:\n%w", field.Name, err)
+	}
+
+	if !isScalarLeaf(reflect.New(field.Type).Elem()) {
+		for _, rng := range set.ranges {
+			if rng.alwaysEmit {
+				return fmt.Errorf(
+					"field %#q: composite-'!' (always-emit nested struct, map, or slice-of-struct) "+
+						"is not implemented at v1",
+					field.Name)
+			}
+		}
+	}
+
+	return nil
+}
+
+// tomlKeyOf returns the field's bare toml key (the part before the first comma),
+// or "" when there is no toml tag.
+func tomlKeyOf(field reflect.StructField) string {
+	key, _, _ := strings.Cut(field.Tag.Get("toml"), ",")
+
+	return key
+}