TL2, TL3: the teller tells a recovery and a merge made at the forge on every channel

recovery-merged gains module and branch, and a forge-made record-opened gains repository, pull, commit and branch (seat
definition, generated Go and TypeScript, fixtures); the teller hears both events and tells them through operator-channel's notify
with every-channel, in the operator's words of §522.

Builds: design 47 G §81, §82, §170, §514, §522 (lead answer A-161)
Claude-Session: https://claude.ai/code/session_01NcbgfGKaxw984XyAPfLm4h
This commit is contained in:
2026-11-12 05:36:47 +01:00
parent a489c738b3
commit 7ba95ac07f
10 changed files with 164 additions and 5 deletions
@@ -590,12 +590,20 @@ type HeadsReplacedEvent struct {
type RecordOpenedEvent struct {
// when
At *time.Time `json:"at,omitempty"`
// for a forge-made record, the branch the merge moved
Branch string `json:"branch,omitempty"`
// for a forge-made record, the merge commit
Commit string `json:"commit,omitempty"`
// a merge made at the forge, with no Approve
ForgeMade bool `json:"forge-made,omitempty"`
// its milestone
Milestone string `json:"milestone"`
// for a forge-made record, the pull request's number
Pull int64 `json:"pull,omitempty"`
// the record's id
Record string `json:"record"`
// for a forge-made record, the repository, <owner>/<name>
Repository string `json:"repository,omitempty"`
}
// RecordEndedEventAwayItem is a type of the contract.
@@ -642,10 +650,14 @@ type SourceMovedEvent struct {
// RecoveryMergedEvent is the body of the event recovery-merged.
type RecoveryMergedEvent struct {
At *time.Time `json:"at,omitempty"`
// the watched branch the merge moved
Branch string `json:"branch,omitempty"`
// the caller the runtime proved
By string `json:"by,omitempty"`
// the merge commit
Commit string `json:"commit"`
// the module the merge changed, from the delivery record
Module string `json:"module,omitempty"`
// the repository
Repository string `json:"repository"`
V int64 `json:"v"`
@@ -31,6 +31,8 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v HeadsReplacedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.heads-replaced$")},
{name: "record-opened is said", subject: "mesh.seat.mesh-delivery.event.record-opened", given: "{\"at\":\"2026-11-09T18:00:00Z\",\"milestone\":\"47/G\",\"record\":\"47-G\"}", wire: "{\"at\":\"2026-11-09T18:00:00Z\",\"milestone\":\"47/G\",\"record\":\"47-G\"}",
decode: func(b []byte) (any, error) { var v RecordOpenedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.record-opened$")},
{name: "record-opened is said for a merge made at the forge", subject: "mesh.seat.mesh-delivery.event.record-opened", given: "{\"at\":\"2026-11-09T18:00:00Z\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"forge-made\":true,\"milestone\":\"47/G\",\"pull\":35,\"record\":\"mesh-tools-35\",\"repository\":\"novox/mesh-tools\"}", wire: "{\"at\":\"2026-11-09T18:00:00Z\",\"branch\":\"main\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"forge-made\":true,\"milestone\":\"47/G\",\"pull\":35,\"record\":\"mesh-tools-35\",\"repository\":\"novox/mesh-tools\"}",
decode: func(b []byte) (any, error) { var v RecordOpenedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.record-opened$")},
{name: "record-ended is said", subject: "mesh.seat.mesh-delivery.event.record-ended", given: "{\"at\":\"2026-11-09T21:00:00Z\",\"away\":[{\"node\":\"laptop\",\"since\":\"2026-11-09T18:00:00Z\"}],\"milestone\":\"47/G\",\"record\":\"47-G\"}", wire: "{\"at\":\"2026-11-09T21:00:00Z\",\"away\":[{\"node\":\"laptop\",\"since\":\"2026-11-09T18:00:00Z\"}],\"milestone\":\"47/G\",\"record\":\"47-G\"}",
decode: func(b []byte) (any, error) { var v RecordEndedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.record-ended$")},
{name: "filling is said", subject: "mesh.seat.mesh-delivery.event.filling", given: "{\"bytes\":650000000,\"cap\":805306368,\"store\":\"records\"}", wire: "{\"bytes\":650000000,\"cap\":805306368,\"store\":\"records\"}",
@@ -41,7 +43,7 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v RoomEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.room$")},
{name: "main moved to its next source revision", subject: "mesh.seat.mesh-delivery.event.source-moved.main", given: "{\"at\":\"2026-11-10T10:00:00Z\",\"branch\":\"main\",\"revision\":3590,\"v\":1}", wire: "{\"at\":\"2026-11-10T10:00:00Z\",\"branch\":\"main\",\"revision\":3590,\"v\":1}",
decode: func(b []byte) (any, error) { var v SourceMovedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.source-moved\\.[^.*> ]+$")},
{name: "a recovery merged", subject: "mesh.seat.mesh-delivery.event.recovery-merged", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"jochen\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"repository\":\"novox/mesh-sdk\",\"v\":1,\"why\":\"the live delivery was broken\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"by\":\"jochen\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"repository\":\"novox/mesh-sdk\",\"v\":1,\"why\":\"the live delivery was broken\"}",
{name: "a recovery merged", subject: "mesh.seat.mesh-delivery.event.recovery-merged", given: "{\"at\":\"2026-11-11T10:00:00Z\",\"branch\":\"main\",\"by\":\"jochen\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"module\":\"mesh-sdk\",\"repository\":\"novox/mesh-sdk\",\"v\":1,\"why\":\"the live delivery was broken\"}", wire: "{\"at\":\"2026-11-11T10:00:00Z\",\"branch\":\"main\",\"by\":\"jochen\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"module\":\"mesh-sdk\",\"repository\":\"novox/mesh-sdk\",\"v\":1,\"why\":\"the live delivery was broken\"}",
decode: func(b []byte) (any, error) { var v RecoveryMergedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.recovery-merged$")},
{name: "approval-carried is said for a pull request approved before G", subject: "mesh.seat.mesh-delivery.event.approval-carried.mesh-tools.35", given: "{\"approver\":\"operator\",\"at\":\"2026-11-11T10:00:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"pull\":35,\"repository\":\"mesh-tools\"}", wire: "{\"approver\":\"operator\",\"at\":\"2026-11-11T10:00:00Z\",\"commit\":\"0123456789abcdef0123456789abcdef01234567\",\"pull\":35,\"repository\":\"mesh-tools\"}",
decode: func(b []byte) (any, error) { var v ApprovalCarriedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.mesh-delivery\\.event\\.approval-carried\\.[^.*> ]+\\.[^.*> ]+$")},
@@ -96,6 +96,21 @@
"at": "2026-11-09T18:00:00Z"
}
},
{
"name": "record-opened is said for a merge made at the forge",
"of": "event:record-opened",
"subject": "mesh.seat.mesh-delivery.event.record-opened",
"given": {
"record": "mesh-tools-35",
"milestone": "47/G",
"forge-made": true,
"repository": "novox/mesh-tools",
"pull": 35,
"commit": "0123456789abcdef0123456789abcdef01234567",
"branch": "main",
"at": "2026-11-09T18:00:00Z"
}
},
{
"name": "record-ended is said",
"of": "event:record-ended",
@@ -161,6 +176,8 @@
"given": {
"v": 1,
"repository": "novox/mesh-sdk",
"module": "mesh-sdk",
"branch": "main",
"commit": "0123456789abcdef0123456789abcdef01234567",
"why": "the live delivery was broken",
"by": "jochen",
@@ -308,6 +308,22 @@
"type": "boolean",
"description": "a merge made at the forge, with no Approve"
},
"repository": {
"type": "string",
"description": "for a forge-made record, the repository, <owner>/<name>"
},
"pull": {
"type": "integer",
"description": "for a forge-made record, the pull request's number"
},
"commit": {
"type": "string",
"description": "for a forge-made record, the merge commit"
},
"branch": {
"type": "string",
"description": "for a forge-made record, the branch the merge moved"
},
"at": {
"type": "string",
"format": "date-time",
@@ -433,6 +449,14 @@
"type": "string",
"description": "the repository"
},
"module": {
"type": "string",
"description": "the module the merge changed, from the delivery record"
},
"branch": {
"type": "string",
"description": "the watched branch the merge moved"
},
"commit": {
"type": "string",
"description": "the merge commit"
@@ -361,12 +361,20 @@ export interface HeadsReplacedEvent {
export interface RecordOpenedEvent {
/** when */
"at"?: string;
/** for a forge-made record, the branch the merge moved */
"branch"?: string;
/** for a forge-made record, the merge commit */
"commit"?: string;
/** a merge made at the forge, with no Approve */
"forge-made"?: boolean;
/** its milestone */
"milestone": string;
/** for a forge-made record, the pull request's number */
"pull"?: number;
/** the record's id */
"record": string;
/** for a forge-made record, the repository, <owner>/<name> */
"repository"?: string;
}
export interface RecordEndedEventAwayItem {
@@ -412,10 +420,14 @@ export interface SourceMovedEvent {
/** is the body of the event recovery-merged. */
export interface RecoveryMergedEvent {
"at"?: string;
/** the watched branch the merge moved */
"branch"?: string;
/** the caller the runtime proved */
"by"?: string;
/** the merge commit */
"commit": string;
/** the module the merge changed, from the delivery record */
"module"?: string;
/** the repository */
"repository": string;
"v": number;
@@ -100,6 +100,13 @@ func run(ctx context.Context, getenv func(string) string, logOut io.Writer) erro
if err := hub.Handle(registrationChangedSubject, widens.HearRegistration); err != nil {
return fmt.Errorf("hearing %s: %w", registrationChangedSubject, err)
}
// A merge named a recovery and a merge made at the forge are told on every channel (design 47 G §81, §170, §514).
if err := hub.Handle(recoveryMergedSubject, widens.HearRecovery); err != nil {
return fmt.Errorf("hearing %s: %w", recoveryMergedSubject, err)
}
if err := hub.Handle(recordOpenedSubject, widens.HearRecordOpened); err != nil {
return fmt.Errorf("hearing %s: %w", recordOpenedSubject, err)
}
// Hear the warrants first, so none that comes while the asks are read is missed.
if err := client.Listen(t.Answer, t.Said); err != nil {
return fmt.Errorf("hearing the router's warrants: %w", err)
@@ -9,6 +9,7 @@ import (
"github.com/nats-io/nats.go/jetstream"
"git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshcatalog"
meshdelivery "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshdelivery"
mpr "git.novox.be/novox/mesh-delivery/modules/mesh-delivery-contracts/go/seats/meshpipelinerunner"
stdio "git.novox.be/novox/mesh-sdk/go"
"git.novox.be/novox/mesh-sdk/go/keys"
@@ -34,6 +35,8 @@ const (
const (
pipelineEndedSubject = "mesh.seat." + mpr.Seat + ".event." + mpr.EventPipelineEnded + ".>"
registrationChangedSubject = meshcatalog.SubjectRegistrationChanged
recoveryMergedSubject = meshdelivery.SubjectRecoveryMerged
recordOpenedSubject = meshdelivery.SubjectRecordOpened
)
// widensState is the state widens-said as the teller keeps it.
@@ -91,8 +94,7 @@ func (w *Widens) Said(p mpr.PipelineEnded) error {
}
words := widensWords(p)
// The message's key holds the commit, so a say that is made again after a failure to keep it replaces the message.
if _, err := w.Call(notifyKey, map[string]any{"key": "widens." + key + "." + commit7(p.Commit), "subject": p.Module,
"severity": "warning", "summary": words, "headline": words, "every-channel": true}); err != nil {
if err := w.tell("widens."+key+"."+commit7(p.Commit), p.Module, words); err != nil {
return fmt.Errorf("the widening of %s %s on %s is not told: %w", p.Module, commit7(p.Commit), p.Branch, err)
}
if e == nil {
@@ -186,3 +188,48 @@ func (w *Widens) logf(format string, args ...any) {
w.Logf(format, args...)
}
}
// recoveryWords is the message of a merge named a recovery (design 47 G §522, §81).
func recoveryWords(ev meshdelivery.RecoveryMergedEvent) string {
return fmt.Sprintf("Recovery merged: %s %s on %s, named by %s: %s.", ev.Module, commit7(ev.Commit), ev.Branch, ev.By, ev.Why)
}
// forgeMadeWords is the message of a record opened for a merge made at the forge (design 47 G §522, §170).
func forgeMadeWords(ev meshdelivery.RecordOpenedEvent) string {
return fmt.Sprintf("Merged at the forge, not through the mesh: %s pull request #%d at %s on %s; delivered like any merge.",
ev.Repository, ev.Pull, commit7(ev.Commit), ev.Branch)
}
// tell says words on every channel under key; a message of the same key is the same message.
func (w *Widens) tell(key, subject, words string) error {
_, err := w.Call(notifyKey, map[string]any{"key": key, "subject": subject, "severity": "warning", "summary": words,
"headline": words, "every-channel": true})
return err
}
// HearRecovery is the handler of recovery-merged: it tells the merge named a recovery on every channel (design 47 G §81, §514).
func (w *Widens) HearRecovery(m jetstream.Msg) {
var ev meshdelivery.RecoveryMergedEvent
if err := json.Unmarshal(m.Data(), &ev); err != nil || ev.Commit == "" {
w.logf("%s is not a recovery and is left: %v", m.Subject(), err)
_ = m.Ack()
return
}
w.finish(m, w.tell("recovery."+ev.Repository+"."+commit7(ev.Commit), ev.Repository, recoveryWords(ev)))
}
// HearRecordOpened is the handler of record-opened: it tells a record opened for a merge made at the forge on every channel
// (design 47 G §170, §514); any other record is left to the watchman.
func (w *Widens) HearRecordOpened(m jetstream.Msg) {
var ev meshdelivery.RecordOpenedEvent
if err := json.Unmarshal(m.Data(), &ev); err != nil {
w.logf("%s is not a record's opening and is left: %v", m.Subject(), err)
_ = m.Ack()
return
}
if !ev.ForgeMade {
_ = m.Ack()
return
}
w.finish(m, w.tell("forge-made."+ev.Record, ev.Repository, forgeMadeWords(ev)))
}
@@ -174,3 +174,39 @@ func TestAPipelineEndedIsAcknowledgedOnlyWhenTold(t *testing.T) {
t.Errorf("a told say: acked %v naked %v", m.acked, m.naked)
}
}
// Design 47 G §81, §170, §522 (TL2, TL3): a recovery and a merge made at the forge are told on every channel in the operator's
// words, with their fields filled; a record opened the ordinary way is told nothing.
func TestARecoveryAndAForgeMadeMergeAreToldInTheOperatorsWords(t *testing.T) {
commit := "0123456789abcdef0123456789abcdef01234567"
for _, tc := range []struct {
name, body string
hear func(*Widens, *fakeMsg)
key, words string
}{
{"a recovery", `{"v":1,"repository":"novox/mesh-sdk","module":"mesh-sdk","branch":"main","commit":"` + commit + `","why":"the live delivery was broken","by":"jochen"}`,
func(w *Widens, m *fakeMsg) { w.HearRecovery(m) }, "recovery.novox/mesh-sdk.0123456",
"Recovery merged: mesh-sdk 0123456 on main, named by jochen: the live delivery was broken."},
{"a forge-made record", `{"record":"mesh-tools-35","milestone":"47/G","forge-made":true,"repository":"novox/mesh-tools","pull":35,"commit":"` + commit + `","branch":"main"}`,
func(w *Widens, m *fakeMsg) { w.HearRecordOpened(m) }, "forge-made.mesh-tools-35",
"Merged at the forge, not through the mesh: novox/mesh-tools pull request #35 at 0123456 on main; delivered like any merge."},
{"an ordinary record", `{"record":"47-G","milestone":"47/G"}`, func(w *Widens, m *fakeMsg) { w.HearRecordOpened(m) }, "", ""},
} {
c := &calls{}
w := &Widens{State: &widensMem{memStore{entries: map[string]*stdio.StateEntry{}}}, Call: c.call}
m := &fakeMsg{data: []byte(tc.body)}
tc.hear(w, m)
if !m.acked || m.naked {
t.Errorf("%s: acked %v naked %v", tc.name, m.acked, m.naked)
}
if tc.words == "" {
if len(c.notified) != 0 {
t.Errorf("%s: told %v", tc.name, c.notified)
}
continue
}
if len(c.notified) != 1 || c.notified[0]["headline"] != tc.words || c.notified[0]["key"] != tc.key || c.notified[0]["every-channel"] != true {
t.Errorf("%s: told %v, want %q under %s on every channel", tc.name, c.notified, tc.words, tc.key)
}
}
}
@@ -113,7 +113,7 @@ func TestManifestDeclarations(t *testing.T) { // 1240/AC1
}
// design 47 G §335 (TL1): the widening of a pipeline end is told through the seat operator-channel and kept in widens-said.
// design 47 G §387: the keeper's ask for the findings is heard, and the finding stream is declared (§383).
if want := []string{"mesh-conditions.findings-asked", "mesh-delivery-assigner.views.asks", "mesh-catalog.registration-changed", "mesh-pipeline-runner.pipeline-ended"}; !reflect.DeepEqual(m.Consumes, want) {
if want := []string{"mesh-conditions.findings-asked", "mesh-delivery-assigner.views.asks", "mesh-catalog.registration-changed", "mesh-pipeline-runner.pipeline-ended", "mesh-delivery.recovery-merged", "mesh-delivery.record-opened"}; !reflect.DeepEqual(m.Consumes, want) {
t.Errorf("consumes = %v, want %v", m.Consumes, want)
}
if want := []string{"operator-channel"}; !reflect.DeepEqual(sorted(m.Uses), want) {
+3 -1
View File
@@ -19,7 +19,9 @@
"mesh-conditions.findings-asked",
"mesh-delivery-assigner.views.asks",
"mesh-catalog.registration-changed",
"mesh-pipeline-runner.pipeline-ended"
"mesh-pipeline-runner.pipeline-ended",
"mesh-delivery.recovery-merged",
"mesh-delivery.record-opened"
],
"emits": [
"answered",