claims

Documentation

Overview

Package claims implements the v1.4 Session 6 (Sol Phase 11) machine-verified documentation ledger: docs/claims.yaml maps each feature claim to the concrete, checkable facts that back it (implementation symbols, CLI reachability, tests, integration tests, acceptance artifacts, and binary build evidence), and Verify re-derives those facts from the repository on every CI run instead of trusting a hand-written status field. This is what makes "implemented," "tested," "accepted," and "shipped" mechanically distinct: each is a computed boolean gated on the one below it, not a claim's own say-so.

Index

• Constants
• Variables
• func Report(results []Result) (string, int)
• type ArtifactRef
• type BinaryEvidence
• type BuildManifest
• type CLIRef
• type Claim
• type Document
  • func Load(path string) (Document, error)
• type FileFuncs
• type FileSymbols
• type Result
  • func Verify(repoRoot string, doc Document) ([]Result, error)
  • func VerifyWithOptions(repoRoot string, doc Document, opts VerifyOptions) ([]Result, error)
  • func (r Result) OK() bool
• type VerifyOptions

Constants

const (
	MaturityUnimplemented = "unimplemented"
	MaturityImplemented   = "implemented"
	MaturityTested        = "tested"
	MaturityAccepted      = "accepted"
	MaturityShipped       = "shipped"
)

Maturity levels, in ascending order. Each requires every level below it to hold, plus its own additional check — see Result.Computed.

const (
	ScopeImplemented        = "implemented"
	ScopePartial            = "partial"
	ScopePlatformDependent  = "platform-dependent"
	ScopeDevelopmentOnly    = "development-only"
	ScopeProductionRequired = "production-required"
)

Variables

var VersionTagSourceForTesting func(repoRoot, tag string) (string, error)

VersionTagSourceForTesting is a TEST-ONLY seam (Sol14 rc7 Session 9a, P1-2). When non-nil, verifyVersionTagProvenance resolves a version's tag through it instead of `git rev-parse <tag>^{commit}` against repoRoot, so the version/tag provenance COMPARISON can be exercised deterministically on any checkout. It must return the commit the tag points at, or an error meaning "no such tag" (which this function treats as nothing to compare, exactly as a failing git rev-parse does).

Before this seam, TestV6Case36UntaggedPostV1TagSourcePackagedAsV1IsRejected depended on the live checkout happening to have a reachable tag with HEAD several commits past it -- it skipped on a checkout sitting exactly at a tag, and on any clone fetched without tags. It was therefore carried as an OPEN GAP exclusion, which Sol14 P1-2 rejects as durable release policy.

The seam replaces only the tag->commit LOOKUP. The provenance rule under test -- a version naming a tag whose commit differs from the evidence commit must be rejected -- still runs for real against the injected pair, so the assertion is the production one. Production code MUST NEVER set this; only _test.go code and the redteam corpus assign it (and defer restoring nil), mirroring containment.ExtinguishGateForTesting.

Functions

func Report

func Report(results []Result) (string, int)

Report renders results as a doctor-style checklist, one line per claim, most-severe (lowest computed vs. claimed) first, and returns the process exit code CI should use.

Types

type ArtifactRef

type ArtifactRef struct {
	Path    string `yaml:"path"`
	Pointer string `yaml:"pointer,omitempty"`
}

ArtifactRef points at a real acceptance-evidence file. Pointer, if set, is a dot-separated path into that file's parsed JSON that must resolve to a present key (e.g. "acceptance_evidence.4_safe_pre_mutation_fallback").

type BinaryEvidence

type BinaryEvidence struct {
	EvidenceFile string `yaml:"evidence_file"`
	Commit       string `yaml:"commit"`
	Platform     string `yaml:"platform,omitempty"`
	ArtifactPath string `yaml:"artifact_path,omitempty"`
	ManifestPath string `yaml:"manifest_path,omitempty"`
	Version      string `yaml:"version,omitempty"`
}

BinaryEvidence points at the commit and evidence file recording the rebuilt-binary proof that Commit's code was actually shipped, not merely merged. Platform, if set, additionally requires that evidence file's binaries list to carry a non-empty sha256 for that platform.

type BuildManifest

type BuildManifest struct {
	Version       string `json:"version"`
	SourceCommit  string `json:"source_commit"`
	GoVersion     string `json:"go_version"`
	BuildFlags    string `json:"build_flags"`
	ArchivePath   string `json:"archive_path"`
	ArchiveSHA256 string `json:"archive_sha256"`
	// ExecutablePath/ExecutableSHA256 are the rc8-upg15 S3 (Sol15 P2-2)
	// canonical names: archive_path names an archive, executable_path names
	// the contained/extracted binary itself -- the ambiguity Sol found in
	// the old artifact_path/artifact_sha256 pair (one path label serving
	// both an archive and the binary it contains). ExtractedBinarySHA256 and
	// ArtifactPath/ArtifactSHA256 remain for one release as deprecated
	// aliases (see docs/migration.md); expectedExtractedBinarySHA256 prefers
	// ExecutableSHA256 first.
	ExecutablePath        string            `json:"executable_path,omitempty"`
	ExecutableSHA256      string            `json:"executable_sha256,omitempty"`
	ExtractedBinarySHA256 string            `json:"extracted_binary_sha256,omitempty"`
	ArtifactPath          string            `json:"artifact_path,omitempty"`
	ArtifactSHA256        string            `json:"artifact_sha256,omitempty"`
	BuildInfo             map[string]string `json:"build_info"`
	ClaimsHash            string            `json:"claims_hash"`
	TestRunID             string            `json:"test_run_id"`
	TestResult            string            `json:"test_result"`
	TestSummaryPath       string            `json:"test_summary_path"`
	AcceptanceRunID       string            `json:"acceptance_run_id"`
	AcceptanceResult      string            `json:"acceptance_result"`
}

