scan

type Breakdown struct {
	Total  int                       `json:"total"`
	Counts map[probe.Verdict]int     `json:"counts"`
	Rates  map[probe.Verdict]float64 `json:"rates"`
}

type NameIssue struct {
	Count  int      `json:"count"`
	Sample []string `json:"sample,omitempty"`
}

type NameIssues struct {
	// BadCharset counts names containing a character outside
	// nameCharsetRe (for example an uppercase letter or a space).
	BadCharset NameIssue `json:"badCharset"`
	// BadShape counts names that are not exactly one "/" splitting a
	// non-empty namespace segment (containing at least one ".") from a
	// non-empty local segment, with neither segment starting with ".".
	BadShape NameIssue `json:"badShape"`
	// CaseCollisions counts names that are distinct but identical to
	// another name in this run once lowercased, which would collide as
	// the same file. An exact (case-sensitive) repeat of the same name is
	// not a collision by itself; registry.Drain already dedupes those
	// before validateNames ever sees the list.
	CaseCollisions NameIssue `json:"caseCollisions"`
}

type NamespaceDrift struct {
	Namespace   string  `json:"namespace"`
	Servers     int     `json:"servers"`
	Signal      string  `json:"signal"` // the signal that moved furthest
	PreviousPct float64 `json:"previousPct"`
	CurrentPct  float64 `json:"currentPct"`
	DeltaPoints float64 `json:"deltaPoints"`

	// The second reading. Reprobed is how many were actually re-probed;
	// Agreed/Changed count those whose signal read the same or differently the
	// second time, and NoAnswer those the re-probe could not reach at all.
	// NoAnswer is absence of evidence and is never counted as either.
	Reprobed int `json:"reprobed"`
	Agreed   int `json:"agreed"`
	Changed  int `json:"changed"`
	NoAnswer int `json:"noAnswer"`
}

type Options struct {
	// Out is the output directory. Required. RecordsFile and SummaryFile are
	// written inside it.
	Out string
	// Limit caps how many servers are drained from the registry. 0 means the
	// whole registry.
	Limit int
	// Concurrency is the worker pool size. <= 0 falls back to
	// DefaultConcurrency.
	Concurrency int
	// Timeout bounds one server's full probe set. <= 0 falls back to
	// DefaultTimeout.
	Timeout time.Duration
	// Progress receives one line per completed server ("1234/13886 name
	// verdict"), plus a startup line noting how many were already recorded.
	// A nil Progress disables progress reporting.
	Progress io.Writer

	// Compare is a previous census directory (or its records.jsonl). Given
	// one, a second pass re-probes every namespace whose aggregate signals
	// moved against that edition and records what it finds, so a transient
	// outage inside a long scan window shows up as a dated observation about
	// one operator instead of a trend in a published rate. Empty disables it.
	Compare string
	// ReprobeThreshold, ReprobeMinServers and ReprobeMaxServers tune that
	// pass; each falls back to its DefaultReprobe* constant when <= 0.
	ReprobeThreshold  float64
	ReprobeMinServers int
	ReprobeMaxServers int
}

type RecordsManifest struct {
	SchemaVersion string            `json:"schemaVersion"`
	Algorithm     string            `json:"algorithm"`
	Shards        int               `json:"shards"`
	Total         int               `json:"total"`
	Files         []RecordsShard    `json:"files"`
	Namespaces    map[string]string `json:"namespaces"`
}

type RecordsShard struct {
	File  string `json:"file"`
	Count int    `json:"count"`
}

type ReprobeReport struct {
	ComparedTo      string  `json:"comparedTo"`
	ThresholdPoints float64 `json:"thresholdPoints"`
	MinServers      int     `json:"minServers"`
	MaxServers      int     `json:"maxServers"`
	StartedAt       string  `json:"startedAt"`
	FinishedAt      string  `json:"finishedAt"`
	Candidates      int     `json:"candidates"`
	// Truncated reports that MaxServers stopped the pass before every
	// candidate namespace was re-probed. Recorded rather than silently
	// dropped: a partial second pass that reads as a complete one would be a
	// false all-clear on exactly the question this pass exists to answer.
	Truncated  bool             `json:"truncated"`
	Namespaces []NamespaceDrift `json:"namespaces"`
}

type Summary struct {
	RegistryBaseURL string `json:"registryBaseUrl"`
	AkashiVersion   string `json:"akashiVersion"`
	Concurrency     int    `json:"concurrency"`
	Limit           int    `json:"limit"` // 0 means the whole registry
	StartedAt       string `json:"startedAt"`
	FinishedAt      string `json:"finishedAt"`

	// Overall is the verdict census across every server this run targeted.
	Overall Breakdown `json:"overall"`
	// Reprobe is the second-pass report, present only when Options.Compare
	// named a previous edition. Its readings live in ReprobeFile; records.jsonl
	// stays the census exactly as first observed.
	Reprobe *ReprobeReport `json:"reprobe,omitempty"`
	// Segments key the same kind of census by a defining trait. "remote"
	// (servers that declare at least one hosted remote endpoint) is the
	// headline: a reachable, conformant remote is the strongest keyless
	// liveness proof a census can gather, since its domain is verified simply
	// by being probed live over HTTPS.
	Segments map[string]Breakdown `json:"segments"`
	// NameIssues flags registry names that would not survive the planned
	// <namespace>/<name> per-server page routing (see validateNames). It is
	// a heads-up for the index build, not a scan failure: every server is
	// still probed and recorded regardless of what this reports.
	NameIssues NameIssues `json:"nameIssues"`
}