Internal

internal/core/receipt

github.com/nilstate/scafld/v2/internal/core/receipt

import "github.com/nilstate/scafld/v2/internal/core/receipt"

Constants

Source: internal/core/receipt/receipt.go:16

const (
	// SchemaVersion is the current signed receipt schema.
	SchemaVersion = 1
	// SignatureAlgorithm is the detached-signature algorithm name.
	SignatureAlgorithm = "ed25519"
	// SnapshotModeWorkingTree signs the default working-tree snapshot mode.
	SnapshotModeWorkingTree = "working_tree"
	// SnapshotModeBaseDelta signs base-to-head delta snapshot mode.
	SnapshotModeBaseDelta = "base_delta"
	// IndependenceLevelIsolationOnly records isolated review without proven model-vendor separation.
	IndependenceLevelIsolationOnly = "isolation_only"
	// IndependenceLevelCrossVendor records proven different model-vendor review.
	IndependenceLevelCrossVendor = "cross_vendor"
	// IndependenceDowngradeSameVendor records same-vendor isolation-only review.
	IndependenceDowngradeSameVendor = "same_vendor"
	// IndependenceDowngradeUnknownHost records missing host-vendor detection.
	IndependenceDowngradeUnknownHost = "unknown_host"
	// IndependenceDowngradeUnknownReviewer records missing reviewer-vendor detection.
	IndependenceDowngradeUnknownReviewer = "unknown_reviewer"
)

Functions

func CanonicalBody(body Body) ([]byte, error)

Source: internal/core/receipt/receipt.go:136

CanonicalBody returns deterministic sorted-key JSON for a receipt body.

func CanonicalJSON(value any) ([]byte, error)

Source: internal/core/receipt/receipt.go:144

CanonicalJSON returns compact deterministic JSON with lexicographically sorted object keys.

func DecodeEnvelope(data []byte) (Envelope, error)

Source: internal/core/receipt/receipt.go:321

DecodeEnvelope parses a receipt envelope from JSON.

func ReceiptDigest(body Body) (string, error)

Source: internal/core/receipt/receipt.go:165

ReceiptDigest returns the hex sha256 digest used by the ledger chain. The digest excludes the detached signature and clears ledger_head to avoid making the head recursively depend on itself.

func ValidateBody(body Body) error

Source: internal/core/receipt/receipt.go:180

ValidateBody checks required receipt body fields.

func ValidateEnvelope(envelope Envelope) error

Source: internal/core/receipt/receipt.go:304

ValidateEnvelope checks the body and detached signature shape.

func ValidateReviewCoverage(body Body) error

Source: internal/core/receipt/receipt.go:265

ValidateReviewCoverage requires every signed file digest to be accounted for: either shown to the independent reviewer (present in reviewed_context_provenance) or explicitly declared withheld (ignored_unreviewed). A digest that is in neither would let a signed pass receipt imply the reviewer saw bytes it never did, breaking the accountability guarantee that the receipt covers the reviewed change set.

Types

type Acceptance

Source: internal/core/receipt/receipt.go:94

Acceptance records one acceptance command result included in the receipt.

type Acceptance struct {
	ID           string `json:"id"`
	PhaseID      string `json:"phase_id,omitempty"`
	Command      string `json:"command,omitempty"`
	ExpectedKind string `json:"expected_kind,omitempty"`
	Status       string `json:"status"`
	Reason       string `json:"reason,omitempty"`
	ExitCode     int    `json:"exit_code,omitempty"`
	OutputSHA256 string `json:"output_sha256,omitempty"`
	Diagnostic   string `json:"diagnostic,omitempty"`
}
Fields
  • ID string `json:"id"`
  • PhaseID string `json:"phase_id,omitempty"`
  • Command string `json:"command,omitempty"`
  • ExpectedKind string `json:"expected_kind,omitempty"`
  • Status string `json:"status"`
  • Reason string `json:"reason,omitempty"`
  • ExitCode int `json:"exit_code,omitempty"`
  • OutputSHA256 string `json:"output_sha256,omitempty"`
  • Diagnostic string `json:"diagnostic,omitempty"`

type Blocker

Source: internal/core/receipt/receipt.go:107

Blocker is a calibrated open reviewer finding.

type Blocker struct {
	ID         string `json:"id"`
	Severity   string `json:"severity,omitempty"`
	Location   string `json:"location,omitempty"`
	Summary    string `json:"summary,omitempty"`
	Validation string `json:"validation,omitempty"`
}
Fields
  • ID string `json:"id"`
  • Severity string `json:"severity,omitempty"`
  • Location string `json:"location,omitempty"`
  • Summary string `json:"summary,omitempty"`
  • Validation string `json:"validation,omitempty"`

type Body

Source: internal/core/receipt/receipt.go:36

Body is the canonical receipt payload signed by the host.

type Body struct {
	SchemaVersion             int               `json:"schema_version"`
	TaskID                    string            `json:"task_id"`
	SessionID                 string            `json:"session_id"`
	Verdict                   string            `json:"verdict"`
	SnapshotMode              string            `json:"snapshot_mode"`
	BaseRef                   string            `json:"base_ref,omitempty"`
	BaseCommit                string            `json:"base_commit"`
	HeadCommit                string            `json:"head_commit"`
	Scope                     []string          `json:"scope"`
	TreeSHA                   string            `json:"tree_sha"`
	FileDigests               map[string]string `json:"file_digests"`
	IgnoredUnreviewed         []string          `json:"ignored_unreviewed"`
	ReviewedContextProvenance []Provenance      `json:"reviewed_context_provenance"`
	Reviewer                  Reviewer          `json:"reviewer"`
	HostUnderReview           HostUnderReview   `json:"host_under_review"`
	Independence              Independence      `json:"independence"`
	SpecFingerprint           string            `json:"spec_fingerprint"`
	AcceptanceDeclared        bool              `json:"acceptance_declared"`
	Acceptance                []Acceptance      `json:"acceptance"`
	OpenBlockers              []Blocker         `json:"open_blockers"`
	MutationGuard             MutationGuard     `json:"mutation_guard"`
	LedgerHead                string            `json:"ledger_head"`
	MintedAt                  string            `json:"minted_at"`
}
Fields
  • SchemaVersion int `json:"schema_version"`
  • TaskID string `json:"task_id"`
  • SessionID string `json:"session_id"`
  • Verdict string `json:"verdict"`
  • SnapshotMode string `json:"snapshot_mode"`
  • BaseRef string `json:"base_ref,omitempty"`
  • BaseCommit string `json:"base_commit"`
  • HeadCommit string `json:"head_commit"`
  • Scope []string `json:"scope"`
  • TreeSHA string `json:"tree_sha"`
  • FileDigests map[string]string `json:"file_digests"`
  • IgnoredUnreviewed []string `json:"ignored_unreviewed"`
  • ReviewedContextProvenance []Provenance `json:"reviewed_context_provenance"`
  • Reviewer Reviewer `json:"reviewer"`
  • HostUnderReview HostUnderReview `json:"host_under_review"`
  • Independence Independence `json:"independence"`
  • SpecFingerprint string `json:"spec_fingerprint"`
  • AcceptanceDeclared bool `json:"acceptance_declared"`
  • Acceptance []Acceptance `json:"acceptance"`
  • OpenBlockers []Blocker `json:"open_blockers"`
  • MutationGuard MutationGuard `json:"mutation_guard"`
  • LedgerHead string `json:"ledger_head"`
  • MintedAt string `json:"minted_at"`

type DetachedSignature

Source: internal/core/receipt/receipt.go:123

DetachedSignature is stored outside the canonical signed receipt body.

type DetachedSignature struct {
	Alg   string `json:"alg"`
	KeyID string `json:"key_id"`
	Sig   string `json:"sig"`
}
Fields
  • Alg string `json:"alg"`
  • KeyID string `json:"key_id"`
  • Sig string `json:"sig"`

type Envelope

Source: internal/core/receipt/receipt.go:130

Envelope carries a receipt body and its detached signature.

type Envelope struct {
	Body      Body              `json:"body"`
	Signature DetachedSignature `json:"signature"`
}
Fields
  • Body Body `json:"body"`
  • Signature DetachedSignature `json:"signature"`

type HostUnderReview

Source: internal/core/receipt/receipt.go:79

HostUnderReview identifies the host agent whose work is being gated.

type HostUnderReview struct {
	Agent     string `json:"agent"`
	Model     string `json:"model,omitempty"`
	SessionID string `json:"session_id,omitempty"`
}
Fields
  • Agent string `json:"agent"`
  • Model string `json:"model,omitempty"`
  • SessionID string `json:"session_id,omitempty"`

type Independence

Source: internal/core/receipt/receipt.go:86

Independence records the separation between the host and reviewer.

type Independence struct {
	Level      string `json:"level"`
	Distinct   bool   `json:"distinct"`
	Downgraded string `json:"downgraded,omitempty"`
	Reason     string `json:"reason,omitempty"`
}
Fields
  • Level string `json:"level"`
  • Distinct bool `json:"distinct"`
  • Downgraded string `json:"downgraded,omitempty"`
  • Reason string `json:"reason,omitempty"`

type MutationGuard

Source: internal/core/receipt/receipt.go:116

MutationGuard records the workspace mutation safety result.

type MutationGuard struct {
	Status string   `json:"status"`
	Scope  []string `json:"scope,omitempty"`
	Reason string   `json:"reason,omitempty"`
}
Fields
  • Status string `json:"status"`
  • Scope []string `json:"scope,omitempty"`
  • Reason string `json:"reason,omitempty"`

type Provenance

Source: internal/core/receipt/receipt.go:63

Provenance records one reviewed context source.

type Provenance struct {
	Kind   string `json:"kind"`
	Path   string `json:"path,omitempty"`
	SHA256 string `json:"sha256,omitempty"`
	Bytes  int    `json:"bytes,omitempty"`
}
Fields
  • Kind string `json:"kind"`
  • Path string `json:"path,omitempty"`
  • SHA256 string `json:"sha256,omitempty"`
  • Bytes int `json:"bytes,omitempty"`

type Reviewer

Source: internal/core/receipt/receipt.go:71

Reviewer records the independent reviewer runtime stamped into the receipt.

type Reviewer struct {
	Provider     string `json:"provider"`
	Model        string `json:"model,omitempty"`
	BinarySHA256 string `json:"binary_sha256,omitempty"`
	EndpointHost string `json:"endpoint_host,omitempty"`
}
Fields
  • Provider string `json:"provider"`
  • Model string `json:"model,omitempty"`
  • BinarySHA256 string `json:"binary_sha256,omitempty"`
  • EndpointHost string `json:"endpoint_host,omitempty"`
Built withSourcey
Edit this page