recovery

package
v0.1.21 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 12, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package recovery owns immutable failed-run inputs and accepted partial results. A recovery manifest grants replay authority, never final review publication.

Index

Constants

View Source
const SchemaURI = "https://mulgae.local/schemas/mulgae-run-recovery.v1.schema.json"
View Source
const SchemaVersion = "mulgae-run-recovery.v1"

Variables

View Source
var ErrUnavailable = errors.New("failed-run recovery manifest is absent")

Functions

func BlobPath

func BlobPath(run ports.PublicationRun, blob Blob) (ports.SafeRelativePath, error)

func Digest

func Digest(value []byte) string

Types

type Attempt

type Attempt struct {
	AttemptID        string              `json:"attempt_id"`
	Role             domain.Role         `json:"role"`
	ProviderInstance string              `json:"provider_instance"`
	State            domain.AttemptState `json:"state"`
	FailureClass     domain.FailureClass `json:"failure_class"`
	ReasonCode       string              `json:"reason_code"`
	InitialPrompt    Prompt              `json:"initial_prompt"`
}

type Blob

type Blob struct {
	SHA256     string `json:"sha256"`
	ByteLength int64  `json:"byte_length"`
}

Blob binds source-sized content without imposing a product byte ceiling.

func AddBlob

func AddBlob(blobs map[string][]byte, value []byte) Blob

type Document

type Document struct {
	SchemaVersion            string          `json:"schema_version"`
	SessionID                string          `json:"session_id"`
	RunID                    string          `json:"run_id"`
	RunType                  domain.RunType  `json:"run_type"`
	RunState                 domain.RunState `json:"run_state"`
	Threshold                domain.Severity `json:"threshold"`
	Source                   *Source         `json:"source"`
	Target                   Target          `json:"target"`
	SnapshotManifestSHA256   string          `json:"snapshot_manifest_sha256"`
	WorkspaceTerminalReceipt string          `json:"workspace_terminal_receipt"`
	Roles                    []Role          `json:"roles"`
	Attempts                 []Attempt       `json:"attempts"`
	Findings                 []Finding       `json:"findings"`
}

Document is the bounded manifest. Provider content remains in hash-bound blobs.

func DecodeManifest

func DecodeManifest(raw []byte) (Document, error)

func (Document) Blobs

func (document Document) Blobs() []Blob

type Evidence

type Evidence struct {
	TargetSHA256  string        `json:"target_sha256"`
	Side          evidence.Side `json:"side"`
	Path          string        `json:"path"`
	LineStart     int           `json:"line_start"`
	LineEnd       int           `json:"line_end"`
	Quote         string        `json:"quote"`
	ExcerptSHA256 string        `json:"excerpt_sha256"`
	Visual        *Visual       `json:"visual"`
}

type Finding

type Finding struct {
	ID               string                  `json:"id"`
	Fingerprint      string                  `json:"fingerprint"`
	Role             domain.Role             `json:"role"`
	ProviderInstance string                  `json:"provider_instance"`
	Severity         domain.Severity         `json:"severity"`
	Title            string                  `json:"title"`
	Description      string                  `json:"description"`
	Recommendation   string                  `json:"recommendation"`
	Confidence       domain.Confidence       `json:"confidence"`
	Lifecycle        domain.FindingLifecycle `json:"lifecycle"`
	Evidence         []Evidence              `json:"evidence"`
}

type Prepared

type Prepared struct {
	// contains filtered or unexported fields
}

func NewPrepared

func NewPrepared(ctx context.Context, document Document, blobs map[string][]byte) (Prepared, error)

func (Prepared) Seal

func (prepared Prepared) Seal(ctx context.Context, receipt ports.WorkspaceTerminalReceipt) (Snapshot, error)

Seal requires the real successful workspace release and provider termination receipt for this run. It cannot authorize an ordinary final review.

type Prompt

type Prompt struct {
	Stdin                 Blob              `json:"stdin"`
	SourceInvocationID    string            `json:"source_invocation_id"`
	ExecutionInvocationID string            `json:"execution_invocation_id"`
	TemplateID            string            `json:"template_id"`
	TemplateVersion       string            `json:"template_version"`
	TemplateSHA256        string            `json:"template_sha256"`
	AdapterProfile        string            `json:"adapter_profile"`
	AdapterParameters     map[string]string `json:"adapter_parameters"`
	Scope                 string            `json:"scope"`
}

type RetentionMetadata

