prod

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 7, 2026 License: Apache-2.0 Imports: 7 Imported by: 0

Documentation

Overview

Package prod computes the bootstrap production score in Go: the ontology alignment score over the reference "older" rows plus the bootstrap "chief" rows, and the seed and the two gates the bootstrap loop keeps by. It mirrors tools/house_lint/alignment.ml — the same scale, method version, penalty arithmetic and checker-output parsers — so a reading over the older rows reproduces the reference score, and it adds the per-directory chief rows (every_directory_declared, fanout_at_most_16, grammar_decision_fits_one_pick, grammar_generated_from_kinds, cli_purpose_declared, csf_only_under_csf) the loop drives to zero. The score reads no files and no environment: every input is a value, so it is testable against the reference's own vectors.

Index

Constants

View Source 
const (
	// Scale is the penalty at which the score reads one half, fixed with the
	// method version so two scores are comparable only under the same method.
	Scale = 1000
	// MethodVersion is the scoring method the reference checker measures.
	MethodVersion = 1
	// Schema versions the alignment record.
	Schema = "candace.ontology.alignment/v1"
)
View Source 
const FileName = "golden_metrics.json"

FileName is the file the merge quality gate's verdict is carried under in the state directory, and the name the ops view panel reads.

View Source 
const GateName = "csf_github_pulls_merge"

GateName is the merge quality gate's name, as the operator's ruling names it: the one gate every pull request passes through.

Variables

View Source 
var ChiefRows = []Row{
	{ID: "every_directory_declared", Kind: KindChief, Weight: 10, Blocking: true, Meaning: "every directory declares its question and options (every_directory_declared)"},
	{ID: "fanout_at_most_16", Kind: KindChief, Weight: 10, Blocking: true, Meaning: "no question offers more than 16 options (fanout_at_most_16)"},
	{ID: "grammar_decision_fits_one_pick", Kind: KindChief, Weight: 10, Blocking: true, Meaning: "every decision grammar fits one pick (grammar_decision_fits_one_pick)"},
	{ID: "grammar_generated_from_kinds", Kind: KindChief, Weight: 10, Blocking: true, Meaning: "every grammar is generated from kinds (grammar_generated_from_kinds)"},
	{ID: "cli_purpose_declared", Kind: KindChief, Weight: 10, Blocking: true, Meaning: "every CLI command declares its purpose (cli_purpose_declared)"},
	{ID: "csf_only_under_csf", Kind: KindChief, Weight: 10, Blocking: true, Meaning: "every .csf source lives under csf/ (csf_only_under_csf)"},
}

ChiefRows are the six bootstrap invariants, measured per directory: a directory is clean (in the seed) only when every one holds there. They are the chief rows the merge quality gate counts violations over — the operator ruled the gate reads "seed and violations over the chief rows only" — and the chief(H) atoms of the brief's done(Repo) rule. Each names a meter the scoreboard declares (csf/observability/scoreboard.csf).

View Source 
var Generators = []Generator{
	{ID: "gazelle", Command: "bazel run //:gazelle", Outputs: []string{"**/BUILD.bazel"}},
	{ID: "protoc", Command: "proto/generate.sh", Outputs: []string{"proto/**/*.pb.go"}},
	{ID: "sqlc", Command: "sqlc generate", Outputs: []string{"**/*.sql.go"}},
	{ID: "mockgen", Command: "go generate ./csf/...", Outputs: []string{"**/*.gen.go"}},
	{ID: "templ", Command: "pkg/widget/gen.sh", Outputs: []string{"**/*_templ.go"}},
	{ID: "csfc", Command: "csfc emit", Outputs: []string{"csf/architecture/generated/**"}},
	{ID: "language_generator", Command: "generate --root . write", Outputs: []string{
		"csf/docs/generated/**",
		"csf/compiler/language/**/*.ebnf",
		"csf/compiler/metric_compat/*_cgen.py",
		"services/ouroboros/codes/*_cgen.go",
		"docs/GLOSSARY.md",
	}},
	{ID: "api_codegen", Command: "csf/tools/codegen", Outputs: []string{
		"csf/*_cgen.go",
		"csf/*_gen.go",
		"csf/tools/codegen/generated/**",
	}},
}

