graph

type AlgorithmResults struct {
	CommunityID        map[string]int     // entity id -> community id
	Centrality         map[string]float64 // entity id -> betweenness
	PageRank           map[string]float64 // entity id -> pagerank
	GodNodes           map[string]bool
	ArticulationPoints map[string]bool
	SurpriseEndpoints  map[string]bool
	Communities        []CommunityResult
	SurpriseEdges      []SurpriseEdge
	Stats              AlgorithmStats
}

type AlgorithmStats struct {
	LouvainModularity  float64 `json:"louvain_modularity"`
	NumCommunities     int     `json:"num_communities"`
	NumGodNodes        int     `json:"num_god_nodes"`
	NumArticulationPts int     `json:"num_articulation_points"`
	NumSurpriseEdges   int     `json:"num_surprise_edges"`
	RuntimeMS          int64   `json:"runtime_ms"`
	// DenoisedCommunities is the number of raw Louvain communities that were
	// collapsed into the "ungrouped" bucket (community_id=-1) because they
	// fell below CommunityOptions.MinSize. Zero when MinSize <= 1.
	DenoisedCommunities int `json:"denoised_communities,omitempty"`
}

type BlastEntity struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Kind        string `json:"kind"`
	SourceFile  string `json:"source_file,omitempty"`
	CommunityID int    `json:"community_id"`
	HopDistance int    `json:"hop_distance"`
}

type ChangeImpact struct {
	Ref         string // ref / branch / PR label
	Communities []int  // impacted community ids (grouped only)

	// CommunityDataAvailable carries PRImpactResult.CommunityDataAvailable for
	// this ref (#6006). An empty Communities slice means "this change touched no
	// community" only when this is true; when it is false the slice is empty
	// because nothing was computed, and no conclusion about merge safety can be
	// drawn from this ref at all.
	CommunityDataAvailable bool

	// OverlayEntityCount / InferredEntityCount carry this ref's measured/deduced
	// split (#6042), so the merge-risk verdict can say whether it rests on the
	// group-algo partition or on inference from placed neighbours.
	OverlayEntityCount  int
	InferredEntityCount int
	// InferredOnlyCommunities are the subset of Communities that this ref touches
	// ONLY through inferred placements (PRImpactResult.InferredOnlyCommunityIDs).
	// A pair overlapping solely on these is a deduced conflict.
	InferredOnlyCommunities []int
}

type ChangeSet struct {
	Added    []DiffEntityEntry
	Removed  []DiffEntityEntry
	Modified []DiffEntityEntry
}

type ChangedEntity struct {
	ID          string `json:"id"`
	Name        string `json:"name"`
	Kind        string `json:"kind"`
	SourceFile  string `json:"source_file,omitempty"`
	Change      string `json:"change"`       // added | removed | modified
	CommunityID int    `json:"community_id"` // -1 when ungrouped/unknown

	// CommunitySource says HOW CommunityID was arrived at (#6042):
	// "overlay" (measured — the group-algo partition placed it), "inferred"
	// (deduced from placed neighbours, see pr_impact_infer.go), or "none" (not
	// placed at all, CommunityID is -1).
	//
	// A caller that ignores this field is reading a guess as a measurement, which
	// is the same defect class as #6006 — hence no omitempty: the label is always
	// on the wire.
	CommunitySource string `json:"community_source"`
	// CommunityInference is the provenance of an inferred placement: which signals
	// voted and how strong the deciding one was. Present only when
	// CommunitySource == "inferred". A 26-of-51 plurality and a 40-of-41 consensus
	// are both "inferred"; only this tells them apart.
	CommunityInference *CommunityInference `json:"community_inference,omitempty"`
}

type CommunityInference struct {
	// Signals that voted, primary first. Two entries means the container-or-module
	// primary and the call targets independently agreed — the strongest case.
	Signals []string `json:"signals"`
	// Support / Sample are the deciding signal's placed neighbours backing the
	// chosen community, out of those it considered.
	Support int `json:"support"`
	Sample  int `json:"sample"`
}

type CommunityOptions struct {
	// MinSize is the minimum number of nodes a community must contain to be
	// emitted as a named community. Communities smaller than MinSize have their
	// members remapped to community -1 ("ungrouped") and are dropped from the
	// CommunityResult slice. This eliminates singleton and micro-community
	// noise without affecting the graph structure or any other algorithm pass.
	//
	// Default: 5  (configurable via ~/.grafel/algorithms.json or
	// the GRAFEL_COMMUNITY_MIN_SIZE environment variable).
	//
	// Set to 1 to disable denoising (all communities emitted, matching the
	// pre-#1382 behaviour).
	MinSize int `json:"min_size"`
}

type CommunityResult struct {
	ID          int      `json:"id"`
	Size        int      `json:"size"`
	Modularity  float64  `json:"modularity"`
	TopEntities []string `json:"top_entities"`
	AutoName    string   `json:"auto_name,omitempty"`
	AgentName   string   `json:"agent_name,omitempty"`
}

