@synopackageland/cli 0.4.1 → 0.5.0

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

@@ -0,0 +1,832 @@
+//go:build synopkgland_sdk_workers
+
+package helper
+
+import (
+	"bytes"
+	"context"
+	"crypto/sha256"
+	"dsmapp/internal/helper/jobcontract"
+	"encoding/hex"
+	"encoding/json"
+	"math"
+	"reflect"
+	"slices"
+	"sort"
+	"time"
+)
+
+// All methods belong to the SAME sole supervisor owner loop as sdkJobOwner.
+// Observations happen outside admission/storage locks. There is no goroutine,
+// scheduler service, dispatcher registration or production offline adapter.
+type sdkBackgroundPrepare struct {
+	Worker, Parent jobcontract.RevisionRef
+	Input          jobcontract.Input
+	TTL            time.Duration
+	NotBefore      time.Time
+}
+type sdkBackgroundProof struct {
+	Binding    jobcontract.Binding
+	Continuity ContinuityBinding
+	Continuous bool
+	CheckedAt  time.Time
+	Root       readOnlyRootWitness
+}
+type sdkBackgroundValidator interface {
+	ValidateBackground(context.Context, backgroundSnapshot, sdkJobRequest, Grant) (sdkBackgroundProof, Code)
+}
+type sdkBackgroundClock func() (time.Time, time.Duration, bool)
+type sdkBackgroundPending struct {
+	record         jobcontract.BackgroundRecord
+	request        sdkJobRequest
+	snapshot       backgroundSnapshot
+	proof          sdkBackgroundProof
+	mono, deadline time.Duration
+	wall           int64
+}
+type sdkBackgroundRuntime struct {
+	id                 string
+	snapshot           backgroundSnapshot
+	deadline, lastMono time.Duration
+	lastWall           int64
+	consumed           bool
+}
+type sdkBackgroundOwner struct {
+	jobs      *sdkJobOwner
+	observer  *backgroundObserver
+	validator sdkBackgroundValidator
+	journal   sdkRetainedJournal
+	clock     sdkBackgroundClock
+	lastUID   uint32
+}
+
+// The original consent actor in operation.actor is retained only for identity
+// indexing/UID quotas, never refreshed into a fabricated session proof. S7 must
+// use Snapshot and its distinct offline bootstrap to execute this reservation.
+type sdkBackgroundReservation struct {
+	Record    jobcontract.BackgroundRecord
+	Request   sdkJobRequest
+	Snapshot  backgroundSnapshot
+	Root      readOnlyRootWitness
+	operation *cohortOperation
+}
+
+func newSDKBackgroundOwner(o *sdkJobOwner, observer *backgroundObserver, v sdkBackgroundValidator, j sdkRetainedJournal, clock sdkBackgroundClock) (*sdkBackgroundOwner, Code) {
+	if o == nil || o.grants == nil || o.grants.authority == nil || j == nil || clock == nil {
+		return nil, ErrUnavailable
+	}
+	a := o.grants.authority
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	if a.sdkBackground != nil || a.sdkJobs != o {
+		return nil, ErrBusy
+	}
+	// Retained history must be fully readable before declaring the index complete.
+	if _, c := j.Records(); c != "" {
+		a.fenced = true
+		return nil, ErrCleanupRequired
+	}
+	b := &sdkBackgroundOwner{jobs: o, observer: observer, validator: v, journal: j, clock: clock}
+	if !reflect.ValueOf(o.services.Journal).Comparable() || !reflect.ValueOf(j).Comparable() || o.services.Journal != j {
+		return nil, ErrIncompatible
+	}
+	a.sdkBackground = b
+	return b, ""
+}
+func sdkPrincipal(a NativeActor) jobcontract.Principal {
+	return jobcontract.Principal{IdentityBasis: "uid-username", UID: a.UID(), Username: a.Username()}
+}
+func sdkIdentity(p jobcontract.Principal) RelaxedIdentity {
+	return RelaxedIdentity{UID: p.UID, Username: p.Username}
+}
+func sdkSnapshotMatchesActor(s backgroundSnapshot, a NativeActor) bool {
+	groups := a.Groups()
+	slices.Sort(groups)
+	groups = slices.Compact(groups)
+	return s.valid && a.valid && a.IdentityBasis() == "uid-username" && s.identity == relaxedActorIdentity(a) && s.gid == a.GID() && s.admin == a.Admin() && slices.Equal(groups, s.groups)
+}
+func (b *sdkBackgroundOwner) available() bool {
+	return b != nil && b.observer != nil && b.validator != nil && b.journal != nil && b.clock != nil
+}
+func (b *sdkBackgroundOwner) prepare(ctx context.Context, carriers SessionCarriers, in sdkBackgroundPrepare) (Intent, Code) {
+	if !b.available() {
+		return Intent{}, ErrUnavailable
+	}
+	a := b.jobs.grants.authority
+	if in.TTL == 0 {
+		in.TTL = 24 * time.Hour
+	}
+	if in.TTL <= 0 || in.TTL > 7*24*time.Hour || in.TTL%time.Millisecond != 0 {
+		return Intent{}, ErrLimit
+	}
+	w, ok := b.jobs.workers[in.Worker.ID]
+	if !ok || w.Revision != in.Worker.Revision {
+		return Intent{}, ErrIncompatible
+	}
+	if why := jobcontract.ValidatePlan(w, in.Input, jobcontract.Background); why != "" {
+		return Intent{}, sdkCode(why)
+	}
+	inputBytes, e := json.Marshal(in.Input)
+	if e != nil {
+		return Intent{}, ErrInvalid
+	}
+	input, why := jobcontract.DecodeInput(bytes.NewReader(inputBytes))
+	if why != "" {
+		return Intent{}, sdkCode(why)
+	}
+	ctx, cancel := context.WithTimeout(ctx, MetadataTimeout)
+	defer cancel()
+	actor, c := a.actor(ctx, carriers, nil)
+	if c != "" {
+		return Intent{}, c
+	}
+	if actor.IdentityBasis() != "uid-username" {
+		return Intent{}, ErrUnsupported
+	}
+	observation := b.observer.observe(ctx, relaxedActorIdentity(actor))
+	if observation.code != "" {
+		return Intent{}, observation.code
+	}
+	if !sdkSnapshotMatchesActor(observation.snapshot, actor) {
+		return Intent{}, ErrStale
+	}
+	g, c := a.grantForActor(actor, DataRequest{GrantID: in.Parent.ID, GrantRevision: in.Parent.Revision, Op: Action(input.Steps[0].Action)})
+	if c != "" {
+		return Intent{}, c
+	}
+	wall, mono, known := b.clock()
+	if !known || wall.UnixMilli() <= 0 || mono < 0 {
+		return Intent{}, ErrUnavailable
+	}
+	notBefore := in.NotBefore
+	if notBefore.IsZero() {
+		notBefore = wall
+	}
+	if notBefore.UnixMilli() < wall.UnixMilli() || !notBefore.Before(wall.Add(in.TTL)) {
+		return Intent{}, ErrInvalid
+	}
+	ids := make([]string, 5)
+	for n := range ids {
+		ids[n], c = randomGrantID()
+		if c != "" {
+			return Intent{}, c
+		}
+	}
+	digest, why := jobcontract.InputDigest(input, w.InputSchemaDigest)
+	if why != "" {
+		return Intent{}, sdkCode(why)
+	}
+	binding := jobcontract.Binding{Inventory: sdkInventory(a.policy.Inventory), JobSchema: 1, Epoch: a.policy.Epoch, Job: jobcontract.RevisionRef{ID: ids[0], Revision: 1}, Worker: in.Worker, ParentGrant: in.Parent, ApprovalBinding: a.policy.ApprovalBinding, CapabilityDigest: a.policy.CapabilityDigest, InputSchemaDigest: w.InputSchemaDigest, InputDigest: digest, Mode: jobcontract.Background, Delegation: &jobcontract.RevisionRef{ID: ids[1], Revision: 1}}
+	request := sdkJobRequest{Control: jobcontract.Control{Op: "jobs.submit", Binding: binding, Intent: jobcontract.RevisionRef{ID: ids[2], Revision: 1}, Nonce: ids[3], Ticket: ids[4]}, Input: input}
+	record := jobcontract.BackgroundRecord{BackgroundSchema: 2, Binding: jobcontract.PrivateBinding{Binding: binding, Actor: sdkPrincipal(actor)}, Issuer: sdkPrincipal(actor), CreatedAt: uint64(wall.UnixMilli()), ExpiresAt: uint64(wall.Add(in.TTL).UnixMilli()), NotBefore: uint64(notBefore.UnixMilli()), State: "active"}
+	if why := jobcontract.ValidateBackground(record); why != "" {
+		return Intent{}, sdkCode(why)
+	}
+	proof, c := b.validateProof(ctx, observation.snapshot, request, g, nil)
+	if c != "" {
+		return Intent{}, c
+	}
+	actor, c = a.actor(ctx, carriers, &actor)
+	if c != "" {
+		return Intent{}, c
+	}
+	pending := &sdkBackgroundPending{record: record, request: request, snapshot: observation.snapshot, proof: proof, mono: mono, deadline: mono + in.TTL, wall: wall.UnixMilli()}
+	if pending.deadline < mono {
+		return Intent{}, ErrLimit
+	}
+	raw, _ := json.Marshal(struct {
+		Record     jobcontract.BackgroundRecord
+		Request    sdkJobRequest
+		Continuity ContinuityBinding
+		GID        uint32
+		Groups     []uint32
+		Admin      bool
+	}{record, request, proof.Continuity, observation.snapshot.gid, observation.snapshot.groups, observation.snapshot.admin})
+	sum := sha256.Sum256(raw)
+	intent := Intent{ID: ids[2], Inventory: a.policy.Inventory, Epoch: a.policy.Epoch, SubjectRef: actor.Principal().SubjectRef, SessionRef: actor.SessionRef(), CandidateID: g.ID, ScopeKind: g.Scope.Kind, SummaryDigest: hex.EncodeToString(sum[:]), ExpiresAt: wall.Add(IntentTTL).UnixMilli()}
+	for _, s := range input.Steps {
+		if !slices.Contains(intent.Actions, Action(s.Action)) {
+			intent.Actions = append(intent.Actions, Action(s.Action))
+		}
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	c = a.transaction(func(s *GrantStore) (bool, Code) {
+		if c := b.checkConsentLocked(ctx, actor, pending, s); c != "" {
+			return false, c
+		}
+		now := a.now()
+		count := 0
+		for id, p := range a.intents {
+			if now.UnixMilli() >= p.intent.ExpiresAt {
+				delete(a.intents, id)
+			} else if p.intent.SubjectRef == intent.SubjectRef {
+				count++
+			}
+		}
+		if count >= MaxLiveIntents || len(a.intents) >= MaxReplayEntries {
+			return false, ErrBusy
+		}
+		if _, exists := a.intents[intent.ID]; exists {
+			return false, ErrReplay
+		}
+		a.intents[intent.ID] = pendingConsent{intent: intent, actor: actor, background: pending}
+		return false, ""
+	})
+	if c != "" {
+		return Intent{}, c
+	}
+	intent.Actions = slices.Clone(intent.Actions)
+	return intent, ""
+}
+func (b *sdkBackgroundOwner) validateProof(ctx context.Context, snapshot backgroundSnapshot, r sdkJobRequest, g Grant, root readOnlyRootWitness) (sdkBackgroundProof, Code) {
+	if b.validator == nil {
+		return sdkBackgroundProof{}, ErrUnavailable
+	}
+	oldest := snapshot.checkedAt
+	seen := map[RelaxedIdentity]bool{snapshot.identity: true}
+	for _, principal := range []Principal{g.Owner, g.Issuer} {
+		if principal.IdentityBasis != "uid-username" {
+			return sdkBackgroundProof{}, ErrSuspended
+		}
+		identity := relaxedPrincipalIdentity(principal)
+		if seen[identity] {
+			continue
+		}
+		seen[identity] = true
+		// The shared issuer is a separate authority, not the beneficiary. Its
+		// current offline observation cannot be inferred from the actor's proof.
+		observation := b.observer.observe(ctx, identity)
+		if observation.revoke {
+			if c := b.invalidateIdentities(ctx, observation.identities); c != "" {
+				return sdkBackgroundProof{}, ErrCleanupRequired
+			}
+		}
+		if observation.code != "" {
+			return sdkBackgroundProof{}, observation.code
+		}
+		if observation.snapshot.checkedAt.Before(oldest) {
+			oldest = observation.snapshot.checkedAt
+		}
+	}
+	request, c := cloneSDKRequest(r)
+	if c != "" {
+		return sdkBackgroundProof{}, c
+	}
+	snapshot.groups = slices.Clone(snapshot.groups)
+	p, c := b.validator.ValidateBackground(ctx, snapshot, request, cloneAuthorityGrant(g))
+	if c = nativeObservationCode(ctx, c); c != "" {
+		return p, c
+	}
+	if jobcontract.CompareBinding(p.Binding, r.Control.Binding) != "" || !nativeFresh(p.CheckedAt, b.jobs.grants.authority.now()) || !p.Continuous || p.Continuity != g.LastValidated || p.Root == nil {
+		return p, ErrSuspended
+	}
+	if oldest.Before(p.CheckedAt) {
+		p.CheckedAt = oldest
+	}
+	if !nativeFresh(p.CheckedAt, b.jobs.grants.authority.now()) {
+		return p, ErrStale
+	}
+	if root != nil && !root.sameReadOnlyRoot(p.Root) {
+		return p, ErrSuspended
+	}
+	return p, ""
+}
+func (b *sdkBackgroundOwner) parentLocked(s *GrantStore, r jobcontract.BackgroundRecord, in jobcontract.Input, p sdkBackgroundProof) Code {
+	g := findGrant(s, r.Binding.Binding.ParentGrant.ID)
+	if g == nil {
+		return ErrDenied
+	}
+	bind := r.Binding.Binding
+	if g.State != GrantActive {
+		return ErrRevoked
+	}
+	if g.Revision != bind.ParentGrant.Revision || g.Inventory != b.jobs.grants.authority.policy.Inventory || g.ApprovalBinding != bind.ApprovalBinding || g.CapabilityDigest != bind.CapabilityDigest || g.LastValidated.Epoch != bind.Epoch {
+		return ErrStale
+	}
+	if g.Scope.Kind == ScopePersonal && (g.Owner.IdentityBasis != "uid-username" || relaxedPrincipalIdentity(g.Owner) != sdkIdentity(r.Binding.Actor)) {
+		return ErrDenied
+	}
+	if !p.Continuous || g.LastValidated != p.Continuity {
+		return ErrSuspended
+	}
+	for _, step := range in.Steps {
+		if !Action(step.Action).ReadOnly() || !slices.Contains(g.Actions, Action(step.Action)) {
+			return ErrDenied
+		}
+	}
+	return ""
+}
+func (b *sdkBackgroundOwner) checkConsentLocked(ctx context.Context, actor NativeActor, p *sdkBackgroundPending, s *GrantStore) Code {
+	now, mono, known := b.clock()
+	if !known || mono < p.mono || now.UnixMilli() < p.wall {
+		return ErrSuspended
+	}
+	if now.UnixMilli() >= p.wall+IntentTTL.Milliseconds() || mono-p.mono >= IntentTTL || mono >= p.deadline || now.UnixMilli() >= int64(p.record.ExpiresAt) {
+		return ErrExpired
+	}
+	if c := nativeContextCode(ctx); c != "" {
+		return c
+	}
+	if !nativeFresh(actor.account.CheckedAt, now) || !nativeFresh(p.snapshot.checkedAt, now) || !nativeFresh(p.proof.CheckedAt, now) {
+		return ErrStale
+	}
+	if s.Schema != 2 {
+		return ErrIncompatible
+	}
+	if c := b.parentLocked(s, p.record, p.request.Input, p.proof); c != "" {
+		return c
+	}
+	if len(s.Grants)+len(s.Background) >= MaxGrants || s.Revision == math.MaxUint64 {
+		return ErrLimit
+	}
+	if c := b.pendingCapacityLocked(p.record.Binding.Actor.UID); c != "" {
+		return c
+	}
+	return ""
+}
+func (b *sdkBackgroundOwner) pendingCapacityLocked(uid uint32) Code {
+	total, own := 0, 0
+	for _, j := range b.jobs.jobs {
+		if j.background != nil && !j.background.consumed && j.failure == "" && !j.terminal {
+			total++
+			if j.background.snapshot.identity.UID == uid {
+				own++
+			}
+		}
+	}
+	if total >= jobcontract.MaxPending || own >= jobcontract.MaxUIDPending {
+		return ErrBusy
+	}
+	if len(b.jobs.jobs) >= jobcontract.MaxExecutionKeys || len(b.jobs.controls) >= 3*jobcontract.MaxMutationControls {
+		return ErrLimit
+	}
+	return ""
+}
+func (b *sdkBackgroundOwner) confirm(ctx context.Context, carriers SessionCarriers, id, summary string, revision uint64) (jobcontract.BackgroundRecord, Code) {
+	empty := jobcontract.BackgroundRecord{}
+	if !b.available() {
+		return empty, ErrUnavailable
+	}
+	a := b.jobs.grants.authority
+	a.mu.Lock()
+	pending, ok := a.intents[id]
+	fenced := a.fenced
+	if ok && pending.background != nil {
+		wall, mono, known := b.clock()
+		if !known || wall.UnixMilli() >= pending.intent.ExpiresAt || mono-pending.background.mono >= IntentTTL {
+			delete(a.intents, id)
+			a.mu.Unlock()
+			return empty, ErrExpired
+		}
+	}
+	a.mu.Unlock()
+	if fenced {
+		return empty, ErrFenced
+	}
+	if !ok || pending.background == nil {
+		return empty, ErrReplay
+	}
+	if summary != pending.intent.SummaryDigest {
+		return empty, ErrDenied
+	}
+	ctx, cancel := context.WithTimeout(ctx, MetadataTimeout)
+	defer cancel()
+	actor, c := a.actor(ctx, carriers, &pending.actor)
+	if c != "" {
+		return empty, c
+	}
+	old := pending.background
+	observation := b.observer.revalidate(ctx, old.snapshot)
+	if observation.code != "" {
+		return empty, observation.code
+	}
+	if !sdkSnapshotMatchesActor(observation.snapshot, actor) {
+		return empty, ErrStale
+	}
+	g, c := a.grantForActor(actor, DataRequest{GrantID: old.record.Binding.Binding.ParentGrant.ID, GrantRevision: old.record.Binding.Binding.ParentGrant.Revision, Op: Action(old.request.Input.Steps[0].Action)})
+	if c != "" {
+		return empty, c
+	}
+	proof, c := b.validateProof(ctx, observation.snapshot, old.request, g, old.proof.Root)
+	if c != "" {
+		return empty, c
+	}
+	actor, c = a.actor(ctx, carriers, &actor)
+	if c != "" {
+		return empty, c
+	}
+	current := *old
+	current.snapshot = observation.snapshot
+	current.proof = proof
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	c = a.transaction(func(s *GrantStore) (bool, Code) {
+		latest, exists := a.intents[id]
+		if !exists || latest.background != old {
+			return false, ErrReplay
+		}
+		if s.Revision != revision {
+			return false, ErrStale
+		}
+		return false, b.checkConsentLocked(ctx, actor, &current, s)
+	})
+	if c != "" {
+		return empty, c
+	}
+	r := current.request
+	ctrl := r.Control
+	if b.jobs.jobs[ctrl.Binding.Job.ID] != nil || b.jobs.controls["n:"+ctrl.Nonce] || b.jobs.controls["t:"+ctrl.Ticket] || b.jobs.controls["i:"+ctrl.Intent.ID] {
+		return empty, ErrReplay
+	}
+	// Burn before any durable write. A lost reply or orphan journal never obtains
+	// a second key. All interactive/background jobs share these tables/caps.
+	delete(a.intents, id)
+	b.jobs.controls["n:"+ctrl.Nonce] = true
+	b.jobs.controls["t:"+ctrl.Ticket] = true
+	b.jobs.controls["i:"+ctrl.Intent.ID] = true
+	runtime := &sdkBackgroundRuntime{id: current.record.Binding.Binding.Delegation.ID, snapshot: current.snapshot, deadline: current.deadline, lastMono: current.mono, lastWall: current.wall}
+	j := &sdkJob{request: r, worker: b.jobs.workers[ctrl.Binding.Worker.ID], actor: actor, root: proof.Root, background: runtime, receipt: sdkJobReceipt{Job: jobcontract.Job{Binding: ctrl.Binding, State: jobcontract.Pending, AcceptedAt: current.record.CreatedAt, Progress: jobcontract.Progress{Phase: "starting"}}}}
+	b.jobs.jobs[ctrl.Binding.Job.ID] = j
+	intent := sdkJobIntent{Request: r, Actor: current.record.Binding.Actor} // NO session/carrier
+	if c = b.journal.Reserve(intent); c != "" {
+		b.fenceLocked(j, c)
+		return empty, c
+	}
+	c = a.transaction(func(s *GrantStore) (bool, Code) {
+		// This job itself now occupies pending capacity, so only validate authority,
+		// proof and clocks again; limits were checked under this same owner lock.
+		now, mono, known := b.clock()
+		if !known || mono < current.mono || now.UnixMilli() < current.wall {
+			return false, ErrSuspended
+		}
+		if now.UnixMilli() >= pending.intent.ExpiresAt || mono-current.mono >= IntentTTL {
+			return false, ErrExpired
+		}
+		if !nativeFresh(actor.account.CheckedAt, now) || !nativeFresh(proof.CheckedAt, now) || !nativeFresh(current.snapshot.checkedAt, now) {
+			return false, ErrStale
+		}
+		if c := nativeContextCode(ctx); c != "" {
+			return false, c
+		}
+		if s.Revision != revision {
+			return false, ErrStale
+		}
+		if s.Revision == math.MaxUint64 || len(s.Grants)+len(s.Background) >= MaxGrants {
+			return false, ErrLimit
+		}
+		if c := b.parentLocked(s, current.record, r.Input, proof); c != "" {
+			return false, c
+		}
+		if findBackground(s, runtime.id) != nil || findGrant(s, runtime.id) != nil {
+			return false, ErrReplay
+		}
+		s.Background = append(s.Background, cloneSDKBackgrounds([]jobcontract.BackgroundRecord{current.record})[0])
+		s.Revision++
+		return true, ""
+	})
+	if c != "" {
+		b.fenceLocked(j, c)
+		return empty, c
+	}
+	return cloneSDKBackgrounds([]jobcontract.BackgroundRecord{current.record})[0], ""
+}
+func (b *sdkBackgroundOwner) fenceLocked(j *sdkJob, c Code) {
+	a := b.jobs.grants.authority
+	a.fenced = true
+	clear(a.intents)
+	if a.gate != nil {
+		a.gate.fenceLocked("sdk-background-cleanup-required")
+	}
+	for _, job := range b.jobs.jobs {
+		b.jobs.reject(job, ErrCleanupRequired)
+	}
+	if j != nil {
+		j.journalUncertain = true
+		b.jobs.uncertain(j)
+	}
+}
+func (b *sdkBackgroundOwner) job(id string) *sdkJob {
+	for _, j := range b.jobs.jobs {
+		if j.background != nil && j.background.id == id {
+			return j
+		}
+	}
+	return nil
+}
+func (b *sdkBackgroundOwner) clockCheck(j *sdkJob, r jobcontract.BackgroundRecord) Code {
+	wall, mono, known := b.clock()
+	rt := j.background
+	if !known || mono < rt.lastMono || wall.UnixMilli() < rt.lastWall {
+		return ErrSuspended
+	}
+	if wall.UnixMilli() >= int64(r.ExpiresAt) || mono >= rt.deadline {
+		return ErrExpired
+	}
+	rt.lastMono = mono
+	rt.lastWall = wall.UnixMilli()
+	return ""
+}
+
+// Read original immutable input from retained storage on each use. An orphan,
+// corrupted journal or another job's key can never dispatch from memory alone.
+func (b *sdkBackgroundOwner) check(ctx context.Context, j *sdkJob) (jobcontract.BackgroundRecord, sdkBackgroundProof, Code) {
+	var record jobcontract.BackgroundRecord
+	var parent Grant
+	var proof sdkBackgroundProof
+	if j == nil || j.background == nil {
+		return record, proof, ErrDenied
+	}
+	if j.failure != "" {
+		return record, proof, j.failure
+	}
+	a := b.jobs.grants.authority
+	a.mu.Lock()
+	c := a.transaction(func(s *GrantStore) (bool, Code) {
+		r := findBackground(s, j.background.id)
+		if r == nil {
+			return false, ErrDenied
+		}
+		record = cloneSDKBackgrounds([]jobcontract.BackgroundRecord{*r})[0]
+		g := findGrant(s, r.Binding.Binding.ParentGrant.ID)
+		if g == nil {
+			return false, ErrDenied
+		}
+		parent = cloneAuthorityGrant(*g)
+		return false, ""
+	})
+	a.mu.Unlock()
+	if c != "" {
+		return record, proof, c
+	}
+	if record.State != "active" && record.State != "consumed" {
+		return record, proof, ErrRevoked
+	}
+	if c := b.clockCheck(j, record); c != "" {
+		return record, proof, c
+	}
+	records, c := b.journal.Records()
+	if c != "" {
+		a.mu.Lock()
+		b.fenceLocked(j, c)
+		a.mu.Unlock()
+		return record, proof, ErrCleanupRequired
+	}
+	found := false
+	for _, r := range records {
+		if r.Intent.Request.Control.Binding.Job.ID == j.request.Control.Binding.Job.ID {
+			if r.State != "pending" || !reflect.DeepEqual(r.Intent.Request, j.request) || r.Intent.Actor != record.Binding.Actor || r.Intent.SessionRef != "" {
+				return record, proof, ErrCleanupRequired
+			}
+			found = true
+		}
+	}
+	if !found {
+		return record, proof, ErrCleanupRequired
+	}
+	if !b.available() {
+		return record, proof, ErrUnavailable
+	}
+	observation := b.observer.revalidate(ctx, j.background.snapshot)
+	if observation.revoke {
+		if c := b.invalidateIdentities(ctx, observation.identities); c != "" {
+			return record, proof, ErrCleanupRequired
+		}
+	}
+	if observation.code != "" {
+		return record, proof, observation.code
+	}
+	proof, c = b.validateProof(ctx, observation.snapshot, j.request, parent, j.root)
+	if c != "" {
+		return record, proof, c
+	}
+	j.background.snapshot = observation.snapshot
+	return record, proof, ""
+}
+func (b *sdkBackgroundOwner) executionCapacityLocked(uid uint32) Code {
+	c := b.jobs.grants.cohort
+	own, totalBG, ownBG := 0, 0, 0
+	for id, op := range c.operations {
+		if op.actor.UID() == uid {
+			own++
+		}
+		if j := b.jobs.jobs[id]; j != nil && j.background != nil {
+			totalBG++
+			if j.background.snapshot.identity.UID == uid {
+				ownBG++
+			}
+		}
+	}
+	if len(c.operations) >= jobcontract.MaxChildren || own >= jobcontract.MaxUIDChildren || totalBG >= jobcontract.MaxBackgroundChildren || ownBG >= jobcontract.MaxUIDBackgroundChildren {
+		return ErrBusy
+	}
+	return ""
+}
+
+// Consume and reserve only. S3 deliberately never calls launchReserved for a
+// background record. S7 must add explicit offline bootstrap/lease assembly.
+func (b *sdkBackgroundOwner) consume(ctx context.Context, id string) (sdkBackgroundReservation, Code) {
+	var result sdkBackgroundReservation
+	j := b.job(id)
+	if j == nil {
+		return result, ErrDenied
+	}
+	if j.background.consumed {
+		return result, ErrReplay
+	}
+	ctx, cancel := context.WithTimeout(ctx, MetadataTimeout)
+	defer cancel()
+	r, p, c := b.check(ctx, j)
+	if c != "" {
+		if c == ErrFenced {
+			b.observerFenced()
+			return result, c
+		}
+		b.invalidateJob(ctx, j, c)
+		return result, c
+	}
+	a := b.jobs.grants.authority
+	cohort := b.jobs.grants.cohort
+	a.mu.Lock()
+	c = a.transaction(func(s *GrantStore) (bool, Code) {
+		current := findBackground(s, id)
+		if current == nil || current.State != "active" || current.Binding.Binding.Delegation.Revision != r.Binding.Binding.Delegation.Revision {
+			return false, ErrReplay
+		}
+		if c := b.clockCheck(j, *current); c != "" {
+			return false, c
+		}
+		now := a.now()
+		if now.UnixMilli() < int64(current.NotBefore) {
+			return false, ErrBusy
+		}
+		if c := nativeContextCode(ctx); c != "" {
+			return false, c
+		}
+		if !nativeFresh(j.background.snapshot.checkedAt, now) || !nativeFresh(p.CheckedAt, now) {
+			return false, ErrStale
+		}
+		if c := b.parentLocked(s, *current, j.request.Input, p); c != "" {
+			return false, c
+		}
+		if !cohort.allowed() {
+			return false, ErrFenced
+		}
+		if c := b.executionCapacityLocked(current.Binding.Actor.UID); c != "" {
+			return false, c
+		}
+		if len(cohort.seen) >= 2*MaxReplayEntries {
+			return false, ErrBusy
+		}
+		ctrl := j.request.Control
+		binding := operationBinding{cohort.inventory, cohort.epoch, ctrl.Binding.Job.ID, ctrl.Nonce, ctrl.Binding.ParentGrant.ID, ctrl.Binding.ParentGrant.Revision}
+		if !cohort.bound(binding) || cohort.seen["op:"+binding.OperationID] || cohort.seen["nonce:"+binding.Nonce] {
+			return false, ErrReplay
+		}
+		if current.Binding.Binding.Delegation.Revision == math.MaxUint64 || s.Revision == math.MaxUint64 {
+			return false, ErrLimit
+		}
+		current.State = "consumed"
+		current.ExecutionKey = ctrl.Intent.ID
+		current.Binding.Binding.Delegation.Revision++
+		s.Revision++
+		// Same operation table and burned-key window; no second slot pool.
+		op := &cohortOperation{binding: binding, actor: j.actor, admittedAt: now, lastActivity: now, maxBytes: j.worker.Limits.StreamBytes, work: &readOnlyWork{Action: ActionReadStream}}
+		cohort.operations[binding.OperationID] = op
+		cohort.seen["op:"+binding.OperationID] = true
+		cohort.seen["nonce:"+binding.Nonce] = true
+		j.op = op
+		j.background.consumed = true
+		result = sdkBackgroundReservation{Record: cloneSDKBackgrounds([]jobcontract.BackgroundRecord{*current})[0], Request: j.request, Snapshot: j.background.snapshot, Root: p.Root, operation: op}
+		return true, ""
+	})
+	if c != "" && j.op != nil {
+		b.fenceLocked(j, c)
+	}
+	a.mu.Unlock()
+	if c != "" && c != ErrBusy {
+		if c == ErrFenced {
+			b.observerFenced()
+			return result, c
+		}
+		b.invalidateJob(ctx, j, c)
+	}
+	if c == "" {
+		result.Request, _ = cloneSDKRequest(result.Request)
+		result.Snapshot.groups = slices.Clone(result.Snapshot.groups)
+	}
+	return result, c
+}
+
+// Latch denial before durable R; Q comes from the same cohort, never from the
+// absence of a session, a signal or journal success. Used for expiry/unknowns.
+func (b *sdkBackgroundOwner) invalidateJob(ctx context.Context, j *sdkJob, why Code) Code {
+	if j == nil {
+		return ErrDenied
+	}
+	a := b.jobs.grants.authority
+	a.mu.Lock()
+	b.jobs.reject(j, why)
+	c := a.transaction(func(s *GrantStore) (bool, Code) {
+		r := findBackground(s, j.background.id)
+		if r == nil {
+			return false, ErrDenied
+		}
+		if r.State != "active" && r.State != "consumed" {
+			return false, ""
+		}
+		if r.Binding.Binding.Delegation.Revision == math.MaxUint64 || s.Revision == math.MaxUint64 {
+			return false, ErrLimit
+		}
+		r.State = "revoked"
+		r.Reason = jobcontract.SafeReason(ErrRevoked)
+		if why == ErrSuspended || why == ErrUnavailable || why == ErrStale {
+			r.State = "suspended"
+			r.Reason = jobcontract.SafeReason(ErrSuspended)
+		}
+		if why == ErrExpired {
+			r.State = "expired"
+			r.Reason = jobcontract.SafeReason(ErrExpired)
+		}
+		r.Binding.Binding.Delegation.Revision++
+		s.Revision++
+		return true, ""
+	})
+	if c != "" {
+		b.fenceLocked(j, c)
+	}
+	// Keep a durable canceled journal even for jobs that never reserved a child.
+	jc := b.journal.Cancel(j.request.Control.Binding)
+	if jc != "" {
+		b.fenceLocked(j, jc)
+	}
+	a.mu.Unlock()
+	drainCtx, cancel := context.WithTimeout(ctx, RevokeDrainTimeout)
+	defer cancel()
+	err := b.jobs.grants.cohort.drainSelected(drainCtx, TerminateGrace, func(op *cohortOperation) bool { return op == j.op })
+	if c != "" || jc != "" || err != nil {
+		a.mu.Lock()
+		b.fenceLocked(j, ErrCleanupRequired)
+		a.mu.Unlock()
+		return ErrCleanupRequired
+	}
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	return b.finishRevokedLocked(j)
+}
+
+// Bounded, UID-round-robin ready list. It grants no authority and never spawns;
+// consume revalidates the whole binding and clocks under the admission order.
+func (b *sdkBackgroundOwner) ready(ctx context.Context) ([]string, Code) {
+	ids := []string{}
+	for _, j := range b.jobs.jobs {
+		if j.background == nil || j.background.consumed || j.failure != "" || j.terminal {
+			continue
+		}
+		r, _, c := b.check(ctx, j)
+		if c != "" {
+			if c == ErrFenced {
+				b.observerFenced()
+				return nil, c
+			}
+			if d := b.invalidateJob(ctx, j, c); d != "" {
+				return nil, d
+			}
+			continue
+		}
+		if b.jobs.grants.authority.now().UnixMilli() >= int64(r.NotBefore) {
+			ids = append(ids, j.background.id)
+		}
+	}
+	sort.Slice(ids, func(i, j int) bool {
+		a, c := b.job(ids[i]).background.snapshot.identity.UID, b.job(ids[j]).background.snapshot.identity.UID
+		if a == c {
+			return ids[i] < ids[j]
+		}
+		if (a > b.lastUID) != (c > b.lastUID) {
+			return a > b.lastUID
+		}
+		return a < c
+	})
+	// Interleave each UID's first item before its second item.
+	out := []string{}
+	seen := map[uint32]bool{}
+	rest := []string{}
+	for _, id := range ids {
+		uid := b.job(id).background.snapshot.identity.UID
+		if seen[uid] {
+			rest = append(rest, id)
+		} else {
+			seen[uid] = true
+			out = append(out, id)
+		}
+	}
+	out = append(out, rest...)
+	if len(out) > jobcontract.MaxPending {
+		out = out[:jobcontract.MaxPending]
+	}
+	if len(out) > 0 {
+		b.lastUID = b.job(out[0]).background.snapshot.identity.UID
+	}
+	return out, ""
+}