devrites 5.14.4 → 6.0.0

package/engine/internal/overhaul/admit/packet_test.go

@@ -0,0 +1,223 @@
+package admit
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+)
+
+const packetName = "full-1__T-1__A1__implementer.json"
+
+// packetRun builds a run area named full-1 with one dispatched attempt and
+// returns the run path and the path of its valid packet.
+func packetRun(t *testing.T) (string, string) {
+	t.Helper()
+	dir := filepath.Join(t.TempDir(), "work", "full-1")
+	write(t, filepath.Join(dir, "CURRENT"), "g0001\n")
+	write(t, filepath.Join(dir, "g0001/run.json"), J{"run_id": "full-1"})
+	write(t, filepath.Join(dir, "g0001/dispatch.json"), J{"attempts": L{
+		J{"task_id": "T-1", "attempt_id": "A1", "role": "implementer", "snapshot": "s1", "status": "dispatched",
+			"receipt": "receipts/full-1__T-1__A1__implementer.json", "packet": "packets/" + packetName},
+		J{"task_id": "T-1", "attempt_id": "A0", "role": "implementer", "snapshot": "s1", "status": "admitted"},
+	}})
+	pk := write(t, filepath.Join(dir, "packets", packetName), validPacket(dir))
+	return dir, pk
+}
+
+func validPacket(dir string) J {
+	return J{"run_id": "full-1", "phase": "REMEDIATING", "task_id": "T-1", "attempt_id": "A1",
+		"role": "implementer", "lane": "backend", "snapshot": "s1", "authorized_by": "APPROVAL-1",
+		"brief": "packets/BRIEF.md", "write_paths": L{"a.go"},
+		"receipt_path": filepath.Join(dir, "receipts", "full-1__T-1__A1__implementer.json")}
+}
+
+func TestPacketAdmit(t *testing.T) {
+	cases := []struct {
+		name   string
+		mutate func(J)
+		code   int
+		want   string
+	}{
+		{"valid", func(J) {}, 0, `{"verdict": "ADMISSIBLE", "reasons": []}`},
+		{"missing snapshot", func(p J) { delete(p, "snapshot") }, 1, "missing or empty snapshot"},
+		{"missing attempt_id", func(p J) { delete(p, "attempt_id") }, 1, "missing or empty attempt_id"},
+		{"empty role", func(p J) { p["role"] = "" }, 1, "missing or empty role"},
+		{"wrong run", func(p J) { p["run_id"] = "full-2" }, 1, "run_id differs from the run"},
+		{"receipt elsewhere", func(p J) { p["receipt_path"] = "/elsewhere/r.json" }, 1, "receipt_path must be <run>/receipts/"},
+		{"snapshot mismatch", func(p J) { p["snapshot"] = "s2" }, 1, "snapshot differs from the dispatched attempt"},
+		{"role mismatch", func(p J) { p["role"] = "reviewer" }, 1, "role differs from the dispatched attempt"},
+		{"unknown attempt", func(p J) { p["attempt_id"] = "A9" }, 1, "no such dispatched attempt"},
+		{"already admitted", func(p J) { p["attempt_id"] = "A0" }, 3, `{"verdict": "DUPLICATE_OR_LATE", "attempt_status": "admitted"}`},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			dir, _ := packetRun(t)
+			p := validPacket(dir)
+			c.mutate(p)
+			// the file keeps its name so only the field under test is wrong
+			pk := write(t, filepath.Join(dir, "packets", packetName), p)
+			code, out, errs := run("packet", dir, pk)
+			if code != c.code || !strings.Contains(out, c.want) {
+				t.Fatalf("want %d with %q, got %d:\n%s%s", c.code, c.want, code, out, errs)
+			}
+		})
+	}
+}
+
+// The dispatch.json attempt records the receipt location; a packet naming
+// another run-relative receipt is not the packet that was dispatched.
+func TestPacketReceiptDiffersFromAttempt(t *testing.T) {
+	dir, pk := packetRun(t)
+	write(t, filepath.Join(dir, "g0001/dispatch.json"), J{"attempts": L{
+		J{"task_id": "T-1", "attempt_id": "A1", "role": "implementer", "snapshot": "s1", "status": "dispatched",
+			"receipt": "receipts/other.json"}}})
+	code, out, _ := run("packet", dir, pk)
+	if code != 1 || !strings.Contains(out, "receipt_path differs from the dispatched attempt's receipt") {
+		t.Fatalf("got %d: %s", code, out)
+	}
+}
+
+// The attempt also records the packet location; an attempt that recorded one
+// packet cannot admit a different file whose identifiers happen to match.
+func TestPacketPathDiffersFromAttempt(t *testing.T) {
+	dir, pk := packetRun(t)
+	write(t, filepath.Join(dir, "g0001/dispatch.json"), J{"attempts": L{
+		J{"task_id": "T-1", "attempt_id": "A1", "role": "implementer", "snapshot": "s1", "status": "dispatched",
+			"packet": "packets/other.json"}}})
+	code, out, _ := run("packet", dir, pk)
+	if code != 1 || !strings.Contains(out, "packet path differs from the dispatched attempt's packet") {
+		t.Fatalf("got %d: %s", code, out)
+	}
+}
+
+// An attempt that records no packet key predates the field and is judged on
+// the other agreements alone.
+func TestPacketAttemptWithoutPacketKey(t *testing.T) {
+	dir, pk := packetRun(t)
+	write(t, filepath.Join(dir, "g0001/dispatch.json"), J{"attempts": L{
+		J{"task_id": "T-1", "attempt_id": "A1", "role": "implementer", "snapshot": "s1", "status": "dispatched"}}})
+	code, out, errs := run("packet", dir, pk)
+	if code != 0 || !strings.Contains(out, `"verdict": "ADMISSIBLE"`) {
+		t.Fatalf("got %d: %s%s", code, out, errs)
+	}
+}
+
+// A recorded packet path that names the same file by an unclean spelling is
+// the packet that was dispatched.
+func TestPacketPathUncleanSpelling(t *testing.T) {
+	for _, rec := range []string{"packets/./" + packetName, "./packets/../packets/" + packetName} {
+		t.Run(rec, func(t *testing.T) {
+			dir, pk := packetRun(t)
+			write(t, filepath.Join(dir, "g0001/dispatch.json"), J{"attempts": L{
+				J{"task_id": "T-1", "attempt_id": "A1", "role": "implementer", "snapshot": "s1", "status": "dispatched",
+					"packet": rec}}})
+			code, out, errs := run("packet", dir, pk)
+			if code != 0 || !strings.Contains(out, `"verdict": "ADMISSIBLE"`) {
+				t.Fatalf("got %d: %s%s", code, out, errs)
+			}
+		})
+	}
+}
+
+// admit packet accepts exactly the receipt_path spellings packet.Validate
+// accepts: the run's receipts file, absolute or spelled from the working
+// directory, and nothing else.
+func TestPacketReceiptPathSpellings(t *testing.T) {
+	dir, pk := packetRun(t)
+	name := "full-1__T-1__A1__implementer.json"
+	for _, c := range []struct {
+		label, path string
+		code        int
+	}{
+		{"bare file name", name, 1},
+		{"receipts/<name>", filepath.Join("receipts", name), 1},
+		{"another run", filepath.Join("work", "full-2", "receipts", name), 1},
+		{"relative to the working directory", filepath.Join("full-1", "receipts", name), 0},
+	} {
+		t.Run(c.label, func(t *testing.T) {
+			t.Chdir(filepath.Dir(dir))
+			p := validPacket(dir)
+			p["receipt_path"] = c.path
+			write(t, pk, p)
+			code, out, errs := run("packet", dir, pk)
+			if code != c.code || (c.code == 1 && !strings.Contains(out, "receipt_path must be")) {
+				t.Fatalf("want %d, got %d: %s%s", c.code, code, out, errs)
+			}
+		})
+	}
+}
+
+// A valid packet with an absolute receipt_path is admitted from an unrelated
+// working directory with an absolute run path, and from the run's parent
+// directory with a relative run path.
+func TestPacketAdmitFromAnyCwd(t *testing.T) {
+	dir, pk := packetRun(t)
+	t.Chdir(t.TempDir())
+	if code, out, errs := run("packet", dir, pk); code != 0 {
+		t.Fatalf("absolute run: %d %s%s", code, out, errs)
+	}
+	t.Chdir(filepath.Dir(dir))
+	if code, out, errs := run("packet", "full-1", filepath.Join("full-1", "packets", packetName)); code != 0 {
+		t.Fatalf("relative run: %d %s%s", code, out, errs)
+	}
+}
+
+func TestPacketUsesWorkingGeneration(t *testing.T) {
+	dir, pk := packetRun(t)
+	stage := filepath.Join(dir, "g0002.tmp")
+	write(t, filepath.Join(stage, ".base"), "g0001")
+	write(t, filepath.Join(stage, "run.json"), J{"run_id": "full-1"})
+	write(t, filepath.Join(stage, "dispatch.json"), J{"attempts": L{}})
+	if code, out, _ := run("packet", dir, pk); code != 1 || !strings.Contains(out, "no such dispatched attempt") {
+		t.Fatalf("open stage ignored: %d %s", code, out)
+	}
+}
+
+func TestPacketSymlinkedPath(t *testing.T) {
+	dir, pk := packetRun(t)
+	link := filepath.Join(dir, "packets", "link.json")
+	if err := os.Symlink(pk, link); err != nil {
+		t.Skip(err)
+	}
+	if code, out, _ := run("packet", dir, link); code != 1 || !strings.Contains(out, "must not be a symlink") {
+		t.Fatalf("symlinked file: %d %s", code, out)
+	}
+	// a symlinked packets directory is not the run's packets directory
+	real := filepath.Join(t.TempDir(), "packets")
+	if err := os.Rename(filepath.Join(dir, "packets"), real); err != nil {
+		t.Fatal(err)
+	}
+	if err := os.Symlink(real, filepath.Join(dir, "packets")); err != nil {
+		t.Skip(err)
+	}
+	if code, out, _ := run("packet", dir, filepath.Join(dir, "packets", packetName)); code != 1 || !strings.Contains(out, "not under the run's packets directory") {
+		t.Fatalf("symlinked packets dir: %d %s", code, out)
+	}
+}
+
+func TestPacketMisplaced(t *testing.T) {
+	dir, pk := packetRun(t)
+	moved := filepath.Join(dir, "stray.json")
+	if err := os.Rename(pk, moved); err != nil {
+		t.Fatal(err)
+	}
+	code, out, _ := run("packet", dir, moved)
+	if code != 1 || !strings.Contains(out, "file name does not match") || !strings.Contains(out, "not under the run's packets directory") {
+		t.Fatalf("got %d: %s", code, out)
+	}
+}
+
+func TestPacketIOAndUsage(t *testing.T) {
+	dir, _ := packetRun(t)
+	if code, _, errs := run("packet", dir, filepath.Join(dir, "packets", "missing.json")); code != 2 || !strings.HasPrefix(errs, "ERROR: ") {
+		t.Fatalf("missing packet: %d %q", code, errs)
+	}
+	write(t, filepath.Join(dir, "packets", "bad.json"), "{not json")
+	if code, _, errs := run("packet", dir, filepath.Join(dir, "packets", "bad.json")); code != 2 || !strings.HasPrefix(errs, "ERROR: ") {
+		t.Fatalf("unparsable packet: %d %q", code, errs)
+	}
+	if code, _, errs := run("packet", dir); code != 2 || !strings.Contains(errs, "packet RUN PACKET") {
+		t.Fatalf("usage: %d %q", code, errs)
+	}
+}

package/engine/internal/overhaul/admit/run.go

@@ -2,6 +2,7 @@
 // checks for worker output.
 //
 //	receipt RUN RECEIPT [--observed FILE]   receipt vs its dispatch packet; writers vs observed paths
+//	packet RUN PACKET                       packet shape and identity vs its dispatch attempt
 //	anchor ROOT PROPOSALS                   every quoted location matches its file lines (ROOT = snapshot tree or repo)
 //
 // Exit: 0 admissible, 1 reject (reasons listed), 2 usage/IO error, 3 duplicate
@@ -30,6 +31,7 @@ import (
 const usage = `usage: overhaul admit <command> ...
 
   receipt RUN RECEIPT [--observed FILE]   receipt vs its dispatch packet; writers vs observed paths
+  packet RUN PACKET                       packet shape and identity vs its dispatch attempt
   anchor ROOT PROPOSALS                   every quoted location matches its file lines (ROOT = snapshot tree or repo)
 Exit: 0 admissible, 1 reject (reasons listed), 2 usage/IO error, 3 duplicate or late receipt.
 `
@@ -57,6 +59,8 @@ func Run(args []string, stdout, stderr io.Writer) int {
 			}
 		}
 		code, err = receipt(args[1], args[2], observed, hasObserved, stdout)
+	case len(args) == 3 && args[0] == "packet":
+		code, err = packetAdmit(args[1], args[2], stdout)
 	case len(args) >= 3 && args[0] == "anchor":
 		code, err = anchor(args[1], args[2], stdout, stderr)
 	default:

package/engine/internal/overhaul/bench/run.go

@@ -172,6 +172,9 @@ func compare(d map[string]any) (any, error) {
 	if err != nil {
 		return nil, err
 	}
+	if !(floor >= 0) {
+		return nil, fmt.Errorf("resolution must be a number >= 0, got %v", floor)
+	}
 	rng, err := seeded(d)
 	if err != nil {
 		return nil, err
@@ -207,6 +210,9 @@ func compare(d map[string]any) (any, error) {
 		hiIdx += len(boots)
 	}
 	bootLo, bootHi := boots[int(0.025*float64(len(boots)))], boots[hiIdx]
+	if math.IsInf(bootLo, 0) || math.IsInf(bootHi, 0) || math.IsNaN(bootLo) || math.IsNaN(bootHi) {
+		return noRatio{"NO_RATIO", "resampled medians reach zero: ratio interval is unbounded", ma, mb, bud, er, notes}, nil
+	}
 	lo, hi := bootLo, bootHi
 	target, err := number(d, "target", 1)
 	if err != nil {

package/engine/internal/overhaul/bench/run_test.go

@@ -142,6 +142,52 @@ func TestBench(t *testing.T) {
 	})
 }
 
+func assertFinite(t *testing.T, v any, path string) {
+	t.Helper()
+	switch x := v.(type) {
+	case float64:
+		if math.IsInf(x, 0) || math.IsNaN(x) {
+			t.Fatalf("%s is not finite: %v", path, x)
+		}
+	case []any:
+		for i, e := range x {
+			assertFinite(t, e, fmt.Sprintf("%s[%d]", path, i))
+		}
+	case map[string]any:
+		for k, e := range x {
+			assertFinite(t, e, path+"."+k)
+		}
+	}
+}
+
+func TestBenchNonFiniteInputs(t *testing.T) {
+	fast, _ := fixture()
+	someZeros := append(make([]float64, 8), gauss(rand.New(rand.NewPCG(3, 0)), 10, 0.4, 12)...)
+
+	t.Run("zero-valued resamples give a finite verdict", func(t *testing.T) {
+		for name, d := range map[string]map[string]any{
+			"lower is better":  with(fast, "candidate", someZeros),
+			"higher is better": with(fast, "direction", "higher_is_better", "baseline", someZeros, "candidate", fast["baseline"]),
+		} {
+			v, res := verdict(t, d)
+			if v != "NO_RATIO" && v != "INCONCLUSIVE" {
+				t.Fatalf("%s: got %v", name, res)
+			}
+			assertFinite(t, res, name)
+		}
+	})
+	t.Run("negative resolution is an error", func(t *testing.T) {
+		code, _, stderr := run(t, with(fast, "resolution", -1))
+		if code != 2 || !strings.Contains(stderr, "resolution") {
+			t.Fatalf("exit %d %q", code, stderr)
+		}
+	})
+	t.Run("every float of a normal result is finite", func(t *testing.T) {
+		_, res := verdict(t, fast)
+		assertFinite(t, res, "result")
+	})
+}
+
 func TestStats(t *testing.T) {
 	if k := tailCount(10, 10, 0.05); k != 24 {
 		t.Fatalf("n=m=10 alpha .05: k=%d, want 24 (Hollander-Wolfe D_(24), D_(77))", k)

package/engine/internal/overhaul/overhaul.go

@@ -1,6 +1,6 @@
 // Package overhaul dispatches the deterministic tools behind the standalone
 // /overhaul skill: run-record generations and validation, worker-output
-// admission, baseline snapshots, readiness scoring, benchmark statistics and
+// admission, dispatch packets, baseline snapshots, readiness scoring, benchmark statistics and
 // escaped offline views. It never calls a model or the network.
 package overhaul
 
@@ -10,6 +10,7 @@ import (
 
 	"github.com/devrites/devrites/internal/overhaul/admit"
 	"github.com/devrites/devrites/internal/overhaul/bench"
+	"github.com/devrites/devrites/internal/overhaul/packet"
 	"github.com/devrites/devrites/internal/overhaul/records"
 	"github.com/devrites/devrites/internal/overhaul/render"
 	"github.com/devrites/devrites/internal/overhaul/score"
@@ -25,7 +26,9 @@ const Usage = `usage: devrites-engine overhaul <tool> ...
   overhaul records publish <run>
   overhaul records validate <run>
   overhaul admit receipt <run> <receipt.json> [--observed <paths.txt>]
+  overhaul admit packet <run> <packet.json>
   overhaul admit anchor <tree> <proposals.json>
+  overhaul packet write <run> <task> <attempt> <role> [--from <fields.json>] [--phase P] [--wave W] [--lane L] [--snapshot S] [--authorized-by A] [--brief PATH] [--write-path PATH]...
   overhaul snapshot capture <repo> <out>
   overhaul snapshot fingerprint <repo>
   overhaul snapshot verify <repo> <out> [--agent-paths <file>]
@@ -50,6 +53,8 @@ func Run(args []string, stdout, stderr io.Writer) int {
 		return records.Run(rest, stdout, stderr)
 	case "admit":
 		return admit.Run(rest, stdout, stderr)
+	case "packet":
+		return packet.Run(rest, stdout, stderr)
 	case "snapshot":
 		return snapshot.Run(rest, stdout, stderr)
 	case "score":

package/engine/internal/overhaul/ovio/ovio.go

@@ -9,6 +9,7 @@ import (
 	"encoding/hex"
 	"encoding/json"
 	"fmt"
+	"io"
 	"os"
 	"path/filepath"
 	"strings"
@@ -22,11 +23,16 @@ func SHA256Bytes(b []byte) string {
 
 // SHA256File returns the lowercase hex SHA-256 of the file's exact bytes.
 func SHA256File(path string) (string, error) {
-	b, err := os.ReadFile(path) // #nosec G304 -- callers pass operator-selected run-area paths
+	f, err := os.Open(path) // #nosec G304 -- callers pass operator-selected run-area paths
 	if err != nil {
 		return "", err
 	}
-	return SHA256Bytes(b), nil
+	defer func() { _ = f.Close() }()
+	h := sha256.New()
+	if _, err := io.Copy(h, f); err != nil {
+		return "", err
+	}
+	return hex.EncodeToString(h.Sum(nil)), nil
 }
 
 // LoadJSON decodes a UTF-8 JSON document. Numbers stay json.Number so digests,
@@ -146,7 +152,8 @@ func Truthy(v any) bool {
 	case string:
 		return x != ""
 	case json.Number:
-		return x.String() != "0" && x.String() != "0.0"
+		f, err := x.Float64()
+		return err != nil || f != 0
 	case float64:
 		return x != 0
 	case []any:

package/engine/internal/overhaul/ovio/ovio_test.go

@@ -0,0 +1,75 @@
+package ovio
+
+import (
+	"bytes"
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+)
+
+func TestTruthyNumberZeroSpellingsAreFalse(t *testing.T) {
+	t.Parallel()
+	for _, n := range []json.Number{"0", "0.0", "0.00", "0.000", "-0", "-0.0", "0e0", "0e-1"} {
+		if Truthy(n) {
+			t.Errorf("Truthy(json.Number(%q)) = true, want false", n)
+		}
+	}
+}
+
+func TestTruthyNumberNonZeroValuesAreTrue(t *testing.T) {
+	t.Parallel()
+	for _, n := range []json.Number{"1", "0.5", "-1", "-0.5", "1e-3", "1e400"} {
+		if !Truthy(n) {
+			t.Errorf("Truthy(json.Number(%q)) = false, want true", n)
+		}
+	}
+}
+
+func TestTruthyNumberZeroAndNonZeroAreDistinguishable(t *testing.T) {
+	t.Parallel()
+	zero, one := Truthy(json.Number("0.00")), Truthy(json.Number("1"))
+	if zero == one {
+		t.Errorf("Truthy(json.Number(\"0.00\")) = Truthy(json.Number(\"1\")) = %v, want false and true", zero)
+	}
+}
+
+func TestTruthyMissingAndNullKeysAreFalse(t *testing.T) {
+	t.Parallel()
+	var record map[string]any
+	if err := json.Unmarshal([]byte(`{"present": 1, "explicit_null": null}`), &record); err != nil {
+		t.Fatal(err)
+	}
+	for _, key := range []string{"absent", "explicit_null"} {
+		if Truthy(Get(record, key)) {
+			t.Errorf("Truthy(Get(record, %q)) = true, want false", key)
+		}
+	}
+}
+
+func TestSHA256FileStreamsWithoutBufferingTheFile(t *testing.T) {
+	const size = 32 << 20
+	path := filepath.Join(t.TempDir(), "big.bin")
+	want := func() string {
+		data := bytes.Repeat([]byte("0123456789abcdef"), size/16)
+		if err := os.WriteFile(path, data, 0o600); err != nil {
+			t.Fatal(err)
+		}
+		return SHA256Bytes(data)
+	}()
+	var before, after runtime.MemStats
+	runtime.GC()
+	runtime.ReadMemStats(&before)
+	got, err := SHA256File(path)
+	runtime.ReadMemStats(&after)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got != want {
+		t.Errorf("SHA256File digest = %s, want %s", got, want)
+	}
+	if delta := after.TotalAlloc - before.TotalAlloc; delta > 1<<20 {
+		t.Errorf("SHA256File allocated %d bytes for a %d byte file, want under 1MiB", delta, size)
+	}
+}

package/engine/internal/overhaul/packet/packet.go

@@ -0,0 +1,208 @@
+// Package packet implements the /overhaul packet tool: it writes the dispatch
+// packet for one worker attempt and validates packets on load.
+//
+//	write RUN TASK ATTEMPT ROLE [flags]   create RUN/packets/<run>__<task>__<attempt>__<role>.json
+//
+// A packet is a JSON object. Flags fill the common fields; --from FILE supplies
+// any further fields (plan, task, read paths, budgets) and flags override it.
+// Exit: 0 written, 1 invalid packet or packet already exists, 2 usage/IO error.
+package packet
+
+import (
+	"flag"
+	"fmt"
+	"io"
+	"os"
+	"path/filepath"
+	"strings"
+
+	"github.com/devrites/devrites/internal/overhaul/ovio"
+)
+
+const usage = `usage: overhaul packet <command> ...
+
+  write RUN TASK ATTEMPT ROLE [--from FILE] [--phase P] [--wave W] [--lane L]
+        [--snapshot S] [--authorized-by A] [--brief PATH] [--write-path PATH]...
+Exit: 0 written, 1 invalid packet or packet already exists, 2 usage/IO error.
+`
+
+// required are the string fields every packet carries.
+var required = []string{"run_id", "phase", "task_id", "attempt_id", "role", "lane", "snapshot", "authorized_by", "brief", "receipt_path"}
+
+// idFields name the path components of a packet file and must be plain names.
+var idFields = []string{"run_id", "task_id", "attempt_id", "role"}
+
+type multi []string
+
+func (m *multi) String() string     { return strings.Join(*m, ",") }
+func (m *multi) Set(s string) error { *m = append(*m, s); return nil }
+
+// Run executes the tool with its arguments (tool name excluded).
+func Run(args []string, stdout, stderr io.Writer) int {
+	if len(args) < 5 || args[0] != "write" {
+		fmt.Fprint(stderr, usage)
+		return 2
+	}
+	fs := flag.NewFlagSet("packet write", flag.ContinueOnError)
+	fs.SetOutput(stderr)
+	from := fs.String("from", "", "JSON object with further packet fields")
+	set := map[string]*string{}
+	for flagName, field := range map[string]string{
+		"phase": "phase", "wave": "wave", "lane": "lane", "snapshot": "snapshot",
+		"authorized-by": "authorized_by", "brief": "brief",
+	} {
+		set[field] = fs.String(flagName, "", field)
+	}
+	var paths multi
+	fs.Var(&paths, "write-path", "exact path the worker may write (repeatable)")
+	if err := fs.Parse(args[5:]); err != nil {
+		return 2
+	}
+	if fs.NArg() > 0 {
+		fmt.Fprintf(stderr, "ERROR: unexpected argument %q\n", fs.Arg(0))
+		return 2
+	}
+	run := args[1]
+	p := map[string]any{}
+	if *from != "" {
+		m, err := ovio.LoadObject(*from)
+		if err != nil {
+			fmt.Fprintf(stderr, "ERROR: %v\n", err)
+			return 2
+		}
+		p = m
+	}
+	p["run_id"], p["task_id"], p["attempt_id"], p["role"] = filepath.Base(filepath.Clean(run)), args[2], args[3], args[4]
+	for field, v := range set {
+		if *v != "" {
+			p[field] = *v
+		}
+	}
+	if _, ok := p["write_paths"]; !ok || len(paths) > 0 {
+		wp := []any{}
+		for _, w := range paths {
+			wp = append(wp, w)
+		}
+		p["write_paths"] = wp
+	}
+	if ovio.Str(p["receipt_path"]) == "" {
+		p["receipt_path"] = filepath.Join(run, "receipts", Name(p)+".json")
+	}
+	if why := Validate(run, p); len(why) > 0 {
+		for _, w := range why {
+			fmt.Fprintf(stderr, "REJECT: %s\n", w)
+		}
+		return 1
+	}
+	out, code, err := write(run, p)
+	if err != nil {
+		fmt.Fprintf(stderr, "ERROR: %v\n", err)
+		return code
+	}
+	fmt.Fprintln(stdout, out)
+	return 0
+}
+
+// Name is the packet file stem: <run>__<task>__<attempt>__<role>.
+func Name(p map[string]any) string {
+	return strings.Join([]string{ovio.Str(p["run_id"]), ovio.Str(p["task_id"]), ovio.Str(p["attempt_id"]), ovio.Str(p["role"])}, "__")
+}
+
+// Validate returns every reason the packet is malformed for the run area run;
+// none means valid. receipt_path must be a clean path that resolves to <run>/receipts/<name>.json.
+func Validate(run string, p map[string]any) []string {
+	var why []string
+	for _, k := range required {
+		if ovio.Str(p[k]) == "" {
+			why = append(why, "missing or empty "+k)
+		}
+	}
+	for _, k := range idFields {
+		if s := ovio.Str(p[k]); s == "." || s == ".." || strings.ContainsAny(s, `/\`+"\x00") || strings.Contains(s, "__") {
+			why = append(why, k+" must be a plain name without path separators or \"__\"")
+		}
+	}
+	if rp := ovio.Str(p["receipt_path"]); rp != "" && !samePath(rp, filepath.Join(run, "receipts", Name(p)+".json")) {
+		why = append(why, "receipt_path must be <run>/receipts/<run_id>__<task_id>__<attempt_id>__<role>.json")
+	}
+	if w, ok := p["write_paths"].([]any); !ok {
+		why = append(why, "write_paths must be an array (empty for read-only roles)")
+	} else if len(ovio.Strings(w)) != len(w) {
+		why = append(why, "write_paths must hold only strings")
+	}
+	if pl, ok := p["plan"]; ok && ovio.Str(ovio.Obj(pl)["file"]) == "" {
+		why = append(why, "plan must be an object with a file")
+	}
+	return why
+}
+
+// samePath reports whether a is the clean spelling of the location b names.
+func samePath(a, b string) bool {
+	x, err1 := filepath.Abs(a)
+	y, err2 := filepath.Abs(b)
+	return err1 == nil && err2 == nil && a == filepath.Clean(a) && x == y
+}
+
+// Load reads a packet file and validates it against the run area that holds
+// its packets/ directory, including that the file name matches the packet's
+// own identifiers.
+func Load(path string) (map[string]any, error) {
+	p, err := ovio.LoadObject(path)
+	if err != nil {
+		return nil, err
+	}
+	why := Validate(filepath.Dir(filepath.Dir(path)), p)
+	if len(why) == 0 && filepath.Base(path) != Name(p)+".json" {
+		why = append(why, "file name does not match run_id, task_id, attempt_id and role")
+	}
+	if len(why) > 0 {
+		return nil, fmt.Errorf("%s: %s", path, strings.Join(why, "; "))
+	}
+	return p, nil
+}
+
+// write publishes the packet atomically and never replaces an existing one:
+// the content is written to a temporary file that is then hard-linked into place.
+func write(run string, p map[string]any) (string, int, error) {
+	if !realDir(run) {
+		return "", 2, fmt.Errorf("run area %s is not a directory", run)
+	}
+	dir := filepath.Join(run, "packets")
+	if err := os.MkdirAll(dir, 0o700); err != nil {
+		return "", 2, err
+	}
+	if !realDir(dir) {
+		return "", 2, fmt.Errorf("%s is not a plain directory", dir)
+	}
+	b, err := ovio.MarshalIndent(p)
+	if err != nil {
+		return "", 2, err
+	}
+	tmp, err := os.CreateTemp(dir, ".packet-*.tmp")
+	if err != nil {
+		return "", 2, err
+	}
+	defer func() { _ = os.Remove(tmp.Name()) }()
+	if _, err := tmp.Write(b); err != nil {
+		_ = tmp.Close()
+		return "", 2, err
+	}
+	if err := tmp.Close(); err != nil {
+		return "", 2, err
+	}
+	dest := filepath.Join(dir, Name(p)+".json")
+	if err := os.Link(tmp.Name(), dest); err != nil {
+		if os.IsExist(err) {
+			return "", 1, fmt.Errorf("packet %s already exists", dest)
+		}
+		return "", 2, err
+	}
+	return dest, 0, nil
+}
+
+// realDir reports whether path is a directory and not a symlink to one, so a
+// packet is never written through a link out of the run area.
+func realDir(path string) bool {
+	st, err := os.Lstat(filepath.Clean(path))
+	return err == nil && st.IsDir()
+}