Internal

internal/core/session

Package session defines the append-only evidence ledger and replay model.

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

Package session defines the append-only evidence ledger and replay model.

Constants

Source: internal/core/session/model.go:14

const (
	// EntryWorkspaceBaseline records dirty workspace state before task execution begins.
	EntryWorkspaceBaseline = "workspace_baseline"
	// EntryReceipt records a signed gate receipt in the append-only ledger.
	EntryReceipt = "receipt"
)

Functions

func AppendEntryWithOptions(s Session, entry Entry, opts ReplayOptions) Session

Source: internal/core/session/model.go:159

AppendEntryWithOptions advances a previously replayed session by one entry without replaying older entries. Callers must pass a trusted replayed session or fall back to ReplayWithOptions first.

func FirstWorkspaceBaseline(s Session) (Entry, bool)

Source: internal/core/session/model.go:273

FirstWorkspaceBaseline returns the first captured task workspace baseline.

func LedgerGenesisHead() string

Source: internal/core/session/model.go:198

LedgerGenesisHead returns the starting head for sessions with no receipts.

func New(taskID string, now string) Session

Source: internal/core/session/model.go:95

New creates an empty session ledger for taskID.

func NextLedgerHead(priorLedgerHead string, receiptDigest string) string

Source: internal/core/session/model.go:204

NextLedgerHead derives the next receipt-chain head from the prior head and receipt digest.

func OrderedCriterionIDs(s Session) []string

Source: internal/core/session/model.go:263

OrderedCriterionIDs returns criterion state keys in deterministic order.

func Replay(s Session) Session

Source: internal/core/session/model.go:110

Replay rebuilds derived criterion and phase state from session entries.

func ReplayWithOptions(s Session, opts ReplayOptions) Session

Source: internal/core/session/model.go:115

ReplayWithOptions rebuilds derived state and optionally checks receipt trust.

func WorkspaceBaselineSnapshot(entry Entry) []string

Source: internal/core/session/model.go:283

WorkspaceBaselineSnapshot decodes the raw changed-file snapshot from an entry.

Types

type Entry

Source: internal/core/session/model.go:35

Entry is one append-only evidence event in a session ledger.

type Entry struct {
	ID                      string   `json:"id,omitempty"`
	Type                    string   `json:"type"`
	RecordedAt              string   `json:"recorded_at"`
	CriterionID             string   `json:"criterion_id,omitempty"`
	PhaseID                 string   `json:"phase_id,omitempty"`
	Status                  string   `json:"status,omitempty"`
	Reason                  string   `json:"reason,omitempty"`
	Provider                string   `json:"provider,omitempty"`
	Command                 string   `json:"command,omitempty"`
	ExitCode                int      `json:"exit_code,omitempty"`
	Output                  string   `json:"output,omitempty"`
	Path                    string   `json:"path,omitempty"`
	ReceiptDigest           string   `json:"receipt_digest,omitempty"`
	LedgerHead              string   `json:"ledger_head,omitempty"`
	TrustStatus             string   `json:"trust_status,omitempty"`
	TrustReason             string   `json:"trust_reason,omitempty"`
	ReviewPacket            string   `json:"review_packet,omitempty"`
	CanonicalResponseSHA256 string   `json:"canonical_response_sha256,omitempty"`
	ProviderModel           string   `json:"provider_model,omitempty"`
	ProviderSession         string   `json:"provider_session,omitempty"`
	AttemptID               string   `json:"attempt_id,omitempty"`
	LeaseExpiresAt          string   `json:"lease_expires_at,omitempty"`
	ReviewMode              string   `json:"review_mode,omitempty"`
	ReviewPassCount         int      `json:"review_pass_count,omitempty"`
	ReviewedHead            string   `json:"reviewed_head,omitempty"`
	ReviewedDirty           string   `json:"reviewed_dirty,omitempty"`
	ReviewedDiff            string   `json:"reviewed_diff,omitempty"`
	ReviewedSpec            string   `json:"reviewed_spec,omitempty"`
	ReviewedScope           []string `json:"reviewed_scope,omitempty"`
	ReviewedMaterialDigest  string   `json:"reviewed_material_digest,omitempty"`
}
Fields
  • ID string `json:"id,omitempty"`
  • Type string `json:"type"`
  • RecordedAt string `json:"recorded_at"`
  • CriterionID string `json:"criterion_id,omitempty"`
  • PhaseID string `json:"phase_id,omitempty"`
  • Status string `json:"status,omitempty"`
  • Reason string `json:"reason,omitempty"`
  • Provider string `json:"provider,omitempty"`
  • Command string `json:"command,omitempty"`
  • ExitCode int `json:"exit_code,omitempty"`
  • Output string `json:"output,omitempty"`
  • Path string `json:"path,omitempty"`
  • ReceiptDigest string `json:"receipt_digest,omitempty"`
  • LedgerHead string `json:"ledger_head,omitempty"`
  • TrustStatus string `json:"trust_status,omitempty"`
  • TrustReason string `json:"trust_reason,omitempty"`
  • ReviewPacket string `json:"review_packet,omitempty"`
  • CanonicalResponseSHA256 string `json:"canonical_response_sha256,omitempty"`
  • ProviderModel string `json:"provider_model,omitempty"`
  • ProviderSession string `json:"provider_session,omitempty"`
  • AttemptID string `json:"attempt_id,omitempty"`
  • LeaseExpiresAt string `json:"lease_expires_at,omitempty"`
  • ReviewMode string `json:"review_mode,omitempty"`
  • ReviewPassCount int `json:"review_pass_count,omitempty"`
  • ReviewedHead string `json:"reviewed_head,omitempty"`
  • ReviewedDirty string `json:"reviewed_dirty,omitempty"`
  • ReviewedDiff string `json:"reviewed_diff,omitempty"`
  • ReviewedSpec string `json:"reviewed_spec,omitempty"`
  • ReviewedScope []string `json:"reviewed_scope,omitempty"`
  • ReviewedMaterialDigest string `json:"reviewed_material_digest,omitempty"`

