@synopackageland/cli 0.4.0 → 0.5.0

package/templates/native-go/backend/internal/helper/sdk_session.go

@@ -0,0 +1,677 @@
+//go:build synopkgland_sdk_workers
+
+package helper
+
+import (
+	"context"
+	"crypto/hmac"
+	"crypto/rand"
+	"crypto/sha256"
+	"encoding/hex"
+	"encoding/json"
+	"errors"
+	"net/http"
+	"sort"
+	"strconv"
+	"strings"
+	"time"
+
+	"dsmapp/internal/api"
+	"dsmapp/internal/filestation"
+	"dsmapp/internal/helper/jobcontract"
+)
+
+func newSDKSessionJobs(o *sdkJobOwner, files sdkSessionFiles, auth api.Authenticator) (*sdkSessionJobs, Code) {
+	if o == nil || files == nil {
+		return nil, ErrUnavailable
+	}
+	s := &sdkSessionJobs{owner: o, files: files, auth: auth, pending: map[string]sdkSessionPending{}, jobs: map[string]*sdkSessionJob{}, history: map[string]sdkJournalRecord{}, cursors: map[string]sdkSessionCursor{}, counts: map[string]int{}, revision: 1}
+	if _, e := rand.Read(s.key[:]); e != nil {
+		return nil, ErrUnavailable
+	}
+	if journal, ok := o.services.Journal.(sdkRetainedJournal); ok {
+		records, c := journal.Records()
+		if c != "" {
+			return nil, c
+		}
+		for _, r := range records {
+			if r.State != "finished" && r.State != "interrupted" {
+				return nil, ErrCleanupRequired
+			}
+			s.history[r.Intent.Request.Control.Binding.Job.ID] = r
+		}
+	}
+	return s, ""
+}
+func sessionError(e error) Code {
+	if e == nil {
+		return ""
+	}
+	var a *api.Error
+	if errors.As(e, &a) {
+		switch a.Code {
+		case "session_required", "auth_unavailable":
+			return ErrDenied
+		default:
+			return safeGrantCode(Code(a.Code))
+		}
+	}
+	return ErrDenied
+}
+func sessionSame(a, b filestation.SessionIdentity) bool { return a.User == b.User && a.UID == b.UID }
+func sessionRequest(c SessionCarriers) (*http.Request, Code) {
+	r, _ := http.NewRequest(http.MethodGet, "http://127.0.0.1/", nil)
+	r.Header.Set("Cookie", c.Cookie)
+	cookies := r.CookiesNamed("id")
+	if len(cookies) != 1 || cookies[0].Value == "" || len(c.Cookie) > 4096 || len(c.SynoToken) > 4096 || strings.ContainsAny(c.SynoToken, "\r\n\x00") || c.ClientAddress == "" {
+		return nil, ErrDenied
+	}
+	r.Header.Del("Cookie")
+	r.AddCookie(cookies[0])
+	r.Header.Set("X-SYNO-TOKEN", c.SynoToken)
+	r.RemoteAddr = c.ClientAddress
+	return r, ""
+}
+func (s *sdkSessionJobs) identity(ctx context.Context, c SessionCarriers) (filestation.SessionIdentity, string, Code) {
+	r, code := sessionRequest(c)
+	if code != "" {
+		return filestation.SessionIdentity{}, "", code
+	}
+	id, e := s.files.CheckSession(ctx, s.auth, r)
+	if e != nil {
+		return id, "", sessionError(e)
+	}
+	uid, e := strconv.ParseUint(id.UID, 10, 32)
+	if e != nil || uid == 0 || !validRelaxedIdentity(RelaxedIdentity{UID: uint32(uid), Username: id.User}) || ctx.Err() != nil {
+		return id, "", ErrDenied
+	}
+	// Per-owner keyed binding. Neither the SID/token nor a reusable unkeyed SID
+	// hash is persisted. A restart cannot recover this binding or resume a job.
+	cookie, _ := r.Cookie("id")
+	mac := hmac.New(sha256.New, s.key[:])
+	mac.Write([]byte(cookie.Value))
+	mac.Write([]byte{0})
+	mac.Write([]byte(c.ClientAddress))
+	return id, hex.EncodeToString(mac.Sum(nil)), ""
+}
+func (s *sdkSessionJobs) ready() bool {
+	s.owner.grants.cohort.gate.mu.Lock()
+	defer s.owner.grants.cohort.gate.mu.Unlock()
+	return s.owner.grants.cohort.allowed() && !s.owner.grants.authority.fenced
+}
+
+// Classify an existing refusal; this never grants admission, returns job data,
+// renews a lease, or changes the cancellation reason retained in the journal.
+func (s *sdkSessionJobs) refusalCode() Code {
+	c := s.owner.grants.cohort
+	g := c.gate
+	g.mu.Lock()
+	defer g.mu.Unlock()
+	_ = c.allowed() // preserve freshness/backwards-clock checks and sticky precedence
+	if !c.fenced && !s.owner.grants.authority.fenced && g.blocked == "" &&
+		(!g.queryUntil.IsZero() || (!g.reloadUntil.IsZero() && !g.pendingUntil.IsZero())) {
+		return ErrRevalidating
+	}
+	return ErrFenced
+}
+func (s *sdkSessionJobs) budget(id filestation.SessionIdentity) Code {
+	second := s.owner.attachNow() / time.Second
+	if second < s.second {
+		return ErrStale
+	}
+	if second != s.second {
+		s.second = second
+		s.counts = map[string]int{}
+	}
+	if s.counts[id.UID] >= 2 {
+		return ErrBusy
+	}
+	if len(s.counts) >= 256 && s.counts[id.UID] == 0 {
+		return ErrLimit
+	}
+	s.counts[id.UID]++
+	return ""
+}
+func (s *sdkSessionJobs) prepare(ctx context.Context, c SessionCarriers, id filestation.SessionIdentity, session string, in sdkPrepareArgs) (any, Code) {
+	w, ok := s.owner.workers[in.Worker.ID]
+	if !ok || w.Revision != in.Worker.Revision {
+		return nil, ErrIncompatible
+	}
+	if !allReferences(in.Parent.ID) || in.Parent.Revision != 1 {
+		return nil, ErrInvalid
+	}
+	if why := jobcontract.ValidatePlan(w, in.Input, jobcontract.Interactive); why != "" {
+		return nil, sdkCode(why)
+	}
+	for _, step := range in.Input.Steps {
+		if step.Action == jobcontract.ReadStream {
+			return nil, ErrUnsupported
+		}
+		if step.MaxBytes != nil && *step.MaxBytes > filestation.MaxBytes || step.Limit != nil && *step.Limit > filestation.PageSize {
+			return nil, ErrLimit
+		}
+	}
+	if e := s.files.JobSelection(ctx, id, in.Parent.ID); e != nil {
+		return nil, sessionError(e)
+	}
+	now := s.owner.attachNow()
+	count := 0
+	for k, p := range s.pending {
+		if now >= p.expires || now < p.expires-IntentTTL {
+			delete(s.pending, k)
+		} else if sessionSame(p.identity, id) {
+			count++
+		}
+	}
+	if count >= MaxLiveIntents || len(s.pending) >= MaxReplayEntries || len(s.jobs)+len(s.history) >= jobcontract.MaxExecutionKeys {
+		return nil, ErrBusy
+	}
+	refs := make([]string, 4)
+	for n := range refs {
+		var code Code
+		refs[n], code = sdkRandomRef()
+		if code != "" {
+			return nil, code
+		}
+	}
+	digest, _ := jobcontract.InputDigest(in.Input, w.InputSchemaDigest)
+	p := s.owner.grants.authority.policy
+	b := jobcontract.Binding{Inventory: sdkInventory(p.Inventory), JobSchema: 1, Epoch: p.Epoch, Job: jobcontract.RevisionRef{ID: refs[0], Revision: 1}, Worker: in.Worker, ParentGrant: in.Parent, ApprovalBinding: p.ApprovalBinding, CapabilityDigest: p.CapabilityDigest, InputSchemaDigest: w.InputSchemaDigest, InputDigest: digest, Mode: jobcontract.Interactive}
+	request, code := cloneSDKRequest(sdkJobRequest{Control: jobcontract.Control{Op: "jobs.submit", Binding: b, Intent: jobcontract.RevisionRef{ID: refs[1], Revision: 1}, Nonce: refs[2], Ticket: refs[3]}, Input: in.Input})
+	if code != "" {
+		return nil, code
+	}
+	raw, _ := json.Marshal(request)
+	sum := sha256.Sum256(raw)
+	summary := hex.EncodeToString(sum[:])
+	fresh, ref, code := s.identity(ctx, c)
+	if code != "" {
+		return nil, code
+	}
+	if !sessionSame(id, fresh) || ref != session {
+		return nil, ErrDenied
+	}
+	if !s.ready() {
+		return nil, ErrFenced
+	}
+	s.pending[refs[1]] = sdkSessionPending{request, id, session, summary, now + IntentTTL}
+	return sdkPrepared{refs[1], refs[0], summary, s.owner.grants.cohort.now().Add(IntentTTL).UnixMilli()}, ""
+}
+func (s *sdkSessionJobs) capacity(id filestation.SessionIdentity) Code {
+	n, own := len(s.owner.grants.cohort.operations), 0
+	for _, op := range s.owner.grants.cohort.operations {
+		if strconv.FormatUint(uint64(op.actor.UID()), 10) == id.UID {
+			own++
+		}
+	}
+	for _, j := range s.jobs {
+		if !j.terminal || j.done != nil {
+			n++
+			if j.identity.UID == id.UID {
+				own++
+			}
+		}
+	}
+	if n >= jobcontract.MaxChildren || own >= jobcontract.MaxUIDChildren {
+		return ErrBusy
+	}
+	return ""
+}
+func (s *sdkSessionJobs) submit(ctx context.Context, c SessionCarriers, id filestation.SessionIdentity, session string, in sdkSubmitArgs) (any, Code) {
+	p, ok := s.pending[in.IntentID]
+	if !ok {
+		return nil, ErrReplay
+	}
+	if !sessionSame(p.identity, id) || p.session != session || p.summary != in.SummaryDigest {
+		return nil, ErrDenied
+	}
+	delete(s.pending, in.IntentID) // single attempt even after a failed admission
+	now := s.owner.attachNow()
+	if now >= p.expires || now < p.expires-IntentTTL {
+		return nil, ErrExpired
+	}
+	if code := s.capacity(id); code != "" {
+		return nil, code
+	}
+	if e := s.files.JobSelection(ctx, id, p.request.Control.Binding.ParentGrant.ID); e != nil {
+		return nil, sessionError(e)
+	}
+	attach, code := sdkRandomRef()
+	if code != "" {
+		return nil, code
+	}
+	uid, _ := strconv.ParseUint(id.UID, 10, 32)
+	// Random journal session reference is display metadata, not the HMAC binding.
+	journalRef, code := sdkRandomRef()
+	if code != "" {
+		return nil, code
+	}
+	j := &sdkSessionJob{request: p.request, identity: id, session: session, attach: attach, carriers: c, deadline: now + sdkAttachTTL, last: now, total: now + time.Duration(s.owner.workers[p.request.Control.Binding.Worker.ID].Limits.TotalMS)*time.Millisecond, receipt: sdkJobReceipt{Job: jobcontract.Job{Binding: p.request.Control.Binding, State: jobcontract.Running, Progress: jobcontract.Progress{Phase: "starting"}, AcceptedAt: uint64(s.owner.grants.cohort.now().UnixMilli())}, Result: &jobcontract.Result{ResultSchema: 1}}}
+	n := uint64(len(j.request.Input.Steps))
+	j.receipt.Job.Progress.TotalUnits = &n
+	started := j.receipt.Job.AcceptedAt
+	j.receipt.Job.StartedAt = &started
+	code = s.owner.services.Journal.Reserve(sdkJobIntent{Request: p.request, Actor: jobcontract.Principal{IdentityBasis: "uid-username", UID: uint32(uid), Username: id.User}, SessionRef: journalRef})
+	if code != "" {
+		return nil, code
+	}
+	s.jobs[p.request.Control.Binding.Job.ID] = j
+	s.revision++
+	// Durability/DSM waits must not extend consent, total time, or attach TTL.
+	fresh, ref, code := s.identity(ctx, c)
+	if code == "" && (!sessionSame(id, fresh) || ref != session) {
+		code = ErrDenied
+	}
+	if code == "" && (s.owner.attachNow() >= p.expires || s.expired(j)) {
+		code = ErrExpired
+	}
+	if code == "" && !s.ready() {
+		code = ErrFenced
+	}
+	if code != "" {
+		if stop := s.stop(j, code); stop != "" {
+			return nil, stop
+		}
+		return nil, code
+	}
+	return sdkAttachReceipt{JobID: p.request.Control.Binding.Job.ID, Revision: s.revision, AttachID: attach, RenewAfterMS: SDKAttachRenewMS, TTLMS: SDKAttachTTLMS}, ""
+}
+func (s *sdkSessionJobs) expired(j *sdkSessionJob) bool {
+	now := s.owner.attachNow()
+	return now < j.last || now >= j.deadline || now >= j.total
+}
+func (s *sdkSessionJobs) finish(j *sdkSessionJob, state jobcontract.State, code Code) Code {
+	at := uint64(s.owner.grants.cohort.now().UnixMilli())
+	j.receipt.Job.State = state
+	j.receipt.Job.Reason = jobcontract.SafeReason(code)
+	j.receipt.Job.FinishedAt = &at
+	j.receipt.Job.Drained = !j.uncertain
+	j.receipt.Job.EffectsUnknown = j.uncertain
+	j.terminal = true
+	j.carriers = SessionCarriers{}
+	s.revision++
+	if state != jobcontract.Succeeded {
+		j.receipt.Result = nil
+	}
+	// An interrupted HTTP request cannot prove remote DSM quiescence. Retain
+	// its durable cancel record; do not write a falsely drained terminal receipt.
+	if j.uncertain {
+		return ""
+	}
+	if c := s.owner.services.Journal.Finish(j.receipt); c != "" {
+		j.receipt.Job.State = jobcontract.CleanupRequired
+		j.receipt.Job.Reason = jobcontract.ReasonCleanupRequired
+		j.receipt.Job.FinishedAt = nil
+		j.receipt.Job.Drained = false
+		j.receipt.Job.EffectsUnknown = true
+		return ErrCleanupRequired
+	}
+	return ""
+}
+func (s *sdkSessionJobs) stop(j *sdkSessionJob, why Code) Code {
+	if j.terminal {
+		return ""
+	}
+	c := s.owner.services.Journal.Cancel(j.request.Control.Binding)
+	// Even a storage failure closes network admission immediately. It never
+	// acknowledges durable cancellation or turns into a successful terminal.
+	j.receipt.Job.CancelRequested = true
+	j.carriers = SessionCarriers{}
+	if j.cancel != nil {
+		j.uncertain = true
+		j.cancel()
+	}
+	if c != "" {
+		j.terminal = true
+		j.receipt.Job.State = jobcontract.CleanupRequired
+		j.receipt.Job.Reason = jobcontract.ReasonCleanupRequired
+		j.receipt.Job.FinishedAt = nil
+		j.receipt.Job.Drained = false
+		j.receipt.Job.EffectsUnknown = true
+		s.revision++
+		return ErrCleanupRequired
+	}
+	return s.finish(j, jobcontract.Canceled, why)
+}
+func (s *sdkSessionJobs) poll() Code {
+	for _, j := range s.jobs {
+		if !j.terminal && (!s.ready() || s.expired(j)) {
+			why := ErrExpired
+			if !s.ready() {
+				why = ErrFenced
+			}
+			if c := s.stop(j, why); c != "" {
+				return c
+			}
+		}
+		if j.done != nil {
+			select {
+			case result := <-j.done:
+				j.cancel()
+				j.done = nil
+				j.cancel = nil
+				if j.terminal {
+					continue
+				}
+				if result.code != "" {
+					// A transport refusal may follow a remote read. There are no writes,
+					// but do not manufacture remote Q from cancellation of a local socket.
+					j.uncertain = true
+					if c := s.stop(j, result.code); c != "" {
+						return c
+					}
+					continue
+				}
+				r := j.receipt.Result
+				r.CompletedSteps += result.result.CompletedSteps
+				r.Entries += result.result.Entries
+				r.BytesRead += result.result.BytesRead
+				j.receipt.Job.Progress.Sequence++
+				j.receipt.Job.Progress.Phase = "metadata"
+				j.receipt.Job.Progress.CompletedUnits = r.CompletedSteps
+				j.receipt.Job.Progress.BytesRead = r.BytesRead
+				s.revision++
+				if r.CompletedSteps == uint64(len(j.request.Input.Steps)) {
+					if c := s.finish(j, jobcontract.Succeeded, ""); c != "" {
+						return c
+					}
+				}
+			default:
+			}
+		}
+		if j.terminal || j.done != nil {
+			continue
+		}
+		w := s.owner.workers[j.request.Control.Binding.Worker.ID]
+		step := j.request.Input.Steps[j.receipt.Result.CompletedSteps]
+		span := min(j.deadline-s.owner.attachNow(), j.total-s.owner.attachNow(), time.Duration(w.Limits.IdleMS)*time.Millisecond)
+		if step.Action == jobcontract.Read {
+			span = min(span, time.Duration(w.Limits.BoundedMS)*time.Millisecond)
+		} else {
+			span = min(span, time.Duration(w.Limits.MetadataMS)*time.Millisecond)
+		}
+		ctx, cancel := context.WithTimeout(context.Background(), span)
+		j.cancel = cancel
+		j.done = make(chan sdkSessionCompletion, 1)
+		// A task receives immutable values and never touches owner state. The owner
+		// alone schedules the next step, journals results, and handles renew/cancel.
+		done, carriers, id, session, grant := j.done, j.carriers, j.identity, j.session, j.request.Control.Binding.ParentGrant.ID
+		go func() {
+			defer cancel()
+			result := sdkSessionCompletion{}
+			fresh, ref, code := s.identity(ctx, carriers)
+			if code == "" && (!sessionSame(id, fresh) || ref != session) {
+				code = ErrDenied
+			}
+			if code == "" {
+				r, _ := sessionRequest(carriers)
+				var e error
+				result.result, e = s.files.JobStep(ctx, r, id, grant, step)
+				code = sessionError(e)
+				if code == "" {
+					fresh, ref, code = s.identity(ctx, carriers)
+					if code == "" && (!sessionSame(id, fresh) || ref != session) {
+						code = ErrDenied
+					}
+				}
+			}
+			if code == "" && ctx.Err() != nil {
+				code = ErrTimeout
+			}
+			result.code = code
+			done <- result
+		}()
+	}
+	return ""
+}
+
+// Deny closes request lifetimes immediately, even if durable lifecycle fencing
+// is waiting on policy.lock. It does not claim cancellation durability or Q.
+func (s *sdkSessionJobs) deny() {
+	clear(s.pending)
+	for _, j := range s.jobs {
+		j.carriers = SessionCarriers{}
+		if j.cancel != nil {
+			j.cancel()
+		}
+	}
+}
+
+// Lifecycle fencing may already have disabled journal admission. Shutdown must
+// still close all local HTTP tasks. Retained pending/canceled entries reconcile
+// to interrupted; no claim about remote DSM Q is made by this local drain.
+func (s *sdkSessionJobs) shutdown(ctx context.Context) Code {
+	clear(s.pending)
+	for _, j := range s.jobs {
+		if !j.terminal {
+			_ = s.stop(j, ErrFenced)
+		}
+		j.carriers = SessionCarriers{}
+		if j.cancel != nil {
+			j.cancel()
+		}
+	}
+	for _, j := range s.jobs {
+		if j.done != nil {
+			select {
+			case <-j.done:
+				j.done = nil
+				j.cancel = nil
+			case <-ctx.Done():
+				return ErrCleanupRequired
+			}
+		}
+	}
+	return ""
+}
+func (s *sdkSessionJobs) owns(j *sdkSessionJob, id filestation.SessionIdentity) bool {
+	return sessionSame(j.identity, id)
+}
+func (s *sdkSessionJobs) dispatch(ctx context.Context, c SessionCarriers, method string, nonce string, args any) (any, Code) {
+	if !s.ready() {
+		return nil, ErrFenced
+	}
+	id, session, code := s.identity(ctx, c)
+	if code != "" {
+		return nil, code
+	}
+	if !s.ready() {
+		return nil, ErrFenced
+	}
+	admin := strings.HasPrefix(method, "jobs.admin.")
+	if admin && !id.Admin {
+		return nil, ErrDenied
+	}
+	if method == "jobs.status" || method == "jobs.admin.status" || method == "jobs.lookup" || method == "jobs.result" || method == "jobs.attach" || method == "jobs.diagnose" {
+		if code = s.budget(id); code != "" {
+			return nil, code
+		}
+	}
+	if method == "jobs.cancel" || method == "jobs.admin.cancel" || method == "jobs.revoke" {
+		if s.owner.grants.rpcNonces[nonce] {
+			return nil, ErrReplay
+		}
+		if len(s.owner.grants.rpcNonces) >= MaxReplayEntries {
+			return nil, ErrBusy
+		}
+		s.owner.grants.rpcNonces[nonce] = true
+	}
+	// This dispatch shares the owner's pinned inventory/peer/syntax gates. Session
+	// mode never falls through to native grants, POSIX workers or background jobs.
+	switch method {
+	case "jobs.prepare":
+		return s.prepare(ctx, c, id, session, *args.(*sdkPrepareArgs))
+	case "jobs.submit":
+		return s.submit(ctx, c, id, session, *args.(*sdkSubmitArgs))
+	case "jobs.attach":
+		p := args.(*sdkAttachArgs)
+		j := s.jobs[p.JobID]
+		if j == nil || !s.owns(j, id) || j.session != session || j.attach != p.AttachID {
+			return nil, ErrDenied
+		}
+		if j.terminal {
+			return nil, ErrExpired
+		}
+		if s.expired(j) {
+			if code = s.stop(j, ErrExpired); code != "" {
+				return nil, code
+			}
+			return nil, ErrExpired
+		}
+		if e := s.files.JobSelection(ctx, id, j.request.Control.Binding.ParentGrant.ID); e != nil {
+			if code = s.stop(j, ErrDenied); code != "" {
+				return nil, code
+			}
+			return nil, sessionError(e)
+		}
+		if s.expired(j) {
+			if code = s.stop(j, ErrExpired); code != "" {
+				return nil, code
+			}
+			return nil, ErrExpired
+		}
+		if !s.ready() {
+			return nil, ErrFenced
+		}
+		now := s.owner.attachNow()
+		j.deadline = now + sdkAttachTTL
+		j.last = now
+		j.carriers = c
+		return struct{}{}, ""
+	case "jobs.status", "jobs.admin.status":
+		return s.page(id, session, args.(*sdkStatusArgs).Cursor, admin)
+	case "jobs.lookup":
+		for _, j := range s.jobs {
+			if j.request.Control.Intent.ID == args.(*sdkLookupArgs).IntentID && s.owns(j, id) && j.session == session {
+				return s.display(j), ""
+			}
+		}
+		return nil, ErrDenied
+	case "jobs.result":
+		j := s.jobs[args.(*sdkResultArgs).JobID]
+		if j == nil || !s.owns(j, id) || j.session != session {
+			return nil, ErrDenied
+		}
+		if j.receipt.Job.State != jobcontract.Succeeded || !j.receipt.Job.Drained || j.receipt.Result == nil {
+			return nil, ErrUnavailable
+		}
+		if e := s.files.JobSelection(ctx, id, j.request.Control.Binding.ParentGrant.ID); e != nil {
+			return nil, sessionError(e)
+		}
+		return *j.receipt.Result, ""
+	case "jobs.cancel", "jobs.admin.cancel":
+		p := args.(*sdkCancelArgs)
+		j := s.jobs[p.JobID]
+		if j == nil || (!admin && (!s.owns(j, id) || j.session != session)) {
+			return nil, ErrDenied
+		}
+		if p.Revision != s.revision {
+			return nil, ErrStale
+		}
+		return struct{}{}, s.stop(j, ErrCanceled)
+	case "jobs.revoke":
+		return nil, ErrUnsupported // no offline delegation exists
+	case "jobs.diagnose":
+		return sdkJobDiagnostic{DiagnosticSchema: 1, Availability: "session-required", Jobs: []sdkDiagnosticJob{}}, ""
+	}
+	return nil, ErrUnsupported
+}
+func (s *sdkSessionJobs) display(j *sdkSessionJob) sdkJobDisplay {
+	r := j.receipt.Job
+	out := sdkJobDisplay{JobID: r.Binding.Job.ID, Revision: s.revision, Mode: jobcontract.Interactive, State: r.State, SafeReason: r.Reason, Progress: r.Progress, AcceptedAt: r.AcceptedAt, StartedAt: r.StartedAt, FinishedAt: r.FinishedAt, CancelRequested: r.CancelRequested, Drained: r.Drained, EffectsUnknown: r.EffectsUnknown, KnownEffects: jobcontract.Result{ResultSchema: 1}}
+	if j.receipt.Result != nil {
+		out.KnownEffects = *j.receipt.Result
+	}
+	return out
+}
+func (s *sdkSessionJobs) page(id filestation.SessionIdentity, session, cursor string, admin bool) (any, Code) {
+	now := s.owner.attachNow()
+	offset := 0
+	if cursor != "" {
+		p, ok := s.cursors[cursor]
+		if !ok || !sessionSame(p.identity, id) || p.session != session || p.admin != admin {
+			return nil, ErrDenied
+		}
+		if p.revision != s.revision || now >= p.expires || now < p.expires-IntentTTL {
+			return nil, ErrStale
+		}
+		offset = p.offset
+	}
+	items := []sdkJobDisplay{}
+	for _, j := range s.jobs {
+		if admin || s.owns(j, id) {
+			items = append(items, s.display(j))
+		}
+	}
+	for key, r := range s.history {
+		uid := strconv.FormatUint(uint64(r.Intent.Actor.UID), 10)
+		if !admin && (id.User != r.Intent.Actor.Username || id.UID != uid) {
+			continue
+		}
+		item := sdkRetainedDisplay(key, r)
+		item.Revision = s.revision
+		items = append(items, item)
+	}
+	sort.Slice(items, func(i, j int) bool { return items[i].JobID < items[j].JobID })
+	if offset > len(items) {
+		return nil, ErrStale
+	}
+	end := min(offset+jobcontract.MaxStatusJobs, len(items))
+	next := ""
+	if end < len(items) {
+		for key, p := range s.cursors {
+			if p.revision != s.revision || now >= p.expires {
+				delete(s.cursors, key)
+			}
+		}
+		if len(s.cursors) >= 256 {
+			return nil, ErrLimit
+		}
+		var code Code
+		next, code = sdkRandomRef()
+		if code != "" {
+			return nil, code
+		}
+		s.cursors[next] = sdkSessionCursor{id, session, admin, end, s.revision, now + IntentTTL}
+	}
+	page := sdkJobPage{Revision: s.revision, Items: items[offset:end], NextCursor: next}
+	if !admin {
+		return struct {
+			sdkJobPage
+			Availability string             `json:"availability"`
+			Workers      []sdkSessionWorker `json:"workers"`
+		}{page, "session-required", s.displayWorkers()}, ""
+	}
+	out := sdkAdminJobPage{Revision: s.revision, Items: []sdkAdminJobDisplay{}, NextCursor: next}
+	for _, j := range page.Items {
+		out.Items = append(out.Items, sdkAdminJobDisplay{j.JobID, j.Revision, j.State, j.SafeReason, j.CancelRequested, j.Drained, j.EffectsUnknown})
+	}
+	return out, ""
+}
+
+func (s *sdkSessionJobs) displayWorkers() []sdkSessionWorker {
+	out := []sdkSessionWorker{}
+	for _, w := range s.owner.workers {
+		interactive := false
+		for _, mode := range w.Modes {
+			if mode == jobcontract.Interactive {
+				interactive = true
+			}
+		}
+		if !interactive {
+			continue
+		}
+		actions := []jobcontract.Action{}
+		for _, action := range w.Actions {
+			if action == jobcontract.List || action == jobcontract.Stat || action == jobcontract.Read {
+				actions = append(actions, action)
+			}
+		}
+		if len(actions) == 0 {
+			continue
+		}
+		out = append(out, sdkSessionWorker{w.ID, w.Revision, actions, min(w.Limits.BoundedBytes, w.Limits.StreamBytes, uint64(filestation.MaxBytes))})
+	}
+	sort.Slice(out, func(i, j int) bool { return out[i].ID < out[j].ID })
+	return out
+}