hostupgrade

type Host interface {
	// StopNode stops the node so its compute drains. UNBOUNDED: a drain waits for
	// the work already running for as long as it runs, and no elapsed time here
	// may end a job.
	StopNode(ctx context.Context) error

	// StopServer stops the control plane, after custody has settled.
	StopServer(ctx context.Context) error

	// PreserveCurrent copies the installed binary, units and configuration into
	// the recovery directory, so a rollback restores what was actually there
	// rather than what a package would reinstall.
	PreserveCurrent(ctx context.Context, dir string) error

	// HideBinary removes the installed executable so a concurrent operator
	// cannot enter through either version while the swap is underway.
	HideBinary(ctx context.Context) error

	// PrepareImages puts a guest generation the candidate's contract accepts in
	// the cluster for every image this host's microVM tiers boot, or does nothing
	// on a host that boots none. A host whose new binary refuses every image it
	// holds launches nothing until somebody pulls, which is not an upgraded host.
	PrepareImages(ctx context.Context) error

	// Fence makes already-open operator handles refuse transactions, and waits
	// for any transaction that began before it to finish.
	Fence(ctx context.Context, reason string) error

	// ClearFence reopens the ledger to ordinary callers.
	ClearFence(ctx context.Context, reason string) error

	// SnapshotLedger writes a complete, verified copy of the ledger.
	SnapshotLedger(ctx context.Context, dest string) error

	// RestoreLedger puts a snapshot back. Only ever called before the commit
	// record exists.
	RestoreLedger(ctx context.Context, from string) error

	// InstallCandidate puts the staged binary in place.
	InstallCandidate(ctx context.Context) error

	// RecordInstalled writes which release manifest produced the binary now in
	// place, bound to the bytes of that binary.
	//
	// WHAT A VERSION STRING CANNOT SAY. A node's registration names the version it
	// was BUILT as; two builds can share one and a moved tag makes them identical,
	// so a rollout comparing versions converges on evidence weaker than the
	// decision it is converging. This is the record that lets a host say which
	// bytes it is actually running.
	RecordInstalled(ctx context.Context, digest, version string) error

	// Migrate runs the candidate's migrations with it as the only ledger writer.
	Migrate(ctx context.Context) error

	// ProbeReady starts probe units that open what they inherited and announce
	// readiness, while polling nothing and accepting no workload.
	ProbeReady(ctx context.Context) error

	// StartServices installs the steady-state units and starts them.
	StartServices(ctx context.Context) error

	// RestorePreserved puts the preserved binary, units and configuration back.
	RestorePreserved(ctx context.Context, dir string) error

	// ProveStable reports whether the services stayed up long enough to believe.
	ProveStable(ctx context.Context) error
}

type Journal struct {
	// Dir is the unique recovery directory this upgrade owns.
	Dir string `json:"dir"`

	// FromVersion and ToVersion are what an operator reads when they find a
	// machine mid-upgrade.
	FromVersion string `json:"from_version"`
	ToVersion   string `json:"to_version"`

	// TargetDigest is the manifest this candidate came from, so a resuming run
	// can tell whether the staged bytes belong to the decision it is resuming.
	TargetDigest string `json:"target_digest"`

	// RolloutID and Generation tie this to the fleet decision that asked for it,
	// or are empty for an operator running it by hand.
	//
	// RECORDED RATHER THAN ENFORCED HERE, and the distinction matters. What stops a
	// delayed instruction from a superseded rollout starting a second transaction
	// on this machine is the CLAIM, which refuses while one is in progress at all —
	// the generation cannot do that job, because the two instructions may arrive
	// with nothing of the first left to compare against. What it does is answer
	// "which decision does this machine's half-finished upgrade belong to", for an
	// operator reading a journal and for a coordinator reconciling one.
	RolloutID  string `json:"rollout_id,omitempty"`
	Generation int64  `json:"generation,omitempty"`

	// SettlesThrough is the newest fleet decision that had completed when an
	// operator's own run began, so the host settles on it at the commit and a
	// timer does not move the host back to a rollout the person knew about.
	// Zero for a run that serves a rollout, whose own Generation is settled on.
	SettlesThrough int64 `json:"settles_through,omitempty"`

	// AllowDowngrade records that a person asked for a release older than the
	// one this ledger has been served by, and that the transaction may lower the
	// ledger's release watermark to admit it.
	//
	// ON THE JOURNAL BECAUSE A RESUME HAS TO KNOW. The mark is lowered inside the
	// migrate step, and a resumed run that had forgotten the permission would
	// have the candidate refused by a ledger this same transaction had already
	// snapshotted and was about to hand it.
	AllowDowngrade bool `json:"allow_downgrade,omitempty"`

	// Ledger says where this host's ledger lives: empty for the SQLite file in
	// the state directory, LedgerExternal for a database billet does not hold.
	//
	// ON THE JOURNAL BECAUSE IT DECIDES WHICH STEPS EXIST. An external ledger is
	// neither fenced, snapshotted nor migrated by the updater — billet copies no
	// PostgreSQL database, and the candidate migrates when it takes the
	// controller claim — and a resumed run has to skip the same steps the
	// interrupted one did, or it would try to restore a snapshot nothing took.
	Ledger string `json:"ledger,omitempty"`

	// PID is the process that claimed this transaction.
	//
	// A NAME FOR THE HOLDER, NOT A HANDLE ON IT. The transaction lock already says
	// whether somebody is working right now — the kernel drops it when the holder
	// dies — but it cannot say WHICH process, and an operator looking at a host
	// that has been draining for an hour needs something to look at. Nothing acts
	// on this: a pid is a number the kernel reuses, and killing an updater that may
	// already be installing is exactly what this command must not do.
	PID int `json:"pid,omitempty"`

	Step      Step   `json:"step"`
	StartedAt string `json:"started_at"`
	UpdatedAt string `json:"updated_at"`

	// Failure is why this upgrade stopped, when it did.
	Failure string `json:"failure,omitempty"`
}

type Request struct {
	Journal *Journal
	Host    Host
	Log     *slog.Logger
}

type Step string