From 42bd7b802ac2e270540ef035b01c080825438f88 Mon Sep 17 00:00:00 2001 From: jochen Date: Tue, 3 Nov 2026 12:39:29 +0100 Subject: [PATCH] A manifest whose judge does not know a field has the verdict waits, held like a refusal by every reader (ADR 0578); in a modules value it is written as a refusal naming the fields, so a reader pinned before holds it too --- go/delivery/source.go | 9 +++++ go/delivery/verdicts.go | 64 ++++++++++++++++++++++++++++++++---- go/delivery/verdicts_test.go | 37 +++++++++++++++++++++ 3 files changed, 103 insertions(+), 7 deletions(-) diff --git a/go/delivery/source.go b/go/delivery/source.go index dac8338..c872d5a 100644 --- a/go/delivery/source.go +++ b/go/delivery/source.go @@ -431,6 +431,10 @@ type Module struct { // that state. Empty in a value written before the indexer judged, which a reader takes as accepted (TakeManifestVerdict). Verdict string `json:"verdict,omitempty"` Problems []string `json:"problems,omitempty"` + // Unknown are the fields of Manifest the judge does not know. A manifest that waits for them (VerdictManifestWaits) is + // written here as a refusal whose Problems say what it waits on and whose Unknown names the fields: a reader pinned + // before the verdict waits holds it as a refused one, and VerdictOf gives a reader that knows it the verdict waits. + Unknown []string `json:"unknown,omitempty"` // Warnings are the problems of an accepted manifest a stricter judge outgrew (novox/hq ADR 0579 §1): Verdict is then // empty (accepted), and the watchman raises delivery.ManifestOutgrown until the manifest is mended. Warnings []string `json:"warnings,omitempty"` @@ -444,6 +448,9 @@ func (m Module) VerdictOf(module string) *ManifestVerdict { if m.Verdict == "" { return &ManifestVerdict{Module: module, State: VerdictAccepted, Warnings: m.Warnings} } + if m.Verdict == VerdictRefused && len(m.Unknown) > 0 { + return &ManifestVerdict{Module: module, State: VerdictManifestWaits, Unknown: m.Unknown} + } return &ManifestVerdict{Module: module, State: m.Verdict, Problems: m.Problems} } @@ -538,6 +545,8 @@ func (m Module) check() error { switch { case m.Verdict != "" && m.Verdict != VerdictAccepted && m.Verdict != VerdictRefused: return fmt.Errorf("delivery: the module's verdict %q is neither %s nor %s", m.Verdict, VerdictAccepted, VerdictRefused) + case len(m.Unknown) > 0 && m.Verdict != VerdictRefused: + return fmt.Errorf("delivery: a module's unknown fields are named only with the refusal a wait is written as") case m.Verdict != "" && m.Manifest == "": return fmt.Errorf("delivery: a module carries a verdict and no manifest digest") case (m.Verdict == VerdictRefused) != (len(m.Problems) > 0): diff --git a/go/delivery/verdicts.go b/go/delivery/verdicts.go index 15a6a9c..322834c 100644 --- a/go/delivery/verdicts.go +++ b/go/delivery/verdicts.go @@ -4,6 +4,7 @@ import ( "encoding/json" "fmt" "slices" + "strings" "time" ) @@ -24,6 +25,14 @@ const ( // VerdictRefused is the state of a manifest the judge found a problem in; Problems says each. VerdictRefused = "refused" + // VerdictManifestWaits is the state of a MANIFEST's verdict (not a proposal's: VerdictWaits, in placement_proposal.go, + // has the same word for a different thing, which is why this one carries Manifest in its name). It is the state of a + // manifest that carries a field the indexer's judge does not know (novox/hq ADR 0578 §1, amended): the manifest is not + // refused, because a newer judge may know the field; Unknown names each field. A reader holds a module whose manifest + // waits as it holds a refused one (ManifestVerdict.Held) and keeps what runs. In a modules value it is written as a + // refusal naming the fields (Module.Unknown), for readers that do not know this state. + VerdictManifestWaits = "waits" + // ManifestRefusedEvent is the indexer's event saying a manifest was refused (ManifestRefused), so the watchman // raises it as a condition beside the indexer's finding. ManifestRefusedEvent = "manifest-refused" @@ -32,6 +41,10 @@ const ( // (novox/hq ADR 0579 §1): it stays accepted, its problems are the verdict's Warnings, and the watchman raises it as a // warning until the manifest is mended. ManifestOutgrown = "manifest-outgrown" + + // ManifestWaits is the finding of a manifest whose verdict waits (VerdictManifestWaits): the watchman raises it as a warning + // until a judge knows the fields or the manifest is mended. + ManifestWaits = "manifest-waits" ) // ManifestVerdict is the value of a verdicts key: the module whose manifest it is, accepted or refused, every problem the judge @@ -41,6 +54,8 @@ type ManifestVerdict struct { Module string `json:"module"` State string `json:"state"` Problems []string `json:"problems,omitempty"` + // Unknown are the fields of a manifest the judge does not know, named when the state is VerdictManifestWaits and nowhere else. + Unknown []string `json:"unknown,omitempty"` // Warnings are the problems a stricter judge found in a manifest it accepted before, digest unchanged (novox/hq ADR // 0579 §1): the verdict stays accepted. Warnings []string `json:"warnings,omitempty"` @@ -51,16 +66,36 @@ type ManifestVerdict struct { // Refused is whether v refuses its manifest. func (v ManifestVerdict) Refused() bool { return v.State == VerdictRefused } -// Same is whether v and o say the same of a manifest: the module, the state and the problems, whoever judged and when. +// Waits is whether v says the manifest waits for a judge that knows its fields. +func (v ManifestVerdict) Waits() bool { return v.State == VerdictManifestWaits } + +// Held is whether a reader holds the module as refused: the manifest is refused or waits. +func (v ManifestVerdict) Held() bool { return v.Refused() || v.Waits() } + +// AsRefused is v as a reader pinned before the verdict waits takes it: a waiting verdict is a refusal naming what it waits +// on, any other verdict is v. For a part that hands a verdict to a program it does not deliver with itself (the checker's +// sandbox composer). +func (v ManifestVerdict) AsRefused() ManifestVerdict { + if !v.Waits() { + return v + } + v.State, v.Problems, v.Unknown = VerdictRefused, []string{v.WaitsOn()}, nil + return v +} + +// Same is whether v and o say the same of a manifest: the module, the state, the problems and the unknown fields, whoever judged and when. // The indexer writes a verdict only when it is not the same as the one it holds. func (v ManifestVerdict) Same(o ManifestVerdict) bool { - return v.Module == o.Module && v.State == o.State && slices.Equal(v.Problems, o.Problems) && slices.Equal(v.Warnings, o.Warnings) + return v.Module == o.Module && v.State == o.State && slices.Equal(v.Problems, o.Problems) && slices.Equal(v.Unknown, o.Unknown) && slices.Equal(v.Warnings, o.Warnings) } func (v ManifestVerdict) check() error { if err := checkName("module", v.Module); err != nil { return err } + if v.State != VerdictManifestWaits && len(v.Unknown) > 0 { + return fmt.Errorf("delivery: the verdict on %s names unknown fields and does not wait", v.Module) + } switch v.State { case VerdictAccepted: if len(v.Problems) > 0 { @@ -73,8 +108,12 @@ func (v ManifestVerdict) check() error { if len(v.Warnings) > 0 { return fmt.Errorf("delivery: the verdict on %s refuses its manifest and warns: a refusal names problems", v.Module) } + case VerdictManifestWaits: + if len(v.Unknown) == 0 || len(v.Problems) > 0 || len(v.Warnings) > 0 { + return fmt.Errorf("delivery: the verdict on %s waits and names no unknown field, or names problems or warnings: a wait names the fields", v.Module) + } default: - return fmt.Errorf("delivery: the verdict on %s is %q, neither %s nor %s", v.Module, v.State, VerdictAccepted, VerdictRefused) + return fmt.Errorf("delivery: the verdict on %s is %q, none of %s, %s and %s", v.Module, v.State, VerdictAccepted, VerdictRefused, VerdictManifestWaits) } if v.Judge == "" { return fmt.Errorf("delivery: the verdict on %s names no judge", v.Module) @@ -113,26 +152,37 @@ func DecodeManifestVerdict(data []byte) (ManifestVerdict, error) { return v, nil } -// TakeManifestVerdict is how a reader takes the verdict on a manifest (ADR 0578 §3): refused, with its problems, only when the -// indexer wrote a refusal. A missing verdict (nil) is taken as accepted, because every manifest the indexer holds before +// TakeManifestVerdict is how a reader takes the verdict on a manifest (ADR 0578 §3): held, with its problems, when the +// indexer wrote a refusal, or, for a manifest that waits, with the words that say which fields it waits on. A missing verdict (nil) is taken as accepted, because every manifest the indexer holds before // it has judged it was taken in under the judges that ran until then; that lasts until the indexer's first pass after its // delivery has written every verdict. A reader holds a refused module and names it with Why, and reads the rest. func TakeManifestVerdict(v *ManifestVerdict) (refused bool, problems []string) { - if v == nil || !v.Refused() { + if v == nil || !v.Held() { return false, nil } + if v.Waits() { + return true, []string{v.WaitsOn()} + } return true, v.Problems } +// WaitsOn says, in words, what a waiting manifest waits on. +func (v ManifestVerdict) WaitsOn() string { + return "it carries " + strings.Join(v.Unknown, ", ") + ", which the indexer's judge does not know yet" +} + // Why is a refusal in a reader's words: the module, that the indexer's judge refused its manifest, and each problem. func (v ManifestVerdict) Why() string { - if !v.Refused() { + if !v.Held() { return "" } judge := "the indexer's judge" if v.Judge != "" { judge += " (" + v.Judge + ")" } + if v.Waits() { + return fmt.Sprintf("%s holds the manifest of %s: %s", judge, v.Module, v.WaitsOn()) + } why := fmt.Sprintf("%s refused the manifest of %s:", judge, v.Module) for _, p := range v.Problems { why += " " + p + ";" diff --git a/go/delivery/verdicts_test.go b/go/delivery/verdicts_test.go index da05519..fa1177e 100644 --- a/go/delivery/verdicts_test.go +++ b/go/delivery/verdicts_test.go @@ -29,6 +29,9 @@ func TestAManifestVerdictIsTheContractReadersTake(t *testing.T) { "refused, no problem": {Module: "m", State: VerdictRefused, Judge: "j"}, "accepted, a problem": {Module: "m", State: VerdictAccepted, Problems: []string{"x"}, Judge: "j"}, "refused, a warning": {Module: "m", State: VerdictRefused, Problems: []string{"x"}, Warnings: []string{"y"}, Judge: "j"}, + "waits, no field": {Module: "m", State: VerdictManifestWaits, Judge: "j"}, + "waits, a problem": {Module: "m", State: VerdictManifestWaits, Unknown: []string{"f"}, Problems: []string{"x"}, Judge: "j"}, + "fields, accepted": {Module: "m", State: VerdictAccepted, Unknown: []string{"f"}, Judge: "j"}, } { if _, err := EncodeManifestVerdict(bad); err == nil { t.Errorf("%s: encoded", name) @@ -72,4 +75,38 @@ func TestAManifestVerdictIsTheContractReadersTake(t *testing.T) { if r, _ := TakeManifestVerdict(m.VerdictOf("x")); r || len(m.VerdictOf("x").Warnings) != 1 { t.Fatalf("an outgrown module: %+v", m.VerdictOf("x")) } + // A manifest with a field the judge does not know waits (clause 3 of the record on a release's Approve): readers hold it + // as a refused one, it round-trips through a modules value, an old value decodes unchanged, and it is not a refusal. + waits := ManifestVerdict{Module: "nats", State: VerdictManifestWaits, Unknown: []string{"core-credentials", "tool-runner"}, Judge: "j"} + data, err = EncodeManifestVerdict(waits) + if err != nil { + t.Fatal(err) + } + if back, err = DecodeManifestVerdict(data); err != nil || !back.Same(waits) || back.Same(ManifestVerdict{Module: "nats", State: VerdictManifestWaits, Unknown: []string{"x"}, Judge: "j"}) { + t.Fatalf("a waiting verdict: %+v %v", back, err) + } + if r, p := TakeManifestVerdict(&waits); !r || waits.Refused() || !waits.Held() || !strings.Contains(p[0], "core-credentials, tool-runner") || + !strings.Contains(waits.Why(), "holds the manifest of nats") { + t.Fatalf("a waiting verdict is held like a refusal: %v %v %q", r, p, waits.Why()) + } + if r := waits.AsRefused(); !r.Refused() || r.Waits() || len(r.Problems) != 1 || len(r.Unknown) != 0 || refused.AsRefused().State != VerdictRefused { + t.Fatalf("a waiting verdict as a reader before it takes it: %+v", r) + } + // In a modules value a wait is written as a refusal naming the fields (an older reader holds it as refused). + w := Module{FP2: "src2:" + strings.Repeat("b", 64), Manifest: strings.Repeat("c", 64), Repository: "novox/x", Commit: "c", + Verdict: VerdictRefused, Problems: []string{waits.WaitsOn()}, Unknown: []string{"f"}} + data, err = EncodeModule(w) + if err != nil { + t.Fatal(err) + } + if got, err = DecodeModule(data); err != nil || got.VerdictOf("x").Unknown[0] != "f" || !got.VerdictOf("x").Waits() || got.VerdictOf("x").Refused() { + t.Fatalf("the module's waiting verdict: %+v %v", got, err) + } + if r, p := TakeManifestVerdict(got.VerdictOf("x")); !r || !strings.Contains(p[0], "which the indexer's judge does not know yet") { + t.Fatalf("a waiting module is held: %v %v", r, p) + } + w.Verdict, w.Problems = "", nil + if _, err := EncodeModule(w); err == nil { + t.Fatal("unknown fields with no wait were encoded") + } }