@synopackageland/cli 0.4.0 → 0.4.1

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

@@ -0,0 +1,372 @@
+package helper
+
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"github.com/godbus/dbus/v5"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+	"time"
+)
+
+func TestLinuxUnitRemovedRequiresFreshVerification(t *testing.T) {
+	b := testBinding()
+	g := newAdmission(b)
+	g.observe(b, 7, true, time.Now())
+	o := &unitObserver{unit: "pkgctl-root.service", path: systemdUnitPath("pkgctl-root.service"), owner: ":1.1", gate: g}
+	o.DeliverSignal("", "", &dbus.Signal{Sender: o.owner, Path: "/org/freedesktop/systemd1", Name: managerInterface + ".UnitRemoved", Body: []interface{}{o.unit, o.path}})
+	if g.allow(time.Now()) || g.reason() != "" {
+		t.Fatalf("must suspend admission without sticky fence: %s", g.reason())
+	}
+}
+
+// Opt-in, disposable root VM. Captures the actual systemd signal sequence and
+// proves a daemon reload cannot alter this helper's durable epoch or identity.
+func TestLinuxDaemonReloadPreservesHelperEpoch(t *testing.T) {
+	p := linuxFixture(t)
+	process := startVMHelper(t, p)
+	before, err := readRecord(p.StateDir, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	child := supervisedPID(t, process.PID)
+	conn, err := dbus.ConnectSystemBus()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	if err = conn.AddMatchSignal(dbus.WithMatchInterface(managerInterface)); err != nil {
+		t.Fatal(err)
+	}
+	events := make(chan *dbus.Signal, 1024)
+	conn.Signal(events)
+	if err = conn.Object(systemdName, "/org/freedesktop/systemd1").Call(managerInterface+".Subscribe", 0).Err; err != nil {
+		t.Fatal(err)
+	}
+	var signalMu sync.Mutex
+	var signals []string
+	done := make(chan struct{})
+	stopped := make(chan struct{})
+	go func() {
+		defer close(stopped)
+		for {
+			select {
+			case s := <-events:
+				if s.Name == managerInterface+".Reloading" || (len(s.Body) > 0 && s.Body[0] == "pkgctl-root.service") {
+					signalMu.Lock()
+					signals = append(signals, fmt.Sprintf("%s %s %v", time.Now().Format(time.RFC3339Nano), s.Name, s.Body))
+					signalMu.Unlock()
+				}
+			case <-done:
+				return
+			}
+		}
+	}()
+	defer func() {
+		close(done)
+		<-stopped
+		signalMu.Lock()
+		defer signalMu.Unlock()
+		for _, s := range signals {
+			t.Log("systemd signal:", s)
+		}
+	}()
+	for n := 0; n < 3; n++ {
+		started := time.Now()
+		if out, err := exec.Command("systemctl", "daemon-reload").CombinedOutput(); err != nil {
+			t.Fatalf("reload: %s: %v", out, err)
+		}
+		time.Sleep(600 * time.Millisecond)
+		after, e := readRecord(p.StateDir, 0)
+		encoded, _ := json.Marshal(after)
+		t.Logf("reload trial=%d elapsed=%s lifecycle=%s", n+1, time.Since(started), encoded)
+		if e != nil || !reflect.DeepEqual(after, before) {
+			journal, _ := exec.Command("journalctl", "--no-pager", "-n", "30").CombinedOutput()
+			t.Fatalf("reload changed approval: lifecycle %+v -> %+v: %v; journal=%s", before.Lifecycle, after.Lifecycle, e, journal)
+		}
+		got, e := readProcess(p.RunDir, 0)
+		if e != nil || got != process || supervisedPID(t, process.PID) != child {
+			t.Fatalf("reload replaced helper: %+v: %v", got, e)
+		}
+		if state := p.Client.Status(context.Background()); state.State != "ready" {
+			t.Fatalf("health after reload: %+v", state)
+		}
+	}
+	signalMu.Lock()
+	defer signalMu.Unlock()
+	seenTrue, seenFalse := false, false
+	for _, s := range signals {
+		seenTrue = seenTrue || strings.Contains(s, ".Reloading [true]")
+		seenFalse = seenFalse || strings.Contains(s, ".Reloading [false]")
+	}
+	if !seenTrue || !seenFalse {
+		t.Fatal("missing reload boundary signals")
+	}
+	t.Logf("reload preserved epoch=%s", before.Lifecycle.Epoch)
+}
+
+func activeUnitValues(o *unitObserver) map[string]dbus.Variant {
+	return map[string]dbus.Variant{"Id": dbus.MakeVariant(o.unit), "LoadState": dbus.MakeVariant("loaded"), "ActiveState": dbus.MakeVariant("active"), "SubState": dbus.MakeVariant("exited"), "ActiveEnterTimestampMonotonic": dbus.MakeVariant(uint64(7)), "Job": dbus.MakeVariant([]interface{}{uint32(0), dbus.ObjectPath("/")}), "InvocationID": dbus.MakeVariant([]byte("1234567890123456"))}
+}
+func TestLinuxReloadRetainsStopRemoveRestartFences(t *testing.T) {
+	for _, kind := range []string{"unchanged", "stop", "restart", "job", "job-snapshot", "malformed-job", "zero-invocation", "invalidated", "owner", "disconnect", "load", "substate", "wrong-id", "timestamp", "invocation", "missing-invocation", "malformed-invocation", "malformed-reload", "foreign-reload", "other-removal"} {
+		t.Run(kind, func(t *testing.T) {
+			g := newAdmission(testBinding())
+			o := &unitObserver{unit: "pkgctl-root.service", path: systemdUnitPath("pkgctl-root.service"), owner: ":1.1", gate: g}
+			now := time.Now()
+			if err := o.observeValues(testBinding(), activeUnitValues(o), 0, now); err != nil {
+				t.Fatal(err)
+			}
+			send := func(name string, body []interface{}) {
+				o.DeliverSignal("", "", &dbus.Signal{Sender: o.owner, Path: "/org/freedesktop/systemd1", Name: managerInterface + "." + name, Body: body})
+			}
+			send("Reloading", []interface{}{true})
+			send("UnitRemoved", []interface{}{o.unit, o.path})
+			if g.allow(now) || g.fenced(now) {
+				t.Fatal("must suspend while reloading")
+			}
+			values := activeUnitValues(o)
+			want := false
+			switch kind {
+			case "unchanged":
+				want = true
+			case "stop", "restart":
+				o.DeliverSignal("", "", &dbus.Signal{Sender: o.owner, Path: o.path, Name: propertiesInterface + ".PropertiesChanged", Body: []interface{}{unitInterface, map[string]dbus.Variant{"ActiveState": dbus.MakeVariant("inactive")}, []string{}}})
+				if kind == "restart" {
+					values["ActiveEnterTimestampMonotonic"] = dbus.MakeVariant(uint64(8))
+				}
+			case "job":
+				send("JobNew", []interface{}{uint32(1), dbus.ObjectPath("/job/1"), o.unit})
+			case "job-snapshot":
+				values["Job"] = dbus.MakeVariant([]interface{}{uint32(9), dbus.ObjectPath("/job/9")})
+			case "malformed-job":
+				values["Job"] = dbus.MakeVariant("bad")
+			case "zero-invocation":
+				values["InvocationID"] = dbus.MakeVariant(make([]byte, 16))
+			case "invalidated":
+				o.DeliverSignal("", "", &dbus.Signal{Sender: o.owner, Path: o.path, Name: propertiesInterface + ".PropertiesChanged", Body: []interface{}{unitInterface, map[string]dbus.Variant{}, []string{"InvocationID"}}})
+			case "owner":
+				g.fence("bus-owner-changed")
+			case "disconnect":
+				o.Terminate()
+			case "load":
+				values["LoadState"] = dbus.MakeVariant("not-found")
+			case "substate":
+				values["SubState"] = dbus.MakeVariant("dead")
+			case "wrong-id":
+				values["Id"] = dbus.MakeVariant("pkgctl-other.service")
+			case "timestamp":
+				values["ActiveEnterTimestampMonotonic"] = dbus.MakeVariant(uint64(8))
+			case "invocation":
+				values["InvocationID"] = dbus.MakeVariant([]byte("6543210987654321"))
+			case "missing-invocation":
+				delete(values, "InvocationID")
+			case "malformed-invocation":
+				values["InvocationID"] = dbus.MakeVariant("wrong-type")
+			case "malformed-reload":
+				send("Reloading", []interface{}{"false"})
+			case "foreign-reload":
+				want = true
+				o.DeliverSignal("", "", &dbus.Signal{Sender: ":1.2", Path: "/org/freedesktop/systemd1", Name: managerInterface + ".Reloading", Body: []interface{}{false}})
+				if _, ready := g.unitProbe(now); ready {
+					t.Fatal("foreign sender ended reload")
+				}
+			case "other-removal":
+				want = true
+				send("UnitRemoved", []interface{}{"pkgctl-other.service", systemdUnitPath("pkgctl-other.service")})
+			}
+			send("Reloading", []interface{}{false})
+			serial, _ := g.unitProbe(now)
+			_ = o.observeValues(testBinding(), values, serial, now)
+			_ = o.observeValues(testBinding(), activeUnitValues(o), serial, now)
+			if g.allow(now) != want {
+				t.Fatalf("reload acceptance %s reason=%s", kind, g.reason())
+			}
+		})
+	}
+}
+
+func TestLinuxStopDuringDaemonReloadStillFences(t *testing.T) {
+	p := linuxFixture(t)
+	process := startVMHelper(t, p)
+	conn, err := dbus.ConnectSystemBus()
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	if err = conn.AddMatchSignal(dbus.WithMatchInterface(managerInterface), dbus.WithMatchMember("Reloading")); err != nil {
+		t.Fatal(err)
+	}
+	events := make(chan *dbus.Signal, 16)
+	conn.Signal(events)
+	if err = conn.Object(systemdName, "/org/freedesktop/systemd1").Call(managerInterface+".Subscribe", 0).Err; err != nil {
+		t.Fatal(err)
+	}
+	generators := "/etc/systemd/system-generators"
+	if err = os.MkdirAll(generators, 0755); err != nil {
+		t.Fatal(err)
+	}
+	generator := filepath.Join(generators, "m1h-slow-reload")
+	if err = os.WriteFile(generator, []byte("#!/bin/sh\nsleep 0.4\n"), 0755); err != nil {
+		t.Fatal(err)
+	}
+	defer os.Remove(generator)
+	reload := exec.Command("systemctl", "daemon-reload")
+	if err = reload.Start(); err != nil {
+		t.Fatal(err)
+	}
+	defer func() { _ = reload.Wait() }()
+	select {
+	case s := <-events:
+		if len(s.Body) != 1 || s.Body[0] != true {
+			t.Fatalf("reload did not start: %+v", s)
+		}
+	case <-time.After(2 * time.Second):
+		t.Fatal("missing Reloading(true)")
+	}
+	stop := exec.Command("systemctl", "stop", "pkgctl-root.service")
+	if err = stop.Run(); err != nil {
+		t.Fatal(err)
+	}
+	ctx, cancel := context.WithTimeout(context.Background(), 3*time.Second)
+	defer cancel()
+	if err = waitHealthy(ctx, func(context.Context) bool {
+		r, e := readRecord(p.StateDir, 0)
+		return e == nil && r.Lifecycle.Phase == "stopped" && r.Lifecycle.Completion != ""
+	}); err != nil {
+		t.Fatal("stop during reload failed to fence and complete", err)
+	}
+	record, err := readRecord(p.StateDir, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	proof, err := completionRecord(p.Client, record)
+	if err != nil || proof.Process != process {
+		t.Fatal("wrong completion identity", err)
+	}
+	vmUnit(t, "start")
+	time.Sleep(300 * time.Millisecond)
+	after, err := readRecord(p.StateDir, 0)
+	if err != nil || !reflect.DeepEqual(after, record) {
+		t.Fatal("active snapshot erased sticky fence", err)
+	}
+}
+
+func TestLinuxReloadQueryAndSubscriptionFailuresFence(t *testing.T) {
+	for _, kind := range []string{"query", "disconnect"} {
+		t.Run(kind, func(t *testing.T) {
+			p := linuxFixture(t)
+			o, err := openUnitObserver(context.Background(), p.Expected)
+			if err != nil {
+				t.Fatal(err)
+			}
+			defer o.conn.Close()
+			binding, values, err := o.snapshot(context.Background())
+			if err != nil {
+				t.Fatal(err)
+			}
+			o.gate.requestUnitCheck(true, time.Now())
+			o.gate.requestUnitCheck(false, time.Now())
+			if kind == "query" {
+				ctx, cancel := context.WithCancel(context.Background())
+				cancel()
+				if err = o.reconcile(ctx); err == nil {
+					t.Fatal("canceled query succeeded")
+				}
+			} else {
+				o.conn.Close()
+			}
+			t.Logf("query kind=%s fence reason=%s", kind, o.gate.reason())
+			if o.gate.allow(time.Now()) || !o.gate.fenced(time.Now()) {
+				t.Fatal("query/subscription failure resumed admission")
+			}
+			serial, _ := o.gate.unitProbe(time.Now())
+			_ = o.observeValues(binding, values, serial, time.Now())
+			if o.gate.allow(time.Now()) {
+				t.Fatal("active snapshot erased failure")
+			}
+		})
+	}
+}
+
+// A query can straddle Reloading(true). Its response cannot revoke the epoch or
+// resume admission after that boundary, even when it contains invalid values.
+func TestLinuxReloadInvalidatedSnapshotCannotFence(t *testing.T) {
+	for _, kind := range []string{"inactive", "missing-invocation", "malformed-invocation", "missing-values"} {
+		for _, finished := range []bool{false, true} {
+			t.Run(fmt.Sprintf("%s/reloadFinished=%t", kind, finished), func(t *testing.T) {
+				now := time.Now()
+				g := newAdmission(testBinding())
+				o := &unitObserver{unit: "pkgctl-root.service", gate: g}
+				if err := o.observeValues(testBinding(), activeUnitValues(o), 0, now); err != nil {
+					t.Fatal(err)
+				}
+				old, _ := g.unitProbe(now)
+				g.requestUnitCheck(true, now)
+				if finished {
+					g.requestUnitCheck(false, now)
+				}
+				values := activeUnitValues(o)
+				switch kind {
+				case "inactive":
+					values["ActiveState"] = dbus.MakeVariant("inactive")
+				case "missing-invocation":
+					delete(values, "InvocationID")
+				case "malformed-invocation":
+					values["InvocationID"] = dbus.MakeVariant("bad")
+				case "missing-values":
+					values = map[string]dbus.Variant{}
+				}
+				if err := o.observeValues(testBinding(), values, old, now); err != nil || g.fenced(now) || g.allow(now) {
+					t.Fatalf("stale response fenced or resumed: err=%v reason=%s", err, g.reason())
+				}
+				if !finished {
+					g.requestUnitCheck(false, now)
+				}
+				serial, _ := g.unitProbe(now)
+				if err := o.observeValues(testBinding(), activeUnitValues(o), serial, now); err != nil || !g.allow(now) {
+					t.Fatalf("fresh verification failed: %v %s", err, g.reason())
+				}
+				g.fence("unit-stopped")
+				_ = o.observeValues(testBinding(), activeUnitValues(o), old, now)
+				if g.reason() != "unit-stopped" {
+					t.Fatal("stale reply cleared stop")
+				}
+			})
+		}
+	}
+}
+
+func TestLinuxReloadInvalidatedQueryCannotFence(t *testing.T) {
+	p := linuxFixture(t)
+	o, err := openUnitObserver(context.Background(), p.Expected)
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer o.conn.Close()
+	binding, values, err := o.snapshot(context.Background())
+	if err != nil {
+		t.Fatal(err)
+	}
+	// Start a probe, then deliver the trusted reload edge before its reply/error.
+	err = o.reconcileSnapshot(context.Background(), func(context.Context) (Binding, map[string]dbus.Variant, error) {
+		o.gate.requestUnitCheck(true, time.Now())
+		ctx, cancel := context.WithCancel(context.Background())
+		cancel()
+		return o.snapshot(ctx)
+	})
+	if err != nil || o.gate.fenced(time.Now()) || o.gate.allow(time.Now()) {
+		t.Fatalf("stale query error fenced or resumed: %v %s", err, o.gate.reason())
+	}
+	o.gate.requestUnitCheck(false, time.Now())
+	serial, _ := o.gate.unitProbe(time.Now())
+	if err = o.observeValues(binding, values, serial, time.Now()); err != nil || !o.gate.allow(time.Now()) {
+		t.Fatalf("fresh check failed: %v %s", err, o.gate.reason())
+	}
+}

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

@@ -0,0 +1,232 @@
+package helper
+
+import (
+	"context"
+	"encoding/json"
+	"github.com/godbus/dbus/v5"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sync"
+	"testing"
+	"time"
+)
+
+// Real manager signal/query sequence, no signal injection or product patch.
+func TestLinuxObserverReloadSignalAndQuerySequence(t *testing.T) {
+	p := linuxFixture(t)
+	identity := startVMHelper(t, p)
+	childBefore := supervisedPID(t, identity.PID)
+	before, err := readRecord(p.StateDir, 0)
+	if err != nil {
+		t.Fatal(err)
+	}
+	unit := "pkgctl-root.service"
+	path := systemdUnitPath(unit)
+	var mu sync.Mutex
+	events := []observerEvent{}
+	started := make(chan struct{})
+	var once sync.Once
+	conn, err := dbus.ConnectSystemBus(dbus.WithIncomingInterceptor(func(m *dbus.Message) {
+		if m.Type != dbus.TypeSignal {
+			return
+		}
+		iface, _ := m.Headers[dbus.FieldInterface].Value().(string)
+		member, _ := m.Headers[dbus.FieldMember].Value().(string)
+		sender, _ := m.Headers[dbus.FieldSender].Value().(string)
+		name := iface + "." + member
+		e := observerEvent{At: time.Now().UTC(), Kind: "signal", Signal: name, Sender: safeBusSender(sender), WireSerial: m.Serial()}
+		switch name {
+		case managerInterface + ".Reloading":
+			if len(m.Body) != 1 {
+				return
+			}
+			value, ok := m.Body[0].(bool)
+			if !ok {
+				return
+			}
+			if value {
+				e.Detail = "reload-start"
+				once.Do(func() { close(started) })
+			} else {
+				e.Detail = "reload-end"
+			}
+		case managerInterface + ".UnitRemoved", managerInterface + ".UnitNew":
+			if len(m.Body) < 1 || m.Body[0] != unit {
+				return
+			}
+		case propertiesInterface + ".PropertiesChanged":
+			if m.Headers[dbus.FieldPath].Value() != path || len(m.Body) != 3 || m.Body[0] != unitInterface {
+				return
+			}
+			e.Detail = "own-properties-changed"
+			// Only fixed monitored names, never values or unrecognized strings.
+			if invalid, ok := m.Body[2].([]string); ok {
+				for _, key := range invalid {
+					for _, fixed := range []string{"LoadState", "ActiveState", "SubState", "Job", "ActiveEnterTimestampMonotonic", "InvocationID"} {
+						if key == fixed {
+							e.Detail = "own-invalidated-" + fixed
+						}
+					}
+				}
+			}
+		default:
+			return
+		}
+		mu.Lock()
+		defer mu.Unlock()
+		if len(events) < 64 {
+			events = append(events, e)
+		}
+	}))
+	if err != nil {
+		t.Fatal(err)
+	}
+	defer conn.Close()
+	if err = conn.AddMatchSignal(dbus.WithMatchInterface(managerInterface)); err != nil {
+		t.Fatal(err)
+	}
+	if err = conn.AddMatchSignal(dbus.WithMatchInterface(propertiesInterface), dbus.WithMatchObjectPath(path)); err != nil {
+		t.Fatal(err)
+	}
+	if err = conn.Object(systemdName, "/org/freedesktop/systemd1").Call(managerInterface+".Subscribe", 0).Err; err != nil {
+		t.Fatal(err)
+	}
+	var owner string
+	if err = conn.BusObject().Call("org.freedesktop.DBus.GetNameOwner", 0, systemdName).Store(&owner); err != nil {
+		t.Fatal(err)
+	}
+	dir := "/etc/systemd/system-generators"
+	if err = os.MkdirAll(dir, 0755); err != nil {
+		t.Fatal(err)
+	}
+	generator := filepath.Join(dir, "m1j-sequence-reload")
+	if err = os.WriteFile(generator, []byte("#!/bin/sh\nsleep 4\n"), 0755); err != nil {
+		t.Fatal(err)
+	}
+	defer os.Remove(generator)
+	reload := exec.Command("systemctl", "daemon-reload")
+	if err = reload.Start(); err != nil {
+		t.Fatal(err)
+	}
+	waited := make(chan error, 1)
+	go func() { waited <- reload.Wait() }()
+	select {
+	case <-started:
+	case <-time.After(3 * time.Second):
+		t.Fatal("missing true")
+	}
+	// Sample the public health envelope throughout the real 4s reload and
+	// post-edge validation. Preserve every sample; any failed/fenced is fatal.
+	stopSamples := make(chan struct{})
+	sampleDone := make(chan []State, 1)
+	go func() {
+		samples := []State{}
+		ticker := time.NewTicker(100 * time.Millisecond)
+		defer ticker.Stop()
+		for {
+			samples = append(samples, p.Client.Status(context.Background()))
+			select {
+			case <-stopSamples:
+				sampleDone <- samples
+				return
+			case <-ticker.C:
+			}
+		}
+	}()
+	defer func() {
+		select {
+		case <-stopSamples:
+		default:
+			close(stopSamples)
+		}
+	}()
+	pendingCtx, pendingCancel := context.WithTimeout(context.Background(), time.Second)
+	var during State
+	err = waitHealthy(pendingCtx, func(context.Context) bool { during = p.Client.Status(pendingCtx); return during.State == "pending" })
+	pendingCancel()
+	if err != nil || during.Reason != "reload-revalidating" || during.Cleanup != "" {
+		t.Fatalf("reload did not report pending: %+v %v", during, err)
+	}
+	t.Logf("during reload API state=%s reason=%s cleanup=%s", during.State, during.Reason, during.Cleanup)
+	query := func(phase string) {
+		ctx, cancel := context.WithTimeout(context.Background(), 500*time.Millisecond)
+		defer cancel()
+		begin := time.Now()
+		var err error
+		switch phase {
+		case "get-owner":
+			var name string
+			err = conn.BusObject().CallWithContext(ctx, "org.freedesktop.DBus.GetNameOwner", 0, systemdName).Store(&name)
+		case "get-unit":
+			var object dbus.ObjectPath
+			err = conn.Object(owner, "/org/freedesktop/systemd1").CallWithContext(ctx, managerInterface+".GetUnit", 0, unit).Store(&object)
+		case "get-all":
+			var values map[string]dbus.Variant
+			err = conn.Object(owner, path).CallWithContext(ctx, propertiesInterface+".GetAll", 0, unitInterface).Store(&values)
+			if err == nil {
+				_, invocationPresent := values["InvocationID"]
+				entered, ok := values["ActiveEnterTimestampMonotonic"].Value().(uint64)
+				t.Logf("GetAll supportedness InvocationID=%t sameEntered=%t", invocationPresent, ok && entered == before.Lifecycle.Binding.Entered)
+			}
+		}
+		result := "ok"
+		if err != nil {
+			result = observerErrorClass(err)
+		}
+		t.Logf("real reload query phase=%s elapsed=%s result=%s", phase, time.Since(begin), result)
+	}
+	for _, phase := range []string{"get-owner", "get-unit", "get-all"} {
+		query(phase)
+	}
+	select {
+	case err := <-waited:
+		if err != nil {
+			t.Fatal(err)
+		}
+	case <-time.After(12 * time.Second):
+		t.Fatal("reload stuck")
+	}
+	time.Sleep(750 * time.Millisecond)
+	for _, phase := range []string{"get-owner", "get-unit", "get-all"} {
+		query(phase)
+	}
+	mu.Lock()
+	copyEvents := append([]observerEvent(nil), events...)
+	mu.Unlock()
+	b, _ := json.Marshal(copyEvents)
+	t.Logf("real reload signals=%s", b)
+	seenTrue, seenFalse := false, false
+	for _, e := range copyEvents {
+		seenTrue = seenTrue || e.Detail == "reload-start"
+		seenFalse = seenFalse || e.Detail == "reload-end"
+	}
+	if !seenTrue || !seenFalse {
+		t.Fatal("missing reload boundaries")
+	}
+	logObserverResult(t, p, before, identity, false, childBefore)
+	close(stopSamples)
+	samples := <-sampleDone
+	ready, pending := 0, 0
+	for _, sample := range samples {
+		switch sample.State {
+		case "ready":
+			ready++
+		case "pending":
+			pending++
+			if sample.Reason != "reload-revalidating" || sample.Cleanup != "" {
+				t.Fatalf("unsafe pending: %+v", sample)
+			}
+		default:
+			t.Fatalf("4s reload API sampled failure: %+v", sample)
+		}
+	}
+	if ready == 0 || pending == 0 {
+		t.Fatalf("missing health transition: ready=%d pending=%d", ready, pending)
+	}
+	t.Logf("4s reload API samples=%d ready=%d pending=%d failed=0", len(samples), ready, pending)
+	r, err := readRecord(p.StateDir, 0)
+	if err != nil || r.Lifecycle.Phase != "running" {
+		t.Fatalf("bounded reload retired helper: %+v %v", r, err)
+	}
+}

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

@@ -0,0 +1,77 @@
+package helper
+
+import (
+	"context"
+	"strings"
+)
+
+// Internal compiled gates; never filled from browser controls or environment.
+// Stream writes require both the write opt-in and a separately proved publish
+// primitive. Shipped adapters install none of these gates.
+type writeGates struct{ Create, Stream, Publish bool }
+
+func (g writeGates) allows(a Action) bool {
+	switch a {
+	case ActionCreate:
+		return g.Create
+	case ActionWriteStream:
+		return g.Create && g.Stream && g.Publish
+	case ActionPublish:
+		return g.Create && g.Publish
+	}
+	return false
+}
+
+type writeWork struct {
+	RootPath string   `json:"rootPath"`
+	Action   Action   `json:"action"`
+	Segments []string `json:"segments"`
+	MaxBytes uint64   `json:"maxBytes"`
+	Staged   bool     `json:"staged"`
+}
+
+func (w writeWork) validate() Code {
+	if !strings.HasPrefix(w.RootPath, "/") || w.RootPath == "/" {
+		return ErrInvalid
+	}
+	if c := ValidateRelativeSegments(strings.Split(w.RootPath[1:], "/"), false); c != "" {
+		return c
+	}
+	if c := ValidateRelativeSegments(w.Segments, false); c != "" {
+		return c
+	}
+	ceiling := uint64(MaxBoundedBytes)
+	switch w.Action {
+	case ActionCreate:
+		if w.Staged {
+			return ErrInvalid
+		}
+	case ActionWriteStream:
+		if !w.Staged {
+			return ErrInvalid
+		}
+		ceiling = MaxTransferBytes
+	default:
+		return ErrUnsupported
+	}
+	if w.MaxBytes == 0 || w.MaxBytes > ceiling {
+		return ErrLimit
+	}
+	return ""
+}
+
+// Only the permanently dropped actor may implement these filesystem effects.
+// Root reserves each chunk and commit under S3, but never opens user data.
+type actorWriteTransfer interface {
+	WriteChunk(context.Context, []byte) (MutationReceipt, Code)
+	Commit(context.Context) (MutationReceipt, Code)
+	Receipt() MutationReceipt
+	Close()
+}
+
+type retiredWriteReceipt struct {
+	operation cohortOperation
+	receipt   MutationReceipt
+	code      Code
+	unknown   bool
+}