clean

package
v0.1.1 Latest Latest
Warning

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

 Go to latest Published: Aug 4, 2026 License: MIT Imports: 15 Imported by: 0

Documentation

Overview

Package clean builds deterministic, side-effect-free retention plans.

Index

Constants

View Source 
const SchemaVersion = "mulgae-clean-plan.v1"

Variables

This section is empty.

Functions

func CanonicalPlanBytes 

func CanonicalPlanBytes(plan CleanPlan) ([]byte, error)

CanonicalPlanBytes returns the RFC 8785-compatible JSON hash preimage. Clean plans contain only strings, integers, booleans, nulls, arrays, and objects; encoding/json's lexicographic object ordering is therefore RFC 8785 ordering for this schema after HTML escaping is disabled. No floats are admitted.

func ExecuteApply 

func ExecuteApply(ctx context.Context, store ApplyStore, apply CleanPlan) error

ExecuteApply verifies an exact dry-run identity against a fresh observation, then executes only the listed tombstone/delete pairs. It never recomputes a retention plan.

func IsFailure 

func IsFailure(err error, kind FailureKind) bool

func PlanHash 

func PlanHash(plan CleanPlan) (string, error)

PlanHash returns the domain-separated digest over CanonicalPlanBytes.

func ResumeTombstones 

func ResumeTombstones(ctx context.Context, store ApplyStore) error

ResumeTombstones completes durable deletions after an interrupted apply. Tombstones are sorted to make recovery deterministic and are not replanned.

Types

type AncestorProtection 

type AncestorProtection struct {
	AncestorRunID           string           `json:"ancestor_run_id"`
	RetainedDescendantRunID string           `json:"retained_descendant_run_id"`
	LineageEdgeRefs         []LineageEdgeRef `json:"lineage_edge_refs"`
}

type ApplyIdentity 

type ApplyIdentity struct {
	DryRunPlanHash            string     `json:"dry_run_plan_hash"`
	ExpectedStoreEpoch        StoreEpoch `json:"expected_store_epoch"`
	ExpectedInputPolicySHA256 string     `json:"expected_input_policy_sha256"`
}

type ApplyStore 

type ApplyStore interface {
	WithCleanupTransaction(context.Context, func(CleanupTransaction) error) error
}

ApplyStore supplies durable deletion mechanics. WithCleanupTransaction MUST hold one exclusive store lock for the complete callback, including snapshot, validation, tombstone commits, and deletion.

type ByteAccounting 

type ByteAccounting struct {
	InitialRegularFileBytes   int64 `json:"initial_regular_file_bytes"`
	AgeDeleteBytes            int64 `json:"age_delete_bytes"`
	SizeDeleteBytes           int64 `json:"size_delete_bytes"`
	PlannedDeleteBytes        int64 `json:"planned_delete_bytes"`
	ProjectedRegularFileBytes int64 `json:"projected_regular_file_bytes"`
	TargetBytes               int64 `json:"target_bytes"`
	TargetReached             bool  `json:"target_reached"`
}

type CleanPlan 

type CleanPlan struct {
	SchemaVersion       string              `json:"schema_version"`
	Mode                string              `json:"mode"`
	Now                 string              `json:"now"`
	StoreEpoch          StoreEpoch          `json:"store_epoch"`
	InputPolicySHA256   string              `json:"input_policy_sha256"`
	Policy              Policy              `json:"policy"`
	RetentionProtection RetentionProtection `json:"retention_protection"`
	RunDecisions        []RunDecision       `json:"run_decisions"`
	DeleteSets          DeleteSets          `json:"delete_sets"`
	OrderedActions      []OrderedAction     `json:"ordered_actions"`
	ByteAccounting      ByteAccounting      `json:"byte_accounting"`
	OutcomeReasons      []Reason            `json:"outcome_reasons"`
	PlanHash            string              `json:"plan_hash"`
	ApplyIdentity       *ApplyIdentity      `json:"apply_identity"`
}

