Internal

internal/app/finalize

Package finalize owns the host-facing accountability finalization use case.

import "github.com/nilstate/scafld/v2/internal/app/finalize"

Package finalize owns the host-facing accountability finalization use case.

Functions

func Run(ctx context.Context, snapshotter Snapshotter, acceptanceRunner AcceptanceRunner, reviewer Reviewer, signer Signer, input Input) (Output, error)

Source: internal/app/finalize/finalize.go:122

Run executes snapshot, acceptance, review, calibration, and receipt minting.

Types

type AcceptanceRunner

Source: internal/app/finalize/finalize.go:27

AcceptanceRunner evaluates declared acceptance criteria.

type AcceptanceRunner interface {
	Evaluate(context.Context, acceptance.EvaluateInput) (acceptance.EvaluateOutput, error)
}
Methods
  • Evaluate func(context.Context, acceptance.EvaluateInput) (acceptance.EvaluateOutput, error)

type FileFact

Source: internal/app/finalize/finalize.go:75

FileFact carries the per-file snapshot facts the reviewer evidence reuses, so review does not re-list and re-hash the tree the snapshot already walked.

type FileFact struct {
	Path   string
	Status string
	SHA256 string
}
Fields
  • Path string
  • Status string
  • SHA256 string

type Input

Source: internal/app/finalize/finalize.go:93

Input configures one gate run.

type Input struct {
	TaskID           string
	SessionID        string
	Scope            []string
	BaseRef          string
	ReviewerProvider string
	SpecFingerprint  string
	HostUnderReview  receipt.HostUnderReview
	Independence     receipt.Independence
	Criteria         []acceptance.Criterion
	WorkDir          string
	Env              []string
	Timeout          time.Duration
	IdleTimeout      time.Duration
	PriorLedgerHead  string
	MintedAt         time.Time
}
Fields
  • TaskID string
  • SessionID string
  • Scope []string
  • BaseRef string
  • ReviewerProvider string
  • SpecFingerprint string
  • HostUnderReview receipt.HostUnderReview
  • Independence receipt.Independence
  • Criteria []acceptance.Criterion
  • WorkDir string
  • Env []string
  • Timeout time.Duration
  • IdleTimeout time.Duration
  • PriorLedgerHead string
  • MintedAt time.Time

type Output

Source: internal/app/finalize/finalize.go:112

Output is the structured gate result.

type Output struct {
	Verdict      string
	Acceptance   acceptance.EvaluateOutput
	Findings     []review.Finding
	Receipt      *receipt.Envelope
	Independence receipt.Independence
	Reason       string
}
Fields
  • Verdict string
  • Acceptance acceptance.EvaluateOutput
  • Findings []review.Finding
  • Receipt *receipt.Envelope
  • Independence receipt.Independence
  • Reason string

type ReviewInput

Source: internal/app/finalize/finalize.go:82

ReviewInput is the app-level review request.

type ReviewInput struct {
	TaskID     string
	TreeSHA    string
	Scope      []string
	Deleted    []string
	Files      []FileFact
	Depth      string
	DiffScoped bool
}
Fields
  • TaskID string
  • TreeSHA string
  • Scope []string
  • Deleted []string
  • Files []FileFact
  • Depth string
  • DiffScoped bool

type ReviewResult

Source: internal/app/finalize/finalize.go:44

ReviewResult is the reviewer port output stamped into the signed receipt. The Reviewer facts come from the invocation that actually ran, never a separate pre-acceptance probe, so the receipt cannot attest a stale reviewer binary. Ignored lists in-scope paths the reviewer deliberately did not read (submodule gitlinks, governed instruction/config files); they are signed in file_digests but recorded as ignored_unreviewed so the receipt never implies their review.

type ReviewResult struct {
	Dossier    review.Dossier
	Provenance []receipt.Provenance
	Ignored    []string
	Reviewer   receipt.Reviewer
}
Fields
  • Dossier review.Dossier
  • Provenance []receipt.Provenance
  • Ignored []string
  • Reviewer receipt.Reviewer

type Reviewer

Source: internal/app/finalize/finalize.go:34

Reviewer runs the isolated adversarial review over the snapshot tree and returns the dossier, the provenance of the exact bytes it reviewed, and the runtime facts of the reviewer that actually ran.

type Reviewer interface {
	Review(context.Context, ReviewInput) (ReviewResult, error)
}
Methods
  • Review func(context.Context, ReviewInput) (ReviewResult, error)

type Signer

Source: internal/app/finalize/finalize.go:52

Signer signs the canonical receipt body.

type Signer interface {
	Sign(receipt.Body) (receipt.DetachedSignature, error)
}
Methods
  • Sign func(receipt.Body) (receipt.DetachedSignature, error)

type Snapshot

Source: internal/app/finalize/finalize.go:63

Snapshot captures the deterministic tree facts included in the receipt.

type Snapshot struct {
	TreeSHA           string
	BaseCommit        string
	HeadCommit        string
	FileDigests       map[string]string
	Files             []FileFact
	IgnoredUnreviewed []string
	Deleted           []string
}
Fields
  • TreeSHA string
  • BaseCommit string
  • HeadCommit string
  • FileDigests map[string]string
  • Files []FileFact
  • IgnoredUnreviewed []string
  • Deleted []string

type SnapshotInput

Source: internal/app/finalize/finalize.go:57

SnapshotInput scopes the tree fingerprint.

type SnapshotInput struct {
	Scope   []string
	BaseRef string
}
Fields
  • Scope []string
  • BaseRef string

type Snapshotter

Source: internal/app/finalize/finalize.go:21

Snapshotter computes the commit-free tree facts reviewed by finalization. TreeSHA recomputes only the tree fingerprint; the mutation guard uses it to detect acceptance-time drift without paying for a second full snapshot.

type Snapshotter interface {
	Snapshot(context.Context, SnapshotInput) (Snapshot, error)
	TreeSHA(context.Context, SnapshotInput) (string, error)
}
Methods
  • Snapshot func(context.Context, SnapshotInput) (Snapshot, error)
  • TreeSHA func(context.Context, SnapshotInput) (string, error)