operations

type AddDatabaseUserParams struct {
	InstanceName string
	DatabaseName string
	Username     string
	ReadOnly     bool
	Owner        bool // Make user the owner of the database
}

type AddDatabaseUserResult struct {
	Username string `json:"username"`
	Password string `json:"password"`
	Database string `json:"database"`
	ReadOnly bool   `json:"readOnly"`
	Message  string `json:"message"`
}

type ArchiveOrigin struct {
	Kind            string `json:"kind"`
	Path            string `json:"path"`
	DownloadedBytes int64  `json:"downloadedBytes,omitempty"`

	// CredentialSource says what authenticated an S3 fetch:
	// "offsite-settings", "request", or "instance-role". Empty for local kinds.
	CredentialSource string `json:"credentialSource,omitempty"`

	// ExpectedSHA256 is the digest the catalogue recorded when this host
	// wrote the archive, for an archive resolved THROUGH the catalogue (--id,
	// or an s3 URI that is a catalogue row's remote copy). The restore checks
	// the file against it before extracting, because a local copy is only
	// ever stat'd here and an intact file that was REPLACED would otherwise
	// restore as if it were the catalogued snapshot. Empty: nothing to check
	// (a --file / uncatalogued --s3-uri source, or a pre-022 row).
	ExpectedSHA256 string `json:"-"`
}

type BackupRDBMSParams struct {
	Name      string
	BackupDir string
	Comment   string // Optional comment for the backup
}

type BackupRDBMSResult struct {
	BackupID   int
	BackupPath string
	Size       int64
	Timestamp  time.Time
}

type ChecklistArchive struct {
	ID        int    `json:"id"`
	Timestamp string `json:"timestamp"`
	SizeBytes int64  `json:"sizeBytes"`
	Location  string `json:"location"` // "local", "s3", "local+s3"
	Comment   string `json:"comment,omitempty"`
}

type ChecklistBackupCron struct {
	UTCHour           int `json:"utcHour"`
	CleanupLocalDays  int `json:"cleanupLocalDays"`
	CleanupRemoteDays int `json:"cleanupRemoteDays"`
}

type ChecklistCoverage struct {
	State    string            `json:"state"`
	Snapshot *ChecklistArchive `json:"snapshot,omitempty"` // set for covered/config-only
}

type ChecklistHealth struct {
	Overall     string `json:"overall"` // "healthy", "degraded", "unhealthy", "checking", "unknown"
	CheckedAt   string `json:"checkedAt,omitempty"`
	HostHealthy bool   `json:"hostHealthy"`
	FailDetails string `json:"failDetails,omitempty"`
}

type ChecklistInstance struct {
	Name             string               `json:"name"`
	Version          string               `json:"version"`
	Status           string               `json:"status"`
	Health           string               `json:"health"` // "ok", "failing", "not-checked", "unknown"
	ParameterGroup   string               `json:"parameterGroup"`
	LegacyBackupCron *ChecklistBackupCron `json:"legacyBackupCron,omitempty"`
	SnapshotCoverage ChecklistCoverage    `json:"snapshotCoverage"`
}

type ChecklistNotificationConfig struct {
	Name string `json:"name"`
	Type string `json:"type"`
}

type ChecklistNotificationEvent struct {
	Name      string `json:"name"`
	Status    string `json:"status"` // "success" or "error"
	Detail    string `json:"detail,omitempty"`
	CreatedAt string `json:"createdAt"`
}

type ChecklistNotifications struct {
	Configured []ChecklistNotificationConfig `json:"configured"`
	LastEvent  *ChecklistNotificationEvent   `json:"lastEvent,omitempty"`
	LastError  *ChecklistNotificationEvent   `json:"lastError,omitempty"`
}

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

type ChecklistResult struct {
	GeneratedAt   string                 `json:"generatedAt"`
	Health        ChecklistHealth        `json:"health"`
	Instances     []ChecklistInstance    `json:"instances"`
	Snapshots     ChecklistSnapshots     `json:"snapshots"`
	Notifications ChecklistNotifications `json:"notifications"`
}

type ChecklistSnapCopy struct {
	LocalAndRemote int `json:"localAndRemote"`
	RemoteOnly     int `json:"remoteOnly"`
	LocalOnly      int `json:"localOnly"`
	None           int `json:"none"`
}

