cleantreeevidence

Documentation

Overview

Package cleantreeevidence records and verifies soundness evidence against an exact synthetic Git tree assembled from HEAD and an explicit path selection.

Index

• Constants
• func LoadPathSelection(path string) ([]string, error)
• func Verify(ctx context.Context, options VerifyOptions) (resultErr error)
• func WriteRecord(path string, record Record) (resultErr error)
• type AggregateReportIdentity
• type AggregateReportPlan
• type CallerSnapshot
  • func SnapshotCallerState(ctx context.Context, root string, excludedPaths ...string) (CallerSnapshot, error)
• type CaptureOptions
• type ChangedPathIdentity
• type CommandOutcome
• type CommandPlan
• type CounterexampleIdentity
• type CounterexampleObservationPlan
• type CounterexamplePlan
• type DiffCensusIdentity
• type DiffReviewPlan
• type InputIdentity
• type InputPlan
• type Materialization
  • func Materialize(ctx context.Context, root, pathsPath, ownershipManifestPath string, ...) (*Materialization, error)
  • func (m *Materialization) Close(ctx context.Context) error
• type MutationProof
• type MutationProofPlan
• type Plan
  • func LoadPlan(path string) (Plan, error)
  • func (p Plan) Validate() error
• type PreservationIdentity
• type ProvenanceIdentity
• type Record
  • func Capture(ctx context.Context, options CaptureOptions) (record Record, resultErr error)
  • func LoadRecord(path string) (Record, error)
  • func Rebind(ctx context.Context, options CaptureOptions) (record Record, resultErr error)
• type RepositoryIdentity
• type ReviewedExclusion
• type TaskLedgerIdentity
• type TaskLedgerPlan
• type ToolIdentity
• type ToolPlan
• type VerifyOptions

Constants

const (
	// ProvenanceGenerated marks a record produced by fresh gate execution.
	ProvenanceGenerated = "generated"
	// ProvenanceRebound marks a record whose prose identity was re-bound while
	// the retained aggregate report was carried forward untouched.
	ProvenanceRebound = "re-bound"
	// ProvenanceReused marks a record whose aggregate command was not executed:
	// a caller-produced report was admitted under the exact-tree, manifest,
	// registry, and producing-toolchain equalities in reuse.go. Verification
	// refuses these records unless the caller explicitly opts in, so a reused
	// record is a local iteration aid and never a completion or release claim.
	//
	// This is a new value of the existing v4 `provenance.kind` member, not a
	// structural change, so the record format is not bumped: every previously
	// retained v4 record verifies exactly as before, and an older verifier
	// reading a newer reused record rejects it as an unknown kind, which fails
	// in the safe direction. The v3 rejection precedent applies to structural
	// meaning changes (single digest to dual digest), where reinterpreting
	// retained bytes would silently weaken the claim.
	ProvenanceReused = "reused-aggregate"
)

const AllowReusedAggregateFlag = "allow-reused-aggregate"

AllowReusedAggregateFlag is the exact opt-in flag name that makes the freshness verifier accept a reused-aggregate record. It is exported so the verifier command and the completion-containment test bind one string: the whole containment argument is that no reviewed gate command passes it.

const FormatVersion = 4

Functions

func LoadPathSelection

func LoadPathSelection(path string) ([]string, error)

LoadPathSelection loads a sorted, explicit, repository-relative path list.

func Verify

func Verify(ctx context.Context, options VerifyOptions) (resultErr error)

Verify recomputes every freshness identity without modifying the caller's real index or worktree.

func WriteRecord

func WriteRecord(path string, record Record) (resultErr error)

WriteRecord durably publishes a clean-tree record through a sibling file.

Types

type AggregateReportIdentity

type AggregateReportIdentity struct {
	OutputFile     string                  `json:"output_file"`
	SHA256         string                  `json:"sha256"`
	ManifestPath   string                  `json:"manifest_path"`
	ManifestSHA256 string                  `json:"manifest_sha256"`
	RegistryPath   string                  `json:"registry_path"`
	RegistrySHA256 string                  `json:"registry_sha256"`
	Report         soundnessgate.RunReport `json:"report"`
}

AggregateReportIdentity embeds the fully validated report and the exact manifest and registry bytes that define its meaning.

type AggregateReportPlan