type CoverageReport struct {
	// TotalProduction is the count of in-scope production entities.
	TotalProduction int `json:"total_production"`
	// CoveredProduction is the count of production entities with ≥1 TESTS edge.
	CoveredProduction int `json:"covered_production"`
	// CoveragePct is CoveredProduction/TotalProduction*100 (0 when no
	// production entities exist).
	//
	// NOTE (#4662): this is the REACH-coverage % — production entities a test
	// actually executes (CALLS the handler / executing TESTS edge / endpoint
	// credited via a reached handler). It deliberately does NOT include
	// contract-covered-only endpoints (see ContractCoveredOnly), so the headline
	// figure stays honest about what is structurally exercised by a test.
	CoveragePct float64 `json:"coverage_pct"`

	// ContractCoveredOnly is the count of production endpoints that are NOT
	// reach-covered but ARE contract-covered: an OFFLINE contract spec references
	// the endpoint's route (asserts its shape) without any test executing the
	// handler (#4662). These read as "contract-covered" rather than "untested".
	//
	// This is a SEPARATE, secondary band — it is never added into
	// CoveredProduction / CoveragePct (which remain pure reach-coverage).
	ContractCoveredOnly int `json:"contract_covered_only"`
	// ContractCoveredPct is (CoveredProduction+ContractCoveredOnly)/TotalProduction
	// *100 — the union band the UI renders behind the reach-coverage bar so the
	// gap between "executed by a test" and "shape-asserted offline" is visible.
	ContractCoveredPct float64 `json:"contract_covered_pct"`

	// TotalTests is the number of test entities found.
	TotalTests int `json:"total_tests"`
	// TotalTestsEdges is the number of TESTS relationship edges (real or
	// synthetic) that contributed to coverage.
	TotalTestsEdges int `json:"total_tests_edges"`

	// UncoveredEntities lists production entities without any TESTS edge,
	// sorted by severity (high → medium → low) then by file+name.
	UncoveredEntities []UncoveredEntity `json:"uncovered_entities"`

	// ByDirectory contains per-directory coverage statistics, sorted by
	// directory path. Only directories with ≥1 production entity are included.
	ByDirectory []DirCoverage `json:"by_directory"`

	// ByFile contains per-file coverage statistics, sorted by file path. Only
	// files with ≥1 production entity are included. Directory rollups in
	// ByDirectory are sums of the files sharing their directory, so the
	// frontend can nest files under their directory using the path segments.
	ByFile []FileCoverage `json:"by_file"`

	// ByModule contains per-module (Properties["module"]) coverage statistics.
	// Only populated when entities carry the "module" property.
	ByModule []ModuleCoverage `json:"by_module"`

	// EntitiesScanned is the total number of entities examined.
	EntitiesScanned int `json:"entities_scanned"`
	// RelationshipsScanned is the total number of relationships examined.
	RelationshipsScanned int `json:"relationships_scanned"`
}

type CrossCutEdge struct {
	FromID        string   `json:"from_id"`
	ToID          string   `json:"to_id"`
	FromName      string   `json:"from_name"`
	ToName        string   `json:"to_name"`
	Kind          string   `json:"kind"`
	Score         float64  `json:"score"`
	Reasons       []string `json:"reasons"`
	FromCommunity int      `json:"from_community"`
	ToCommunity   int      `json:"to_community"`
}

type CycleEdge struct {
	FromID string `json:"from_id"`
	ToID   string `json:"to_id"`
}

type DiffEntityEntry struct {
	ID             string   `json:"id"`
	Kind           string   `json:"kind"`
	Name           string   `json:"name"`
	SourceFile     string   `json:"source_file"`
	ModifiedFields []string `json:"modified_fields,omitempty"`
}

type DiffRelEntry struct {
	FromID string `json:"from_id"`
	ToID   string `json:"to_id"`
	Kind   string `json:"kind"`
}

type DiffResult struct {
	Group string `json:"group,omitempty"`
	Repo  string `json:"repo,omitempty"`
	RefA  string `json:"ref_a,omitempty"`
	RefB  string `json:"ref_b,omitempty"`

	Summary DiffSummary `json:"summary"`

	Entities struct {
		Added    []DiffEntityEntry `json:"added"`
		Removed  []DiffEntityEntry `json:"removed"`
		Modified []DiffEntityEntry `json:"modified"`
	} `json:"entities"`

	Relationships struct {
		Added   []DiffRelEntry `json:"added"`
		Removed []DiffRelEntry `json:"removed"`
	} `json:"relationships"`
}

type DiffSummary struct {
	EntitiesAdded        int `json:"entities_added"`
	EntitiesRemoved      int `json:"entities_removed"`
	EntitiesModified     int `json:"entities_modified"`
	RelationshipsAdded   int `json:"relationships_added"`
	RelationshipsRemoved int `json:"relationships_removed"`
	FilesChanged         int `json:"files_changed"`
}

type DirCoverage struct {
	Dir     string `json:"dir"`
	Total   int    `json:"total"`
	Covered int    `json:"covered"`
	// ContractOnly is the count of entities in this directory that are
	// contract-covered-only (shape-asserted offline, not reach-covered) (#4662).
	ContractOnly int     `json:"contract_only"`
	CoveragePct  float64 `json:"coverage_pct"`
}

type Document struct {
	Version        int               `json:"version"`
	GeneratedAt    time.Time         `json:"generated_at"`
	Repo           string            `json:"repo"`
	IndexerVersion string            `json:"indexer_version"`
	Stats          Stats             `json:"stats"`
	Entities       []Entity          `json:"entities"`
	Relationships  []Relationship    `json:"relationships"`
	Communities    []CommunityResult `json:"communities,omitempty"`
	SurpriseEdges  []SurpriseEdge    `json:"surprise_edges,omitempty"`
	AlgorithmStats *AlgorithmStats   `json:"algorithm_stats,omitempty"`

	// Phase 0 git metadata (#2088). Populated at index time by
	// internal/gitmeta.Capture. Empty/false for non-git repos or when the
	// graph was loaded from an older graph.fb written before this field was
	// added (FlatBuffers defaults to "" / false for missing fields).
	IndexedRef string `json:"indexed_ref,omitempty"`
	IndexedSHA string `json:"indexed_sha,omitempty"`
	IsWorktree bool   `json:"is_worktree,omitempty"`

	// CoverageStatus indicates whether the indexed working tree is a full
	// or partial checkout (#2181 / M4 of monorepo epic #2175).
	//
	// Values (see internal/gitmeta constants):
	//   ""        — field absent / legacy graph (treated as "full" by readers).
	//   "full"    — normal full checkout; all tracked files are present.
	//   "partial" — git sparse-checkout is active; only a subset of paths
	//               was indexed. Readers should surface a badge in the UI.
	CoverageStatus string `json:"coverage_status,omitempty"`
}

