Help us shape the future of Go! Take the 2026 Go Developer Survey

failureknowledge

package
v0.55.5 Latest Latest
Warning

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

 Go to latest Published: Nov 1, 2026 License: Apache-2.0 Imports: 25 Imported by: 0

Documentation

Overview

Package failureknowledge holds the offline failure resolution snapshot: a versioned SQLite FTS5 database of promoted failure resolutions that ships with StackKits releases, and its lookup.

A resolution names normalized failure signatures (fk-normalizer), where it applies, the root cause and fix steps as references to StackKits or Techstack procedures. The snapshot holds no installation, tenant or subject data; it is knowledge, never execution authority. A fix runs only through the referenced product procedure.

The snapshot is built from a resolution catalog (schema kombify.failure-resolution-catalog/v1) exported from the curated catalog. Lookup runs offline: exact signature first, then FTS5 lexical search, and a semantic step only when a local Ollama with bge-m3 is configured, against the BGE-M3 vectors the snapshot carries.

Index

Constants

View Source 
const (
	// CatalogSchema is the catalog format the snapshot is built from.
	CatalogSchema = "kombify.failure-resolution-catalog/v1"
	// SnapshotSchema versions the SQLite layout.
	SnapshotSchema = "stackkits.failure-snapshot/v1"
	// SnapshotFileName is the snapshot's name in release archives and beside
	// an installed CLI.
	SnapshotFileName = "failure-resolutions.sqlite"
	// SnapshotEnv overrides where the CLI finds the snapshot.
	SnapshotEnv = "STACKKIT_FAILURE_SNAPSHOT"
	// VectorDimensions is the BGE-M3 dense dimension.
	VectorDimensions = 1024
)
View Source 
const (
	// OllamaURLEnv names a local Ollama that serves bge-m3; without it the
	// semantic step does not run.
	OllamaURLEnv = "STACKKIT_FAILURE_OLLAMA_URL"
)

Variables

This section is empty.

Functions

func DefaultSnapshotPath 

func DefaultSnapshotPath() (string, bool)

DefaultSnapshotPath finds the snapshot: STACKKIT_FAILURE_SNAPSHOT, else beside the executable, in its bin directory or in ../lib/stackkit, where release archives and installers place it.

Types

type Applicability 

type Applicability struct {
	StackKitModules   []string `json:"stackkitModules,omitempty"`
	StackKitVersions  []string `json:"stackkitVersions,omitempty"`
	AppVersions       []string `json:"appVersions,omitempty"`
	OS                []string `json:"os,omitempty"`
	OSVersions        []string `json:"osVersions,omitempty"`
	Arch              []string `json:"arch,omitempty"`
	ContainerRuntimes []string `json:"containerRuntimes,omitempty"`
	Providers         []string `json:"providers,omitempty"`
	DeviceClasses     []string `json:"deviceClasses,omitempty"`
}

Applicability lists the contexts a resolution applies to; an empty dimension applies everywhere.

type Catalog 

type Catalog struct {
	Schema         string          `json:"schema"`
	GeneratedAt    time.Time       `json:"generatedAt"`
	Dimensions     int             `json:"dimensions"`
	VectorEncoding string          `json:"vectorEncoding"`
	Truncated      bool            `json:"truncated"`
	Resolutions    []CatalogRecord `json:"resolutions"`
}

Catalog is the export of promoted resolutions the snapshot is built from.

func LoadCatalog 

func LoadCatalog(path string) (Catalog, string, error)

LoadCatalog reads and validates a catalog file and returns it with the SHA-256 of its bytes.

type CatalogRecord 

type CatalogRecord struct {
	ID             string        `json:"id"`
	Title          string        `json:"title"`
	Symptoms       []Symptom     `json:"symptoms"`
	Applicability  Applicability `json:"applicability"`
	RootCause      string        `json:"rootCause"`
	FixSteps       []FixStep     `json:"fixSteps"`
	Evidence       Evidence      `json:"evidence"`
	Revision       int           `json:"revision"`
	ReviewedAt     *time.Time    `json:"reviewedAt,omitempty"`
	SymptomText    string        `json:"symptomText"`
	BodyText       string        `json:"bodyText"`
	EmbeddingModel string        `json:"embeddingModel,omitempty"`
	Embedding      string        `json:"embedding,omitempty"`
}

CatalogRecord is one promoted resolution of the catalog.

type Evidence 

type Evidence struct {
	SuccessCount int     `json:"successCount"`
	FailureCount int     `json:"failureCount"`
	SuccessRate  float64 `json:"successRate"`
}

Evidence is the verified outcome count of a resolution.

type FixStep 

type FixStep struct {
	Product   string `json:"product"`
	Procedure string `json:"procedure"`
	Summary   string `json:"summary,omitempty"`
}

FixStep references a product procedure; it is never a command.

type Leg 

type Leg struct {
	Name    string `json:"name"`
	State   string `json:"state"`
	Matches int    `json:"matches"`
	Detail  string `json:"detail,omitempty"`
}

Leg reports how one lookup step ran.

type Match 

type Match struct {
	Rank  int            `json:"rank"`
	Match string         `json:"match"`
	Score float64        `json:"score"`
	Ranks map[string]int `json:"ranks"`
	// Similarity is the cosine similarity of the semantic step, when it ran.
	Similarity *float64   `json:"similarity,omitempty"`
	Resolution Resolution `json:"resolution"`
}

Match is one lookup result.

type Query 

type Query struct {
	Signature string
	Text      string
	TopK      int
	// OllamaURL enables the semantic step; empty skips it.
	OllamaURL string
}

Query is a normalized failure signature, a free-text description, or both.

type Resolution 

type Resolution struct {
	ID            string        `json:"id"`
	Title         string        `json:"title"`
	Symptoms      []Symptom     `json:"symptoms"`
	Applicability Applicability `json:"applicability"`
	RootCause     string        `json:"rootCause"`
	FixSteps      []FixStep     `json:"fixSteps"`
	Evidence      Evidence      `json:"evidence"`
	Revision      int           `json:"revision"`
	ReviewedAt    string        `json:"reviewedAt,omitempty"`
}

Resolution is a promoted resolution as the snapshot holds it.

type Result 

type Result struct {
	Snapshot SnapshotInfo `json:"snapshot"`
	Results  []Match      `json:"results"`
	Legs     []Leg        `json:"legs"`
	Advisory bool         `json:"advisory"`
}

Result is the lookup answer. A resolution is advisory: a fix runs only through the referenced product procedure.

type Snapshot 

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

Snapshot is an opened, read-only snapshot.

func OpenSnapshot 

func OpenSnapshot(ctx context.Context, path string) (*Snapshot, error)

OpenSnapshot opens a snapshot read-only and checks its schema.

func (*Snapshot) Close 

func (s *Snapshot) Close() error

Close releases the snapshot.

func (*Snapshot) Info 

func (s *Snapshot) Info() SnapshotInfo

Info describes the opened snapshot.

func (*Snapshot) Lookup 

func (s *Snapshot) Lookup(ctx context.Context, query Query) (Result, error)

Lookup runs the offline lookup: exact signature, then FTS5 lexical and, with a local bge-m3, semantic search, fused by reciprocal rank. Signature matches rank first.

type SnapshotInfo 

type SnapshotInfo struct {
	Schema             string `json:"schema"`
	Version            string `json:"version"`
	CatalogGeneratedAt string `json:"catalogGeneratedAt"`
	CatalogSHA256      string `json:"catalogSha256"`
	Resolutions        int    `json:"resolutions"`
	Signatures         int    `json:"signatures"`
	Vectors            int    `json:"vectors"`
	EmbeddingModel     string `json:"embeddingModel,omitempty"`
	Path               string `json:"path,omitempty"`
}

SnapshotInfo describes a built or opened snapshot.

func BuildSnapshot 

func BuildSnapshot(ctx context.Context, catalog Catalog, catalogSHA256, output string) (SnapshotInfo, error)

BuildSnapshot writes a new snapshot of the catalog to output. The file is written beside output and renamed into place, so a reader never sees a partial snapshot.

type Symptom 

type Symptom struct {
	Signature         string `json:"signature"`
	NormalizerVersion string `json:"normalizerVersion,omitempty"`
	Component         string `json:"component,omitempty"`
	Phase             string `json:"phase,omitempty"`
	ErrorCode         string `json:"errorCode,omitempty"`
	Template          string `json:"template,omitempty"`
}

Symptom is one normalized failure symptom.

Source Files

View all Source files

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.