check

type BrowserExpectation struct {
	Static bool
	// Attached is what the page must be given: the integration settings as
	// they are now.
	Attached map[string]string
	// Installed is what the running container was started with, read from the
	// container itself; nil when that could not be established.
	Installed map[string]string
}

type ChecklistMeta struct {
	Served     string // the model the provider actually served
	PromptHash string
	Items      int
	Cost       float64
	Tokens     Tokens
	ParseError bool
	Retried    bool // the answer was asked for twice: the first was not JSON
}

type Completer interface {
	Complete(ctx context.Context, system, user string) (Completion, error)
}

type CompleterFunc func(ctx context.Context, system, user string) (Completion, error)

type Completion struct {
	Text   string
	Model  string // the model the provider actually served
	Tokens Tokens
	Cost   float64
}

type Declaration struct {
	Name      string `json:"name"`
	Title     string `json:"title,omitempty"`     // authored action title for a remediation; identity remains Name
	Expects   string `json:"expects"`             // one plain sentence: what conformance looks like
	Severity  string `json:"severity,omitempty"`  // note|low|medium|high (default note)
	Evaluator string `json:"evaluator,omitempty"` // sh|llm|runtime|tool (default sh when sh set, llm when rubric set, tool when tool set)
	Sh        string `json:"sh,omitempty"`
	Rubric    string `json:"rubric,omitempty"`
	Probe     string `json:"probe,omitempty"` // runtime evaluator: a probe against the booted app
	Tool      string `json:"tool,omitempty"`  // tool evaluator: names a scanner binding to run (design/subsystems/conformance.md §13)
	// Scope says what the check is ABOUT (design/subsystems/conformance-surface.md §2):
	// "tree" — a state of the committed tree, judged at the gate AND in every
	// fleet review; "diff" — a transition made by one change, judged at the gate
	// only. sh/tool/runtime are always tree. An llm rubric defaults to diff (the
	// meaning every existing block version has) and may declare tree, in which
	// case Files names the evidence the rubric is judged on.
	Scope string   `json:"scope,omitempty"`
	Files []string `json:"files,omitempty"`
	// Occurrences says how the check reports WHAT it found: "lines" — one
	// occurrence per output line, so a gate can tell a pre-existing finding
	// from a new one (design/subsystems/ways-of-working-versions.md §4.2). Unset: the
	// check is boolean; failing on both trees is "regression unknown".
	Occurrences string `json:"occurrences,omitempty"`
	// AppliesTo says what the check applies to, in words about the app's
	// declared parts (applies.go). Required: a check that applies to no
	// declared part is not applicable, never a pass on nothing.
	AppliesTo []string `json:"appliesTo,omitempty"`
}

type Declared struct {
	Identity
	Declaration
}

type Evaluation struct {
	Declared
	Mode        Mode
	Outcome     Outcome
	Detail      string
	Findings    []Finding
	Occurrences []string
	Evidence    Evidence
	// Fault: the judge failed, not the tree. A change must never be sent back
	// to its author over one.
	Fault bool
}

type Evidence struct {
	EvaluatorVersion string // the identity a verdict keys on; unchanged strings
	Hash             string // hash of the evidence bundle judged
	PromptHash       string // model calls only
	Report           string // the report a tool wrote and the judge read; "" = none
	Image            string // the image (by ID) an exec-image check ran in; "" = none
	Files            []string
	Output           string
	ExitCode         *int
	Duration         time.Duration
	Tokens           Tokens
}

type Fetcher interface {
	Fetch(ctx context.Context, url string) (int, string, error)
}

type FetcherFunc func(ctx context.Context, url string) (int, string, error)

type Finding struct {
	Fingerprint string      `json:"fingerprint"`
	Kind        string      `json:"kind"`     // vuln | secret | sast | license
	Severity    string      `json:"severity"` // critical|high|medium|low|unknown
	Identifiers []string    `json:"identifiers,omitempty"`
	Package     *PackageRef `json:"package,omitempty"`
	Location    *Location   `json:"location,omitempty"`
	Title       string      `json:"title"`
	Detail      string      `json:"detail,omitempty"`
	URL         string      `json:"url,omitempty"`
	Source      string      `json:"source"` // binding name
	// Reached: osv-scanner call analysis — does the program actually call the
	// vulnerable code? nil = no data. VEX-grade context: an unreached vuln is
	// the textbook not_affected justification. Never changes the verdict by
	// itself; dispositions stay a human act.
	Reached *bool `json:"reached,omitempty"`
	// Items: the occurrences a conformance check reported (one per line when
	// the check declares occurrences: lines), so a gate can subtract what
	// already fails on the base tree and count only what is new.
	Items []string `json:"items,omitempty"`
}