type Entity struct {
	ID            string                 `json:"id"`
	Name          string                 `json:"name"`
	QualifiedName string                 `json:"qualified_name,omitempty"`
	Kind          string                 `json:"kind"`
	Subtype       string                 `json:"subtype,omitempty"`
	SourceFile    string                 `json:"source_file"`
	StartLine     int                    `json:"start_line"`
	EndLine       int                    `json:"end_line"`
	Language      string                 `json:"language"`
	Signature     string                 `json:"signature,omitempty"`
	Tags          []string               `json:"tags,omitempty"`
	Metadata      map[string]interface{} `json:"metadata,omitempty"`

	// PH8 (#2100): content-hash pointer into the shared embedding cache.
	// When non-empty, readers load the vector from Cache instead of
	// computing it inline. Old graphs have this absent; omitempty preserves
	// byte-identical output for graphs written before PH8.
	EmbeddingRef string `json:"embedding_ref,omitempty"`

	// Pass 4 (graph algorithm) attributes. Pointers + omitempty so that
	// documents written with --skip-pass=graph-algo stay byte-identical to
	// the pre-PORT-4 schema.
	CommunityID        *int     `json:"community_id,omitempty"`
	Centrality         *float64 `json:"centrality,omitempty"`
	PageRank           *float64 `json:"pagerank,omitempty"`
	IsGodNode          bool     `json:"is_god_node,omitempty"`
	IsSurpriseEndpoint bool     `json:"is_surprise_endpoint,omitempty"`
	IsArticulationPt   bool     `json:"is_articulation_point,omitempty"`

	// Confidence overlay (Phase 1C, #2769). Value in [0.0, 1.0]; zero/unset
	// reads as 1.0 (direct AST extraction). See internal/types/confidence.go
	// for the universal taxonomy and propagation rules.
	Confidence float64 `json:"confidence,omitempty"`
	// contains filtered or unexported fields
}

type EntityCoverageResult struct {
	EntityID         string   `json:"entity_id"`
	Name             string   `json:"name"`
	Kind             string   `json:"kind"`
	SourceFile       string   `json:"source_file"`
	StartLine        int      `json:"start_line"`
	Severity         string   `json:"severity"`
	Tested           bool     `json:"tested"`
	CoveringTests    []string `json:"covering_tests"`
	CoverageFraction float64  `json:"coverage_fraction"`
	// State is the three-state coverage classification (#4662):
	// "reach" (a test executes it), "contract-only" (an offline contract spec
	// asserts its shape but nothing executes it), or "uncovered".
	State string `json:"state"`
	// ContractCovered is true when a contract spec references this entity's
	// route (shape-asserted) regardless of reach state.
	ContractCovered bool `json:"contract_covered"`
}

type EntityView interface {
	ID() string
	Kind() string
	Name() string
	QualifiedName() string
	Subtype() string
	SourceFile() string
	Language() string
	Signature() string

	// The read-only property surface below is NAME- AND SIGNATURE-IDENTICAL to
	// graph.Entity's own methods. That identity is the whole point of W2
	// (ADR-0027): *graph.Entity satisfies these for free, so migrating a
	// property-reading consumer to EntityView is a pure TYPE change — its
	// PropGet/PropLookup/PropLen/PropRange/PropsSnapshot calls compile unchanged.
	// The WRITE methods (PropSet/PropDelete) are deliberately EXCLUDED: writes are
	// cut-set and stay on the concrete type. Storage-agnostic by contract
	// (ADR-0027 §Interaction): compatible with the map-backed and []propKV
	// backings and with values aliased straight out of the mmap.
	//
	// PropGet returns the value for key, or "" if absent.
	PropGet(key string) string
	// PropLookup returns the value for key and whether it was present.
	PropLookup(key string) (string, bool)
	// PropLen returns the number of properties.
	PropLen() int
	// PropRange calls f for every key/value pair in key-sorted order, stopping
	// early if f returns false.
	PropRange(f func(k, v string) bool)
	// PropsSnapshot returns an independent copy of all properties as a map, or nil
	// if there are none. The returned map (and its strings) are safe to retain
	// past any borrow — an mmap-backed impl heap-copies the values.
	PropsSnapshot() map[string]string
}

type FileCoverage struct {
	File    string `json:"file"`
	Dir     string `json:"dir"`
	Total   int    `json:"total"`
	Covered int    `json:"covered"`
	// ContractOnly is the count of entities in this file that are
	// contract-covered-only (shape-asserted offline, not reach-covered) (#4662).
	ContractOnly int     `json:"contract_only"`
	CoveragePct  float64 `json:"coverage_pct"`
}

type FormatVersionError struct {
	// Found is the FormatVersion actually stamped on the rejected graph.fb.
	Found int
	// Required is the minimum FormatVersion this binary accepts
	// (fbversion.Version at build time).
	Required int
}

type GraphDescriptor struct {
	Kind GraphKind
	// Dir is the state dir this descriptor was resolved for.
	Dir string
	// Path is the single .fb file for GraphSingleFile (and, for GraphAbsent,
	// the flat graph.fb path that does not exist — mirroring CurrentGraphPath's
	// "return the flat path even when absent" contract). Empty for a segment-set.
	Path string
	// GenDir is the absolute graph.<gen>/ directory for GraphSegmentSet; empty
	// otherwise.
	GenDir string
	// Manifest is the parsed, validated manifest for GraphSegmentSet; nil
	// otherwise.
	Manifest *Manifest
	// Segments are the absolute seg-NNNN.fb paths (in manifest order) for
	// GraphSegmentSet; nil otherwise. Handed straight to OpenSegmentsWithRanges.
	Segments []string
}

type GraphKind int

