From 31ae30372e647d14e22171a87d96ef1918ef586f Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Tue, 27 Oct 2026 15:01:54 +0000 Subject: [PATCH] Clarify source version evidence names --- conversion.go | 6 +-- docs/roadmap/implementation.md | 4 +- examples/consumers/layered_test.go | 4 +- facade_import_lifecycle_test.go | 6 +-- facade_sequence_version_test.go | 2 +- facade_source_version_mode_test.go | 78 +++++++++++++++--------------- lifecycle.go | 4 +- records.go | 10 ++-- records_test.go | 10 ++-- 9 files changed, 62 insertions(+), 62 deletions(-) diff --git a/conversion.go b/conversion.go index e926a7c..168b3a7 100644 --- a/conversion.go +++ b/conversion.go @@ -48,7 +48,7 @@ func fromEngineSourceInfo(value engine.SourceInfo) SourceInfo { PlacementMode: PlacementMode(engine.SourceInfoPlacementModeForFacade(value)), DestinationUnresolved: engine.SourceInfoDestinationUnresolvedForFacade(value), Layer: Layer(value.Layer), Kind: SourceKind(value.Kind), UnderlayIndex: value.UnderlayIndex, - ImportedFrom: fromEngineLocationPointer(value.ImportedFrom), VersionCheck: fromEngineSourceVersionCheck(value.VersionCheck), + ImportedFrom: fromEngineLocationPointer(value.ImportedFrom), VersionEvidence: fromEngineSourceVersionEvidence(value.VersionCheck), ImportSelections: fromEngineImportSelections(engine.SourceInfoImportSelectionsForFacade(value)), } } @@ -89,11 +89,11 @@ func toEngineImportDefaults(value ImportDefaults) engine.ImportDefaults { } } -func fromEngineSourceVersionCheck(value *engine.SourceVersionCheck) *SourceVersionCheck { +func fromEngineSourceVersionEvidence(value *engine.SourceVersionCheck) *SourceVersionEvidence { if value == nil { return nil } - return &SourceVersionCheck{ + return &SourceVersionEvidence{ Path: fromEnginePath(value.Path), Version: Version{Present: value.Version.Present, Null: value.Version.Null, Text: value.Version.Text}, Location: fromEngineLocationPointer(value.Location), Redacted: value.Redacted, diff --git a/docs/roadmap/implementation.md b/docs/roadmap/implementation.md index 809061e..12498eb 100644 --- a/docs/roadmap/implementation.md +++ b/docs/roadmap/implementation.md @@ -1,6 +1,6 @@ # Pre-v1 Public API Cleanup Implementation Plan -Status: in progress; Stage 1 is complete and Stages 2–11 are pending. +Status: in progress; Stages 1–2 are complete and Stages 3–11 are pending. Baseline: `07e4ae5d9236935389e81b207d4a8f00543fafce`. Audience: a Luna coding agent executing the stages sequentially. @@ -127,7 +127,7 @@ classification behavior are unchanged. ## Stage 2 — Rename Version Policy And Evidence -Status: pending. Implements D3. +Status: complete. Implements D3. 1. Replace root `SourceVersionModeDefault` with `SourceVersionModeMainOnly` in the same zero slot in [lifecycle.go](../../lifecycle.go). Preserve numeric diff --git a/examples/consumers/layered_test.go b/examples/consumers/layered_test.go index 9f3acfe..4802e31 100644 --- a/examples/consumers/layered_test.go +++ b/examples/consumers/layered_test.go @@ -68,7 +68,7 @@ func Example_sourceVersionAdoption() { } checks, redacted := 0, true for _, source := range result.Sources() { - if check := source.VersionCheck; check != nil { + if check := source.VersionEvidence; check != nil { checks++ redacted = redacted && check.Redacted && check.Version.Text == "" } @@ -95,7 +95,7 @@ func TestVersionedServiceModesAndMountedProtection(t *testing.T) { t.Fatalf("versioned service sources = %#v", sources) } for _, source := range sources { - check := source.VersionCheck + check := source.VersionEvidence if check == nil || check.Path.String() != "/version" || !check.Version.Present || !check.Redacted || check.Version.Text != "" { t.Fatalf("safe source version evidence = %#v", sources) diff --git a/facade_import_lifecycle_test.go b/facade_import_lifecycle_test.go index 18038be..a238134 100644 --- a/facade_import_lifecycle_test.go +++ b/facade_import_lifecycle_test.go @@ -77,8 +77,8 @@ entries: itemSource = source } } - if itemSource.VersionCheck == nil || !itemSource.VersionCheck.Version.Present || !itemSource.VersionCheck.Redacted || itemSource.VersionCheck.Version.Text != "" { - t.Fatalf("consumed header inspection = %#v", itemSource.VersionCheck) + if itemSource.VersionEvidence == nil || !itemSource.VersionEvidence.Version.Present || !itemSource.VersionEvidence.Redacted || itemSource.VersionEvidence.Version.Text != "" { + t.Fatalf("consumed header inspection = %#v", itemSource.VersionEvidence) } idInfo, ok := result.Metadata().Lookup(Keys("services", "records").Index(0).Key("id")) if !ok || len(idInfo.Origin.Locations) != 1 || filesByID[idInfo.Origin.Locations[0].SourceID] != "bundle/config/records/helper.yml" { @@ -129,7 +129,7 @@ entries: break } } - if !foundFailedItem || failedItemSource.VersionCheck == nil || failedItemSource.VersionCheck.Version.Text != "" || !failedItemSource.VersionCheck.Redacted { + if !foundFailedItem || failedItemSource.VersionEvidence == nil || failedItemSource.VersionEvidence.Version.Text != "" || !failedItemSource.VersionEvidence.Redacted { t.Fatalf("failed-load source inspection exposed or omitted header evidence: %#v", failedItemSource) } } diff --git a/facade_sequence_version_test.go b/facade_sequence_version_test.go index 63fc1d7..381837b 100644 --- a/facade_sequence_version_test.go +++ b/facade_sequence_version_test.go @@ -64,7 +64,7 @@ func TestMainVersionDecodingFollowsSequenceMovement(t *testing.T) { t.Fatal("unrelated underlay payload was treated as the main declaration") } for _, source := range loaded.Sources() { - if source.Layer == configkit.LayerBase && source.VersionCheck.Path.String() != path.String() { + if source.Layer == configkit.LayerBase && source.VersionEvidence.Path.String() != path.String() { t.Fatal("effective movement changed source-local version evidence") } } diff --git a/facade_source_version_mode_test.go b/facade_source_version_mode_test.go index 30e1b39..3787ea9 100644 --- a/facade_source_version_mode_test.go +++ b/facade_source_version_mode_test.go @@ -61,7 +61,7 @@ func TestFacadeSourceVersionEvidenceFollowsAssembledSequenceRanges(t *testing.T) } } sources := result.Sources() - check := sources[len(sources)-1].VersionCheck + check := sources[len(sources)-1].VersionEvidence if check == nil || check.Path.String() != "/records/0/version" || check.Location == nil || check.Location.SourceID != sources[len(sources)-1].ID { t.Fatalf("source-local evidence changed: %#v", check) } @@ -209,7 +209,7 @@ func TestFacadeSourceVersionEvidenceRedactsCollidingShapes(t *testing.T) { continue } foundMapping = true - if check := source.VersionCheck; check == nil || !check.Version.Present || !check.Redacted || check.Version.Text != "" { + if check := source.VersionEvidence; check == nil || !check.Version.Present || !check.Redacted || check.Version.Text != "" { t.Errorf("reverse=%v: schema-tagged header was not redacted", reverse) } } @@ -265,7 +265,7 @@ func TestFacadeSourceVersionAbsenceKeepsCompleteEvidencePath(t *testing.T) { {"unavailable index", "meta: [null, null, null, {version: main}]\n", "meta: []\n", configkit.Keys("meta").Index(3).Key("version")}, } { for _, mode := range []configkit.SourceVersionMode{configkit.SourceVersionModeIfPresent, configkit.SourceVersionModeRequired} { - var callbackEvidence *configkit.SourceVersionCheck + var callbackEvidence *configkit.SourceVersionEvidence loaded, err := configkit.LoadLayered(configkit.Input{Source: configkit.Bytes("main", []byte(test.main))}, configkit.LayeredOptions[map[string]any]{ SourceVersionMode: mode, Definition: configkit.Definition[map[string]any]{ @@ -275,7 +275,7 @@ func TestFacadeSourceVersionAbsenceKeepsCompleteEvidencePath(t *testing.T) { if !found { t.Fatal("missing callback source") } - callbackEvidence = source.VersionCheck + callbackEvidence = source.VersionEvidence return nil }, }, @@ -283,7 +283,7 @@ func TestFacadeSourceVersionAbsenceKeepsCompleteEvidencePath(t *testing.T) { Source: configkit.Bytes("underlay", []byte(test.underlay)), Destination: configkit.Keys("under"), }}}}, }) - var evidence *configkit.SourceVersionCheck + var evidence *configkit.SourceVersionEvidence if mode == configkit.SourceVersionModeRequired { var failure *configkit.LoadError if loaded != nil || !errors.As(err, &failure) { @@ -293,12 +293,12 @@ func TestFacadeSourceVersionAbsenceKeepsCompleteEvidencePath(t *testing.T) { if len(diagnostics) != 1 || diagnostics[0].Code != configkit.CodeVersionError || diagnostics[0].Path.String() != test.path.String() { t.Fatalf("%s: required diagnostics=%#v", test.name, diagnostics) } - evidence = failure.Sources()[1].VersionCheck + evidence = failure.Sources()[1].VersionEvidence } else { if err != nil { t.Fatalf("%s: %v", test.name, err) } - evidence = loaded.Sources()[1].VersionCheck + evidence = loaded.Sources()[1].VersionEvidence if callbackEvidence == nil || callbackEvidence.Path.String() != test.path.String() { t.Errorf("%s: callback path is incomplete", test.name) } @@ -365,7 +365,7 @@ func TestFacadeSourceVersionMissingHeaderDoesNotOverlapControl(t *testing.T) { if child["value"] != "good" { t.Fatal("valid sibling inheritance was not applied") } - check := loaded.Sources()[1].VersionCheck + check := loaded.Sources()[1].VersionEvidence if check == nil || check.Version.Present || check.Path.String() != path.String() { t.Fatal("optional omission evidence was not retained") } @@ -552,8 +552,8 @@ func TestFacadeSourceVersionEvidenceIsSanitizedAndDetached(t *testing.T) { if !found { t.Fatal("resolution callback could not query the acquired source") } - if callbackSource.VersionCheck == nil || !callbackSource.VersionCheck.Redacted || callbackSource.VersionCheck.Version.Text != "" { - t.Fatalf("callback source did not conservatively redact evidence: %#v", callbackSource.VersionCheck) + if callbackSource.VersionEvidence == nil || !callbackSource.VersionEvidence.Redacted || callbackSource.VersionEvidence.Version.Text != "" { + t.Fatalf("callback source did not conservatively redact evidence: %#v", callbackSource.VersionEvidence) } callbackContext, found = resolution.SourceContext("source-1") if !found || callbackContext.FS == nil || callbackContext.BaseDir != "." { @@ -568,17 +568,17 @@ func TestFacadeSourceVersionEvidenceIsSanitizedAndDetached(t *testing.T) { if err != nil || loaded == nil { t.Fatalf("LoadLayered = %#v, %v", loaded, err) } - if callbackSource.VersionCheck == nil || !callbackSource.VersionCheck.Redacted || callbackSource.VersionCheck.Version.Text != "" { - t.Fatalf("callback evidence lost its conservative snapshot: %#v", callbackSource.VersionCheck) + if callbackSource.VersionEvidence == nil || !callbackSource.VersionEvidence.Redacted || callbackSource.VersionEvidence.Version.Text != "" { + t.Fatalf("callback evidence lost its conservative snapshot: %#v", callbackSource.VersionEvidence) } - callbackSource.VersionCheck.Path = configkit.Keys("mutated-callback") - callbackSource.VersionCheck.Version.Text = canary - callbackSource.VersionCheck.Location.Line = 98 + callbackSource.VersionEvidence.Path = configkit.Keys("mutated-callback") + callbackSource.VersionEvidence.Version.Text = canary + callbackSource.VersionEvidence.Location.Line = 98 finalSources := loaded.Sources() - if len(finalSources) != 1 || finalSources[0].Path != path || finalSources[0].VersionCheck == nil { + if len(finalSources) != 1 || finalSources[0].Path != path || finalSources[0].VersionEvidence == nil { t.Fatalf("final sources = %#v", finalSources) } - check := finalSources[0].VersionCheck + check := finalSources[0].VersionEvidence if check.Path.String() != "/version" || check.Version != (configkit.Version{Present: true}) || !check.Redacted || check.Location == nil || check.Location.SourceID != finalSources[0].ID || check.Location.Line != 1 { t.Fatalf("final classified evidence = %#v", check) @@ -594,9 +594,9 @@ func TestFacadeSourceVersionEvidenceIsSanitizedAndDetached(t *testing.T) { check.Redacted = false check.Version.Text = "mutated" repeated := loaded.Sources() - if len(repeated) != 1 || repeated[0].VersionCheck.Path.String() != "/version" || - repeated[0].VersionCheck.Location.Line != 1 || !repeated[0].VersionCheck.Redacted || - repeated[0].VersionCheck.Version.Text != "" { + if len(repeated) != 1 || repeated[0].VersionEvidence.Path.String() != "/version" || + repeated[0].VersionEvidence.Location.Line != 1 || !repeated[0].VersionEvidence.Redacted || + repeated[0].VersionEvidence.Version.Text != "" { t.Fatalf("source evidence was aliased or re-read after source removal: %#v", repeated) } @@ -612,14 +612,14 @@ func TestFacadeSourceVersionEvidenceIsSanitizedAndDetached(t *testing.T) { }, }, }) - if err != nil || public == nil || len(public.Sources()) != 1 || public.Sources()[0].VersionCheck == nil { + if err != nil || public == nil || len(public.Sources()) != 1 || public.Sources()[0].VersionEvidence == nil { t.Fatalf("unclassified source evidence = %#v, %v", public, err) } - if got := public.Sources()[0].VersionCheck; got.Redacted || got.Version.Text != publicText || !got.Version.Present { + if got := public.Sources()[0].VersionEvidence; got.Redacted || got.Version.Text != publicText || !got.Version.Present { t.Fatalf("unclassified evidence = %#v", got) } - if publicCallback.VersionCheck == nil || !publicCallback.VersionCheck.Redacted || publicCallback.VersionCheck.Version.Text != "" { - t.Fatalf("unclassified callback evidence was not initially conservative: %#v", publicCallback.VersionCheck) + if publicCallback.VersionEvidence == nil || !publicCallback.VersionEvidence.Redacted || publicCallback.VersionEvidence.Version.Text != "" { + t.Fatalf("unclassified callback evidence was not initially conservative: %#v", publicCallback.VersionEvidence) } } @@ -650,7 +650,7 @@ func TestFacadeSourceVersionEvidenceOnFailedLoadsAndSyntheticSources(t *testing. if checked != 1 { t.Fatalf("main declaration checker calls = %d; error %v", checked, err) } - check := failure.Sources()[0].VersionCheck + check := failure.Sources()[0].VersionEvidence if check == nil || !check.Redacted || !check.Version.Present || check.Version.Text != "" { t.Fatalf("early acquisition evidence was not conservatively redacted: %#v; sources %#v", check, failure.Sources()) } @@ -666,14 +666,14 @@ func TestFacadeSourceVersionEvidenceOnFailedLoadsAndSyntheticSources(t *testing. t.Fatalf("malformed version error = %v", err) } sources := loadError.Sources() - if len(sources) != 1 || sources[0].VersionCheck == nil || !sources[0].VersionCheck.Redacted || - !sources[0].VersionCheck.Version.Present || sources[0].VersionCheck.Version.Text != "" || sources[0].VersionCheck.Path.String() != "/version" { + if len(sources) != 1 || sources[0].VersionEvidence == nil || !sources[0].VersionEvidence.Redacted || + !sources[0].VersionEvidence.Version.Present || sources[0].VersionEvidence.Version.Text != "" || sources[0].VersionEvidence.Path.String() != "/version" { t.Fatalf("failed-load source evidence = %#v", sources) } - sources[0].VersionCheck.Path = configkit.Keys("mutated-error") - sources[0].VersionCheck.Version.Text = "mutated" - sources[0].VersionCheck.Location.Line = 99 - if again := loadError.Sources()[0].VersionCheck; again.Path.String() != "/version" || again.Version.Text != "" || again.Location.Line == 99 { + sources[0].VersionEvidence.Path = configkit.Keys("mutated-error") + sources[0].VersionEvidence.Version.Text = "mutated" + sources[0].VersionEvidence.Location.Line = 99 + if again := loadError.Sources()[0].VersionEvidence; again.Path.String() != "/version" || again.Version.Text != "" || again.Location.Line == 99 { t.Fatalf("LoadError source evidence was aliased: %#v", again) } for _, test := range []struct { @@ -707,7 +707,7 @@ func TestFacadeSourceVersionEvidenceOnFailedLoadsAndSyntheticSources(t *testing. if strings.Contains(err.Error(), test.canary) { t.Fatalf("late failure disclosed source-version canary: %v", err) } - check := failure.Sources()[0].VersionCheck + check := failure.Sources()[0].VersionEvidence if check == nil || !check.Redacted || !check.Version.Present || check.Version.Text != "" { t.Fatalf("late-failure evidence was not conservatively redacted: %#v", check) } @@ -715,7 +715,7 @@ func TestFacadeSourceVersionEvidenceOnFailedLoadsAndSyntheticSources(t *testing. } defaultResult, err := configkit.Load(configkit.Bytes("default", []byte("version: 7\n")), configkit.Options[map[string]any]{}) - if err != nil || defaultResult == nil || len(defaultResult.Sources()) != 1 || defaultResult.Sources()[0].VersionCheck != nil { + if err != nil || defaultResult == nil || len(defaultResult.Sources()) != 1 || defaultResult.Sources()[0].VersionEvidence != nil { t.Fatalf("default source version check = %#v, %v", defaultResult, err) } @@ -728,7 +728,7 @@ func TestFacadeSourceVersionEvidenceOnFailedLoadsAndSyntheticSources(t *testing. } sawCLI := false for _, source := range withCLI.Sources() { - if source.Kind == configkit.SourceKindCLI && source.VersionCheck != nil { + if source.Kind == configkit.SourceKindCLI && source.VersionEvidence != nil { t.Fatalf("synthetic CLI source acquired declaration evidence: %#v", source) } sawCLI = sawCLI || source.Kind == configkit.SourceKindCLI @@ -764,14 +764,14 @@ func TestFacadeSourceVersionEvidencePreservesAbsenceAndNull(t *testing.T) { t.Fatalf("checker calls = %#v; absent contribution must skip while null is checked", checked) } sources := loaded.Sources() - if len(sources) != 3 || sources[1].VersionCheck == nil || sources[2].VersionCheck == nil { + if len(sources) != 3 || sources[1].VersionEvidence == nil || sources[2].VersionEvidence == nil { t.Fatalf("source version evidence = %#v", sources) } - absent := sources[1].VersionCheck + absent := sources[1].VersionEvidence if absent.Version.Present || absent.Path.String() != "/version" || absent.Location == nil || absent.Redacted { t.Fatalf("optional omission evidence = %#v", absent) } - null := sources[2].VersionCheck + null := sources[2].VersionEvidence if !null.Version.Present || !null.Version.Null || null.Version.Text != "" || null.Path.String() != "/version" { t.Fatalf("null declaration evidence = %#v", null) } @@ -865,8 +865,8 @@ func TestFacadeSourceVersionLifecycleKeepsConsumedHeadersOutOfPayloadHistory(t * t.Fatalf("consumed declarations affected effective rendering:\n%s\n%s", firstEffective.String(), secondEffective.String()) } sourcesA, sourcesB := first.Sources(), second.Sources() - if len(sourcesA) != 2 || len(sourcesB) != 2 || sourcesA[1].VersionCheck == nil || sourcesB[1].VersionCheck == nil || - sourcesA[1].VersionCheck.Version.Text != "underlay-release-a" || sourcesB[1].VersionCheck.Version.Text != "underlay-release-b" { + if len(sourcesA) != 2 || len(sourcesB) != 2 || sourcesA[1].VersionEvidence == nil || sourcesB[1].VersionEvidence == nil || + sourcesA[1].VersionEvidence.Version.Text != "underlay-release-a" || sourcesB[1].VersionEvidence.Version.Text != "underlay-release-b" { t.Fatalf("sanitized evidence did not retain distinct accepted declarations: %#v / %#v", sourcesA, sourcesB) } versionExplanation, found := first.Explain(configkit.Keys("service", "version")) diff --git a/lifecycle.go b/lifecycle.go index dc06c63..59383a0 100644 --- a/lifecycle.go +++ b/lifecycle.go @@ -44,10 +44,10 @@ const ( type SourceVersionMode uint8 const ( - // SourceVersionModeDefault preserves the existing main-version check and + // SourceVersionModeMainOnly preserves the existing main-version check and // rejects version-path contributions from imported, underlay, and overlay // payloads. - SourceVersionModeDefault SourceVersionMode = iota + SourceVersionModeMainOnly SourceVersionMode = iota // SourceVersionModeIfPresent checks each participating document that has a // declaration. A missing main declaration still reaches the checker; an // absent non-main declaration skips it. Accepted non-main declarations are diff --git a/records.go b/records.go index eadbca0..df80368 100644 --- a/records.go +++ b/records.go @@ -206,12 +206,12 @@ type SourceInfo struct { Kind SourceKind UnderlayIndex int ImportedFrom *Location - // VersionCheck is sanitized evidence for source-local declaration processing + // VersionEvidence is sanitized evidence for source-local declaration processing // in an enabled source-version load. It is nil when that processing did not - // occur, including default mode and synthetic CLI sources. During callbacks + // occur, including MainOnly mode and synthetic CLI sources. During callbacks // and failed loads, text is conservatively withheld; successful final source // records reflect completed sensitivity classification. - VersionCheck *SourceVersionCheck + VersionEvidence *SourceVersionEvidence // ImportSelections records completed optional declarations that selected no // sources, in declaration order. Paths are local to this declaring source. // Each record identifies the declaration mapping, selector, and empty outcome; @@ -250,14 +250,14 @@ type ImportSelection struct { Outcome ImportSelectionOutcome } -// SourceVersionCheck describes a source-local version declaration observed +// SourceVersionEvidence describes a source-local version declaration observed // during an enabled load. A non-nil record with Present false records observed // absence, but does not imply that a checker ran or accepted a value. Text is // empty when sensitivity classification or conservative callback-time/failed- // load redaction withholds it; Present and Null retain their meaning. Copies // returned by source queries are detached. See docs/config.md for disclosure // and lifecycle details. -type SourceVersionCheck struct { +type SourceVersionEvidence struct { Path Path Version Version Location *Location diff --git a/records_test.go b/records_test.go index d3424d3..98df0f1 100644 --- a/records_test.go +++ b/records_test.go @@ -40,7 +40,7 @@ func TestSourceInfoDestinationConversion(t *testing.T) { } } -func TestSourceVersionCheckConversion(t *testing.T) { +func TestSourceVersionEvidenceConversion(t *testing.T) { path := Keys("version") file := writeRecordConfig(t, "version: '123'\nvalue: main\n") options := engine.Options[recordConfig]{ @@ -59,10 +59,10 @@ func TestSourceVersionCheckConversion(t *testing.T) { } internal := engineSourceInfoFromLoad(t, file, "source-1", options) converted := fromEngineSourceInfo(internal) - if converted.VersionCheck == nil || converted.VersionCheck.Path.String() != path.String() || - !converted.VersionCheck.Version.Present || converted.VersionCheck.Version.Text != "123" || - converted.VersionCheck.Location == nil || converted.VersionCheck.Location.SourceID != internal.ID || converted.VersionCheck.Location.Line != 1 { - t.Fatalf("public source version check = %#v", converted.VersionCheck) + if converted.VersionEvidence == nil || converted.VersionEvidence.Path.String() != path.String() || + !converted.VersionEvidence.Version.Present || converted.VersionEvidence.Version.Text != "123" || + converted.VersionEvidence.Location == nil || converted.VersionEvidence.Location.SourceID != internal.ID || converted.VersionEvidence.Location.Line != 1 { + t.Fatalf("public source version check = %#v", converted.VersionEvidence) } }