diff --git a/modules/mesh-delivery-contracts/go/seats/git/contract.go b/modules/mesh-delivery-contracts/go/seats/git/contract.go index 30f7c416..7d4172ff 100644 --- a/modules/mesh-delivery-contracts/go/seats/git/contract.go +++ b/modules/mesh-delivery-contracts/go/seats/git/contract.go @@ -1,6 +1,6 @@ // Code generated by seatgen from the seat definitions; DO NOT EDIT. -// Package git is the contract of the seat "git", defined whole (seats/git/seat.json): The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 §1, §2). A failed read answers an error, never an empty answer. The act verbs are the forge bridge's alone. +// Package git is the contract of the seat "git", defined whole (seats/git/seat.json): The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 §1, §2). A failed read answers an error, never an empty answer. package git import ( @@ -40,6 +40,7 @@ const ( EventForgeDelete = "forge-delete" EventRepoWritable = "repo-writable" EventBranchMoved = "branch-moved" + EventMergeCalled = "merge-called" ) // Verbs is every verb the seat serves, in its definition's order: a new copy each call. @@ -49,7 +50,7 @@ func Verbs() []string { // Events is every event published on the seat's subject: a new copy each call. func Events() []string { - return []string{EventPullUpdated, EventPullMerged, EventPullClosed, EventForgePull, EventForgeStatus, EventForgeDelete, EventRepoWritable, EventBranchMoved} + return []string{EventPullUpdated, EventPullMerged, EventPullClosed, EventForgePull, EventForgeStatus, EventForgeDelete, EventRepoWritable, EventBranchMoved, EventMergeCalled} } // Family is where the seat's events are kept: the shared events stream, filtered to the seat's subjects. @@ -85,8 +86,18 @@ const StreamBranchMoved = "SEAT_git_branch-moved" // SubjectBranchMoved is where branch-moved is published. const SubjectBranchMoved = "mesh.seat.git.event.branch-moved" +// StreamMergeCalled is the stream merge-called is kept in. +const StreamMergeCalled = "SEAT_git_merge-called" + +// SubjectMergeCalled is where merge-called is published, on mesh.seat.git.event.merge-called.. +func SubjectMergeCalled(call string) string { return "mesh.seat.git.event.merge-called." + call } + +// SubjectMergeCalledAll hears every merge-called. +const SubjectMergeCalledAll = "mesh.seat.git.event.merge-called.*" + const ( StateFailedSteps = "failed-steps" + StateCalls = "calls" ) // FailedStepsByModuleFingerprintStepKey is the key of one value of the state failed-steps under the form "..". @@ -132,6 +143,72 @@ func DecodeFailedStepsByModuleFingerprintStepValue(raw []byte) (FailedStepsByMod return v, nil } +// CallsByCallCallKey is the key of one value of the state calls under the form "call.". +func CallsByCallCallKey(call string) string { return "call." + call } + +// ParseCallsByCallCallKey reads the parts of a key of the form "call.", in the order of the form; the last result is false for a key of another form. +func ParseCallsByCallCallKey(key string) (string, bool) { + rest := key + if !strings.HasPrefix(rest, "call.") { + return "", false + } + rest = rest[5:] + if rest == "" { + return "", false + } + v1 := rest + rest = "" + if rest != "" { + return "", false + } + return v1, true +} + +// DecodeCallsByCallCallValue reads one value of the state calls under the form "call.", refusing a field CallsByCallCallValue does not know and any text after the value. +func DecodeCallsByCallCallValue(raw []byte) (CallsByCallCallValue, error) { + var v CallsByCallCallValue + dec := json.NewDecoder(bytes.NewReader(raw)) + dec.DisallowUnknownFields() + if err := dec.Decode(&v); err != nil { + return v, err + } + if dec.More() { + return v, errors.New("text after the value") + } + return v, nil +} + +// Call is one merge call, written before its first merge and updated as each member merges (design 47 H §766). +type Call struct { + // the bus account the tool runner proved for the call + Account string `json:"account"` + At time.Time `json:"at"` + // the caller as who@node + By string `json:"by"` + Members []CallMember `json:"members"` + // merge-called was said for it + Said bool `json:"said"` +} + +// CallMember is one member of a kept call. +type CallMember struct { + // for merged, the merge commit + Commit string `json:"commit,omitempty"` + Head string `json:"head"` + Number int64 `json:"number"` + Repository string `json:"repository"` + State string `json:"state"` + // for refused, why + Why string `json:"why,omitempty"` +} + +// The values of CallMember's state. +const ( + CallMemberStateJudged = "judged" + CallMemberStateMerged = "merged" + CallMemberStateRefused = "refused" +) + // Change is what a pull request changed. type Change struct { // the changed directories that hold a module at its head; absent when they could not be read @@ -173,6 +250,25 @@ type FailedStep struct { V int64 `json:"v,omitempty"` } +// MemberOutcome is one member of a merge call and where it stands (design 47 H §766, H-A-22). +type MemberOutcome struct { + // for merged, the merge commit; for a member refused already-merged, its commit + Commit string `json:"commit,omitempty"` + Number int64 `json:"number"` + Repository string `json:"repository"` + // judged, judged and not merged; merged, with its commit; refused, with why + State string `json:"state"` + // for refused, why, naming the step for a failed required step + Why string `json:"why,omitempty"` +} + +// The values of MemberOutcome's state. +const ( + MemberOutcomeStateJudged = "judged" + MemberOutcomeStateMerged = "merged" + MemberOutcomeStateRefused = "refused" +) + // Merging is what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 §1): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one. type Merging struct { // the forge's own word on whether it merges into its base now: false while it is in conflict with its base, or while the forge works that out after the base moved @@ -243,6 +339,40 @@ type Status struct { Target string `json:"target,omitempty"` } +// MergeCalledMembersItem is a type of the contract. +type MergeCalledMembersItem struct { + // the pull request's base, a watched branch + Branch string `json:"branch"` + // the merge commit the forge records for the pull request + Commit string `json:"commit"` + Head string `json:"head"` + Number int64 `json:"number"` + Repository string `json:"repository"` +} + +// MergeCalledRefusedItem is a type of the contract. +type MergeCalledRefusedItem struct { + Number int64 `json:"number"` + Repository string `json:"repository"` + Why string `json:"why"` +} + +// MergeCalled is a merge call's members merged or refused, said once by the forge module (design 47 H §736, §767). +type MergeCalled struct { + // the bus account the tool runner proved + Account string `json:"account"` + // the time of the last merge + At time.Time `json:"at"` + // the caller as who@node + By string `json:"by"` + // the merge call, 16 lowercase hex characters made once per call + Call string `json:"call"` + // one per landed member + Members []MergeCalledMembersItem `json:"members"` + // one per member not merged after every member was judged (design 47 H §767) + Refused []MergeCalledRefusedItem `json:"refused,omitempty"` +} + // PullInput is what pull takes. type PullInput struct { // instead of the number: the merge commit it made @@ -276,9 +406,7 @@ type BranchAnswer struct { Error string `json:"error,omitempty"` ErrorKind ErrorKind `json:"error-kind,omitempty"` // a commit, its full 40-hex sha - Head string `json:"head,omitempty"` - // a protection rule refuses a direct push and admits only merges - Protected bool `json:"protected,omitempty"` + Head string `json:"head,omitempty"` Repository string `json:"repository,omitempty"` } @@ -541,52 +669,35 @@ type NoteAnswer struct { Performed bool `json:"performed,omitempty"` } -// MergePullInput is what merge-pull takes. -type MergePullInput struct { +// MergePullInputPullsItem is a type of the contract. +type MergePullInputPullsItem struct { // the head the caller names Head string `json:"head"` - // the act's id - ID string `json:"id"` // the pull request's number Number int64 `json:"number"` // the repository, / Repository string `json:"repository"` } +// MergePullInput is what merge-pull takes. +type MergePullInput struct { + // the caller as who@node, recorded beside the bus account the tool runner proves + By string `json:"by"` + // the members, in the order they are merged + Pulls []MergePullInputPullsItem `json:"pulls"` +} + // MergePullAnswer is what merge-pull answers. type MergePullAnswer struct { + // the merge call, 16 lowercase hex characters made once per call + Call string `json:"call,omitempty"` // why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none Error string `json:"error,omitempty"` ErrorKind ErrorKind `json:"error-kind,omitempty"` - // the id was already held on the pull request or the note, so nothing was done again - Held bool `json:"held,omitempty"` - // the act's id, as the caller gave it - ID string `json:"id,omitempty"` - // the merge commit - MergeCommit string `json:"merge-commit,omitempty"` - // for policy-failed, the module - Module string `json:"module,omitempty"` - // the forge holds the act now - Performed bool `json:"performed,omitempty"` - // why the forge or the holder refused the merge; the act is not performed - Refused string `json:"refused,omitempty"` - // which refusal, set with refused: head-moved, the pull request's head is not the one named; unprotected, the base branch's protection does not refuse a direct push; policy-failed, a run at the head's fingerprint failed a required step (run, module and step name it); no-registrations, no registration-changed heard yet (ADR 0667 section 10); git-refused, git refused the merge - RefusedKind string `json:"refused-kind,omitempty"` - // for policy-failed, the run that failed the step: the runner's pipeline key - Run string `json:"run,omitempty"` - // for policy-failed, the step - Step string `json:"step,omitempty"` + // each member's outcome, in the order named + Members []MemberOutcome `json:"members,omitempty"` } -// The values of MergePullAnswer's refused-kind. -const ( - MergePullAnswerRefusedKindHeadMoved = "head-moved" - MergePullAnswerRefusedKindUnprotected = "unprotected" - MergePullAnswerRefusedKindPolicyFailed = "policy-failed" - MergePullAnswerRefusedKindNoRegistrations = "no-registrations" - MergePullAnswerRefusedKindGitRefused = "git-refused" -) - // TagInput is what tag takes. type TagInput struct { // the commit it is written at @@ -748,5 +859,11 @@ type BranchMovedEvent struct { Repository string `json:"repository"` } +// MergeCalledEvent is the body of the event merge-called. +type MergeCalledEvent = MergeCalled + // FailedStepsByModuleFingerprintStepValue is one value of the state failed-steps under the key ... type FailedStepsByModuleFingerprintStepValue = FailedStep + +// CallsByCallCallValue is one value of the state calls under the key call.. +type CallsByCallCallValue = Call diff --git a/modules/mesh-delivery-contracts/go/seats/git/contract_test.go b/modules/mesh-delivery-contracts/go/seats/git/contract_test.go index 9d6e2151..c797bf52 100644 --- a/modules/mesh-delivery-contracts/go/seats/git/contract_test.go +++ b/modules/mesh-delivery-contracts/go/seats/git/contract_test.go @@ -33,12 +33,16 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v RepoWritableEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.git\\.event\\.repo-writable$")}, {name: "a branch moved by a merge", subject: "mesh.seat.git.event.branch-moved", given: "{\"at\":\"2026-11-10T10:00:00Z\",\"branch\":\"main\",\"head\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"repository\":\"novox/mesh-catalog\"}", wire: "{\"at\":\"2026-11-10T10:00:00Z\",\"branch\":\"main\",\"head\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"repository\":\"novox/mesh-catalog\"}", decode: func(b []byte) (any, error) { var v BranchMovedEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.git\\.event\\.branch-moved$")}, + {name: "merge-called is said once per call", subject: "mesh.seat.git.event.merge-called.0123456789abcdef", given: "{\"account\":\"tools-shanks\",\"at\":\"2026-11-20T02:00:00Z\",\"by\":\"lead-47@workstation\",\"call\":\"0123456789abcdef\",\"members\":[{\"branch\":\"main\",\"commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"number\":178,\"repository\":\"novox/mesh-sdk\"}],\"refused\":[{\"number\":261,\"repository\":\"novox/mesh-delivery\",\"why\":\"the forge refused the merge: conflict\"}]}", wire: "{\"account\":\"tools-shanks\",\"at\":\"2026-11-20T02:00:00Z\",\"by\":\"lead-47@workstation\",\"call\":\"0123456789abcdef\",\"members\":[{\"branch\":\"main\",\"commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"number\":178,\"repository\":\"novox/mesh-sdk\"}],\"refused\":[{\"number\":261,\"repository\":\"novox/mesh-delivery\",\"why\":\"the forge refused the merge: conflict\"}]}", + decode: func(b []byte) (any, error) { var v MergeCalledEvent; err := json.Unmarshal(b, &v); return v, err }, subjectIs: regexp.MustCompile("^mesh\\.seat\\.git\\.event\\.merge-called\\.[^.*> ]+$")}, {name: "a failed required step kept", subject: "", given: "{\"artifact\":\"nats:program\",\"at\":\"2026-11-10T10:00:00Z\",\"commits\":[\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"],\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"run\":\"main.12.nats\",\"said\":\"TestTheBusWhole failed\",\"step\":\"unit\",\"v\":1}", wire: "{\"artifact\":\"nats:program\",\"at\":\"2026-11-10T10:00:00Z\",\"commits\":[\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"],\"fingerprint\":\"fp-0123\",\"module\":\"nats\",\"run\":\"main.12.nats\",\"said\":\"TestTheBusWhole failed\",\"step\":\"unit\",\"v\":1}", decode: func(b []byte) (any, error) { var v FailedStepsByModuleFingerprintStepValue err := json.Unmarshal(b, &v) return v, err }, subjectIs: nil}, + {name: "a merge call kept", subject: "", given: "{\"account\":\"tools-shanks\",\"at\":\"2026-11-20T02:00:00Z\",\"by\":\"lead-47@workstation\",\"members\":[{\"commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"number\":178,\"repository\":\"novox/mesh-sdk\",\"state\":\"merged\"},{\"head\":\"cccccccccccccccccccccccccccccccccccccccc\",\"number\":261,\"repository\":\"novox/mesh-delivery\",\"state\":\"judged\"}],\"said\":false}", wire: "{\"account\":\"tools-shanks\",\"at\":\"2026-11-20T02:00:00Z\",\"by\":\"lead-47@workstation\",\"members\":[{\"commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"number\":178,\"repository\":\"novox/mesh-sdk\",\"state\":\"merged\"},{\"head\":\"cccccccccccccccccccccccccccccccccccccccc\",\"number\":261,\"repository\":\"novox/mesh-delivery\",\"state\":\"judged\"}],\"said\":false}", + decode: func(b []byte) (any, error) { var v CallsByCallCallValue; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "pull asks", subject: "", given: "{\"merge-commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"repository\":\"novox/mesh-sdk\"}", wire: "{\"merge-commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"repository\":\"novox/mesh-sdk\"}", decode: func(b []byte) (any, error) { var v PullInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "pull answers", subject: "", given: "{\"pull\":{\"author\":\"alice\",\"base\":\"main\",\"branch\":\"feat/47-G\",\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"merge-commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"merged-at\":\"2026-11-09T19:40:00Z\",\"number\":178,\"repository\":\"novox/mesh-sdk\",\"state\":\"merged\",\"title\":\"One wiring of the seat list\",\"url\":\"https://forge.test/novox/mesh-sdk/pulls/178\"}}", wire: "{\"pull\":{\"author\":\"alice\",\"base\":\"main\",\"branch\":\"feat/47-G\",\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"merge-commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"merged-at\":\"2026-11-09T19:40:00Z\",\"number\":178,\"repository\":\"novox/mesh-sdk\",\"state\":\"merged\",\"title\":\"One wiring of the seat list\",\"url\":\"https://forge.test/novox/mesh-sdk/pulls/178\"}}", @@ -113,19 +117,9 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v NoteAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "note answers an error, never none", subject: "", given: "{\"error\":\"the note ref could not be pushed\",\"error-kind\":\"failed\"}", wire: "{\"error\":\"the note ref could not be pushed\",\"error-kind\":\"failed\"}", decode: func(b []byte) (any, error) { var v NoteAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "merge-pull asks", subject: "", given: "{\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"id\":\"owed-5\",\"number\":178,\"repository\":\"novox/mesh-sdk\"}", wire: "{\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"id\":\"owed-5\",\"number\":178,\"repository\":\"novox/mesh-sdk\"}", - decode: func(b []byte) (any, error) { var v MergePullInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "merge-pull answers", subject: "", given: "{\"id\":\"owed-5\",\"merge-commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"performed\":true}", wire: "{\"id\":\"owed-5\",\"merge-commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"performed\":true}", - decode: func(b []byte) (any, error) { var v MergePullAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "merge-pull answers", subject: "", given: "{\"id\":\"owed-5\",\"refused\":\"the head moved: cccccccccccccccccccccccccccccccccccccccc, not the named aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"refused-kind\":\"head-moved\"}", wire: "{\"id\":\"owed-5\",\"refused\":\"the head moved: cccccccccccccccccccccccccccccccccccccccc, not the named aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"refused-kind\":\"head-moved\"}", - decode: func(b []byte) (any, error) { var v MergePullAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "merge-pull answers an error, never none", subject: "", given: "{\"error\":\"the forge answered 502\",\"error-kind\":\"failed\"}", wire: "{\"error\":\"the forge answered 502\",\"error-kind\":\"failed\"}", - decode: func(b []byte) (any, error) { var v MergePullAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "merge-pull refuses a failed required step, naming the run, the module and the step", subject: "", given: "{\"id\":\"merge-7\",\"module\":\"nats\",\"refused\":\"unit of nats:program failed at fp-0123 in main.12.nats\",\"refused-kind\":\"policy-failed\",\"run\":\"main.12.nats\",\"step\":\"unit\"}", wire: "{\"id\":\"merge-7\",\"module\":\"nats\",\"refused\":\"unit of nats:program failed at fp-0123 in main.12.nats\",\"refused-kind\":\"policy-failed\",\"run\":\"main.12.nats\",\"step\":\"unit\"}", - decode: func(b []byte) (any, error) { var v MergePullAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "branch asks a branch", subject: "", given: "{\"branch\":\"main\",\"repository\":\"novox/mesh-catalog\"}", wire: "{\"branch\":\"main\",\"repository\":\"novox/mesh-catalog\"}", decode: func(b []byte) (any, error) { var v BranchInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, - {name: "branch answers its head and protection", subject: "", given: "{\"branch\":\"main\",\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"protected\":true,\"repository\":\"novox/mesh-catalog\"}", wire: "{\"branch\":\"main\",\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"protected\":true,\"repository\":\"novox/mesh-catalog\"}", + {name: "branch answers its head", subject: "", given: "{\"branch\":\"main\",\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"repository\":\"novox/mesh-catalog\"}", wire: "{\"branch\":\"main\",\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"repository\":\"novox/mesh-catalog\"}", decode: func(b []byte) (any, error) { var v BranchAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "branch answers a branch the forge does not hold", subject: "", given: "{\"error\":\"no branch beta in novox/mesh-catalog\",\"error-kind\":\"not-found\"}", wire: "{\"error\":\"no branch beta in novox/mesh-catalog\",\"error-kind\":\"not-found\"}", decode: func(b []byte) (any, error) { var v BranchAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, @@ -135,6 +129,16 @@ func TestFixtures(t *testing.T) { decode: func(b []byte) (any, error) { var v TagAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, {name: "tag answers an error, never none", subject: "", given: "{\"error\":\"the forge answered 403\",\"error-kind\":\"refused\"}", wire: "{\"error\":\"the forge answered 403\",\"error-kind\":\"refused\"}", decode: func(b []byte) (any, error) { var v TagAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "merge-pull asks two pull requests in two repositories", subject: "", given: "{\"by\":\"lead-47@workstation\",\"pulls\":[{\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"number\":178,\"repository\":\"novox/mesh-sdk\"},{\"head\":\"cccccccccccccccccccccccccccccccccccccccc\",\"number\":261,\"repository\":\"novox/mesh-delivery\"}]}", wire: "{\"by\":\"lead-47@workstation\",\"pulls\":[{\"head\":\"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\",\"number\":178,\"repository\":\"novox/mesh-sdk\"},{\"head\":\"cccccccccccccccccccccccccccccccccccccccc\",\"number\":261,\"repository\":\"novox/mesh-delivery\"}]}", + decode: func(b []byte) (any, error) { var v MergePullInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "merge-pull answers the call and each member merged", subject: "", given: "{\"call\":\"0123456789abcdef\",\"members\":[{\"commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"number\":178,\"repository\":\"novox/mesh-sdk\",\"state\":\"merged\"},{\"commit\":\"eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\"number\":261,\"repository\":\"novox/mesh-delivery\",\"state\":\"merged\"}]}", wire: "{\"call\":\"0123456789abcdef\",\"members\":[{\"commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"number\":178,\"repository\":\"novox/mesh-sdk\",\"state\":\"merged\"},{\"commit\":\"eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee\",\"number\":261,\"repository\":\"novox/mesh-delivery\",\"state\":\"merged\"}]}", + decode: func(b []byte) (any, error) { var v MergePullAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "merge-pull refuses every member when one is refused, naming why", subject: "", given: "{\"call\":\"0123456789abcdef\",\"members\":[{\"number\":178,\"repository\":\"novox/mesh-sdk\",\"state\":\"refused\",\"why\":\"the head moved: cccccccccccccccccccccccccccccccccccccccc, not the named aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},{\"number\":261,\"repository\":\"novox/mesh-delivery\",\"state\":\"judged\"}]}", wire: "{\"call\":\"0123456789abcdef\",\"members\":[{\"number\":178,\"repository\":\"novox/mesh-sdk\",\"state\":\"refused\",\"why\":\"the head moved: cccccccccccccccccccccccccccccccccccccccc, not the named aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa\"},{\"number\":261,\"repository\":\"novox/mesh-delivery\",\"state\":\"judged\"}]}", + decode: func(b []byte) (any, error) { var v MergePullAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "merge-pull refuses a member already merged, naming its commit", subject: "", given: "{\"call\":\"fedcba9876543210\",\"members\":[{\"commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"number\":178,\"repository\":\"novox/mesh-sdk\",\"state\":\"refused\",\"why\":\"already-merged\"}]}", wire: "{\"call\":\"fedcba9876543210\",\"members\":[{\"commit\":\"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb\",\"number\":178,\"repository\":\"novox/mesh-sdk\",\"state\":\"refused\",\"why\":\"already-merged\"}]}", + decode: func(b []byte) (any, error) { var v MergePullAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, + {name: "merge-pull answers an error, never none", subject: "", given: "{\"error\":\"the forge answered 502\",\"error-kind\":\"failed\"}", wire: "{\"error\":\"the forge answered 502\",\"error-kind\":\"failed\"}", + decode: func(b []byte) (any, error) { var v MergePullAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil}, } for _, c := range cases { v, err := c.decode([]byte(c.given)) diff --git a/modules/mesh-delivery-contracts/seats/git/fixtures/events.json b/modules/mesh-delivery-contracts/seats/git/fixtures/events.json index 98a0faa4..43d9aa1a 100644 --- a/modules/mesh-delivery-contracts/seats/git/fixtures/events.json +++ b/modules/mesh-delivery-contracts/seats/git/fixtures/events.json @@ -118,5 +118,32 @@ "head": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", "at": "2026-11-10T10:00:00Z" } + }, + { + "name": "merge-called is said once per call", + "of": "event:merge-called", + "subject": "mesh.seat.git.event.merge-called.0123456789abcdef", + "given": { + "account": "tools-shanks", + "at": "2026-11-20T02:00:00Z", + "by": "lead-47@workstation", + "call": "0123456789abcdef", + "members": [ + { + "branch": "main", + "commit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", + "head": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "number": 178, + "repository": "novox/mesh-sdk" + } + ], + "refused": [ + { + "number": 261, + "repository": "novox/mesh-delivery", + "why": "the forge refused the merge: conflict" + } + ] + } } ] diff --git a/modules/mesh-delivery-contracts/seats/git/fixtures/states.json b/modules/mesh-delivery-contracts/seats/git/fixtures/states.json index 89510c7c..824f1999 100644 --- a/modules/mesh-delivery-contracts/seats/git/fixtures/states.json +++ b/modules/mesh-delivery-contracts/seats/git/fixtures/states.json @@ -15,5 +15,30 @@ "said": "TestTheBusWhole failed", "at": "2026-11-10T10:00:00Z" } + }, + { + "name": "a merge call kept", + "of": "state:calls/call.", + "given": { + "account": "tools-shanks", + "at": "2026-11-20T02:00:00Z", + "by": "lead-47@workstation", + "members": [ + { + "commit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", + "head": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", + "number": 178, + "repository": "novox/mesh-sdk", + "state": "merged" + }, + { + "head": "cccccccccccccccccccccccccccccccccccccccc", + "number": 261, + "repository": "novox/mesh-delivery", + "state": "judged" + } + ], + "said": false + } } ] diff --git a/modules/mesh-delivery-contracts/seats/git/fixtures/verbs.json b/modules/mesh-delivery-contracts/seats/git/fixtures/verbs.json index 384e6f7a..2cccbd42 100644 --- a/modules/mesh-delivery-contracts/seats/git/fixtures/verbs.json +++ b/modules/mesh-delivery-contracts/seats/git/fixtures/verbs.json @@ -416,56 +416,6 @@ "error-kind": "failed" } }, - { - "name": "merge-pull asks", - "of": "verb:merge-pull.input", - "given": { - "id": "owed-5", - "repository": "novox/mesh-sdk", - "number": 178, - "head": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" - } - }, - { - "name": "merge-pull answers", - "of": "verb:merge-pull.answer", - "given": { - "id": "owed-5", - "performed": true, - "merge-commit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" - } - }, - { - "name": "merge-pull answers", - "of": "verb:merge-pull.answer", - "given": { - "id": "owed-5", - "refused": "the head moved: cccccccccccccccccccccccccccccccccccccccc, not the named aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - "refused-kind": "head-moved" - }, - "why": "a head that moved is refused by name, not performed" - }, - { - "name": "merge-pull answers an error, never none", - "of": "verb:merge-pull.answer", - "why": "a failed read or act is an error the caller reads as a failure (design 47 *The seat git*)", - "given": { - "error": "the forge answered 502", - "error-kind": "failed" - } - }, - { - "name": "merge-pull refuses a failed required step, naming the run, the module and the step", - "of": "verb:merge-pull.answer", - "given": { - "id": "merge-7", - "refused": "unit of nats:program failed at fp-0123 in main.12.nats", - "refused-kind": "policy-failed", - "run": "main.12.nats", - "module": "nats", - "step": "unit" - } - }, { "name": "branch asks a branch", "of": "verb:branch.input", @@ -475,13 +425,12 @@ } }, { - "name": "branch answers its head and protection", + "name": "branch answers its head", "of": "verb:branch.answer", "given": { "repository": "novox/mesh-catalog", "branch": "main", - "head": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", - "protected": true + "head": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" } }, { @@ -518,5 +467,91 @@ "error": "the forge answered 403", "error-kind": "refused" } + }, + { + "name": "merge-pull asks two pull requests in two repositories", + "of": "verb:merge-pull.input", + "given": { + "pulls": [ + { + "repository": "novox/mesh-sdk", + "number": 178, + "head": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + }, + { + "repository": "novox/mesh-delivery", + "number": 261, + "head": "cccccccccccccccccccccccccccccccccccccccc" + } + ], + "by": "lead-47@workstation" + } + }, + { + "name": "merge-pull answers the call and each member merged", + "of": "verb:merge-pull.answer", + "given": { + "call": "0123456789abcdef", + "members": [ + { + "repository": "novox/mesh-sdk", + "number": 178, + "state": "merged", + "commit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb" + }, + { + "repository": "novox/mesh-delivery", + "number": 261, + "state": "merged", + "commit": "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee" + } + ] + } + }, + { + "name": "merge-pull refuses every member when one is refused, naming why", + "of": "verb:merge-pull.answer", + "why": "every member is judged before any is merged (design 47 H \u00a7735)", + "given": { + "call": "0123456789abcdef", + "members": [ + { + "repository": "novox/mesh-sdk", + "number": 178, + "state": "refused", + "why": "the head moved: cccccccccccccccccccccccccccccccccccccccc, not the named aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa" + }, + { + "repository": "novox/mesh-delivery", + "number": 261, + "state": "judged" + } + ] + } + }, + { + "name": "merge-pull refuses a member already merged, naming its commit", + "of": "verb:merge-pull.answer", + "given": { + "call": "fedcba9876543210", + "members": [ + { + "repository": "novox/mesh-sdk", + "number": 178, + "state": "refused", + "commit": "bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb", + "why": "already-merged" + } + ] + } + }, + { + "name": "merge-pull answers an error, never none", + "of": "verb:merge-pull.answer", + "why": "a failed read or act is an error the caller reads as a failure (design 47 *The seat git*)", + "given": { + "error": "the forge answered 502", + "error-kind": "failed" + } } ] diff --git a/modules/mesh-delivery-contracts/seats/git/seat.json b/modules/mesh-delivery-contracts/seats/git/seat.json index c24a4f12..7af220d3 100644 --- a/modules/mesh-delivery-contracts/seats/git/seat.json +++ b/modules/mesh-delivery-contracts/seats/git/seat.json @@ -5,7 +5,7 @@ "grain": "whole", "domain": "Delivery", "decision": "novox/hq ADR 0111", - "description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer. The act verbs are the forge bridge's alone.", + "description": "The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 \u00a71, \u00a72). A failed read answers an error, never an empty answer.", "delivers": "git", "verbs": [ { @@ -56,7 +56,7 @@ }, { "name": "branch", - "description": "A branch's head, and whether a protection rule refuses a direct push and admits only merges (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found.", + "description": "A branch's head (design 47 *The seat git*, *Watched branches and the catalog graph per branch*). A branch the forge does not hold answers the error kind not-found.", "input": { "type": "object", "properties": { @@ -90,10 +90,6 @@ "description": "a commit, its full 40-hex sha", "pattern": "^[0-9a-f]{40}$" }, - "protected": { - "type": "boolean", - "description": "a protection rule refuses a direct push and admits only merges" - }, "error": { "type": "string", "description": "why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none" @@ -742,83 +738,66 @@ }, { "name": "merge-pull", - "description": "Merge a pull request with the forge tools' account at the head the caller names (design 47 *Approval is a step, and a session merges a pull request*). It judges that this is still the pull request's head and that the base branch's protection refuses a direct push, read again on every branch-moved, and refuses a head when any run at its build-input fingerprint failed a required step, judged from its own state failed-steps heard from the runner's step-ended, never by a call; a head with no run yet or a passed one merges, it never waits for a run and never asks an Approve (ADR 0666 section 11). Refused, naming why: a head that moved, a branch no protection guards, a failed required step (naming the run, the module and the step), no registrations yet (ADR 0667 section 10), a merge git refuses. A pull request already merged at that head is answered performed.", + "description": "Merge one or more pull requests with the forge tools' account, each at the head the caller names: one merge call, a delivery's start and, with two or more members, its group (design 47 H \u00a7734, \u00a7735, \u00a7766; ADR 0682 \u00a71, \u00a72). Every member is judged before any is merged: still the pull request's head, its base a watched branch, no run at the head's build-input fingerprint failed a required step (judged from its own state failed-steps), registrations heard; no branch protection is read. When one member is refused, none is merged. Then it merges them in the order named, writing the call in its state calls before the first merge, and says merge-called once. It answers once, at the call's end, naming the call and each member's outcome; a member already merged is refused already-merged, naming its commit.", "input": { "type": "object", "properties": { - "id": { + "pulls": { + "type": "array", + "minItems": 1, + "description": "the members, in the order they are merged", + "items": { + "type": "object", + "properties": { + "repository": { + "type": "string", + "description": "the repository, /", + "minLength": 1 + }, + "number": { + "type": "integer", + "description": "the pull request's number" + }, + "head": { + "type": "string", + "description": "the head the caller names", + "pattern": "^[0-9a-f]{40}$" + } + }, + "additionalProperties": false, + "required": [ + "repository", + "number", + "head" + ] + } + }, + "by": { "type": "string", - "description": "the act's id", + "description": "the caller as who@node, recorded beside the bus account the tool runner proves", "minLength": 1 - }, - "repository": { - "type": "string", - "description": "the repository, /", - "minLength": 1 - }, - "number": { - "type": "integer", - "description": "the pull request's number" - }, - "head": { - "type": "string", - "description": "the head the caller names", - "pattern": "^[0-9a-f]{40}$" } }, "additionalProperties": false, "required": [ - "id", - "repository", - "number", - "head" + "pulls", + "by" ] }, "answer": { "type": "object", "properties": { - "id": { + "call": { "type": "string", - "description": "the act's id, as the caller gave it" + "description": "the merge call, 16 lowercase hex characters made once per call", + "pattern": "^[0-9a-f]{16}$" }, - "performed": { - "type": "boolean", - "description": "the forge holds the act now" - }, - "held": { - "type": "boolean", - "description": "the id was already held on the pull request or the note, so nothing was done again" - }, - "merge-commit": { - "type": "string", - "description": "the merge commit" - }, - "refused": { - "type": "string", - "description": "why the forge or the holder refused the merge; the act is not performed" - }, - "refused-kind": { - "type": "string", - "enum": [ - "head-moved", - "unprotected", - "policy-failed", - "no-registrations", - "git-refused" - ], - "description": "which refusal, set with refused: head-moved, the pull request's head is not the one named; unprotected, the base branch's protection does not refuse a direct push; policy-failed, a run at the head's fingerprint failed a required step (run, module and step name it); no-registrations, no registration-changed heard yet (ADR 0667 section 10); git-refused, git refused the merge" - }, - "run": { - "type": "string", - "description": "for policy-failed, the run that failed the step: the runner's pipeline key" - }, - "module": { - "type": "string", - "description": "for policy-failed, the module" - }, - "step": { - "type": "string", - "description": "for policy-failed, the step" + "members": { + "type": "array", + "description": "each member's outcome, in the order named", + "items": { + "$ref": "#/defs/MemberOutcome" + } }, "error": { "type": "string", @@ -828,9 +807,10 @@ "$ref": "#/defs/ErrorKind" } }, - "description": "what merge-pull answers; error and error-kind alone when it fails" + "description": "what merge-pull answers at the call's end; error and error-kind alone when it fails" }, - "class": "act" + "class": "act", + "timeout": 120 }, { "name": "tag", @@ -1242,6 +1222,17 @@ "max-age-days": 90, "max-mib": 64 } + }, + { + "name": "merge-called", + "subject": "merge-called.", + "body": { + "$ref": "#/bodies/MergeCalled" + }, + "keep": { + "max-age-days": 30, + "max-mib": 64 + } } ], "family": { @@ -1263,6 +1254,21 @@ "description": "a failed required step" } ] + }, + { + "name": "calls", + "template": "state", + "history": 1, + "description": "every merge call, written before its first merge; one whose merge-called is not said is said at the holder's start; deleted past the stream merge-called's age (design 47 H \u00a7766, H-A-47)", + "key-forms": [ + { + "key": "call.", + "value": { + "$ref": "#/defs/Call" + }, + "description": "one merge call" + } + ] } ], "defs": { @@ -1520,6 +1526,206 @@ "run", "commits" ] + }, + "MemberOutcome": { + "type": "object", + "description": "one member of a merge call and where it stands (design 47 H \u00a7766, H-A-22)", + "properties": { + "repository": { + "type": "string" + }, + "number": { + "type": "integer" + }, + "state": { + "type": "string", + "enum": [ + "judged", + "merged", + "refused" + ], + "description": "judged, judged and not merged; merged, with its commit; refused, with why" + }, + "commit": { + "type": "string", + "description": "for merged, the merge commit; for a member refused already-merged, its commit", + "pattern": "^[0-9a-f]{40}$" + }, + "why": { + "type": "string", + "description": "for refused, why, naming the step for a failed required step" + } + }, + "required": [ + "repository", + "number", + "state" + ] + }, + "Call": { + "type": "object", + "description": "one merge call, written before its first merge and updated as each member merges (design 47 H \u00a7766)", + "properties": { + "by": { + "type": "string", + "description": "the caller as who@node" + }, + "account": { + "type": "string", + "description": "the bus account the tool runner proved for the call" + }, + "at": { + "type": "string", + "format": "date-time" + }, + "members": { + "type": "array", + "items": { + "$ref": "#/defs/CallMember" + } + }, + "said": { + "type": "boolean", + "description": "merge-called was said for it" + } + }, + "required": [ + "by", + "account", + "at", + "members", + "said" + ] + }, + "CallMember": { + "type": "object", + "description": "one member of a kept call", + "properties": { + "repository": { + "type": "string" + }, + "number": { + "type": "integer" + }, + "head": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + }, + "state": { + "type": "string", + "enum": [ + "judged", + "merged", + "refused" + ] + }, + "commit": { + "type": "string", + "description": "for merged, the merge commit", + "pattern": "^[0-9a-f]{40}$" + }, + "why": { + "type": "string", + "description": "for refused, why" + } + }, + "required": [ + "repository", + "number", + "head", + "state" + ] + } + }, + "bodies": { + "MergeCalled": { + "type": "object", + "description": "a merge call's members merged or refused, said once by the forge module (design 47 H \u00a7736, \u00a7767)", + "properties": { + "call": { + "type": "string", + "description": "the merge call, 16 lowercase hex characters made once per call", + "pattern": "^[0-9a-f]{16}$" + }, + "by": { + "type": "string", + "description": "the caller as who@node" + }, + "account": { + "type": "string", + "description": "the bus account the tool runner proved" + }, + "at": { + "type": "string", + "format": "date-time", + "description": "the time of the last merge" + }, + "members": { + "type": "array", + "description": "one per landed member", + "items": { + "type": "object", + "properties": { + "repository": { + "type": "string" + }, + "number": { + "type": "integer" + }, + "branch": { + "type": "string", + "description": "the pull request's base, a watched branch" + }, + "head": { + "type": "string", + "pattern": "^[0-9a-f]{40}$" + }, + "commit": { + "type": "string", + "description": "the merge commit the forge records for the pull request", + "pattern": "^[0-9a-f]{40}$" + } + }, + "required": [ + "repository", + "number", + "branch", + "head", + "commit" + ] + } + }, + "refused": { + "type": "array", + "description": "one per member not merged after every member was judged (design 47 H \u00a7767)", + "items": { + "type": "object", + "properties": { + "repository": { + "type": "string" + }, + "number": { + "type": "integer" + }, + "why": { + "type": "string" + } + }, + "required": [ + "repository", + "number", + "why" + ] + } + } + }, + "required": [ + "call", + "by", + "account", + "at", + "members" + ] } } } diff --git a/modules/mesh-delivery-contracts/ts/seats/git/index.d.ts b/modules/mesh-delivery-contracts/ts/seats/git/index.d.ts index 5fee3889..b2ee42ed 100644 --- a/modules/mesh-delivery-contracts/ts/seats/git/index.d.ts +++ b/modules/mesh-delivery-contracts/ts/seats/git/index.d.ts @@ -1,6 +1,6 @@ // Code generated by seatgen from the seat definitions; DO NOT EDIT. -// The contract of the seat "git", defined whole (seats/git/seat.json): The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 §1, §2). A failed read answers an error, never an empty answer. The act verbs are the forge bridge's alone. +// The contract of the seat "git", defined whole (seats/git/seat.json): The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 §1, §2). A failed read answers an error, never an empty answer. export declare const seat: "git"; @@ -30,6 +30,7 @@ export declare const events: { readonly forgeDelete: "forge-delete"; readonly repoWritable: "repo-writable"; readonly branchMoved: "branch-moved"; + readonly mergeCalled: "merge-called"; }; export declare const family: { readonly name: "git.events"; readonly maxAgeDays: 7 }; @@ -52,8 +53,15 @@ export declare const branchMovedStream: "SEAT_git_branch-moved"; export declare const branchMovedSubject: "mesh.seat.git.event.branch-moved"; +export declare const mergeCalledStream: "SEAT_git_merge-called"; + +export declare function mergeCalledSubject(call: string): string; + +export declare const mergeCalledSubjectAll: "mesh.seat.git.event.merge-called.*"; + export declare const states: { readonly failedSteps: "failed-steps"; + readonly calls: "calls"; }; /** The key of one value of the state failed-steps under the form "..". */ @@ -62,6 +70,36 @@ export declare function failedStepsByModuleFingerprintStepKey(module: string, fi /** The parts of a key of the form "..", or undefined for a key of another form. */ export declare function parseFailedStepsByModuleFingerprintStepKey(_key: string): { module: string; fingerprint: string; step: string } | undefined; +/** The key of one value of the state calls under the form "call.". */ +export declare function callsByCallCallKey(call: string): string; + +/** The parts of a key of the form "call.", or undefined for a key of another form. */ +export declare function parseCallsByCallCallKey(_key: string): { call: string } | undefined; + +/** one merge call, written before its first merge and updated as each member merges (design 47 H §766) */ +export interface Call { + /** the bus account the tool runner proved for the call */ + "account": string; + "at": string; + /** the caller as who@node */ + "by": string; + "members": CallMember[]; + /** merge-called was said for it */ + "said": boolean; +} + +/** one member of a kept call */ +export interface CallMember { + /** for merged, the merge commit */ + "commit"?: string; + "head": string; + "number": number; + "repository": string; + "state": "judged" | "merged" | "refused"; + /** for refused, why */ + "why"?: string; +} + /** what a pull request changed */ export interface Change { /** the changed directories that hold a module at its head; absent when they could not be read */ @@ -96,6 +134,18 @@ export interface FailedStep { "v"?: number; } +/** one member of a merge call and where it stands (design 47 H §766, H-A-22) */ +export interface MemberOutcome { + /** for merged, the merge commit; for a member refused already-merged, its commit */ + "commit"?: string; + "number": number; + "repository": string; + /** judged, judged and not merged; merged, with its commit; refused, with why */ + "state": "judged" | "merged" | "refused"; + /** for refused, why, naming the step for a failed required step */ + "why"?: string; +} + /** what the forge would merge now, for an open pull request (issues 1275, 1945; ADR 0441 §1): answered whole or not at all, and a read the forge could not make answers the verb's error, never a guess; absent for a merged or closed one */ export interface Merging { /** the forge's own word on whether it merges into its base now: false while it is in conflict with its base, or while the forge works that out after the base moved */ @@ -159,6 +209,38 @@ export interface Status { "target"?: string; } +export interface MergeCalledMembersItem { + /** the pull request's base, a watched branch */ + "branch": string; + /** the merge commit the forge records for the pull request */ + "commit": string; + "head": string; + "number": number; + "repository": string; +} + +export interface MergeCalledRefusedItem { + "number": number; + "repository": string; + "why": string; +} + +/** a merge call's members merged or refused, said once by the forge module (design 47 H §736, §767) */ +export interface MergeCalled { + /** the bus account the tool runner proved */ + "account": string; + /** the time of the last merge */ + "at": string; + /** the caller as who@node */ + "by": string; + /** the merge call, 16 lowercase hex characters made once per call */ + "call": string; + /** one per landed member */ + "members": MergeCalledMembersItem[]; + /** one per member not merged after every member was judged (design 47 H §767) */ + "refused"?: MergeCalledRefusedItem[]; +} + /** is what pull takes. */ export interface PullInput { /** instead of the number: the merge commit it made */ @@ -193,8 +275,6 @@ export interface BranchAnswer { "error-kind"?: ErrorKind; /** a commit, its full 40-hex sha */ "head"?: string; - /** a protection rule refuses a direct push and admits only merges */ - "protected"?: boolean; "repository"?: string; } @@ -448,41 +528,32 @@ export interface NoteAnswer { "performed"?: boolean; } -/** is what merge-pull takes. */ -export interface MergePullInput { +export interface MergePullInputPullsItem { /** the head the caller names */ "head": string; - /** the act's id */ - "id": string; /** the pull request's number */ "number": number; /** the repository, / */ "repository": string; } +/** is what merge-pull takes. */ +export interface MergePullInput { + /** the caller as who@node, recorded beside the bus account the tool runner proves */ + "by": string; + /** the members, in the order they are merged */ + "pulls": MergePullInputPullsItem[]; +} + /** is what merge-pull answers. */ export interface MergePullAnswer { + /** the merge call, 16 lowercase hex characters made once per call */ + "call"?: string; /** why the forge could not answer, or refused: set alone with error-kind, and a caller reads it as a failure, never as none */ "error"?: string; "error-kind"?: ErrorKind; - /** the id was already held on the pull request or the note, so nothing was done again */ - "held"?: boolean; - /** the act's id, as the caller gave it */ - "id"?: string; - /** the merge commit */ - "merge-commit"?: string; - /** for policy-failed, the module */ - "module"?: string; - /** the forge holds the act now */ - "performed"?: boolean; - /** why the forge or the holder refused the merge; the act is not performed */ - "refused"?: string; - /** which refusal, set with refused: head-moved, the pull request's head is not the one named; unprotected, the base branch's protection does not refuse a direct push; policy-failed, a run at the head's fingerprint failed a required step (run, module and step name it); no-registrations, no registration-changed heard yet (ADR 0667 section 10); git-refused, git refused the merge */ - "refused-kind"?: "head-moved" | "unprotected" | "policy-failed" | "no-registrations" | "git-refused"; - /** for policy-failed, the run that failed the step: the runner's pipeline key */ - "run"?: string; - /** for policy-failed, the step */ - "step"?: string; + /** each member's outcome, in the order named */ + "members"?: MemberOutcome[]; } /** is what tag takes. */ @@ -646,6 +717,12 @@ export interface BranchMovedEvent { "repository": string; } +/** is the body of the event merge-called. */ +export type MergeCalledEvent = MergeCalled; + /** is one value of the state failed-steps under the key ... */ export type FailedStepsByModuleFingerprintStepValue = FailedStep; +/** is one value of the state calls under the key call.. */ +export type CallsByCallCallValue = Call; + diff --git a/modules/mesh-delivery-contracts/ts/seats/git/index.js b/modules/mesh-delivery-contracts/ts/seats/git/index.js index c0bea488..8fb5955d 100644 --- a/modules/mesh-delivery-contracts/ts/seats/git/index.js +++ b/modules/mesh-delivery-contracts/ts/seats/git/index.js @@ -1,6 +1,6 @@ // Code generated by seatgen from the seat definitions; DO NOT EDIT. -// The contract of the seat "git", defined whole (seats/git/seat.json): The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 §1, §2). A failed read answers an error, never an empty answer. The act verbs are the forge bridge's alone. +// The contract of the seat "git", defined whole (seats/git/seat.json): The forge: every read and act a delivery part makes of the mesh's git repositories, and what the forge says happened (design 47 *The seat git*, ADR 0596 §1, §2). A failed read answers an error, never an empty answer. export const seat = "git"; @@ -30,6 +30,7 @@ export const events = { forgeDelete: "forge-delete", repoWritable: "repo-writable", branchMoved: "branch-moved", + mergeCalled: "merge-called", }; export const family = { name: "git.events", maxAgeDays: 7 }; @@ -52,8 +53,17 @@ export const branchMovedStream = "SEAT_git_branch-moved"; export const branchMovedSubject = "mesh.seat.git.event.branch-moved"; +export const mergeCalledStream = "SEAT_git_merge-called"; + +export function mergeCalledSubject(call) { + return "mesh.seat.git.event.merge-called." + call; +} + +export const mergeCalledSubjectAll = "mesh.seat.git.event.merge-called.*"; + export const states = { failedSteps: "failed-steps", + calls: "calls", }; /** The key of one value of the state failed-steps under the form "..". */ @@ -79,3 +89,20 @@ export function parseFailedStepsByModuleFingerprintStepKey(_key) { return { module, fingerprint, step }; } +/** The key of one value of the state calls under the form "call.". */ +export function callsByCallCallKey(call) { + return "call." + call; +} + +/** The parts of a key of the form "call.", or undefined for a key of another form. */ +export function parseCallsByCallCallKey(_key) { + let _rest = _key; + if (!_rest.startsWith("call.")) return undefined; + _rest = _rest.slice(5); + if (_rest === "") return undefined; + const call = _rest; + _rest = ""; + if (_rest !== "") return undefined; + return { call }; +} +