type GraphStatsSidecar struct {
	Version            int       `json:"version"`
	ComputedAt         time.Time `json:"computed_at"`
	TotalFiles         int       `json:"total_files,omitempty"`
	TotalEntities      int       `json:"total_entities"`
	TotalRelationships int       `json:"total_relationships"`
	Communities        int       `json:"communities"`
	Modularity         float64   `json:"modularity"`
	GodNodes           int       `json:"god_nodes"`
	ArticulationPoints int       `json:"articulation_points"`
	// KindVocabularyVersion is types.KindVocabularyVersion as of the build
	// that produced the accompanying graph (#6779) — the version of the
	// entity-kind VOCABULARY the stored entities are spelled in.
	//
	// This sidecar is the only place it lives TODAY — not the only place it
	// could: the graph.fb header or graph.json could carry it, at the cost of
	// an .fbs slot (and an fbversion bump, which would auto-reindex every
	// group — precisely what this mechanism exists to avoid doing behind the
	// user's back). What is genuinely forced is that it must be stamped
	// SOMEWHERE outside the entities: nothing in the graph's own rows records
	// which vocabulary their kind strings belong to, so after a rename the old
	// graph still loads, still validates, and still answers a query for the
	// new kind with an empty result — indistinguishable from "there is nothing
	// of that kind here".
	//
	// Zero / absent means the graph was written before this field existed and
	// is therefore on an OLDER vocabulary — deliberately NOT "unknown, assume
	// fine". omitempty is safe here because 0 is never a valid stamp:
	// KindVocabularyVersion starts at 1.
	KindVocabularyVersion int `json:"kind_vocabulary_version,omitempty"`

	// RuntimeMS is the wall-clock duration of the graph-algorithm pass
	// (Pass 4: Louvain / PageRank / articulation). Its meaning is unchanged
	// since it was introduced; the extract/link phase timings below are
	// tracked separately.
	RuntimeMS int64 `json:"runtime_ms"`

	// ExtractMS is the wall-clock duration (milliseconds) of the extraction
	// phase for the index pass that produced this sidecar (#5692). Recorded so
	// `grafel feedback` and future tooling can report where indexing time goes.
	// A zero value means "unknown": the phase was not measured, or this sidecar
	// was written before the field existed (back-compat).
	//
	// The measured span differs slightly by write path: on the full-index path
	// it is scoped to the extraction pipeline (idx.Run) only; on the
	// incremental reindex path it is the whole incremental pass wall-clock
	// (manifest load + re-extract + scoped resolve + graph.fb write). Both are
	// written in-band by the same goroutine that writes this sidecar, so the
	// value is always consistent with the counts alongside it.
	//
	// It is written IN-BAND (by the reindex writer, sole owner of this file);
	// the cross-repo link timing lives in a SEPARATE link-stats.json (see
	// LinkStatsSidecar) so an unserialized link goroutine never races the
	// reindex writer on this file's count fields (#5692).
	ExtractMS int64 `json:"extract_ms,omitempty"`

	// ParseErrorCanary is the A4 per-language parse-error-node canary report
	// (#5414, epic #5359): per-language aggregate ERROR-node rates plus a
	// baseline comparison and a spike flag. The shape is the JSON marshalling
	// of treesitter.CanaryReport; kept as raw JSON here so the graph package
	// does not depend on the treesitter package. Omitted when no parse stats
	// were collected (e.g. a heuristic-only index).
	ParseErrorCanary json.RawMessage `json:"parse_error_canary,omitempty"`
	// ParseErrorSpike mirrors ParseErrorCanary.spiked at the top level so
	// dashboards / crons can read the alarm without decoding the full report.
	ParseErrorSpike bool `json:"parse_error_spike,omitempty"`

	// RenameDetectTruncated reports that the rename-detection pass (#6087) hit
	// its work budget and did NOT examine every candidate entity, so the
	// RENAMED_FROM edges in the accompanying graph are a PARTIAL result.
	//
	// This exists because the stderr warning is invisible to every
	// programmatic consumer: MCP, the dashboard and `grafel doctor` read the
	// graph, not the indexer's log. A consumer that reports "no renames" off a
	// truncated index is stating a confident wrong answer; this flag is how it
	// can tell the difference. Absent/false means the pass ran to completion
	// (or was skipped, or there was no prior graph to compare against — in all
	// of which cases no rename data was dropped).
	RenameDetectTruncated bool `json:"rename_detect_truncated,omitempty"`
	// RenameDetectAddedSkipped is how many added entities the truncated pass
	// never examined. Only meaningful when RenameDetectTruncated is true.
	RenameDetectAddedSkipped int `json:"rename_detect_added_skipped,omitempty"`
	// RenameDetectPairsSkipped is how many candidate pairs those skipped
	// entities would have contributed. Only meaningful when
	// RenameDetectTruncated is true.
	RenameDetectPairsSkipped int `json:"rename_detect_pairs_skipped,omitempty"`

	// UnsupportedExtensions counts the files this index pass SAW and dropped
	// because no extractor claims their extension, keyed by lowercased
	// extension (#6338).
	//
	// This is the one skip reason that means grafel silently indexed nothing:
	// the file is not vendored, not ignored, not binary, not quarantined and
	// did not error — no extractor was ever reached, so `doctor` had nothing
	// to report and a 670-file VB.NET codebase looked exactly like a healthy
	// index. Aggregated by extension, never per file: the originating report
	// was 672 files.
	//
	// omitempty, and never written with zero-valued entries, so a repo with
	// full extractor coverage carries no key at all and its consumers print
	// nothing.
	UnsupportedExtensions map[string]int `json:"unsupported_extensions,omitempty"`

	// RelationshipKindsScanned records that the write path that produced this
	// sidecar actually tallied the relationship kinds it serialized (#6757
	// arm C). It is the difference between "counted, found none" and "never
	// counted": with omitempty alone those two are the same bytes, and a
	// consumer reading "no problem" off a graph nothing looked at is the
	// #6534 failure exactly. A sidecar written before this field existed, or
	// by a pass whose graph write FAILED, carries false.
	//
	// The three fields below are meaningless unless this is true.
	RelationshipKindsScanned bool `json:"relationship_kinds_scanned,omitempty"`

	// RelationshipEdgesKindNotInEnum is how many relationships this index
	// WROTE whose kind is absent from BOTH relationship-kind vocabularies —
	// types.AllRelationshipKinds() and, since #6773,
	// types.AllDerivedRelationshipKinds(). Derived kinds are counted under
	// RelationshipEdgesDerivedKind below instead, never here.
	//
	// The relationship vocabulary is enforced by nothing —
	// types.IsValidRelationshipKind had zero non-test callers — so the enum
	// described an intention, not a constraint. Only the write path can see
	// the kinds that resolve at RUNTIME, and only if it says so: the same
	// reasoning as RenameDetectTruncated above — the stderr line is invisible
	// to MCP, the dashboard and `grafel doctor`, which read the graph.
	//
	// "Not in the enum" is NOT the same as "undeclared": an engine rule YAML
	// can declare a kind the Go enum omits (DECORATES, in
	// internal/engine/rules/python/frameworks/fastapi.yaml), and such a kind
	// is counted here. The field names say enum because the enum is what was
	// checked.
	//
	// Nothing is dropped and no index fails because of this. It is a
	// measurement, taken so a later decision about declaring or rejecting
	// these kinds rests on evidence.
	RelationshipEdgesKindNotInEnum int `json:"relationship_edges_kind_not_in_enum,omitempty"`
	// RelationshipDistinctKindsNotInEnum is the number of DISTINCT such
	// kinds. Never capped, so it may exceed len(RelationshipKindsNotInEnum).
	RelationshipDistinctKindsNotInEnum int `json:"relationship_distinct_kinds_not_in_enum,omitempty"`
	// RelationshipKindsNotInEnum maps each distinct kind to the number of
	// edges that carried it. A bare count would only say something is wrong;
	// the names say what. Truncated to the busiest
	// fbwriter.NonEnumKindListCap kinds so a pathological graph cannot bloat
	// this file — the two counts above stay exact.
	RelationshipKindsNotInEnum map[string]int `json:"relationship_kinds_not_in_enum,omitempty"`

	// RelationshipEdgesDerivedKind is how many relationships this index wrote
	// whose kind is in types.AllDerivedRelationshipKinds() — the DERIVED
	// (statistical) vocabulary added by #6773.
	//
	// These are declared kinds, so they are NOT counted in
	// RelationshipEdgesKindNotInEnum above. They get their own count because
	// COMMIT_COUPLED alone was 27,407 of the 27,645 edges arm C reported as
	// absent from the vocabulary — 99.1%. Declaring it removes it from that
	// count, and if nothing else recorded it, the effect of the decision
	// would be indistinguishable from deleting the measurement. Nothing about
	// these edges is wrong: a derived edge is an inference from git history
	// rather than a structural fact an extractor observed, and this is the
	// number that says how much of the graph is that.
	RelationshipEdgesDerivedKind int `json:"relationship_edges_derived_kind,omitempty"`
	// RelationshipDistinctDerivedKinds is the number of DISTINCT such kinds.
	// Never capped, so it may exceed len(RelationshipDerivedKinds).
	RelationshipDistinctDerivedKinds int `json:"relationship_distinct_derived_kinds,omitempty"`
	// RelationshipDerivedKinds maps each distinct derived kind to the number
	// of edges that carried it, truncated to the busiest
	// fbwriter.NonEnumKindListCap kinds while the two counts above stay exact.
	RelationshipDerivedKinds map[string]int `json:"relationship_derived_kinds,omitempty"`

	// EntityKindsScanned records that the write path that produced this
	// sidecar actually tallied the ENTITY kinds it serialized (#6776 arm A).
	// Same job as RelationshipKindsScanned above and for the same reason:
	// with omitempty alone, "counted, found none" and "never counted" are the
	// same bytes, and reporting a clean vocabulary off a graph nothing looked
	// at is the #6534 failure exactly. A sidecar written before this field
	// existed, or by a pass whose graph write FAILED, carries false.
	//
	// The three fields below are meaningless unless this is true.
	EntityKindsScanned bool `json:"entity_kinds_scanned,omitempty"`

	// EntitiesKindNotInEnum is how many entities this index WROTE whose kind
	// is absent from types.AllEntityKinds().
	//
	// The entity vocabulary is not enforced on the rule path at all:
	// internal/engine/detector.go copies SourcePattern.EntityType straight
	// into types.EntityRecord.Kind, so types.IsValidEntityKind is never
	// consulted and a rule YAML can mint any string it likes. #6744 ledgered
	// 532 declaration sites over 25 invalid values; this field is the other
	// half of that picture, because a declaration site that produces no
	// entity is an edit that buys nothing (#6776 arm A).
	//
	// "Not in the enum" is NOT the same as "undeclared": `Route` is declared
	// by rule YAML and counted here, because the enum is what was checked.
	//
	// Nothing is dropped and no index fails because of this. It is a
	// measurement, taken so the migration is ranked on evidence.
	EntitiesKindNotInEnum int `json:"entity_entities_kind_not_in_enum,omitempty"`
	// EntityDistinctKindsNotInEnum is the number of DISTINCT such kinds.
	// Never capped, so it may exceed len(EntityKindsNotInEnum).
	EntityDistinctKindsNotInEnum int `json:"entity_distinct_kinds_not_in_enum,omitempty"`
	// EntityKindsNotInEnum maps each distinct kind to the number of entities
	// that carried it. A bare count would only say something is wrong; the
	// names say what, and the names are what a migration is ranked by.
	// Truncated to the busiest fbwriter.NonEnumKindListCap kinds so a
	// pathological graph cannot bloat this file — the two counts above stay
	// exact.
	EntityKindsNotInEnum map[string]int `json:"entity_kinds_not_in_enum,omitempty"`
}

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

type ImpactedCommunity struct {
	CommunityID    int `json:"community_id"`
	ChangedCount   int `json:"changed_count"`    // changed entities in this community
	BlastRadiusHit int `json:"blast_radius_hit"` // downstream entities in this community
	// InferredChangedCount is how many of ChangedCount were placed here by
	// INFERENCE rather than by the overlay (#6042).
	InferredChangedCount int `json:"inferred_changed_count,omitempty"`
	// InferredOnly is true when this community appears in the impact set SOLELY
	// because of inferred placements: no overlay-placed changed entity and no
	// blast-radius entity puts it here. Such a community is a deduction, and any
	// merge-risk overlap resting on it is a deduced conflict, not a measured one.
	InferredOnly bool `json:"inferred_only,omitempty"`
}

type ImportCycle struct {
	// Members lists entity IDs that form the cycle, sorted for determinism.
	Members []string `json:"members"`
	// Edges lists the IMPORTS relationships (FromID → ToID) inside the cycle,
	// sorted for determinism.
	Edges []CycleEdge `json:"edges"`
	// WeakestLinkFromID / WeakestLinkToID identify the edge whose source has
	// the lowest PageRank — the best edge to sever to break the cycle cheaply.
	WeakestLinkFromID string `json:"weakest_link_from_id"`
	WeakestLinkToID   string `json:"weakest_link_to_id"`
	// SuggestedExtractionID is the entity inside the cycle with the highest
	// PageRank — the best candidate for extraction into a common module.
	SuggestedExtractionID string `json:"suggested_extraction_id"`
	// Size is len(Members) for fast filtering.
	Size int `json:"size"`
}

