D4: the catalog seat pages registrations, says the seat list, takes a source alone

registrations filters by repository beside module while it reads, pages by
the cursor next and answers capped and total. The read verb seat-list answers
the seat list's object in seat-lists by digest, size and name. A registration
takes a source-only form under source.<owner>.<name>, with origin, one branch,
policy and check (a build seat and a step kind), naming no module; its history
keeps the same key. The seat's form rises to 2.

Builds: design 47 H2 §806, §811, §814, §815; H-A-349 DQ-9, DQ-10
This commit is contained in:
2026-11-22 00:05:48 +01:00
parent 1767d7b4e9
commit 278310cc67
7 changed files with 489 additions and 22 deletions
@@ -14,13 +14,13 @@ const Seat = "mesh-catalog"
// Form is the form of the seat's values, events and answers this contract was generated at (design 47 H2 §780):
// a reader of a value of another form says "form N, this reader knows M".
const Form = 1
const Form = 2
// The forms and the digest of the fields this contract was generated from: the generator's compare fails a definition
// whose fields changed while its forms did not (design 47 H2 §780).
const (
generatedForms = "1"
generatedFieldsDigest = "ActingRule=8a83ce7e0457 Artifact=78b05c1a9ec3 ArtifactPackage=2a3a660a934d ArtifactRef=a2f06147f4b6 BuildEdge=76f0684e254a BuildEdges=d2b95000259e BuildEdgesByModuleBranchValue=4fdf7cc1e723 CandidatesByGroupValue=9ea8c6c580d2 CandidatesByGroupValuePullsItem=90fb03643258 CandidatesByGroupValuePullsItemFpsValue=4c6783201aa3 CatalogEntry=d154f232237b CatalogRevision=d1ecaaa484af CatalogRevisionDefinitionsItem=77fcff620d48 CatalogRevisionEvent=710cbc5bfff1 CatalogRevisionsByBranchRevisionValue=17e54f635d35 CatalogRevisionsByCandidateGroupHeadsValue=17e54f635d35 CatalogRevisionsByEntryDigestValue=8755036a3051 DependentsAnswer=7538f2f5e68e Edge=7242732afaef EntryAnswer=805c2ff28e1c EntryInputs=76a7f8690dd2 EntryRef=ff109e5089e1 Fill=80f442916429 FillingEvent=5bd4df78ed84 FingerprintInputs=99a6df7f991f FullEvent=5bd4df78ed84 Head=774b4bf88ba4 InputAnswer=cd41ee65565d InputsByTimeDigestValue=a2f06147f4b6 ManifestsByDigestValue=51b3822b29c6 ModuleAnswer=499a03ce9b27 ModuleAnswerModule=c0f679e09f08 ModulesAnswer=6d119571c69e ModulesAnswerModulesItem=a70f39c60b67 ModulesByModuleValue=fc7530ba893a ModulesByModuleValueInputs2=99a6df7f991f Outdated=e820214f66bc OutdatedAnswer=275fb25266b9 OutdatedDependency=dc35dca1b683 PackagesByModuleValue=2b62574b709f PackagesByModuleValuePackagesItem=a7d30558470d PackagesByPackageSeriesValue=07421d8d3411 PackagesByPackageSeriesValueNewest=aba144994370 PackagesByPackageSeriesValueNewestContents=eca2ccf56913 PackagesByPackageSeriesValueNewestContentsPackagesItem=a7d30558470d PackagesByPackageSeriesValueNumbered=c8ffc628599c PackagesByPackageSeriesValueNumberedContents=0def6c0794ee PackagesByPackageSeriesValueNumberedContentsPackagesItem=a7d30558470d Policy=719e2f460c6f PolicyAnswer=46cdf8430557 PredefinedByListValue=ec8e3febe8ac ProvidesAnswer=7538f2f5e68e RegisterAnswer=46cdf8430557 Registration=2de67522639b RegistrationAsked=55adba349c24 RegistrationChangedEvent=99a3268edf41 RegistrationHistoryByModuleVersionValue=0999b5bb7dc7 RegistrationsAnswer=90757c7185f6 RegistrationsByModuleValue=0999b5bb7dc7 RevisionAnswer=258ea5124931 RoomEvent=5bd4df78ed84 SeatDefinitionChangedEvent=e271d24d58f7 SeatDefinitionRemovedEvent=f7d6171111e6 SeatDefinitionsAnswer=0fd6a59fec59 SeatDefinitionsAnswerEntry=d006f68d2be5 SeatDefinitionsAnswerSeatsItem=e271d24d58f7 StepStatuses=4f50aa633e61 TakeInEntry=545ec1528499 ToolchainUsed=43b6d42376fb UnwatchAnswer=46cdf8430557 VersionArtifact=438c49a392b0 VersionEdge=b0f80e83f4dc VersionEntry=33f5b00dbda9 VersionReleasedEvent=4ccf1ea90e7f VersionsAnswer=b59e6e057e7b VersionsByModuleVersionValue=e546dfadb913 VersionsFilledEvent=4cc437912dc3 WatchAnswer=46cdf8430557"
generatedForms = "2"
generatedFieldsDigest = "ActingRule=8a83ce7e0457 Artifact=78b05c1a9ec3 ArtifactPackage=2a3a660a934d ArtifactRef=a2f06147f4b6 BuildEdge=76f0684e254a BuildEdges=d2b95000259e BuildEdgesByModuleBranchValue=4fdf7cc1e723 CandidatesByGroupValue=9ea8c6c580d2 CandidatesByGroupValuePullsItem=90fb03643258 CandidatesByGroupValuePullsItemFpsValue=4c6783201aa3 CatalogEntry=d154f232237b CatalogRevision=d1ecaaa484af CatalogRevisionDefinitionsItem=77fcff620d48 CatalogRevisionEvent=710cbc5bfff1 CatalogRevisionsByBranchRevisionValue=17e54f635d35 CatalogRevisionsByCandidateGroupHeadsValue=17e54f635d35 CatalogRevisionsByEntryDigestValue=8755036a3051 DependentsAnswer=7538f2f5e68e Edge=7242732afaef EntryAnswer=805c2ff28e1c EntryInputs=76a7f8690dd2 EntryRef=ff109e5089e1 Fill=80f442916429 FillingEvent=5bd4df78ed84 FingerprintInputs=99a6df7f991f FullEvent=5bd4df78ed84 Head=774b4bf88ba4 InputAnswer=cd41ee65565d InputsByTimeDigestValue=a2f06147f4b6 ManifestsByDigestValue=51b3822b29c6 ModuleAnswer=499a03ce9b27 ModuleAnswerModule=c0f679e09f08 ModulesAnswer=6d119571c69e ModulesAnswerModulesItem=a70f39c60b67 ModulesByModuleValue=fc7530ba893a ModulesByModuleValueInputs2=99a6df7f991f Outdated=e820214f66bc OutdatedAnswer=275fb25266b9 OutdatedDependency=dc35dca1b683 PackagesByModuleValue=2b62574b709f PackagesByModuleValuePackagesItem=a7d30558470d PackagesByPackageSeriesValue=07421d8d3411 PackagesByPackageSeriesValueNewest=aba144994370 PackagesByPackageSeriesValueNewestContents=eca2ccf56913 PackagesByPackageSeriesValueNewestContentsPackagesItem=a7d30558470d PackagesByPackageSeriesValueNumbered=c8ffc628599c PackagesByPackageSeriesValueNumberedContents=0def6c0794ee PackagesByPackageSeriesValueNumberedContentsPackagesItem=a7d30558470d Policy=719e2f460c6f PolicyAnswer=46cdf8430557 PredefinedByListValue=ec8e3febe8ac ProvidesAnswer=7538f2f5e68e RegisterAnswer=46cdf8430557 Registration=ef03d1b2e73f RegistrationAsked=55adba349c24 RegistrationChangedEvent=99a3268edf41 RegistrationHistoryByModuleVersionValue=0999b5bb7dc7 RegistrationHistoryBySourceOwnerNameVersionValue=0999b5bb7dc7 RegistrationsAnswer=8849ef618cf3 RegistrationsByModuleValue=0999b5bb7dc7 RegistrationsBySourceOwnerNameValue=0999b5bb7dc7 RevisionAnswer=258ea5124931 RoomEvent=5bd4df78ed84 SeatDefinitionChangedEvent=e271d24d58f7 SeatDefinitionRemovedEvent=f7d6171111e6 SeatDefinitionsAnswer=0fd6a59fec59 SeatDefinitionsAnswerEntry=d006f68d2be5 SeatDefinitionsAnswerSeatsItem=e271d24d58f7 SeatListAnswer=912c0cebcf0a SourceCheck=d1ed7cbbd579 StepStatuses=4f50aa633e61 TakeInEntry=545ec1528499 ToolchainUsed=43b6d42376fb UnwatchAnswer=46cdf8430557 VersionArtifact=438c49a392b0 VersionEdge=b0f80e83f4dc VersionEntry=33f5b00dbda9 VersionReleasedEvent=4ccf1ea90e7f VersionsAnswer=b59e6e057e7b VersionsByModuleVersionValue=e546dfadb913 VersionsFilledEvent=4cc437912dc3 WatchAnswer=46cdf8430557"
)
const (
@@ -29,6 +29,7 @@ const (
VerbProvides = "provides"
VerbDependents = "dependents"
VerbSeatDefinitions = "seat-definitions"
VerbSeatList = "seat-list"
VerbRevision = "revision"
VerbRegistrations = "registrations"
VerbRegister = "register"
@@ -55,7 +56,7 @@ const (
// Verbs is every verb the seat serves, in its definition's order: a new copy each call.
func Verbs() []string {
return []string{VerbModules, VerbModule, VerbProvides, VerbDependents, VerbSeatDefinitions, VerbRevision, VerbRegistrations, VerbRegister, VerbPolicy, VerbWatch, VerbUnwatch, VerbVersions, VerbOutdated, VerbInput, VerbEntry}
return []string{VerbModules, VerbModule, VerbProvides, VerbDependents, VerbSeatDefinitions, VerbSeatList, VerbRevision, VerbRegistrations, VerbRegister, VerbPolicy, VerbWatch, VerbUnwatch, VerbVersions, VerbOutdated, VerbInput, VerbEntry}
}
// Events is every event published on the seat's subject: a new copy each call.
@@ -410,6 +411,43 @@ func DecodeRegistrationsByModuleValue(raw []byte) (RegistrationsByModuleValue, i
return v, formRead(raw), nil
}
// RegistrationsBySourceOwnerNameKey is the key of one value of the state registrations under the form "source.<owner>.<name>".
func RegistrationsBySourceOwnerNameKey(owner, name string) string {
return "source." + owner + "." + name
}
// ParseRegistrationsBySourceOwnerNameKey reads the parts of a key of the form "source.<owner>.<name>", in the order of the form; the last result is false for a key of another form.
func ParseRegistrationsBySourceOwnerNameKey(key string) (string, string, bool) {
rest := key
if !strings.HasPrefix(rest, "source.") {
return "", "", false
}
rest = rest[7:]
v1, after1, found1 := strings.Cut(rest, ".")
if !found1 || v1 == "" {
return "", "", false
}
rest = after1
if rest == "" {
return "", "", false
}
v3 := rest
rest = ""
if rest != "" {
return "", "", false
}
return v1, v3, true
}
// DecodeRegistrationsBySourceOwnerNameValue reads one value of the state registrations under the form "source.<owner>.<name>" as another part wrote it: a field RegistrationsBySourceOwnerNameValue does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780).
func DecodeRegistrationsBySourceOwnerNameValue(raw []byte) (RegistrationsBySourceOwnerNameValue, int, error) {
var v RegistrationsBySourceOwnerNameValue
if err := json.Unmarshal(raw, &v); err != nil {
return v, 0, err
}
return v, formRead(raw), nil
}
// RegistrationHistoryByModuleVersionKey is the key of one value of the state registration-history under the form "<module>.<version>".
func RegistrationHistoryByModuleVersionKey(module, version string) string {
return module + "." + version
@@ -443,6 +481,48 @@ func DecodeRegistrationHistoryByModuleVersionValue(raw []byte) (RegistrationHist
return v, formRead(raw), nil
}
// RegistrationHistoryBySourceOwnerNameVersionKey is the key of one value of the state registration-history under the form "source.<owner>.<name>.<version>".
func RegistrationHistoryBySourceOwnerNameVersionKey(owner, name, version string) string {
return "source." + owner + "." + name + "." + version
}
// ParseRegistrationHistoryBySourceOwnerNameVersionKey reads the parts of a key of the form "source.<owner>.<name>.<version>", in the order of the form; the last result is false for a key of another form.
func ParseRegistrationHistoryBySourceOwnerNameVersionKey(key string) (string, string, string, bool) {
rest := key
if !strings.HasPrefix(rest, "source.") {
return "", "", "", false
}
rest = rest[7:]
v1, after1, found1 := strings.Cut(rest, ".")
if !found1 || v1 == "" {
return "", "", "", false
}
rest = after1
v3, after3, found3 := strings.Cut(rest, ".")
if !found3 || v3 == "" {
return "", "", "", false
}
rest = after3
if rest == "" {
return "", "", "", false
}
v5 := rest
rest = ""
if rest != "" {
return "", "", "", false
}
return v1, v3, v5, true
}
// DecodeRegistrationHistoryBySourceOwnerNameVersionValue reads one value of the state registration-history under the form "source.<owner>.<name>.<version>" as another part wrote it: a field RegistrationHistoryBySourceOwnerNameVersionValue does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780).
func DecodeRegistrationHistoryBySourceOwnerNameVersionValue(raw []byte) (RegistrationHistoryBySourceOwnerNameVersionValue, int, error) {
var v RegistrationHistoryBySourceOwnerNameVersionValue
if err := json.Unmarshal(raw, &v); err != nil {
return v, 0, err
}
return v, formRead(raw), nil
}
// VersionsByModuleVersionKey is the key of one value of the state versions under the form "<module>.<version>".
func VersionsByModuleVersionKey(module, version string) string { return module + "." + version }
@@ -807,20 +887,23 @@ type Policy struct {
Steps StepStatuses `json:"steps"`
}
// Registration is a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve.
// Registration is a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve; or a source-only registration of a repository with no module (design 47 H2 §815): its origin, one watched branch, its policy and its check, naming no module and no path, kept under source.<owner>.<name>.
type Registration struct {
At *time.Time `json:"at,omitempty"`
// its watched branches, the first the default a placement runs
Branches []string `json:"branches"`
// who asked the change
By string `json:"by,omitempty"`
// for a source-only registration, the one step its heads run (design 47 H2 §815)
Check *SourceCheck `json:"check,omitempty"`
// is the form of what this value carries, left out while it is 1 (design 47 H2 §780).
Form int64 `json:"form,omitempty"`
Module string `json:"module"`
Form int64 `json:"form,omitempty"`
// the module; absent for a source-only registration
Module string `json:"module,omitempty"`
// its git origin, the repository as <owner>/<name>
Origin string `json:"origin"`
// the path of its manifest in the repository
Path string `json:"path"`
// the path of its manifest in the repository; absent for a source-only registration
Path string `json:"path,omitempty"`
Policy Policy `json:"policy"`
// the layout version
V int64 `json:"v,omitempty"`
@@ -855,6 +938,28 @@ const (
RegistrationAskedRefusedNothingMoves = "nothing moves"
)
// SourceCheck is the check of a source-only registration: a build seat and a step kind, run at the repository's root, never a free command (design 47 H2 §815).
type SourceCheck struct {
// the build seat that runs it
Seat string `json:"seat"`
// the step kind
Step string `json:"step"`
}
// The values of SourceCheck's seat.
const (
SourceCheckSeatNodeBuildGo = "node-build-go"
SourceCheckSeatNodeBuildNode = "node-build-node"
SourceCheckSeatNodeBuildImage = "node-build-image"
)
// The values of SourceCheck's step.
const (
SourceCheckStepLint = "lint"
SourceCheckStepUnit = "unit"
SourceCheckStepIntegration = "integration"
)
// StepStatuses is the status of each pipeline step (design 47 *Pipeline steps and the policy*); a step left out keeps the module's.
type StepStatuses struct {
// required runs and holds the delivery until it passes; optional runs, a failure is shown and may be accepted; bypass runs nothing and is said as bypassed
@@ -1123,6 +1228,22 @@ type SeatDefinitionsAnswer struct {
Seats []SeatDefinitionsAnswerSeatsItem `json:"seats,omitempty"`
}
// SeatListInput is what seat-list takes.
type SeatListInput struct {
}
// SeatListAnswer is what seat-list answers.
type SeatListAnswer struct {
// the seat list's digest
Digest string `json:"digest"`
// is the form of what this value carries, left out while it is 1 (design 47 H2 §780).
Form int64 `json:"form,omitempty"`
// the object's name in seat-lists
Object string `json:"object"`
// the object's size in bytes
Size int64 `json:"size"`
}
// RevisionInput is what revision takes.
type RevisionInput struct {
// the last module of the page before; absent: the first page
@@ -1158,16 +1279,26 @@ type RegistrationsInput struct {
History bool `json:"history,omitempty"`
// one module; absent, every registration
Module string `json:"module,omitempty"`
// the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)
Next string `json:"next,omitempty"`
// only the registrations of this repository, <owner>/<name>, applied while reading (design 47 H2 §806)
Repository string `json:"repository,omitempty"`
}
// RegistrationsAnswer is what registrations answers.
type RegistrationsAnswer struct {
Fill *Fill `json:"fill,omitempty"`
// yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §806)
Capped bool `json:"capped,omitempty"`
Fill *Fill `json:"fill,omitempty"`
// is the form of what this value carries, left out while it is 1 (design 47 H2 §780).
Form int64 `json:"form,omitempty"`
// every version of the one module asked, oldest first
History []Registration `json:"history,omitempty"`
History []Registration `json:"history,omitempty"`
// the cursor of the next page, opaque; empty at the end (design 47 H2 §779)
Next string `json:"next,omitempty"`
Registrations []Registration `json:"registrations"`
// how many registrations the filters hold in all (design 47 H2 §811)
Total int64 `json:"total,omitempty"`
}
// RegisterInput is what register takes.
@@ -1590,9 +1721,15 @@ type CatalogRevisionsByEntryDigestValue = CatalogEntry
// RegistrationsByModuleValue is one value of the state registrations under the key <module>.
type RegistrationsByModuleValue = Registration
// RegistrationsBySourceOwnerNameValue is one value of the state registrations under the key source.<owner>.<name>.
type RegistrationsBySourceOwnerNameValue = Registration
// RegistrationHistoryByModuleVersionValue is one value of the state registration-history under the key <module>.<version>.
type RegistrationHistoryByModuleVersionValue = Registration
// RegistrationHistoryBySourceOwnerNameVersionValue is one value of the state registration-history under the key source.<owner>.<name>.<version>.
type RegistrationHistoryBySourceOwnerNameVersionValue = Registration
// VersionsByModuleVersionValue is one value of the state versions under the key <module>.<version>.
type VersionsByModuleVersionValue = VersionEntry
@@ -1647,6 +1784,15 @@ func DecodeSeatDefinitionsAnswer(raw []byte) (SeatDefinitionsAnswer, int, error)
return v, formRead(raw), nil
}
// DecodeSeatListAnswer reads a SeatListAnswer as another part wrote it: a field this reader does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780).
func DecodeSeatListAnswer(raw []byte) (SeatListAnswer, int, error) {
var v SeatListAnswer
if err := json.Unmarshal(raw, &v); err != nil {
return v, 0, err
}
return v, formRead(raw), nil
}
// DecodeRevisionAnswer reads a RevisionAnswer as another part wrote it: a field this reader does not know is left unread, never refused; the form read is answered, 1 when absent (design 47 H2 §780).
func DecodeRevisionAnswer(raw []byte) (RevisionAnswer, int, error) {
var v RevisionAnswer
@@ -119,6 +119,18 @@ func TestFixtures(t *testing.T) {
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "a source-only registration of a repository with no module", subject: "", given: "{\"at\":\"2026-11-22T00:10:00Z\",\"branches\":[\"main\"],\"by\":\"operator@workstation\",\"check\":{\"seat\":\"node-build-go\",\"step\":\"unit\"},\"origin\":\"novox/hq\",\"policy\":{\"steps\":{\"approval\":\"bypass\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":1,\"warrant\":\"ask-m2kx9a1b3c4d6a\"}", wire: "{\"at\":\"2026-11-22T00:10:00Z\",\"branches\":[\"main\"],\"by\":\"operator@workstation\",\"check\":{\"seat\":\"node-build-go\",\"step\":\"unit\"},\"origin\":\"novox/hq\",\"policy\":{\"steps\":{\"approval\":\"bypass\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":1,\"warrant\":\"ask-m2kx9a1b3c4d6a\"}",
decode: func(b []byte) (any, error) {
var v RegistrationsBySourceOwnerNameValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "one version of a source-only registration in the history", subject: "", given: "{\"at\":\"2026-11-22T00:10:00Z\",\"branches\":[\"main\"],\"by\":\"operator@workstation\",\"check\":{\"seat\":\"node-build-go\",\"step\":\"unit\"},\"origin\":\"novox/hq\",\"policy\":{\"steps\":{\"approval\":\"bypass\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":1,\"warrant\":\"ask-m2kx9a1b3c4d6a\"}", wire: "{\"at\":\"2026-11-22T00:10:00Z\",\"branches\":[\"main\"],\"by\":\"operator@workstation\",\"check\":{\"seat\":\"node-build-go\",\"step\":\"unit\"},\"origin\":\"novox/hq\",\"policy\":{\"steps\":{\"approval\":\"bypass\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":1,\"warrant\":\"ask-m2kx9a1b3c4d6a\"}",
decode: func(b []byte) (any, error) {
var v RegistrationHistoryBySourceOwnerNameVersionValue
err := json.Unmarshal(b, &v)
return v, err
}, subjectIs: nil},
{name: "revision asks the trunk's newest", subject: "", given: "{}", wire: "{}",
decode: func(b []byte) (any, error) { var v RevisionInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "revision asks a candidate's, from a page on", subject: "", given: "{\"after\":\"mesh-build-go\",\"group\":\"feat/47-G\",\"heads\":\"0123456789ab\"}", wire: "{\"after\":\"mesh-build-go\",\"group\":\"feat/47-G\",\"heads\":\"0123456789ab\"}",
@@ -163,6 +175,12 @@ func TestFixtures(t *testing.T) {
decode: func(b []byte) (any, error) { var v InputAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "entry asks by fingerprint", subject: "", given: "{\"fingerprint\":\"src2:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"}", wire: "{\"fingerprint\":\"src2:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef\"}",
decode: func(b []byte) (any, error) { var v EntryInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "registrations of one repository from a cursor", subject: "", given: "{\"next\":\"c-120\",\"repository\":\"novox/mesh-catalog\"}", wire: "{\"next\":\"c-120\",\"repository\":\"novox/mesh-catalog\"}",
decode: func(b []byte) (any, error) { var v RegistrationsInput; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "registrations answers a capped page with a source-only registration and the next cursor", subject: "", given: "{\"capped\":true,\"next\":\"c-121\",\"registrations\":[{\"at\":\"2026-11-22T00:10:00Z\",\"branches\":[\"main\"],\"by\":\"operator@workstation\",\"check\":{\"seat\":\"node-build-go\",\"step\":\"unit\"},\"origin\":\"novox/hq\",\"policy\":{\"steps\":{\"approval\":\"bypass\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":1,\"warrant\":\"ask-m2kx9a1b3c4d6a\"}],\"total\":118}", wire: "{\"capped\":true,\"next\":\"c-121\",\"registrations\":[{\"at\":\"2026-11-22T00:10:00Z\",\"branches\":[\"main\"],\"by\":\"operator@workstation\",\"check\":{\"seat\":\"node-build-go\",\"step\":\"unit\"},\"origin\":\"novox/hq\",\"policy\":{\"steps\":{\"approval\":\"bypass\",\"review\":\"optional\",\"unit\":\"required\"}},\"v\":1,\"version\":1,\"warrant\":\"ask-m2kx9a1b3c4d6a\"}],\"total\":118}",
decode: func(b []byte) (any, error) { var v RegistrationsAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
{name: "seat-list answers the seat list's object by its digest", subject: "", given: "{\"digest\":\"sha256:eeee\",\"object\":\"sha256-eeee\",\"size\":412345}", wire: "{\"digest\":\"sha256:eeee\",\"object\":\"sha256-eeee\",\"size\":412345}",
decode: func(b []byte) (any, error) { var v SeatListAnswer; err := json.Unmarshal(b, &v); return v, err }, subjectIs: nil},
}
for _, c := range cases {
v, err := c.decode([]byte(c.given))
@@ -549,5 +549,57 @@
"name": "an input",
"of": "state:inputs/<time>.<digest>",
"given": "eyJ2IjoxfQ=="
},
{
"name": "a source-only registration of a repository with no module",
"of": "state:registrations/source.<owner>.<name>",
"given": {
"v": 1,
"origin": "novox/hq",
"branches": [
"main"
],
"policy": {
"steps": {
"unit": "required",
"review": "optional",
"approval": "bypass"
}
},
"check": {
"seat": "node-build-go",
"step": "unit"
},
"version": 1,
"by": "operator@workstation",
"warrant": "ask-m2kx9a1b3c4d6a",
"at": "2026-11-22T00:10:00Z"
}
},
{
"name": "one version of a source-only registration in the history",
"of": "state:registration-history/source.<owner>.<name>.<version>",
"given": {
"v": 1,
"origin": "novox/hq",
"branches": [
"main"
],
"policy": {
"steps": {
"unit": "required",
"review": "optional",
"approval": "bypass"
}
},
"check": {
"seat": "node-build-go",
"step": "unit"
},
"version": 1,
"by": "operator@workstation",
"warrant": "ask-m2kx9a1b3c4d6a",
"at": "2026-11-22T00:10:00Z"
}
}
]
@@ -442,5 +442,55 @@
"given": {
"fingerprint": "src2:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
},
{
"name": "registrations of one repository from a cursor",
"of": "verb:registrations.input",
"given": {
"repository": "novox/mesh-catalog",
"next": "c-120"
}
},
{
"name": "registrations answers a capped page with a source-only registration and the next cursor",
"of": "verb:registrations.answer",
"given": {
"registrations": [
{
"v": 1,
"origin": "novox/hq",
"branches": [
"main"
],
"policy": {
"steps": {
"unit": "required",
"review": "optional",
"approval": "bypass"
}
},
"check": {
"seat": "node-build-go",
"step": "unit"
},
"version": 1,
"by": "operator@workstation",
"warrant": "ask-m2kx9a1b3c4d6a",
"at": "2026-11-22T00:10:00Z"
}
],
"capped": true,
"total": 118,
"next": "c-121"
}
},
{
"name": "seat-list answers the seat list's object by its digest",
"of": "verb:seat-list.answer",
"given": {
"digest": "sha256:eeee",
"size": 412345,
"object": "sha256-eeee"
}
}
]
@@ -253,6 +253,38 @@
},
"class": "read"
},
{
"name": "seat-list",
"class": "read",
"description": "The seat list the mesh holds, as one object in the holder's objects seat-lists, one object per digest (design 47 H2 §814): the manifest validator program takes it by address, so a run by hand reads what the live validate reads. Reads only.",
"input": {
"type": "object",
"properties": {}
},
"answer": {
"type": "object",
"properties": {
"digest": {
"type": "string",
"description": "the seat list's digest"
},
"size": {
"type": "integer",
"minimum": 0,
"description": "the object's size in bytes"
},
"object": {
"type": "string",
"description": "the object's name in seat-lists"
}
},
"required": [
"digest",
"size",
"object"
]
}
},
{
"name": "revision",
"description": "The catalog half of the revision view (ADR 0656 §6): one catalog graph revision with its entries whole, the trunk heads, the seat definitions by digest, and each manifest's verdict and fingerprint; the trunk's newest when no revision and no candidate is named, or a candidate's for its group and heads. Answered by the holder from what it holds, in its own runtime (ADR 0663), in pages of entries. Reads only. A watched branch with no revision yet answers {none-yet: true} alone (design 47 G section 530).",
@@ -312,7 +344,7 @@
},
{
"name": "registrations",
"description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed.",
"description": "Every module's registration, or one with every version and who changed it on whose warrant (design 47 *A module's registration*). Its readers take a first view here, then hear registration-changed. Filtered by module or repository while it reads and paged by the cursor next, at most 768 KB a page (design 47 H2 §806, §811).",
"input": {
"type": "object",
"properties": {
@@ -323,6 +355,14 @@
"history": {
"type": "boolean",
"description": "with every version of the one module"
},
"repository": {
"type": "string",
"description": "only the registrations of this repository, <owner>/<name>, applied while reading (design 47 H2 §806)"
},
"next": {
"type": "string",
"description": "the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779)"
}
}
},
@@ -344,6 +384,18 @@
},
"fill": {
"$ref": "#/defs/Fill"
},
"capped": {
"type": "boolean",
"description": "yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §806)"
},
"total": {
"type": "integer",
"description": "how many registrations the filters hold in all (design 47 H2 §811)"
},
"next": {
"type": "string",
"description": "the cursor of the next page, opaque; empty at the end (design 47 H2 §779)"
}
},
"required": [
@@ -1474,6 +1526,13 @@
"$ref": "#/defs/Registration"
},
"description": "a module's registration"
},
{
"key": "source.<owner>.<name>",
"value": {
"$ref": "#/defs/Registration"
},
"description": "a source-only registration of a repository with no module (design 47 H2 §815)"
}
]
},
@@ -1488,6 +1547,13 @@
"$ref": "#/defs/Registration"
},
"description": "one version of a module's registration"
},
{
"key": "source.<owner>.<name>.<version>",
"value": {
"$ref": "#/defs/Registration"
},
"description": "one version of a source-only registration (design 47 H2 §815)"
}
]
},
@@ -2134,14 +2200,15 @@
},
"Registration": {
"type": "object",
"description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve",
"description": "a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve; or a source-only registration of a repository with no module (design 47 H2 §815): its origin, one watched branch, its policy and its check, naming no module and no path, kept under source.<owner>.<name>",
"properties": {
"v": {
"type": "integer",
"description": "the layout version"
},
"module": {
"type": "string"
"type": "string",
"description": "the module; absent for a source-only registration"
},
"origin": {
"type": "string",
@@ -2149,7 +2216,7 @@
},
"path": {
"type": "string",
"description": "the path of its manifest in the repository"
"description": "the path of its manifest in the repository; absent for a source-only registration"
},
"branches": {
"type": "array",
@@ -2177,12 +2244,14 @@
"at": {
"type": "string",
"format": "date-time"
},
"check": {
"$ref": "#/defs/SourceCheck",
"description": "for a source-only registration, the one step its heads run (design 47 H2 §815)"
}
},
"required": [
"module",
"origin",
"path",
"branches",
"policy"
]
@@ -2525,6 +2594,34 @@
"ref",
"language"
]
},
"SourceCheck": {
"type": "object",
"description": "the check of a source-only registration: a build seat and a step kind, run at the repository's root, never a free command (design 47 H2 §815)",
"properties": {
"seat": {
"type": "string",
"enum": [
"node-build-go",
"node-build-node",
"node-build-image"
],
"description": "the build seat that runs it"
},
"step": {
"type": "string",
"enum": [
"lint",
"unit",
"integration"
],
"description": "the step kind"
}
},
"required": [
"seat",
"step"
]
}
},
"bodies": {
@@ -2623,5 +2720,6 @@
"call"
]
}
}
},
"form": 2
}
@@ -10,6 +10,7 @@ export declare const verbs: {
readonly provides: "provides";
readonly dependents: "dependents";
readonly seatDefinitions: "seat-definitions";
readonly seatList: "seat-list";
readonly revision: "revision";
readonly registrations: "registrations";
readonly register: "register";
@@ -136,12 +137,24 @@ export declare function registrationsByModuleKey(module: string): string;
/** The parts of a key of the form "<module>", or undefined for a key of another form. */
export declare function parseRegistrationsByModuleKey(_key: string): { module: string } | undefined;
/** The key of one value of the state registrations under the form "source.<owner>.<name>". */
export declare function registrationsBySourceOwnerNameKey(owner: string, name: string): string;
/** The parts of a key of the form "source.<owner>.<name>", or undefined for a key of another form. */
export declare function parseRegistrationsBySourceOwnerNameKey(_key: string): { owner: string; name: string } | undefined;
/** The key of one value of the state registration-history under the form "<module>.<version>". */
export declare function registrationHistoryByModuleVersionKey(module: string, version: string): string;
/** The parts of a key of the form "<module>.<version>", or undefined for a key of another form. */
export declare function parseRegistrationHistoryByModuleVersionKey(_key: string): { module: string; version: string } | undefined;
/** The key of one value of the state registration-history under the form "source.<owner>.<name>.<version>". */
export declare function registrationHistoryBySourceOwnerNameVersionKey(owner: string, name: string, version: string): string;
/** The parts of a key of the form "source.<owner>.<name>.<version>", or undefined for a key of another form. */
export declare function parseRegistrationHistoryBySourceOwnerNameVersionKey(_key: string): { owner: string; name: string; version: string } | undefined;
/** The key of one value of the state versions under the form "<module>.<version>". */
export declare function versionsByModuleVersionKey(module: string, version: string): string;
@@ -419,20 +432,23 @@ export interface Policy {
"steps": StepStatuses;
}
/** a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve */
/** a module's registration (ADR 0666 section 2; design 47 *A module's registration*): its git origin, its manifest's path, its watched branches and its policy, every version with who changed it and the warrant of the operator's Approve; or a source-only registration of a repository with no module (design 47 H2 §815): its origin, one watched branch, its policy and its check, naming no module and no path, kept under source.<owner>.<name> */
export interface Registration {
"at"?: string;
/** its watched branches, the first the default a placement runs */
"branches": string[];
/** who asked the change */
"by"?: string;
/** for a source-only registration, the one step its heads run (design 47 H2 §815) */
"check"?: SourceCheck;
/** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */
"form"?: number;
"module": string;
/** the module; absent for a source-only registration */
"module"?: string;
/** its git origin, the repository as <owner>/<name> */
"origin": string;
/** the path of its manifest in the repository */
"path": string;
/** the path of its manifest in the repository; absent for a source-only registration */
"path"?: string;
"policy": Policy;
/** the layout version */
"v"?: number;
@@ -457,6 +473,14 @@ export interface RegistrationAsked {
"words"?: string;
}
/** the check of a source-only registration: a build seat and a step kind, run at the repository's root, never a free command (design 47 H2 §815) */
export interface SourceCheck {
/** the build seat that runs it */
"seat": "node-build-go" | "node-build-node" | "node-build-image";
/** the step kind */
"step": "lint" | "unit" | "integration";
}
/** the status of each pipeline step (design 47 *Pipeline steps and the policy*); a step left out keeps the module's */
export interface StepStatuses {
/** required runs and holds the delivery until it passes; optional runs, a failure is shown and may be accepted; bypass runs nothing and is said as bypassed */
@@ -671,6 +695,22 @@ export interface SeatDefinitionsAnswer {
"seats"?: SeatDefinitionsAnswerSeatsItem[];
}
/** is what seat-list takes. */
export interface SeatListInput {
}
/** is what seat-list answers. */
export interface SeatListAnswer {
/** the seat list's digest */
"digest": string;
/** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */
"form"?: number;
/** the object's name in seat-lists */
"object": string;
/** the object's size in bytes */
"size": number;
}
/** is what revision takes. */
export interface RevisionInput {
/** the last module of the page before; absent: the first page */
@@ -706,16 +746,26 @@ export interface RegistrationsInput {
"history"?: boolean;
/** one module; absent, every registration */
"module"?: string;
/** the cursor the previous page answered, opaque; absent for the first page (design 47 H2 §779) */
"next"?: string;
/** only the registrations of this repository, <owner>/<name>, applied while reading (design 47 H2 §806) */
"repository"?: string;
}
/** is what registrations answers. */
export interface RegistrationsAnswer {
/** yes when the answer stopped at 768 KB; the rest is read from next (design 47 H2 §806) */
"capped"?: boolean;
"fill"?: Fill;
/** is the form of what this value carries, left out while it is 1 (design 47 H2 §780). */
"form"?: number;
/** every version of the one module asked, oldest first */
"history"?: Registration[];
/** the cursor of the next page, opaque; empty at the end (design 47 H2 §779) */
"next"?: string;
"registrations": Registration[];
/** how many registrations the filters hold in all (design 47 H2 §811) */
"total"?: number;
}
/** is what register takes. */
@@ -1120,9 +1170,15 @@ export type CatalogRevisionsByEntryDigestValue = CatalogEntry;
/** is one value of the state registrations under the key <module>. */
export type RegistrationsByModuleValue = Registration;
/** is one value of the state registrations under the key source.<owner>.<name>. */
export type RegistrationsBySourceOwnerNameValue = Registration;
/** is one value of the state registration-history under the key <module>.<version>. */
export type RegistrationHistoryByModuleVersionValue = Registration;
/** is one value of the state registration-history under the key source.<owner>.<name>.<version>. */
export type RegistrationHistoryBySourceOwnerNameVersionValue = Registration;
/** is one value of the state versions under the key <module>.<version>. */
export type VersionsByModuleVersionValue = VersionEntry;
@@ -10,6 +10,7 @@ export const verbs = {
provides: "provides",
dependents: "dependents",
seatDefinitions: "seat-definitions",
seatList: "seat-list",
revision: "revision",
registrations: "registrations",
register: "register",
@@ -243,6 +244,27 @@ export function parseRegistrationsByModuleKey(_key) {
return { module };
}
/** The key of one value of the state registrations under the form "source.<owner>.<name>". */
export function registrationsBySourceOwnerNameKey(owner, name) {
return "source." + owner + "." + name;
}
/** The parts of a key of the form "source.<owner>.<name>", or undefined for a key of another form. */
export function parseRegistrationsBySourceOwnerNameKey(_key) {
let _rest = _key;
if (!_rest.startsWith("source.")) return undefined;
_rest = _rest.slice(7);
const _at1 = _rest.indexOf(".");
if (_at1 <= 0) return undefined;
const owner = _rest.slice(0, _at1);
_rest = _rest.slice(_at1 + 1);
if (_rest === "") return undefined;
const name = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { owner, name };
}
/** The key of one value of the state registration-history under the form "<module>.<version>". */
export function registrationHistoryByModuleVersionKey(module, version) {
return module + "." + version;
@@ -262,6 +284,31 @@ export function parseRegistrationHistoryByModuleVersionKey(_key) {
return { module, version };
}
/** The key of one value of the state registration-history under the form "source.<owner>.<name>.<version>". */
export function registrationHistoryBySourceOwnerNameVersionKey(owner, name, version) {
return "source." + owner + "." + name + "." + version;
}
/** The parts of a key of the form "source.<owner>.<name>.<version>", or undefined for a key of another form. */
export function parseRegistrationHistoryBySourceOwnerNameVersionKey(_key) {
let _rest = _key;
if (!_rest.startsWith("source.")) return undefined;
_rest = _rest.slice(7);
const _at1 = _rest.indexOf(".");
if (_at1 <= 0) return undefined;
const owner = _rest.slice(0, _at1);
_rest = _rest.slice(_at1 + 1);
const _at3 = _rest.indexOf(".");
if (_at3 <= 0) return undefined;
const name = _rest.slice(0, _at3);
_rest = _rest.slice(_at3 + 1);
if (_rest === "") return undefined;
const version = _rest;
_rest = "";
if (_rest !== "") return undefined;
return { owner, name, version };
}
/** The key of one value of the state versions under the form "<module>.<version>". */
export function versionsByModuleVersionKey(module, version) {
return module + "." + version;