engine

package
v1.13.7 Latest Latest
Warning

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

 Go to latest Published: Jun 20, 2026 License: Apache-2.0 Imports: 20 Imported by: 0

Documentation

Overview

Package engine defines the behavior-preserving facade for coldkeep operations.

v1.11.0 — Behavior-Preserving Engine Facade Baseline.

This package introduces the engine boundary without changing any observable behavior. CLI commands are not routed through the engine in Phase 1. Wrapper-only implementation begins in Phase 2.

Invariants

Engine callers must not weaken these invariants:

  • GC must never delete reachable data.
  • Restore must never write outside the intended destination.
  • Verify must fail closed on inconsistent catalog/storage state.
  • Recovery must not legitimize corrupt mappings.
  • Packed and legacy storage behavior must remain aligned.
  • CLI parsing must not be the only place where correctness invariants live.
  • Engine APIs must not weaken existing safety guarantees.

Dependency direction 

cmd/coldkeep    may import internal/engine
internal/engine must not import cmd/coldkeep
domain packages must not import internal/engine

Index

Constants

This section is empty.

Variables

View Source 
var ErrNotImplemented = errors.New("engine operation not implemented")

ErrNotImplemented is returned by engine methods that are not yet wired to real implementations. Wrapper-only implementation begins in Phase 2.

Functions

func IsUnsupported added in v1.13.2 

func IsUnsupported(err error) bool

IsUnsupported classifies only active unsupported engine modes already represented by ErrNotImplemented.

It does not classify validation, domain, invariant, runtime, catalog, or storage failures. It also does not imply deferred candidate-only surfaces are active. The helper is intentionally narrow for v1.13.2.

Types

type BatchItemStatus added in v1.12.0 

type BatchItemStatus string

BatchItemStatus is the outcome of a single item within a batch operation. 

const (
	// BatchItemOK indicates the item completed successfully.
	BatchItemOK BatchItemStatus = "ok"
	// BatchItemFailed indicates the item failed.
	BatchItemFailed BatchItemStatus = "failed"
	// BatchItemSkipped indicates the item was skipped (e.g. dry-run/no-op).
	BatchItemSkipped BatchItemStatus = "skipped"
)

type BatchSummary added in v1.12.0 

type BatchSummary struct {
	OK      int
	Failed  int
	Skipped int
}

BatchSummary aggregates the outcome counts of a batch operation.

type Config 

type Config struct {
	// DB is the active database connection.
	// The caller is responsible for the connection lifetime.
	DB *sql.DB
	// ContainerDir is the path to the coldkeep containers directory.
	// Defaults to container.ContainersDir if empty.
	ContainerDir string
	// StoreContext provides writer+chunker-aware dependencies for store wrappers.
	// Phase 8: required for Store until store orchestration is fully engine-owned.
	StoreContext *storage.StorageContext
}

Config holds configuration for a DefaultEngine.

Database backend selection (SQLite vs PostgreSQL) is not decided here; the caller is responsible for opening the correct backend and providing the connection. Config fields will expand as wrapper-only implementations require additional dependencies.

type DefaultEngine 

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

DefaultEngine is the canonical Engine implementation.

Phase 2: wrapper-only. All methods delegate to existing domain packages. No business logic is moved; the engine is a thin delegation layer.

func New 

func New(cfg Config) (*DefaultEngine, error)

New returns a new DefaultEngine with the given configuration. Returns an error if DB is nil or if the observability service cannot be initialized.

func (*DefaultEngine) GarbageCollect added in v1.12.0 

func (e *DefaultEngine) GarbageCollect(ctx context.Context, req GarbageCollectRequest) (GarbageCollectResult, error)

func (*DefaultEngine) Inspect 

func (e *DefaultEngine) Inspect(ctx context.Context, req InspectRequest) (InspectResult, error)

func (*DefaultEngine) Remove added in v1.12.0 

func (e *DefaultEngine) Remove(ctx context.Context, req RemoveRequest) (RemoveResult, error)

func (*DefaultEngine) Restore added in v1.12.0 

func (e *DefaultEngine) Restore(ctx context.Context, req RestoreRequest) (RestoreResult, error)

func (*DefaultEngine) SnapshotDiff added in v1.12.0 

func (e *DefaultEngine) SnapshotDiff(ctx context.Context, req SnapshotDiffRequest) (SnapshotDiffResult, error)

func (*DefaultEngine) SnapshotList added in v1.12.0 

func (e *DefaultEngine) SnapshotList(ctx context.Context, req SnapshotListRequest) (SnapshotListResult, error)

func (*DefaultEngine) SnapshotShow added in v1.12.0 

func (e *DefaultEngine) SnapshotShow(ctx context.Context, req SnapshotShowRequest) (SnapshotShowResult, error)

func (*DefaultEngine) SnapshotStats added in v1.12.0 