type ChecklistSnapshots struct {
	Scheduled     bool              `json:"scheduled"`
	UTCHour       int               `json:"utcHour,omitempty"`
	IntervalHours int               `json:"intervalHours,omitempty"`
	Format        string            `json:"format,omitempty"`
	LastSnapshot  *ChecklistArchive `json:"lastSnapshot,omitempty"`
	Total         int               `json:"total"`
	Copies        ChecklistSnapCopy `json:"copies"`

	// Stale is set when a schedule exists but the newest snapshot is older than
	// two intervals. Without it a schedule that has been failing for weeks reads
	// green: the newest COMPLETED snapshot is still shown, and a failed capture
	// writes no record at all, so there is nothing to make the gap visible.
	Stale       bool   `json:"stale"`
	StaleDetail string `json:"staleDetail,omitempty"`

	// Paused reports a schedule that exists but is suspended, which `snapshot
	// apply` does automatically so a restored host cannot write into the source
	// deployment's offsite bucket. It is a PROBLEM, not a neutral state: the
	// deployment is taking no snapshots, and the whole risk is that someone
	// restores a host and never resumes it. Scheduled stays true — the schedule
	// exists — so a reader must check both.
	Paused       bool   `json:"paused"`
	PausedSince  string `json:"pausedSince,omitempty"`
	PausedReason string `json:"pausedReason,omitempty"`

	// PausedBackupCrons counts suspended per-instance backup schedules, which
	// `snapshot apply` pauses for the same reason.
	PausedBackupCrons []string `json:"pausedBackupCrons,omitempty"`
}

type ConnectOptions struct {
	Database string
}

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

type ConsistencyStatus struct {
	ContainerExists  bool
	ContainerRunning bool
	PostgreSQLReady  bool
	OverallHealthy   bool
	Issues           []string
}

type CreateDatabaseParams struct {
	InstanceName string
	DatabaseName string
	// Username, when set, also creates the database's owner user in the
	// same operation — the right setup for a service that runs its own
	// migrations. If database creation fails, the just-created user is
	// rolled back (best-effort; a failed rollback is logged and reported).
	// Other access levels are deliberately not offered here — a read-only
	// user on a brand-new empty database has nothing to read; add those
	// with add-db-user once the database has content.
	Username string
}

type CreateDatabaseResult struct {
	DatabaseName string `json:"databaseName"`
	Username     string `json:"username,omitempty"`
	Password     string `json:"password,omitempty"`
	Message      string `json:"message"`
}

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

type CreateRDBMSParams struct {
	Name           string
	Version        string
	Image          string
	Port           int
	CPUCores       int
	RAMMB          int
	ParameterGroup string
}

type CreateRDBMSResult struct {
	Instance *instances.RDBMSInstance
	Password string // Plaintext password for initial response
}

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

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

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

type CronLogsParams struct {
	// Instance filters to one instance's runs. Empty returns every instance's,
	// including the whole-deployment snapshot runs recorded under
	// SnapshotCronInstance.
	Instance string
	Limit    int
}

type CronLogsResult struct {
	Logs []*cron.CronLog `json:"logs"`
}

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

type DatabaseInfo struct {
	Name      string    `json:"name"`
	Owner     string    `json:"owner"`
	Encoding  string    `json:"encoding"`
	Size      string    `json:"size"`
	CreatedAt time.Time `json:"createdAt,omitzero"`
}

type DatabaseMeta struct {
	Name           string   `json:"name"`
	Owner          string   `json:"owner"`
	Encoding       string   `json:"encoding"`
	Collate        string   `json:"collate"`
	Ctype          string   `json:"ctype"`
	LocProvider    string   `json:"locProvider"` // "c" (libc), "i" (icu), "b" (builtin); "c" assumed pre-PG15
	CreateGrantees []string `json:"createGrantees,omitempty"`
}

type DeleteDatabaseUserParams struct {
	InstanceName string
	Username     string
}

type DeleteDatabaseUserResult struct {
	Username string `json:"username"`
	Message  string `json:"message"`
}

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

type DeleteRDBMSParams struct {
	Name string
}

type Dependencies struct {
	Store     *store.Store
	Docker    *docker.Client
	MasterKey []byte
	// Archives writes and reads this host's archives, encrypted to the key
	// derived from MasterKey (ArchiveCompressor). Built once, with MasterKey.
	Archives  *compression.Compressor
	DataDir   string // Added for backup operations
	BackupDir string // Added for backup operations
	Logger    *log.Logger
}

