package release

import (
	"context"
	"crypto/ed25519"
	"encoding/json"
	"errors"
	"fmt"
	"io"
	"os"
	"path/filepath"
	"slices"
	"sort"
	"strings"
	"time"

	"github.com/carlosframework/platform/internal/controlname"
	"github.com/carlosframework/platform/internal/hostwrite"
	"github.com/carlosframework/platform/internal/registry"
	"github.com/carlosframework/platform/internal/safefile"
)

// ErrStageBlocked is MaterializeHeld reporting that this process cannot
// write the version store (StageBlocked: EROFS, EPERM or EACCES). The
// sandboxed agent gets it on every box, because carlos-edge.service writes
// only /data and /run/carlos; its caller relays the stage to the root pass
// (a held-stage request) instead of failing (moves design §7.3, T7).
var ErrStageBlocked = errors.New("release: this process cannot write the version store, so the root stage pass stages this release")

// ErrStaleHeldStage is a held-stage request its authority refused: the
// operation it names is no longer the one the host claim, the registry row
// or the source's report names, so the request is dropped and live/<host>
// is never repointed for it.
var ErrStaleHeldStage = errors.New("release: held stage request no longer matches its move")

// ErrHeldClaimWired is MaterializeHeld refusing while CARLOS_HOST_CLAIM is
// on: the live link would be written outside any claim selection. Plan 2
// adds the held-row selection under the landing op (ruling F10, applied
// here as it is to appconfig.RenderHeld).
var ErrHeldClaimWired = errors.New("release: held rows are not staged while CARLOS_HOST_CLAIM is on")

// ErrHeldNotProven is a held stage D3 refused (controller ruling D3-held):
// this box's proof policy lists the app (or does not load), and the pinned
// release has neither a verified proof for its bytes nor a place in this
// box's healthy history, or its staged bytes are not the proven ones.
// Returned before anything is published, so live/<host> is untouched.
var ErrHeldNotProven = errors.New("release: the held release is not proven for this box")

// ErrHeldNotAuthorized is a held stage of a build §4.1 does not authorize:
// no promotion record, and no verified pointer of the app names it (settings
// spec rev 11 §4.3a). The request is dropped, never retried, so it is
// returned only when every pointer of the app was read and judged.
var ErrHeldNotAuthorized = errors.New("release: the held release is not authorized: no promotion record and no signed pointer names it")

// HeldAuthorized is §4.1 for a move's held stage. want is the digest staging
// must bind: the record's, else a naming pointer entry's, preferring one that
// signs a digest ("" only when every admitted naming entry comes from a
// pointer whose channel carries no digests at all, today's pointer trust).
//
// Every pointer that verifies goes through the box's ratchet, whether or not
// it names the version: §4.6 remembers a channel from the moment the box has
// verified digests for it, so a digestless replay later is refused (ruling
// R15). That observation never changes this answer; only a naming pointer's
// ratchet outcome does.
//
// A pointer that is gone, fails verification, does not name the version, or
// that the box's ratchet refuses is not evidence and is skipped. So is a
// naming entry with no digest on a pointer whose channel carries digests: a
// legacy build is never a target once its channel has any digest (§4.6,
// ruling R16). A read that fails any other way, or a ratchet that cannot
// tell about a naming pointer (the mark could not be persisted or read), is
// returned as is: the answer is unknown, not no, so the root relay keeps the
// request for the next pass.
func HeldAuthorized(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, acct, app, version string) (string, error) {
	rec, err := ReadPromotionRecord(ctx, s, pub, acct, app, version)
	if err == nil {
		return rec.ManifestDigest, nil
	}
	if !errors.Is(err, ErrNoPromotionRecord) {
		return "", err
	}
	prefix := ChannelsPrefix(acct, app)
	keys, err := s.List(ctx, prefix)
	if err != nil {
		return "", err
	}
	named := false // some admitted pointer of a digestless channel names the version
	for _, k := range keys {
		name, ok := strings.CutSuffix(strings.TrimPrefix(k, prefix), ".json")
		if !ok || name == "" {
			continue
		}
		raw, _, err := GetQualified(ctx, s, ChannelKey(acct, app, name))
		if errors.Is(err, os.ErrNotExist) {
			continue // gone since the list
		}
		if err != nil {
			return "", fmt.Errorf("release: held stage of %s/%s at %s: reading channel %s: %w", acct, app, version, name, err)
		}
		p, err := verifyPointer(pub, raw, acct, app, name)
		if err != nil {
			continue // a pointer that does not verify is not evidence
		}
		// Observed first, so a verified pointer with digests marks its channel
		// whatever it names (§4.6 "once verified"). On a pointer that does not
		// name the version the outcome is dropped: a refusal or an unpersisted
		// mark there is no evidence either way, and the ratchet's in-memory
		// mark keeps that channel refusing digestless pointers regardless.
		rerr := r.Admit(acct, p)
		if p.Version != version && !slices.Contains(p.History, version) {
			continue
		}
		// The box's ratchet and CARLOS_REQUIRE_POINTER_DIGEST apply here as
		// they do to adoption (§4.6): a pointer the ratchet refuses is not
		// evidence. A nil ratchet would admit everything, so it is refused.
		if r == nil {
			return "", fmt.Errorf("%w: no pointer digest ratchet", ErrHeldNotAuthorized)
		}
		if rerr != nil {
			if errors.Is(rerr, ErrPointerWithoutDigests) && !errors.Is(rerr, errRatchetMarkUnreadable) {
				continue // the ratchet's verdict: this pointer is refused
			}
			return "", fmt.Errorf("release: held stage of %s/%s at %s: channel %s: %w", acct, app, version, name, rerr)
		}
		if d := p.DigestOf(version); d != "" {
			return d, nil
		}
		if p.ChannelHasDigests() {
			continue // a digestless entry on a digested channel is not evidence
		}
		named = true
	}
	if named {
		return "", nil
	}
	return "", fmt.Errorf("%w: %s/%s at %s", ErrHeldNotAuthorized, acct, app, version)
}

