// Package cartography builds a bidirectional English↔Go atlas of the codebase.
//
// The atlas maps every Go declaration to an English description with API
// contracts and validation criteria. It works in two phases:
//   - Mechanical extraction (zero oracle calls): go/ast parsing gives signatures,
//     doc comments, test associations, and side-effect detection.
//   - Oracle enrichment (rate-limited, iterative): the organism revises its
//     lowest-confidence descriptions over generations.
//
// The atlas is bidirectional: Go path → English description via LookupGo,
// and English concept → Go code path via LookupEnglish.
package cartography

// Entry is a single declaration in the atlas.
type Entry struct {
	// Identity (Go side — mechanical).
	ID       string `json:"id"`                 // "lattice.Bond" or "lattice.Node.Dissolve"
	Kind     string `json:"kind"`               // "func", "method", "type", "interface", "const", "var"
	Package  string `json:"package"`            // package name
	Name     string `json:"name"`               // declaration name
	Receiver string `json:"receiver,omitempty"` // receiver type for methods
	Exported bool   `json:"exported"`           // starts with uppercase
	FilePath string `json:"file_path"`          // relative to project root
	Line     int    `json:"line"`               // source line number

	// Contract (mechanical from signature + oracle-enriched).
	Signature   string       `json:"signature"`              // full Go signature text
	Params      []ParamInfo  `json:"params,omitempty"`       // parameter names, types, semantics
	Returns     []ReturnInfo `json:"returns,omitempty"`      // return types, error conditions
	DocComment  string       `json:"doc_comment,omitempty"`  // existing Go doc comment
	DependsOn   []string     `json:"depends_on,omitempty"`   // IDs of other entries this calls
	SideEffects []string     `json:"side_effects,omitempty"` // "spawns goroutine", "file I/O", etc.

	// English (starts mechanical, oracle-refined).
	Description string `json:"description"`            // what it does + why
	Contract    string `json:"contract,omitempty"`     // "takes X, returns Y, errors when Z"
	EdgeCases   string `json:"edge_cases,omitempty"`   // oracle-enriched: nil/empty/zero behavior

	// Validation (from test files).
	HasTest      bool     `json:"has_test"`                  // whether a corresponding test exists
	TestFuncs    []string `json:"test_funcs,omitempty"`      // ["TestBond", "TestBond_NilElement"]
	TestFile     string   `json:"test_file,omitempty"`       // path to the test file
	TestPatterns []string `json:"test_patterns,omitempty"`   // test table case names
	Validation   string   `json:"validation,omitempty"`      // "tested with nil, empty, and valid inputs"

	// Concepts (bidirectional index keys).
	Concepts []string `json:"concepts,omitempty"` // ["lattice", "bond", "element"]

	// Fitness.
	Confidence float64 `json:"confidence"` // 0.3 mechanical, 0.5 +tests, 0.7 oracle, 0.9 validated
	Source     string  `json:"source"`     // "mechanical", "oracle", "self-revised"
	Revision   int     `json:"revision"`   // generation number of last revision
}

// ParamInfo describes a function parameter.
type ParamInfo struct {
	Name     string `json:"name"`
	Type     string `json:"type"`
	Semantic string `json:"semantic,omitempty"` // oracle-enriched: what this param means
}

// ReturnInfo describes a return value.
type ReturnInfo struct {
	Type      string `json:"type"`
	Semantic  string `json:"semantic,omitempty"`   // oracle-enriched
	IsError   bool   `json:"is_error,omitempty"`   // whether this is an error return
	ErrorCond string `json:"error_cond,omitempty"` // when this error occurs
}