type DownloadBackupParams struct {
	InstanceName string
	BackupID     int
}

type DownloadBackupResult struct {
	Message  string `json:"message"`
	Location string `json:"location"`
	Size     int64  `json:"size"`
}

type DownloadSnapshotResult struct {
	ID        int    `json:"id"`
	Filename  string `json:"filename"`
	Size      int64  `json:"size"`
	LocalPath string `json:"localPath"`
}

type DropAllBackupsResult struct {
	RecordsTotal               int      `json:"recordsTotal"`
	RecordsDropped             int      `json:"recordsDropped"`
	RecordsKept                int      `json:"recordsKept"`
	LocalFilesDeleted          int      `json:"localFilesDeleted"`
	LocalFilesMissing          int      `json:"localFilesMissing"`
	LocalBytesFreed            int64    `json:"localBytesFreed"`
	RemoteObjectsDeleted       int      `json:"remoteObjectsDeleted"`
	RemoteRefsDroppedNoOffsite int      `json:"remoteRefsDroppedNoOffsite"`
	Errors                     []string `json:"errors"`
	Message                    string   `json:"message"`
}

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

type FetchResult struct {
	Path   string
	Size   int64
	Reused bool
}

type GetLogsParams struct {
	InstanceName string
	Tail         string
}

type GetLogsResult struct {
	Logs string
}

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

type GetPasswordResult struct {
	Password string `json:"password"`
}

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

type InstanceMeta struct {
	Name           string `json:"name"`
	Version        string `json:"version"`
	Image          string `json:"image"`
	Port           int    `json:"port"`
	CPUCores       int    `json:"cpuCores"`
	RAMMB          int    `json:"ramMb"`
	ParameterGroup string `json:"parameterGroup"`

	// ParameterGroupDefinition inlines the group rather than only naming it:
	// the target host has no reason to have a group by that name, and
	// recreating the container needs the actual parameters. Nil when the group
	// could not be read at backup time (see captureInstanceMetadata).
	ParameterGroupDefinition *parameters.ParameterGroup `json:"parameterGroupDefinition,omitempty"`
}

type ListBackupsParams struct {
	InstanceName string
}

type ListBackupsResult struct {
	Backups []backup.BackupRecord
}

type ListDatabasesParams struct {
	InstanceName string
}

type ListDatabasesResult struct {
	Databases []DatabaseInfo `json:"databases"`
}

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

type MakeSnapshotParams struct {
	BackupDir string // where the snapshot archive is written
	Comment   string // free-text note stored with the catalogue record

	// Format is SnapshotFormatPhysical or SnapshotFormatLogical; empty means
	// physical (callers should have gone through NormalizeSnapshotFormat).
	Format string

	// SpreadCheckpoint selects pg_basebackup's spread checkpoint, which paces
	// the initial checkpoint over minutes instead of spiking I/O. Scheduled
	// runs set it; interactive runs use a fast checkpoint because an operator
	// is waiting.
	SpreadCheckpoint bool
}

type MakeSnapshotResult struct {
	ID                int                     `json:"id,omitempty"`
	Path              string                  `json:"path"`
	Size              int64                   `json:"size"`
	Timestamp         time.Time               `json:"timestamp"`
	Format            string                  `json:"format"`
	Instances         []SnapshotInstanceEntry `json:"instances"`
	InstancesWithData int                     `json:"instancesWithData"`
	ConfigOnly        int                     `json:"configOnly"`
	// SHA256 of the archive file, as recorded in the catalogue.
	SHA256 string `json:"sha256,omitempty"`

	// CaptureFailures is non-empty when the archive was written but is NOT a
	// complete capture of the deployment. Callers must treat that as a failed
	// run — see CaptureFailureError — while still keeping, shipping and
	// cataloguing the archive.
	CaptureFailures []SnapshotCaptureFailure `json:"captureFailures,omitempty"`
}

type NotificationAddParams struct {
	Name   string                         `json:"name"`
	Type   notifications.NotificationType `json:"type"`
	Config json.RawMessage                `json:"config"`
}

type NotificationAddResult struct {
	Notification *notifications.Notification `json:"notification"`
}

type NotificationEditParams struct {
	Name   string          `json:"name"`
	Type   string          `json:"type"`
	Config json.RawMessage `json:"config"`
}

type NotificationEditResult struct {
	Notification *notifications.Notification `json:"notification"`
}

type NotificationGetParams struct {
	Name string `json:"name"`
}

