flex-auth/tools/survey_layer_declarations.go

//go:build ignore

// Command survey_layer_declarations runs the §11 mechanical check across the
// estate rather than against flex-auth alone.
//
// Why this exists: §11 calls the layer declaration mechanically checkable, but
// every checker in the estate reads only its own file. A check that cannot
// disagree with anyone has not been run. FLEX-WP-0030 B1 was found by an ad-hoc
// shell survey, which is the same defect in a different costume — a finding
// nobody can reproduce is an assertion. This makes it a command.
//
// It checks ONE property: whether each layer: value sits in the §3 vocabulary
// as written, case-sensitively. It does not apply flex-auth's own declaration
// rules to any other repository, and it does not grade anyone: §11 is explicit
// that a layer stated about a repository by another repository is not a
// declaration.
//
//	go run tools/survey_layer_declarations.go --root ~ [--json out.json]
package main

import (
	"encoding/json"
	"flag"
	"fmt"
	"os"
	"os/user"
	"path/filepath"
	"sort"
	"strings"

	"github.com/netkingdom/flex-auth/internal/layer"
)

// Security-relevant counterparts from docs/conformance/boundaries-review.md.
var counterparts = []string{
	"approval-engine", "audit-core", "flex-auth", "gate-house", "key-cape",
	"kings-guard", "maturity-engine", "net-kingdom", "ops-mason", "ops-warden",
	"secrets-engine", "tenant-engine", "user-engine", "zone-engine",
}

func filterRows(rows []layer.SurveyRow, keep []string) []layer.SurveyRow {
	in := map[string]bool{}
	for _, r := range keep {
		in[r] = true
	}
	var out []layer.SurveyRow
	for _, r := range rows {
		if in[r.Repo] {
			out = append(out, r)
		}
	}
	return out
}

func main() {
	root := flag.String("root", "", "directory holding the repositories (default: home)")
	jsonOut := flag.String("json", "", "write a receipt to this path")
	catalogOnly := flag.Bool("catalog-only", false, "range over the §4 catalog rows alone, the set §11's obligations bind")
	flag.Parse()

	dir := *root
	if dir == "" {
		u, err := user.Current()
		if err != nil {
			fail(err)
		}
		dir = u.HomeDir
	}

	rows, err := layer.SurveyDeclarations(dir, counterparts)
	if err != nil {
		fail(err)
	}

	// §11 as amended by A11: a run MUST state its scope. A run over §4 and a
	// run over every repository carrying a declaration answer different
	// questions, and a report that does not say which it did cannot be acted
	// on. This survey is estate-wide by construction — it was built to disagree
	// with other repositories' checkers — so it says so and reports
	// non-catalogued repositories as volunteers rather than as findings.
	scope := layer.EstateScope(counterparts)
	if *catalogOnly {
		scope = layer.CatalogScope(counterparts)
		rows = filterRows(rows, scope.Repos)
	}

	fmt.Print(layer.FormatSurvey(scope, rows))

	spellings := layer.Spellings(rows)
	undeclared := layer.Undeclared(rows)

	fmt.Printf("\n%d counterparts surveyed, %d declared, %d undeclared.\n",
		len(rows), len(rows)-len(undeclared), len(undeclared))

	keys := make([]string, 0, len(spellings))
	for k := range spellings {
		keys = append(keys, k)
	}
	sort.Strings(keys)

	fmt.Printf("\nSpellings of layer: (%d distinct)\n", len(keys))
	for _, k := range keys {
		fmt.Printf("  %-10s %s\n", k, strings.Join(spellings[k], ", "))
	}

	if len(undeclared) > 0 {
		fmt.Printf("\nNo machine-readable declaration (§11 B2): %s\n", strings.Join(undeclared, ", "))
	}

	disagree := layer.SelfDisagreeing(rows)
	if len(disagree) > 0 {
		fmt.Printf("\nRepositories whose two §11 forms disagree (§11 B1): %d\n", len(disagree))
		for _, r := range disagree {
			fmt.Printf("  %-18s INTENT.md=%-8q %s=%q\n", r.Repo, r.Intent.Layer, r.File.Source, r.File.Layer)
		}
		fmt.Println("\nRuled (GH-DEC-2026-017 §1): INTENT.md governs; a layer.yaml is a derived")
		fmt.Println("artifact and MUST agree. The disagreement is still reported, because")
		fmt.Println("precedence says which value is the answer, not that the disagreement")
		fmt.Println("did not happen. Rows marked 'spelling only' name the same layer.")
	}

	var offVocab []string
	for _, r := range rows {
		for _, f := range []layer.Form{r.Intent, r.File} {
			if f.Found && !f.InVocabulary {
				offVocab = append(offVocab, fmt.Sprintf("%s=%q", f.Source, f.Layer))
			}
		}
	}
	if len(offVocab) > 0 {
		fmt.Printf("\nOutside the closed §3 vocabulary (four tokens, case folded): %s\n", strings.Join(offVocab, ", "))
	}

	if vol := layer.VolunteerDeclarations(rows); len(vol) > 0 {
		fmt.Printf("\nDeclared voluntarily, outside §4 catalog scope — welcome, and NOT a §11\nnon-conformance: %s\n", strings.Join(vol, ", "))
	}

	if *jsonOut != "" {
		receipt := map[string]any{
			"derived_at":       "run time",
			"scope":            scope,
			"root":             dir,
			"rows":             rows,
			"spellings":        spellings,
			"undeclared":       undeclared,
			"off_vocab":        offVocab,
			"self_disagreeing": disagree,
			"volunteers":       layer.VolunteerDeclarations(rows),
			"checks_only":      "the closed four-token §3 vocabulary, ASCII case folded per GH-DEC-2026-017 §2; no flex-auth house rules applied to peers",
		}
		b, err := json.MarshalIndent(receipt, "", "  ")
		if err != nil {
			fail(err)
		}
		if err := os.WriteFile(filepath.Clean(*jsonOut), append(b, '\n'), 0o644); err != nil {
			fail(err)
		}
		fmt.Printf("\nReceipt: %s\n", *jsonOut)
	}
}

func fail(err error) {
	fmt.Fprintln(os.Stderr, "survey:", err)
	os.Exit(1)
}