reconcile

type DuckStatsReader struct {
	DB     *sql.DB
	Bucket string
}

type GCStateStore interface {
	Load(ctx context.Context, schemaID int16) (map[string]int64, string, error)
	Save(ctx context.Context, schemaID int16, state map[string]int64, etag string) (string, error)
}

type LiveRowChecker interface {
	MissingLiveRows(ctx context.Context, schemaID int16, rowIDs []string) ([]string, error)
	LiveRowCount(ctx context.Context, schemaID int16) (int64, error)
}

type Locker interface {
	TryLock(ctx context.Context, schemaID int16) (locked bool, unlock func(), err error)
}

type ManifestGCStateStore struct {
	Store    manifest.Store
	Resolver manifest.PathResolver
}

type ManifestStore interface {
	Load(ctx context.Context, schemaID int16) (*manifest.Manifest, string, error)
	Save(ctx context.Context, schemaID int16, m *manifest.Manifest, etag string) (string, error)
}

type ObjectDeleter interface {
	DeleteObject(ctx context.Context, key string) error
}

type ObjectInfo struct {
	Key          string
	Size         int64
	LastModified time.Time
}

type ObjectLister interface {
	ListObjects(ctx context.Context, prefix string) ([]ObjectInfo, error)
}

type ObjectReader interface {
	GetObject(ctx context.Context, params *s3.GetObjectInput, optFns ...func(*s3.Options)) (*s3.GetObjectOutput, error)
}

type Options struct {
	Repair  bool          // append delta-shaped orphans back to the manifest
	GC      bool          // delete base-shaped and _tmp orphans past the grace period
	GCGrace time.Duration // minimum object age before GC may delete it
	// VerifyStamps compares every listed entry's #256 column stamp against
	// the object footer; divergence is the byte-truth breach the read-path
	// stamp short-circuit cannot see.
	VerifyStamps bool
	// VerifyChecksums re-hashes every stamped entry's object and compares the
	// digest with its #347 content stamp — the byte-integrity layer under
	// VerifyStamps' shape check, and the only offline detector of silent
	// parquet mis-decode corruption. One full GET per stamped entry.
	VerifyChecksums bool
	MaxETagRetries  int // manifest save retries on optimistic-concurrency conflict
	// AllowEmptyManifestSchemas waives the #463 empty-manifest GC guard for
	// exactly these schemas. Schema-explicit by design: one mis-pointed
	// manifest template resolves EVERY schema's manifest empty, so a global
	// override would wave the whole fleet through the very failure the
	// guard exists to stop.
	AllowEmptyManifestSchemas []int16
}

type OrphanClass int

type PGAdvisoryLocker struct {
	DB *sql.DB
}

type PGLiveRows struct {
	DB    *sql.DB
	Table string // entity_main table name
}

type Reconciler struct {
	Lister     ObjectLister
	Deleter    ObjectDeleter
	Manifests  ManifestStore
	Objects    ObjectReader   // required by Opts.VerifyChecksums; nil also leaves repaired and promoted entries unstamped
	Stats      StatsReader    // may be nil unless Opts.Repair or Opts.VerifyStamps
	LiveRows   LiveRowChecker // may be nil unless Opts.Repair
	Locker     Locker
	Schemas    SchemaEnumerator
	GCStates   GCStateStore // may be nil unless Opts.GC
	Now        func() time.Time
	Bucket     string
	DataPrefix string
	Logger     *zap.Logger
	Opts       Options
}

type RegistrySchemaEnumerator struct {
	DB             *sql.DB
	Table          string
	SchemaIDFilter int // 0 = all schemas
}

type Report struct {
	Schemas []SchemaReport
}

type ResolverManifestStore struct {
	Store    manifest.Store
	Resolver manifest.PathResolver
}

type S3ObjectStore struct {
	Client s3ObjectAPI
	Bucket string
}

type SchemaEnumerator interface {
	SchemaIDs(ctx context.Context) ([]int16, error)
}

type SchemaReport struct {
	SchemaID     int16
	Skipped      bool // advisory lock not acquired; nothing inspected
	DeltaOrphans []string
	BaseOrphans  []string
	TmpOrphans   []string
	Unknown      []string // unrecognized shapes; reported, never repaired or deleted
	Dangling     []string // manifest entries with no live object; removal stays manual
	Unverifiable []string // manifest paths this listing cannot prove absent
	// ObjectsSeen counts this schema's classified parquet objects in
	// storage; ManifestEntries counts its manifest's file entries as
	// loaded (#463). Together they distinguish "the manifest genuinely
	// lists nothing" from "the manifest failed to resolve" — N objects
	// against 0 entries is the mis-pointed-template signature --gc refuses.
	ObjectsSeen     int
	ManifestEntries int
	Repaired        []string // delta orphans appended to the manifest (--repair)
	// DeltaLeftovers are delta orphans the repair guard classified as
	// compaction leftovers (no uncovered rows, or every uncovered row
	// deleted in Postgres): never appended, GC-eligible under --gc.
	DeltaLeftovers []string
	Deleted        []string // leftover/merged-base/tmp orphans removed (--gc)
	// PromotedBase are init-shaped base orphans promoted into the manifest
	// base tier after the coverage + eviction-safety proof (--repair, #292).
	PromotedBase []string
	// InitPromotionRefusal explains why an init-shaped orphan set was NOT
	// promoted. Promotion is all-or-nothing over the set, so one reason
	// covers every file; empty when promotion succeeded or never ran. The
	// refused files stay ordinary GC candidates.
	InitPromotionRefusal string
	// StampDivergences are listed entries whose stamp no longer matches the
	// object footer (--verify-stamps); each is a byte-truth breach requiring
	// operator action — restamp via rewrite, or investigate the overwrite.
	StampDivergences []string
	// ChecksumDivergences are listed entries whose object bytes no longer hash
	// to the entry's #347 content stamp (--verify-checksums): silent
	// corruption, actionable exactly like a stamp divergence.
	ChecksumDivergences []string
	// SkippedUnstamped counts entries --verify-checksums could not cover
	// because they carry no checksum — either legacy (never backfilled) or a
	// best-effort write-side hash that failed. It is coverage observability,
	// not a discrepancy: it never affects the exit code, but a "clean"
	// verdict over mostly-unstamped entries means far less than a clean
	// verdict over stamped ones.
	SkippedUnstamped int
	Err              error // per-schema failure; other schemas still reconcile
}

type StatsReader interface {
	FileStats(ctx context.Context, key string) (compaction.MergeStats, error)
	UncoveredRows(ctx context.Context, key string, listedKeys []string) ([]compaction.UncoveredRow, error)
	FileColumns(ctx context.Context, key string) (map[string]string, error)
}