var (
	errHeldNoGuard     = errors.New("release: a held publication needs its authority")
	errHeldNoProofGate = errors.New("release: a held stage needs its proof gate")
)

// materializeHeldStage is MaterializeHeld's staging step, ensureStagedDigest
// bound to the digest HeldAuthorized returned (want "" is ensureStaged
// exactly), as a variable so a test can make it fail the way a read-only
// mount does.
var materializeHeldStage = func(ctx context.Context, s Store, optDir, acct, app, ver, host, want string) (*Manifest, error) {
	return ensureStagedDigest(ctx, s, optDir, acct, app, ver, host, want, stageCheck{})
}

// heldBeforeSwap runs inside the publication between bind and the link
// swap. A test seam: the window a replaced staged file lands in.
var heldBeforeSwap = func() {}

// heldAfterSwap runs inside the publication between the link swap and the
// second bind. A test seam: the window in which live/<host> names a version
// whose bytes are not yet vouched for, which the rollback may undo.
var heldAfterSwap = func() {}

// ErrHeldNotLive is VerifyHeldLive finding live/<host> on another version,
// or on none: the held release is not published on this box.
var ErrHeldNotLive = errors.New("release: live/<host> does not name the held release")

var errHeldNoLock = errors.New("release: a held reading needs the publication's lock")

// VerifyHeldLive is T7's reading of a published held release (final review
// finding 1). A link that names the version is no evidence by itself: the
// publication's rollback can undo it, and the bytes it names or the box's
// proof policy can change after it was written. So the reading passes only
// when, now:
//
//   - D3 admits the release under the policy in force (heldProofAdmit, the
//     publication's own admit, after BeginPass re-reads the policy), and
//   - under lock, live/<host> names version and bind accepts the bytes it
//     names (ProofGate.bindRecording, the publication's own check; no
//     refusal is recorded, since a reading changes nothing).
//
// lock must be the lock the publication's guard holds across the swap, the
// re-hash and the rollback (internal/host withHeldStageLock), so a reading
// never sees a link a failing publication is about to take back. A nil
// lock or gate is refused. A link on another version, or none, is
// ErrHeldNotLive; a refusal is ErrHeldNotProven.
//
// It writes nothing, so it does not consult CARLOS_HOST_CLAIM: under the
// claim it is the configured step's reading of the release it published
// under the held-release selection (moves Task 7, Paul's T7 ruling of
// 2026-10-12).
func VerifyHeldLive(ctx context.Context, s Store, optDir string, rt registry.Route, version string, proof *ProofGate, lock func(read func() error) error) error {
	if err := heldShape(rt, version); err != nil {
		return err
	}
	return verifyHeldLive(ctx, s, optDir, rt, version, proof, lock)
}