Generators are the declared generators. Each names the run that reproduces its outputs and the globs those outputs match, so a file is derived by the program that owns it, regardless of the header its text carries.

View Source 
var OlderRows = []Row{
	{ID: "csfc-check", Kind: KindOlder, Weight: 10, Blocking: true, Meaning: "csfc check diagnostics against csf/architecture/architecture.csf"},
	{ID: "generated-drift", Kind: KindOlder, Weight: 10, Blocking: true, Meaning: "generated projections that differ from their source (csfc check-generated and the language generator's check)"},
	{ID: "cs-16", Kind: KindOlder, Weight: 5, Blocking: true, Meaning: "network, gRPC and PostgreSQL crossings outside ipc/"},
	{ID: "cs-15", Kind: KindOlder, Weight: 3, Blocking: false, Meaning: "go statements with no visible owner (no join and no context-driven exit)"},
	{ID: "cs-17", Kind: KindOlder, Weight: 3, Blocking: false, Meaning: "process environment reads outside runtime/config"},
	{ID: "ontology-dirs", Kind: KindOlder, Weight: 3, Blocking: false, Meaning: "directories whose role segment is not an ontology term"},
	{ID: "retired-vocabulary", Kind: KindOlder, Weight: 2, Blocking: false, Meaning: "retired ontology words in tracked READMEs"},
	{ID: "unlinked-terms", Kind: KindOlder, Weight: 1, Blocking: true, Meaning: "ontology terms in tracked READMEs without a link to their definition"},
}

OlderRows are the eight reference alignment signals, with the same ids, weights and blocking flags as tools/house_lint/alignment.ml. They are the "older" half of the score's rows.

View Source 
var Outputs = []Output{
	{ID: "gotth_bench_driver", Run: "pkg/gotth/test/memory/measure.sh", Outputs: []string{"pkg/gotth/docs/bench/data/**"}},
}

Outputs are the declared machine-written outputs. Each names the run that writes its outputs and the globs those outputs match.

View Source 
var Rows = append(append([]Row{}, ChiefRows...), OlderRows...)

Rows is the whole registry, chief rows first then older rows.

View Source 
var SourceExts = []string{".csf", ".dl"}

SourceExts are the extensions that make a file source rather than authored: the CSF and Datalog the tooling reads as its own.

Functions

func DocumentationDrift 

func DocumentationDrift(text string) (count int, present bool)

DocumentationDrift counts the files named in the language generator's drift message. The second result reports whether that message was present.

func Drift 

func Drift(text string) int

Drift counts only the CSF_GENERATED_DRIFT diagnostics.

func Equal 

func Equal(a, b Reading) bool

Equal reports whether two readings are the same measurement: the same observations and the same per-directory chief counts. It backs the loop's equal(S1, S0) fixed-point check.

func Findings 

func Findings(text string) int

Findings counts csfc diagnostics; summaries and malformed lines are not findings.

func Grew 

func Grew(before, after Reading) bool

Grew reports whether the seed grew strictly: every directory that was clean is still clean and at least one more became clean. It is the seed_grows predicate keep_if requires.

func IsSource 

func IsSource(path string) bool

IsSource reports whether a path is source: a .csf or .dl file.

func LintUnsupported 

func LintUnsupported(text string) bool

LintUnsupported detects a generator that predates the lint verb.

func Round4 

func Round4(value float64) float64

Round4 rounds to four decimal places.

func ScoreOfPenalty 

func ScoreOfPenalty(penalty int) (float64, error)

ScoreOfPenalty maps a penalty into [0, 1) with the fixed scale, exactly as the reference: a negative penalty is refused. The value is unrounded; the reference rounds only where a record is serialized.

func VocabularyCounts 

func VocabularyCounts(text string) (retired, unlinked int)

VocabularyCounts separates retired words from unlinked ontology terms in one language-generator lint run.

Types

type Classification 

type Classification struct {
	Source   []string
	Derived  []string
	Authored []string
}

Classification is the tree split three ways: the source, the derived, and the authored — the last being what a person or agent still writes.

func Classify 

func Classify(files []string) Classification

Classify splits files into source, derived and authored by the rules at the top of this file: a source file is source; a file reproduced by a declared generator, or written by a declared run and not hand-edited, is derived; the rest is authored.

func (Classification) AuthoredFamilies 

func (c Classification) AuthoredFamilies() []Family

AuthoredFamilies groups the authored files by directory, most files first and ties by directory name: the report(authored, by(family), descending) the next derivation slices read.

func (Classification) DerivedShare 

func (c Classification) DerivedShare() float64

DerivedShare is the fraction of the tree that is source or derived, over every classified file. A tree with no files is wholly derived, vacuously.

func (Classification) TopFamilies 

func (c Classification) TopFamilies(n int) []Family

TopFamilies is the first n authored families, all of them when there are fewer than n.

type Family 

type Family struct {
	// Directory is the authored file's directory, repository-relative.
	Directory string `json:"directory"`
	// Files is how many authored files the directory holds.
	Files int `json:"files"`
}

Family is a directory and how many authored files it holds: one entry of the report the next derivation slices read.

type Gate 

type Gate string

Gate is one refusal the loop applies to a candidate change. 

const (
	// GateNewViolationInSeed refuses a change that breaks a directory that was
	// clean: a chief row there rose from zero. It is refuse(new_violation_in_seed).
	GateNewViolationInSeed Gate = "new_violation_in_seed"
	// GateRowCountRises refuses a change that raises the total penalty. It is
	// refuse(row_count_rises).
	GateRowCountRises Gate = "row_count_rises"
)

type Generator 

type Generator struct {
	// ID is the generator's name.
	ID string
	// Command is the run that reproduces its outputs.
	Command string
	// Outputs are the path globs the run reproduces.
	Outputs []string
	// Authored are matching paths a person edits by hand.
	Authored []string
}

Generator is a declared generator: a tool whose run reproduces every tracked file matching one of its Outputs, byte for byte. Authored lists paths that match an Output but a person wrote by hand (reproduces_or_listed_as_authored).

type Kind 

type Kind string

Kind distinguishes the two halves of the score: the bootstrap chief rows, measured per directory, and the reference older rows, measured over the tree. 

const (
	KindChief Kind = "chief"
	KindOlder Kind = "older"
)

type MergeGate 

type MergeGate string

MergeGate is one reason the merge quality gate refuses a merge. 

const (
	// MergeGateSeedFilesFall refuses a merge that lowers the number of seed
	// files: main held more directories clean than the merge result does.
	MergeGateSeedFilesFall MergeGate = "seed_files_fall"
	// MergeGateSeedBreaks refuses a merge that adds a chief violation inside a
	// directory main's seed held clean.
	MergeGateSeedBreaks MergeGate = "seed_breaks"
	// MergeGateChiefViolationsRise refuses a merge that raises the chief
	// violation count.
	MergeGateChiefViolationsRise MergeGate = "chief_violations_rise"
	// MergeGateDerivedShareFalls refuses a merge that lowers the derived share
	// (derived.go): the merge result holds a smaller fraction of source and
	// reproduced files than main does.
	MergeGateDerivedShareFalls MergeGate = "derived_share_falls"
)

type MergeMetrics 

type MergeMetrics struct {
	SeedFilesBefore  int
	SeedFilesAfter   int
	SeedBreaks       int
	ViolationsBefore int
	ViolationsAfter  int
	// DerivedShareBefore and DerivedShareAfter are the derived share of main
	// and of the merge result (derived.go), measured by reproduction.
	DerivedShareBefore float64
	DerivedShareAfter  float64
}