type CLIRef

type CLIRef struct {
	Command string `yaml:"command"`
}

CLIRef declares the gov command line a claim must be reachable from. Command may be a multi-word command ("gov ask approve"); every word after "gov" is checked against every `case "<word>":` label found anywhere under cmd/gov — a heuristic that confirms the verbs exist as dispatch targets, not that they nest exactly as written.

type Claim

type Claim struct {
	ID                  string          `yaml:"id"`
	Title               string          `yaml:"title"`
	FirstShippedVersion string          `yaml:"first_shipped_version"`
	ClaimedMaturity     string          `yaml:"claimed_maturity"`
	Implementation      []FileSymbols   `yaml:"implementation"`
	CLI                 *CLIRef         `yaml:"cli,omitempty"`
	Tests               []FileFuncs     `yaml:"tests"`
	IntegrationTests    []FileFuncs     `yaml:"integration_tests,omitempty"`
	AcceptanceArtifacts []ArtifactRef   `yaml:"acceptance_artifacts,omitempty"`
	BinaryBuildEvidence *BinaryEvidence `yaml:"binary_build_evidence,omitempty"`
	// RedteamCases lists internal/redteam/manifest.yaml case numbers this
	// claim's "shipped" maturity depends on (Sol v7 S7, secondary finding 5:
	// "claims verification rejects evidence ... and fails when a claim
	// exceeds executable enforcement"). A claim naming case 4 ("narrow
	// Landlock is enforced") must have case 4 actually passing in the
	// shipped binary's redteam evidence, not merely skipped or absent —
	// verifyShipped checks this against the manifest and the evidence
	// file's identity_gate results.
	RedteamCases []int `yaml:"redteam_cases,omitempty"`

	// ClaimScope is P1-7 (Sol10 rc4 Session 8): "introduce claim states
	// implemented | partial | platform-dependent | development-only |
	// production-required" so a claim can honestly describe a degraded
	// control instead of leaving an absolute claim standing next to a
	// known limitation. Empty defaults to ScopeProductionRequired (the
	// strictest, pre-existing behavior: fully absolute, no allowlisted
	// gap marker may remain in its implementation files). Only
	// ScopePartial, ScopePlatformDependent, and ScopeDevelopmentOnly
	// exempt a claim from the active-gap-marker rejection below --
	// declaring one of those is itself the honest disclosure Sol asked
	// for, not a loophole.
	ClaimScope string `yaml:"claim_scope,omitempty"`
}

type Document

type Document struct {
	Version int     `yaml:"version"`
	Claims  []Claim `yaml:"claims"`
}

Document is the top-level docs/claims.yaml shape.

func Load

func Load(path string) (Document, error)

Load reads and strictly decodes a claims YAML file.

type FileFuncs

type FileFuncs struct {
	File     string   `yaml:"file"`
	Funcs    []string `yaml:"funcs"`
	BuildTag string   `yaml:"build_tag,omitempty"`
}

FileFuncs names test functions within one file. BuildTag, if set, is required to appear as a `//go:build <tag>` line near the top of the file (e.g. "integration" for the mandatory real-Assayer-CLI tier).

type FileSymbols

type FileSymbols struct {
	File    string   `yaml:"file"`
	Symbols []string `yaml:"symbols"`
}

FileSymbols names top-level symbols (funcs, types, consts, vars — methods are matched by name only, ignoring their receiver type) a claim depends on within one file.

type Result

type Result struct {
	ID               string
	Title            string
	ClaimedMaturity  string
	ComputedMaturity string
	Problems         []string
}

Result is one claim's re-derived, verified state.

func Verify

func Verify(repoRoot string, doc Document) ([]Result, error)

Verify re-derives every claim's computed maturity against repoRoot (the governator repository root) and returns one Result per claim, in the same order as doc.Claims.

func VerifyWithOptions

func VerifyWithOptions(repoRoot string, doc Document, opts VerifyOptions) ([]Result, error)

func (Result) OK

func (r Result) OK() bool

OK is true when the claim's asserted maturity is fully backed by what Verify could re-derive from the repository — the condition CI gates on.

type VerifyOptions

type VerifyOptions struct {
	ArtifactPath     string
	ManifestPath     string
	ClaimsPath       string
	PortableVerifier bool
}

VerifyOptions lets the CLI bind a claims verification run to the exact release artifact under inspection without editing docs/claims.yaml.