@synopackageland/cli 0.4.0 → 0.5.0

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

@@ -0,0 +1,421 @@
+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

@@ -0,0 +1,244 @@
+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 == ""
+}