type NotificationGetResult struct {
	Notification *notifications.Notification `json:"notification"`
}

type NotificationListParams struct{}

type NotificationListResult struct {
	Notifications []notifications.Notification `json:"notifications"`
}

type NotificationLogsParams struct {
	Limit int `json:"limit"`
}

type NotificationLogsResult struct {
	Logs []notifications.NotificationLog `json:"logs"`
}

type NotificationRemoveParams struct {
	Name string `json:"name"`
}

type NotificationRemoveResult struct {
	Message string `json:"message"`
}

type NotificationTestParams struct{}

type NotificationTestResult struct {
	Message string `json:"message"`
}

type OffsiteApplyParams struct {
	ConfigJSON []byte
}

type OffsiteGetResult struct {
	Config offsite.OffsiteSettingsJSON `json:"config"`
}

type OffsiteInfoResult struct {
	Active bool                     `json:"active"`
	Config *offsite.OffsiteSettings `json:"config,omitempty"`
}

type OffsiteLogsParams struct {
	Limit int
}

type OffsiteTestResult struct {
	Success bool   `json:"success"`
	Message string `json:"message"`
	Error   string `json:"error,omitempty"`
}

type OpType int

type Operation interface {
	// Name returns a human-readable name for the operation
	Name() string

	Execute(ctx context.Context) error

	// Type returns whether this is a read or write operation
	Type() OpType
}

type ParameterGroupDeleteParams struct {
	Name string
}

type ParameterGroupDeleteResult struct {
	Message string `json:"message"`
}

type ParameterGroupGetParams struct {
	Name string
}

type ParameterGroupGetResult struct {
	GroupName  string                         `json:"groupName"`
	Parameters []parameters.ResolvedParameter `json:"parameters"`
}

type ParameterGroupInfo struct {
	Name       string                         `json:"name"`
	Parameters []parameters.ResolvedParameter `json:"parameters"`
}

type ParameterGroupListParams struct{}

type ParameterGroupListResult struct {
	Groups []ParameterGroupInfo `json:"groups"`
}

type ParameterGroupPutParams struct {
	Name       string
	Parameters []byte // JSON data
}

type ParameterGroupPutResult struct {
	Message string `json:"message"`
}

type PostgreSQLStatus int

type PreflightCheck struct {
	Label  string
	OK     bool
	Detail string
}

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

type PullImageParams struct {
	Version string
	Image   string
	// IfMissing pulls only when the image is not already present locally;
	// when present it is a no-op (no network). Used by create/switch to
	// auto-provision an image without forcing a re-pull of a cached one.
	// Standalone pull and update leave this false so a moving tag is refreshed.
	IfMissing bool
}

type PullImageResult struct {
	Version string
	Tags    []string
	Message string
}

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

type ReconfigureRDBMSParams struct {
	Name           string
	ParameterGroup string
	CPUCores       *int
	RAMMB          *int
	Port           *int
}

type ReconfigureRDBMSResult struct {
	Instance *instances.RDBMSInstance
}

type RemoteSnapshotObject struct {
	URI          string    `json:"uri"`
	Key          string    `json:"key"`
	Size         int64     `json:"size"`
	LastModified time.Time `json:"lastModified"`
}

type RemoteSnapshotSpec struct {
	URI      string // s3://bucket/key of a snapshot archive
	Region   string // "" = credential chain's region, then us-east-1
	Endpoint string // "" = AWS S3

	// Credentials is the CLIENT-resolved ambient triple, when the CLI's
	// environment had one. Nil means none were supplied. Never persisted,
	// never logged.
	Credentials *s3service.StaticCredentials

	// Profile selects a shared-config profile for the AMBIENT chain. Only
	// meaningful on daemon-less paths (apply, list-remote), where this process
	// resolves credentials itself.
	Profile string
}

type RemoveLocalBackupParams struct {
	InstanceName string
	BackupID     int
}

type RemoveLocalBackupResult struct {
	Message string `json:"message"`
}

type RemoveRemoteBackupParams struct {
	InstanceName string
	BackupID     int
}

type RemoveRemoteBackupResult struct {
	Message string `json:"message"`
}

type ResetDatabaseUserPasswordParams struct {
	InstanceName string
	Username     string
}

type ResetDatabaseUserPasswordResult struct {
	Username string `json:"username"`
	Password string `json:"password"`
	Message  string `json:"message"`
}

