From 1b9f9355b51a6289eeb5d8259475eb1df8f40888 Mon Sep 17 00:00:00 2001 From: jochen Date: Tue, 17 Nov 2026 00:39:39 +0100 Subject: [PATCH] Node-engine: a hold of the composition carries its wait, step compose (A-453) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit A module not composed for want of its entry (entry-asked, entry-missing) and a want whose parts differ write their have with a Wait of step compose and that reason, as the kept data's holds do; the hold for a failed backup carries none. Builds: design 47 G A-453 (ADR 0539 §16, §541) --- internal/agent/agent.go | 13 +++++++++++-- internal/agent/agent_test.go | 19 +++++++++++++------ internal/agent/parts.go | 8 ++++++++ 3 files changed, 32 insertions(+), 8 deletions(-) diff --git a/internal/agent/agent.go b/internal/agent/agent.go index 411b2ad2..2a2456c0 100644 --- a/internal/agent/agent.go +++ b/internal/agent/agent.go @@ -660,13 +660,16 @@ func (a *Agent) NotComposedEach(ctx context.Context, why string, held map[string a.notComposed[module] = mark a.mu.Unlock() phase, detail := string(nodeengineclient.PhaseFailed), NotComposedDetail+why + var wait *nodeengine.Wait if heldForEntry(why) { // The entry its want names is not held: the phase held, its detail opening entry-asked: or entry-missing: and // naming the fingerprint (design 47 G section 421). phase, detail = string(nodeengineclient.PhaseHeld), why + // The hold says what it waits on, as every hold but a failed backup does (design 47 G A-453, section 541). + wait = a.composeWait(strings.TrimSuffix(heldReason(why), ":"), why) } a.writeHave(ctx, Have{Module: module, FP: mark.prior.FP, Composed: mark.prior.Composed, Sealed: mark.prior.Sealed, - Phase: phase, Detail: detail}) + Phase: phase, Detail: detail, Wait: wait}) } } @@ -678,6 +681,12 @@ func (a *Agent) NotComposedEach(ctx context.Context, why string, held map[string // module since its start: held by a failed backup, waiting for a yes, not composed) keeps what the module's last have // said runs, its fingerprint, digest and sealed values, rather than a have naming nothing: what runs is not lost, and // the boxes the composer reuses after a restart stay (review of L2, rounds 2 and 3). +// composeWait is the wait a hold of the composition carries in its have: step compose, with its reason and its words (design 47 G +// A-453, section 541). Only a hold for a failed backup carries none. +func (a *Agent) composeWait(reason, words string) *nodeengine.Wait { + return &nodeengine.Wait{Owner: nodeengine.Seat, Step: nodeengine.WaitStepCompose, Reason: reason, Since: a.now(), Words: words} +} + func (a *Agent) writeHave(ctx context.Context, h Have) { if h.Module != NodeModule { a.mu.Lock() @@ -1634,7 +1643,7 @@ func (a *Agent) apply(ctx context.Context, module string, w wantNow, comp compNo } a.env.Say(fmt.Sprintf("%s is held: %s", module, words)) a.writeHave(ctx, Have{Module: module, FP: prev.Fp, Composed: prev.Composed, Phase: string(nodeengineclient.PhaseHeld), - Detail: words}) + Detail: words, Wait: a.composeWait("parts-differ", words)}) return } diff --git a/internal/agent/agent_test.go b/internal/agent/agent_test.go index d592dd83..9ad87282 100644 --- a/internal/agent/agent_test.go +++ b/internal/agent/agent_test.go @@ -357,8 +357,9 @@ func TestAWantAndItsCompositionApplyTheModuleAndTheHaveNamesBoth(t *testing.T) { if got := len(b.appliedList()) - before; (got == 1) != row.applies { t.Fatalf("parts %q: applied %d times, want applies=%v", row.name, got, row.applies) } - if h := b.haves.last("web"); !row.applies && (h.Phase != string(nodeengineclient.PhaseHeld) || h.Detail != row.detail) { - t.Fatalf("parts %q: the have is %s %q, want held %q", row.name, h.Phase, h.Detail, row.detail) + if h := b.haves.last("web"); !row.applies && (h.Phase != string(nodeengineclient.PhaseHeld) || h.Detail != row.detail || + h.Wait == nil || h.Wait.Step != nodeengine.WaitStepCompose || h.Wait.Reason != "parts-differ" || h.Wait.Words != row.detail) { + t.Fatalf("parts %q: the have is %s %q wait %+v, want held %q waiting on parts-differ (A-453)", row.name, h.Phase, h.Detail, h.Wait, row.detail) } } // A container's digest is the one after its image's @. @@ -754,7 +755,8 @@ func TestADataModuleIsBackedUpFirstAndHeldWhenItFails(t *testing.T) { }) eventually(t, "the have does not say held", func() bool { h := b.haves.last("db") - return h.Phase == string(nodeengineclient.PhaseHeld) && strings.Contains(h.Detail, "repository is locked") && h.FP == fp1 + // A hold for a failed backup carries no wait: the operator is asked about it (A-453). + return h.Phase == string(nodeengineclient.PhaseHeld) && strings.Contains(h.Detail, "repository is locked") && h.FP == fp1 && h.Wait == nil }) if got := b.appliedList(); len(got) != 0 { t.Fatalf("something was applied behind a failed backup: %v", got) @@ -1784,9 +1786,14 @@ func TestTheNodesOwnCompositionIsAppliedWhenItDiffersAndARecordMoveWaitsForAYes( } // Design 47 G §421: a module whose want's entry the catalog half holds none of is the phase held, its detail opening // entry-missing: and naming the fingerprint; composed again, its have is what it runs. - b.ag.NotComposedEach(context.Background(), "", map[string]string{"idle": EntryMissing + " the catalog half holds no entry of the build src2:x"}) - if h := b.haves.last("idle"); h.Phase != string(nodeengineclient.PhaseHeld) || h.Composed != idleDig || h.Detail != EntryMissing+" the catalog half holds no entry of the build src2:x" { - t.Errorf("idle's have while its entry is missing: %+v", h) + // A-453: the hold carries its wait, step compose with the reason, as every hold but a failed backup does. + for _, row := range []struct{ opening, reason string }{{EntryMissing, "entry-missing"}, {EntryAsked, "entry-asked"}} { + words := row.opening + " the catalog half holds no entry of the build src2:x" + b.ag.NotComposedEach(context.Background(), "", map[string]string{"idle": words}) + if h := b.haves.last("idle"); h.Phase != string(nodeengineclient.PhaseHeld) || h.Composed != idleDig || h.Detail != words || + h.Wait == nil || h.Wait.Step != nodeengine.WaitStepCompose || h.Wait.Reason != row.reason || h.Wait.Words != words || h.Wait.Since.IsZero() { + t.Errorf("idle's have while its entry is %s: %+v", row.reason, h) + } } b.ag.NotComposedEach(context.Background(), "", nil) if h := b.haves.last("idle"); h.Phase != string(nodeengineclient.PhaseRunning) || h.Composed != idleDig { diff --git a/internal/agent/parts.go b/internal/agent/parts.go index 222808de..1da96058 100644 --- a/internal/agent/parts.go +++ b/internal/agent/parts.go @@ -31,6 +31,14 @@ func judgedAgain(why string) bool { } // heldForEntry says whether why is a hold for the entry a want names. +// heldReason is the opening of a detail held for an entry: EntryAsked or EntryMissing. +func heldReason(why string) string { + if strings.HasPrefix(why, EntryAsked) { + return EntryAsked + } + return EntryMissing +} + func heldForEntry(why string) bool { return strings.HasPrefix(why, EntryAsked) || strings.HasPrefix(why, EntryMissing) }