semantic

package
v1.10.7 Latest Latest
Warning

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

 Go to latest Published: May 5, 2026 License: MIT Imports: 0 Imported by: 0

Documentation

Overview

Package semantic holds the shared type aliases and configuration shape used by the semantic-graph subsystem (Phase 57+, v1.10).

SPEC reference: SPEC-DRAFT.md §7 (typed identifiers) and §25 (config keys).

This package is intentionally tiny — it carries only the cross-package types that BOTH internal/semantic/store/ AND internal/config/ reference, so neither can pull in the duckdb-go dependency by accident. The store package owns the duckdb-go import (D-12, STORE-06).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ClusteringConfig 

type ClusteringConfig struct {
	Enabled                     bool `koanf:"enabled"`                         // default true
	MaxComponentSizeBeforeSplit int  `koanf:"max_component_size_before_split"` // default 5000
	LabelPropagationIterations  int  `koanf:"label_propagation_iterations"`    // default 20
}

ClusteringConfig holds symbol-cluster parameters (P62). Field set mirrors SPEC §25.clustering.* verbatim.

type Config 

type Config struct {
	// Enabled gates the entire semantic-graph subsystem. When false, the
	// daemon's bootstrap step 6b skips Open and downstream consumers MUST
	// guard `daemon.SemanticStore() == nil`.
	Enabled bool `koanf:"enabled"`

	// Store holds the DuckDB embedded fact-store settings (path, memory,
	// thread budget). See SPEC-DRAFT.md §25.store.*.
	Store StoreConfig `koanf:"store"`

	// Indexing configures the per-snapshot indexing pipeline (P59).
	Indexing IndexingConfig `koanf:"indexing"`

	// Extraction configures the tree-sitter extraction layer (P59 P02).
	// Per Phase 59 user decision (CONTEXT.md): max_file_size and
	// auto_index_on_activate REMAIN under Indexing (already present from
	// Phase 57). Only the four genuinely-new keys live here.
	Extraction ExtractionConfig `koanf:"extraction"`

	// LiveUpdates configures the fsnotify-driven overlay watcher (P60).
	LiveUpdates LiveUpdatesConfig `koanf:"live_updates"`

	// LSPEnrichment configures the LSP enrichment worker (P61).
	LSPEnrichment LSPEnrichmentConfig `koanf:"lsp_enrichment"`

	// Graph configures the graph-engine projections (P62).
	Graph GraphConfig `koanf:"graph"`

	// PageRank configures the cross-file ranking pass (P62).
	PageRank PageRankConfig `koanf:"pagerank"`

	// Clustering configures the symbol-cluster derivation (P62).
	Clustering ClusteringConfig `koanf:"clustering"`

	// Retrieval configures retrieval-tool defaults (P64).
	Retrieval RetrievalConfig `koanf:"retrieval"`

	// Guardrails configures the GuardrailMiddleware (P66).
	Guardrails GuardrailsConfig `koanf:"guardrails"`

	// Eval configures the eval harness (P67).
	Eval EvalConfig `koanf:"eval"`

	// TypeResolution configures the type-resolution pipeline (P62).
	TypeResolution TypeResolutionConfig `koanf:"type_resolution"`

	// PhaseGraph configures the bootstrap phase-graph runner (v1.11+).
	PhaseGraph PhaseGraphConfig `koanf:"phase_graph"`
}

Config is the typed mirror of the koanf `semantic_index.*` block declared in SPEC-DRAFT.md §25. Phase 57 plan P02 lands this typed shape with zero values; plan P03 wires the koanf binding (`koanf:"semantic_index"`) onto the SerenaConfig.SemanticIndex field that consumes this type AND populates the SPEC §25 default values into internal/config/defaults.go.

The split is deliberate: P02's daemon step 6b references `cfg.SemanticIndex.Enabled`, which must compile at end of wave 1 even without P03 having merged. With Go's bool zero value, Enabled defaults to false, so step 6b's `if cfg.SemanticIndex.Enabled { ... }` branch is dead at runtime when P03 is absent — safe degradation.

Style note: this file mirrors the ObservabilityConfig nested-struct style in internal/config/config.go (one koanf tag per leaf). Every field name and its koanf tag mirrors a SPEC-DRAFT.md §25 key verbatim — when SPEC §25 changes a key name, this file MUST change in lockstep, otherwise the koanf binding silently drops the value.