type RetentionMetadata struct {
	// contains filtered or unexported fields
}

RetentionMetadata identifies a manifest and its optional parent for cleanup. It does not verify blob content and cannot authorize replay or publication.

func ReadRetentionMetadata

func ReadRetentionMetadata(ctx context.Context, store ports.RunSupportArtifactStore, validator SchemaValidator, run ports.PublicationRun, maxManifestBytes int64) (RetentionMetadata, error)

ReadRetentionMetadata verifies bounded manifest metadata and confirms that it remains unchanged. It never reads the source-sized input or report blobs.

func (RetentionMetadata) Manifest

func (RetentionMetadata) Parent

func (metadata RetentionMetadata) Parent() (domain.SourceReference, bool)

type RetryAttempt

type RetryAttempt struct {
	Role      domain.Role `json:"role"`
	AttemptID string      `json:"attempt_id"`
}

type Role

type Role struct {
	Role             domain.Role `json:"role"`
	Required         bool        `json:"required"`
	Outcome          string      `json:"outcome"`
	AttemptID        string      `json:"attempt_id"`
	ProviderInstance string      `json:"provider_instance"`
	ReportsOnly      bool        `json:"reports_only"`
	Report           *Blob       `json:"report"`
	FindingIDs       []string    `json:"finding_ids"`
}

type SchemaValidator

type SchemaValidator interface {
	Validate(context.Context, ports.AssetID, []byte) error
}

type Snapshot

type Snapshot struct {
	// contains filtered or unexported fields
}

func Read

func Read(ctx context.Context, store ports.RunSupportArtifactStore, validator SchemaValidator, run ports.PublicationRun, maxManifestBytes int64) (Snapshot, error)

Read verifies the manifest, all original input and report blobs, captured evidence, and an unchanged manifest before returning replay authority.

func Restore

func Restore(ctx context.Context, raw []byte, blobs map[string][]byte) (Snapshot, error)

func (Snapshot) Blob

func (snapshot Snapshot) Blob(blob Blob) []byte

func (Snapshot) Document

func (snapshot Snapshot) Document() Document

func (Snapshot) Manifest

func (snapshot Snapshot) Manifest() []byte

func (Snapshot) Reference

func (snapshot Snapshot) Reference() (domain.SourceReference, error)

func (Snapshot) Status

func (snapshot Snapshot) Status() Status

type Source

type Source struct {
	Kind                   string  `json:"kind"`
	RunID                  string  `json:"run_id"`
	ReviewID               *string `json:"review_id"`
	RecoveryManifestSHA256 *string `json:"recovery_manifest_sha256"`
	AttemptID              string  `json:"attempt_id"`
	ReplayMode             string  `json:"replay_mode"`
}

func (Source) Reference

func (source Source) Reference() (domain.SourceReference, error)

type Status

type Status struct {
	Available         bool           `json:"available"`
	SourceKind        *string        `json:"source_kind"`
	RunID             *string        `json:"run_id"`
	ManifestSHA256    *string        `json:"manifest_sha256"`
	AcceptedRoles     []domain.Role  `json:"accepted_roles"`
	RetryAttempts     []RetryAttempt `json:"retry_attempts"`
	UnavailableReason *string        `json:"unavailable_reason"`
}

Status exposes replay admission without granting final-review authority.

func UnavailableStatus

func UnavailableStatus(reason string) Status

func (Status) ValidateFor

func (status Status) ValidateFor(runID domain.RunID) error

type Target

type Target struct {
	Kind              domain.TargetKind    `json:"kind"`
	SHA256            string               `json:"sha256"`
	RepositoryID      string               `json:"repository_id"`
	BaseObjectID      string               `json:"base_object_id"`
	HeadObjectID      string               `json:"head_object_id"`
	HeadTreeObjectID  string               `json:"head_tree_object_id"`
	IndexTreeObjectID string               `json:"index_tree_object_id"`
	GitMode           domain.GitTargetMode `json:"git_mode"`
	Bytes             Blob                 `json:"bytes"`
	CapturedArchive   Blob                 `json:"captured_archive"`
}

func (Target) Identity

func (target Target) Identity() (domain.TargetIdentity, error)

type Visual

type Visual struct {
	Path   string `json:"path"`
	SHA256 string `json:"sha256"`
	X      int    `json:"x"`
	Y      int    `json:"y"`
	Width  int    `json:"width"`
	Height int    `json:"height"`
}

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL