engine

package
v1.13.13 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2026 License: Apache-2.0 Imports: 31 Imported by: 0

Documentation

Overview

Package engine defines the coldkeep engine boundary.

The package owns typed operation requests and results, request-level validation, and behavior-preserving orchestration between headless callers and lower domain adapters. Lower packages execute injected storage, catalog, verification, maintenance, and recovery details without owning the public operation boundary.

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

View Source 
const MaxFileQueryLimit int64 = 10000

Variables

This section is empty.

Functions

func IsCode added in v1.13.12 

func IsCode(err error, code ErrorCode) bool

IsCode reports whether err has the requested stable engine classification.

func IsUnsupported added in v1.13.2 

func IsUnsupported(err error) bool

IsUnsupported reports the stable typed unsupported classification.

func TranslateError added in v1.13.12 

func TranslateError(operation string, err error) error

TranslateError applies deterministic engine-wide classification while preserving the original error message and chain. Existing engine Errors are returned unchanged.

func TranslateErrorAs added in v1.13.12 

func TranslateErrorAs(operation string, code ErrorCode, err error) error

TranslateErrorAs applies a caller-selected semantic classification. Context cancellation and invariant errors still use their universal classifications.

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"
	// BatchItemPlanned indicates the item was validated/read-only planned.
	BatchItemPlanned BatchItemStatus = "planned"
	// BatchItemFailed indicates the item failed.
	BatchItemFailed BatchItemStatus = "failed"
	// BatchItemSkipped indicates the item was skipped (e.g. duplicate/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 active store
	// orchestration.
	StoreContext *storage.StorageContext
	// ChunkerDeprecationPolicy optionally rejects registered chunkers for new
	// repository defaults. Nil means no registered chunker is deprecated.
	ChunkerDeprecationPolicy func(chunk.Version) (bool, string)
}

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. Additional dependencies are supplied only when an active engine method needs them.

type ConfigurationKey added in v1.13.12 

type ConfigurationKey string
const (
	ConfigurationDefaultChunker   ConfigurationKey = "default-chunker"
	ConfigurationCompression      ConfigurationKey = "compression"
	ConfigurationCompressionLevel ConfigurationKey = "compression-level"
)

type CurrentFile added in v1.13.12 

type CurrentFile struct {
	ID        int64  `json:"id"`
	Name      string `json:"name"`
	FileHash  string `json:"file_hash"`
	SizeBytes int64  `json:"size_bytes"`
	CreatedAt string `json:"created_at"`
}

CurrentFile is a presentation-neutral completed current-state path. JSON tags preserve the established CLI projection when the CLI embeds it.

type DefaultEngine 

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

DefaultEngine is the canonical Engine implementation.

It preserves existing command behavior while routing supported operations through typed engine methods and lower domain packages.

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) Doctor added in v1.13.12 

func (e *DefaultEngine) Doctor(ctx context.Context, req DoctorRequest) (_ DoctorResult, outErr error)

func (*DefaultEngine) GarbageCollect added in v1.12.0 

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

func (*DefaultEngine) GetConfiguration added in v1.13.12 

func (e *DefaultEngine) GetConfiguration(ctx context.Context, req GetConfigurationRequest) (_ GetConfigurationResult, outErr error)

func (*DefaultEngine) Inspect 

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

func (*DefaultEngine) ListFiles added in v1.13.12 

func (e *DefaultEngine) ListFiles(ctx context.Context, req ListFilesRequest) (_ ListFilesResult, outErr error)

func (*DefaultEngine) PlanGarbageCollection added in v1.13.12 

func (e *DefaultEngine) PlanGarbageCollection(ctx context.Context, req GarbageCollectionPlanRequest) (_ GarbageCollectionPlanResult, outErr error)

func (*DefaultEngine) Recover added in v1.13.12 

func (e *DefaultEngine) Recover(ctx context.Context, _ RecoverRequest) (_ RecoverResult, outErr error)

Recover executes real corrective recovery. It intentionally has no dry-run mode: startup and explicit recovery share this exact operation.

func (*DefaultEngine) Remove added in v1.12.0 

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

func (*DefaultEngine) RemoveStoredPaths added in v1.13.8 

func (e *DefaultEngine) RemoveStoredPaths(ctx context.Context, req RemoveStoredPathsRequest) (_ RemoveStoredPathsResult, outErr error)

func (*DefaultEngine) Repair added in v1.13.12 

func (e *DefaultEngine) Repair(ctx context.Context, req RepairRequest) (_ RepairResult, outErr error)

func (*DefaultEngine) Restore added in v1.12.0 

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

func (*DefaultEngine) RestoreStoredPath added in v1.13.8 

func (e *DefaultEngine) RestoreStoredPath(ctx context.Context, req RestoreStoredPathRequest) (_ RestoreStoredPathResult, outErr error)

func (*DefaultEngine) SearchFiles added in v1.13.12 

func (e *DefaultEngine) SearchFiles(ctx context.Context, req SearchFilesRequest) (_ SearchFilesResult, outErr error)

func (*DefaultEngine) SetConfiguration added in v1.13.12 

func (e *DefaultEngine) SetConfiguration(ctx context.Context, req SetConfigurationRequest) (_ SetConfigurationResult, outErr error)

func (*DefaultEngine) SnapshotCreate added in v1.13.9 

func (e *DefaultEngine) SnapshotCreate(ctx context.Context, req SnapshotCreateRequest) (_ SnapshotCreateResult, outErr error)

func (*DefaultEngine) SnapshotDelete added in v1.13.9 

func (e *DefaultEngine) SnapshotDelete(ctx context.Context, req SnapshotDeleteRequest) (_ SnapshotDeleteResult, outErr error)

func (*DefaultEngine) SnapshotDiff added in v1.12.0 

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

func (*DefaultEngine) SnapshotList added in v1.12.0 

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

func (*DefaultEngine) SnapshotRestore added in v1.13.9 

func (e *DefaultEngine) SnapshotRestore(ctx context.Context, req SnapshotRestoreRequest) (_ SnapshotRestoreResult, outErr error)

func (*DefaultEngine) SnapshotShow added in v1.12.0 

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

func (*DefaultEngine) SnapshotStats added in v1.12.0 

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

func (*DefaultEngine) Stats 

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

func (*DefaultEngine) Store added in v1.12.0 

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

func (*DefaultEngine) StoreFolder added in v1.13.12 

func (e *DefaultEngine) StoreFolder(ctx context.Context, req StoreFolderRequest) (_ StoreFolderResult, outErr error)

func (*DefaultEngine) Verify 

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

type DoctorPhysicalAudit added in v1.13.12 

type DoctorPhysicalAudit struct {
	OrphanPhysicalFileRows    int64
	LogicalRefCountMismatches int64
	NegativeLogicalRefCounts  int64
}

DoctorPhysicalAudit is the neutral current-path integrity summary.

type DoctorRequest added in v1.13.12 

type DoctorRequest struct {
	VerifyLevel string
}

DoctorRequest selects the verification strength for the corrective health gate. Empty VerifyLevel means standard.

type DoctorResult added in v1.13.12 

type DoctorResult struct {
	Recovery       RecoverResult
	VerifyLevel    string
	SchemaVersion  int64
	RecoveryStatus string
	VerifyStatus   string
	SchemaStatus   string
	PhysicalAudit  DoctorPhysicalAudit
	SnapshotAudit  DoctorSnapshotAudit
	FailedStage    DoctorStage
}

DoctorResult is the presentation-neutral ordered recovery, schema, verification, and audit report. Status strings retain the stable CLI values.

type DoctorSnapshotAudit added in v1.13.12 

type DoctorSnapshotAudit struct {
	SnapshotFileRows               int64
	OrphanSnapshotPathRefs         int64
	DuplicateSnapshotPathPairs     int64
	SnapshotReferencedLogicalFiles int64
	SnapshotOnlyLogicalFiles       int64
	SharedLogicalFiles             int64
	OrphanSnapshotLogicalRefs      int64
	InvalidLifecycleStates         int64
	RetainedMissingChunkGraph      int64
}

DoctorSnapshotAudit is the neutral snapshot-retention integrity summary.

type DoctorStage added in v1.13.12 

type DoctorStage string

DoctorStage identifies one ordered Doctor stage. 

const (
	DoctorStageRecovery DoctorStage = "recovery"
	DoctorStageSchema   DoctorStage = "schema"
	DoctorStageVerify   DoctorStage = "verify"
	DoctorStageAudit    DoctorStage = "audit"
)

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)

	// SnapshotCreate creates a snapshot through the catalog-only snapshot domain.
	// Type is derived from request paths, omitted IDs are generated by the
	// engine, and the underlying mutation must remain atomic.
	SnapshotCreate(ctx context.Context, req SnapshotCreateRequest) (SnapshotCreateResult, error)

	// SnapshotDelete previews or executes a metadata-only snapshot deletion.
	// Preview is read-only and DB-only. Execute must be affected-row honest and
	// must not fabricate preview data.
	SnapshotDelete(ctx context.Context, req SnapshotDeleteRequest) (SnapshotDeleteResult, error)

	// SnapshotRestore restores snapshot-owned files through the engine boundary.
	// Destination mode and lexical root/path are explicit, repeated selectors are
	// preserved, restore may leave filesystem side effects before a later error,
	// and the engine must not perform GC or repair as part of restore.
	SnapshotRestore(ctx context.Context, req SnapshotRestoreRequest) (SnapshotRestoreResult, 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)

	// PlanGarbageCollection computes live-repository reachability and reclaim
	// impact without mutating database or storage state.
	PlanGarbageCollection(ctx context.Context, req GarbageCollectionPlanRequest) (GarbageCollectionPlanResult, error)

	// Store stores a file into the repository.
	// Safety invariant: Store must not create inconsistent catalog/storage state.
	// Active semantics are limited to single-file store.
	Store(ctx context.Context, req StoreRequest) (StoreResult, error)

	// StoreFolder recursively stores a directory with deterministic discovery,
	// bounded workers, aggregate results, and worker-writer finalization owned
	// below this engine boundary.
	StoreFolder(ctx context.Context, req StoreFolderRequest) (StoreFolderResult, error)

	// ListFiles returns completed current-state stored paths in path order.
	ListFiles(ctx context.Context, req ListFilesRequest) (ListFilesResult, error)

	// SearchFiles returns completed current-state paths matching typed filters.
	SearchFiles(ctx context.Context, req SearchFilesRequest) (SearchFilesResult, error)

	// GetConfiguration returns one validated repository write default.
	GetConfiguration(ctx context.Context, req GetConfigurationRequest) (GetConfigurationResult, error)

	// SetConfiguration validates and persists one repository write default.
	SetConfiguration(ctx context.Context, req SetConfigurationRequest) (SetConfigurationResult, error)

	// Repair validates, normalizes, deduplicates, and executes ordered catalog
	// integrity recomputations. Each target remains transactionally independent;
	// FailFast stops after the first execution failure.
	Repair(ctx context.Context, req RepairRequest) (RepairResult, error)
	// Recover executes the corrective repository recovery pass against the
	// injected database and configured container directory.
	Recover(ctx context.Context, req RecoverRequest) (RecoverResult, error)
	// Doctor executes recovery, schema validation, system verification, and
	// integrity audit in order, stopping on the first failed stage.
	Doctor(ctx context.Context, req DoctorRequest) (DoctorResult, error)

	// Remove removes logical files from the repository by logical file ID.
	// Safety invariant: Remove must never make valid data unrecoverable.
	// Method selection owns addressing semantics: this method is by-ID only.
	Remove(ctx context.Context, req RemoveRequest) (RemoveResult, error)

	// RemoveStoredPaths unlinks one or more current stored physical-path mappings.
	//
	// Method selection owns addressing semantics: this method is for current
	// physical_file.path mappings rather than logical file IDs.
	// Safety invariant: the operation must preserve logical-file identity,
	// file-chunk ownership, chunk live-reference counts, and payload storage.
	// Physical payload reclamation remains GC-owned.
	RemoveStoredPaths(ctx context.Context, req RemoveStoredPathsRequest) (RemoveStoredPathsResult, error)

	// Restore restores logical files by logical file ID.
	// Safety invariant: Restore must never write outside the intended destination.
	// Method selection owns addressing semantics: this method is by-ID only.
	Restore(ctx context.Context, req RestoreRequest) (RestoreResult, error)

	// RestoreStoredPath restores one current stored physical-path mapping.
	//
	// Method selection owns addressing semantics: this method restores exactly
	// one current physical_file.path mapping rather than a logical file ID.
	// Safety invariant: the operation must preserve logical identity,
	// physical mappings, snapshot state, and ref-count ownership. Storage may
	// temporarily pin chunks while reconstructing payloads.
	RestoreStoredPath(ctx context.Context, req RestoreStoredPathRequest) (RestoreStoredPathResult, 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.

type Error added in v1.13.12 

type Error struct {
	Code          ErrorCode
	Operation     string
	Message       string
	InvariantCode string
	// contains filtered or unexported fields
}

Error is the stable typed engine failure. Its exported state is deliberately string-only and backend-neutral; cause remains private but is available to errors.Is/errors.As through Unwrap.

func NewError added in v1.13.12 

func NewError(code ErrorCode, operation, message, invariantCode string, cause error) *Error

NewError creates one typed error without changing the supplied human message. Invalid or empty codes fail closed to operation_failed.

func (*Error) Error added in v1.13.12 

func (e *Error) Error() string

func (*Error) Unwrap added in v1.13.12 

func (e *Error) Unwrap() error

type ErrorCode added in v1.13.12 

type ErrorCode string

ErrorCode is the renderer- and backend-neutral classification of an engine operation failure. Human messages and public CLI exit behavior remain caller compatibility concerns. 

const (
	ErrorInvalidArgument    ErrorCode = "invalid_argument"
	ErrorNotFound           ErrorCode = "not_found"
	ErrorUnsupported        ErrorCode = "unsupported"
	ErrorInvariantViolation ErrorCode = "invariant_violation"
	ErrorVerificationFailed ErrorCode = "verification_failed"
	ErrorRecoveryFailed     ErrorCode = "recovery_failed"
	ErrorConflict           ErrorCode = "conflict"
	ErrorCancelled          ErrorCode = "cancelled"
	ErrorOperationFailed    ErrorCode = "operation_failed"
)

func CodeOf added in v1.13.12 

func CodeOf(err error) ErrorCode

CodeOf returns the typed or universally derivable classification. An empty result means the error has not crossed a typed engine boundary yet.

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 the active request contract for Engine.GarbageCollect.

Safety invariant: GC must never delete reachable data. Dry-run is supported on SQLite and PostgreSQL; live collection is supported on PostgreSQL only.

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 the active result contract for Engine.GarbageCollect.

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

type GarbageCollectionContainerImpact added in v1.13.12 

type GarbageCollectionContainerImpact struct {
	ContainerID        int64
	Filename           string
	TotalBytes         int64
	LiveBytesAfterGC   int64
	ReclaimableBytes   int64
	ReclaimableChunks  int64
	TotalChunks        int64
	FullyReclaimable   bool
	RequiresCompaction bool
}

GarbageCollectionContainerImpact is a presentation-neutral container plan.

type GarbageCollectionPlanRequest added in v1.13.12 

type GarbageCollectionPlanRequest struct {
	SnapshotIDsToOmit []string
	IncludeTrace      bool
}

GarbageCollectionPlanRequest describes a read-only live-repository GC plan.

type GarbageCollectionPlanResult added in v1.13.12 

type GarbageCollectionPlanResult struct {
	SnapshotIDsToOmit []string
	Summary           GarbageCollectionPlanSummary
	Containers        []GarbageCollectionContainerImpact
	Warnings          []OperationWarning
	Trace             []TraceEvent
}

GarbageCollectionPlanResult is the immutable read-only plan projection.

type GarbageCollectionPlanSummary added in v1.13.12 

type GarbageCollectionPlanSummary struct {
	TotalChunks                        int64
	ReachableChunks                    int64
	UnreachableChunks                  int64
	LogicallyReclaimableBytes          int64
	PhysicallyReclaimableBytes         int64
	FullyReclaimableContainers         int64
	PartiallyDeadContainers            int64
	PackedBlocksLive                   int64
	PackedBlocksDead                   int64
	PackedBytesLive                    int64
	PackedBytesReclaimable             int64
	RetainedDeadBytesDueToPackedBlocks int64
}

GarbageCollectionPlanSummary preserves exact GC planner counters.

type GetConfigurationRequest added in v1.13.12 

type GetConfigurationRequest struct {
	Key ConfigurationKey
}

type GetConfigurationResult added in v1.13.12 

type GetConfigurationResult struct {
	Key          ConfigurationKey
	Value        string
	IntegerValue *int64
}

type InspectEntity added in v1.13.12 

type InspectEntity string

InspectEntity identifies a supported inspection target without importing the observability implementation contract. 

const (
	InspectRepository   InspectEntity = "repository"
	InspectFile         InspectEntity = "file"
	InspectLogicalFile  InspectEntity = "logical_file"
	InspectPhysicalFile InspectEntity = "physical_file"
	InspectChunk        InspectEntity = "chunk"
	InspectContainer    InspectEntity = "container"
	InspectSnapshot     InspectEntity = "snapshot"
)

type InspectOptions added in v1.13.12 

type InspectOptions struct {
	Deep         bool
	Relations    bool
	Reverse      bool
	Limit        int
	IncludeTrace bool
}

type InspectRelation added in v1.13.12 

type InspectRelation struct {
	Type       string
	Direction  RelationDirection
	TargetType InspectEntity
	TargetID   string
	Metadata   map[string]Value
}

type InspectRequest 

type InspectRequest struct {
	Entity   InspectEntity
	EntityID string
	Options  InspectOptions
}

type InspectResult 

type InspectResult struct {
	GeneratedAtUTC time.Time
	Entity         InspectEntity
	EntityID       string
	Summary        map[string]Value
	Metadata       map[string]Value
	Relations      []InspectRelation
	Warnings       []OperationWarning
	Trace          []TraceEvent
}

type ListFilesRequest added in v1.13.12 

type ListFilesRequest struct {
	Limit  *int64
	Offset *int64
}

type ListFilesResult added in v1.13.12 

type ListFilesResult struct {
	Files []CurrentFile
}

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{}

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 or simulation. RecoverRequest deliberately has no unsupported dry-run/input/limit surface.

type RecoverResult 

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

RecoverResult is the neutral corrective recovery report.

type RelationDirection added in v1.13.12 

type RelationDirection string
const (
	RelationOutgoing RelationDirection = "outgoing"
	RelationIncoming RelationDirection = "incoming"
)

type RemoveItemResult added in v1.12.0 

type RemoveItemResult struct {
	// FileID is the removed logical file ID.
	FileID int64
	// LogicalFileRemoved reports whether the logical file row was removed.
	LogicalFileRemoved bool
	// RemovedChunkAssociations is the count of removed file_chunk associations.
	RemovedChunkAssociations int
	// 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 RemoveRequest 

type RemoveRequest struct {
	// FileIDs is the ordered set of logical file IDs to remove.
	FileIDs []int64
	// DryRun simulates without mutating.
	DryRun bool
	// FailFast stops a batch on the first failure.
	FailFast bool
}

RemoveRequest is the active by-ID remove request contract.

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
}

RemoveResult is the active by-ID remove batch result contract.

type RemoveStoredPathItemResult added in v1.13.8 

type RemoveStoredPathItemResult struct {
	// RawTarget is the exact caller-provided text before trimming.
	RawTarget string
	// StoredPath is the trimmed stored-path value used for lookup/mutation.
	StoredPath string
	// LogicalFileID is the logical file owning the current mapping.
	LogicalFileID int64
	// RemainingRefCount is the remaining current ref-count after a live unlink.
	RemainingRefCount int64
	// MappingRemoved reports whether one physical_file row was removed.
	MappingRemoved 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
}

RemoveStoredPathItemResult is the outcome of unlinking one stored-path target.

type RemoveStoredPathsRequest added in v1.13.8 

type RemoveStoredPathsRequest struct {
	// StoredPaths is the ordered set of raw stored-path targets.
	StoredPaths []string
	// DryRun simulates unlinking without mutating.
	DryRun bool
	// FailFast stops on the first executable target failure.
	FailFast bool
}

RemoveStoredPathsRequest is the active stored-path batch remove contract.

type RemoveStoredPathsResult added in v1.13.8 

type RemoveStoredPathsResult 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 []RemoveStoredPathItemResult
	// Summary aggregates the item outcomes.
	Summary BatchSummary
}

RemoveStoredPathsResult is the active stored-path batch remove result.

func PreflightRemoveStoredPaths added in v1.13.9 

func PreflightRemoveStoredPaths(req RemoveStoredPathsRequest) (RemoveStoredPathsResult, bool, error)

type RepairRequest 

type RepairRequest struct {
	Targets []string
	// FailFast stops a batch on the first failure.
	FailFast bool
}

RepairRequest is the active ordered repair contract. Targets contain raw caller values so validation, normalization, duplicate detection, and deterministic reporting remain engine-owned. Input-file ingestion remains a caller responsibility.

type RepairResult 

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

RepairResult is the complete aggregate result of the processed targets.

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 {
	RawTarget string
	Target    RepairTarget
	// ScannedRows and UpdatedRows are generic counters covering both
	// logical-file and chunk recomputations.
	ScannedRows int64
	UpdatedRows int64
	// OrphanRows captures orphan physical-file rows for ref-count repair.
	OrphanRows        int64
	Status            BatchItemStatus
	Message           string
	InvariantCode     string
	RecommendedAction 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 restored logical file ID.
	FileID int64
	// OriginalName is the persisted logical-file name used to derive the
	// destination. It lets adapters preserve the established batch projection
	// without querying storage metadata outside the engine boundary.
	OriginalName string
	// DestinationPath is the path the file was (or would be) written to.
	DestinationPath 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 RestoreRequest 

type RestoreRequest struct {
	// FileIDs is the ordered set of logical file IDs to restore.
	FileIDs []int64
	// DestinationRoot is the output root used to derive per-item destinations.
	DestinationRoot string

	// Overwrite permits overwriting existing files.
	Overwrite bool
	// DryRun simulates without writing.
	DryRun bool
	// FailFast stops a batch on the first failure.
	FailFast bool
}

RestoreRequest is the active by-ID restore request contract.

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

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 the active by-ID restore batch result contract.

type RestoreStoredPathRequest added in v1.13.8 

type RestoreStoredPathRequest struct {
	// StoredPath identifies exactly one persisted physical_file.path.
	StoredPath string
	// DestinationMode controls how the output location is derived.
	DestinationMode RestoreDestinationMode
	// DestinationRoot is used only by prefix mode.
	DestinationRoot string
	// DestinationPath is used only by override mode.
	DestinationPath string
	// Overwrite permits overwriting existing files.
	Overwrite bool
	// StrictMetadata enforces strict metadata application.
	StrictMetadata bool
	// NoMetadata disables metadata application.
	NoMetadata bool
}

RestoreStoredPathRequest is the active stored-path restore request contract.

It restores exactly one current persisted physical_file.path mapping using destination semantics that remain distinct from by-ID restore.

type RestoreStoredPathResult added in v1.13.8 

type RestoreStoredPathResult struct {
	// StoredPath is the trimmed stored path used for the catalog lookup.
	StoredPath string
	// FileID identifies the owning logical file.
	FileID int64
	// DestinationMode is the normalized destination mode that executed.
	DestinationMode RestoreDestinationMode
	// DestinationPath is the exact resolved output path.
	DestinationPath string
	// RestoredHash is the successful restored content hash.
	RestoredHash string
}

RestoreStoredPathResult is the active stored-path restore success contract.

It is a single-operation result shape; execution failures are returned as errors rather than embedded item status fields.

type SearchFilesRequest added in v1.13.12 

type SearchFilesRequest struct {
	NameContains []string
	MinSizeBytes []int64
	MaxSizeBytes []int64
	Limit        *int64
	Offset       *int64
}

SearchFilesRequest preserves repeated filters and their historical AND semantics without exposing raw CLI tokens to the engine or catalog.

type SearchFilesResult added in v1.13.12 

type SearchFilesResult struct {
	Files []CurrentFile
}

type SetConfigurationRequest added in v1.13.12 

type SetConfigurationRequest struct {
	Key   ConfigurationKey
	Value string
}

type SetConfigurationResult added in v1.13.12 

type SetConfigurationResult struct {
	Key          ConfigurationKey
	Value        string
	IntegerValue *int64
	Changed      bool
}

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 the frozen active v1.13.9 Engine snapshot-create request surface.

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
}

SnapshotCreateResult is the frozen active v1.13.9 Engine snapshot-create result surface.

type SnapshotDeleteMode added in v1.13.9 

type SnapshotDeleteMode string

SnapshotDeleteMode is the frozen v1.13.9 snapshot-delete mode enum. 

const (
	SnapshotDeleteModePreview SnapshotDeleteMode = "preview"
	SnapshotDeleteModeExecute SnapshotDeleteMode = "execute"
)

type SnapshotDeleteParent added in v1.13.9 

type SnapshotDeleteParent struct {
	ID    string
	State SnapshotDeleteParentState
}

SnapshotDeleteParent is the renderer-neutral parent-state surface frozen in v1.13.9 Phase 3.

type SnapshotDeleteParentState added in v1.13.9 

type SnapshotDeleteParentState string

SnapshotDeleteParentState distinguishes no parent, present parent, and recorded-but-missing parent in the frozen v1.13.9 delete contract. 

const (
	SnapshotDeleteParentNone    SnapshotDeleteParentState = "none"
	SnapshotDeleteParentPresent SnapshotDeleteParentState = "present"
	SnapshotDeleteParentMissing SnapshotDeleteParentState = "missing"
)

type SnapshotDeletePreviewResult added in v1.13.9 

type SnapshotDeletePreviewResult struct {
	Parent      SnapshotDeleteParent
	Children    []string
	TotalFiles  int64
	UniqueFiles int64
	SharedFiles int64
}

SnapshotDeletePreviewResult is the renderer-neutral delete-preview shape frozen in v1.13.9 Phase 3.

type SnapshotDeleteRequest 

type SnapshotDeleteRequest struct {
	SnapshotID string
	Mode       SnapshotDeleteMode
}

SnapshotDeleteRequest is the frozen v1.13.9 active request for Engine.SnapshotDelete.

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
	Mode       SnapshotDeleteMode
	Deleted    bool
	Preview    *SnapshotDeletePreviewResult
}

SnapshotDeleteResult is the frozen v1.13.9 active result for Engine.SnapshotDelete.

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
	BaseLogicalID   *int64
	TargetLogicalID *int64
}

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).
	// 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.
	Filter SnapshotDiffFilter
	// Query filters which entries are considered.
	Query SnapshotQuery
}

SnapshotDiffRequest is the active request contract for Engine.SnapshotDiff.

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 the complete result contract for Engine.SnapshotDiff.

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          *int64
	ModTime       *time.Time
}

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

type SnapshotGraph added in v1.13.12 

type SnapshotGraph struct {
	Nodes   []SnapshotGraphNode
	RootIDs []string
}

SnapshotGraph is ordered by created_at ascending, then snapshot ID.

type SnapshotGraphNode added in v1.13.12 

type SnapshotGraphNode struct {
	Snapshot    SnapshotMeta
	ParentState SnapshotParentState
	ChildIDs    []string
}

SnapshotGraphNode is one renderer-neutral lineage node.

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.
	// Rendering remains the caller's responsibility.
	Tree bool
}

SnapshotListRequest is the active request contract for Engine.SnapshotList.

type SnapshotListResult added in v1.12.0 

type SnapshotListResult struct {
	Snapshots []SnapshotMeta
	Count     int
	// TreeMode echoes whether tree data was requested.
	TreeMode bool
	// Graph is populated only when TreeMode is true. It contains metadata and
	// relationships, never rendered lines.
	Graph *SnapshotGraph
}

SnapshotListResult is the active result contract for Engine.SnapshotList.

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 SnapshotParentState added in v1.13.12 

type SnapshotParentState string

SnapshotParentState distinguishes a root, a resolved parent, and historical missing-parent metadata without inventing a relationship. 

const (
	SnapshotParentNone    SnapshotParentState = "none"
	SnapshotParentPresent SnapshotParentState = "present"
	SnapshotParentMissing SnapshotParentState = "missing"
)

type SnapshotQuery added in v1.12.0 

type SnapshotQuery struct {
	// Paths match exact normalized stored paths.
	Paths []string
	// Prefixes match normalized stored paths by directory prefix.
	Prefixes []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 and diff. 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".

type SnapshotRestoreDestination added in v1.13.9 

type SnapshotRestoreDestination struct {
	Mode SnapshotRestoreDestinationMode
	Path string
}

SnapshotRestoreDestination is the explicit snapshot-restore destination contract frozen in v1.13.9 Phase 4.

type SnapshotRestoreDestinationMode added in v1.13.9 

type SnapshotRestoreDestinationMode string

SnapshotRestoreDestinationMode is part of the frozen v1.13.9 active Engine.SnapshotRestore contract. It remains intentionally distinct from the stored-path RestoreDestinationMode contract. 

const (
	SnapshotRestoreDestinationOriginal SnapshotRestoreDestinationMode = "original"
	SnapshotRestoreDestinationPrefix   SnapshotRestoreDestinationMode = "prefix"
	SnapshotRestoreDestinationOverride SnapshotRestoreDestinationMode = "override"
)

type SnapshotRestoreMetadataMode added in v1.13.9 

type SnapshotRestoreMetadataMode string

SnapshotRestoreMetadataMode is the frozen snapshot-restore metadata policy contract. Zero value means best-effort metadata application. 

const (
	SnapshotRestoreMetadataBestEffort SnapshotRestoreMetadataMode = ""
	SnapshotRestoreMetadataStrict     SnapshotRestoreMetadataMode = "strict"
	SnapshotRestoreMetadataNone       SnapshotRestoreMetadataMode = "none"
)

type SnapshotRestoreRequest 

type SnapshotRestoreRequest struct {
	SnapshotID string
	// Paths scopes a partial restore; empty means restore all snapshot files.
	Paths []string
	// Selection applies query-style restore filters without narrowing repeated
	// exact paths or repeated prefixes to a single value.
	Selection SnapshotRestoreSelection
	// Destination is the explicit restore destination contract.
	Destination SnapshotRestoreDestination
	// Overwrite permits overwriting existing files.
	Overwrite bool
	// Metadata controls best-effort, strict, or disabled metadata behavior.
	Metadata SnapshotRestoreMetadataMode
}

SnapshotRestoreRequest is the frozen v1.13.9 active request for Engine.SnapshotRestore.

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

type SnapshotRestoreResult 

type SnapshotRestoreResult struct {
	SnapshotID          string
	DestinationMode     SnapshotRestoreDestinationMode
	RequestedPathsCount int
	RestoredFiles       int64
	OutputTarget        string
	OutputPaths         []string
	Warnings            []SnapshotRestoreWarning
}

SnapshotRestoreResult is the frozen v1.13.9 active result for Engine.SnapshotRestore.

type SnapshotRestoreSelection added in v1.13.9 

type SnapshotRestoreSelection struct {
	ExactPaths     []string
	Prefixes       []string
	Pattern        string
	Regex          string
	MinSize        *int64
	MaxSize        *int64
	ModifiedAfter  *time.Time
	ModifiedBefore *time.Time
}

SnapshotRestoreSelection is the frozen snapshot-restore selection contract. It intentionally differs from the active read-side SnapshotQuery: repeated exact paths and prefixes remain representable as slices, regex crosses the boundary as a string, and no Limit field exists here.

type SnapshotRestoreWarning added in v1.13.9 

type SnapshotRestoreWarning struct {
	Code      SnapshotRestoreWarningCode
	Path      string
	Operation string
	Detail    string
}

SnapshotRestoreWarning is the renderer-neutral structured restore warning shape frozen in v1.13.9 Phase 4.

type SnapshotRestoreWarningCode added in v1.13.9 

type SnapshotRestoreWarningCode string

SnapshotRestoreWarningCode is the stable machine-readable restore warning code surface frozen in v1.13.9 Phase 4. 

const (
	SnapshotRestoreWarningMetadata SnapshotRestoreWarningCode = "metadata_apply_failed"
)

type SnapshotShowRequest added in v1.12.0 

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

SnapshotShowRequest is the active request contract for Engine.SnapshotShow.

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 the active result contract for Engine.SnapshotShow.

type SnapshotStatsRequest added in v1.12.0 

type SnapshotStatsRequest struct {
	SnapshotID string
}

SnapshotStatsRequest is the active request contract for Engine.SnapshotStats.

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 the active result contract for Engine.SnapshotStats. 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 StatsBlockLayout added in v1.13.12 

type StatsBlockLayout struct {
	StorageBlocksCount        int64
	ChunkBlockRefsCount       int64
	AvgChunksPerBlock         float64
	AvgBlockPlaintextSize     float64
	AvgBlockStoredSize        float64
	LogicalBytes              int64
	CompressedBytes           int64
	StoredBytes               int64
	CompressionSizeRatio      float64
	CompressionFactor         float64
	PhysicalSizeRatio         float64
	PhysicalFactor            float64
	CompressedBlocks          int64
	UncompressedBlocks        int64
	CompressionCodecBreakdown map[string]int64
	AvgBlockFillRatio         float64
	LegacyBlockCount          int64
	PackedBlockCount          int64
	CodecDistribution         map[string]int64
}

type StatsChunks added in v1.13.12 

type StatsChunks struct {
	TotalChunks      int64
	CompletedChunks  int64
	CompletedBytes   int64
	CountsByVersion  map[string]int64
	BytesByVersion   map[string]int64
	ChunkerVersions  []StatsVersion
	TotalReferences  int64
	UniqueReferenced int64
}

type StatsContainerRecord added in v1.13.12 

type StatsContainerRecord struct {
	ID           int64
	Filename     string
	TotalBytes   int64
	LiveBytes    int64
	DeadBytes    int64
	Quarantine   bool
	LiveRatioPct float64
}

type StatsContainers added in v1.13.12 

type StatsContainers struct {
	TotalContainers       int64
	HealthyContainers     int64
	QuarantineContainers  int64
	TotalBytes            int64
	HealthyBytes          int64
	QuarantineBytes       int64
	LiveBlockBytes        int64
	DeadBlockBytes        int64
	FragmentationRatioPct float64
	Records               []StatsContainerRecord
}

type StatsEfficiency added in v1.13.12 

type StatsEfficiency struct {
	LogicalBytes         int64
	UniqueChunkBytes     int64
	ContainerBytes       int64
	DedupRatio           float64
	DedupRatioPercent    float64
	ContainerOverheadPct float64
	StorageOverheadPct   float64
}

type StatsGraph added in v1.13.12 

type StatsGraph struct {
	SnapshotReachableChunks int64
	SnapshotReachableBytes  int64
}

type StatsLogical added in v1.13.12 

type StatsLogical struct {
	TotalFiles             int64
	CompletedFiles         int64
	ProcessingFiles        int64
	AbortedFiles           int64
	TotalSizeBytes         int64
	CompletedSizeBytes     int64
	EstimatedDedupRatioPct float64
}

type StatsPhysical added in v1.13.12 

type StatsPhysical struct {
	TotalPhysicalFiles int64
}

type StatsRepository added in v1.13.12 

type StatsRepository struct {
	ActiveWriteChunker string
}

type StatsRequest 

type StatsRequest struct {
	IncludeContainers bool
	IncludeTrace      bool
}

StatsRequest carries parameters for the Stats operation.

type StatsResult 

type StatsResult struct {
	GeneratedAtUTC time.Time
	Repository     StatsRepository
	Logical        StatsLogical
	Physical       StatsPhysical
	Chunks         StatsChunks
	BlockLayout    StatsBlockLayout
	Containers     StatsContainers
	Efficiency     StatsEfficiency
	Snapshots      StatsSnapshots
	Retention      StatsRetention
	Graph          StatsGraph
	Warnings       []OperationWarning
	Trace          []TraceEvent
}

StatsResult is the complete neutral repository-statistics result.

type StatsRetention added in v1.13.12 

type StatsRetention struct {
	CurrentOnlyLogicalFiles        int64
	CurrentOnlyBytes               int64
	SnapshotReferencedLogicalFiles int64
	SnapshotReferencedBytes        int64
	SnapshotOnlyLogicalFiles       int64
	SnapshotOnlyBytes              int64
	SharedLogicalFiles             int64
	SharedBytes                    int64
}

type StatsSnapshots added in v1.13.12 

type StatsSnapshots struct {
	TotalSnapshots int64
}

type StatsVersion added in v1.13.12 

type StatsVersion struct {
	Version string
	Chunks  int64
	Bytes   int64
}

type StoreFolderRequest added in v1.13.12 

type StoreFolderRequest struct {
	SourcePath string
	Codec      string
	Workers    int
}

StoreFolderRequest is the recursive folder-store contract. Workers zero selects the established default; positive values request bounded file-level fan-out subject to writer capability.

type StoreFolderResult added in v1.13.12 

type StoreFolderResult struct {
	SourcePath   string
	FilesStored  int
	BytesLogical int64
	WorkersUsed  int
}

StoreFolderResult reports deterministic aggregate execution statistics. Partial statistics are returned with an error when work fails after some files have completed.

type StoreRequest 

type StoreRequest struct {
	// SourcePath is the file to store.
	SourcePath string
	// Codec selects the storage codec (e.g. "plain", "aes-gcm"). Empty means
	// the repository default.
	Codec string
}

StoreRequest is the active request contract for Engine.Store.

Store is intentionally single-file only. Folder traversal and aggregation use the distinct StoreFolder operation.

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
	// 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
}