type AggregateReportPlan struct {
	CommandName  string                  `json:"command_name"`
	OutputFile   string                  `json:"output_file"`
	ManifestPath string                  `json:"manifest_path"`
	RegistryPath string                  `json:"registry_path"`
	Profile      soundnessgate.ProfileID `json:"profile"`
}

AggregateReportPlan binds the retained aggregate report to its producing command and reviewed manifest/registry.

type CallerSnapshot

type CallerSnapshot struct {
	IndexSHA256    string
	WorktreeSHA256 string
}

CallerSnapshot is a byte-sensitive identity for the caller's real index and worktree inventory. Git administrative state is deliberately excluded.

func SnapshotCallerState

func SnapshotCallerState(ctx context.Context, root string, excludedPaths ...string) (CallerSnapshot, error)

SnapshotCallerState captures the caller state while excluding authorized recorder output paths. Exclusions must be repository-relative slash paths.

type CaptureOptions

type CaptureOptions struct {
	Root                     string
	PathsPath                string
	PlanPath                 string
	EvidencePath             string
	ReuseAggregateReportPath string
}

CaptureOptions selects the exact tree and destination for a retained proof. ReuseAggregateReportPath is empty by default, which executes every planned command including the aggregate profile. When it is set, the named report is admitted in place of executing the planned aggregate command under the tree-content and producing-run bindings in reuse.go; the resulting record carries ProvenanceReused, which verification refuses unless the caller explicitly opts in, because admission binds identities rather than execution.

type ChangedPathIdentity

type ChangedPathIdentity struct {
	Path          string `json:"path"`
	GitStatus     string `json:"git_status"`
	Kind          string `json:"kind"`
	ContentSHA256 string `json:"content_sha256,omitempty"`
	Disposition   string `json:"disposition"`
}

ChangedPathIdentity records one complete-diff member and how review disposed of it. ContentSHA256 is empty only for a deletion.

type CommandOutcome

type CommandOutcome struct {
	Name         string   `json:"name"`
	Directory    string   `json:"directory"`
	Args         []string `json:"args"`
	VectorSHA256 string   `json:"vector_sha256"`
	ExitCode     int      `json:"exit_code"`
	DurationMS   int64    `json:"duration_ms"`
	Log          string   `json:"log"`
	LogSHA256    string   `json:"log_sha256"`
	Passed       bool     `json:"passed"`
}

CommandOutcome records one command and its retained log identity.

type CommandPlan

type CommandPlan struct {
	Name           string   `json:"name"`
	Directory      string   `json:"directory,omitempty"`
	Args           []string `json:"args"`
	TimeoutMinutes int      `json:"timeout_minutes"`
}

CommandPlan declares one exact command vector.

type CounterexampleIdentity

type CounterexampleIdentity struct {
	Path         string                          `json:"path"`
	SHA256       string                          `json:"sha256"`
	Observations []CounterexampleObservationPlan `json:"observations"`
}

CounterexampleIdentity records the exact inventory and observed IDs.

type CounterexampleObservationPlan

type CounterexampleObservationPlan struct {
	ID          string `json:"id"`
	Observation string `json:"observation"`
}

CounterexampleObservationPlan binds one reviewed counterexample to its exact required production observation.

type CounterexamplePlan

type CounterexamplePlan struct {
	Path     string                          `json:"path"`
	Required []CounterexampleObservationPlan `json:"required"`
}

CounterexamplePlan identifies the reviewed counterexample inventory.

type DiffCensusIdentity

type DiffCensusIdentity struct {
	BaseCommit         string                `json:"base_commit"`
	Changes            []ChangedPathIdentity `json:"changes"`
	ReviewedExclusions []ReviewedExclusion   `json:"reviewed_exclusions"`
	AuthorizedOutputs  []string              `json:"authorized_outputs"`
	CanonicalSHA256    string                `json:"canonical_sha256"`
}

DiffCensusIdentity binds every selected or explicitly excluded changed path relative to the retained base. Recorder outputs are listed separately because publishing the record necessarily changes those paths after census capture.

type DiffReviewPlan

type DiffReviewPlan struct {
	ReviewedExclusions []ReviewedExclusion `json:"reviewed_exclusions"`
}