type RestoreArchiveSource struct {
	ArchivePath string              // a path on this host's filesystem
	SnapshotID  int                 // a row in this host's snapshot catalogue
	Remote      *RemoteSnapshotSpec // an s3:// object, possibly foreign

	// MasterKeyPath is a foreign archive's master key (--master-key), on the
	// daemon's filesystem. A Remote fetch is verified as it lands, which for
	// an encrypted archive needs its key.
	MasterKeyPath string
}

type RestoreClusterParams struct {
	InstanceName  string         // names the ephemeral helper containers
	Image         string         // image the helper containers run
	Major         int            // the cluster's PostgreSQL major (gates pgRestoreEnv)
	Port          int            // cluster port on the bridge gateway
	Password      string         // postgres superuser password (plaintext)
	CPUCores      int            // caps pg_restore -j
	ExtractedDir  string         // root of the extracted backup archive
	Databases     []DatabaseMeta // per-database metadata from databases.json
	ExpectedRoles []string       // roles globals.sql must create
}

type RestoreDatabaseParams struct {
	ArchivePath  string
	InstanceName string // the target instance: the live one the database is created on

	// SourceInstance is the snapshot entry the database is read from. Empty
	// means InstanceName — restoring an instance's own database. Naming
	// another lets prod's database from last night land on staging.
	SourceInstance string
	DatabaseName   string // the database inside the snapshot
	RestoreAs      string // optional: the name to create it under

	// MasterKeyPath is the SOURCE host's master.key. Only a physical entry
	// needs a key at all (to open the scratch copy of the cluster, whose roles
	// are the source's), and only when the snapshot came from elsewhere.
	MasterKeyPath string

	BackupDir string
	Progress  io.Writer

	// ExpectedSHA256 is the catalogue's digest for the archive, when it was
	// resolved through the catalogue (see ArchiveOrigin.ExpectedSHA256).
	ExpectedSHA256 string
}

type RestoreDatabaseResult struct {
	Instance       string    `json:"instance"`
	SourceInstance string    `json:"sourceInstance"`
	SourceDatabase string    `json:"sourceDatabase"`
	TargetDatabase string    `json:"targetDatabase"`
	Format         string    `json:"format"`
	SourceHost     string    `json:"sourceHost"`
	SnapshotAt     time.Time `json:"snapshotAt"`

	// SkippedGrantRoles are roles the source granted CREATE on the database
	// that do not exist on the target, so the grant could not be replayed.
	SkippedGrantRoles []string `json:"skippedGrantRoles,omitempty"`

	// Warnings are things the operator must know that did not fail the
	// restore — e.g. a scratch copy of the instance's data that could not be
	// removed.
	Warnings []string `json:"warnings,omitempty"`

	// ArchiveOrigin is set by the caller that resolved the archive source.
	ArchiveOrigin *ArchiveOrigin `json:"archiveOrigin,omitempty"`
}

type RestoreInstanceParams struct {
	ArchivePath  string
	InstanceName string

	// MasterKeyPath is the SOURCE host's master.key. Empty means "use this
	// host's own key", which is correct for the common case of restoring an
	// instance from a snapshot this same host took.
	MasterKeyPath string

	// ForeignSource marks an archive that did NOT come from this host's own
	// snapshot catalogue (an s3Uri fetch with no matching catalogue row). Such
	// a restore must never backdate created_at for checklist coverage — this
	// host's snapshots do not hold that data, so "not yet captured" is the
	// truthful verdict. MasterKeyPath already implies foreignness, but a
	// cloned-master-key fleet (or a deleted catalogue row) can be foreign
	// without needing a key, which is the hole this flag closes.
	ForeignSource bool

	BackupDir string

	// ExpectedSHA256 is the catalogue's digest for the archive, when it was
	// resolved through the catalogue (see ArchiveOrigin.ExpectedSHA256).
	ExpectedSHA256 string

	// Progress receives human-readable lines. Nil is fine (emitLine no-ops).
	Progress io.Writer
}