// VerifyHeldLiveUnder is VerifyHeldLive for a held row under the host
// claim (region HA Task 8c), as MaterializeHeldUnder is MaterializeHeld's:
// the same reading under the same lock, with heldShape in place of the
// CARLOS_HOST_CLAIM refusal. It writes nothing; the claim's selection
// authorized the publication it reads.
func VerifyHeldLiveUnder(ctx context.Context, s Store, optDir string, rt registry.Route, version string, proof *ProofGate, lock func(read func() error) error) error {
	if err := heldShape(rt, version); err != nil {
		return err
	}
	return verifyHeldLive(ctx, s, optDir, rt, version, proof, lock)
}

// verifyHeldLive is VerifyHeldLive and VerifyHeldLiveUnder after their
// shape checks.
func verifyHeldLive(ctx context.Context, s Store, optDir string, rt registry.Route, version string, proof *ProofGate, lock func(read func() error) error) error {
	if proof == nil {
		return errHeldNoProofGate
	}
	if lock == nil {
		return errHeldNoLock
	}
	// A peek, so a release not yet published is not admitted twice (the
	// stage that follows admits it). Only the reading under lock passes.
	if live, err := LiveVersion(optDir, rt.Host); err != nil {
		return err
	} else if live != version {
		return ErrHeldNotLive
	}
	proof.BeginPass()
	ptr, v, err := heldProofAdmit(ctx, s, optDir, rt, version, proof)
	if err != nil {
		return err
	}
	return lock(func() error {
		live, err := LiveVersion(optDir, rt.Host)
		if err != nil {
			return err
		}
		if live != version {
			return ErrHeldNotLive
		}
		if !proof.bindRecording(optDir, rt, ptr, v, live, proof.now(), func(Refusal) error { return nil }) {
			return fmt.Errorf("%w: %s at %s: the bytes live/%s names are not the proven ones", ErrHeldNotProven, rt.Host, version, rt.Host)
		}
		return nil
	})
}

// MaterializeHeld is StageHeld then PublishHeld: version of rt's app is
// staged, and live/<host> is pointed at it inside guard. A held row runs
// exactly the pinned release, so there is no channel resolution, no
// bake-hold check and no restart. When this process cannot write optDir it
// returns ErrStageBlocked wrapping the cause and has written nothing to
// live/<host>.
//
// proof is D3's gate, applied as adoption applies it (ProofGate.admit via
// heldProofAdmit, ProofGate.bind in publishHeld): admit before staging, so an unproven release is neither
// downloaded nor relayed to a root pass, and bind before publishing. A
// refusal is ErrHeldNotProven and live/<host> is untouched. A nil proof is
// refused, as a nil guard is.
//
// pub and r are §4.1's evidence for the stage (StageHeld): a build no
// signed promotion record and no ratchet-admitted pointer of the app
// authorizes is ErrHeldNotAuthorized, before anything is downloaded.
func MaterializeHeld(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, optDir string, rt registry.Route, version string, proof *ProofGate, guard func(publish func() error) error) (*Manifest, error) {
	return materializeHeldChecked(ctx, s, pub, r, optDir, rt, version, proof, guard)
}

func materializeHeldChecked(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, optDir string, rt registry.Route, version string, proof *ProofGate, guard func(publish func() error) error, pins ...PinSource) (*Manifest, error) {
	if err := heldStageable(rt, version); err != nil {
		return nil, err
	}
	return materializeHeld(ctx, s, pub, r, optDir, rt, version, proof, guard, pins...)
}

// MaterializeHeldUnder is MaterializeHeld for a held row under the host
// claim (moves Phase 1 Plan 3 Task 5, ruling H13). As adoption does under
// the claim, the version is staged outside the selection (the version store
// is shared, and a download must not hold the hostguard flock), and the
// host-specific publication, the bind, the live/<host> swap and its
// rollback, runs inside work under the identity naming exactly version (the
// held-release action's identity). guard, when not nil, runs inside work
// around the publication (the caller's held-stage lock). D3's admit and bind
// are MaterializeHeld's. A nil work is refused before anything is staged; it
// does not consult CARLOS_HOST_CLAIM, since the selection is the authority.
// A stage this process cannot write is ErrStageBlocked. Under the claim the
// sandboxed agent never calls this on a hardened box: it asks root, which
// calls it inside root's own held-release selection (moves Task 7b,
// internal/host movesheldrelease_root.go).
//
// pub and r are §4.1's evidence, as for MaterializeHeld: the stage
// (stageHeld) runs HeldAuthorized first and binds its digest, so a build no
// signed promotion record and no ratchet-admitted pointer of the app
// authorizes is ErrHeldNotAuthorized, before anything is downloaded. The
// claim's selection authorizes the write, not the build.
func MaterializeHeldUnder(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, optDir string, rt registry.Route, version string, proof *ProofGate, work hostwrite.Work, guard func(publish func() error) error) (*Manifest, error) {
	return MaterializeHeldUnderWithPins(ctx, s, pub, r, optDir, rt, version, proof, work, guard)
}