func ApplyPlan 

func ApplyPlan(dryRun CleanPlan) (CleanPlan, error)

ApplyPlan returns the effect-plan identity paired with a dry-run plan. The hash remains identical because mode and apply identity are excluded from the domain hash preimage.

func Plan 

func Plan(snapshot RetentionSnapshot) (CleanPlan, error)

Plan computes a dry-run plan from a fixed retention observation. It performs no I/O and never retains references to caller-owned slices.

func (CleanPlan) Clone 

func (p CleanPlan) Clone() CleanPlan

type CleanupTransaction 

type CleanupTransaction interface {
	Snapshot(context.Context) (RetentionSnapshot, error)
	DryRunPlan(context.Context, string) (CleanPlan, error)
	PersistDryRunPlan(context.Context, CleanPlan) error
	Tombstones(context.Context) ([]Tombstone, error)
	Tombstone(context.Context, Tombstone) error
	DeleteTombstoned(context.Context, Tombstone) error
}

CleanupTransaction is the exclusive artifact-store scope for a cleanup observation and its destructive effects.

type DeleteSetEntry 

type DeleteSetEntry struct {
	RunID            string `json:"run_id"`
	CompletedAt      string `json:"completed_at"`
	RegularFileBytes int64  `json:"regular_file_bytes"`
	Reason           Reason `json:"reason"`
}

type DeleteSets 

type DeleteSets struct {
	AgeDeleteSet  []DeleteSetEntry `json:"age_delete_set"`
	SizeDeleteSet []DeleteSetEntry `json:"size_delete_set"`
}

type Failure 

type Failure struct {
	Kind    FailureKind
	Message string
	Cause   error
}

func (*Failure) Error 

func (failure *Failure) Error() string

func (*Failure) Unwrap 

func (failure *Failure) Unwrap() error

type FailureKind 

type FailureKind string
const (
	FailureInvalidSnapshot FailureKind = "invalid_snapshot"
	FailureInvalidGraph    FailureKind = "invalid_graph"
	FailureInvalidPath     FailureKind = "invalid_path"
	FailureStalePlan       FailureKind = "stale_plan"
	FailureTombstone       FailureKind = "tombstone"
)

type GraphAnomalyComponent 

type GraphAnomalyComponent struct {
	AffectedRunIDs  []string         `json:"affected_run_ids"`
	LineageEdgeRefs []LineageEdgeRef `json:"lineage_edge_refs"`
}

type LineageEdgeObservation 

type LineageEdgeObservation struct {
	LineageEdgeRef
	// Valid is false when the edge record is malformed or fails its integrity checks.
	Valid bool
}

type LineageEdgeRef 

type LineageEdgeRef struct {
	ParentRunID string `json:"parent_run_id"`
	ChildRunID  string `json:"child_run_id"`
	EdgePath    string `json:"edge_path"`
	SHA256      string `json:"sha256"`
}

type Mode 

type Mode string

Mode selects a command-facing cleanup operation. 

const (
	ModeDryRun  Mode = "dry_run"
	ModeExplain Mode = "explain"
	ModeApply   Mode = "apply"
)

type OrderedAction 

type OrderedAction struct {
	Sequence      int    `json:"sequence"`
	Phase         string `json:"phase"`
	Action        string `json:"action"`
	RunID         string `json:"run_id"`
	Reason        Reason `json:"reason"`
	BytesReleased int64  `json:"bytes_released"`
}

type Policy 

type Policy struct {
	RetentionAgeSeconds  int64    `json:"retention_age_seconds"`
	MinAgeForSizeSeconds int64    `json:"min_age_for_size_seconds"`
	TargetBytes          int64    `json:"target_bytes"`
	ExplicitKeepRunIDs   []string `json:"explicit_keep_run_ids"`
}

type Reason 