DiffReviewPlan declares every changed path intentionally excluded from the combined proof tree. Paths selected for the proof may not also be excluded.

type InputIdentity

type InputIdentity struct {
	Name   string `json:"name"`
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
}

InputIdentity records the digest of one declared proof input.

type InputPlan

type InputPlan struct {
	Name string `json:"name"`
	Path string `json:"path"`
}

InputPlan identifies a proof input whose byte digest is retained.

type Materialization

type Materialization struct {
	Root     string
	Worktree string
	Identity RepositoryIdentity
	// contains filtered or unexported fields
}

Materialization owns the temporary index and optional detached worktree used to evaluate an exact selected tree.

func Materialize

func Materialize(
	ctx context.Context,
	root, pathsPath, ownershipManifestPath string,
	withWorktree bool,
) (*Materialization, error)

Materialize builds HEAD plus the explicit path selection through an isolated temporary index. When withWorktree is true it also creates a clean detached worktree at the deterministic synthetic commit.

func (*Materialization) Close

func (m *Materialization) Close(ctx context.Context) error

Close removes the detached worktree and all isolated temporary state.

type MutationProof

type MutationProof struct {
	Name                 string `json:"name"`
	Observation          string `json:"observation"`
	CleanControlPassed   bool   `json:"clean_control_passed"`
	MutantSelected       bool   `json:"mutant_selected"`
	IntendedMismatchSeen bool   `json:"intended_mismatch_seen"`
	Restored             bool   `json:"restored"`
	PostControlPassed    bool   `json:"post_control_passed"`
}

MutationProof records the required causal control/mutation/restoration chain.

type MutationProofPlan

type MutationProofPlan struct {
	Name        string `json:"name"`
	Observation string `json:"observation"`
}

MutationProofPlan names an observation that must contain a causal mutation sequence rather than a generic failing command.

type Plan

type Plan struct {
	FormatVersion         int                 `json:"format_version"`
	OwnershipManifestPath string              `json:"ownership_manifest_path"`
	Inputs                []InputPlan         `json:"inputs"`
	Toolchain             []ToolPlan          `json:"toolchain"`
	TaskLedgers           []TaskLedgerPlan    `json:"task_ledgers"`
	DiffReview            DiffReviewPlan      `json:"diff_review"`
	Counterexamples       CounterexamplePlan  `json:"counterexamples"`
	Commands              []CommandPlan       `json:"commands"`
	AggregateReport       AggregateReportPlan `json:"aggregate_report"`
	MutationProofs        []MutationProofPlan `json:"mutation_proofs"`
}

Plan declares every input and executed command required by a retained proof. The reviewed plan is the single source of truth for expected task-ledger names, paths, order, and permitted pending identifiers; code and schema validate structure only.

func LoadPlan

func LoadPlan(path string) (Plan, error)

LoadPlan decodes and validates one format-v4 plan.

func (Plan) Validate

func (p Plan) Validate() error

Validate rejects incomplete, ambiguous, or internally disconnected plans.

type PreservationIdentity

type PreservationIdentity struct {
	IndexSHA256Before    string `json:"index_sha256_before"`
	IndexSHA256After     string `json:"index_sha256_after"`
	WorktreeSHA256Before string `json:"worktree_sha256_before"`
	WorktreeSHA256After  string `json:"worktree_sha256_after"`
}

PreservationIdentity proves the recorder left the caller state unchanged.

type ProvenanceIdentity

type ProvenanceIdentity struct {
	Kind                        string `json:"kind"`
	AggregateSemanticTreeDigest string `json:"aggregate_semantic_tree_digest"`
	AggregateWorkspaceDigest    string `json:"aggregate_workspace_digest"`
	CarriedReportSHA256         string `json:"carried_report_sha256"`
	PreviousProseDigest         string `json:"previous_prose_digest,omitempty"`
}

ProvenanceIdentity attributes the retained aggregate report to the exact semantic content that produced it. Re-binding rewrites the prose identity but never this attribution: the aggregate semantic digest and workspace digest stay fixed across every re-bind of the same evidence.

type Record

type Record struct {
	FormatVersion   int                     `json:"format_version"`
	Status          string                  `json:"status"`
	StartedAt       string                  `json:"started_at"`
	FinishedAt      string                  `json:"finished_at"`
	Repository      RepositoryIdentity      `json:"repository"`
	Provenance      ProvenanceIdentity      `json:"provenance"`
	DiffCensus      DiffCensusIdentity      `json:"diff_census"`
	Inputs          []InputIdentity         `json:"inputs"`
	Toolchain       []ToolIdentity          `json:"toolchain"`
	TaskLedgers     []TaskLedgerIdentity    `json:"task_ledgers"`
	Counterexamples CounterexampleIdentity  `json:"counterexamples"`
	Commands        []CommandOutcome        `json:"commands"`
	AggregateReport AggregateReportIdentity `json:"aggregate_report"`
	MutationProofs  []MutationProof         `json:"mutation_proofs"`
	Preservation    PreservationIdentity    `json:"preservation"`
}

Record is the retained format-v4 proof record.

func Capture

func Capture(ctx context.Context, options CaptureOptions) (record Record, resultErr error)

Capture materializes the selected tree, executes every planned command, and publishes a format-v3 record. A failed command still produces a failed record.

func LoadRecord

func LoadRecord(path string) (Record, error)

LoadRecord decodes one format-v4 retained proof record. The retired v3 single-digest format is rejected with an explicit migration notice.

func Rebind

func Rebind(ctx context.Context, options CaptureOptions) (record Record, resultErr error)

Rebind refreshes the prose identity of a retained record without executing any assurance profile. It recomputes both class digests, revalidates the task ledgers and diff census against the reviewed plan, carries the retained aggregate report forward untouched, and records the carried-forward provenance. Any semantic-content drift fails closed with the drifted paths named; the retained record is never modified on failure.

type RepositoryIdentity

type RepositoryIdentity struct {
	BaseCommit          string   `json:"base_commit"`
	SyntheticTree       string   `json:"synthetic_tree"`
	SyntheticCommit     string   `json:"synthetic_commit"`
	DiffSHA256          string   `json:"diff_sha256"`
	SemanticTreeDigest  string   `json:"semantic_tree_digest"`
	ProseTreeDigest     string   `json:"prose_tree_digest"`
	PathSelectionSHA256 string   `json:"path_selection_sha256"`
	PathSelection       []string `json:"path_selection"`
}

RepositoryIdentity binds a proof to the exact selected repository content. The tree binding is split by reviewed ownership class: the semantic-content digest covers every path class that any gate executes or reads, and the prose digest covers documentation-class paths only.

type ReviewedExclusion

type ReviewedExclusion struct {
	Path   string `json:"path"`
	Reason string `json:"reason"`
}

ReviewedExclusion records the exact path and human review rationale for one unrelated repository change.

type TaskLedgerIdentity

type TaskLedgerIdentity struct {
	Name       string   `json:"name"`
	Path       string   `json:"path"`
	SHA256     string   `json:"sha256"`
	Total      int      `json:"total"`
	Completed  int      `json:"completed"`
	PendingIDs []string `json:"pending_ids"`
}

TaskLedgerIdentity records exact checkbox state from one OpenSpec task file.

type TaskLedgerPlan

type TaskLedgerPlan struct {
	Name            string   `json:"name"`
	Path            string   `json:"path"`
	ExpectedPending []string `json:"expected_pending"`
}

TaskLedgerPlan identifies a task ledger and the only task IDs that may still be pending when the retained proof is accepted.

type ToolIdentity

type ToolIdentity struct {
	Name              string   `json:"name"`
	Command           []string `json:"command"`
	RequiredVersionRE string   `json:"required_version_re"`
	Version           string   `json:"version"`
}

ToolIdentity records the executed version command and its exact result.

type ToolPlan

type ToolPlan struct {
	Name              string   `json:"name"`
	Command           []string `json:"command"`
	RequiredVersionRE string   `json:"required_version_re"`
}

ToolPlan identifies a version command and the required version expression.

type VerifyOptions

type VerifyOptions struct {
	Root                 string
	PathsPath            string
	PlanPath             string
	EvidencePath         string
	AllowReusedAggregate bool
}

VerifyOptions selects the repository, reviewed paths, plan, and retained record checked by Verify. AllowReusedAggregate is an explicit local-iteration opt-in: without it, a record whose aggregate command was reused instead of executed is refused, so completion and release claims always rest on fresh aggregate execution.