type RestoreInstanceResult struct {
	Instance   string    `json:"instance"`
	Created    bool      `json:"created"`
	Replaced   bool      `json:"replaced"`
	Databases  int       `json:"databases"`
	SourceHost string    `json:"sourceHost"`
	SnapshotAt time.Time `json:"snapshotAt"`
	Port       int       `json:"port"`
	CPUCores   int       `json:"cpuCores"`
	RAMMB      int       `json:"ramMb"`
	Image      string    `json:"image"`

	// PasswordChanged reports that the instance's stored postgres password was
	// replaced by the snapshot's. This is not optional and not a side effect to
	// hide: globals.sql sets the postgres role to the SOURCE's hash, so the only
	// plaintext that can still authenticate is the source's.
	PasswordChanged bool `json:"passwordChanged"`

	// Format is how the entry was captured ("physical" or "logical").
	Format string `json:"format"`

	// FinalStatus is the instance's status after the restore: "running", or
	// "stopped" for a physical cold capture — the instance was stopped when
	// the snapshot was taken, and the restore reproduces that (after starting
	// once to verify the cluster actually recovers).
	FinalStatus string `json:"finalStatus"`

	// ArchiveOrigin reports where the archive came from (a daemon-side path,
	// the catalogue, or an S3 fetch). Set by the caller that resolved the
	// source, not by RestoreInstanceFromSnapshot, which only ever sees a local
	// path.
	ArchiveOrigin *ArchiveOrigin `json:"archiveOrigin,omitempty"`
}

type RestoreRDBMSParams struct {
	// Either BackupID or FilePath must be provided (mutually exclusive)
	BackupID int    // ID from backup_history table
	FilePath string // Direct path to a .tar.zst.age (or pre-0.1.94 .tar.zst) file

	InstanceName string // Target instance to restore to
	DatabaseName string // Database name inside the backup to restore
	RestoreAs    string // Optional: restore under a different name
	BackupDir    string // Backup directory for resolving relative paths
}

type RestoreRDBMSResult struct {
	TargetDatabase string `json:"targetDatabase"`
	SourceBackup   string `json:"sourceBackup"`
	Message        string `json:"message"`
}

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

type SetPasswordResult struct {
	Success bool   `json:"success"`
	Message string `json:"message"`
}

type SnapshotApplyParams struct {
	ArchivePath   string
	MasterKeyPath string
	DataDir       string
	BackupDir     string
	DaemonPort    int
	Docker        *docker.Client

	// NoPauseSchedules skips the automatic pause of every restored schedule.
	//
	// The pause exists because the restored oddk.db carries the SOURCE host's
	// offsite settings alongside its schedules, so an unpaused restore uploads
	// into — and runs RETENTION against — a bucket the source may still be
	// using. Apply cannot tell a rehearsal from a real failover, so it fails
	// safe by default.
	//
	// This flag is the operator asserting the one fact apply cannot check: that
	// no other host is writing to that bucket. It is for the genuine
	// disaster-recovery case, where the source is gone and the replacement must
	// start protecting itself immediately rather than waiting for somebody to
	// notice a paused schedule. Set it when the source is dead; leave it alone
	// for a rehearsal or a staged migration.
	NoPauseSchedules bool

	// Progress receives human-readable status lines during preflight (nil
	// discards them).
	Progress io.Writer

	// PullProgress receives raw Docker pull frames, for a caller that wants to
	// render layer progress. nil discards them; an image pull on a DR host can
	// take minutes, so a CLI should supply one.
	PullProgress io.Writer
}

type SnapshotApplyPlan struct {
	Manifest     *SnapshotManifest
	ExtractedDir string
	MasterKey    []byte
	Instances    []*InstanceMeta
	Checks       []PreflightCheck

	// LogicalInputs holds, per logically captured instance, what its dumps
	// declare (databases.json, the roles in globals.sql). Read in preflight so
	// a truncated logical archive is refused before oddk.db and master.key are
	// replaced, and carried into the rebuild so it is read exactly once.
	LogicalInputs map[string]*logicalRestoreInputs

	// ExistingKeyPath is set when the target already has a master.key that
	// will be displaced (the normal case: the installer started the daemon,
	// which generated one).
	ExistingKeyPath string

	// PulledImages lists images preflight fetched onto this host. Recorded so
	// the summary can be honest that preflight was not purely read-only.
	PulledImages []string
	// contains filtered or unexported fields
}

