Documentation
¶
Overview ¶
Package clean builds deterministic, side-effect-free retention plans.
Index ¶
- Constants
- func CanonicalPlanBytes(plan CleanPlan) ([]byte, error)
- func ExecuteApply(ctx context.Context, store ApplyStore, apply CleanPlan) error
- func IsFailure(err error, kind FailureKind) bool
- func PlanHash(plan CleanPlan) (string, error)
- func ResumeTombstones(ctx context.Context, store ApplyStore) error
- type AncestorProtection
- type ApplyIdentity
- type ApplyStore
- type ByteAccounting
- type CleanPlan
- type CleanupTransaction
- type DeleteSetEntry
- type DeleteSets
- type Failure
- type FailureKind
- type GraphAnomalyComponent
- type LineageEdgeObservation
- type LineageEdgeRef
- type OrderedAction
- type Policy
- type Reason
- type Request
- type Result
- type RetentionProtection
- type RetentionSnapshot
- type RunDecision
- type RunKind
- type RunObservation
- type SchemaValidator
- type Service
- type StoreEpoch
- type Tombstone
Constants ¶
const SchemaVersion = "mulgae-clean-plan.v1"
Variables ¶
This section is empty.
Functions ¶
func CanonicalPlanBytes ¶
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 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 {
Observe(context.Context) (RetentionSnapshot, error)
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 ¶
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.
type CleanupTransaction ¶
type CleanupTransaction interface {
Snapshot(context.Context) (RetentionSnapshot, error)
DryRunPlan(context.Context, string) (CleanPlan, error)
PersistDryRunPlan(context.Context, CleanPlan) error
ClearDryRunPlans(context.Context) 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 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
}
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 OrderedAction ¶
type Reason ¶
type Reason string
const ( ReasonProtectedExplicit Reason = "protected_explicit" ReasonActive Reason = "active" ReasonUncommitted Reason = "uncommitted" ReasonCorrupt Reason = "corrupt" 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 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 RunObservation ¶
type SchemaValidator ¶
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 a fixed clock, schema validation, and the durable cleanup store.
func NewService ¶
func NewService(clock ports.Clock, validator SchemaValidator, store ApplyStore) (*Service, error)
NewService constructs a cleanup service with only explicit authorities.