devrites 5.12.0 → 5.13.0

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

@@ -0,0 +1,416 @@
+// Package admit implements the /overhaul admit tool: read-only admission
+// checks for worker output.
+//
+//	receipt RUN RECEIPT [--observed FILE]   receipt vs its dispatch packet; writers vs observed paths
+//	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. Nothing here edits canonical records; the coordinator
+// records the verdict in a staged generation.
+package admit
+
+import (
+	"encoding/json"
+	"fmt"
+	"io"
+	"math"
+	"os"
+	"path/filepath"
+	"slices"
+	"sort"
+	"strconv"
+	"strings"
+	"unicode/utf16"
+	"unicode/utf8"
+
+	"github.com/devrites/devrites/internal/overhaul/ovio"
+	"github.com/devrites/devrites/internal/overhaul/records"
+)
+
+const usage = `usage: overhaul admit <command> ...
+
+  receipt RUN RECEIPT [--observed FILE]   receipt vs its dispatch packet; writers vs observed paths
+  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.
+`
+
+var (
+	writers  = map[string]bool{"implementer": true}
+	outcomes = []string{"findings", "gap", "no-findings", "patch", "verdict"} // sorted
+)
+
+// Run executes the tool with its arguments (tool name excluded).
+func Run(args []string, stdout, stderr io.Writer) int {
+	var code int
+	var err error
+	switch {
+	case len(args) >= 3 && args[0] == "receipt":
+		observed, hasObserved := "", false
+		for i, a := range args {
+			if a == "--observed" {
+				if i+1 >= len(args) {
+					fmt.Fprint(stderr, usage)
+					return 2
+				}
+				observed, hasObserved = args[i+1], true
+				break
+			}
+		}
+		code, err = receipt(args[1], args[2], observed, hasObserved, stdout)
+	case len(args) >= 3 && args[0] == "anchor":
+		code, err = anchor(args[1], args[2], stdout, stderr)
+	default:
+		fmt.Fprint(stderr, usage)
+		return 2
+	}
+	if err != nil {
+		fmt.Fprintf(stderr, "ERROR: %v\n", err)
+		return 2
+	}
+	return code
+}
+
+// join mirrors os.path.join: an absolute part replaces everything before it.
+func join(base, rel string) string {
+	switch {
+	case strings.HasPrefix(rel, "/"):
+		return rel
+	case base == "" || strings.HasSuffix(base, "/"):
+		return base + rel
+	}
+	return base + "/" + rel
+}
+
+func realpath(p string) string {
+	abs, err := filepath.Abs(p)
+	if err != nil {
+		abs = p
+	}
+	return ovio.Resolve(abs)
+}
+
+// pyJSON renders s like Python's json.dumps (ensure_ascii=True).
+func pyJSON(s string) string {
+	var b strings.Builder
+	b.WriteByte('"')
+	for _, r := range s {
+		switch r {
+		case '"':
+			b.WriteString(`\"`)
+		case '\\':
+			b.WriteString(`\\`)
+		case '\n':
+			b.WriteString(`\n`)
+		case '\r':
+			b.WriteString(`\r`)
+		case '\t':
+			b.WriteString(`\t`)
+		case '\b':
+			b.WriteString(`\b`)
+		case '\f':
+			b.WriteString(`\f`)
+		default:
+			switch {
+			case r > 0xffff:
+				r1, r2 := utf16.EncodeRune(r)
+				fmt.Fprintf(&b, `\u%04x\u%04x`, r1, r2)
+			case r < 0x20 || r > 0x7e:
+				fmt.Fprintf(&b, `\u%04x`, r)
+			default:
+				b.WriteRune(r)
+			}
+		}
+	}
+	b.WriteByte('"')
+	return b.String()
+}
+
+func pyValue(v any) string {
+	switch x := v.(type) {
+	case string:
+		return pyJSON(x)
+	case []string:
+		parts := make([]string, len(x))
+		for i, s := range x {
+			parts[i] = pyJSON(s)
+		}
+		return "[" + strings.Join(parts, ", ") + "]"
+	}
+	b, _ := json.Marshal(v)
+	return string(b)
+}
+
+// verdict prints {"verdict": v, <key>: val} exactly as Python's json.dumps does.
+func verdict(w io.Writer, v, key string, val any) {
+	fmt.Fprintf(w, "{\"verdict\": %s, %s: %s}\n", pyJSON(v), pyJSON(key), pyValue(val))
+}
+
+func keyed(m any, k string) (any, error) {
+	o, ok := m.(map[string]any)
+	if !ok {
+		return nil, fmt.Errorf("'%s': parent is not an object", k)
+	}
+	v, ok := o[k]
+	if !ok {
+		return nil, fmt.Errorf("'%s'", k)
+	}
+	return v, nil
+}
+
+// strSet collects string members keyed by records.Repr (non-strings never match paths).
+func strSet(vals []any) map[string]any {
+	s := map[string]any{}
+	for _, v := range vals {
+		s[records.Repr(v)] = v
+	}
+	return s
+}
+
+func sortedVals(s map[string]any) []any {
+	out := make([]any, 0, len(s))
+	for _, v := range s {
+		out = append(out, v)
+	}
+	sort.Slice(out, func(i, j int) bool { return records.PyStr(out[i]) < records.PyStr(out[j]) })
+	return out
+}
+
+func receipt(run, path, observed string, hasObserved bool, stdout io.Writer) (int, error) {
+	cur, err := os.ReadFile(join(run, "CURRENT"))
+	if err != nil {
+		return 0, err
+	}
+	gen := join(run, strings.TrimSpace(string(cur)))
+	rj, err := ovio.LoadObject(join(gen, "run.json"))
+	if err != nil {
+		return 0, err
+	}
+	disp, err := ovio.LoadObject(join(gen, "dispatch.json"))
+	if err != nil {
+		return 0, err
+	}
+	rc, err := ovio.LoadObject(path)
+	if err != nil {
+		return 0, err
+	}
+	eq := func(a, b any) bool { return records.Repr(a) == records.Repr(b) }
+	var why []string
+	var x map[string]any
+	for _, it := range ovio.List(disp["attempts"]) {
+		if a := ovio.Obj(it); eq(a["task_id"], rc["task_id"]) && eq(a["attempt_id"], rc["attempt_id"]) {
+			x = a
+			break
+		}
+	}
+	if ovio.Str(rc["schema"]) != "overhaul.receipt/1" || !eq(rc["run_id"], rj["run_id"]) {
+		why = append(why, "wrong schema or run")
+	}
+	if x == nil {
+		why = append(why, "no such dispatched attempt")
+	} else {
+		if s := ovio.Str(x["status"]); s == "admitted" || s == "rejected" || s == "cancelled" {
+			verdict(stdout, "DUPLICATE_OR_LATE", "attempt_status", x["status"])
+			return 3, nil
+		}
+		for _, k := range []string{"role", "lane", "snapshot"} {
+			if !eq(rc[k], x[k]) {
+				why = append(why, k+" differs from the dispatch packet")
+			}
+		}
+		for _, k := range []string{"started_at", "finished_at"} {
+			if !ovio.Truthy(rc[k]) {
+				why = append(why, "missing "+k)
+			}
+		}
+		if !slices.Contains(outcomes, ovio.Str(rc["outcome"])) {
+			why = append(why, "outcome must be one of "+records.Repr(outcomes))
+		}
+		if ovio.Str(rc["outcome"]) == "no-findings" && !ovio.Truthy(rc["inspected"]) {
+			why = append(why, "no-findings without inspected ranges is malformed")
+		}
+		if writers[ovio.Str(x["role"])] {
+			v, err := keyed(rj, "revisions")
+			if err == nil {
+				v, err = keyed(v, "plan")
+			}
+			if err == nil {
+				v, err = keyed(v, "file")
+			}
+			if err != nil {
+				return 0, err
+			}
+			plan, err := ovio.LoadObject(join(run, ovio.Str(v)))
+			if err != nil {
+				return 0, err
+			}
+			allowed := map[string]any{}
+			for _, t := range ovio.List(plan["tasks"]) {
+				if tm := ovio.Obj(t); eq(tm["id"], x["task_id"]) {
+					for k, p := range strSet(ovio.List(tm["allowed_paths"])) {
+						allowed[k] = p
+					}
+				}
+			}
+			claimed := strSet(ovio.List(rc["changed_paths"]))
+			outside := map[string]any{}
+			for k, p := range claimed {
+				if _, ok := allowed[k]; !ok {
+					outside[k] = p
+				}
+			}
+			if len(outside) > 0 {
+				why = append(why, "changed paths outside contract: "+records.Repr(sortedVals(outside)))
+			}
+			if !hasObserved {
+				why = append(why, "writer receipt needs observed changed paths (--observed)")
+			} else {
+				b, err := os.ReadFile(observed) // #nosec G304 -- observed-paths file is an explicit operator argument
+				if err != nil {
+					return 0, err
+				}
+				text := strings.NewReplacer("\r\n", "\n", "\r", "\n").Replace(string(b)) // universal newlines
+				seen := map[string]any{}
+				for _, ln := range strings.Split(text, "\n") {
+					if ln = strings.TrimSpace(ln); ln != "" {
+						seen[records.Repr(ln)] = ln
+					}
+				}
+				same := len(seen) == len(claimed)
+				for k := range seen {
+					if _, ok := claimed[k]; !ok {
+						same = false
+					}
+				}
+				if !same {
+					why = append(why, fmt.Sprintf("observed paths %s differ from claimed %s",
+						records.Repr(sortedVals(seen)), records.Repr(sortedVals(claimed))))
+				}
+			}
+		}
+	}
+	return result(stdout, why, "ADMISSIBLE"), nil
+}
+
+func result(stdout io.Writer, why []string, ok string) int {
+	if why == nil {
+		why = []string{}
+	}
+	if len(why) > 0 {
+		verdict(stdout, "REJECT", "reasons", why)
+		return 1
+	}
+	verdict(stdout, ok, "reasons", why)
+	return 0
+}
+
+// splitlines is Python's str.splitlines().
+func splitlines(s string) []string {
+	var out []string
+	start := 0
+	for i := 0; i < len(s); {
+		r, size := utf8.DecodeRuneInString(s[i:])
+		i += size
+		switch r {
+		case '\n', '\r', '\v', '\f', 0x1c, 0x1d, 0x1e, 0x85, 0x2028, 0x2029:
+			out = append(out, s[start:i-size])
+			if r == '\r' && i < len(s) && s[i] == '\n' {
+				i++
+			}
+			start = i
+		}
+	}
+	if start < len(s) {
+		out = append(out, s[start:])
+	}
+	return out
+}
+
+// pyInt is Python's int() on a decoded JSON value.
+func pyInt(v any) (int, error) {
+	switch x := v.(type) {
+	case json.Number:
+		if i, err := x.Int64(); err == nil {
+			return int(i), nil
+		}
+		f, err := x.Float64()
+		if err != nil || math.IsInf(f, 0) || math.IsNaN(f) {
+			return 0, fmt.Errorf("invalid line number %s", x)
+		}
+		return int(f), nil
+	case string:
+		i, err := strconv.Atoi(strings.TrimSpace(x))
+		if err != nil {
+			return 0, fmt.Errorf("invalid literal for int() with base 10: %s", records.Repr(x))
+		}
+		return i, nil
+	case bool:
+		if x {
+			return 1, nil
+		}
+		return 0, nil
+	}
+	return 0, fmt.Errorf("int() argument must be a string or a number, not %s", records.Repr(v))
+}
+
+func anchor(root, path string, stdout, stderr io.Writer) (int, error) {
+	doc, err := ovio.LoadJSON(path)
+	if err != nil {
+		return 0, err
+	}
+	items, ok := ovio.Obj(doc)["findings"].([]any)
+	if !ok || len(items) == 0 {
+		fmt.Fprintln(stderr, `ERROR: expected {"findings": [...]} with at least one finding`)
+		return 2, nil
+	}
+	why := []string{}
+	base := realpath(root)
+	for _, it := range items {
+		f := ovio.Obj(it)
+		id := records.PyStr(f["id"])
+		if !ovio.Truthy(f["locations"]) {
+			why = append(why, id+": no locations to anchor")
+		}
+		for _, l := range ovio.List(f["locations"]) {
+			loc := ovio.Obj(l)
+			rel, quote := ovio.Str(loc["path"]), ovio.Str(loc["quote"])
+			full := realpath(join(base, rel))
+			if fi, err := os.Stat(full); !strings.HasPrefix(full, base+string(os.PathSeparator)) || err != nil || !fi.Mode().IsRegular() {
+				why = append(why, fmt.Sprintf("%s: %s is not a file under the reviewed tree", id, rel))
+				continue
+			}
+			b, err := os.ReadFile(full) // #nosec G304 -- anchor path checked to stay inside the reviewed tree
+			if err != nil {
+				return 0, err
+			}
+			lines := splitlines(strings.ToValidUTF8(string(b), "�"))
+			start, ok := loc["start"]
+			if !ok {
+				start = json.Number("0")
+			}
+			end, ok := loc["end"]
+			if !ok {
+				end = start
+			}
+			s, err := pyInt(start)
+			if err != nil {
+				return 0, err
+			}
+			e, err := pyInt(end)
+			if err != nil {
+				return 0, err
+			}
+			if !(1 <= s && s <= e && e <= len(lines)) {
+				why = append(why, fmt.Sprintf("%s: %s lines %d-%d outside file (%d lines)", id, rel, s, e, len(lines)))
+				continue
+			}
+			q := strings.Join(strings.Fields(quote), " ")
+			w := strings.Join(strings.Fields(strings.Join(lines[s-1:e], " ")), " ")
+			if q == "" || !strings.Contains(w, q) {
+				why = append(why, fmt.Sprintf("%s: quote not found at %s:%d-%d", id, rel, s, e))
+			} else if utf8.RuneCountInString(strings.ReplaceAll(q, " ", "")) < 8 && q != w {
+				why = append(why, fmt.Sprintf("%s: quote at %s:%d is too short to anchor; quote the whole line", id, rel, s))
+			}
+		}
+	}
+	return result(stdout, why, "ANCHORED"), nil
+}

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

@@ -0,0 +1,248 @@
+// Package bench implements the /overhaul bench tool: ratio of medians with a
+// seeded percentile-bootstrap 95% confidence interval.
+//
+// Input: {"direction": "lower_is_better"|"higher_is_better", "baseline": [...],
+// "candidate": [...], "order": ["A","B",...], "target": 2.0, "materiality": 1.05,
+// "resamples": 10000, "seed": 1, "resolution": 0}. The unit of resampling is one
+// independent invocation per sample; never pass inner iterations. A k-fold claim
+// is supported only when the CI lower bound >= k.
+package bench
+
+import (
+	"encoding/json"
+	"errors"
+	"fmt"
+	"io"
+	"math"
+	"math/rand/v2"
+	"reflect"
+	"sort"
+	"strconv"
+	"strings"
+
+	"github.com/devrites/devrites/internal/overhaul/ovio"
+)
+
+const usage = "usage: devrites-engine overhaul bench <result.json>\n"
+
+// Run executes the tool with its arguments (tool name excluded).
+func Run(args []string, stdout, stderr io.Writer) int {
+	if len(args) != 1 {
+		fmt.Fprint(stderr, usage)
+		return 2
+	}
+	d, err := ovio.LoadObject(args[0])
+	var res any
+	if err == nil {
+		res, err = compare(d)
+	}
+	var out []byte
+	if err == nil {
+		out, err = ovio.MarshalIndent(res)
+	}
+	if err != nil {
+		fmt.Fprintf(stderr, "ERROR: %v\n", err)
+		return 2
+	}
+	_, _ = stdout.Write(out)
+	return 0
+}
+
+type result struct {
+	Verdict         string     `json:"verdict"`
+	Ratio           float64    `json:"ratio"`
+	CI95            [2]float64 `json:"ci95"`
+	BaselineMedian  float64    `json:"baseline_median"`
+	CandidateMedian float64    `json:"candidate_median"`
+	AbsoluteDelta   float64    `json:"absolute_delta"`
+	PercentChange   float64    `json:"percent_change"`
+	N               [2]int     `json:"n"`
+	Target          float64    `json:"target"`
+	Materiality     float64    `json:"materiality"`
+	Notes           []string   `json:"notes"`
+}
+
+type noRatio struct {
+	Verdict         string   `json:"verdict"`
+	Reason          string   `json:"reason"`
+	BaselineMedian  float64  `json:"baseline_median"`
+	CandidateMedian float64  `json:"candidate_median"`
+	Notes           []string `json:"notes"`
+}
+
+const (
+	noteFew     = "fewer than 10 invocations per arm: exploratory only"
+	noteBlocked = "arms not recorded as interleaved: contamination risk, verdict capped at inconclusive"
+)
+
+func compare(d map[string]any) (any, error) {
+	dir := d["direction"]
+	if dir != "lower_is_better" && dir != "higher_is_better" {
+		return nil, fmt.Errorf("direction must be lower_is_better or higher_is_better, got %#v", dir)
+	}
+	lower := dir == "lower_is_better"
+	a, err := samples(d, "baseline")
+	if err != nil {
+		return nil, err
+	}
+	b, err := samples(d, "candidate")
+	if err != nil {
+		return nil, err
+	}
+	if len(a) == 0 || len(b) == 0 {
+		return nil, errors.New("no median for empty data")
+	}
+	notes := []string{}
+	n := min(len(a), len(b))
+	if n < 10 {
+		notes = append(notes, noteFew)
+	}
+	order := ovio.List(d["order"])
+	switches := 0
+	for i := 1; i < len(order); i++ {
+		if !reflect.DeepEqual(order[i-1], order[i]) {
+			switches++
+		}
+	}
+	if len(order) != len(a)+len(b) || switches < n/2 {
+		notes = append(notes, noteBlocked)
+	}
+	ma, mb := median(a), median(b)
+	floor, err := number(d, "resolution", 0)
+	if err != nil {
+		return nil, err
+	}
+	if min(ma, mb) <= floor {
+		return noRatio{"NO_RATIO", "median at or below measurement resolution", ma, mb, notes}, nil
+	}
+	seed := int64(1)
+	if v, ok := d["seed"]; ok {
+		num, isNum := v.(json.Number)
+		s, err := num.Int64()
+		if !isNum || err != nil {
+			return nil, fmt.Errorf("seed must be an integer, got %v", v)
+		}
+		seed = s
+	}
+	resamples, err := number(d, "resamples", 10000)
+	if err != nil {
+		return nil, err
+	}
+	if int(resamples) < 1 {
+		return nil, fmt.Errorf("resamples must be at least 1, got %v", resamples)
+	}
+	rng := rand.New(rand.NewPCG(uint64(seed), 0)) // #nosec G404 -- bootstrap resampling needs a seeded, reproducible PRNG, not secrecy
+	boots := make([]float64, int(resamples))
+	ra, rb := make([]float64, len(a)), make([]float64, len(b))
+	for i := range boots {
+		for j := range ra {
+			ra[j] = a[rng.IntN(len(a))]
+		}
+		for j := range rb {
+			rb[j] = b[rng.IntN(len(b))]
+		}
+		boots[i] = ratio(median(ra), median(rb), lower)
+	}
+	sort.Float64s(boots)
+	hiIdx := int(0.975*float64(len(boots))) - 1
+	if hiIdx < 0 { // Python's boots[-1]
+		hiIdx += len(boots)
+	}
+	lo, hi := boots[int(0.025*float64(len(boots)))], boots[hiIdx]
+	target, err := number(d, "target", 1)
+	if err != nil {
+		return nil, err
+	}
+	mat, err := number(d, "materiality", 1)
+	if err != nil {
+		return nil, err
+	}
+	var verdict string
+	switch {
+	case hi < 1:
+		verdict = "REGRESSION"
+	case lo >= target && target > 1:
+		verdict = "SUPPORTS_TARGET"
+	case lo >= mat && lo > 1 && target > 1:
+		verdict = "IMPROVEMENT_BELOW_TARGET"
+	case lo >= mat && lo > 1:
+		verdict = "IMPROVEMENT"
+	default:
+		verdict = "INCONCLUSIVE"
+	}
+	if len(notes) > 0 && verdict != "REGRESSION" {
+		verdict = "INCONCLUSIVE"
+	}
+	delta := mb - ma
+	return result{
+		Verdict: verdict, Ratio: round(ratio(ma, mb, lower), 4), CI95: [2]float64{round(lo, 4), round(hi, 4)},
+		BaselineMedian: ma, CandidateMedian: mb, AbsoluteDelta: delta,
+		PercentChange: round(100*delta/ma, 2), N: [2]int{len(a), len(b)},
+		Target: target, Materiality: mat, Notes: notes,
+	}, nil
+}
+
+func ratio(base, cand float64, lowerBetter bool) float64 {
+	if lowerBetter {
+		return base / cand
+	}
+	return cand / base
+}
+
+func median(xs []float64) float64 {
+	s := append([]float64(nil), xs...)
+	sort.Float64s(s)
+	m := len(s) / 2
+	if len(s)%2 == 1 {
+		return s[m]
+	}
+	return (s[m-1] + s[m]) / 2
+}
+
+func round(x float64, places int) float64 {
+	p := math.Pow(10, float64(places))
+	return math.Round(x*p) / p
+}
+
+func samples(d map[string]any, key string) ([]float64, error) {
+	v, ok := d[key]
+	if !ok {
+		return nil, fmt.Errorf("missing %q", key)
+	}
+	list, ok := v.([]any)
+	if !ok {
+		return nil, fmt.Errorf("%s must be an array", key)
+	}
+	out := make([]float64, len(list))
+	for i, x := range list {
+		f, err := toFloat(x, key)
+		if err != nil {
+			return nil, err
+		}
+		out[i] = f
+	}
+	return out, nil
+}
+
+func number(d map[string]any, key string, def float64) (float64, error) {
+	v, ok := d[key]
+	if !ok {
+		return def, nil
+	}
+	return toFloat(v, key)
+}
+
+// toFloat accepts JSON numbers and numeric strings, like Python's float().
+func toFloat(v any, key string) (float64, error) {
+	switch x := v.(type) {
+	case json.Number:
+		return x.Float64()
+	case string:
+		f, err := strconv.ParseFloat(strings.TrimSpace(x), 64)
+		if err != nil {
+			return 0, fmt.Errorf("%s: could not convert %q to float", key, x)
+		}
+		return f, nil
+	}
+	return 0, fmt.Errorf("%s: expected a number, got %v", key, v)
+}