type KeyEntity struct {
	ID          string  `json:"id"`
	Name        string  `json:"name"`
	Kind        string  `json:"kind"`
	SourceFile  string  `json:"source_file,omitempty"`
	CommunityID int     `json:"community_id"`
	Degree      int     `json:"degree"`      // in+out degree (cheap centrality)
	Betweenness float64 `json:"betweenness"` // precomputed approx. betweenness
	PageRank    float64 `json:"pagerank"`    // precomputed pagerank
	Score       float64 `json:"score"`       // composite ranking score
	Reason      string  `json:"reason"`      // why this entity is a key entity
}

type KindVocabularyState string

type LinkStatsSidecar struct {
	Version    int       `json:"version"`
	ComputedAt time.Time `json:"computed_at"`
	// LinkMS is the wall-clock duration (milliseconds) of the most recent
	// cross-repo link pass for the group this repo belongs to. Zero (or an
	// absent file) means "unknown".
	LinkMS int64 `json:"link_ms"`
}

type Manifest struct {
	// FormatVersion is the manifest schema version (ManifestFormatVersion).
	FormatVersion int `json:"format_version"`
	// Segments lists every segment file in the gen dir, in read/open order.
	Segments []SegmentMeta `json:"segments"`
}

type MergeRiskPair struct {
	RefA              string `json:"ref_a"`
	RefB              string `json:"ref_b"`
	SharedCount       int    `json:"shared_community_count"`
	SharedCommunities []int  `json:"shared_communities"`

	// InferredSharedCommunities are the shared communities that at least one side
	// touches ONLY through inference (#6042 D1). The overlap on such a community
	// was not observed — it was deduced on one or both sides.
	InferredSharedCommunities []int `json:"inferred_shared_communities,omitempty"`
	// InferredOnly is true when EVERY shared community is in the list above, i.e.
	// this reported conflict is entirely a product of inference.
	//
	// The verdict-level CommunityDataInferredOnly cannot express this: a pair of
	// refs can each have measured communities (so the verdict looks measured) and
	// still overlap ONLY on an inferred one, making the reported conflict
	// manufactured while every aggregate flag reads "measured". That is the #6006
	// defect class at pair granularity, which is the granularity a merge decision
	// is actually made at.
	InferredOnly bool `json:"inferred_only"`
}

type MergeRiskResult struct {
	Pairs      []MergeRiskPair `json:"risk_pairs"`
	RefCount   int             `json:"ref_count"`
	RiskyPairs int             `json:"risky_pair_count"`

	// CommunityDataAvailable is false when ANY input ref lacked community data
	// (#6006). A zero risky_pair_count is only a "these refs do not conflict"
	// answer when this is true; when it is false the analysis did not run and the
	// empty pair list carries no safety information whatsoever.
	//
	// Deliberately conservative: one uncovered ref taints the whole result,
	// because merge risk is a property of the pair set, not of a single ref.
	CommunityDataAvailable bool `json:"community_data_available"`
	// RefsWithoutCommunityData names the refs that had no community data, sorted.
	RefsWithoutCommunityData []string `json:"refs_without_community_data,omitempty"`

	// InferredEntityCount totals the changed entities across all refs that were
	// placed by INFERENCE rather than by the group-algo overlay.
	InferredEntityCount int `json:"inferred_entity_count"`
	// CommunityDataInferredOnly is true when the analysis ran but NO ref
	// contributed a single overlay-measured entity — the add-only PR shape #6042
	// exists for. The pairs below are then a reasoned guess at what Louvain would
	// have said, not a reading of what it did say. False when the data was
	// unavailable altogether: that is a decline, not a low-confidence answer.
	CommunityDataInferredOnly bool `json:"community_data_inferred_only"`
	// RefsWithInferredCommunityData names the refs that contributed at least one
	// inferred placement, sorted.
	RefsWithInferredCommunityData []string `json:"refs_with_inferred_community_data,omitempty"`
	// InferredOnlyPairCount is how many of the reported risk pairs overlap SOLELY
	// on communities that at least one side reached by inference. Non-zero means
	// at least one reported conflict is deduced rather than observed — even when
	// CommunityDataInferredOnly is false, which it will be whenever the refs also
	// touch measured communities that happen not to overlap.
	InferredOnlyPairCount int `json:"inferred_only_pair_count"`
}

type ModuleAlgorithmResults struct {
	// ModuleIDs is the deterministic sorted list of all module IDs present
	// in the aggregated graph (including singletons with no inbound/outbound
	// edges, when they're present in the input as Module entities).
	ModuleIDs []string `json:"module_ids"`
	// ModuleNames maps module ID → human-readable name. Always populated.
	ModuleNames map[string]string `json:"module_names"`
	// Edges is the full set of aggregated module→module edges, sorted.
	Edges []ModuleEdge `json:"edges"`
	// SCCs are the strongly-connected components of size >= 2.
	SCCs []ModuleSCC `json:"sccs"`
	// SCCOf maps module ID → SCC ID; -1 when the module is not in any
	// non-trivial SCC. Always populated for every module ID.
	SCCOf map[string]int `json:"scc_of"`
	// Centrality is per-module PageRank + betweenness, sorted by ID.
	Centrality []ModuleCentrality `json:"centrality"`
	// Stats are corpus-level summaries.
	Stats ModuleAlgorithmStats `json:"stats"`
}

type ModuleAlgorithmStats struct {
	NumModules        int `json:"num_modules"`
	NumModuleEdges    int `json:"num_module_edges"`
	NumSCCs           int `json:"num_sccs"`
	LargestSCCSize    int `json:"largest_scc_size"`
	NumModulesInCycle int `json:"num_modules_in_cycle"`
}

type ModuleCentrality struct {
	ModuleID    string  `json:"module_id"`
	ModuleName  string  `json:"module_name"`
	PageRank    float64 `json:"pagerank"`
	Betweenness float64 `json:"betweenness"`
	// InDegree / OutDegree are the unweighted node-degrees in the module
	// graph — cheap sanity-check metrics that often correlate with PageRank
	// but with very different units, useful for hub vs. fan-out distinction.
	InDegree  int `json:"in_degree"`
	OutDegree int `json:"out_degree"`
}

type ModuleCoverage struct {
	Module      string  `json:"module"`
	Total       int     `json:"total"`
	Covered     int     `json:"covered"`
	CoveragePct float64 `json:"coverage_pct"`
}