// MaterializeHeldUnderWithPins adds the root reservation check under the caller's
// release exclusion. Agent callers retain the original entry point.
func MaterializeHeldUnderWithPins(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, optDir string, rt registry.Route, version string, proof *ProofGate, work hostwrite.Work, guard func(publish func() error) error, pins ...PinSource) (*Manifest, error) {
	if err := heldShape(rt, version); err != nil {
		return nil, err
	}
	if work == nil {
		return nil, errHeldNoGuard
	}
	id := hostwrite.Identity{Release: version}
	return materializeHeld(ctx, s, pub, r, optDir, rt, version, proof, func(publish func() error) error {
		return work.With(ctx, id, func() error {
			if guard == nil {
				return publish()
			}
			return guard(publish)
		})
	}, pins...)
}

// materializeHeld is MaterializeHeld and MaterializeHeldUnder after their
// admissions: D3's admit, the authorized stage (stageHeld), then publication.
func materializeHeld(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, optDir string, rt registry.Route, version string, proof *ProofGate, guard func(publish func() error) error, pins ...PinSource) (*Manifest, error) {
	if guard == nil {
		return nil, errHeldNoGuard
	}
	if proof == nil {
		return nil, errHeldNoProofGate
	}
	proof.BeginPass()
	ptr, v, err := heldProofAdmit(ctx, s, optDir, rt, version, proof)
	if err != nil {
		return nil, err
	}
	m, err := stageHeld(ctx, s, pub, r, optDir, rt, version, pins...)
	if err != nil {
		return nil, err
	}
	if err := publishHeld(optDir, rt, version, proof, ptr, v, guard); err != nil {
		return nil, err
	}
	return m, nil
}

// StageHeldVerified is T7 under the host claim (moves design §7.3 and §9.2
// as amended on 2026-10-12, Paul's T7 ruling): the pinned version is staged
// into the shared version store and verified, and live/<host> is never
// touched. Its publication is the landing's, at configured, under the
// held-release selection (MaterializeHeldUnder). As adoption does under the
// claim, the stage runs outside any selection: the version store is shared
// and a stage is no host's write. So, like MaterializeHeldUnder, it does not
// consult CARLOS_HOST_CLAIM.
//
// Verified is everything MaterializeHeld checks short of the swap: D3's
// admit before anything is staged (heldProofAdmit), §4.1's authorization
// and the stage bound to its digest (stageHeld), then D3's bind on the
// staged bytes, which hashes the version's own file and so needs no link.
// A refusal of either D3 check is ErrHeldNotProven, and bind's is recorded
// in the move's held namespace as the publication records it; a build §4.1
// does not authorize is ErrHeldNotAuthorized, before anything is
// downloaded; a version store this process cannot write is ErrStageBlocked,
// which the agent answers by asking root to run this same stage (moves Task
// 7b, internal/host movesheldrelease_root.go). A nil proof is refused.
func StageHeldVerified(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, optDir string, rt registry.Route, version string, proof *ProofGate) (*Manifest, error) {
	return StageHeldVerifiedWithPins(ctx, s, pub, r, optDir, rt, version, proof)
}