MergeMetrics is the golden metrics of merging after onto main, and the decision the merge quality gate makes from them.

func Metrics 

func Metrics(main, after Reading) MergeMetrics

Metrics measures the golden metrics of merging after onto main: the seed file counts, the chief violations per side, the seed breaks — the chief rows that rose from zero inside a directory main's seed held clean — and the derived share on each side.

func (MergeMetrics) Reasons 

func (m MergeMetrics) Reasons() []MergeGate

Reasons are the merge gates the merge violates, in a fixed order: the seed files fell, the seed broke, the chief violations rose, or the derived share fell.

func (MergeMetrics) Refused 

func (m MergeMetrics) Refused() bool

Refused reports whether the merge quality gate refuses the merge.

type Observation 

type Observation struct {
	// contains filtered or unexported fields
}

Observation is one measured count or an explicit not-measured marker, so an absent checker never reads as a clean zero.

func Measured 

func Measured(count int) Observation

Measured is a signal whose checker ran.

func NotMeasured 

func NotMeasured(reason string) Observation

NotMeasured marks a signal whose checker has not landed, with the reason.

func (Observation) Contribution 

func (o Observation) Contribution(row Row) int

Contribution is weight times count, zero when not measured.

func (Observation) Count 

func (o Observation) Count() (int, bool)

Count returns the measured count and whether it was measured.

func (Observation) IsMeasured 

func (o Observation) IsMeasured() bool

IsMeasured reports whether the checker ran.

func (Observation) Reason 

func (o Observation) Reason() string

Reason returns the not-measured reason, empty when measured.

type ObservationEntry 

type ObservationEntry struct {
	Row   Row
	Value Observation
}

ObservationEntry pairs a row with its observation, mirroring the reference record's ordered (signal, observation) list: a record carries only the observations it was given.

func Entry 

func Entry(id string, observation Observation) (ObservationEntry, bool)

Entry builds an observation entry for a row id from the registry.

type Output 

type Output struct {
	// ID is the run's name.
	ID string
	// Run is the command that writes its outputs.
	Run string
	// Outputs are the path globs the run writes.
	Outputs []string
	// HandEdited are matching paths a person edited by hand.
	HandEdited []string
}

Output is a declared machine-written output: a declared run that writes every tracked file matching one of its Outputs, which no hand edits. HandEdited lists matching paths that were in fact edited by hand.

type Reading 

type Reading struct {
	Record Record
	// Chief is a directory's count for each chief row id; an absent id is zero.
	Chief map[string]map[string]int
	// Files are the tracked files of the revision, by repository-relative slash
	// path. DerivedShare classifies them; Equal and the seed gates read Chief
	// and Record only, so they ignore Files.
	Files []string
}

Reading is one measured snapshot of a repository: the global alignment record over the older rows plus the per-directory chief counts.

func (Reading) AllHold 

func (r Reading) AllHold() bool

AllHold reports whether every directory has all chief rows at zero: the chief half of the brief's done(Repo) rule.

func (Reading) AuthoredFamilies 

func (r Reading) AuthoredFamilies() []Family

AuthoredFamilies groups the revision's authored files by directory, most files first: the report(authored, by(family), descending) the next derivation slices read.

func (Reading) DerivedShare 

func (r Reading) DerivedShare() float64

DerivedShare is the share of the revision's files that are source or derived, measured by reproduction rather than the generated header a file's text carries: Classify splits Files, and DerivedShare folds the split. A reading with no files is wholly derived, vacuously.

func (Reading) Penalty 

func (r Reading) Penalty() int

Penalty adds the per-directory chief contribution to the older penalty: the score's rows are chief plus older.

func (Reading) Score 

func (r Reading) Score() (float64, error)

Score is the production score over every row, chief plus older.

func (Reading) Seed 

func (r Reading) Seed() []string

Seed is the directories where every chief row holds (count zero), sorted: the part of the repository the loop already trusts.

func (Reading) SeedFiles 

func (r Reading) SeedFiles() int

SeedFiles is how many directories are in the seed: the directories whose chief rows all hold. The gate refuses a merge that lowers it.

func (Reading) Violations 

func (r Reading) Violations() int

Violations counts the chief violations across every directory, unweighted: one chief instance is one item. The ruling counts violations "over the chief rows only", so the older observations are not counted here — this is the "chief_violations" the gate watches, distinct from Penalty, which weights each count and includes the older rows.

type Record 

type Record struct {
	Revision     string
	Dirty        bool
	CommitTime   int64
	Observations []ObservationEntry
}

Record is an alignment record over the older rows, mirroring the reference record. Observations is an ordered list of only the observations it carries.

func (Record) Complete 

func (r Record) Complete() bool

Complete reports whether every carried observation was measured.

func (Record) MarshalJSON 

func (r Record) MarshalJSON() ([]byte, error)

MarshalJSON emits the reference alignment record shape: signals in the order they are carried, a measured count as a number and a not-measured count as null with its reason.

func (Record) ObservationFor 

func (r Record) ObservationFor(id string) Observation

ObservationFor returns the observation for an older row id, defaulting to not measured when the record does not name it.

func (Record) Penalty 

func (r Record) Penalty() int

Penalty is the weighted sum of measured observations, exactly as the reference folds over its observations.

func (Record) Score 

func (r Record) Score() (float64, error)

Score is the reference score over the record's older rows.

type Refusal 

type Refusal struct {
	Gate      Gate
	Signal    string
	Directory string
	Before    int
	After     int
}

Refusal is one refused change, logged by the loop.

func Refuses 

func Refuses(before, after Reading) []Refusal

Refuses applies the two gates to a candidate change. A directory that was clean and now carries a chief violation is one refusal per chief row it broke; a rise in the total penalty is one more. An empty result is the nothing_breaks predicate keep_if requires.

type Row 

type Row struct {
	ID       string
	Kind     Kind
	Weight   int
	Blocking bool
	Meaning  string
}

Row is one scored signal.

func RowByID 

func RowByID(id string) (Row, bool)

RowByID returns the row with the given id from Rows.

type Snapshot 

type Snapshot struct {
	Gate              string  `json:"gate"`
	MainRevision      string  `json:"main_revision"`
	MergeRevision     string  `json:"merge_revision"`
	SeedFilesMain     int     `json:"seed_files_main"`
	SeedFilesMerge    int     `json:"seed_files_merge"`
	SeedBreaks        int     `json:"seed_breaks"`
	ViolationsMain    int     `json:"violations_main"`
	ViolationsMerge   int     `json:"violations_merge"`
	DerivedShareMain  float64 `json:"derived_share_main"`
	DerivedShareMerge float64 `json:"derived_share_merge"`
	// AuthoredFamilies is the merge result's authored files grouped by directory,
	// most files first: the report(authored, by(family), descending) the next
	// derivation slices read (derived.go). Its head is top_families(authored), so
	// the report names where the tree is still hand-written and which family to
	// derive next.
	AuthoredFamilies []Family    `json:"authored_families"`
	Refused          bool        `json:"refused"`
	Reasons          []MergeGate `json:"reasons"`
}

Snapshot is the merge quality gate's verdict on merging one pull request onto main: the golden metrics on each side and the gate's decision. It is the JSON the ops view panel reads.

func SnapshotOf 

func SnapshotOf(mainRevision, mergeRevision string, main, merge Reading) Snapshot

SnapshotOf measures the merge quality gate over the two readings: main and the merge result, each named by its revision. The derived shares are rounded to four places, like the score, so the record is stable. It also carries the merge result's authored families, the report the next derivation slices read.

Source Files

View all Source files

Directories

Path Synopsis
Package certificate records why a bootstrap's choices are right.
 Package certificate records why a bootstrap's choices are right.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.