cortex

package
v2.2.1 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2026 License: MIT Imports: 18 Imported by: 0

Documentation

Overview

Package cortex captures retrieval evidence from the currently shipped Cortex application path without reimplementing search, filtering, or ranking.

Index

Constants

View Source 
const CapabilityNotExecuted = "not_executed_capability"

CapabilityNotExecuted identifies a labelled authority field that the current production search path cannot execute without broadening its semantics.

Variables

View Source 
var (
	ErrCorpusHashMismatch   = errors.New("corpus hash mismatch")
	ErrProtocolHashMismatch = errors.New("protocol hash mismatch")
	ErrBinaryHashMismatch   = errors.New("binary hash mismatch")
	ErrCommitMismatch       = errors.New("commit mismatch")
	ErrHardwareMismatch     = errors.New("hardware mismatch")
)

Typed identity validation errors. Each error message contains the field name so callers and tests can match on the expected substring.

View Source 
var (
	// ErrEvidenceOutputExists identifies a run that would overwrite evidence.
	ErrEvidenceOutputExists = errors.New("evidence output already exists")
	// ErrExternalProviderConfigured identifies an offline-policy violation.
	ErrExternalProviderConfigured = errors.New("external provider configuration is forbidden")
)
View Source 
var ErrMeasurementUnavailable = errors.New("process resource measurement unavailable")

ErrMeasurementUnavailable identifies a platform measurement that cannot be provided without representing absence as a zero value.

Functions

func IngestEvidenceCorpus 

func IngestEvidenceCorpus(ctx context.Context, stores *common.BenchStores, corpus common.Corpus) (map[int64]string, error)

IngestEvidenceCorpus ingests corpus records through the existing BenchStores.App.Stores APIs (IngestSession) and returns a map from database observation ID to the immutable corpus record ID. No internal/* retrieval code is copied or reimplemented.

func NewFreshBenchStores 

func NewFreshBenchStores(ctx context.Context, dbDir string) (*common.BenchStores, error)

NewFreshBenchStores creates a fresh file-based SQLite database in dbDir and returns a BenchStores wrapping the new app instance. Each invocation gets its own database file and app — no shared state across calls.

func RefuseExternalProviders 

func RefuseExternalProviders() error

RefuseExternalProviders enforces the preregistered offline evidence policy.

func RunEvidence 

func RunEvidence(ctx context.Context, request EvidenceRunRequest) (run common.IndependentRun, err error)

RunEvidence composes identity validation, fresh ingestion, the production runner, resource capture, report construction, and atomic output publishing.

func RunFreshProcess 

func RunFreshProcess(ctx context.Context, request FreshProcessRequest) error

RunFreshProcess creates and waits for a new operating-system process for every call. It never reuses an in-process runner, database, or app instance.

func ValidateEvidenceIdentity 

func ValidateEvidenceIdentity(request EvidenceRunRequest) error

ValidateEvidenceIdentity checks that the committed corpus, protocol, binary, and hardware identities match the request before any database or output is created. Each mismatch returns a typed error whose message contains the field name for test matching.

The evaluated commit is NOT compared against corpus.Build.Commit here. That comparison is structurally self-referential: the corpus file is part of the evaluated commit, so changing its embedded build commit necessarily changes the containing HEAD, yielding no stable fixed point. Commit integrity is instead enforced by the CLI preflight (executeEvidenceRun), which compares the approved commit against the current clean repository HEAD.

func WriteEvidenceOutput 

func WriteEvidenceOutput(outputDir string, raw BaselineRun, report common.EvidenceReport, run common.IndependentRun) (err error)

WriteEvidenceOutput validates and stages all evidence artifacts before one directory rename makes the complete output visible to readers.

Types

type BaselineRun 

type BaselineRun struct {
	Queries            []QueryTrace `json:"queries"`
	BlockingFailures   []string     `json:"blocking_failures"`
	IncompleteEvidence []string     `json:"incomplete_evidence"`
}

BaselineRun contains per-query current-production traces and any correctness failures that block use of the run as baseline evidence.

func RunCurrentProductionBaseline 

func RunCurrentProductionBaseline(ctx context.Context, stores *common.BenchStores, stableIDs map[int64]string, queries []Query) (BaselineRun, error)

RunCurrentProductionBaseline executes queries through BenchStores.App's current production Search store. stableIDs maps current SQLite identities to immutable corpus labels; it does not participate in search or ranking.

type CapabilityTrace 

type CapabilityTrace struct {
	Field  string `json:"field"`
	Status string `json:"status"`
}

CapabilityTrace records an explicitly labelled field that was not executed by the current production retrieval path.

type CollectorLifecycle 

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

CollectorLifecycle enforces start-before-snapshot and cumulative monotonic evidence. Platform collectors may embed it and call Start and Observe.

func (*CollectorLifecycle) Observe 

func (l *CollectorLifecycle) Observe(next ProcessResources) error

Observe validates a snapshot against the collector lifecycle and prior cumulative sample. HeapAllocBytes is intentionally excluded because it is a current gauge rather than a cumulative counter.

func (*CollectorLifecycle) Start 

func (l *CollectorLifecycle) Start() error

Start begins one collector lifecycle and rejects reuse.

type EffectiveInput 

type EffectiveInput struct {
	Query       string     `json:"query"`
	Project     string     `json:"project"`
	Type        string     `json:"type,omitempty"`
	Scope       string     `json:"scope,omitempty"`
	Limit       int        `json:"limit"`
	FusionK     float64    `json:"fusion_k,omitempty"`
	GraphExpand bool       `json:"graph_expand"`
	AsOf        *time.Time `json:"as_of,omitempty"`
}

EffectiveInput is the exact supported filter and execution input passed to the current production Search store.

type EvidenceIdentity 

type EvidenceIdentity struct {
	Commit         string                  `json:"commit"`
	BinarySHA256   string                  `json:"binary_sha256"`
	CorpusSHA256   string                  `json:"corpus_sha256"`
	ProtocolSHA256 string                  `json:"protocol_sha256"`
	Hardware       common.HardwareMetadata `json:"hardware"`
}

EvidenceIdentity binds the immutable build, binary, corpus, protocol, and hardware identities that must match across independent baseline runs under design #720. Identity is validated before any database creation.

type EvidenceOrchestrationRequest 

type EvidenceOrchestrationRequest struct {
	Stores    *common.BenchStores
	StableIDs map[int64]string
	Queries   []Query
	Collector ResourceCollector
	Report    common.EvidenceReport
}

EvidenceOrchestrationRequest provides the existing production runner, resource collector, and report inputs for one evidence run.

type EvidenceOrchestrationResult 

type EvidenceOrchestrationResult struct {
	Baseline  BaselineRun
	Resources ProcessResources
	Report    common.EvidenceReport
}

EvidenceOrchestrationResult retains the raw production trace, measured process resources, and the report derived from that trace.

func OrchestrateEvidence 

func OrchestrateEvidence(ctx context.Context, request EvidenceOrchestrationRequest) (EvidenceOrchestrationResult, error)

OrchestrateEvidence measures one invocation of the unchanged current production baseline runner and maps its observed ranking into EvidenceReport.

type EvidenceRunRequest 

type EvidenceRunRequest struct {
	EvidenceRoot    string           `json:"evidence_root"`
	OutputDir       string           `json:"output_dir"`
	WorkDir         string           `json:"work_dir"`
	RunID           string           `json:"run_id"`
	Seed            string           `json:"seed"`
	ProtocolVersion string           `json:"protocol_version"`
	Identity        EvidenceIdentity `json:"identity"`
	Corpus          common.Corpus    `json:"-"`
}

EvidenceRunRequest describes one independent evidence invocation. It is constructed by NewEvidenceRunRequest and consumed by RunEvidence.

func NewEvidenceRunRequest 

func NewEvidenceRunRequest(root, outputDir, runID, seed, protocolVersion string, identity EvidenceIdentity) (EvidenceRunRequest, error)

NewEvidenceRunRequest loads the corpus from root, stores the identity, and returns a request ready for identity validation and ingestion. It does NOT validate the identity — call ValidateEvidenceIdentity separately so that identity checks run before any database creation.

type FreshProcessRequest 

type FreshProcessRequest struct {
	Executable string
	Args       []string
	Dir        string
	Env        []string
}

FreshProcessRequest describes exactly one independent process invocation.

type LatencySample 

type LatencySample struct {
	Unit        string `json:"unit"`
	Nanoseconds int64  `json:"nanoseconds"`
}

LatencySample records wall-clock search latency in a serialization-friendly unit.

type MeasurementUnavailableError 

type MeasurementUnavailableError struct {
	Collector ResourceCollectorIdentity
	Resource  string
	Cause     error
}

MeasurementUnavailableError carries the versioned collector identity and unavailable resource for fail-closed representative evidence.

func (*MeasurementUnavailableError) Error 

func (e *MeasurementUnavailableError) Error() string

func (*MeasurementUnavailableError) Is 

func (e *MeasurementUnavailableError) Is(target error) bool

Is allows errors.Is(err, ErrMeasurementUnavailable).

type ProcessResources 

type ProcessResources struct {
	Collector       ResourceCollectorIdentity `json:"collector"`
	Units           ResourceUnits             `json:"units"`
	Availability    ResourceAvailability      `json:"availability"`
	Wall            time.Duration             `json:"wall_nanoseconds"`
	CPU             time.Duration             `json:"cpu_nanoseconds"`
	PeakRSSBytes    int64                     `json:"peak_rss_bytes"`
	HeapAllocBytes  uint64                    `json:"heap_alloc_bytes"`
	TotalAllocBytes uint64                    `json:"total_alloc_bytes"`
}

ProcessResources is one cumulative process resource sample. Durations are serialized as nanoseconds and memory/allocation values as bytes.

func NewProcessResources 

func NewProcessResources(identity ResourceCollectorIdentity) ProcessResources

NewProcessResources initializes a sample with the canonical evidence units.

func (ProcessResources) Validate 

func (r ProcessResources) Validate() error

Validate rejects ambiguous, unversioned, or unit-inconsistent samples.

type Query 

type Query struct {
	ID                      string               `json:"id"`
	Text                    string               `json:"text"`
	Options                 domain.SearchOptions `json:"options"`
	UnsupportedCapabilities []string             `json:"unsupported_capabilities,omitempty"`
}

Query identifies one immutable baseline query and its effective production search inputs.

type QueryTrace 

type QueryTrace struct {
	QueryID        string            `json:"query_id"`
	EffectiveInput EffectiveInput    `json:"effective_input"`
	Ranked         []RankedResult    `json:"ranked"`
	Capabilities   []CapabilityTrace `json:"capabilities,omitempty"`
	Latency        LatencySample     `json:"latency"`
	Resources      ResourceSample    `json:"resources"`
	Error          string            `json:"error,omitempty"`
}

QueryTrace records effective inputs, ranked identities, performance samples, and a safe error string for one production search invocation.

type RankedResult 

type RankedResult struct {
	StableID  string  `json:"stable_id"`
	CurrentID int64   `json:"current_id"`
	Project   string  `json:"project"`
	Position  int     `json:"position"`
	Score     float64 `json:"score"`
	Strategy  string  `json:"strategy"`
}

RankedResult binds a corpus-stable label to the current production database identity and observed ranking evidence.

type ResourceAvailability 

type ResourceAvailability struct {
	Wall       bool `json:"wall"`
	CPU        bool `json:"cpu"`
	PeakRSS    bool `json:"peak_rss"`
	HeapAlloc  bool `json:"heap_alloc"`
	TotalAlloc bool `json:"total_alloc"`
}

ResourceAvailability distinguishes an available zero measurement from a metric the collector could not measure.

type ResourceCollector 

type ResourceCollector interface {
	Start(context.Context) error
	Snapshot(context.Context) (ProcessResources, error)
}

ResourceCollector captures process resources without changing the measured process lifecycle. Platform implementations provide the measurements.

func NewResourceCollector 

func NewResourceCollector() (ResourceCollector, error)

NewResourceCollector returns a Linux /proc-based resource collector.

type ResourceCollectorIdentity 

type ResourceCollectorIdentity struct {
	Method  string `json:"method"`
	Version string `json:"version"`
}

ResourceCollectorIdentity versions the operating-system measurement method. It is serialized with each sample so run and hardware identities cannot silently compare different collectors.

type ResourceSample 

type ResourceSample struct {
	HeapAllocBytes  uint64 `json:"heap_alloc_bytes"`
	TotalAllocBytes uint64 `json:"total_alloc_bytes"`
}

ResourceSample records process heap state and allocations observed across a query. It is evidence, not a performance gate.

type ResourceUnits 

type ResourceUnits struct {
	Wall       string `json:"wall"`
	CPU        string `json:"cpu"`
	PeakRSS    string `json:"peak_rss"`
	HeapAlloc  string `json:"heap_alloc"`
	TotalAlloc string `json:"total_alloc"`
}

ResourceUnits makes every serialized resource unit explicit.

Source Files

View all Source files

Directories

Path Synopsis
cmd
baseline command
Command baseline validates and materializes Cortex-native retrieval evidence.
 Command baseline validates and materializes Cortex-native retrieval evidence.

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.