Files
mesh-catalog/modules/mesh-issues/cmd/mesh-issues/issue.go
T
jochen 2493e3e048
mesh/merge-gate pass: builds new: modules/mesh-issues, sent nowhere; no bus step; every machine composes with the change as it did without (4 of 4 compose)
mesh/repo-check pass: its merge-check.sh passed, each part in its toolchain: merge-check.sh (go), merge-check-typescript.sh (typescript)
mesh/delivery superseded: a newer head of the same pull request
Add mesh-issues, the issue tracker, so an issue's number comes from one counter no two openers share (hq ADR 0275, to-be 53 slice 1)
The seat issue-tracker, held once for the mesh: open, get, list, move, note
and link. The counter is advanced by the SDK's compare-and-set Increment
(go/v0.1.12) and started once at the setting first-number (365, after hq's
highest), never below an issue kept. The cycle's issue rules are refused at
the write; every change is an event. The runtime does not yet say who called,
so every change is recorded as by "unproven" and no argument can name a caller.
2026-10-10 12:51:15 +02:00

153 lines
5.5 KiB
Go

package main
import (
"encoding/json"
"errors"
"fmt"
"strconv"
"time"
stdio "git.novox.be/novox/mesh-sdk/go"
)
// What the tracker keeps (novox/hq to-be 53 §3, §4): one issue per key of the state `issues`, keyed by
// its number, and one counter per sequence in the state `counters`. Both are declared in the manifest and
// made by the controller; this module never makes a bucket (ADR 0201).
const (
IssuesState = "issues"
CountersState = "counters"
// IssueCounter is the key of the issue numbers' counter in `counters`.
IssueCounter = "issue"
)
// The five statuses of an issue, as the development cycle names them (hq 00-META/checks/cycle.py).
const (
StatusOpen = "open"
StatusDiagnosing = "diagnosing"
StatusLocated = "located"
StatusResolved = "resolved"
StatusWontfix = "wontfix"
)
// Statuses is every status an issue may have, in the order the cycle walks them.
var Statuses = []string{StatusOpen, StatusDiagnosing, StatusLocated, StatusResolved, StatusWontfix}
// Unproven is who acted, as recorded, while the runtime does not tell a module who called it: a tool call
// reaches a bundle as a name and arguments only (mesh-sdk Tool.Run), and the tool runner is not told who
// called it either (hq issue 340). The caller is never taken from an argument, so this is recorded rather
// than a name anybody could type (novox/hq ADR 0275 §5).
const Unproven = "unproven"
// Issue is one issue as the tracker keeps it.
type Issue struct {
Number uint64 `json:"number"`
Title string `json:"title"`
// Status is one of the five; empty for an issue whose folder in hq keeps its status (to-be 53 §3).
Status string `json:"status,omitempty"`
Report string `json:"report"`
Opened time.Time `json:"opened"`
OpenedBy string `json:"opened-by"`
Closed *time.Time `json:"closed,omitempty"`
// LocatedIn names registered owners, each optionally followed by where in it.
LocatedIn []string `json:"located-in,omitempty"`
FixedBy []string `json:"fixed-by,omitempty"`
AmendedDesign []string `json:"amended-design,omitempty"`
Replay string `json:"replay,omitempty"`
ReplayNone string `json:"replay-none,omitempty"`
// Reason is why it will not be fixed: what a wontfix needs.
Reason string `json:"reason,omitempty"`
// Record is the issue's folder in hq, when it has one.
Record string `json:"record,omitempty"`
Notes []Note `json:"notes,omitempty"`
Links []Link `json:"links,omitempty"`
// Opening is the id of the call that opened it, so a write whose answer was lost is known as its own.
Opening string `json:"opening"`
}
// Note is one note on an issue: appended, never edited.
type Note struct {
By string `json:"by"`
At time.Time `json:"at"`
Text string `json:"text"`
}
// Link is one typed link from an issue.
type Link struct {
Kind string `json:"kind"`
Target string `json:"target"`
By string `json:"by"`
At time.Time `json:"at"`
}
// MostIssueBytes is the most one issue may be as kept: a value the bus holds (to-be 53 §4). The largest
// issue folder in hq was 25 KiB on 2026-10-10.
const MostIssueBytes = 256 << 10
// Entry is one key's value and the revision it was read at.
type Entry struct {
Value json.RawMessage
Revision uint64
}
// Store is the module's state as the runtime offers it (novox/hq ADR 0201, ADR 0259): a write that must win
// once is a compare-and-set, refused with stdio.ErrChanged when another writer was first.
type Store interface {
Get(state, key string) (*Entry, error)
Create(state, key string, value any) (uint64, error)
Update(state, key string, value any, revision uint64) (uint64, error)
Keys(state string) ([]string, error)
Increment(state, key string, attempts int) (uint64, error)
}
// runtimeStore is Store through the runtime that launched this bundle.
type runtimeStore struct{}
func (runtimeStore) Get(state, key string) (*Entry, error) {
e, err := stdio.State(state).Get(key)
if err != nil || e == nil {
return nil, err
}
return &Entry{Value: e.Value, Revision: e.Revision}, nil
}
func (runtimeStore) Create(state, key string, value any) (uint64, error) {
return stdio.State(state).Create(key, value)
}
func (runtimeStore) Update(state, key string, value any, revision uint64) (uint64, error) {
return stdio.State(state).Update(key, value, revision)
}
func (runtimeStore) Keys(state string) ([]string, error) { return stdio.State(state).Keys() }
func (runtimeStore) Increment(state, key string, attempts int) (uint64, error) {
return stdio.State(state).Increment(key, attempts)
}
// keyOf is an issue's key: its number in decimal.
func keyOf(n uint64) string { return strconv.FormatUint(n, 10) }
// numberOfKey is the number a key of `issues` holds, or false for a key that is not one.
func numberOfKey(k string) (uint64, bool) {
n, err := strconv.ParseUint(k, 10, 64)
if err != nil || n == 0 || keyOf(n) != k {
return 0, false
}
return n, true
}
// ErrNoIssue is a number the tracker holds no issue under.
var ErrNoIssue = errors.New("no such issue")
// read is one issue and the revision it was read at.
func read(s Store, n uint64) (*Issue, uint64, error) {
e, err := s.Get(IssuesState, keyOf(n))
if err != nil {
return nil, 0, fmt.Errorf("issue %d could not be read: %v", n, err)
}
if e == nil {
return nil, 0, fmt.Errorf("there is no issue %d: %w", n, ErrNoIssue)
}
var is Issue
if err := json.Unmarshal(e.Value, &is); err != nil {
return nil, 0, fmt.Errorf("issue %d is kept in a form this module cannot read: %v", n, err)
}
return &is, e.Revision, nil
}