@synopackageland/cli 0.4.1 → 0.5.0

package/dist/templates/native-go/backend/internal/background/store.go

@@ -0,0 +1,807 @@
+// Package background is the package-private spool, journal and fixed worker
+// behind opt-in background jobs. The CGI submits and reads jobs; a package
+// user unit runs the worker. Both run as the package account and share one
+// 0700 directory, so no root helper, task scheduler or DSM session is needed.
+package background
+
+import (
+	"context"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"io"
+	"os"
+	"regexp"
+	"syscall"
+	"time"
+	"unicode"
+	"unicode/utf8"
+
+	"golang.org/x/sys/unix"
+)
+
+// Product limits, not DSM limits.
+const (
+	WorkerSHA256V1 = "sha256-v1"
+	// WorkerRevision identifies the worker code. A journal written under another
+	// revision never has its queued jobs run by this one.
+	WorkerRevision  = 1
+	MaxInputBytes   = 512 * 1024
+	MaxQueued       = 16
+	MaxOwnerPending = 2
+	MaxOwnerBytes   = 1 << 20
+	MaxPurgeAudit   = 64
+	MaxTotalBytes   = 16 << 20
+	JobTimeout      = 60 * time.Second
+	// MaxHistory bounds finished jobs kept for reading results and for key reuse.
+	MaxHistory = 64
+
+	schemaVersion = 1
+	// resultReserve is charged against the total quota for every kept result.
+	resultReserve = 512
+	maxJournal    = 4 << 20
+)
+
+type State string
+
+const (
+	StateQueued      State = "queued"
+	StateRunning     State = "running"
+	StateSucceeded   State = "succeeded"
+	StateFailed      State = "failed"
+	StateCanceled    State = "canceled"
+	StateInterrupted State = "interrupted"
+)
+
+func (s State) terminal() bool { return s != StateQueued && s != StateRunning }
+
+var (
+	ErrOrdinaryDisabled = errors.New("ordinary background users are disabled")
+	ErrOwnerQueueFull   = errors.New("owner pending quota reached")
+	ErrOwnerQuota       = errors.New("owner storage quota reached")
+	ErrDisabled         = errors.New("background mode is off")
+	ErrInvalid          = errors.New("invalid background request")
+	ErrTooLarge         = errors.New("input is larger than the per-file limit")
+	ErrQueueFull        = errors.New("background queue is full")
+	ErrQuota            = errors.New("background spool quota reached")
+	ErrKeyConflict      = errors.New("idempotency key already used for another input")
+	ErrNotFound         = errors.New("job not found")
+	ErrNotCancelable    = errors.New("job already finished")
+	ErrNotRunning       = errors.New("job is not running")
+	ErrUnsafeSpool      = errors.New("background spool is not private to the package account")
+)
+
+// Submitter binds visibility to a fresh DSM username and UID. It never grants
+// filesystem permissions or changes the worker identity.
+type Submitter struct {
+	User string `json:"user"`
+	UID  string `json:"uid"`
+}
+
+type Result struct {
+	SHA256 string `json:"sha256"`
+	Bytes  int    `json:"bytes"`
+}
+
+type Job struct {
+	CopyRetained    bool      `json:"copyRetained,omitempty"`
+	ScheduleID      string    `json:"scheduleId,omitempty"`
+	ScheduledAt     time.Time `json:"scheduledAt,omitzero"`
+	ID              string    `json:"id"`
+	Key             string    `json:"key"`
+	Name            string    `json:"name"`
+	State           State     `json:"state"`
+	PurgeRequested  bool      `json:"purgeRequested,omitempty"`
+	CancelRequested bool      `json:"cancelRequested,omitempty"`
+	Submitter       Submitter `json:"submitter"`
+	Worker          string    `json:"worker"`
+	WorkerRevision  int       `json:"workerRevision"`
+	InputDigest     string    `json:"inputDigest"`
+	InputBytes      int       `json:"inputBytes"`
+	SubmittedAt     time.Time `json:"submittedAt"`
+	StartedAt       time.Time `json:"startedAt,omitzero"`
+	FinishedAt      time.Time `json:"finishedAt,omitzero"`
+	ErrorCode       string    `json:"errorCode,omitempty"`
+	Result          *Result   `json:"result,omitempty"`
+}
+
+type SubmitRequest struct {
+	Admin     bool // trusted request policy, not a client-supplied field
+	Key       string
+	Name      string
+	Data      []byte
+	Submitter Submitter
+}
+
+// Outcome is what a worker reports for the job it claimed.
+type Outcome struct {
+	State     State
+	ErrorCode string
+	Result    *Result
+}
+
+type WorkerInfo struct {
+	PID      int       `json:"pid"`
+	UID      int       `json:"uid"`
+	Username string    `json:"username"`
+	Revision int       `json:"revision"`
+	At       time.Time `json:"at"`
+}
+
+type Status struct {
+	AllowOrdinaryUsers bool        `json:"allowOrdinaryUsers"`
+	Enabled            bool        `json:"enabled"`
+	Algorithm          string      `json:"algorithm"`
+	Revision           int         `json:"revision"`
+	Queued             int         `json:"queued"`
+	Running            int         `json:"running"`
+	Worker             *WorkerInfo `json:"worker,omitempty"`
+}
+
+type Limits struct{ MaxTotalBytes int64 }
+
+type journal struct {
+	Schedules          []Schedule   `json:"schedules,omitempty"`
+	AllowOrdinaryUsers bool         `json:"allowOrdinaryUsers,omitempty"`
+	PurgeAudit         []PurgeAudit `json:"purgeAudit,omitempty"`
+	Schema             int          `json:"schema"`
+	Revision           int          `json:"workerRevision"`
+	Enabled            bool         `json:"enabled"`
+	Jobs               []Job        `json:"jobs"`
+}
+
+// Store is safe for concurrent use by several processes: every operation runs
+// under an exclusive flock and commits the journal with write, fsync, rename.
+type Store struct {
+	dir      string
+	limits   Limits
+	revision int
+	now      func() time.Time
+}
+
+func NewStore(dir string) *Store {
+	return &Store{dir: dir, limits: Limits{MaxTotalBytes: MaxTotalBytes}, revision: WorkerRevision, now: time.Now}
+}
+
+var (
+	jobID  = regexp.MustCompile(`^[0-9a-f]{32}$`)
+	keyRE  = regexp.MustCompile(`^[A-Za-z0-9._-]{1,64}$`)
+	inputs = "inputs"
+)
+
+func validName(name string) bool {
+	if n := utf8.RuneCountInString(name); n < 1 || n > 128 || !utf8.ValidString(name) {
+		return false
+	}
+	for _, r := range name {
+		if unicode.IsControl(r) || r == '/' || r == '\\' {
+			return false
+		}
+	}
+	return true
+}
+
+// withJournal runs fn on the journal under the spool lock. fn reports whether
+// it changed anything; only then is the journal rewritten.
+func (s *Store) withJournal(ctx context.Context, fn func(root *os.Root, j *journal) (bool, error)) error {
+	root, err := s.openRoot()
+	if err != nil {
+		return err
+	}
+	defer root.Close()
+	lock, err := root.OpenFile("lock", os.O_CREATE|os.O_RDWR|unix.O_NOFOLLOW, 0o600)
+	if err != nil {
+		return err
+	}
+	defer lock.Close()
+	if err := checkPrivate(lock); err != nil {
+		return err
+	}
+	for {
+		err = unix.Flock(int(lock.Fd()), unix.LOCK_EX|unix.LOCK_NB)
+		if err == nil {
+			break
+		}
+		if !errors.Is(err, unix.EWOULDBLOCK) {
+			return err
+		}
+		select {
+		case <-ctx.Done():
+			return ctx.Err()
+		case <-time.After(10 * time.Millisecond):
+		}
+	}
+	defer unix.Flock(int(lock.Fd()), unix.LOCK_UN)
+	j, err := s.readJournal(root)
+	if err != nil {
+		return err
+	}
+	changed, err := fn(root, &j)
+	if err != nil || !changed {
+		return err
+	}
+	if err := writeAtomic(root, "journal.json", &j); err != nil {
+		return err
+	}
+	s.removeOrphanInputs(root, &j)
+	return nil
+}
+
+// openRoot creates the spool on first use and refuses one that is a symlink,
+// belongs to someone else or is readable by other accounts.
+func (s *Store) openRoot() (*os.Root, error) {
+	if err := os.Mkdir(s.dir, 0o700); err != nil && !errors.Is(err, os.ErrExist) {
+		return nil, err
+	}
+	info, err := os.Lstat(s.dir)
+	if err != nil {
+		return nil, err
+	}
+	if err := checkPrivateInfo(info, true); err != nil {
+		return nil, err
+	}
+	root, err := os.OpenRoot(s.dir)
+	if err != nil {
+		return nil, err
+	}
+	if err := root.Mkdir(inputs, 0o700); err != nil && !errors.Is(err, os.ErrExist) {
+		root.Close()
+		return nil, err
+	}
+	if info, err := root.Lstat(inputs); err != nil || checkPrivateInfo(info, true) != nil {
+		root.Close()
+		return nil, ErrUnsafeSpool
+	}
+	return root, nil
+}
+
+func checkPrivate(f *os.File) error {
+	info, err := f.Stat()
+	if err != nil {
+		return err
+	}
+	return checkPrivateInfo(info, false)
+}
+
+func checkPrivateInfo(info os.FileInfo, dir bool) error {
+	if dir != info.IsDir() || (!dir && !info.Mode().IsRegular()) || info.Mode().Perm()&0o077 != 0 || !ownedByUs(info) {
+		return ErrUnsafeSpool
+	}
+	return nil
+}
+
+func (s *Store) readJournal(root *os.Root) (journal, error) {
+	j := journal{Schema: schemaVersion, Revision: s.revision}
+	f, err := root.OpenFile("journal.json", os.O_RDONLY|unix.O_NOFOLLOW, 0)
+	if errors.Is(err, os.ErrNotExist) {
+		return j, nil
+	}
+	if err != nil {
+		return j, err
+	}
+	defer f.Close()
+	if err := checkPrivate(f); err != nil {
+		return j, err
+	}
+	b, err := io.ReadAll(io.LimitReader(f, maxJournal+1))
+	if err != nil || len(b) > maxJournal {
+		return j, errors.New("background journal unreadable")
+	}
+	if err := json.Unmarshal(b, &j); err != nil || j.Schema != schemaVersion {
+		return journal{}, errors.New("background journal has an unsupported schema")
+	}
+	return j, nil
+}
+
+func writeAtomic(root *os.Root, name string, v any) error {
+	b, err := json.Marshal(v)
+	if err != nil {
+		return err
+	}
+	nonce := make([]byte, 8)
+	if _, err := rand.Read(nonce); err != nil {
+		return err
+	}
+	tmp := "." + name + "-" + hex.EncodeToString(nonce)
+	f, err := root.OpenFile(tmp, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+	if err != nil {
+		return err
+	}
+	_, err = f.Write(b)
+	if err == nil {
+		err = f.Sync()
+	}
+	if cerr := f.Close(); err == nil {
+		err = cerr
+	}
+	if err == nil {
+		err = root.Rename(tmp, name)
+	}
+	if err != nil {
+		_ = root.Remove(tmp)
+		return err
+	}
+	return syncDir(root, ".")
+}
+
+func syncDir(root *os.Root, name string) error {
+	d, err := root.Open(name)
+	if err != nil {
+		return err
+	}
+	defer d.Close()
+	return d.Sync()
+}
+
+func newID() (string, error) {
+	b := make([]byte, 16)
+	if _, err := rand.Read(b); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(b), nil
+}
+
+func find(j *journal, id string) *Job {
+	if !jobID.MatchString(id) {
+		return nil
+	}
+	for i := range j.Jobs {
+		if j.Jobs[i].ID == id {
+			return &j.Jobs[i]
+		}
+	}
+	return nil
+}
+
+func (j *journal) pending() (count int, bytes int64) {
+	for _, job := range j.Jobs {
+		if !job.State.terminal() {
+			count++
+			bytes += int64(job.InputBytes + resultReserve)
+		} else {
+			if job.CopyRetained {
+				bytes += int64(job.InputBytes)
+			}
+			if job.Result != nil {
+				bytes += resultReserve
+			}
+		}
+	}
+	for _, sc := range j.Schedules {
+		bytes += int64(sc.InputBytes)
+	}
+	return count, bytes
+}
+
+// trim keeps pending jobs and the newest MaxHistory finished ones.
+func (j *journal) trim() {
+	finished := 0
+	for _, job := range j.Jobs {
+		if job.State.terminal() {
+			finished++
+		}
+	}
+	kept := j.Jobs[:0]
+	for _, job := range j.Jobs {
+		if job.State.terminal() && finished > MaxHistory {
+			finished--
+			continue
+		}
+		kept = append(kept, job)
+	}
+	j.Jobs = kept
+}
+
+func (s *Store) removeInput(root *os.Root, id string) {
+	_ = root.Remove(inputs + "/" + id)
+}
+
+func (s *Store) SetEnabled(ctx context.Context, enabled bool) error {
+	return s.withJournal(ctx, func(root *os.Root, j *journal) (bool, error) {
+		if j.Enabled == enabled {
+			return false, nil
+		}
+		j.Enabled = enabled
+		if !enabled {
+			for i := range j.Schedules {
+				j.Schedules[i].Enabled = false
+				j.Schedules[i].Reason = "disabled"
+			}
+			for i := range j.Jobs {
+				switch job := &j.Jobs[i]; job.State {
+				case StateQueued:
+					s.finishJob(root, job, StateCanceled, "disabled")
+				case StateRunning:
+					job.CancelRequested = true
+				}
+			}
+		}
+		return true, nil
+	})
+}
+
+func (s *Store) finishJob(root *os.Root, job *Job, state State, code string) {
+	job.State, job.ErrorCode, job.FinishedAt = state, code, s.now().UTC()
+	if state != StateSucceeded {
+		job.CopyRetained = false
+	}
+	if !job.CopyRetained {
+		s.removeInput(root, job.ID)
+	}
+}
+
+func (s *Store) Submit(ctx context.Context, req SubmitRequest) (Job, bool, error) {
+	if len(req.Data) > MaxInputBytes {
+		return Job{}, false, ErrTooLarge
+	}
+	if !keyRE.MatchString(req.Key) || !validName(req.Name) || len(req.Data) == 0 || !req.Submitter.Valid() {
+		return Job{}, false, ErrInvalid
+	}
+	digest := sha256hex(req.Data)
+	var created Job
+	var duplicate bool
+	err := s.withJournal(ctx, func(root *os.Root, j *journal) (bool, error) {
+		if !j.Enabled {
+			return false, ErrDisabled
+		}
+		if !req.Admin && !j.AllowOrdinaryUsers {
+			return false, ErrOrdinaryDisabled
+		}
+		for _, job := range j.Jobs {
+			if job.Submitter == req.Submitter && job.Key == req.Key && !job.PurgeRequested {
+				if job.InputDigest != digest {
+					return false, ErrKeyConflict
+				}
+				created, duplicate = job, true
+				return false, nil
+			}
+		}
+		// Reserve the input and one bounded result for each pending job. Finished
+		// result charges remain until history trimming or an explicit admin purge.
+		pending, ownerBytes := j.ownerUsage(req.Submitter)
+		if pending >= MaxOwnerPending {
+			return false, ErrOwnerQueueFull
+		}
+		if ownerBytes+int64(len(req.Data)+resultReserve) > MaxOwnerBytes {
+			return false, ErrOwnerQuota
+		}
+		count, used := j.pending()
+		if count >= MaxQueued {
+			return false, ErrQueueFull
+		}
+		if used+int64(len(req.Data)+resultReserve) > s.limits.MaxTotalBytes {
+			return false, ErrQuota
+		}
+		id, err := newID()
+		if err != nil {
+			return false, err
+		}
+		if err := writeInput(root, id, req.Data); err != nil {
+			return false, err
+		}
+		created = Job{
+			ID: id, Key: req.Key, Name: req.Name, CopyRetained: true, State: StateQueued, Submitter: req.Submitter,
+			Worker: WorkerSHA256V1, WorkerRevision: s.revision, InputDigest: digest,
+			InputBytes: len(req.Data), SubmittedAt: s.now().UTC(),
+		}
+		j.Jobs = append(j.Jobs, created)
+		j.trim()
+		// A journal commit failure surfaces below; the input is then orphaned
+		// and removed by the next Recover.
+		return true, nil
+	})
+	return created, duplicate, err
+}
+
+func writeInput(root *os.Root, id string, data []byte) error {
+	f, err := root.OpenFile(inputs+"/"+id, os.O_CREATE|os.O_EXCL|os.O_WRONLY, 0o600)
+	if err != nil {
+		return err
+	}
+	_, err = f.Write(data)
+	if err == nil {
+		err = f.Sync()
+	}
+	if cerr := f.Close(); err == nil {
+		err = cerr
+	}
+	if err == nil {
+		err = syncDir(root, inputs)
+	}
+	if err != nil {
+		_ = root.Remove(inputs + "/" + id)
+	}
+	return err
+}
+
+func (s *Store) List(ctx context.Context) ([]Job, error) { return s.ListFor(ctx, Access{Admin: true}) }
+func (s *Store) ListFor(ctx context.Context, access Access) ([]Job, error) {
+	var jobs []Job
+	err := s.withJournal(ctx, func(_ *os.Root, j *journal) (bool, error) {
+		for _, job := range j.Jobs {
+			if access.sees(job) {
+				jobs = append(jobs, job)
+			}
+		}
+		return false, nil
+	})
+	return jobs, err
+}
+
+// Get is the internal worker view, including a pending purge so cancellation drains.
+func (s *Store) Get(ctx context.Context, id string) (Job, error) { return s.get(ctx, id, nil) }
+func (s *Store) GetFor(ctx context.Context, id string, access Access) (Job, error) {
+	return s.get(ctx, id, &access)
+}
+func (s *Store) get(ctx context.Context, id string, access *Access) (Job, error) {
+	var out Job
+	err := s.withJournal(ctx, func(_ *os.Root, j *journal) (bool, error) {
+		job := find(j, id)
+		if job == nil || (access != nil && !access.sees(*job)) {
+			return false, ErrNotFound
+		}
+		out = *job
+		return false, nil
+	})
+	return out, err
+}
+
+func (s *Store) Cancel(ctx context.Context, id string) (Job, error) {
+	return s.CancelFor(ctx, id, Access{Admin: true})
+}
+func (s *Store) CancelFor(ctx context.Context, id string, access Access) (Job, error) {
+	var out Job
+	err := s.withJournal(ctx, func(root *os.Root, j *journal) (bool, error) {
+		job := find(j, id)
+		if job == nil || !access.sees(*job) {
+			return false, ErrNotFound
+		}
+		switch job.State {
+		case StateQueued:
+			s.finishJob(root, job, StateCanceled, "")
+		case StateRunning:
+			job.CancelRequested = true
+		default:
+			return false, ErrNotCancelable
+		}
+		out = *job
+		return true, nil
+	})
+	return out, err
+}
+
+// Claim hands the oldest queued job to the worker, or nil when there is none,
+// the mode is off or another job is still running.
+func (s *Store) Claim(ctx context.Context) (*Job, error) {
+	var out *Job
+	err := s.withJournal(ctx, func(_ *os.Root, j *journal) (bool, error) {
+		if !j.Enabled {
+			return false, nil
+		}
+		var next *Job
+		for i := range j.Jobs {
+			switch job := &j.Jobs[i]; job.State {
+			case StateRunning:
+				return false, nil
+			case StateQueued:
+				if next == nil {
+					next = job
+				}
+			}
+		}
+		if next == nil {
+			return false, nil
+		}
+		next.State, next.StartedAt = StateRunning, s.now().UTC()
+		claimed := *next
+		out = &claimed
+		return true, nil
+	})
+	return out, err
+}
+
+// Finish records the outcome of a running job. A cancel request that was
+// journaled first wins over a success or failure that arrives later.
+func (s *Store) Finish(ctx context.Context, id string, outcome Outcome) error {
+	if !outcome.State.terminal() {
+		return ErrInvalid
+	}
+	return s.withJournal(ctx, func(root *os.Root, j *journal) (bool, error) {
+		job := find(j, id)
+		if job == nil || job.State != StateRunning {
+			return false, ErrNotRunning
+		}
+		if job.CancelRequested {
+			outcome = Outcome{State: StateCanceled}
+		}
+		s.finishJob(root, job, outcome.State, outcome.ErrorCode)
+		if outcome.State == StateSucceeded {
+			job.Result = outcome.Result
+		}
+		j.removePurged()
+		j.trim()
+		return true, nil
+	})
+}
+
+// Recover runs when the worker starts. A job still marked running lost its
+// worker: it is interrupted (or canceled when a cancel was already requested)
+// and never replayed. Queued jobs journaled for another worker revision are
+// interrupted too, so an upgrade cannot silently run old work with new code.
+func (s *Store) Recover(ctx context.Context) error {
+	return s.withJournal(ctx, func(root *os.Root, j *journal) (bool, error) {
+		changed := j.Revision != s.revision
+		for i := range j.Jobs {
+			job := &j.Jobs[i]
+			switch {
+			case job.State == StateRunning && job.CancelRequested:
+				s.finishJob(root, job, StateCanceled, "")
+				changed = true
+			case job.State == StateRunning:
+				s.finishJob(root, job, StateInterrupted, "worker-stopped")
+				changed = true
+			case job.State == StateQueued && j.Revision != s.revision:
+				s.finishJob(root, job, StateInterrupted, "worker-changed")
+			}
+		}
+		j.removePurged()
+		changed = s.reconcileSchedules(root, j, true) || changed
+		j.Revision = s.revision
+		s.removeOrphanInputs(root, j)
+		return changed, nil
+	})
+}
+
+func (s *Store) removeOrphanInputs(root *os.Root, j *journal) {
+	dir, err := root.Open(inputs)
+	if err != nil {
+		return
+	}
+	names, _ := dir.Readdirnames(-1)
+	dir.Close()
+	live := map[string]bool{}
+	for _, job := range j.Jobs {
+		if !job.State.terminal() || job.CopyRetained {
+			live[job.ID] = true
+		}
+	}
+	for _, sc := range j.Schedules {
+		live[sc.ID] = true
+	}
+	for _, name := range names {
+		if !live[name] {
+			_ = root.Remove(inputs + "/" + name)
+		}
+	}
+}
+
+// OpenInput returns the stored input of the job that is currently running.
+func (s *Store) OpenInput(id string) (*os.File, error) {
+	var f *os.File
+	err := s.withJournal(context.Background(), func(root *os.Root, j *journal) (bool, error) {
+		job := find(j, id)
+		if job == nil || job.State != StateRunning {
+			return false, ErrNotRunning
+		}
+		var err error
+		f, err = root.OpenFile(inputs+"/"+id, os.O_RDONLY|unix.O_NOFOLLOW, 0)
+		return false, err
+	})
+	return f, err
+}
+
+func (s *Store) Status(ctx context.Context) (Status, error) {
+	return s.StatusFor(ctx, Access{Admin: true})
+}
+func (s *Store) StatusFor(ctx context.Context, access Access) (Status, error) {
+	st := Status{Algorithm: WorkerSHA256V1, Revision: s.revision}
+	err := s.withJournal(ctx, func(root *os.Root, j *journal) (bool, error) {
+		st.Enabled, st.AllowOrdinaryUsers = j.Enabled, j.AllowOrdinaryUsers
+		for _, job := range j.Jobs {
+			if !access.sees(job) {
+				continue
+			}
+			switch job.State {
+			case StateQueued:
+				st.Queued++
+			case StateRunning:
+				st.Running++
+			}
+		}
+		st.Worker = readWorker(root)
+		return false, nil
+	})
+	return st, err
+}
+
+func readWorker(root *os.Root) *WorkerInfo {
+	f, err := root.OpenFile("worker.json", os.O_RDONLY|unix.O_NOFOLLOW, 0)
+	if err != nil {
+		return nil
+	}
+	defer f.Close()
+	b, err := io.ReadAll(io.LimitReader(f, 4096))
+	var w WorkerInfo
+	if err != nil || checkPrivate(f) != nil || json.Unmarshal(b, &w) != nil {
+		return nil
+	}
+	return &w
+}
+
+// Heartbeat publishes who the worker is and when it last ran. It is kept out
+// of the journal so an idle worker causes no journal rewrites.
+func (s *Store) Heartbeat(ctx context.Context, info WorkerInfo) error {
+	root, err := s.openRoot()
+	if err != nil {
+		return err
+	}
+	defer root.Close()
+	info.Revision, info.At = s.revision, s.now().UTC()
+	return writeAtomic(root, "worker.json", info)
+}
+
+func ownedByUs(info os.FileInfo) bool {
+	st, ok := info.Sys().(*syscall.Stat_t)
+	return ok && int(st.Uid) == os.Getuid()
+}
+
+func sha256hex(b []byte) string {
+	sum := sha256.Sum256(b)
+	return hex.EncodeToString(sum[:])
+}
+
+// SetOrdinaryUsers is independent of background mode, and defaults off when
+// reading an A0 journal. A submission rechecks it under the same flock as enqueue.
+func (s *Store) SetOrdinaryUsers(ctx context.Context, allow bool) error {
+	return s.withJournal(ctx, func(_ *os.Root, j *journal) (bool, error) { j.AllowOrdinaryUsers = allow; return true, nil })
+}
+func (j *journal) removePurged() {
+	kept := j.Jobs[:0]
+	for _, job := range j.Jobs {
+		if !job.PurgeRequested || !job.State.terminal() {
+			kept = append(kept, job)
+		}
+	}
+	j.Jobs = kept
+}
+
+// PurgeOwner preserves other owners and records an audit in the same durable
+// journal. Running jobs become hidden tombstones until Finish/Recover drains them.
+func (s *Store) PurgeOwner(ctx context.Context, owner Submitter, actor string) (PurgeAudit, error) {
+	if owner.User == "" || actor == "" {
+		return PurgeAudit{}, ErrInvalid
+	}
+	audit := PurgeAudit{Owner: owner, Actor: actor, At: s.now().UTC()}
+	err := s.withJournal(ctx, func(root *os.Root, j *journal) (bool, error) {
+		for i := range j.Jobs {
+			job := &j.Jobs[i]
+			if job.Submitter != owner || job.PurgeRequested {
+				continue
+			}
+			job.PurgeRequested = true
+			if job.State == StateRunning {
+				job.CancelRequested = true
+				audit.Draining++
+			} else {
+				s.finishJob(root, job, StateCanceled, "purged")
+				audit.Removed++
+			}
+		}
+		kept := j.Schedules[:0]
+		for _, sc := range j.Schedules {
+			if sc.Owner != owner {
+				kept = append(kept, sc)
+			}
+		}
+		j.Schedules = kept
+		j.removePurged()
+		j.PurgeAudit = append(j.PurgeAudit, audit)
+		if len(j.PurgeAudit) > MaxPurgeAudit {
+			j.PurgeAudit = j.PurgeAudit[len(j.PurgeAudit)-MaxPurgeAudit:]
+		}
+		return true, nil
+	})
+	return audit, err
+}