type SnapshotApplyResult struct {
	Restored       []string // instances rebuilt with their data
	ConfigOnly     []string // instances whose snapshot held no data
	ReplacedKeyAs  string
	ReplacedDBAs   string
	TokensReplaced bool

	// Backup catalogue reconciliation. BackupsDangling counts records left with
	// neither a local nor a remote copy — the daemon's startup sweep will drop
	// those, so the operator is told rather than finding history gone.
	BackupsRepointed    int
	BackupsLocalCleared int
	BackupsDangling     int

	// Snapshot catalogue reconciliation, same shape and same reason: the
	// restored rows carry the source host's paths.
	SnapshotsRepointed    int
	SnapshotsLocalCleared int
	SnapshotsDangling     int

	// Schedules suspended by this apply. The restored oddk.db carries the SOURCE
	// host's schedule AND its offsite settings, so an unpaused restore starts
	// writing into — and running RETENTION against — a bucket the source may
	// still be using. SnapshotCronPaused is false when the archive carried no
	// snapshot schedule at all.
	SnapshotCronPaused bool
	BackupCronsPaused  int

	// SchedulesLeftRunning records that --no-pause-schedules suppressed the
	// pause, so the CLI can warn about the bucket collision the operator has
	// just taken responsibility for instead of the paused schedules they do not
	// have.
	SchedulesLeftRunning bool
}

type SnapshotCaptureFailure struct {
	Instance string `json:"instance"`
	Stage    string `json:"stage"` // "base backup", "cold copy", "dump", "decrypt password"
	Error    string `json:"error"`
}

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

type SnapshotInstanceEntry struct {
	Name    string `json:"name"`
	Version string `json:"version"`
	Image   string `json:"image"`

	// HasData is false for a configuration-only entry: the instance's
	// configuration was captured but its databases were not.
	HasData bool `json:"hasData"`

	// Format says how this entry's data was captured: "physical"
	// (pg_basebackup / cold copy under basebackup/) or "logical"
	// (globals.sql + databases/). Empty means logical — pre-0.1.61 archives
	// predate the field. Restore paths branch on this, never on a flag.
	Format string `json:"format,omitempty"`

	// CaptureMode distinguishes physical captures: "basebackup" was taken from
	// the live server, "cold" is a file copy of a stopped instance's data dir.
	// A cold entry is restored to a STOPPED instance — the deployment's shape
	// is reproduced, not just its bytes.
	CaptureMode string `json:"captureMode,omitempty"`

	// SkipReason explains a configuration-only entry, and is shown by apply so
	// the operator is never surprised by an instance coming back empty.
	SkipReason string `json:"skipReason,omitempty"`
}

type SnapshotManifest struct {
	FormatVersion int       `json:"formatVersion"`
	OddkVersion   string    `json:"oddkVersion"`
	CreatedAt     time.Time `json:"createdAt"`
	SourceHost    string    `json:"sourceHost"`

	// SourceArch is runtime.GOARCH on the capturing host. Physical data
	// directories are only supported on the same platform, so apply and
	// restore-instance refuse a physical entry on a different architecture
	// (logical archives restore anywhere; the field is informational there).
	// Empty in pre-0.1.61 archives, which are all logical anyway.
	SourceArch string `json:"sourceArch,omitempty"`

	// Migrations is the applied-migration list from the source's oddk.db. It
	// describes the embedded store's schema more precisely than OddkVersion.
	Migrations []string `json:"migrations"`

	Instances []SnapshotInstanceEntry `json:"instances"`
}

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

type SwitchRDBMSParams struct {
	Name    string
	Image   string
	Version string // empty = keep current instance version
}

type SwitchRDBMSResult struct {
	Instance *instances.RDBMSInstance
}

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

type UpdateRDBMSParams struct {
	Name  string
	Image string // empty = the instance's current image
}

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

type UpdateStateParams struct {
	Name  string
	State string // "start" or "stop"
}

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

type UpgradeRDBMSParams struct {
	Name          string
	TargetVersion string // target PostgreSQL major version, e.g. "18"
	Image         string // optional target image; required for custom (non-postgres:) images
}

type UpgradeRDBMSResult struct {
	Instance          *instances.RDBMSInstance `json:"instance"`
	FromVersion       string                   `json:"fromVersion"`
	ToVersion         string                   `json:"toVersion"`
	BackupID          int                      `json:"backupId"`
	DatabasesRestored int                      `json:"databasesRestored"`
}

type UploadBackupParams struct {
	InstanceName string
	BackupID     int
}

type UploadBackupResult struct {
	Message  string
	Location string
	Size     int64
}

type UploadSnapshotResult struct {
	ID             int    `json:"id"`
	Filename       string `json:"filename"`
	Size           int64  `json:"size"`
	RemoteLocation string `json:"remoteLocation"`
}