@synopackageland/cli 0.5.3 → 0.6.0

package/dist/templates/native-go/backend/internal/helper/native_provider_test.go

@@ -1,421 +0,0 @@
-package helper
-
-import (
-	"context"
-	"encoding/json"
-	"slices"
-	"strings"
-	"testing"
-	"time"
-)
-
-type fakeNativeSession struct {
-	value    NativeSession
-	code     Code
-	calls    int
-	carriers SessionCarriers
-	after    func()
-}
-
-func (f *fakeNativeSession) ValidateSession(ctx context.Context, c SessionCarriers) (NativeSession, Code) {
-	f.calls++
-	f.carriers = c
-	if _, ok := ctx.Deadline(); !ok {
-		panic("missing session deadline")
-	}
-	if f.after != nil {
-		f.after()
-	}
-	return f.value, f.code
-}
-
-type fakeLocalAccount struct {
-	value    LocalAccount
-	code     Code
-	calls    int
-	username string
-	after    func()
-}
-
-func (f *fakeLocalAccount) LookupLocalAccount(ctx context.Context, name string) (LocalAccount, Code) {
-	f.calls++
-	f.username = name
-	if _, ok := ctx.Deadline(); !ok {
-		panic("missing account deadline")
-	}
-	if f.after != nil {
-		f.after()
-	}
-	return f.value, f.code
-}
-
-type fakeNativeDiscovery struct {
-	value DiscoveryObservation
-	code  Code
-	calls int
-	actor NativeActor
-	after func()
-}
-
-func (f *fakeNativeDiscovery) DiscoverAnchors(ctx context.Context, a NativeActor, _ ScopeKind, _ int) (DiscoveryObservation, Code) {
-	f.calls++
-	f.actor = a
-	if _, ok := ctx.Deadline(); !ok {
-		panic("missing discovery deadline")
-	}
-	if f.after != nil {
-		f.after()
-	}
-	return f.value, f.code
-}
-
-func nativeFixture() (*NativeProvider, *fakeNativeSession, *fakeLocalAccount, SessionCarriers, time.Time) {
-	now := time.Unix(1700000000, 0)
-	principal := Principal{Kind: "local", SubjectRef: strings.Repeat("a", 64), InstanceRef: strings.Repeat("b", 64)}
-	s := &fakeNativeSession{value: NativeSession{Username: "alice", SessionRef: strings.Repeat("c", 64), AccountInstanceRef: principal.InstanceRef, CheckedAt: now}}
-	a := &fakeLocalAccount{value: LocalAccount{Principal: principal, Username: "alice", Enabled: true, UID: 1001, GID: 100, Groups: []uint32{105, 101}, Admin: true, CheckedAt: now}}
-	p := NewNativeProvider(s, a)
-	p.now = func() time.Time { return now }
-	return p, s, a, SessionCarriers{Cookie: "session-secret", SynoToken: "csrf-secret", ClientAddress: "192.0.2.1"}, now
-}
-
-func TestNativeResolveRootObservationsAndIsolation(t *testing.T) {
-	p, s, a, carriers, _ := nativeFixture()
-	actor, c := p.Resolve(context.Background(), carriers)
-	if c != "" {
-		t.Fatal(c)
-	}
-	if a.username != "alice" || s.carriers != carriers || actor.Principal() != a.value.Principal || actor.SessionRef() != s.value.SessionRef || actor.Username() != "alice" || actor.UID() != 1001 || actor.GID() != 100 || !actor.Admin() {
-		t.Fatal("actor did not derive from native observations")
-	}
-	if !slices.Equal(actor.Groups(), []uint32{101, 105}) {
-		t.Fatal(actor.Groups())
-	}
-	a.value.Groups[0] = 999
-	groups := actor.Groups()
-	groups[0] = 888
-	if !slices.Equal(actor.Groups(), []uint32{101, 105}) {
-		t.Fatal("mutable credential alias")
-	}
-	encoded, err := json.Marshal(struct {
-		Actor    NativeActor
-		Carriers SessionCarriers
-	}{actor, carriers})
-	if err != nil || strings.Contains(string(encoded), "secret") || strings.Contains(string(encoded), "alice") {
-		t.Fatalf("secret/identity serialization: %s, %v", encoded, err)
-	}
-}
-
-func TestNativeResolveFailsClosed(t *testing.T) {
-	cases := []struct {
-		name         string
-		change       func(*fakeNativeSession, *fakeLocalAccount, *SessionCarriers)
-		want         Code
-		accountCalls int
-	}{
-		{"no carrier", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { c.Cookie = "" }, ErrDenied, 0},
-		{"invalid session", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { s.code = ErrDenied }, ErrDenied, 0},
-		{"native failure redacted", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) {
-			s.code = Code("/private/session-secret")
-		}, ErrUnavailable, 0},
-		{"disabled", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { a.value.Enabled = false }, ErrDenied, 1},
-		{"deleted", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { a.code = ErrDenied }, ErrDenied, 1},
-		{"directory account", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { a.value.Principal.Kind = "ldap" }, ErrUnsupported, 1},
-		{"unknown account incarnation", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) {
-			a.value.Principal.InstanceRef = ""
-		}, ErrSuspended, 1},
-		{"unknown session incarnation", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { s.value.AccountInstanceRef = "" }, ErrSuspended, 0},
-		{"recreated same UID", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) {
-			a.value.Principal.InstanceRef = strings.Repeat("d", 64)
-		}, ErrSuspended, 1},
-		{"name substitution", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { a.value.Username = "bob" }, ErrDenied, 1},
-		{"incomplete groups", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { a.value.Groups = nil }, ErrUnavailable, 1},
-		{"malformed session ref", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { s.value.SessionRef = "cookie" }, ErrUnavailable, 0},
-		{"malformed session instance", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) {
-			s.value.AccountInstanceRef = "alice:1001"
-		}, ErrUnavailable, 0},
-		{"zero session timestamp", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { s.value.CheckedAt = time.Time{} }, ErrStale, 0},
-		{"zero account timestamp", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) { a.value.CheckedAt = time.Time{} }, ErrStale, 1},
-		{"malformed subject ref", func(s *fakeNativeSession, a *fakeLocalAccount, c *SessionCarriers) {
-			a.value.Principal.SubjectRef = "alice:1001"
-		}, ErrUnavailable, 1},
-	}
-	for _, tt := range cases {
-		t.Run(tt.name, func(t *testing.T) {
-			p, s, a, carriers, _ := nativeFixture()
-			tt.change(s, a, &carriers)
-			actor, c := p.Resolve(context.Background(), carriers)
-			if c != tt.want || actor.valid || a.calls != tt.accountCalls {
-				t.Fatalf("code=%q valid=%v lookups=%d", c, actor.valid, a.calls)
-			}
-		})
-	}
-	if actor, c := NewNativeProvider(nil, nil).Resolve(context.Background(), SessionCarriers{}); c != ErrUnavailable || actor.valid {
-		t.Fatal(c)
-	}
-}
-
-func TestNativeProofAgeAndCancellation(t *testing.T) {
-	for _, source := range []string{"session", "account"} {
-		for _, age := range []time.Duration{-time.Nanosecond, 0, NativeProofFreshness, NativeProofFreshness + time.Nanosecond} {
-			t.Run(source+age.String(), func(t *testing.T) {
-				p, s, a, carriers, now := nativeFixture()
-				if source == "session" {
-					s.value.CheckedAt = now.Add(-age)
-				} else {
-					a.value.CheckedAt = now.Add(-age)
-				}
-				actor, c := p.Resolve(context.Background(), carriers)
-				want := Code("")
-				if age < 0 || age > NativeProofFreshness {
-					want = ErrStale
-				}
-				if c != want || actor.valid != (want == "") {
-					t.Fatalf("code=%q want=%q", c, want)
-				}
-			})
-		}
-	}
-	p, s, a, carriers, now := nativeFixture()
-	a.after = func() { p.now = func() time.Time { return now.Add(NativeProofFreshness + time.Nanosecond) } }
-	if _, c := p.Resolve(context.Background(), carriers); c != ErrStale {
-		t.Fatal("accepted proof aged during lookup", c)
-	}
-	ctx, cancel := context.WithCancel(context.Background())
-	cancel()
-	before := s.calls
-	if _, c := p.Resolve(ctx, carriers); c != ErrCanceled || s.calls != before {
-		t.Fatal("canceled admission reached provider", c)
-	}
-	ctx, cancel = context.WithDeadline(context.Background(), time.Now().Add(-time.Second))
-	defer cancel()
-	if _, c := p.Resolve(ctx, carriers); c != ErrTimeout {
-		t.Fatal(c)
-	}
-	p, s, _, carriers, _ = nativeFixture()
-	ctx, cancel = context.WithCancel(context.Background())
-	defer cancel()
-	s.after = cancel
-	if _, c := p.Resolve(ctx, carriers); c != ErrCanceled {
-		t.Fatal("accepted provider success after cancellation", c)
-	}
-}
-
-func TestNativeRevalidationChangesInvalidateSnapshots(t *testing.T) {
-	cases := []struct {
-		name   string
-		change func(*fakeNativeSession, *fakeLocalAccount)
-		want   Code
-	}{
-		{"session revoked", func(s *fakeNativeSession, a *fakeLocalAccount) { s.code = ErrDenied }, ErrDenied},
-		{"disabled", func(s *fakeNativeSession, a *fakeLocalAccount) { a.value.Enabled = false }, ErrDenied},
-		{"deleted", func(s *fakeNativeSession, a *fakeLocalAccount) { a.code = ErrDenied }, ErrDenied},
-		{"session swapped", func(s *fakeNativeSession, a *fakeLocalAccount) { s.value.SessionRef = strings.Repeat("d", 64) }, ErrStale},
-		{"group removed", func(s *fakeNativeSession, a *fakeLocalAccount) { a.value.Groups = []uint32{105} }, ErrStale},
-		{"group added", func(s *fakeNativeSession, a *fakeLocalAccount) { a.value.Groups = []uint32{101, 105, 106} }, ErrStale},
-		{"admin removed", func(s *fakeNativeSession, a *fakeLocalAccount) { a.value.Admin = false }, ErrStale},
-		{"primary group changed", func(s *fakeNativeSession, a *fakeLocalAccount) { a.value.GID++ }, ErrSuspended},
-		{"UID changed", func(s *fakeNativeSession, a *fakeLocalAccount) { a.value.UID++ }, ErrSuspended},
-		{"rename", func(s *fakeNativeSession, a *fakeLocalAccount) {
-			s.value.Username = "alice2"
-			a.value.Username = "alice2"
-		}, ErrSuspended},
-		{"same UID new instance", func(s *fakeNativeSession, a *fakeLocalAccount) {
-			a.value.Principal.InstanceRef = strings.Repeat("d", 64)
-			s.value.AccountInstanceRef = a.value.Principal.InstanceRef
-		}, ErrSuspended},
-		{"continuity lost", func(s *fakeNativeSession, a *fakeLocalAccount) { a.value.Principal.InstanceRef = "" }, ErrSuspended},
-	}
-	for _, tt := range cases {
-		t.Run(tt.name, func(t *testing.T) {
-			p, s, a, carriers, _ := nativeFixture()
-			old, c := p.Resolve(context.Background(), carriers)
-			if c != "" {
-				t.Fatal(c)
-			}
-			tt.change(s, a)
-			current, c := p.Revalidate(context.Background(), carriers, old)
-			if c != tt.want || current.valid || s.calls != 2 {
-				t.Fatalf("code=%q want=%q calls=%d", c, tt.want, s.calls)
-			}
-			if tt.name == "admin removed" {
-				next, c := p.Resolve(context.Background(), carriers)
-				if c != "" || next.Admin() {
-					t.Fatal("current admin role not refreshed")
-				}
-			}
-		})
-	}
-	p, _, a, carriers, _ := nativeFixture()
-	old, _ := p.Resolve(context.Background(), carriers)
-	a.value.Groups = []uint32{101, 105, 101}
-	if _, c := p.Revalidate(context.Background(), carriers, old); c != "" {
-		t.Fatal("group set order changed identity", c)
-	}
-	if _, c := p.Revalidate(context.Background(), carriers, NativeActor{}); c != ErrDenied {
-		t.Fatal("zero actor accepted", c)
-	}
-}
-
-func discoveryFixture() (*NativeProvider, *fakeNativeSession, *fakeLocalAccount, *fakeNativeDiscovery, SessionCarriers) {
-	p, s, a, carriers, now := nativeFixture()
-	d := &fakeNativeDiscovery{value: DiscoveryObservation{Principal: a.value.Principal, SessionRef: s.value.SessionRef, CheckedAt: now, Anchors: []DiscoveryAnchor{{Ref: strings.Repeat("e", 64), DisplayName: "My home", Kind: ScopePersonal, Owner: a.value.Principal, LocalFilesystem: true}}}}
-	return p, s, a, d, carriers
-}
-
-func TestNativeDiscoveryOwnHomeAndCurrentVisibility(t *testing.T) {
-	p, s, _, d, carriers := discoveryFixture()
-	anchors, c := p.Discover(context.Background(), carriers, d, ScopePersonal, 1)
-	if c != "" || len(anchors) != 1 || d.actor.Username() != "alice" || s.calls != 2 {
-		t.Fatalf("anchors=%v code=%q checks=%d", anchors, c, s.calls)
-	}
-	d.value.Anchors[0].DisplayName = "changed"
-	if anchors[0].DisplayName != "My home" {
-		t.Fatal("discovery aliases mutable provider storage")
-	}
-	d.value.Anchors = []DiscoveryAnchor{}
-	if anchors, c := p.Discover(context.Background(), carriers, d, ScopePersonal, 1); c != "" || anchors == nil || len(anchors) != 0 {
-		t.Fatal("empty discovery rejected", c)
-	}
-	d.value.Anchors = []DiscoveryAnchor{{Ref: strings.Repeat("f", 64), DisplayName: "Visible share", Kind: ScopeShared, LocalFilesystem: true}}
-	if anchors, c := p.Discover(context.Background(), carriers, d, ScopeShared, 200); c != "" || len(anchors) != 1 {
-		t.Fatal(c)
-	}
-}
-
-func TestNativeDiscoveryRejectsUntrustedOrStaleMetadata(t *testing.T) {
-	cases := []struct {
-		name   string
-		change func(*NativeProvider, *fakeNativeSession, *fakeLocalAccount, *fakeNativeDiscovery)
-		want   Code
-	}{
-		{"other home even for admin", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.Anchors[0].Owner.SubjectRef = strings.Repeat("f", 64)
-		}, ErrDenied},
-		{"other subject", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.Principal.SubjectRef = strings.Repeat("f", 64)
-		}, ErrDenied},
-		{"other session", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.SessionRef = strings.Repeat("f", 64)
-		}, ErrDenied},
-		{"remote filesystem", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.Anchors[0].LocalFilesystem = false
-		}, ErrUnsupported},
-		{"wrong scope", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.Anchors[0].Kind = ScopeShared
-		}, ErrDenied},
-		{"unknown listing", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.Anchors = nil
-		}, ErrUnavailable},
-		{"oversize page", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.Anchors = append(d.value.Anchors, d.value.Anchors[0])
-		}, ErrLimit},
-		{"stale discovery", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.CheckedAt = d.value.CheckedAt.Add(-NativeProofFreshness - time.Nanosecond)
-		}, ErrStale},
-		{"name leaks path", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.Anchors[0].DisplayName = "/volume1/homes/bob"
-		}, ErrUnavailable},
-		{"raw native error", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.code = Code("session-secret /volume1")
-		}, ErrUnavailable},
-		{"session invalidated during discovery", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.after = func() { s.code = ErrDenied }
-		}, ErrDenied},
-		{"groups change during discovery", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.after = func() { a.value.Groups = []uint32{105} }
-		}, ErrStale},
-		{"admin removed during discovery", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.after = func() { a.value.Admin = false }
-		}, ErrStale},
-		{"future discovery timestamp", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.CheckedAt = d.value.CheckedAt.Add(time.Nanosecond)
-		}, ErrStale},
-		{"invalid anchor reference", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.Anchors[0].Ref = "/home"
-		}, ErrUnavailable},
-		{"invalid UTF-8 label", func(p *NativeProvider, s *fakeNativeSession, a *fakeLocalAccount, d *fakeNativeDiscovery) {
-			d.value.Anchors[0].DisplayName = string([]byte{255})
-		}, ErrUnavailable},
-	}
-	for _, tt := range cases {
-		t.Run(tt.name, func(t *testing.T) {
-			p, s, a, d, carriers := discoveryFixture()
-			tt.change(p, s, a, d)
-			anchors, c := p.Discover(context.Background(), carriers, d, ScopePersonal, 1)
-			if c != tt.want || anchors != nil {
-				t.Fatalf("metadata leaked on refusal: anchors=%v code=%q want=%q", anchors, c, tt.want)
-			}
-		})
-	}
-	p, s, _, d, carriers := discoveryFixture()
-	for _, limit := range []int{0, -1, MaxPageEntries + 1} {
-		if _, c := p.Discover(context.Background(), carriers, d, ScopeShared, limit); c != ErrLimit {
-			t.Fatal(c)
-		}
-	}
-	if _, c := p.Discover(context.Background(), carriers, d, ScopeKind("all-homes"), 1); c != ErrUnsupported {
-		t.Fatal(c)
-	}
-	if d.calls != 0 || s.calls != 0 {
-		t.Fatal("invalid request reached providers")
-	}
-	if _, c := p.Discover(context.Background(), carriers, nil, ScopePersonal, 1); c != ErrUnavailable {
-		t.Fatal(c)
-	}
-}
-
-func TestNativeDiscoveryTwoUsersAndEmptyCredentialSet(t *testing.T) {
-	p, s, a, d, carriers := discoveryFixture()
-	// The provider's explicit empty complete set is valid; primary GID is separate.
-	a.value.Groups = []uint32{}
-	a.value.Admin = false
-	first, c := p.Resolve(context.Background(), carriers)
-	if c != "" || first.Groups() == nil || len(first.Groups()) != 0 || first.Admin() {
-		t.Fatal("empty complete credentials rejected", c)
-	}
-	other := Principal{Kind: "local", SubjectRef: strings.Repeat("1", 64), InstanceRef: strings.Repeat("2", 64)}
-	s.value.Username = "bob"
-	s.value.SessionRef = strings.Repeat("3", 64)
-	s.value.AccountInstanceRef = other.InstanceRef
-	a.value.Username = "bob"
-	a.value.Principal = other
-	a.value.UID = 1002
-	if _, c := p.Revalidate(context.Background(), carriers, first); c != ErrSuspended {
-		t.Fatal("cross-user snapshot accepted", c)
-	}
-	if anchors, c := p.Discover(context.Background(), carriers, d, ScopePersonal, 1); c != ErrDenied || anchors != nil {
-		t.Fatal("previous user's home leaked", c)
-	}
-	d.value.Principal = other
-	d.value.SessionRef = s.value.SessionRef
-	d.value.Anchors[0].Owner = other
-	if anchors, c := p.Discover(context.Background(), carriers, d, ScopePersonal, 1); c != "" || anchors[0].Owner != other {
-		t.Fatal("current user's home rejected", c)
-	}
-}
-
-func TestNativeDiscoveryPageIntegrityAndCancellation(t *testing.T) {
-	p, s, _, d, carriers := discoveryFixture()
-	d.value.Anchors = []DiscoveryAnchor{
-		{Ref: strings.Repeat("e", 64), DisplayName: "one", Kind: ScopeShared, LocalFilesystem: true},
-		{Ref: strings.Repeat("e", 64), DisplayName: "two", Kind: ScopeShared, LocalFilesystem: true},
-	}
-	if anchors, c := p.Discover(context.Background(), carriers, d, ScopeShared, 2); c != ErrUnavailable || anchors != nil {
-		t.Fatal("duplicate anchor references accepted", c)
-	}
-	d.value.Anchors[1].Ref = strings.Repeat("f", 64)
-	if anchors, c := p.Discover(context.Background(), carriers, d, ScopeShared, 2); c != "" || len(anchors) != 2 {
-		t.Fatal(c)
-	}
-	ctx, cancel := context.WithCancel(context.Background())
-	d.after = cancel
-	if anchors, c := p.Discover(ctx, carriers, d, ScopeShared, 2); c != ErrCanceled || anchors != nil {
-		t.Fatal("canceled metadata returned", c)
-	}
-	s.code = ErrDenied
-	before := d.calls
-	if anchors, c := p.Discover(context.Background(), carriers, d, ScopeShared, 2); c != ErrDenied || anchors != nil || d.calls != before {
-		t.Fatal("unauthenticated discovery reached adapter", c)
-	}
-}

package/dist/templates/native-go/backend/internal/helper/observation.go

@@ -1,244 +0,0 @@
-package helper
-
-import (
-	"sync"
-	"time"
-)
-
-const observationFreshness = time.Second
-const unitVerificationBudget = 3 * time.Second
-const unitReloadBudget = 10 * time.Second
-const unitQueryRecoveryBudget = 3 * time.Second
-
-// Signal delivery, bounded reload verification, and admission share one ordering
-// point. A temporary suspension is distinct from an irreversible sticky fence.
-type admission struct {
-	mu                    sync.Mutex
-	events                [observerEventLimit]observerEvent
-	eventNext, eventCount int
-	firstFence            observerEvent
-	queryPending          *observerQueryPending
-	diagnosticWake        chan struct{}
-	binding               Binding
-	entered               uint64
-	seen                  time.Time
-	blocked               string
-	queryUntil            time.Time
-	pendingUntil          time.Time
-	reloadUntil           time.Time
-	reloading             bool
-	unitSerial            uint64
-	unitObserved          bool
-	invocation            string
-	hasInvocation         bool
-}
-
-func newAdmission(b Binding) *admission  { return &admission{binding: b} }
-func (g *admission) fence(reason string) { g.mu.Lock(); defer g.mu.Unlock(); g.fenceLocked(reason) }
-func (g *admission) fenceLocked(reason string) {
-	g.fenceObserverLocked(reason, observerEvent{Detail: reason})
-}
-func (g *admission) observe(b Binding, entered uint64, active bool, now time.Time) {
-	g.mu.Lock()
-	defer g.mu.Unlock()
-	g.observeLocked(b, entered, active, now)
-}
-func (g *admission) observeLocked(b Binding, entered uint64, active bool, now time.Time) {
-	if !active {
-		g.fenceObserverLocked("observation-unavailable", observerEvent{Detail: "inactive-observation"})
-	} else if b.Boot != g.binding.Boot || b.Install != g.binding.Install {
-		g.fenceObserverLocked("installation-changed", observerEvent{Detail: "binding-changed", Phase: "validate-values"})
-	} else if entered == 0 || (g.entered != 0 && g.entered != entered) {
-		g.fenceObserverLocked("unit-transition", observerEvent{Detail: "entered-changed", Phase: "validate-values"})
-	} else {
-		g.entered = entered
-		g.binding.Entered = entered
-		g.seen = now
-	}
-}
-func (g *admission) requestUnitCheck(reloading bool, now time.Time) {
-	g.mu.Lock()
-	defer g.mu.Unlock()
-	g.requestUnitCheckLocked(reloading, now)
-}
-func (g *admission) requestUnitRemoval(now time.Time) {
-	g.mu.Lock()
-	defer g.mu.Unlock()
-	g.requestUnitCheckLocked(g.reloading, now)
-}
-func (g *admission) requestUnitCheckLocked(reloading bool, now time.Time) {
-	g.checkLocked(now)
-	if g.blocked != "" {
-		return
-	}
-	if reloading {
-		// The first trusted true pins the cap for this whole pending cycle.
-		// Repeated true/removal or a true after false cannot buy another cap.
-		if g.reloadUntil.IsZero() {
-			g.reloadUntil = now.Add(unitReloadBudget)
-			// An earlier unpaired removal already began this suspension;
-			// keep the cycle anchored there instead of buying another 3s.
-			if !g.pendingUntil.IsZero() {
-				g.reloadUntil = g.pendingUntil.Add(unitReloadBudget - unitVerificationBudget)
-			}
-		}
-		g.pendingUntil = g.reloadUntil
-	} else if g.reloading && !g.reloadUntil.IsZero() {
-		// A matched false starts a separate verification budget. The overall
-		// cycle remains <= reload cap + verification, even with chattering.
-		g.pendingUntil = now.Add(unitVerificationBudget)
-		if absolute := g.reloadUntil.Add(unitVerificationBudget); absolute.Before(g.pendingUntil) {
-			g.pendingUntil = absolute
-		}
-	} else if g.pendingUntil.IsZero() {
-		// Removal/unmatched false without a trusted reload keeps the short bound.
-		g.pendingUntil = now.Add(unitVerificationBudget)
-	}
-	g.recordObserverLocked(observerEvent{Kind: "verification-request", QuerySerial: g.unitSerial + 1})
-	g.reloading = reloading
-	g.unitSerial++     // A response begun before this edge cannot resume admission.
-	g.checkLocked(now) // A late true cannot resurrect an already elapsed reload cap.
-}
-func (g *admission) unitProbe(now time.Time) (uint64, bool) {
-	g.mu.Lock()
-	defer g.mu.Unlock()
-	if !g.seen.IsZero() || !g.pendingUntil.IsZero() {
-		g.checkLocked(now)
-	}
-	return g.unitSerial, g.blocked == "" && !g.reloading
-}
-func (g *admission) observeUnit(b Binding, entered uint64, invocation string, present, active bool, serial uint64, now time.Time, detail ...observerEvent) {
-	g.mu.Lock()
-	defer g.mu.Unlock()
-	if g.unitObserved || !g.pendingUntil.IsZero() {
-		g.checkLocked(now)
-	}
-	if g.blocked != "" || serial != g.unitSerial || g.reloading {
-		return
-	}
-	if !active {
-		e := observerEvent{Detail: "snapshot-not-active", Phase: "validate-values", QuerySerial: serial}
-		if len(detail) > 0 {
-			e = detail[0]
-		}
-		g.fenceObserverLocked("observation-unavailable", e)
-		return
-	}
-	if g.unitObserved && (g.hasInvocation != present || (present && g.invocation != invocation)) {
-		g.fenceObserverLocked("unit-transition", observerEvent{Detail: "invocation-changed", Phase: "validate-values", QuerySerial: serial})
-		return
-	}
-	g.observeLocked(b, entered, active, now)
-	if g.blocked != "" {
-		return
-	}
-	g.invocation, g.hasInvocation, g.unitObserved = invocation, present, true
-	g.recordObserverLocked(observerEvent{Kind: "query-accepted", QuerySerial: serial})
-	g.finishQueryPendingLocked("ready", now)
-	g.queryUntil = time.Time{}
-	g.pendingUntil = time.Time{}
-	g.reloadUntil = time.Time{}
-}
-
-// A transient error from a probe invalidated by a trusted reload edge is not
-// fresh evidence. It cannot extend the budget or undo a definitive sticky fence.
-func (g *admission) failUnitProbe(serial uint64, reason string, definitive bool, now time.Time, detail ...observerEvent) bool {
-	g.mu.Lock()
-	defer g.mu.Unlock()
-	if !g.seen.IsZero() || !g.pendingUntil.IsZero() {
-		g.checkLocked(now)
-	}
-	if definitive || (serial == g.unitSerial && !g.reloading) {
-		e := observerEvent{Detail: "query-failed", QuerySerial: serial}
-		if len(detail) > 0 {
-			e = detail[0]
-		}
-		g.fenceObserverLocked(reason, e)
-	} else {
-		g.recordObserverLocked(observerEvent{Kind: "query-discarded", QuerySerial: serial})
-	}
-	return g.blocked != ""
-}
-func (g *admission) checkLocked(now time.Time) {
-	if g.blocked != "" {
-		return
-	} // Do not flood the diagnostic ring with the same terminal check.
-	if !g.queryUntil.IsZero() && !now.Before(g.queryUntil) {
-		g.fenceObserverLocked("observation-unavailable", observerEvent{At: now, Detail: "query-deadline", QuerySerial: g.unitSerial})
-		return
-	}
-	if !g.pendingUntil.IsZero() {
-		if !now.Before(g.pendingUntil) {
-			detail := "verification-deadline"
-			if g.reloading {
-				detail = "reload-deadline"
-			}
-			g.fenceObserverLocked("observation-unavailable", observerEvent{At: now, Detail: detail, QuerySerial: g.unitSerial})
-		}
-		return // The fixed verification budget replaces freshness only while denied.
-	}
-	if !g.queryUntil.IsZero() {
-		return // A fixed query recovery window denies admission instead of freshness.
-	}
-	if g.seen.IsZero() || now.Sub(g.seen) > observationFreshness {
-		g.fenceObserverLocked("observation-expired", observerEvent{Detail: "freshness-deadline", QuerySerial: g.unitSerial})
-	}
-}
-func (g *admission) allow(now time.Time) bool {
-	g.mu.Lock()
-	defer g.mu.Unlock()
-	return g.allowLocked(now)
-}
-func (g *admission) allowLocked(now time.Time) bool {
-	g.checkLocked(now)
-	return g.blocked == "" && g.pendingUntil.IsZero() && g.queryUntil.IsZero()
-}
-
-// Only the lifecycle owner may turn this terminal result into durable teardown.
-func (g *admission) fenced(now time.Time) bool {
-	g.mu.Lock()
-	defer g.mu.Unlock()
-	g.checkLocked(now)
-	return g.blocked != ""
-}
-func (g *admission) reason() string { g.mu.Lock(); defer g.mu.Unlock(); return g.blocked }
-
-// Readiness reports the gate at the same ordering point as admission.
-func (g *admission) readiness(now time.Time) string {
-	g.mu.Lock()
-	defer g.mu.Unlock()
-	if g.allowLocked(now) {
-		return "ready"
-	}
-	if g.blocked == "" && !g.queryUntil.IsZero() {
-		return "query-revalidating"
-	}
-	if g.blocked == "" && !g.reloadUntil.IsZero() && !g.pendingUntil.IsZero() {
-		return "reload-revalidating"
-	}
-	return "fenced"
-}
-
-// Only a previously authenticated observation may temporarily suspend. Startup
-// cannot acquire authority from a timeout. Neither retries nor reload edges
-// extend this deadline, and an expired/sticky fence always wins.
-func (g *admission) deferUnitDeadline(serial uint64, started, now time.Time, e observerEvent) bool {
-	g.mu.Lock()
-	defer g.mu.Unlock()
-	if !g.unitObserved || serial != g.unitSerial || g.reloading {
-		return false
-	}
-	g.checkLocked(now)
-	if g.blocked != "" {
-		return false
-	}
-	if g.queryUntil.IsZero() {
-		g.queryUntil = started.Add(unitQueryRecoveryBudget)
-		g.queryPending = &observerQueryPending{StartedAt: started, PendingAt: now, Outcome: "pending", Phase: e.Phase, ErrorClass: e.ErrorClass, QuerySerial: serial}
-		g.notifyObserverDiagnosticLocked()
-	}
-	e.Kind = "query-pending"
-	g.recordObserverLocked(e)
-	g.checkLocked(now)
-	return g.blocked == ""
-}