type ModuleEdge struct {
	FromModule string `json:"from_module"`
	ToModule   string `json:"to_module"`
	// Weight is the count of underlying entity-edges that collapsed onto
	// this module-pair (or, when DEPENDS_ON edges already carry a weight
	// property, that pre-baked count).
	Weight int `json:"weight"`
}

type ModuleSCC struct {
	// ID is a deterministic integer assigned to the SCC for cross-reference.
	// Stable across runs of the same input (Tarjan-discovery order over the
	// sorted node set).
	ID int `json:"id"`
	// Members lists module IDs participating in the cycle, sorted.
	Members []string `json:"members"`
	// MemberNames mirrors Members but carries the human-readable module name
	// (Module entity.Name when available; falls back to the ID).
	MemberNames []string `json:"member_names"`
	// Edges are the directed module→module edges INTERNAL to the SCC, sorted.
	Edges []ModuleEdge `json:"edges"`
	// Size is len(Members), for fast filtering.
	Size int `json:"size"`
}

type NPlusOneFinding struct {
	// CallerEntityID is the Function/Method entity that contains the loop.
	CallerEntityID string `json:"caller_entity_id"`
	// CallerName is the human-readable name of that entity.
	CallerName string `json:"caller_name"`
	// CallerFile is the source file of the caller entity.
	CallerFile string `json:"caller_file"`
	// CallerStartLine is the start line of the enclosing function.
	CallerStartLine int `json:"caller_start_line"`

	// QueryEntityID is the entity ID of the ORM query call site.
	QueryEntityID string `json:"query_entity_id"`
	// QueryName is the name of the query call (e.g. "User.objects.get").
	QueryName string `json:"query_name"`
	// QueryFile is the source file of the query call site.
	QueryFile string `json:"query_file"`
	// QueryLine is the line of the query call site.
	QueryLine int `json:"query_line"`

	// ORM is the ORM framework (e.g. "django", "sqlalchemy", "activerecord").
	ORM string `json:"orm"`
	// Language is the programming language.
	Language string `json:"language"`

	// LoopEntityID is the entity ID of the intermediate loop entity, if any.
	// Empty when the loop context was inferred from Properties["loop_context"].
	LoopEntityID string `json:"loop_entity_id,omitempty"`
	// LoopSubtype is the loop kind ("for_loop", "while_loop", etc.).
	LoopSubtype string `json:"loop_subtype,omitempty"`

	// Suggestion is the recommended remediation.
	Suggestion string `json:"suggestion"`
}

type NPlusOneReport struct {
	// Findings is the list of detected N+1 sites, sorted by file+line.
	Findings []NPlusOneFinding `json:"findings"`
	// EntitiesScanned is the number of entities examined.
	EntitiesScanned int `json:"entities_scanned"`
	// RelationshipsScanned is the number of relationships examined.
	RelationshipsScanned int `json:"relationships_scanned"`
}

type OrientQuestion struct {
	Question string   `json:"question"`
	Source   string   `json:"source"` // ambiguous_edge | bridge_node | isolated_node
	Entities []string `json:"entities,omitempty"`
}

type OrientationOptions struct {
	TopEntities  int // max KeyEntities returned (default 15)
	TopEdges     int // max CrossCutEdges returned (default 15)
	MaxQuestions int // max OrientQuestions returned (default 12)
}

type OrientationResult struct {
	KeyEntities   []KeyEntity      `json:"key_entities"`
	CrossCutEdges []CrossCutEdge   `json:"cross_cutting_edges"`
	Questions     []OrientQuestion `json:"orientation_questions"`
}

type PRImpactOptions struct {
	Hops          int // downstream BFS depth (default 3, clamped [1,6])
	MaxBlastNodes int // cap on blast_radius entries returned (default 500)
}

type PRImpactResult struct {
	ChangedEntities     []ChangedEntity     `json:"changed_entities"`
	ImpactedCommunities []ImpactedCommunity `json:"impacted_communities"`
	BlastRadius         []BlastEntity       `json:"blast_radius"`

	// Aggregate counts for quick triage.
	ChangedCount     int  `json:"changed_count"`
	CommunityCount   int  `json:"impacted_community_count"`
	BlastRadiusCount int  `json:"blast_radius_count"`
	Truncated        bool `json:"truncated,omitempty"`

	// CommunityDataAvailable is the validity flag for every community-derived
	// field in this struct (ImpactedCommunities, CommunityCount,
	// ImpactedCommunityIDs, and therefore the whole merge-risk analysis built on
	// top of them). Issue #6006.
	//
	// It exists because the per-repo Pass-4 algorithm pass was removed when the
	// group-scope algo pass replaced it: entities loaded straight out of graph.fb
	// carry the -2/nil sentinel, so every community-derived output collapses to
	// empty. Without this flag "no impacted communities" is indistinguishable
	// from "communities were never computed" — and on a merge-risk question that
	// reads as "safe to merge", which is the worst direction to be wrong in.
	//
	// MEASURED OVER THE CHANGED SET, NOT THE ENTITY SET. The first cut of this
	// flag asked "does any entity anywhere in the graph carry a community?", and
	// that is the wrong question: the group-algo overlay is computed from the
	// INDEXED GROUP UNION, so entities that exist only on a feature ref — every
	// entity a PR ADDS — are absent from it by construction. A pure add-only PR
	// therefore has a fully-covered repo and a completely uncovered change set,
	// and the graph-wide flag reported `community_data_available: true` next to
	// `risky_pair_count: 0` — an affirmative all-clear on a change nothing was
	// known about. Coverage of the entities we are actually reasoning about is
	// the only coverage that makes the answer valid.
	//
	// An EMPTY change set is vacuously available: nothing changed, so nothing can
	// conflict, and that is a real answer rather than a missing one. (This is the
	// live default-base case — conflicts mode diffs refs[0] against itself.)
	CommunityDataAvailable bool `json:"community_data_available"`
	// ChangedWithoutCommunity counts changed entities carrying no community, i.e.
	// the entities this analysis could not place — neither by the overlay nor by
	// inference. Non-zero with CommunityDataAvailable=true is PARTIAL coverage:
	// the verdict stands on the entities that were placed, but this many were
	// invisible to it.
	ChangedWithoutCommunity int `json:"changed_entities_without_community"`

	// ChangedWithOverlayCommunity counts changed entities the group-algo overlay
	// placed directly. These are MEASURED.
	ChangedWithOverlayCommunity int `json:"changed_entities_with_overlay_community"`
	// ChangedWithInferredCommunity counts changed entities placed by inference
	// from their placed neighbours (pr_impact_infer.go). These are DEDUCED — good
	// enough to triage with, not good enough to present as measured.
	ChangedWithInferredCommunity int `json:"changed_entities_with_inferred_community"`
	// CommunityDataInferredOnly is the verdict-level confidence marker: the
	// analysis ran, but EVERY placement behind it was inferred. An agent should
	// weigh such a verdict differently from one the overlay measured. False when
	// nothing was placed at all — that case is a decline
	// (CommunityDataAvailable=false), not a low-confidence answer.
	CommunityDataInferredOnly bool `json:"community_data_inferred_only"`
}