type ReceiptTrustChecker

Source: internal/core/session/model.go:79

ReceiptTrustChecker validates receipt key trust at replay time. The core session package owns replay mechanics but not trust-anchor loading, so callers inject key lifecycle checks through this narrow port.

type ReceiptTrustChecker interface {
	CheckReceiptTrust(receipt.Envelope) error
}
Methods
  • CheckReceiptTrust func(receipt.Envelope) error

type ReplayOptions

Source: internal/core/session/model.go:84

ReplayOptions configures optional replay checks.

type ReplayOptions struct {
	ReceiptTrustChecker ReceiptTrustChecker
	SkipReceiptDecode   bool
}
Fields
  • ReceiptTrustChecker ReceiptTrustChecker
  • SkipReceiptDecode bool

type Session

Source: internal/core/session/model.go:21

Session is the durable task evidence ledger plus replayed state indexes.

type Session struct {
	SchemaVersion   int                    `json:"schema_version"`
	TaskID          string                 `json:"task_id"`
	CreatedAt       string                 `json:"created_at,omitempty"`
	UpdatedAt       string                 `json:"updated_at,omitempty"`
	Entries         []Entry                `json:"entries"`
	CriterionStates map[string]StateRecord `json:"criterion_states,omitempty"`
	PhaseBlocks     map[string]StateRecord `json:"phase_blocks,omitempty"`
	LedgerHead      string                 `json:"ledger_head,omitempty"`
	LedgerValid     bool                   `json:"ledger_valid,omitempty"`
	LedgerError     string                 `json:"ledger_error,omitempty"`
}
Fields
  • SchemaVersion int `json:"schema_version"`
  • TaskID string `json:"task_id"`
  • CreatedAt string `json:"created_at,omitempty"`
  • UpdatedAt string `json:"updated_at,omitempty"`
  • Entries []Entry `json:"entries"`
  • CriterionStates map[string]StateRecord `json:"criterion_states,omitempty"`
  • PhaseBlocks map[string]StateRecord `json:"phase_blocks,omitempty"`
  • LedgerHead string `json:"ledger_head,omitempty"`
  • LedgerValid bool `json:"ledger_valid,omitempty"`
  • LedgerError string `json:"ledger_error,omitempty"`

func AppendEntry(entry Entry) Session

Source: internal/core/session/model.go:152

AppendEntry advances a previously replayed session by one entry.

func WithEntry(entry Entry) Session

Source: internal/core/session/model.go:90

WithEntry returns a replayed copy of the session with entry appended.

type StateRecord

Source: internal/core/session/model.go:69

StateRecord is the replayed state for a criterion or phase.

type StateRecord struct {
	Status    string `json:"status"`
	Reason    string `json:"reason,omitempty"`
	UpdatedAt string `json:"updated_at,omitempty"`
	SourceID  string `json:"source_id,omitempty"`
}
Fields
  • Status string `json:"status"`
  • Reason string `json:"reason,omitempty"`
  • UpdatedAt string `json:"updated_at,omitempty"`
  • SourceID string `json:"source_id,omitempty"`
Built withSourcey
Edit this page