evidence

package

v0.21.0 Latest Latest Go to latest Published: Oct 29, 2026 License: AGPL-3.0 Imports: 20 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/pblumer/atlas

Links

Open Source Insights

Documentation ¶

Overview ¶

Package evidence keeps and checks the evidence that one built-in Worker Type operation conforms to one technical capability contract (ADR-0483).

A record binds four things a reviewer chose: a published contract, a Worker Type, one of its operations, and the suite whose cases check that operation against the contract. Everything else in it is derived from the module: the contract's digest, the Worker Type's version and job type, the packages every runtime path of the Worker Type goes through and their dependency digest, the suite's digest, the outcome of every case, and the approval rule in force. A record is current exactly when deriving it again gives the bytes on disk, which is what Verify checks and what Renew restores.

The approval itself is not in the file. A string naming a reviewer proves nothing; a record counts as approved once it reached the protected main branch through a pull request the code owner approved or merged, and the file records only which rule that was. A record with a failed or unexercised case is still a current record: it says what the operation does not do, and it verifies no claim.

Published contracts live under workertype/contracts and records under workertype/evidence/records; both paths belong to the code owner. This is build and review tooling: it runs the go command and the suites' fakes, and the engine never calls it.

Index ¶

Constants
func Register(name string, s Suite)
func Verify(ctx context.Context, moduleDir string, raw []byte) error
func VerifyAll(ctx context.Context, moduleDir, dir string) error
type Binding
type Conformance
type ContractRef
type Evidence
- func (e Evidence) Render() ([]byte, error)
type Implementation
type OperationRef
type Result
type StaleError
- func (e *StaleError) Error() string
type Suite

Constants ¶

View Source

const (
	// EvidenceAPIVersion is the first evidence record format.
	EvidenceAPIVersion = "atlas.io/technical-capability-evidence/v1alpha1"
	// EvidenceKind identifies an evidence record.
	EvidenceKind = "TechnicalCapabilityEvidence"
	// ApprovalRepositoryProvenance is the approval rule of ADR-0483's initial phase:
	// the record reached protected main through a pull request the single maintainer
	// approved or merged. Recording it lets a stricter rule tell these records apart.
	ApprovalRepositoryProvenance = "repository-provenance/single-maintainer"
)

View Source

const (
	OutcomePassed       = "passed"
	OutcomeFailed       = "failed"
	OutcomeNotExercised = "not-exercised"
)

The outcomes a case can have. A case the suite could not exercise says so rather than passing or being left out, so a record shows what was not checked.

Variables ¶

This section is empty.

Functions ¶

func Register ¶

func Register(name string, s Suite)

Register adds a suite under the name records use for it. A suite package registers itself from init, and both the gate in workertype/evidence/gate and the evidence command import it, so a record verifies in CI exactly as it renews on a desk. A name registered twice is a programming error.

func Verify ¶

func Verify(ctx context.Context, moduleDir string, raw []byte) error

Verify checks one record's bytes against the module. A record that cannot bind what it names is an error; one whose derived values moved is a StaleError.

func VerifyAll ¶

func VerifyAll(ctx context.Context, moduleDir, dir string) error

VerifyAll checks every record under dir. The directory holds records only, and no two of them bind the same contract to the same operation; a directory that does not exist holds none. Every failing record is reported, each under its path.

Types ¶

type Binding ¶

type Binding struct {
	Contract   string
	WorkerType string
	Operation  string
	Suite      string
}

Binding is what a reviewer chooses when a record is created; the rest is derived.

type Conformance ¶

type Conformance struct {
	Suite       string   `json:"suite"`
	Digest      string   `json:"digest"`
	Environment string   `json:"environment"`
	Results     []Result `json:"results"`
}

Conformance is the suite that checked the operation, the digest of its code and fixtures, what it ran against, and every case's outcome.

type ContractRef ¶

type ContractRef struct {
	Path    string `json:"path"`
	ID      string `json:"id"`
	Version string `json:"version"`
	Profile string `json:"profile,omitempty"`
	Digest  string `json:"digest"`
}

