commitintent

package
v0.41.0 Latest Latest
Warning

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

 Go to latest Published: Jul 14, 2026 License: Apache-2.0 Imports: 15 Imported by: 0

Documentation

Overview

Package commitintent defines the durable, pure queue record that sits before an effectful fak commit drain.

The package deliberately does not run git, inspect the live index, take locks, or push. It validates and orders submit records so a later single-writer drain can consume one deterministic stream.

Index

Constants

View Source 
const (
	QueueSchema  = "fak.commit-intent.queue.v1"
	RecordSchema = "fak.commit-intent.submit.v1"
)
View Source 
const (
	StoreDirName   = "commit-intents"
	StoreQueueFile = "queue.json"
	StoreLockFile  = "queue.lock"
)
View Source 
const SelectionSchema = "fak.commit-intent.quality-selection.v1"

SelectionSchema versions the quality-case selection emitted for a changed surface set.

Variables

View Source 
var (
	ErrMissingField       = errors.New("commitintent: missing field")
	ErrInvalidField       = errors.New("commitintent: invalid field")
	ErrPathDigestMismatch = errors.New("commitintent: path digest mismatch")
	ErrStaleBase          = errors.New("commitintent: stale base")
)

Functions

func DefaultQueueDir 

func DefaultQueueDir(repoRoot string) string

func MarshalQueue 

func MarshalQueue(q Queue) ([]byte, error)

func MarshalRecord 

func MarshalRecord(rec SubmitRecord) ([]byte, error)

func MarshalSelection added in v0.41.0 

func MarshalSelection(sel Selection) ([]byte, error)

MarshalSelection renders a selection as a stable, newline-terminated JSON artifact. The artifact carries only surface labels, changed paths, and provenance identifiers — no request content — so it is safe to attach to a failure as a replay record.

func NormalizeHexDigest 

func NormalizeHexDigest(digest, field string) (string, error)

func NormalizeID 

func NormalizeID(id string) (string, error)

func NormalizePath 

func NormalizePath(raw string) (string, error)

func NormalizePaths 

func NormalizePaths(paths []string) ([]string, error)

func NormalizeSHA 

func NormalizeSHA(sha string) (string, error)

func PathDigest 

func PathDigest(paths []string) string

func Submit 

func Submit(q Queue, now time.Time, intent Intent) (Queue, SubmitRecord, error)

func ValidateIntent 

func ValidateIntent(in Intent) error

func ValidateIntentForBase 

func ValidateIntentForBase(in Intent, currentBaseSHA string) error

func ValidateMetadata 

func ValidateMetadata(meta StampMetadata) error

func ValidateQueue 

func ValidateQueue(q Queue) error

func ValidateRecord 

func ValidateRecord(rec SubmitRecord) error

func ValidateStamp 

func ValidateStamp(stamp Stamp) error

func ValidateState 

func ValidateState(state State) error

func ValidateSubject 

func ValidateSubject(subject string) error

func ValidateTier added in v0.41.0 

func ValidateTier(t Tier) error

ValidateTier reports whether t is one of the explicit PR, nightly, or release tiers a quality case may be assigned to.

Types

type DrainPlan 

type DrainPlan struct {
	Ready   []SubmitRecord  `json:"ready"`
	Stale   []SubmitRecord  `json:"stale"`
	Invalid []InvalidRecord `json:"invalid"`
}

func Drain 

func Drain(records []SubmitRecord, currentBaseSHA string, limit int) DrainPlan

type FieldError 

type FieldError struct {
	Field  string
	Reason string
	Err    error
}

func (FieldError) Error 

func (e FieldError) Error() string

func (FieldError) Unwrap 

func (e FieldError) Unwrap() error

type Intent 

type Intent struct {
	ID         string        `json:"id"`
	BaseSHA    string        `json:"base_sha"`
	Paths      []string      `json:"paths"`
	PathDigest string        `json:"path_digest"`
	DiffDigest string        `json:"diff_digest,omitempty"`
	Subject    string        `json:"subject"`
	Stamp      Stamp         `json:"stamp"`
	Metadata   StampMetadata `json:"metadata,omitempty"`
}

func NormalizeIntent 

func NormalizeIntent(in Intent) (Intent, error)

type InvalidRecord 

type InvalidRecord struct {
	Record SubmitRecord `json:"record"`
	Error  string       `json:"error"`
}

type Provenance added in v0.41.0 

type Provenance struct {
	Model     string `json:"model,omitempty"`
	Tokenizer string `json:"tokenizer,omitempty"`
	Engine    string `json:"engine,omitempty"`
	Oracle    string `json:"oracle"`
	Revision  string `json:"revision"`
	Baseline  string `json:"baseline"`
	Tolerance string `json:"tolerance,omitempty"`
}

Provenance records how a quality case is pinned so a failure is replayable and a pass is trustworthy: the model/tokenizer/engine under test, the seed or deterministic oracle, the code/module revision, and the tolerance/baseline it is scored against. Oracle, Revision, and Baseline are mandatory — without them a "pass" is not independently verifiable.

type QualityCase added in v0.41.0 

type QualityCase struct {
	Surface      Surface    `json:"surface"`
	Tier         Tier       `json:"tier"`
	Cost         string     `json:"cost"`
	Rationale    string     `json:"rationale"`
	MatchedPaths []string   `json:"matched_paths,omitempty"`
	Provenance   Provenance `json:"provenance"`
}

QualityCase is a single case the selector picked for a changed surface, with the tier it runs in, its runtime/resource cost, the rationale for the choice, the changed paths that triggered it, and its provenance.