type Reason string
const (
	ReasonProtectedExplicit Reason = "protected_explicit"
	ReasonActive            Reason = "active"
	ReasonUncommitted       Reason = "uncommitted"
	ReasonCorrupt           Reason = "corrupt"
	ReasonNewestSession     Reason = "newest_session"
	ReasonAncestor          Reason = "ancestor"
	ReasonGraphAnomaly      Reason = "graph_anomaly"
	ReasonMissingTime       Reason = "missing_time"
	ReasonYoung             Reason = "young"
	ReasonEligibleAge       Reason = "eligible_age"
	ReasonEligibleSize      Reason = "eligible_size"
	ReasonDeletedAge        Reason = "deleted_age"
	ReasonDeletedSize       Reason = "deleted_size"
	ReasonTargetProtected   Reason = "target_not_reached_protected"
	ReasonStaleEpoch        Reason = "stale_epoch"
	ReasonPartialResume     Reason = "partial_delete_resume"
)

type Request 

type Request struct {
	Mode               Mode
	ExpectedPlanSHA256 string
}

Request is a cleanup command selection. ExpectedPlanSHA256 is required only for ModeApply.

type Result 

type Result struct {
	Plan        CleanPlan
	ExplainRows []string
}

Result is the immutable plan projection and optional deterministic explain rows.

type RetentionPolicySource 

type RetentionPolicySource interface {
	RetentionPolicy(context.Context) (Policy, string, error)
}

RetentionPolicySource is the sole authority for cleanup retention policy. Implementations must return the exact resolved policy and its canonical digest.

type RetentionProtection 

type RetentionProtection struct {
	RetainedSeedRunIDs           []string                `json:"retained_seed_run_ids"`
	TransitiveAncestorProtection []AncestorProtection    `json:"transitive_ancestor_protection"`
	GraphAnomalyComponents       []GraphAnomalyComponent `json:"graph_anomaly_components"`
}

type RetentionSnapshot 

type RetentionSnapshot struct {
	Now                       time.Time
	StoreEpoch                StoreEpoch
	InputPolicySHA256         string
	Policy                    Policy
	Runs                      []RunObservation
	Edges                     []LineageEdgeObservation
	ProtectedRegularFileBytes int64
}

func (RetentionSnapshot) Clone 

func (s RetentionSnapshot) Clone() RetentionSnapshot

type RunDecision 

type RunDecision struct {
	RunID    string   `json:"run_id"`
	Decision string   `json:"decision"`
	Reasons  []Reason `json:"reasons"`
}

type RunKind 

type RunKind string
const (
	RunKindPublication    RunKind = "publication"
	RunKindDiagnosticOnly RunKind = "diagnostic_only"
)

type RunObservation 

type RunObservation struct {
	RunID               string
	SessionID           string
	Kind                RunKind
	Completed           bool
	CompletedAt         *time.Time
	Active              bool
	Committed           bool
	Corrupt             bool
	DiagnosticProtected bool
	RegularFileBytes    int64
}

type SchemaValidator 

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

SchemaValidator validates a candidate plan against the embedded clean-plan contract before it becomes a durable receipt.

type Service 

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

Service composes explicit policy authority, a fixed clock, schema validation, and the durable cleanup store. It has no policy defaults or provider dependency.

func NewService 

func NewService(clock ports.Clock, policy RetentionPolicySource, validator SchemaValidator, store ApplyStore) (*Service, error)

NewService constructs a cleanup service with only explicit authorities.

func (*Service) Run 

func (service *Service) Run(ctx context.Context, request Request) (Result, error)

Run executes one command-facing cleanup operation. It always resumes durable tombstones before observing a new dry-run plan or executing a hash-bound apply.

type StoreEpoch 

type StoreEpoch struct {
	Value  int64  `json:"value"`
	SHA256 string `json:"sha256"`
}

type Tombstone 

type Tombstone struct {
	RunID    string
	PlanHash string
}

Tombstone is the durable authorization to remove one run. A deletion may be retried only from this record; an unjournaled partial directory is never inferred to be eligible for deletion.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.