StoreResult is the active result contract for Engine.Store.

type TraceEvent added in v1.13.12 

type TraceEvent struct {
	Step     string
	Entity   string
	EntityID string
	Message  string
	Metadata map[string]Value
}

TraceEvent is a sanitized, ordered diagnostic event returned by an engine operation. Callers decide whether and how to render it.

type Value added in v1.13.12 

type Value struct {
	Kind    ValueKind
	Boolean bool
	String  string
	Integer string
	Decimal string
	Object  map[string]Value
	Array   []Value
}

Value is a recursive, renderer-neutral representation for dynamic inspect and trace metadata. Integer and decimal text preserve exact numeric tokens across the engine boundary.

type ValueKind added in v1.13.12 

type ValueKind string

ValueKind identifies the exact neutral representation stored in Value. 

const (
	ValueNull    ValueKind = "null"
	ValueBoolean ValueKind = "boolean"
	ValueString  ValueKind = "string"
	ValueInteger ValueKind = "integer"
	ValueDecimal ValueKind = "decimal"
	ValueObject  ValueKind = "object"
	ValueArray   ValueKind = "array"
)

type VerifyRequest 

type VerifyRequest struct {
	Level  string
	Target string
	FileID int
}

VerifyRequest carries parameters for the Verify operation.

type VerifyResult 

type VerifyResult struct {
	BlocksChecked           int64
	PhysicalHashChecked     int64
	CompressedHashChecked   int64
	LogicalHashChecked      int64
	CompressedBlocksChecked int64
}

VerifyResult includes the complete stable summary required by the existing CLI after successful verification.

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.