type Queue 

type Queue struct {
	Schema       string         `json:"schema"`
	NextSequence int64          `json:"next_sequence"`
	Records      []SubmitRecord `json:"records"`
}

func MarkStates 

func MarkStates(q Queue, states map[string]State) (Queue, error)

func NewQueue 

func NewQueue() Queue

func ParseQueue 

func ParseQueue(data []byte) (Queue, error)

type Selection added in v0.41.0 

type Selection struct {
	Schema       string        `json:"schema"`
	Revision     string        `json:"revision"`
	Cases        []QualityCase `json:"cases"`
	UnknownPaths []string      `json:"unknown_paths,omitempty"`
	Expanded     bool          `json:"expanded"`
	Inconclusive bool          `json:"inconclusive"`
}

Selection is the deterministic plan of quality cases for one changed path set. Expanded is set when an unknown path forced full-surface coverage; Inconclusive is set when no path could be classified, so downstream must treat the sentinel-only plan as "unproven", never as a silent empty pass.

func SelectCases added in v0.41.0 

func SelectCases(changed []string, rev string, rules []SurfaceRule) (Selection, error)

SelectCases maps changed onto the quality cases that must run for revision rev. It is pure and deterministic: identical inputs yield an identical Selection. Passing nil rules uses DefaultSurfaceRules.

A changed path that no rule maps is recorded in UnknownPaths and forces Expanded coverage — every surface is selected — because an unclassified change could regress anywhere. When no path can be classified at all the Selection is Inconclusive and carries only the sentinel case, so an empty selection can never be read as "nothing to check".

func SelectForIntent added in v0.41.0 

func SelectForIntent(intent Intent, rules []SurfaceRule) (Selection, error)

SelectForIntent maps a commit intent's normalized changed paths onto the quality cases that must run before the intent drains, using the intent's base SHA as the code/module revision.

type Stamp 

type Stamp struct {
	Kind StampKind `json:"kind"`
	Leaf string    `json:"leaf,omitempty"`
	Text string    `json:"text,omitempty"`
}

func NormalizeStamp 

func NormalizeStamp(stamp Stamp, subject string) (Stamp, error)

func StampFromSubject 

func StampFromSubject(subject string) Stamp

type StampKind 

type StampKind string
const (
	StampNone    StampKind = "none"
	StampTrailer StampKind = "trailer"
	StampDirect  StampKind = "direct"
	StampRelease StampKind = "release"
)

type StampMetadata 

type StampMetadata struct {
	Issue      int      `json:"issue,omitempty"`
	Generation string   `json:"generation,omitempty"`
	Source     string   `json:"source,omitempty"`
	Requester  string   `json:"requester,omitempty"`
	Labels     []string `json:"labels,omitempty"`
}

type State 

type State string
const (
	StatePending  State = "pending"
	StateDraining State = "draining"
	StateDone     State = "done"
	StateFailed   State = "failed"
)

type Store 

type Store struct {
	Dir         string
	Now         func() time.Time
	LockTimeout time.Duration
	RetryDelay  time.Duration
}

func (Store) Drain 

func (s Store) Drain(currentBaseSHA string, limit int) (DrainPlan, error)

func (Store) Load 

func (s Store) Load() (Queue, error)

func (Store) MarkStates 

func (s Store) MarkStates(states map[string]State) (Queue, error)

func (Store) Submit 

func (s Store) Submit(intent Intent) (Queue, SubmitRecord, error)

type SubmitRecord 

type SubmitRecord struct {
	Schema      string    `json:"schema"`
	Sequence    int64     `json:"sequence"`
	SubmittedAt time.Time `json:"submitted_at"`
	State       State     `json:"state"`
	Intent      Intent    `json:"intent"`
}

func Ordered 

func Ordered(records []SubmitRecord) []SubmitRecord

func ParseRecord 

func ParseRecord(data []byte) (SubmitRecord, error)

type Surface added in v0.41.0 

type Surface string

Surface is a quality-bearing engine surface a changed path can touch. A diff is mapped onto surfaces so the matching quality cases run; a path no rule maps is treated as unknown and expands coverage rather than silently passing. 

const (
	SurfaceModel        Surface = "model"
	SurfaceTokenizer    Surface = "tokenizer"
	SurfaceEngine       Surface = "engine"
	SurfaceSampler      Surface = "sampler"
	SurfaceCache        Surface = "cache"
	SurfaceReportRubric Surface = "report-rubric"
	SurfaceSentinel     Surface = "sentinel"
)

type SurfaceRule added in v0.41.0 

type SurfaceRule struct {
	Surface    Surface
	Match      []string
	Tier       Tier
	Cost       string
	Provenance Provenance
}

SurfaceRule maps changed paths onto one Surface. Match holds lowercase path substrings; a changed path whose lowercased form contains any of them selects the rule's surface. Provenance carries the case defaults; its Revision is filled per selection.

func DefaultSurfaceRules added in v0.41.0 

func DefaultSurfaceRules() []SurfaceRule

DefaultSurfaceRules is the built-in diff→surface mapping. Matching is coarse and explainable — a path substring names the surface — so an operator can read why a case was picked. Unmapped paths are handled by expansion, not by silently guessing a surface.

type Tier added in v0.41.0 

type Tier string

Tier is the CI lane a quality case is assigned to. 

const (
	TierPR      Tier = "pr"
	TierNightly Tier = "nightly"
	TierRelease Tier = "release"
)

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.