ContractRef names the published contract file and the identity and digest of its bytes. The digest is the one value renewal never changes: a published contract does not change, and new bytes need a new version.

type Evidence ¶

type Evidence struct {
	APIVersion     string         `json:"apiVersion"`
	Kind           string         `json:"kind"`
	Contract       ContractRef    `json:"contract"`
	Operation      OperationRef   `json:"operation"`
	Implementation Implementation `json:"implementation"`
	Conformance    Conformance    `json:"conformance"`
	Approval       string         `json:"approval"`
}

Evidence is one record: which contract, which operation, what implements it, what was checked and with which outcome.

func Create ¶

func Create(ctx context.Context, moduleDir string, b Binding) (Evidence, error)

Create derives a new record for a binding.

func ParseEvidenceJSON ¶

func ParseEvidenceJSON(raw []byte) (Evidence, error)

ParseEvidenceJSON decodes one complete record. Unknown fields, a second JSON value and missing or malformed values are refused; parsing does not check the record against the module, which is Verify's work.

func Renew ¶

func Renew(ctx context.Context, moduleDir string, rec Evidence) (Evidence, error)

Renew derives a record again from what it binds. It keeps the recorded contract digest: a published contract does not change, so contract bytes that moved are an error, not something renewal records.

func (Evidence) Render ¶

func (e Evidence) Render() ([]byte, error)

Render is the one rendering of a record: two-space indentation, fields in format order, a final newline. Verify compares bytes, so a record is kept as Render writes it.

type Implementation ¶

type Implementation struct {
	Roots  []string `json:"roots"`
	Digest string   `json:"digest"`
}

Implementation is what runs the operation: the root packages of every path the Worker Type can run on and the dependency digest of their closure.

type OperationRef ¶

type OperationRef struct {
	WorkerType        string `json:"workerType"`
	WorkerTypeVersion string `json:"workerTypeVersion"`
	ID                string `json:"id"`
	JobType           string `json:"jobType"`
}

OperationRef names the Worker Type operation the evidence is about.

type Result ¶

type Result struct {
	Case    string `json:"case"`
	Outcome string `json:"outcome"`
	Detail  string `json:"detail,omitempty"`
}

Result is one case's outcome. Detail says why a case failed or was not exercised.

type StaleError ¶

type StaleError struct {
	// Parts names what moved: "operation", "implementation", "conformance", or
	// "format" when only the rendering differs.
	Parts []string
}

StaleError is a record that no longer matches the module: what it binds is still there, but something derived from it moved. Renewing it in the same change is the remedy ADR-0483 requires.

func (*StaleError) Error ¶

func (e *StaleError) Error() string

type Suite ¶

type Suite struct {
	// Package is the import path of the suite's code and fixtures. Its dependency
	// digest is the fixture revision a record carries, and it includes the
	// schema validator's version through go.sum.
	Package string
	// Environment states what the cases ran against, for the reviewer.
	Environment string
	// Run executes every case, in a fixed order, and reports each outcome. It
	// fails only when the suite cannot run at all.
	Run func(ctx context.Context, contract workertype.TechnicalContract) ([]Result, error)
}

Suite is the executable cases that check one operation against one contract. The cases run in process against a fake of the provider, so a record can be renewed and verified anywhere, without a tenant or a credential; what a fake cannot show is a case the suite reports as not exercised, and Environment says what it ran against.

Source Files ¶

View all Source files

Directories ¶

Path	Synopsis
cmd
evidence command Command evidence creates, renews and verifies the conformance evidence records of built-in Worker Types, and prints the dependency digest of any set of packages (ADR-0483).	Command evidence creates, renews and verifies the conformance evidence records of built-in Worker Types, and prints the dependency digest of any set of packages (ADR-0483).
gate Package gate holds the CI check over the evidence records in workertype/evidence/records and nothing else: its test verifies every record against the module, with every registered suite, so a change that moves what a record binds fails until the same change renews the record (ADR-0483).	Package gate holds the CI check over the evidence records in workertype/evidence/records and nothing else: its test verifies every record against the module, with every registered suite, so a change that moves what a record binds fails until the same change renews the record (ADR-0483).

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL