@synopackageland/cli 0.3.10 → 0.4.1

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

@@ -0,0 +1,389 @@
+package helper
+
+import (
+	"bytes"
+	"context"
+	"encoding/json"
+	"slices"
+)
+
+type cohortReceipt struct {
+	binding operationBinding
+	bytes   uint64
+	write   *retiredWriteReceipt
+}
+
+func (c *operationCohort) retire(id string, op *cohortOperation) {
+	if c.receipts == nil {
+		c.receipts = map[string]cohortReceipt{}
+	}
+	receipt := cohortReceipt{binding: op.binding, bytes: op.bytes}
+	if op.writeWork != nil {
+		value, code, known := MutationReceipt{}, ErrCleanupRequired, false
+		if p, ok := op.process.(writeMutationProcess); ok {
+			value, code, known = p.mutationResult()
+		}
+		value.EffectsUnknown = !known
+		retired := *op
+		retired.process = nil
+		receipt.write = &retiredWriteReceipt{retired, value, code, !known}
+	}
+	c.receipts[id] = receipt
+	delete(c.operations, id)
+	c.reaped++
+}
+func (q GrantDrainProof) valid() bool {
+	return allReferences(q.Key.Epoch, q.Key.GrantID) && q.Key.Revision > 0 && q.Started <= MaxReplayEntries && q.Started == q.Reaped && q.AdmittedBytes <= MaxReplayEntries*MaxTransferBytes && q.BytesWritten <= q.AdmittedBytes && q.WriteOperations <= q.Started && q.PublishedOperations <= q.WriteOperations && q.CommittedOperations <= q.PublishedOperations && (!q.WriteEffectsUnknown || q.WriteOperations > 0)
+}
+
+// Sole supervisor owner/reaper only. This derives Q from S2's actual removal
+// condition (Wait4 + stopped relay/FDs), including operations previously polled.
+func (c *operationCohort) DrainGrant(ctx context.Context, key GrantDrainKey) (GrantQuiescence, Code) {
+	if key.Epoch != c.epoch || !allReferences(key.GrantID) || key.Revision == 0 {
+		return GrantQuiescence{}, ErrStale
+	}
+	if err := c.cancelGrant(ctx, key.GrantID, key.Revision); err != nil {
+		return GrantQuiescence{}, ErrCleanupRequired
+	}
+	if ctx.Err() != nil {
+		return GrantQuiescence{}, ErrCleanupRequired
+	}
+	for _, op := range c.operations {
+		if op.binding.GrantID == key.GrantID {
+			return GrantQuiescence{}, ErrCleanupRequired
+		}
+	}
+	proof := GrantDrainProof{Key: key}
+	for _, receipt := range c.receipts {
+		if receipt.binding.GrantID != key.GrantID {
+			continue
+		}
+		if receipt.binding.Epoch != key.Epoch || receipt.binding.GrantRevision >= key.Revision {
+			return GrantQuiescence{}, ErrStale
+		}
+		proof.Started++
+		proof.Reaped++
+		proof.AdmittedBytes += receipt.bytes
+		if receipt.write != nil {
+			proof.WriteOperations++
+			proof.BytesWritten += receipt.write.receipt.BytesWritten
+			if receipt.write.unknown || receipt.write.code == ErrCommitUncertain {
+				proof.WriteEffectsUnknown = true
+			}
+			if receipt.write.receipt.Published {
+				proof.PublishedOperations++
+			}
+			if receipt.write.receipt.Committed {
+				proof.CommittedOperations++
+			}
+		}
+	}
+	if !proof.valid() {
+		return GrantQuiescence{}, ErrCleanupRequired
+	}
+	return GrantQuiescence{Key: key, Cohort: &proof, ChildrenReaped: true, RelayClosed: true, LeasesClosed: true, FDsClosed: true, EffectsRecorded: true}, ""
+}
+
+type supervisorGrants struct {
+	authority                   *GrantAuthority
+	cohort                      *operationCohort
+	services                    supervisorGrantServices
+	tickets, nonces             map[string]bool // one bounded window/epoch, never evicted
+	streamTickets, streamNonces map[string]bool
+	streamRPCNonces             map[string]bool
+	rpcNonces                   map[string]bool
+}
+
+func newSupervisorGrants(repo GrantRepository, cohort *operationCohort, services supervisorGrantServices) (*supervisorGrants, Code) {
+	if cohort == nil || cohort.gate == nil {
+		return nil, ErrUnavailable
+	}
+	authority, code := NewGrantAuthority(repo, services.native, services.consent, cohort)
+	if code != "" {
+		return nil, code
+	}
+	if authority.policy.Inventory != cohort.inventory || authority.policy.Epoch != cohort.epoch {
+		return nil, ErrIncompatible
+	}
+	// Set before publishing the runtime; observer fencing and all grant mutations
+	// now share the SAME mutex. No helper-local or cross-process mutex claim.
+	authority.mu = &cohort.gate.mu
+	authority.gate = cohort.gate
+	authority.writes = services.writes
+	return &supervisorGrants{authority: authority, cohort: cohort, services: services, tickets: map[string]bool{}, nonces: map[string]bool{}, rpcNonces: map[string]bool{}, streamTickets: map[string]bool{}, streamNonces: map[string]bool{}, streamRPCNonces: map[string]bool{}}, ""
+}
+func (a *GrantAuthority) grantForActor(actor NativeActor, r DataRequest) (Grant, Code) {
+	a.mu.Lock()
+	defer a.mu.Unlock()
+	var result Grant
+	code := a.transaction(func(s *GrantStore) (bool, Code) {
+		g := findGrant(s, r.GrantID)
+		if g == nil {
+			return false, ErrDenied
+		}
+		if g.Scope.Kind == ScopePersonal && g.Owner != actor.Principal() {
+			return false, ErrDenied
+		}
+		if g.State == GrantRevoked {
+			return false, ErrRevoked
+		}
+		if g.Revision != r.GrantRevision {
+			return false, ErrStale
+		}
+		if g.State == GrantSuspended {
+			return false, ErrSuspended
+		}
+		if !slices.Contains(g.Actions, r.Op) {
+			return false, ErrDenied
+		}
+		result = cloneAuthorityGrant(*g)
+		return false, ""
+	})
+	return result, code
+}
+func (s *supervisorGrants) validate(ctx context.Context, carriers SessionCarriers, r DataRequest, old *NativeActor) (NativeActor, GrantUseValidation, Code) {
+	if code := validateOperationRequest(r, s.services.writes); code != "" {
+		return NativeActor{}, GrantUseValidation{}, code
+	}
+	if !r.Op.ReadOnly() && !s.services.writes.allows(r.Op) {
+		return NativeActor{}, GrantUseValidation{}, ErrUnsupported
+	}
+	if r.Inventory != s.cohort.inventory || r.Epoch != s.cohort.epoch {
+		return NativeActor{}, GrantUseValidation{}, ErrStale
+	}
+	actor, code := s.authority.actor(ctx, carriers, old)
+	if code != "" {
+		return NativeActor{}, GrantUseValidation{}, code
+	}
+	g, code := s.authority.grantForActor(actor, r)
+	if code != "" {
+		return NativeActor{}, GrantUseValidation{}, code
+	}
+	if s.services.operations == nil {
+		return NativeActor{}, GrantUseValidation{}, ErrUnavailable
+	}
+	proof, code := s.services.operations.ValidateOperation(ctx, actor, r, g)
+	if code = nativeObservationCode(ctx, code); code != "" {
+		return NativeActor{}, GrantUseValidation{}, code
+	}
+	actor, code = s.authority.actor(ctx, carriers, &actor)
+	if code != "" {
+		return NativeActor{}, GrantUseValidation{}, code
+	}
+	return actor, proof, ""
+}
+func (s *supervisorGrants) ticketLocked(r DataRequest, b TicketBinding, actor NativeActor) Code {
+	if b.Inventory != r.Inventory || b.Epoch != r.Epoch || b.SubjectRef != actor.Principal().SubjectRef || b.SessionRef != actor.SessionRef() || b.Action != r.Op || b.GrantID != r.GrantID || b.GrantRevision != r.GrantRevision || b.OperationID != r.OperationID || b.Nonce != r.Nonce || b.Ticket != r.Ticket || b.RequestDigest != r.Digest() {
+		return ErrDenied
+	}
+	now := s.authority.now()
+	if !now.Before(b.ExpiresAt) {
+		return ErrExpired
+	}
+	if b.ExpiresAt.Sub(now) > IntentTTL {
+		return ErrInvalid
+	}
+	if s.tickets[r.Ticket] || s.nonces[r.Nonce] || s.streamTickets[r.Ticket] || s.streamNonces[r.Nonce] {
+		return ErrReplay
+	}
+	full := len(s.tickets) >= MaxReplayEntries
+	if r.Op == ActionReadStream || r.Op == ActionWriteStream {
+		full = len(s.streamTickets) >= MaxStreamReplayEntries
+	}
+	if full {
+		return ErrBusy
+	}
+	return ""
+}
+func (s *supervisorGrants) burnTicket(r DataRequest) {
+	if r.Op == ActionReadStream || r.Op == ActionWriteStream {
+		s.streamTickets[r.Ticket] = true
+		s.streamNonces[r.Nonce] = true
+		return
+	}
+	s.tickets[r.Ticket] = true
+	s.nonces[r.Nonce] = true
+}
+func (s *supervisorGrants) start(ctx context.Context, peer operationPeer, carriers SessionCarriers, r DataRequest) Code {
+	if !r.Op.ReadOnly() {
+		return s.startWrite(ctx, peer, carriers, r)
+	}
+	if !s.cohort.peerAllowed(peer) {
+		return ErrDenied
+	}
+	actor, proof, code := s.validate(ctx, carriers, r, nil)
+	if code != "" {
+		return code
+	}
+	work, code := readOnlyRequestWork(r, proof.root)
+	if code != "" {
+		return code
+	}
+	binding := operationBinding{r.Inventory, r.Epoch, r.OperationID, r.Nonce, r.GrantID, r.GrantRevision}
+	var op *cohortOperation
+	code = s.authority.WithGrantAdmission(GrantAdmission{actor, r.GrantID, r.GrantRevision, r.Op, proof.Binding, proof.Continuous}, func(g Grant, a NativeActor) Code {
+		if ctx.Err() != nil {
+			return nativeContextCode(ctx)
+		}
+		if code := s.ticketLocked(r, proof.Ticket, a); code != "" {
+			return code
+		}
+		var code Code
+		op, code = s.cohort.reserveLocked(a, binding)
+		if code != "" {
+			return code
+		}
+		op.maxBytes = work.MaxBytes
+		op.segments = slices.Clone(work.Segments)
+		op.work = work
+		op.root = proof.root
+		s.burnTicket(r)
+		return ""
+	})
+	if code != "" {
+		return code
+	}
+	return s.cohort.launchReserved(op)
+}
+func (s *supervisorGrants) chunk(ctx context.Context, peer operationPeer, carriers SessionCarriers, r DataRequest) Code {
+	if !r.Op.ReadOnly() {
+		return s.writeControl(ctx, peer, carriers, r, false)
+	}
+	if !s.cohort.peerAllowed(peer) {
+		return ErrDenied
+	}
+	op := s.cohort.operations[r.OperationID]
+	if op == nil || op.binding.Inventory != r.Inventory || op.binding.Epoch != r.Epoch || op.binding.GrantID != r.GrantID || op.binding.GrantRevision != r.GrantRevision {
+		return ErrDenied
+	}
+	if op.canceled || op.process == nil {
+		return ErrCanceled
+	}
+	if op.expired(s.cohort.now()) {
+		op.canceled = true
+		op.process.stopRelay()
+		return ErrTimeout
+	}
+	actor, proof, code := s.validate(ctx, carriers, r, &op.actor)
+	if code != "" {
+		op.canceled = true
+		op.process.stopRelay()
+		return code
+	}
+	work, code := readOnlyRequestWork(r, proof.root)
+	if code != "" {
+		return code
+	}
+	if (r.Op != ActionRead && r.Op != ActionReadStream) || !sameReadOnlyRequest(op, work, proof.root, false) {
+		return ErrDenied
+	}
+	if work.MaxBytes > MaxChunkBytes {
+		return ErrLimit
+	}
+	if p, ok := op.process.(readOnlyMetadataProcess); ok {
+		if code := p.readOnlyLeaseReady(uint32(work.MaxBytes)); code != "" {
+			return code
+		}
+	}
+	code = s.authority.WithGrantAdmission(GrantAdmission{actor, r.GrantID, r.GrantRevision, r.Op, proof.Binding, proof.Continuous}, func(g Grant, a NativeActor) Code {
+		if ctx.Err() != nil {
+			return nativeContextCode(ctx)
+		}
+		if code := s.ticketLocked(r, proof.Ticket, a); code != "" {
+			return code
+		}
+		if code := s.cohort.reserveChunkLocked(op, a, uint32(work.MaxBytes)); code != "" {
+			return code
+		}
+		s.burnTicket(r)
+		return ""
+	})
+	if code != "" {
+		return code
+	}
+	return s.cohort.deliverChunk(op, uint32(work.MaxBytes))
+}
+
+// JSON-only, bounded decoded controls; no credential serialization here.
+func bytesReader(b json.RawMessage) *bytes.Reader { return bytes.NewReader(b) }
+
+// Nonblocking metadata polling on the SAME S3 owner/admission/ticket path.
+// Filesystem IO has already run in the actor child; metadata is never published
+// until fresh identity, grant, continuity, action, decoded args and ticket pass.
+func (s *supervisorGrants) result(ctx context.Context, peer operationPeer, carriers SessionCarriers, r DataRequest) (*readOnlyResult, Code) {
+	if !s.cohort.peerAllowed(peer) {
+		return nil, ErrDenied
+	}
+	op := s.cohort.operations[r.OperationID]
+	if op == nil || op.binding.Inventory != r.Inventory || op.binding.Epoch != r.Epoch || op.binding.GrantID != r.GrantID || op.binding.GrantRevision != r.GrantRevision {
+		return nil, ErrDenied
+	}
+	if op.canceled || op.process == nil {
+		return nil, ErrCanceled
+	}
+	if op.expired(s.cohort.now()) {
+		op.canceled = true
+		op.process.stopRelay()
+		return nil, ErrTimeout
+	}
+	actor, proof, code := s.validate(ctx, carriers, r, &op.actor)
+	if code != "" {
+		op.canceled = true
+		op.process.stopRelay()
+		return nil, code
+	}
+	work, code := readOnlyRequestWork(r, proof.root)
+	if code != "" {
+		return nil, code
+	}
+	if !sameReadOnlyRequest(op, work, proof.root, true) {
+		return nil, ErrDenied
+	}
+	p, ok := op.process.(readOnlyMetadataProcess)
+	if !ok {
+		return nil, ErrUnavailable
+	}
+	value, ready, err := p.readOnlyMetadata()
+	if err != nil {
+		op.canceled = true
+		op.process.stopRelay()
+		return nil, ErrCleanupRequired
+	}
+	if !ready {
+		return nil, ErrBusy
+	}
+	var result *readOnlyResult
+	code = s.authority.WithGrantAdmission(GrantAdmission{actor, r.GrantID, r.GrantRevision, r.Op, proof.Binding, proof.Continuous}, func(_ Grant, a NativeActor) Code {
+		if ctx.Err() != nil {
+			return nativeContextCode(ctx)
+		}
+		if op.canceled {
+			return ErrCanceled
+		}
+		if op.expired(s.cohort.now()) {
+			op.canceled = true
+			op.process.stopRelay()
+			return ErrTimeout
+		}
+		if code := s.ticketLocked(r, proof.Ticket, a); code != "" {
+			return code
+		}
+		result = cloneReadOnlyResult(value)
+		if result == nil {
+			return ErrUnavailable
+		}
+		op.actor = a
+		s.burnTicket(r)
+		return ""
+	})
+	if code != "" {
+		return nil, code
+	}
+	// Private completion ACK/IO stays outside grant/policy/admission locks.
+	if err := p.releaseReadOnlyMetadata(); err != nil {
+		op.canceled = true
+		op.process.stopRelay()
+		return nil, ErrCleanupRequired
+	}
+	return result, ""
+}

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

@@ -0,0 +1,239 @@
+package helper
+
+import (
+	"context"
+	"encoding/json"
+	"syscall"
+	"testing"
+	"time"
+)
+
+type grantOperationStub struct {
+	after func()
+	code  Code
+}
+
+func (v grantOperationStub) ValidateOperation(_ context.Context, a NativeActor, r DataRequest, g Grant) (GrantUseValidation, Code) {
+	if v.after != nil {
+		v.after()
+	}
+	return GrantUseValidation{Binding: g.LastValidated, Continuous: true, Ticket: TicketBinding{Inventory: r.Inventory, Epoch: r.Epoch, SubjectRef: a.Principal().SubjectRef, SessionRef: a.SessionRef(), Action: r.Op, GrantID: r.GrantID, GrantRevision: r.GrantRevision, OperationID: r.OperationID, Nonce: r.Nonce, Ticket: r.Ticket, RequestDigest: r.Digest(), ExpiresAt: a.account.CheckedAt.Add(IntentTTL)}}, v.code
+}
+func grantCohortFixture(t *testing.T) (*supervisorGrants, *memoryGrantRepository, *operationCohort, SessionCarriers, Grant, *[]*operationFixture) {
+	t.Helper()
+	a, r, p, _, _, consent, carriers, now := grantAuthorityFixture(t)
+	gate := newAdmission(Binding{Boot: "boot", Install: "install"})
+	gate.observe(gate.binding, 1, true, now)
+	children := new([]*operationFixture)
+	cohort := newOperationCohort(r.policy.Inventory, r.policy.Epoch, 42, gate, func() bool { return true })
+	cohort.now = func() time.Time { return now }
+	cohort.startChild = func(NativeActor, operationBinding) (operationProcess, error) {
+		child := &operationFixture{childFixture: childFixture{exitOn: syscall.SIGTERM}}
+		*children = append(*children, child)
+		return child, nil
+	}
+	runtime, code := newSupervisorGrants(r, cohort, supervisorGrantServices{native: p, consent: consent, operations: grantOperationStub{}})
+	if code != "" {
+		t.Fatal(code)
+	}
+	runtime.authority.now = a.now
+	grant := confirmGrant(t, runtime.authority, r, carriers, prepareGrant(t, runtime.authority, carriers, ScopePersonal))
+	return runtime, r, cohort, carriers, grant, children
+}
+func grantControl(t *testing.T, g Grant, op, nonce, ticket byte, n uint64) DataRequest {
+	t.Helper()
+	args, _ := json.Marshal(ReadArgs{Segments: []string{"fixture"}, MaxBytes: n})
+	return DataRequest{Inventory: g.Inventory, Op: ActionRead, Epoch: g.LastValidated.Epoch, GrantID: g.ID, GrantRevision: g.Revision, OperationID: grantRef(op), Nonce: grantRef(nonce), Ticket: grantRef(ticket), Args: args}
+}
+func TestGrantCohortReservationRevokeAndS2Proof(t *testing.T) {
+	runtime, r, c, carriers, g, children := grantCohortFixture(t)
+	request := grantControl(t, g, '1', '2', '3', MaxBoundedBytes)
+	if code := runtime.start(context.Background(), operationPeer{42, 0}, carriers, request); code != "" {
+		t.Fatal(code)
+	}
+	chunk := grantControl(t, g, '1', '4', '5', MaxChunkBytes)
+	if code := runtime.chunk(context.Background(), operationPeer{42, 0}, carriers, chunk); code != "" {
+		t.Fatal(code)
+	}
+	result, code := runtime.authority.Revoke(context.Background(), carriers, g.ID, 1, r.store.Revision)
+	if code != "" || !result.Revoked || !result.Drained || !(*children)[0].reaped || len(c.operations) != 0 {
+		t.Fatal(result, code)
+	}
+	if r.q.Cohort == nil || r.q.Cohort.Started != 1 || r.q.Cohort.Reaped != 1 || r.q.Cohort.AdmittedBytes != MaxChunkBytes {
+		t.Fatal("Q did not carry S2 proof", r.q)
+	}
+	if code := runtime.chunk(context.Background(), operationPeer{42, 0}, carriers, grantControl(t, g, '1', '6', '7', 1)); code == "" {
+		t.Fatal("lease after R")
+	}
+}
+func TestGrantCohortSharedFenceAndNoBootstrapInDiskLocks(t *testing.T) {
+	runtime, repo, cohort, carriers, g, children := grantCohortFixture(t)
+	if runtime.authority.mu != &cohort.gate.mu {
+		t.Fatal("independent ordering mutex")
+	}
+	original := cohort.startChild
+	cohort.startChild = func(a NativeActor, b operationBinding) (operationProcess, error) {
+		if repo.inTransaction {
+			t.Fatal("bootstrap while disk locks held")
+		}
+		cohort.gate.fence("during-bootstrap")
+		return original(a, b)
+	}
+	if code := runtime.start(context.Background(), operationPeer{42, 0}, carriers, grantControl(t, g, '1', '2', '3', 1)); code != ErrFenced {
+		t.Fatal(code)
+	}
+	if len(*children) != 1 || !(*children)[0].stopped || len((*children)[0].signals) != 0 {
+		t.Fatal("lost owned child or signalled before durable fence")
+	}
+
+}
+func TestGrantCohortPeerTicketAndGrantChecks(t *testing.T) {
+	for _, kind := range []string{"peer", "uid", "revision", "suspended", "fence", "ticket", "nil-validator", "replay"} {
+		t.Run(kind, func(t *testing.T) {
+			runtime, r, c, carriers, g, children := grantCohortFixture(t)
+			request := grantControl(t, g, '1', '2', '3', 1)
+			peer := operationPeer{42, 0}
+			switch kind {
+			case "peer":
+				peer.PID++
+			case "uid":
+				peer.UID++
+			case "revision":
+				request.GrantRevision++
+			case "suspended":
+				r.store.Grants[0].State = GrantSuspended
+				r.store.Grants[0].Reason = ErrSuspended
+			case "fence":
+				c.gate.fence("test")
+			case "ticket":
+				runtime.services.operations = grantOperationStub{code: ErrDenied}
+			case "nil-validator":
+				runtime.services.operations = nil
+			case "replay":
+				if code := runtime.start(context.Background(), peer, carriers, request); code != "" {
+					t.Fatal(code)
+				}
+			}
+			before := len(*children)
+			if code := runtime.start(context.Background(), peer, carriers, request); code == "" || len(*children) != before {
+				t.Fatal("invalid reservation launched", kind, code)
+			}
+		})
+	}
+}
+func TestGrantCohortChunkRevalidatesGrantAndTicket(t *testing.T) {
+	runtime, r, c, carriers, g, children := grantCohortFixture(t)
+	if code := runtime.start(context.Background(), operationPeer{42, 0}, carriers, grantControl(t, g, '1', '2', '3', 10)); code != "" {
+		t.Fatal(code)
+	}
+	if code := runtime.chunk(context.Background(), operationPeer{42, 0}, carriers, grantControl(t, g, '1', '4', '5', 11)); code != ErrLimit {
+		t.Fatal("requested byte ceiling", code)
+	}
+	chunk := grantControl(t, g, '1', '6', '7', 1)
+	if code := runtime.chunk(context.Background(), operationPeer{42, 0}, carriers, chunk); code != "" {
+		t.Fatal(code)
+	}
+	if code := runtime.chunk(context.Background(), operationPeer{42, 0}, carriers, chunk); code != ErrReplay {
+		t.Fatal("ticket replay", code)
+	}
+	(*children)[0].pending = false
+	r.store.Grants[0].State = GrantRevoked
+	r.store.Grants[0].Reason = ErrRevoked
+	r.store.Grants[0].RevokedAt = g.CreatedAt
+	r.store.Grants[0].Revision++
+	if code := runtime.chunk(context.Background(), operationPeer{42, 0}, carriers, grantControl(t, g, '1', '8', '9', 1)); code != ErrRevoked {
+		t.Fatal(code)
+	}
+	if err := c.cancelGrant(context.Background(), g.ID, 2); err != nil {
+		t.Fatal(err)
+	}
+}
+func TestGrantCohortNoQForUnknownChildOrRelay(t *testing.T) {
+	for _, kind := range []string{"child", "relay"} {
+		t.Run(kind, func(t *testing.T) {
+			runtime, r, _, carriers, g, children := grantCohortFixture(t)
+			if code := runtime.start(context.Background(), operationPeer{42, 0}, carriers, grantControl(t, g, '1', '2', '3', 1)); code != "" {
+				t.Fatal(code)
+			}
+			if kind == "child" {
+				(*children)[0].err = syscall.ECHILD
+			} else {
+				(*children)[0].stuck = true
+				(*children)[0].pending = true
+			}
+			ctx, cancel := context.WithTimeout(context.Background(), 20*time.Millisecond)
+			defer cancel()
+			result, code := runtime.authority.Revoke(ctx, carriers, g.ID, 1, r.store.Revision)
+			if code != ErrCleanupRequired || !result.Revoked || result.Drained {
+				t.Fatal("false Q", result, code)
+			}
+			if kind == "child" && len((*children)[0].signals) != 0 {
+				t.Fatal("foreign signal")
+			}
+		})
+	}
+}
+
+func TestGrantCohortRejectsInvalidReceipt(t *testing.T) {
+	key := GrantDrainKey{grantRef('e'), grantRef('f'), 2}
+	q := completeGrantProof(key)
+	q.Cohort = &GrantDrainProof{Key: key, Started: 1, Reaped: 0}
+	if completeQuiescence(q) {
+		t.Fatal("unreaped child accepted")
+	}
+	q.Cohort.Reaped = 1
+	q.Cohort.Key.Revision++
+	if completeQuiescence(q) {
+		t.Fatal("foreign receipt accepted")
+	}
+}
+
+type alteredGrantTicket struct{ grantOperationStub }
+
+func (v alteredGrantTicket) ValidateOperation(ctx context.Context, a NativeActor, r DataRequest, g Grant) (GrantUseValidation, Code) {
+	p, c := v.grantOperationStub.ValidateOperation(ctx, a, r, g)
+	p.Ticket.RequestDigest = grantRef('f')
+	return p, c
+}
+func TestGrantCohortBindsCompleteTicketDigest(t *testing.T) {
+	s, _, _, carriers, g, children := grantCohortFixture(t)
+	s.services.operations = alteredGrantTicket{}
+	if code := s.start(context.Background(), operationPeer{42, 0}, carriers, grantControl(t, g, '1', '2', '3', 1)); code != ErrDenied || len(*children) != 0 {
+		t.Fatal("substituted control ticket", code)
+	}
+}
+
+func TestReloadSuspensionBlocksGrantAndCohortWithoutRevokingEpoch(t *testing.T) {
+	runtime, repo, c, carriers, g, children := grantCohortFixture(t)
+	now := c.now()
+	c.gate.requestUnitCheck(true, now)
+	commits := repo.commits
+	c.gate.mu.Lock()
+	code := runtime.authority.transaction(func(*GrantStore) (bool, Code) { t.Fatal("disk transaction during suspension"); return true, "" })
+	c.gate.mu.Unlock()
+	if code != ErrFenced || runtime.authority.fenced || c.fenced || repo.commits != commits {
+		t.Fatal("suspension permanently revoked authority")
+	}
+	if code = c.start(context.Background(), operationPeer{42, 0}, runtime.authority.native, carriers, NativeActor{}, operationBinding{}); code == "" {
+		t.Fatal("start admitted during suspension")
+	}
+	c.gate.mu.Lock()
+	allowed := c.allowed()
+	c.gate.mu.Unlock()
+	if allowed || len(*children) != 0 {
+		t.Fatal("cohort bypassed suspension")
+	}
+	c.gate.requestUnitCheck(false, now)
+	serial, _ := c.gate.unitProbe(now)
+	c.gate.observeUnit(c.gate.binding, 1, "", false, true, serial, now)
+	if code = runtime.start(context.Background(), operationPeer{42, 0}, carriers, grantControl(t, g, '1', '2', '3', 1)); code != "" || len(*children) != 1 {
+		t.Fatal("verified reload could not resume original grant/epoch", code)
+	}
+	c.gate.fence("unit-stopped")
+	c.gate.mu.Lock()
+	code = runtime.authority.transaction(func(*GrantStore) (bool, Code) { return false, "" })
+	c.gate.mu.Unlock()
+	if code != ErrFenced || !runtime.authority.fenced {
+		t.Fatal("real stop did not permanently fence authority")
+	}
+}

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

@@ -0,0 +1,49 @@
+package helper
+
+import (
+	"io"
+	"net"
+	"sync"
+	"time"
+)
+
+// Private epoch-owned delivery state. These are not RPCs, identity providers,
+// or admission authority. Only a trusted native/ACL validator may issue tickets;
+// the S3 owner still consumes its replay window at the common admission order.
+// Missing DSM proof must not be replaced with these delivery bindings.
+type operationTickets struct {
+	writes       writeGates
+	mu           sync.Mutex
+	inventory    Inventory
+	epoch        string
+	now          func() time.Time
+	random       io.Reader
+	issued       map[string]issuedOperationTicket
+	closed       bool
+	streamIssued int
+}
+
+type issuedOperationTicket struct {
+	binding   TicketBinding
+	principal Principal
+	used      bool
+}
+
+// outputHandoff transfers an already authenticated, owned transport to the S2
+// relay exactly once. It never dials a caller address or publishes data itself.
+// The registering transport owns peer authentication and disconnect observation.
+type outputHandoff struct {
+	mu        sync.Mutex
+	inventory Inventory
+	epoch     string
+	now       func() time.Time
+	entries   map[string]operationOutput
+	closed    bool
+}
+
+type operationOutput struct {
+	binding operationBinding
+	conn    net.Conn
+	expires time.Time
+	taken   bool
+}