Documentation
¶
Overview ¶
Package gate decides whether a skill version may be published, held for review, or refused outright. It is pure: no database, no HTTP, no clock.
Index ¶
Constants ¶
const ( // ClassExfiltration and ClassSecret are unappealable. No evaluation // overrides credential theft: a sandbox observing sixty well-behaved // runs does not prove the sixty-first will not post a token somewhere. ClassExfiltration = scan.ClassExfiltration ClassSecret = scan.ClassSecret // The rest are guesses the scanner makes from shape alone, which is // exactly what running the skill in a network-off sandbox measures // directly. ClassExecution = scan.ClassExecution ClassInjection = scan.ClassInjection ClassHeuristic = scan.ClassHeuristic )
const ( ReasonScan = "scan" ReasonOwnership = "ownership" )
Hold reason kinds. These are persisted in skill_versions.hold_reasons and in version_approvals.reason, so they are a wire contract: renaming one makes every in-flight hold unclearable.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Class ¶
Class groups a scan finding by what kind of claim it makes. Severity says how confident the scanner is; class says whether an empirical measurement could ever overturn it.
The vocabulary itself lives in internal/scan (see scan/class.go): scan already needs it to populate Finding.Class as rules fire, and gate needs scan's report types for Decide, so the type must live on the side with no outgoing edge back to the other. Class is a type alias (not a defined type) precisely so gate.Class and scan.Class stay interchangeable and every existing gate.ClassExecution / gate.ClassOf callsite keeps compiling and reading naturally.
func ClassOf ¶
ClassOf maps a scan rule category onto a Class. The bool is false for an unmapped category; callers must not substitute a default, because every plausible default is wrong in one direction or the other. Decide treats an unmapped class as Block, and TestEveryRuleHasAClass keeps that unreachable from the native rule set.
type Decision ¶
type Decision struct {
Outcome Outcome `json:"outcome"`
Reasons []Reason `json:"reasons"`
// HoldReasons are the reason kinds that must each be cleared before this
// version may be served. Empty means nothing is holding it. It is a set,
// not a state, because a scan finding and an unowned publisher are two
// different questions and neither may be used to launder the other.
HoldReasons []string `json:"hold_reasons"`
// Ownership is present only when ownership was evaluated.
Ownership *OwnershipDetail `json:"ownership,omitempty"`
}
Decision is the whole verdict. It is persisted as an object rather than a bare array of reasons: json.Marshal on a nil slice emits null, and a null in a column declared NOT NULL DEFAULT '[]' makes "no reasons" and "never written" indistinguishable while breaking jsonb_array_length.
func Decide ¶
func Decide(rep scan.Report, q *QualityState, o OwnerState, p Policy) Decision
Decide maps a scan report, an optional quality state, and the publisher's ownership standing onto an outcome. It is pure: no database, no HTTP, no clock, no context.
type OwnerRef ¶
type OwnerRef struct {
ID string `json:"id"`
Name string `json:"name"`
Email string `json:"email"`
}
OwnerRef identifies one owner well enough for a CLI or a UI to name them. Decide is pure and cannot look users up, so the caller passes them in.
type OwnerState ¶
type OwnerState struct {
Evaluated bool
IsOwner bool
Unowned bool
RulePattern string
Owners []OwnerRef
}
OwnerState is what is known about who owns the skill being published to.
Evaluated is false when ownership was not determined at all — the CLI's local pre-scan, which has no way to ask. An unevaluated state contributes nothing, so local behaviour is byte-for-byte what it was before ownership existed.
IsOwner already folds in instance privilege: an owner or admin is an implicit owner of everything. Resolving that at the HTTP boundary keeps this package free of auth and keeps the privilege check to one call site, exactly as Policy.AdminOverride does.
type OwnershipDetail ¶
type OwnershipDetail struct {
RulePattern string `json:"rule_pattern,omitempty"`
Owners []OwnerRef `json:"owners"`
Clears string `json:"clears"`
}
OwnershipDetail is the ownership half of a decision, rendered by the CLI and the review screen. Naming the humans who can unblock a publisher is what turns a wall into a next step.
type Policy ¶
type Policy struct {
// Floor is the minimum headline score a verified report must reach to
// clear a NeedsReview. 0 means any verified report clears, provided the
// other conditions hold.
Floor float64
// AdminOverride is the already-resolved answer to "may this caller
// override, and did they ask to". Resolving it at the HTTP boundary and
// passing the answer keeps Decide pure and keeps the privilege check to
// exactly one call site, so re-pointing it at an audited authorizer
// later is a one-function change.
AdminOverride bool
}
Policy is the deployment's configuration.
type QualityState ¶
type QualityState struct {
Verified bool
PanelComplete bool
Headline float64
CriticalForbidViolations int
}
QualityState is what is known about the version's measured behaviour. A nil *QualityState means no measurement exists — never a zero score. A zero headline means the skill scored nothing, which is the opposite claim.
type Reason ¶
type Reason struct {
Rule string `json:"rule"`
Class string `json:"class"`
Severity string `json:"severity"`
File string `json:"file"`
Line int `json:"line"`
Message string `json:"message"`
// Clears states in one sentence what would resolve this finding.
Clears string `json:"clears"`
}
Reason is one finding that drove the decision, together with what would clear it. It is part of the contract, not a debug aid: the CLI renders it and the review UI consumes it.