// StageHeldVerifiedWithPins adds the root reservation check under the caller's
// release exclusion. Agent callers retain the original entry point.
func StageHeldVerifiedWithPins(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, optDir string, rt registry.Route, version string, proof *ProofGate, pins ...PinSource) (*Manifest, error) {
	if err := heldShape(rt, version); err != nil {
		return nil, err
	}
	if proof == nil {
		return nil, errHeldNoProofGate
	}
	proof.BeginPass()
	ptr, v, err := heldProofAdmit(ctx, s, optDir, rt, version, proof)
	if err != nil {
		return nil, err
	}
	m, err := stageHeld(ctx, s, pub, r, optDir, rt, version, pins...)
	if err != nil {
		return nil, err
	}
	cur, err := LiveVersion(optDir, rt.Host)
	if err != nil {
		return nil, err
	}
	if !proof.bindRecording(optDir, rt, ptr, v, cur, proof.now(), heldRefusalWriter(proof.bakeDir, rt.HoldOp)) {
		return nil, fmt.Errorf("%w: %s at %s: its staged bytes are not the proven ones", ErrHeldNotProven, rt.Host, version)
	}
	return m, nil
}

// stageHeld is every held stage's one staging step (StageHeld, and
// materializeHeld for MaterializeHeld and MaterializeHeldUnder): §4.1 first
// (HeldAuthorized, under pub and the box's ratchet r), then the stage bound
// to the digest it returned, whose manifest is checked before any artifact
// byte is written (ensureStagedDigest). Authorization lives here, below
// every entry point, so no held path stages a build it has not authorized.
func stageHeld(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, optDir string, rt registry.Route, version string, pins ...PinSource) (*Manifest, error) {
	if err := heldShape(rt, version); err != nil {
		return nil, err
	}
	want, err := HeldAuthorized(ctx, s, pub, r, RouteAccount(rt), rt.App, version)
	if err != nil {
		return nil, err
	}
	var m *Manifest
	if len(pins) == 0 {
		m, err = materializeHeldStage(ctx, s, optDir, RouteAccount(rt), rt.App, version, rt.Host, want)
	} else {
		check := stageCheck{beforeWrite: func(path string) error {
			for _, source := range pins {
				if err := (passConfig{generationPins: source}).generationWriteCheck(ctx, optDir, path); err != nil {
					return err
				}
			}
			return nil
		}}
		m, err = ensureStagedDigest(ctx, s, optDir, RouteAccount(rt), rt.App, version, rt.Host, want, check)
	}
	if err != nil {
		if StageBlocked(err) {
			return nil, fmt.Errorf("%w: %w", ErrStageBlocked, err)
		}
		return nil, err
	}
	return m, nil
}

// publishHeld is PublishHeld after admit. Everything runs inside guard,
// after the authority's re-check and under whatever it holds (for the root
// relay, the registry's holds frozen): bind hashes the staged bytes, the
// link is swapped, and bind runs again on the bytes the link now names. The
// guard's re-check reads the bucket and waits for the freeze, and the
// staged file can be replaced meanwhile or after the first hash, so only a
// hash taken after the swap vouches for what the link points at. When that
// second bind refuses, the link goes back to the version it named before
// (or away, when there was none) and the stage is ErrHeldNotProven.
//
// A binding refusal is recorded scoped to the move (rt.HoldOp, Refusal's
// MoveOp) in the held namespace (HeldRefusalBase), never in adoption's; a
// publication that succeeds retires its move's earlier refusal.
func publishHeld(optDir string, rt registry.Route, version string, proof *ProofGate, ptr *ChannelPointer, v proofVerdict, guard func(publish func() error) error) error {
	// The CARLOS_HOST_CLAIM refusal is the callers' (heldStageable): the
	// claim path reaches here only inside its selection.
	if err := heldShape(rt, version); err != nil {
		return err
	}
	if guard == nil {
		return errHeldNoGuard
	}
	record := heldRefusalWriter(proof.bakeDir, rt.HoldOp)
	notProven := fmt.Errorf("%w: %s at %s: its staged bytes are not the proven ones", ErrHeldNotProven, rt.Host, version)
	err := guard(func() error {
		cur, err := LiveVersion(optDir, rt.Host)
		if err != nil {
			return err
		}
		if !proof.bindRecording(optDir, rt, ptr, v, cur, proof.now(), record) {
			return notProven
		}
		heldBeforeSwap()
		if err := PointLive(optDir, rt.Host, RouteAccount(rt), version, rt.App); err != nil {
			if StageBlocked(err) {
				return fmt.Errorf("%w: %w", ErrStageBlocked, err)
			}
			return err
		}
		heldAfterSwap()
		if !proof.bindRecording(optDir, rt, ptr, v, cur, proof.now(), record) {
			if rerr := restoreLive(optDir, rt, cur); rerr != nil {
				return errors.Join(notProven, fmt.Errorf("putting live/%s back on %q: %w", rt.Host, cur, rerr))
			}
			return notProven
		}
		return nil
	})
	if err != nil {
		return err
	}
	if proof.bakeDir != "" {
		if err := RetireHeldRefusal(proof.bakeDir, rt.Host, rt.HoldOp); err != nil {
			fmt.Printf("  %s: retiring move %s's held refusal: %v\n", rt.Host, rt.HoldOp, err)
		}
	}
	return nil
}