type PersistedStats struct {
	Entities      int
	Relationships int
	// ComputedAt is the index timestamp stamped into the graph.fb header
	// (the same value the sidecar's computed_at would carry). Zero when the
	// header carries no/unparseable timestamp.
	ComputedAt time.Time
	// IndexedRef is the git ref name (branch/tag) at index time, read
	// directly off the graph.fb header (#5729-W1 status plane). Empty for
	// legacy graphs written before Phase 0 git metadata (#2088) or a
	// detached HEAD / non-git repo.
	IndexedRef string
	// IndexedSHA is the abbreviated (short) HEAD commit hash at index time,
	// read directly off the graph.fb header. Empty under the same
	// conditions as IndexedRef.
	IndexedSHA string
}

type Relationship struct {
	ID     string `json:"id"`
	FromID string `json:"from_id"`
	ToID   string `json:"to_id"`
	Kind   string `json:"kind"`

	// Confidence overlay (Phase 1C, #2769). Value in [0.0, 1.0]; zero reads
	// as 1.0. See internal/types/confidence.go.
	Confidence float64 `json:"confidence,omitempty"`
	// contains filtered or unexported fields
}

type RelationshipView interface {
	ID() string
	FromID() string
	ToID() string
	Kind() string

	PropGet(key string) string
	PropLookup(key string) (string, bool)
	PropLen() int
	PropRange(f func(k, v string) bool)
	PropsSnapshot() map[string]string
}

type SegmentKind string

type SegmentMeta struct {
	// File is the BARE filename (seg-NNNN.fb) of the segment, relative to the
	// gen dir. It is never a path — read-side validation (segFileRe) rejects
	// any value containing a separator or "..".
	File string `json:"file"`
	// Kind is the primary stream carried by this segment (entity|relationship).
	Kind SegmentKind `json:"kind"`
	// EntityCount / RelCount are the number of entities / relationships this
	// segment contributes. Either may be zero (a pure-relationship segment has
	// EntityCount==0, and vice-versa).
	EntityCount int `json:"entity_count"`
	RelCount    int `json:"rel_count"`
	// MinKey / MaxKey are the smallest and largest entity-ID keys present in
	// this segment (lexicographic, matching the FlatBuffers `(key)` sort on
	// Entity.id). Populated only for segments that carry entities
	// (EntityCount>0); empty for pure-relationship segments. The reader uses
	// [MinKey,MaxKey] to skip segments during LookupEntityByID (decision 4).
	MinKey string `json:"min_key,omitempty"`
	MaxKey string `json:"max_key,omitempty"`
}

type ServiceCycle struct {
	// Members lists service (repo) names that form the cycle, sorted.
	Members []string `json:"members"`
	// Edges lists the directed service→service edges internal to the cycle,
	// sorted for determinism.
	Edges []ServiceEdge `json:"edges"`
	// Size is len(Members), for fast filtering.
	Size int `json:"size"`
}

type ServiceEdge struct {
	From      string   `json:"from"`
	To        string   `json:"to"`
	Relations []string `json:"relations,omitempty"`
}

type ServiceLink struct {
	FromService string
	ToService   string
	Relation    string
}

type Stats struct {
	Files         int `json:"files"`
	Entities      int `json:"entities"`
	Relationships int `json:"relationships"`
}

type SubtypeConflict struct {
	EntityID  string
	Canonical string
	Property  string
}

type SurpriseEdge struct {
	FromID string  `json:"from_id"`
	ToID   string  `json:"to_id"`
	Score  float64 `json:"score"`
	Reason string  `json:"reason"`
}

type UncoveredEntity struct {
	EntityID   string `json:"entity_id"`
	Name       string `json:"name"`
	Kind       string `json:"kind"`
	SourceFile string `json:"source_file"`
	StartLine  int    `json:"start_line"`
	Language   string `json:"language"`
	Module     string `json:"module,omitempty"`
	// Repo is the slug of the owning repository. ComputeCoverage runs on a
	// single document and leaves this empty; the group-level aggregator stamps
	// it so the UI can resolve source through the correct repo root in a
	// multi-repo group (#4551). Without it, a source-peek ref like
	// "src/app.controller.ts:9" cannot be mapped to the repo it lives in.
	Repo string `json:"repo,omitempty"`
	// Severity is "high" | "medium" | "low".
	Severity string `json:"severity"`
	// State is the coverage state of this entity (#4662). For entities in this
	// (not-reach-covered) list it is either:
	//
	//	"contract-only" — an offline contract spec asserts the endpoint's shape
	//	                  but no test executes the handler. NOT dangerously
	//	                  untested; severity is downgraded accordingly.
	//	"uncovered"     — neither reach-covered nor contract-covered.
	//
	// (Reach-covered entities never appear in this list, so the value is never
	// "reach" here; the three-state vocabulary is reach | contract-only |
	// uncovered, and "reach" lives on the covered side of the report.)
	State string `json:"state"`
}

type WalkUpStats struct {
	// HelperTargets is the number of TESTS-edge targets that have inbound CALLS.
	HelperTargets int
	// DerivedEdges is the number of new derived TESTS edges emitted.
	DerivedEdges int
	// SkippedHighFanIn is the number of helpers skipped because their caller
	// count exceeded maxCallersPerHelper.
	SkippedHighFanIn int
	// DuplicatesSuppressed is the number of derived edges skipped because an
	// explicit TESTS edge already covered the caller.
	DuplicatesSuppressed int
}