type Identity struct {
	Namespace string
	Version   int
}

type Item struct {
	Declared
	Scope    string // tree | diff
	Evidence string // packed files for tree; "" for diff (the shared diff is attached once)
	Files    []string
	Hash     string // hash of the exact evidence this item is judged on
	// Unreadable says why the item's evidence could not be read: it is not
	// put to the model, and its judgement is cannot-assess.
	Unreadable string
}

type Judge struct {
	// Run executes one container. The caller supplies it rather than a bare
	// execution.Runner because a host adds its own cache mounts, labels and
	// ownership to every run it owns.
	Run func(execution.Request) execution.Outcome
	// ShImage is the image sh checks run in, the tool versions' shell, from
	// the snapshot the caller's unit of work took. "": they error.
	ShImage string
	// Complete asks a model for one answer. nil: rubrics cannot be assessed.
	Complete Completer
	// Probe makes one HTTP request. nil: runtime checks cannot be assessed.
	Probe Prober
	// Scanners resolves a tool check's name to the tool it names. nil: tool
	// checks cannot be assessed.
	Scanners Scanners
	// RunImage runs a command INSIDE an already-built image, with nothing
	// mounted: the exec-image self-check, which must see the app as the app
	// sees itself. nil: those checks cannot be assessed.
	RunImage func(image string, argv, env []string) (exitCode int, output string)
	// Readiness resolves what path a `readiness` probe means for this source —
	// the app's own declaration, which only the caller can read. nil or false:
	// the check reports does-not-conform, as an app that is served while
	// declaring nothing about when it is ready has not met the way of working.
	Readiness func(src Source) (string, bool)
	// NamePrefix names the containers a run owns, so a host can find them.
	NamePrefix string
	// Now is the judge's clock, for how long an evaluation took; nil is the
	// real clock.
	Now func() time.Time
}

type Judged struct {
	Evaluation
	Provenance  Provenance
	Own         []Finding
	PreExisting []Finding
}

type Location struct {
	File string `json:"file"`
	Line int    `json:"line,omitempty"`
}

type Mode int

type Outcome int

type PackageRef struct {
	Name      string `json:"name"`
	Version   string `json:"version,omitempty"`
	Ecosystem string `json:"ecosystem,omitempty"`
	FixedIn   string `json:"fixedIn,omitempty"`
}

type PageProbe struct {
	URL     string
	Host    string
	Headers map[string]string
}

type Part struct {
	Name string
	// Folder is the part's folder relative to the repository root ("." for
	// the root); "" for a part with none (a pulled image), which is judged
	// at the root.
	Folder string
	Kinds  []string // KindBuild, KindStatic, KindContainer
	Tools  []string // what the part is built with
	Public bool
}

type Place struct {
	Folder string   // relative to the repository root; "." is the root
	Parts  []string // sorted; nil for a repository run
}

type ProbeSpec struct {
	Path       string
	Expect     int
	Readiness  bool // resolve the path from the contract's declared readiness
	BrowserEnv bool // judge the page against AppTown's /_apptown/env.js
	Page       bool // judge the front page through the front door (JudgePage)
	// MemoryDeclared judges the contract, not the running app.
	MemoryDeclared bool
	// MemoryWithin is the share of its applied limit, in percent, a part of
	// the standing deployment must stay under; 0 when the probe is another.
	MemoryWithin int
}

type ProbeVerdict struct {
	Outcome Outcome
	Detail  string
	Fault   bool
}

type Prober interface {
	Probe(ctx context.Context, url string) (int, error)
}

type ProberFunc func(ctx context.Context, url string) (int, error)

type Provenance int

