Add facade lifecycle wrappers

internal/facade/metadata.go

@@ -0,0 +1,56 @@
+package configkit
+
+import "gitea.maximumdirect.net/eric/ConfigKit/internal/engine"
+
+// Metadata provides detached effective presence/origin and chronological history
+// queries for a load. Its zero value contains no paths.
+type Metadata struct{ value engine.Metadata }
+
+// Lookup returns information for an effective path. Unknown and invalid paths
+// return false.
+func (m Metadata) Lookup(path Path) (FieldInfo, bool) {
+	value, ok := m.value.Lookup(toEnginePath(path))
+	return fromEngineFieldInfo(value), ok
+}
+
+// IsExplicit reports whether a surviving input contribution explicitly defined
+// path.
+func (m Metadata) IsExplicit(path Path) bool {
+	return m.value.IsExplicit(toEnginePath(path))
+}
+
+// History returns detached definition and resolution records for path. A record's
+// Path can be an ancestor when that container operation replaced or removed path.
+// Removed historical paths can have history even though Lookup returns false.
+// Unknown and invalid paths return nil.
+func (m Metadata) History(path Path) []Change {
+	values := m.value.History(toEnginePath(path))
+	if values == nil {
+		return nil
+	}
+	result := make([]Change, len(values))
+	for index := range values {
+		result[index] = fromEngineChange(values[index])
+	}
+	return result
+}
+
+// HistoricalPaths returns the paths observed during loading, including effective
+// paths and paths removed by overlays or recorded resolution. It includes default
+// paths and the root, but not paths that never existed. The zero Metadata returns
+// an empty slice.
+//
+// Paths are detached, unique by canonical JSON Pointer, and sorted by that
+// spelling. Like ParsePath results, numeric tokens are resolved contextually;
+// one pointer can identify a mapping key in an earlier layer and a sequence index
+// in a later one. Use History to inspect definitions and Lookup to check whether
+// a path remains effective. Enumeration exposes no configuration values and does
+// not perform another load or resolve secrets.
+func (m Metadata) HistoricalPaths() []Path {
+	values := m.value.HistoricalPaths()
+	result := make([]Path, len(values))
+	for index := range values {
+		result[index] = fromEnginePath(values[index])
+	}
+	return result
+}