func (e *DefaultEngine) SnapshotStats(ctx context.Context, req SnapshotStatsRequest) (SnapshotStatsResult, error)

func (*DefaultEngine) Stats 

func (e *DefaultEngine) Stats(ctx context.Context, req StatsRequest) (StatsResult, error)

func (*DefaultEngine) Store added in v1.12.0 

func (e *DefaultEngine) Store(ctx context.Context, req StoreRequest) (StoreResult, error)

func (*DefaultEngine) Verify 

func (e *DefaultEngine) Verify(ctx context.Context, req VerifyRequest) (VerifyResult, error)

type Engine 

type Engine interface {
	// Stats returns repository statistics.
	Stats(ctx context.Context, req StatsRequest) (StatsResult, error)

	// Inspect returns metadata about a stored file.
	Inspect(ctx context.Context, req InspectRequest) (InspectResult, error)

	// Verify runs repository verification.
	Verify(ctx context.Context, req VerifyRequest) (VerifyResult, error)

	// SnapshotList returns snapshots matching the request filters.
	SnapshotList(ctx context.Context, req SnapshotListRequest) (SnapshotListResult, error)

	// SnapshotShow returns metadata and filtered files for a single snapshot.
	SnapshotShow(ctx context.Context, req SnapshotShowRequest) (SnapshotShowResult, error)

	// SnapshotStats returns aggregate or per-snapshot statistics.
	SnapshotStats(ctx context.Context, req SnapshotStatsRequest) (SnapshotStatsResult, error)

	// SnapshotDiff compares two snapshots and returns change entries.
	SnapshotDiff(ctx context.Context, req SnapshotDiffRequest) (SnapshotDiffResult, error)

	// GarbageCollect runs dry-run or live GC against the repository.
	// Safety invariant: GC must never delete reachable data.
	// Live GC is only supported on the PostgreSQL backend; dry-run is supported
	// on both backends.
	GarbageCollect(ctx context.Context, req GarbageCollectRequest) (GarbageCollectResult, error)

	// Store stores a file into the repository.
	// Safety invariant: Store must not create inconsistent catalog/storage state.
	// Phase 8: single-file mode is active; folder mode remains deferred.
	Store(ctx context.Context, req StoreRequest) (StoreResult, error)

	// Remove removes logical files from the repository.
	// Safety invariant: Remove must never make valid data unrecoverable.
	// Phase 9: file-ID mode is active; stored-path modes remain deferred.
	Remove(ctx context.Context, req RemoveRequest) (RemoveResult, error)

	// Restore restores logical files by ID or by stored path.
	// Safety invariant: Restore must never write outside the intended destination.
	// Phase 7: file-ID mode is active; stored-path mode remains deferred.
	Restore(ctx context.Context, req RestoreRequest) (RestoreResult, error)
}

Engine is the behavior-preserving facade for coldkeep operations.

All implementations must preserve existing CLI output, JSON output, exit codes, storage format, repository format, and schema behavior.

Phase 1: interface contract only. Methods return ErrNotImplemented until Phase 2 wrapper-only implementation is complete.

type ExecutionMode added in v1.12.0 

type ExecutionMode string

ExecutionMode describes how a batch operation was executed. It mirrors the existing execution semantics without encoding CLI syntax. 

const (
	// ExecutionModeSequential processes batch items one at a time.
	ExecutionModeSequential ExecutionMode = "sequential"
	// ExecutionModeParallel processes batch items with multiple workers.
	ExecutionModeParallel ExecutionMode = "parallel"
)

type GarbageCollectRequest 

type GarbageCollectRequest struct {
	// DryRun simulates the collection without deleting.
	DryRun bool
	// Workers is the parallelism; zero means the default.
	Workers int
}

GarbageCollectRequest is a candidate request for a future GarbageCollect operation. Not part of the active v1.12 Engine interface.

Safety invariant: GC must never delete reachable data.

type GarbageCollectResult 

type GarbageCollectResult struct {
	// DryRun echoes whether the operation was a simulation.
	DryRun bool
	// AffectedContainers is the count of containers deleted (or that would be).
	AffectedContainers int
	// ContainerFilenames lists the affected container filenames.
	ContainerFilenames []string
	// SnapshotRetainedContainers is the count of containers retained because a
	// snapshot references them.
	SnapshotRetainedContainers int
	// SnapshotRetainedLogicalFiles is the count of logical files retained by
	// snapshots.
	SnapshotRetainedLogicalFiles int
	// CurrentOnlyRetainedLogicalFiles, SnapshotOnlyRetainedLogicalFiles, and
	// SharedRetainedLogicalFiles break down retention by reachability source.
	CurrentOnlyRetainedLogicalFiles  int
	SnapshotOnlyRetainedLogicalFiles int
	SharedRetainedLogicalFiles       int
	// BytesReclaimed is the number of bytes reclaimed (or reclaimable).
	BytesReclaimed int64
	// Warnings carries structured, non-fatal warnings.
	Warnings []OperationWarning
}

GarbageCollectResult is a candidate result for a future GarbageCollect operation. Not part of the active v1.12 Engine interface.

The retention fields represent both packed and legacy roots so that GC plan reporting can stay backend- and storage-format-neutral.

type InspectRequest 

type InspectRequest struct {
	// Entity is the type of entity to inspect.
	Entity observability.EntityType
	// EntityID is the string identifier for the entity.
	// For EntityRepository this field is ignored.
	EntityID string
	// Options controls relation traversal, depth, and trace behavior.
	Options observability.InspectOptions
}

InspectRequest carries parameters for the Inspect operation.

type InspectResult 

type InspectResult struct {
	// Raw is the underlying observability result.
	Raw *observability.InspectResult
}

InspectResult carries the result of the Inspect operation.

type OperationWarning added in v1.12.0 

type OperationWarning struct {
	// Code is a stable machine-readable identifier for the warning class.
	Code string
	// Message is a short human-readable description.
	Message string
	// Detail carries optional additional context (e.g. an offending path).
	Detail string
}

OperationWarning is a structured, renderer-neutral warning produced by an engine operation. CLI rendering (human or JSON) is the caller's concern.

type RecoverRequest 

type RecoverRequest struct {
	// DryRun reports what recovery would do without mutating.
	DryRun bool
}

RecoverRequest is a candidate request for a future corrective Recover operation. Not part of the active v1.12 Engine interface.

Candidate-only in v1.13.1: request/result presence must not be mistaken for active engine ownership. Repair and recover remain CLI/domain owned until the explicit corrective-integrity follow-up in v1.13.9.

Safety invariant: Recovery must not legitimize corrupt mappings. Recovery is a corrective integrity pass (abort dangling writes, clear stale sealing markers, quarantine corrupt/orphaned data), NOT a restore. The previous placeholder modeled it like a restore; that was incorrect.

type RecoverResult 

type RecoverResult struct {
	AbortedLogicalFiles    int
	AbortedChunks          int
	QuarantinedMissing     int
	QuarantinedCorruptTail int
	QuarantinedOrphan      int
	SkippedDirEntries      int
	CheckedContainerRecord int
	CheckedDiskFiles       int
	SealingCompleted       int
	SealingQuarantined     int
	Warnings               []OperationWarning
}

RecoverResult is a candidate result for a future Recover operation. Not part of the active v1.12 Engine interface.

Fields mirror the existing recovery report so the corrective outcome can be represented without CLI rendering.

type RemoveItemResult added in v1.12.0 

type RemoveItemResult struct {
	// FileID is the logical file ID (file-ID mode).
	FileID int64
	// StoredPath is the stored path (stored-path modes).
	StoredPath string
	// RemovedMappings is the count of removed chunk mappings (file-ID mode).
	RemovedMappings int
	// RemainingRefCount is the logical-file ref count after removal.
	RemainingRefCount int
	// Removed indicates whether the logical file row was removed.
	Removed bool
	// Status is the per-item outcome.
	Status BatchItemStatus
	// Error is a non-empty message when Status is failed.
	Error string
	// InvariantCode is the machine-readable invariant identifier when available.
	InvariantCode string
	// RecommendedAction is operator guidance associated with InvariantCode.
	RecommendedAction string
}

RemoveItemResult is the outcome of removing a single target.

type RemoveMode added in v1.12.0 

type RemoveMode string

RemoveMode selects how remove targets are addressed. 

const (
	// RemoveModeFileIDs removes one or more logical file IDs.
	RemoveModeFileIDs RemoveMode = "file_ids"
	// RemoveModeStoredPath removes a single stored path.
	RemoveModeStoredPath RemoveMode = "stored_path"
	// RemoveModeStoredPaths removes a batch of stored paths.
	RemoveModeStoredPaths RemoveMode = "stored_paths"
)

type RemoveRequest 

type RemoveRequest struct {
	// Mode selects file-ID, single stored-path, or stored-paths addressing.
	// Support limitation in v1.13.1: only RemoveModeFileIDs is active through
	// Engine.Remove.
	Mode RemoveMode
	// FileIDs is the set of logical file IDs to remove (Mode == file_ids).
	FileIDs []int64
	// StoredPath is the single stored path to remove (Mode == stored_path).
	// Support limitation in v1.13.1: this remains a direct CLI/storage concern,
	// not an active Engine.Remove field.
	StoredPath string
	// StoredPaths is the batch of stored paths (Mode == stored_paths).
	// Support limitation in v1.13.1: this remains a direct CLI/batch concern,
	// not an active Engine.Remove field.
	StoredPaths []string
	// DryRun simulates without mutating.
	DryRun bool
	// FailFast stops a batch on the first failure.
	FailFast bool
	// InputPath is an optional batch-input source.
	//
	// Deferred: batch input parsing ownership is decided in Phase 9. The field
	// remains provisional and does not imply active stored-path engine support.
	InputPath string
}

RemoveRequest is a candidate request for a future Remove operation. Not part of the active v1.12 Engine interface.

Support limitation in v1.13.1: the active engine route owns only file-ID remove. Stored-path and stored-paths modes remain outside the active engine path; non-file-ID engine calls return ErrNotImplemented and are covered by Phase 2 tests. Contract split cleanup belongs to v1.13.7.

type RemoveResult 

type RemoveResult struct {
	// DryRun echoes whether the operation was a simulation.
	DryRun bool
	// ExecutionMode echoes how the batch was executed.
	ExecutionMode ExecutionMode
	// Items holds per-target outcomes.
	Items []RemoveItemResult
	// Summary aggregates the item outcomes.
	Summary BatchSummary
	// Warnings carries structured, non-fatal warnings.
	Warnings []OperationWarning
}

RemoveResult is a candidate result for a future Remove operation. Not part of the active v1.12 Engine interface.

type RepairRequest 

type RepairRequest struct {
	// Target selects the single-target repair (when Batch is false).
	Target RepairTarget
	// Batch processes multiple targets.
	Batch bool
	// Targets is the explicit batch target list.
	Targets []RepairTarget
	// FailFast stops a batch on the first failure.
	FailFast bool
	// InputPath is an optional batch-input source.
	//
	// Deferred: batch input parsing ownership is decided in Phase 9; it may
	// remain a CLI-level concern rather than an engine input.
	InputPath string
	// DryRun simulates without mutating, where supported.
	DryRun bool
	// Limit caps the number of rows processed when greater than zero.
	Limit int
}

RepairRequest is a candidate request for a future Repair operation. Not part of the active v1.12 Engine interface.

Candidate-only in v1.13.1: request/result presence must not be mistaken for active engine ownership. Repair and recover remain CLI/domain owned until the explicit corrective-integrity follow-up in v1.13.9.

type RepairResult 

type RepairResult struct {
	// Targets holds per-target outcomes.
	Targets []RepairTargetResult
	// Summary aggregates the target outcomes.
	Summary  BatchSummary
	Warnings []OperationWarning
}

RepairResult is a candidate result for a future Repair operation. Not part of the active v1.12 Engine interface.

type RepairTarget added in v1.12.0 

type RepairTarget string

RepairTarget selects which integrity recomputation a repair performs. 

const (
	// RepairTargetRefCounts recomputes logical_file.ref_count.
	RepairTargetRefCounts RepairTarget = "ref-counts"
	// RepairTargetChunkLiveRefCounts recomputes chunk.live_ref_count.
	RepairTargetChunkLiveRefCounts RepairTarget = "chunk-live-ref-counts"
)

type RepairTargetResult added in v1.12.0 

type RepairTargetResult struct {
	Target RepairTarget
	// ScannedRows and UpdatedRows are generic counters covering both
	// logical-file and chunk recomputations.
	ScannedRows int
	UpdatedRows int
	// OrphanRows captures orphan physical-file rows for ref-count repair.
	OrphanRows int
	Status     BatchItemStatus
	Error      string
}

RepairTargetResult is the outcome of a single repair target.

type RestoreDestinationMode added in v1.12.0 

type RestoreDestinationMode string

RestoreDestinationMode controls how a restored file's output location is derived. It mirrors the existing stored-path restore modes. 

const (
	// RestoreDestinationOriginal reconstructs the file at its original path.
	RestoreDestinationOriginal RestoreDestinationMode = "original"
	// RestoreDestinationPrefix prepends a destination prefix to the path.
	RestoreDestinationPrefix RestoreDestinationMode = "prefix"
	// RestoreDestinationOverride writes to an exact destination path.
	RestoreDestinationOverride RestoreDestinationMode = "override"
)

type RestoreItemResult added in v1.12.0 

type RestoreItemResult struct {
	// FileID is the logical file ID (file-ID mode).
	FileID int64
	// StoredPath is the stored path (stored-path mode).
	StoredPath string
	// OutputPath is the path the file was (or would be) written to.
	OutputPath string
	// RestoredHash is the content hash of the restored file.
	RestoredHash string
	// Status is the per-item outcome.
	Status BatchItemStatus
	// Error is a non-empty message when Status is failed.
	Error string
}

RestoreItemResult is the outcome of restoring a single target.

type RestoreMode added in v1.12.0 

type RestoreMode string

RestoreMode selects how restore targets are addressed. 

const (
	// RestoreModeFileIDs restores one or more logical file IDs to a directory.
	RestoreModeFileIDs RestoreMode = "file_ids"
	// RestoreModeStoredPath restores a single stored path.
	RestoreModeStoredPath RestoreMode = "stored_path"
)

type RestoreRequest 

type RestoreRequest struct {
	// Mode selects file-ID or stored-path addressing.
	// Support limitation in v1.13.1: only RestoreModeFileIDs is active through
	// Engine.Restore.
	Mode RestoreMode

	// FileIDs is the set of logical file IDs to restore (Mode == file_ids).
	FileIDs []int64
	// OutputDir is the destination directory for file-ID restore.
	OutputDir string

	// StoredPath is the single stored path to restore (Mode == stored_path).
	// Support limitation in v1.13.1: this remains a direct CLI/storage concern,
	// not an active Engine.Restore field.
	StoredPath string
	// DestinationMode controls output location derivation for stored-path
	// restore.
	// Support limitation in v1.13.1: destination-mode handling applies only to
	// deferred stored-path restore, not the active file-ID engine route.
	DestinationMode RestoreDestinationMode
	// Destination is the prefix or override target, required by prefix/override
	// destination modes.
	// Support limitation in v1.13.1: this is meaningful only for deferred
	// stored-path restore.
	Destination string
	// Strict enforces strict metadata application.
	Strict bool
	// NoMetadata disables metadata application (mutually exclusive with Strict).
	NoMetadata bool

	// Overwrite permits overwriting existing files.
	Overwrite bool
	// DryRun simulates without writing.
	DryRun bool
	// FailFast stops a batch on the first failure.
	FailFast bool
	// InputPath is an optional batch-input source for file-ID restore.
	//
	// Deferred: whether batch input parsing remains a CLI-level concern or moves
	// into the engine is decided in Phase 7. Retained here so the contract can
	// represent the existing command, but current engine support still covers
	// only the file-ID execution subset.
	InputPath string
	// Workers is the batch parallelism; zero means the default.
	// Support limitation in v1.13.1: execution remains sequential today; this
	// field is provisional rather than proof of active worker support.
	Workers int
	// Limit caps the number of restored items when greater than zero.
	// Support limitation in v1.13.1: this remains a provisional batch-shaping
	// field on a contract that is not yet split cleanly by ownership.
	Limit int
}

RestoreRequest is a candidate request for a future Restore operation. Not part of the active v1.12 Engine interface.

Safety invariant: Restore must never write outside the intended destination. The destination/mode fields exist precisely so this invariant can be enforced in the engine/catalog rather than only in the CLI.

Support limitation in v1.13.1: the active engine route owns only file-ID restore. Stored-path restore and its destination semantics remain outside the active engine path; non-file-ID engine calls return ErrNotImplemented and are covered by Phase 2 tests. Contract split cleanup belongs to v1.13.7.

type RestoreResult 

type RestoreResult struct {
	// DryRun echoes whether the operation was a simulation.
	DryRun bool
	// ExecutionMode echoes how the batch was executed.
	ExecutionMode ExecutionMode
	// Items holds per-target outcomes.
	Items []RestoreItemResult
	// Summary aggregates the item outcomes.
	Summary BatchSummary
	// Warnings carries structured, non-fatal warnings.
	Warnings []OperationWarning
}

RestoreResult is a candidate result for a future Restore operation. Not part of the active v1.12 Engine interface.

type SnapshotCreateRequest 

type SnapshotCreateRequest struct {
	// ID is an optional caller-supplied snapshot ID; empty means auto-generate.
	ID string
	// Label is an optional human label.
	Label string
	// ParentID establishes lineage for delta/reuse analysis (the --from source).
	ParentID string
	// Paths scopes a partial snapshot; empty means a full snapshot.
	Paths []string
}

SnapshotCreateRequest is a candidate request for a future SnapshotCreate operation. Not part of the active v1.12 Engine interface.

Candidate-only in v1.13.1: request/result presence must not be mistaken for active engine ownership. Snapshot create/delete/restore remain CLI/domain owned until the explicit snapshot-mutation follow-up in v1.13.8.

Safety invariant: Snapshot operations must preserve immutability and retention semantics.

type SnapshotCreateResult 

type SnapshotCreateResult struct {
	SnapshotID    string
	Type          SnapshotType
	PathsCount    int
	FilesInserted int
	Label         string
	ParentID      string
	Warnings      []OperationWarning
}

SnapshotCreateResult is a candidate result for a future SnapshotCreate operation. Not part of the active v1.12 Engine interface.

type SnapshotDeleteRequest 

type SnapshotDeleteRequest struct {
	SnapshotID string
	// Force performs a live delete (mutually exclusive with DryRun).
	Force bool
	// DryRun simulates the delete.
	DryRun bool
}

SnapshotDeleteRequest is a candidate request for a future SnapshotDelete operation. Not part of the active v1.12 Engine interface.

Candidate-only in v1.13.1: request/result presence must not be mistaken for active engine ownership. Snapshot create/delete/restore remain CLI/domain owned until the explicit snapshot-mutation follow-up in v1.13.8.

Safety invariant: Snapshot operations must preserve immutability and retention semantics. Deleting a snapshot removes only its metadata; content referenced by other snapshots or the current state must be retained.

type SnapshotDeleteResult 

type SnapshotDeleteResult struct {
	SnapshotID string
	DryRun     bool
	ParentID   string
	// ParentMissing indicates the recorded parent no longer exists.
	ParentMissing bool
	// Children lists snapshot IDs whose lineage references this snapshot.
	Children []string
	// TotalFiles, UniqueFiles, and SharedFiles describe content impact.
	TotalFiles  int
	UniqueFiles int
	SharedFiles int
	Warnings    []OperationWarning
}

SnapshotDeleteResult is a candidate result for a future SnapshotDelete operation. Not part of the active v1.12 Engine interface.

type SnapshotDiffChange added in v1.12.0 

type SnapshotDiffChange string

SnapshotDiffChange classifies a single diff entry. 

const (
	SnapshotDiffChangeAdded    SnapshotDiffChange = "added"
	SnapshotDiffChangeRemoved  SnapshotDiffChange = "removed"
	SnapshotDiffChangeModified SnapshotDiffChange = "modified"
)

type SnapshotDiffEntry added in v1.12.0 

type SnapshotDiffEntry struct {
	StoredPath string
	Change     SnapshotDiffChange
}

SnapshotDiffEntry is a renderer-neutral diff entry.

type SnapshotDiffFilter added in v1.12.0 

type SnapshotDiffFilter string

SnapshotDiffFilter narrows a diff to a single change class. 

const (
	// SnapshotDiffAll includes all change classes.
	SnapshotDiffAll SnapshotDiffFilter = ""
	// SnapshotDiffAdded includes only added entries.
	SnapshotDiffAdded SnapshotDiffFilter = "added"
	// SnapshotDiffRemoved includes only removed entries.
	SnapshotDiffRemoved SnapshotDiffFilter = "removed"
	// SnapshotDiffModified includes only modified entries.
	SnapshotDiffModified SnapshotDiffFilter = "modified"
)

type SnapshotDiffRequest added in v1.12.0 

type SnapshotDiffRequest struct {
	BaseID   string
	TargetID string
	// Summary requests the summary-only fast path (no per-entry list).
	// Support limitation in v1.13.1: when this fast path is used, the current
	// engine result reports summary-only semantics rather than a full entry list.
	Summary bool
	// Filter narrows the diff to a single change class.
	// Support limitation in v1.13.1: filter behavior is layered on top of a
	// provisional diff seam and is not yet a frozen contract.
	Filter SnapshotDiffFilter
	// Query filters which entries are considered.
	Query SnapshotQuery
}

SnapshotDiffRequest is a candidate request for a future SnapshotDiff operation. Not part of the active v1.12 Engine interface.

Support limitation in v1.13.1: summary fast-path behavior and query/filter semantics remain provisional. The CLI can parse richer repeated path/prefix inputs than the current engine seam preserves, and full read-side cleanup belongs to v1.13.3.

type SnapshotDiffResult added in v1.12.0 

type SnapshotDiffResult struct {
	BaseID   string
	TargetID string
	// SummaryMode echoes whether the summary-only fast path was used.
	SummaryMode bool
	Summary     SnapshotDiffSummary
	// Entries is populated only when SummaryMode is false.
	Entries []SnapshotDiffEntry
	// MatchedEntryCount and TotalEntryCount describe filtering.
	MatchedEntryCount int
	TotalEntryCount   int
}

SnapshotDiffResult is a candidate result for a future SnapshotDiff operation. Not part of the active v1.12 Engine interface.

Support limitation in v1.13.1: SummaryMode, MatchedEntryCount, and TotalEntryCount are provisional read-side semantics. They reflect the current summary-versus-detailed seam and filtering behavior, not a frozen daemon/API-ready diff contract. Read-side cleanup belongs to v1.13.3.

type SnapshotDiffSummary added in v1.12.0 

type SnapshotDiffSummary struct {
	Added    int
	Removed  int
	Modified int
}

SnapshotDiffSummary aggregates change counts.

type SnapshotFile added in v1.12.0 

type SnapshotFile struct {
	StoredPath    string
	LogicalFileID int64
	Size          int64
	Mode          uint32
	ModTime       time.Time
}

SnapshotFile is a renderer-neutral file entry within a snapshot.

type SnapshotListRequest added in v1.12.0 

type SnapshotListRequest struct {
	// Type filters by snapshot type; empty means all.
	Type SnapshotType
	// Label filters by label substring.
	Label string
	// Since and Until bound the created-at range.
	Since *time.Time
	Until *time.Time
	// Limit caps the number of results when greater than zero.
	Limit int
	// Tree requests lineage-tree ordering/visualization data.
	// Support limitation in v1.13.1: this is a provisional view-shaping flag
	// and does not prove engine ownership of lineage presentation semantics.
	// Read-side cleanup belongs to v1.13.3 / v1.13.11.
	Tree bool
}

SnapshotListRequest is a candidate request for a future SnapshotList operation. Not part of the active v1.12 Engine interface.

type SnapshotListResult added in v1.12.0 

type SnapshotListResult struct {
	Snapshots []SnapshotMeta
	Count     int
	// TreeMode echoes whether tree data was requested.
	TreeMode bool
	// TreeLines holds renderer-neutral lineage rows when TreeMode is set.
	TreeLines []string
}

SnapshotListResult is a candidate result for a future SnapshotList operation. Not part of the active v1.12 Engine interface.

Support limitation in v1.13.1: TreeMode and TreeLines are provisional view-shaping fields. They do not prove engine ownership of lineage presentation semantics; read-side cleanup belongs to v1.13.3 / v1.13.11.

type SnapshotMeta added in v1.12.0 

type SnapshotMeta struct {
	ID        string
	Type      SnapshotType
	Label     string
	ParentID  string
	CreatedAt time.Time
	FileCount int
}

SnapshotMeta is the renderer-neutral metadata for a snapshot.

type SnapshotQuery added in v1.12.0 

type SnapshotQuery struct {
	// Path matches an exact stored path.
	// Support limitation in v1.13.1: only one exact path is preserved at the
	// current engine seam.
	Path string
	// Prefix matches stored paths by prefix.
	// Support limitation in v1.13.1: only one prefix is preserved at the
	// current engine seam.
	Prefix string
	// Pattern is a glob-style match against stored paths.
	Pattern string
	// Regex is a regular-expression match against stored paths.
	Regex string
	// MinSize, when set, filters files at or above the given byte size.
	MinSize *int64
	// MaxSize, when set, filters files at or below the given byte size.
	MaxSize *int64
	// ModifiedAfter, when set, filters files modified at or after the time.
	ModifiedAfter *time.Time
	// ModifiedBefore, when set, filters files modified at or before the time.
	ModifiedBefore *time.Time
	// Limit, when greater than zero, caps the number of returned files.
	Limit int
}

SnapshotQuery represents the renderer-neutral file-selection filters shared by snapshot show, diff, and restore. All fields are optional; zero values mean "no filter on this dimension". Size and time fields use pointers so that a zero value can be distinguished from "unset".

Support limitation in v1.13.1: only one exact Path and one Prefix can cross the current engine seam, even though CLI parsing may accept richer repeated path/prefix inputs before narrowing. Query-shape cleanup belongs to v1.13.3.

type SnapshotRestoreRequest 

type SnapshotRestoreRequest struct {
	SnapshotID string
	// Paths scopes a partial restore; empty means restore all snapshot files.
	Paths []string
	// DestinationMode controls output location derivation.
	DestinationMode RestoreDestinationMode
	// Destination is the prefix or override target.
	Destination string
	// Overwrite permits overwriting existing files.
	Overwrite bool
	// Strict enforces strict metadata application.
	Strict bool
	// NoMetadata disables metadata application.
	NoMetadata bool
	// Query filters which snapshot files are restored.
	Query SnapshotQuery
}

SnapshotRestoreRequest is a candidate request for a future SnapshotRestore operation. Not part of the active v1.12 Engine interface.

Candidate-only in v1.13.1: request/result presence must not be mistaken for active engine ownership. Snapshot create/delete/restore remain CLI/domain owned until the explicit snapshot-mutation follow-up in v1.13.8.

Safety invariant: Restore must never write outside the intended destination.

type SnapshotRestoreResult 

type SnapshotRestoreResult struct {
	SnapshotID string
	Type       SnapshotType
	// RestoredFiles is the number of files restored (or that would be).
	RestoredFiles int
	// OutputRoot is the effective destination root.
	OutputRoot string
	Warnings   []OperationWarning
}

SnapshotRestoreResult is a candidate result for a future SnapshotRestore operation. Not part of the active v1.12 Engine interface.

type SnapshotShowRequest added in v1.12.0 

type SnapshotShowRequest struct {
	SnapshotID string
	// Query filters which files are returned.
	Query SnapshotQuery
}

SnapshotShowRequest is a candidate request for a future SnapshotShow (files) operation. Not part of the active v1.12 Engine interface.

type SnapshotShowResult added in v1.12.0 

type SnapshotShowResult struct {
	Snapshot SnapshotMeta
	Files    []SnapshotFile
	// MatchedFileCount is the number of files matching Query.
	MatchedFileCount int
	// TotalFileCount is the total number of files in the snapshot.
	TotalFileCount int
}

SnapshotShowResult is a candidate result for a future SnapshotShow operation. Not part of the active v1.12 Engine interface.

Support limitation in v1.13.1: this coherent result shape is still provisional and does not prove fully unified engine ownership. Metadata, listing, and counts still come from mixed seams; read-side cleanup belongs to v1.13.3.

type SnapshotStatsRequest added in v1.12.0 

type SnapshotStatsRequest struct {
	SnapshotID string
}

SnapshotStatsRequest is a candidate request for a future SnapshotStats operation. Not part of the active v1.12 Engine interface.

SnapshotID is optional; empty means aggregate stats across all snapshots.

type SnapshotStatsResult added in v1.12.0 

type SnapshotStatsResult struct {
	SnapshotCount     int
	SnapshotFileCount int
	TotalSizeBytes    int64
	// HasReuse indicates whether the reuse metrics below are meaningful.
	HasReuse bool
	Reused   int
	New      int
	// ReuseRatio is a percentage in [0,100].
	ReuseRatio float64
	// LineageStatus explains why HasReuse is false, when applicable.
	// Mirrors snapshot.SnapshotLineageStatus string values.
	// Empty when HasReuse is true or when SnapshotID is empty (aggregate call).
	LineageStatus string
	// ParentSnapshotID is the parent snapshot's ID when HasReuse is true.
	ParentSnapshotID string
}

SnapshotStatsResult is a candidate result for a future SnapshotStats operation. Not part of the active v1.12 Engine interface.

Reuse fields are populated only for a specific snapshot that has a parent.

type SnapshotType added in v1.12.0 

type SnapshotType string

SnapshotType distinguishes full and partial snapshots. 

const (
	// SnapshotTypeFull captures the whole current state.
	SnapshotTypeFull SnapshotType = "full"
	// SnapshotTypePartial captures a path-scoped subset.
	SnapshotTypePartial SnapshotType = "partial"
)

type StatsRequest 

type StatsRequest struct {
	// IncludeContainers requests container-level statistics in the result.
	IncludeContainers bool
	// Trace controls optional trace-event emission during stats collection.
	Trace observability.TraceOptions
}

StatsRequest carries parameters for the Stats operation.

type StatsResult 

type StatsResult struct {
	// Raw is the underlying observability result.
	Raw *observability.StatsResult
}

StatsResult carries the result of the Stats operation.

type StoreRequest 

type StoreRequest struct {
	// SourcePath is the file or folder to store.
	SourcePath string
	// Codec selects the storage codec (e.g. "plain", "aes-gcm"). Empty means
	// the repository default.
	Codec string
	// Recursive requests folder store semantics (store-folder).
	// Support limitation in v1.13.1: active Engine.Store callers must leave
	// this false; true returns ErrNotImplemented.
	Recursive bool
	// Workers is the parallelism for folder store; zero means the default.
	// Support limitation in v1.13.1: this is candidate-only until recursive
	// folder store is activated outside the current engine route.
	Workers int
	// Tags carries optional caller-supplied tags.
	Tags []string
}

StoreRequest is a candidate request for a future Store / store-folder operation. Not part of the active v1.12 Engine interface.

Support limitation in v1.13.1: the active Engine.Store path owns only single-file store. Recursive/folder semantics remain deferred, and Engine.Store returns ErrNotImplemented when Recursive is true. Full folder store cleanup remains outside engine scope in v2.x.

type StoreResult 

type StoreResult struct {
	// SourcePath echoes the stored source path.
	SourcePath string
	// StoredPath is the canonical stored path recorded in the catalog.
	StoredPath string
	// LogicalFileID identifies the stored logical file.
	LogicalFileID int64
	// PhysicalFileID identifies the underlying physical file when applicable.
	PhysicalFileID int64
	// FileHash is the content hash (e.g. SHA-256) of the stored file.
	FileHash string
	// AlreadyStored indicates the content was already present (dedup hit).
	AlreadyStored bool
	// BytesLogical is the logical (pre-transform) size in bytes.
	BytesLogical int64
	// BytesStored is the physical (post-transform) size in bytes.
	BytesStored int64
	// ChunksCreated and ChunksReused describe chunk-level dedup outcomes.
	ChunksCreated int
	ChunksReused  int
	// Warnings carries structured, non-fatal warnings.
	Warnings []OperationWarning
}

StoreResult is a candidate result for a future Store operation. Not part of the active v1.12 Engine interface.

type VerifyRequest 

type VerifyRequest struct {
	// Level is the verification level: "fast", "standard", "full", or "deep".
	// Defaults to "standard" if empty.
	Level string
	// Target is the verification target: "system" or "file".
	// Defaults to "system" if empty.
	Target string
	// FileID is the logical file ID to verify when Target is "file".
	FileID int
}

VerifyRequest carries parameters for the Verify operation.

type VerifyResult 

type VerifyResult struct{}

VerifyResult carries the result of the Verify operation. Verify is pass-or-fail; a nil error from Engine.Verify means the repository passed at the requested level. Non-nil errors preserve the underlying verify.VerifyFailure chain.

v1.13.1 intentionally keeps this result empty: it is a minimal success-only placeholder, not a stable rich verification payload. Error taxonomy cleanup belongs to v1.13.2, and deeper verification/invariant ownership work belongs to v1.13.5.

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.