type Scanner struct {
	Name        string   `yaml:"name" json:"name"`
	Description string   `yaml:"description" json:"description"`
	Image       string   `yaml:"image" json:"image"`
	Command     []string `yaml:"command" json:"command"`
	Report      string   `yaml:"report" json:"report"`
	Network     bool     `yaml:"network" json:"network"`
	// Format enables the structured-findings layer (findings.md): osv | sarif.
	// Empty = exit-code contract only. Kind labels SARIF findings (secret|sast|license).
	Format string `yaml:"format" json:"format"`
	Kind   string `yaml:"kind" json:"kind"`
	// ArtifactKind overrides the report artifact's kind (default scan-report);
	// e.g. "sbom" for syft — evidence of what shipped, not findings.
	ArtifactKind string `yaml:"artifactKind" json:"artifactKind"`
	// Target: what the scanner looks at — "source" (the committed tree,
	// default), "image" (the app's built container image, handed over
	// as a saved tarball at /work/.apptown/image.tar; use ${IMAGE_TAR} in
	// the command), or "exec-image" (run the command INSIDE the app's built
	// image — a framework self-check that must import settings;
	// design/subsystems/conformance.md §13.5). Scan POINTS in system workflows
	// (`with: {on: image}`) expand to every attached scanner with the matching
	// target (design/decisions/workflows-as-lanes.md).
	Target string `yaml:"target" json:"target"`
	// HistoryCommand: a source scanner that can read Git history checks,
	// at a landing, every commit the landing brings to the default branch,
	// not only its final tree: this command runs instead of Command, with
	// the project's repository mounted read-only at /history and
	// ${HISTORY_RANGE} naming those commits (target..candidate). A secret
	// added in one commit and removed in the next still lands in history,
	// which only a history scan sees.
	HistoryCommand []string `yaml:"historyCommand" json:"historyCommand"`
	// Manual: this scanner is invoked ONLY by name (a way-of-working `tool`
	// check, design/subsystems/conformance.md §13), never auto-expanded at a scan point.
	// It keeps a way-of-working-specific tool (a Django linter) from firing
	// fleet-wide the way a universal scanner (gitleaks) does.
	Manual bool `yaml:"manual" json:"manual"`
	// NoEntrypoint clears the image's entrypoint, so Command (and
	// HistoryCommand) is the whole command: a networked scanner whose image starts its program directly
	// runs the extra certificates' script first (internal/trust) with
	// ["sh", "-c", "eval \"${APPTOWN_TRUST:-}\"; exec \"$@\"", "sh", <program>, ...].
	NoEntrypoint bool `yaml:"noEntrypoint" json:"noEntrypoint"`
	// AppliesTo is what a scan-point scanner applies to (applies.go),
	// required for one that is not manual; a manual scanner takes the
	// applicability of the check that names it and declares none.
	AppliesTo []string `yaml:"appliesTo" json:"appliesTo,omitempty"`
	// EmptyExit is the exit the tool gives when it found nothing to judge
	// (osv-scanner's 128, "no package sources found"). Where the scanner
	// applies, that is a failure: the contract says there is something to
	// judge. 0: the tool has no such exit.
	EmptyExit int `yaml:"emptyExit" json:"emptyExit,omitempty"`
}

type Scanners interface {
	Scanner(name string) (Scanner, bool)
}

type ScannersFunc func(name string) (Scanner, bool)

type Source struct {
	Tree  string // a read-only checkout of the exact commit; the caller stages it
	SHA   string
	Diff  string // for diff-scoped rubrics; "" in a review
	Image string // built app image reference for exec-image tools; "" = not available
	// Env is what an exec-image tool runs with: the environment of a deployed
	// app, derived by the caller from what the app declares.
	Env []string
	App string // base URL of a booted app for runtime probes; "" = not available
	// Naked: the same app reached by address with no front-door signal. "" when
	// only one door is reachable.
	Naked string
	// What applicability reads (applies.go): the app's declared parts,
	// whether the tree holds no file, whether there is no contract at all,
	// a contract that could not be read, and the folders the contract says
	// are not the app's code.
	Parts      []Part
	Empty      bool
	NoContract bool
	PartsErr   error
	NotAppCode []string
}

type Tokens struct {
	Input  int64
	Output int64
}

type Verdict struct {
	Item     int    `json:"item"`
	Verdict  string `json:"verdict"`
	Evidence string `json:"evidence"`
	Note     string `json:"note"`
}