// restoreLive puts live/<host> back on cur, or removes it when cur is "".
func restoreLive(optDir string, rt registry.Route, cur string) error {
	if cur == "" {
		if err := os.Remove(LiveLink(optDir, rt.Host)); err != nil && !errors.Is(err, os.ErrNotExist) {
			return err
		}
		return nil
	}
	return PointLive(optDir, rt.Host, RouteAccount(rt), cur, rt.App)
}

// Held refusals (final review finding 3) live in their own namespace,
// HeldRefusalBase(bakeDir)/refusals/<host>.json, the same record shape as
// adoption's refusals/<host>.json beside it, written and read with the same
// functions (WriteRefusal, ReadRefusal, ListRefusals, ClearRefusal) over the
// other base. Adoption never reads that directory and the held stage never
// writes, reads or removes adoption's, so neither can clobber or delete the
// other's record whatever the interleaving: adoption runs in the agent and
// in root, and nothing serialises the two across processes. Minting
// (internal/host proofroot.go) reads only adoption's records; status and
// alerts read both (internal/host refusalwatch.go).
//
// Within the namespace one host has one record, the latest held stage's.
// Retirement reads it and removes it only when it names the ended move; a
// newer move's record replacing it in between would be removed too. That
// race is between two moves of one host into one box, and costs a status
// row: a held refusal blocks nothing, and the next held stage of the live
// move writes it again.

// HeldRefusalBase is the bake directory the held namespace is rooted at:
// its records are at RefusalDir(HeldRefusalBase(bakeDir)).
func HeldRefusalBase(bakeDir string) string { return filepath.Join(bakeDir, "moves-held") }

// heldRefusalWriter is a held stage's refusal writer for bindRecording: the
// record carries the move's op and goes to the held namespace.
func heldRefusalWriter(bakeDir, op string) func(Refusal) error {
	return func(r Refusal) error {
		r.MoveOp = op
		return WriteRefusal(HeldRefusalBase(bakeDir), r)
	}
}

// RetireHeldRefusal removes host's held refusal when it is move op's, and
// leaves another move's. Adoption's records are never read or touched.
func RetireHeldRefusal(bakeDir, host, op string) error {
	if op == "" {
		return nil
	}
	base := HeldRefusalBase(bakeDir)
	r, err := ReadRefusal(base, host)
	if err != nil || r == nil || r.MoveOp != op {
		return err
	}
	heldRetireBeforeClear(host)
	return ClearRefusal(base, host)
}

// heldRetireBeforeClear runs between RetireHeldRefusal's read and its
// removal. A test seam: the window a concurrent writer lands in.
var heldRetireBeforeClear = func(host string) {}

// ListHeldRefusals is every held refusal record, sorted by host. With no
// held namespace yet it reads nothing.
func ListHeldRefusals(bakeDir string) ([]Refusal, error) {
	return ListRefusals(HeldRefusalBase(bakeDir))
}

// RetireHeldRefusals removes every held refusal whose move live says is
// over, and returns the hosts it removed. With no held namespace it reads
// nothing. Errors from individual removals are joined; the rest go ahead.
func RetireHeldRefusals(bakeDir string, live func(Refusal) bool) ([]string, error) {
	recs, err := ListHeldRefusals(bakeDir)
	if err != nil {
		return nil, err
	}
	var (
		retired []string
		errs    []error
	)
	for _, r := range recs {
		if r.MoveOp == "" || live(r) {
			continue
		}
		if err := RetireHeldRefusal(bakeDir, r.Host, r.MoveOp); err != nil {
			errs = append(errs, fmt.Errorf("%s: %w", r.Host, err))
			continue
		}
		retired = append(retired, r.Host)
	}
	return retired, errors.Join(errs...)
}

// heldProofAdmit is D3's cheap check (ProofGate.admit, unchanged) for a
// held stage. A held row runs a pinned release, not a channel head, so the
// pointer it is asked about carries only the version: admit and bind read
// nothing else from it but PromotedAt, which is zero here (the sha cache
// key, and a binding refusal's PointerPromotedAt, which no real pointer
// matches, so the record never blocks a later adoption).
//
// One difference from adoption, on the closed side: a policy that does not
// load refuses every held route. Adoption closes only named-unit routes
// then, but a held route is built from a move's record or a relayed
// request, whose unit binding this path cannot vouch for.
func heldProofAdmit(ctx context.Context, s Store, optDir string, rt registry.Route, version string, proof *ProofGate) (*ChannelPointer, proofVerdict, error) {
	ptr := &ChannelPointer{Version: version}
	if _, perr := proof.Requires(rt.App); perr {
		_, err := proof.state()
		fmt.Printf("  %s: held stage of %s: %v; not staged\n", rt.Host, version, err)
		return nil, proofVerdict{}, fmt.Errorf("%w: %s at %s: %v", ErrHeldNotProven, rt.Host, version, err)
	}
	cur, _ := LiveVersion(optDir, rt.Host)
	v, ok := proof.admit(ctx, s, optDir, rt, ptr, cur)
	if !ok {
		return nil, proofVerdict{}, fmt.Errorf("%w: %s at %s", ErrHeldNotProven, rt.Host, version)
	}
	return ptr, v, nil
}

// heldStageable is the admission StageHeld and PublishHeld share.
func heldStageable(rt registry.Route, version string) error {
	if hostwrite.Enabled(os.Getenv) {
		return ErrHeldClaimWired
	}
	return heldShape(rt, version)
}

// heldShape is heldStageable without the CARLOS_HOST_CLAIM refusal, for the
// claim path, which writes only inside its selection.
func heldShape(rt registry.Route, version string) error {
	if !controlname.ValidHostShape(rt.Host) || !ValidApp(rt.App) || !ValidVersion(version) {
		return fmt.Errorf("release: held stage of %q/%q at %q: malformed", rt.Host, rt.App, version)
	}
	if rt.HoldOp == "" {
		return fmt.Errorf("release: held stage of %q at %q names no move", rt.Host, version)
	}
	return nil
}

// HeldStageRequest is what the sandboxed agent leaves at
// HeldStageDir(dataDir)/<Host>.json when MaterializeHeld returned
// ErrStageBlocked: stage Version of Account/App for Host under move Op,
// whose target is Box.
type HeldStageRequest struct {
	Account string `json:"account"`
	App     string `json:"app"`
	Host    string `json:"host"`
	Version string `json:"version"`
	Op      string `json:"op"`
	Box     string `json:"box"`
}

// HeldStaged is what the root pass leaves at HeldStagedDir(dataDir)/<host>.json
// after serving a request. It is a hint only: T7 trusts VerifyHeldLive.
type HeldStaged struct {
	Version string    `json:"version"`
	Op      string    `json:"op"`
	At      time.Time `json:"at"`
}

// HeldStageDir is where held-stage requests wait for the root pass.
func HeldStageDir(dataDir string) string { return filepath.Join(dataDir, "moves", "held-stage") }

// HeldStagedDir is where the root pass acknowledges the requests it served.
func HeldStagedDir(dataDir string) string { return filepath.Join(dataDir, "moves", "held-staged") }

// heldStageRequestMax bounds a request file: the six fields fit many times
// over, and the directory is writable by every process that runs as the
// agent's uid, flat tenants included.
const heldStageRequestMax = 4096

// ServeHeldStageRequestsWithPins protects the old relay on census boxes, including
// after claims are disabled. The caller holds release exclusion through the pass.
func ServeHeldStageRequestsWithPins(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, optDir, dataDir string, proof *ProofGate, authorize func(req HeldStageRequest, then func() error) error, pins ...PinSource) error {
	reqDir := HeldStageDir(dataDir)
	dir, err := safefile.OpenDir(reqDir)
	if errors.Is(err, os.ErrNotExist) {
		return nil
	}
	if err != nil {
		return err
	}
	defer dir.Close()
	ents, err := dir.ReadDir(-1)
	if err != nil {
		return err
	}
	sort.Slice(ents, func(i, j int) bool { return ents[i].Name() < ents[j].Name() })
	for _, e := range ents {
		name := e.Name()
		if strings.HasPrefix(name, ".") || !strings.HasSuffix(name, ".json") {
			continue // a writer's temp file, or not a request
		}
		if err := serveHeldStageRequest(ctx, s, pub, r, optDir, dataDir, reqDir, name, proof, authorize, pins...); err != nil {
			return err
		}
	}
	return nil
}

// serveHeldStageRequest serves one request file. It returns an error only
// when this build cannot do the work at all.
func serveHeldStageRequest(ctx context.Context, s Store, pub ed25519.PublicKey, r *DigestRatchet, optDir, dataDir, reqDir, name string, proof *ProofGate, authorize func(HeldStageRequest, func() error) error, pins ...PinSource) error {
	drop := func(format string, args ...any) error {
		fmt.Printf("  held stage request %q: "+format+"; removed\n", append([]any{name}, args...)...)
		if err := safefile.Remove(filepath.Join(reqDir, name)); err != nil {
			if errors.Is(err, errors.ErrUnsupported) {
				return err
			}
			fmt.Printf("  held stage request %q: remove: %v\n", name, err)
		}
		return nil
	}
	f, err := safefile.OpenFile(filepath.Join(reqDir, name), os.O_RDONLY, 0)
	if err != nil {
		if errors.Is(err, errors.ErrUnsupported) {
			return err
		}
		return drop("unreadable: %v", err)
	}
	body, err := io.ReadAll(io.LimitReader(f, heldStageRequestMax+1))
	closeErr := f.Close()
	if err != nil {
		return drop("unreadable: %v", err)
	}
	if closeErr != nil {
		return drop("unreadable: %v", closeErr)
	}
	if len(body) > heldStageRequestMax {
		return drop("unreadable: request exceeds %d bytes", heldStageRequestMax)
	}
	var req HeldStageRequest
	if err := json.Unmarshal(body, &req); err != nil {
		return drop("not a request")
	}
	if why := heldStageRequestInvalid(req, strings.TrimSuffix(name, ".json")); why != "" {
		return drop("refused: %s", why)
	}
	if err := authorize(req, nil); err != nil {
		return drop("refused: %v", err)
	}
	rt := registry.Route{Host: req.Host, Account: req.Account, App: req.App, HoldOp: req.Op}
	guard := func(publish func() error) error { return authorize(req, publish) }
	if _, err := materializeHeldChecked(ctx, s, pub, r, optDir, rt, req.Version, proof, guard, pins...); err != nil {
		if errors.Is(err, ErrStaleHeldStage) {
			return drop("refused at publication: %v", err)
		}
		if errors.Is(err, ErrHeldNotProven) || errors.Is(err, ErrHeldNotAuthorized) || errors.Is(err, ErrManifestDigest) {
			return drop("refused: %v", err)
		}
		fmt.Printf("  %s: held stage of %s for %s: %v; kept for the next pass\n", req.Host, req.Version, req.Op, err)
		return nil
	}
	raw, err := json.Marshal(HeldStaged{Version: req.Version, Op: req.Op, At: time.Now().UTC()})
	if err == nil {
		err = safefile.MkdirAll(HeldStagedDir(dataDir), 0o755)
	}
	if err == nil {
		err = safefile.WriteFile(filepath.Join(HeldStagedDir(dataDir), req.Host+".json"), raw, 0o644)
	}
	if err != nil {
		fmt.Printf("  %s: held stage of %s for %s: live, but the ack was not written: %v; kept for the next pass\n", req.Host, req.Version, req.Op, err)
		return nil
	}
	fmt.Printf("  %s: held stage of %s for %s: live\n", req.Host, req.Version, req.Op)
	if err := safefile.Remove(filepath.Join(reqDir, name)); err != nil {
		fmt.Printf("  held stage request %q: served, but not removed: %v\n", name, err)
	}
	return nil
}

// heldStageRequestInvalid names the first field of req that cannot be
// trusted as a path component or an identity, or returns "". host is the
// request's own file name less ".json".
func heldStageRequestInvalid(req HeldStageRequest, host string) string {
	switch {
	case req.Host != host:
		return "its host is not its file name"
	case !controlname.ValidHostShape(req.Host):
		return "malformed host"
	case !ValidAccount(req.Account):
		return "malformed account"
	case !ValidApp(req.App):
		return "malformed app"
	case !ValidVersion(req.Version):
		return "malformed version"
	case req.Op == "":
		return "no move op"
	case req.Box == "":
		return "no box"
	}
	return ""
}