History note: P03 broadened the nested type set so every SPEC §25 key has a typed home (P02 shipped a smaller speculative subset that drifted from SPEC §25; aligning the field names here is part of P03's RED-gate preparation since the coverage tests reference the SPEC §25 keys verbatim).

type EdgeID 

type EdgeID uint64

EdgeID is the monotone identifier for an edge row in semantic_edges (SPEC-DRAFT.md §9.7).

type EvalConfig 

type EvalConfig struct {
	Enabled               bool     `koanf:"enabled"`                  // default true
	DefaultModes          []string `koanf:"default_modes"`            // default [baseline, native, semantic, semantic_guarded]
	OutputDir             string   `koanf:"output_dir"`               // default ".helix/eval"
	TrackCosts            bool     `koanf:"track_costs"`              // default true
	TrackToolBehavior     bool     `koanf:"track_tool_behavior"`      // default true
	RedactSourceInReports bool     `koanf:"redact_source_in_reports"` // default false
}

EvalConfig holds eval-harness settings (P67). Field set mirrors SPEC §25.eval.* verbatim.

type ExtractionConfig added in v1.10.1 

type ExtractionConfig struct {
	// ExtractionReadyTimeout bounds RequireReady's wait for an initial
	// extraction to surface ready|partial|failed. Human-readable duration
	// (e.g., "30s").
	ExtractionReadyTimeout string `koanf:"extraction_ready_timeout"`

	// ExtractionFileTimeout bounds per-file extraction. Beyond this the
	// file is dropped to PartialReasonTimeout.
	ExtractionFileTimeout string `koanf:"extraction_file_timeout"`

	// MaxParallelFiles caps the per-workspace extraction worker pool.
	MaxParallelFiles int `koanf:"max_parallel_files"`

	// AllowPartialResults gates whether RequireReady accepts a "partial"
	// outcome as ready. When false, a partial-only extraction blocks
	// consumer queries until ready or failed.
	AllowPartialResults bool `koanf:"allow_partial_results"`
}

ExtractionConfig holds tree-sitter extraction settings (P59 P02). Per Phase 59 user decision (CONTEXT.md): max_file_size and initial_extraction_on_activation REMAIN under IndexingConfig (already present as Indexing.MaxFileSize and Indexing.AutoIndexOnActivate from Phase 57). Only the four genuinely-new keys live here.

Field set mirrors SPEC §25.extraction.* verbatim.

type FileID 

type FileID uint64

FileID is the monotone identifier for a file row in semantic_files (SPEC-DRAFT.md §9.4). Stable within a single store; not portable across stores or rebuilds.

type Freshness 

type Freshness string

Freshness classifies the staleness of a fact returned by the effective-read API (SPEC-DRAFT.md §10). Values are written into log fields and (later) surfaced as a metric label, so the enum is closed. 

const (
	// FreshnessFresh means the fact comes from the live overlay or from a
	// snapshot whose underlying file mtime matches the fact's recorded mtime.
	FreshnessFresh Freshness = "fresh"
	// FreshnessStale means the fact comes from a snapshot but the file has
	// been modified since indexing; consumers should warn but may still serve.
	FreshnessStale Freshness = "stale"
	// FreshnessUnknown means the fact cannot be classified (e.g., the file
	// is missing, mtime is unreadable). Consumers should treat as stale.
	FreshnessUnknown Freshness = "unknown"
)

type GraphConfig 

type GraphConfig struct {
	MinEdgeConfidence                float64 `koanf:"min_edge_confidence"`                  // default 0.50
	MaxLoadedNodes                   int     `koanf:"max_loaded_nodes"`                     // default 1_000_000
	MaxLoadedEdges                   int     `koanf:"max_loaded_edges"`                     // default 5_000_000
	MaxLocalPagerankNodes            int     `koanf:"max_local_pagerank_nodes"`             // default 5000
	MaxIncrementalClusterRepairNodes int     `koanf:"max_incremental_cluster_repair_nodes"` // default 10_000
}

GraphConfig holds graph-engine projection settings (P62). Field set mirrors SPEC §25.graph.* verbatim.

type GuardrailsConfig 

type GuardrailsConfig struct {
	Enabled                       bool   `koanf:"enabled"`                            // default true
	Enforcement                   string `koanf:"enforcement"`                        // "warn" | "block"
	RequireImpactForPublicAPIEdit bool   `koanf:"require_impact_for_public_api_edit"` // default true
	RequireReferencesBeforeRename bool   `koanf:"require_references_before_rename"`   // default true
	RequireReferencesBeforeDelete bool   `koanf:"require_references_before_delete"`   // default true
	RequireVerifyAfterEdit        bool   `koanf:"require_verify_after_edit"`          // default true
	StaleGraphPolicy              string `koanf:"stale_graph_policy"`                 // "warn" | "block"
}

GuardrailsConfig holds GuardrailMiddleware settings (P66). Field set mirrors SPEC §25.guardrails.* verbatim.

type HeritageID added in v1.10.1 

type HeritageID uint64

HeritageID is the monotone identifier for a heritage-edge row (extends / implements / embeds) in semantic_heritage (SPEC-DRAFT.md §9.x). Phase 59 introduces it.

type ImportID added in v1.10.1 

type ImportID uint64

ImportID is the monotone identifier for an import row in semantic_imports (SPEC-DRAFT.md §9.x). Phase 59 introduces it alongside the tree-sitter extraction layer.

type IndexingConfig 

type IndexingConfig struct {
	Mode                   string  `koanf:"mode"`                      // "lazy" | "eager" | "on_demand"
	AutoIndexOnActivate    bool    `koanf:"auto_index_on_activate"`    // default false
	MaxFileSize            string  `koanf:"max_file_size"`             // human-readable size, e.g., "2MiB"
	MaxFiles               int     `koanf:"max_files"`                 // ceiling for indexed file count
	FullReindexChangeRatio float64 `koanf:"full_reindex_change_ratio"` // default 0.25
	SnapshotRetention      int     `koanf:"snapshot_retention"`        // default 5
	IncludeGenerated       bool    `koanf:"include_generated"`         // default false
	RequiredForReadyz      bool    `koanf:"required_for_readyz"`       // default false
}

IndexingConfig holds per-snapshot indexing-pipeline settings (P59). Field set mirrors SPEC §25.indexing.* verbatim.

type LSPEnrichmentConfig 

type LSPEnrichmentConfig struct {
	Enabled                bool   `koanf:"enabled"`
	TimeoutPerFile         string `koanf:"timeout_per_file"`          // default "5s"
	TimeoutTotal           string `koanf:"timeout_total"`             // default "120s"
	MaxSymbolsPerFile      int    `koanf:"max_symbols_per_file"`      // default 200
	MaxReferencesPerSymbol int    `koanf:"max_references_per_symbol"` // default 1000
	MaxReferencesPerFile   int    `koanf:"max_references_per_file"`   // default 5000
	MaxCallHierarchyDepth  int    `koanf:"max_call_hierarchy_depth"`  // default 2
	MaxTypeHierarchyDepth  int    `koanf:"max_type_hierarchy_depth"`  // default 2
}

LSPEnrichmentConfig holds LSP enrichment-worker settings (P61). Field set mirrors SPEC §25.lsp_enrichment.* verbatim.

type LiveUpdatesConfig 

type LiveUpdatesConfig struct {
	Enabled                  bool   `koanf:"enabled"`                      // default true
	DebounceMS               int    `koanf:"debounce_ms"`                  // default 250
	MaxBatchDelayMS          int    `koanf:"max_batch_delay_ms"`           // default 1500
	BulkChangeThreshold      int    `koanf:"bulk_change_threshold"`        // default 200
	CompactAfterIdleMS       int    `koanf:"compact_after_idle_ms"`        // default 5000
	LSPRevalidateAfterIdleMS int    `koanf:"lsp_revalidate_after_idle_ms"` // default 750
	LSPCompactionMaxWaitMS   int    `koanf:"lsp_compaction_max_wait_ms"`   // default 3000
	MaxOverlayFiles          int    `koanf:"max_overlay_files"`            // default 1000
	MaxOverlayAge            string `koanf:"max_overlay_age"`              // default "30m"
}

LiveUpdatesConfig holds fsnotify overlay-watcher settings (P60). Field set mirrors SPEC §25.live_updates.* verbatim.

type PageRankConfig 

type PageRankConfig struct {
	Damping       float64 `koanf:"damping"`        // default 0.85
	Epsilon       float64 `koanf:"epsilon"`        // default 1e-6
	MaxIterations int     `koanf:"max_iterations"` // default 100
}

PageRankConfig holds cross-file ranking parameters (P62). Field set mirrors SPEC §25.pagerank.* verbatim.

type PhaseGraphConfig 

type PhaseGraphConfig struct {
	Enabled           bool `koanf:"enabled"`             // default true
	ValidateOnStartup bool `koanf:"validate_on_startup"` // default true
	FailOnCycle       bool `koanf:"fail_on_cycle"`       // default true
	DumpDotOnError    bool `koanf:"dump_dot_on_error"`   // default true
}

PhaseGraphConfig holds bootstrap phase-graph-runner settings (v1.11+). Field set mirrors SPEC §25.phase_graph.* verbatim.

type ReferenceID 

type ReferenceID uint64

ReferenceID is the monotone identifier for a reference row in semantic_references (SPEC-DRAFT.md §9.6).

type RetrievalConfig 

type RetrievalConfig struct {
	DefaultMaxTokens         int  `koanf:"default_max_tokens"`          // default 8000
	IncludeEvidenceByDefault bool `koanf:"include_evidence_by_default"` // default true
}

RetrievalConfig holds retrieval-tool defaults (P64). Field set mirrors SPEC §25.retrieval.* verbatim.

type SnapshotID 

type SnapshotID uint64

SnapshotID is the monotone identifier for a semantic snapshot row in semantic_snapshots (SPEC-DRAFT.md §9.2). Snapshots are immutable; readers resolve effective facts via snapshot ⊕ overlay − tombstones (SPEC §10).

type StoreConfig 

type StoreConfig struct {
	// Kind names the store implementation. Phase 57 ships only "duckdb".
	Kind string `koanf:"kind"`
	// Path is workspace-relative (default: ".helix/semantic.duckdb").
	// MUST be a relative path; absolute paths and `..` segments are rejected
	// at Open time (T-57-02-01 mitigation).
	Path string `koanf:"path"`
	// MemoryLimit is the DuckDB memory budget (e.g., "1GiB").
	MemoryLimit string `koanf:"memory_limit"`
	// Threads is the DuckDB worker-thread count.
	Threads int `koanf:"threads"`
}

StoreConfig holds the DuckDB embedded fact-store settings. SPEC-DRAFT.md §25.store.*. Defaults populated by P03 in internal/config/defaults.go.

type SymbolID 

type SymbolID uint64

SymbolID is the monotone identifier for a symbol row in semantic_symbols (SPEC-DRAFT.md §9.5).

type TypeFactID added in v1.10.1 

type TypeFactID uint64

TypeFactID is the monotone identifier for a type-annotation fact row in semantic_type_facts (SPEC-DRAFT.md §9.x). Phase 59 introduces it.

type TypeResolutionConfig 

type TypeResolutionConfig struct {
	Enabled               bool    `koanf:"enabled"`                 // default true
	MaxChainDepth         int     `koanf:"max_chain_depth"`         // default 8
	MaxFixpointIterations int     `koanf:"max_fixpoint_iterations"` // default 8
	MinConfidenceForEdge  float64 `koanf:"min_confidence_for_edge"` // default 0.45
	CommentFallbacks      bool    `koanf:"comment_fallbacks"`       // default true
	EmitUnresolvedEdges   bool    `koanf:"emit_unresolved_edges"`   // default true
}

TypeResolutionConfig holds type-resolution pipeline parameters (P62). Field set mirrors SPEC §25.type_resolution.* verbatim.

type WorkspaceID added in v1.10.1 

type WorkspaceID string

WorkspaceID is the opaque identifier for a workspace registered with the daemon's kernel. It is the key under which the extraction scheduler tracks per-workspace state, in-flight jobs, and subscribers (Phase 59 P03, D-04). Stable for the lifetime of a daemon process; not portable across daemon restarts.

Source Files

View all Source files

Directories

Path Synopsis
Package extract emits typed semantic facts (symbols, references, imports, types, heritage, syntax edges) by parsing source files with tree-sitter.
 Package extract emits typed semantic facts (symbols, references, imports, types, heritage, syntax edges) by parsing source files with tree-sitter.
golang
Package goextract is the per-language tree-sitter extraction provider for Go source files.
 Package goextract is the per-language tree-sitter extraction provider for Go source files.
python
Package pyextract is the per-language tree-sitter extraction provider for Python.
 Package pyextract is the per-language tree-sitter extraction provider for Python.
testutil
Package testutil — golden-file helpers shared by all per-language provider tests (internal/semantic/extract/<lang>/provider_test.go).
 Package testutil — golden-file helpers shared by all per-language provider tests (internal/semantic/extract/<lang>/provider_test.go).
typescript
Package tsextract is the per-language tree-sitter extraction provider for TypeScript and JavaScript.
 Package tsextract is the per-language tree-sitter extraction provider for TypeScript and JavaScript.
Package scheduler owns extraction lifecycle: initial-walk on workspace activation, incremental scheduling on file changes (Phase 60 fills body), state tracking, and the centralized RequireReady consumer-side gate.
 Package scheduler owns extraction lifecycle: initial-walk on workspace activation, incremental scheduling on file changes (Phase 60 fills body), state tracking, and the centralized RequireReady consumer-side gate.
Package store is the SOLE owner of the github.com/duckdb/duckdb-go/v2 import in this module.
 Package store is the SOLE owner of the github.com/duckdb/duckdb-go/v2 import in this module.

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.