Documentation
¶
Overview ¶
Package console is the read-through local admin console of `docs/specs/local-admin-console-v0.md` (decision 0081). It renders what the owning tools report and performs a change only by invoking the owning tool's own verb; it holds no database, opens no outbound connection, and carries no authority of its own.
Index ¶
- Constants
- func ChangeIDs(listing *Listing) []string
- func GapCount(edges []ChainEdge) int
- func IssuedNow() string
- func NewRequestID() string
- func RequireToplevel(ctx context.Context, root string, timeout time.Duration) error
- type Axes
- type Axis
- type AxisPair
- type Blob
- type Board
- type Capabilities
- type Card
- type Chain
- type ChainArtifact
- type ChainDetail
- type ChainEdge
- type ChainHunk
- type ChainRequirement
- type ChainSpan
- type Clause
- type CodeBacklinks
- type CodeLink
- type Column
- type Control
- type Dashboard
- type Detail
- type Dogfood
- type DogfoodPacket
- type DogfoodStep
- type Entry
- type Envelope
- type Evidence
- type ExitError
- type Issue
- type KeyValue
- type Listing
- type Metric
- type MetricFamily
- type MutationRequest
- type MutationResult
- type Options
- type ProcessError
- type Refusal
- type Requirement
- type RequirementLink
- type RequirementLinks
- type Revision
- type Roadmap
- type RoadmapGroup
- type RoadmapRow
- type Server
- type SnapshotSource
- type Source
- type SpecEntry
- type SpecLookup
- type Taskman
- func (t *Taskman) Mutate(ctx context.Context, request MutationRequest) *MutationResult
- func (t *Taskman) ReadBoard(ctx context.Context, caps *Capabilities) *Board
- func (t *Taskman) ReadCapabilities(ctx context.Context) *Capabilities
- func (t *Taskman) ReadDetail(ctx context.Context, id string) *Detail
- func (t *Taskman) ReadRoadmap(ctx context.Context, page int) *Roadmap
- func (t *Taskman) Run(ctx context.Context, args ...string) (*Envelope, Source)
- type Unknown
- type Worktree
- func (w Worktree) CodeBacklinks(ctx context.Context, lookup SpecLookup, commit, path string) *CodeBacklinks
- func (w Worktree) Head(ctx context.Context) Revision
- func (w Worktree) HunkDetail(ctx context.Context, chain *Chain, hunkID string) *ChainDetail
- func (w Worktree) List(ctx context.Context, revision, dir string) *Listing
- func (w Worktree) Read(ctx context.Context, revision, path string) *Blob
- func (w Worktree) ReadChain(ctx context.Context, commit, change string) *Chain
- func (w Worktree) RequirementLinks(ctx context.Context, lookup SpecLookup, commit, id string) *RequirementLinks
Constants ¶
const ( GapMissing = "missing" GapStale = "stale" GapAmbiguous = "ambiguous" GapUnverified = "unverified" GapUnsupported = "unsupported" )
The gap classes of LAC-V0-035. A gap is an edge the artifacts do not establish; it is rendered as itself, never replaced by an inferred link.
const ( SnapshotProfile = "corvint-dashboard-snapshot/0" ErrorProfile = "corvint-dashboard-error/0" )
SnapshotProfile is the schema the console consumes from `corvint-dashboard-snapshot`, and ErrorProfile is what that tool answers with when it refuses.
const DogfoodProfile = "corvint-dogfood-change/0"
DogfoodProfile is the report profile `make dogfood-change` writes.
const EnvelopeProfile = "taskman-command-result/0"
EnvelopeProfile is the only result profile this console consumes.
const Unstated = "NOT_STATED"
Unstated is what the console renders for an axis its source did not state. It is deliberately not one of the closed values: LAC-V0-007 forbids the console from deriving or defaulting an axis, and every closed value would be a claim the source never made. `taskman-command-result/0` states none of the six, so most values a board renders carry this.
Variables ¶
This section is empty.
Functions ¶
func ChangeIDs ¶ added in v0.8.0
ChangeIDs names the sealed changes a listing of .corvint/changes holds, newest-named last as Git lists them.
func NewRequestID ¶
func NewRequestID() string
NewRequestID mints an idempotency key for one form. It is stable for that rendered form, so a double submit is a replay rather than a second commit.
Types ¶
type Axes ¶
type Axes struct {
Validity string
EpistemicClass string
AuthorityClass string
Completeness string
Currency string
DeliveryStage string
}
Axes is one value's six axes as its source stated them. An axis the source did not state stays Unstated; nothing in this package fills one in.
func UnstatedAxes ¶
func UnstatedAxes() Axes
UnstatedAxes is the starting point for a source that states no axis at all, which is every `taskman-command-result/0` envelope today.
func Weakest ¶
Weakest combines the axes of several contributing sources into the axes of a value derived from all of them (LAC-V0-010). Every axis takes the weakest contribution: for an ordered axis that is the last value in its closed list, and an unstated contribution makes the result unstated, because a value can be no better supported than the source that says least about it.
type Axis ¶
type Axis string
Axis is one of the six independent evidence axes of `docs/specs/local-observability-dashboard-v0.md`. Their closed values are reproduced here so the console can reject a value outside them rather than pass an unrecognized string through as if it were an axis.
type Blob ¶
type Blob struct {
Path string
ObjectID string
Revision string
Text string
Truncated bool
Dirty bool
DirtyNote string
Source Source
Err string
}
Blob is one file's committed bytes and the object id they came from.
type Board ¶
type Board struct {
Columns []Column
Source Source
Envelope *Envelope
Total int
Statuses []string
Err string
Untrusted []string
}
Board is the whole board plus the attribution and refusal of the read that produced it.
type Capabilities ¶
type Capabilities struct {
Implemented []string
Omitted []string
Statuses []string
Eligibility []string
Note string
Source Source
Err string
}
Capabilities is what the tool says it can do, read from `atm help`: the verbs it implements, the verbs it does not, and the enumerations a board must use instead of carrying its own (LAC-V0-013, LAC-V0-016).
func (*Capabilities) Controls ¶
func (c *Capabilities) Controls() []Control
Controls answers, for one ticket, which mutations this tool can perform.
func (*Capabilities) Implements ¶
func (c *Capabilities) Implements(verb string) bool
Implements reports whether the tool named this verb as implemented.
func (*Capabilities) Reason ¶
func (c *Capabilities) Reason(verb string) string
Reason is the tool's own explanation for a verb it did not implement. An unimplemented verb renders as a disabled control carrying this string; the console never invents one and never hides the control (LAC-V0-013).
type Card ¶
type Card struct {
TicketID string
Title string
Status string
Kind string
Priority string
Owner string
Milestone string
Eligibility string
NextAction string
Revision string
Blockers int
Unknowns []Unknown
Axes Axes
}
Card is one ticket as the board shows it. Every field is copied from the tool's item; nothing is computed here.
type Chain ¶ added in v0.8.0
type Chain struct {
Change string
Commit string
Base string
Profile string
SealedPath string
Sealed *Blob
Binding []ChainEdge
Artifacts []ChainArtifact
Verification []ChainEdge
Requirements []ChainRequirement
Hunks []ChainHunk
Detail *ChainDetail
Err string
}
Chain is the rendered chain for one sealed change.
type ChainArtifact ¶ added in v0.8.0
ChainArtifact is one untracked local artifact the pane read, and whether it is bound to this change.
type ChainDetail ¶ added in v0.8.0
type ChainDetail struct {
Hunk ChainHunk
Lines *Blob
Range string
Text string
Spans []ChainSpan
Err string
Requirements []ChainRequirement
Unmapped []ChainRequirement
Verification []ChainEdge
}
ChainDetail is one hunk's lines at the revision its map pins, and the bytes of every span it cites.
type ChainEdge ¶ added in v0.8.0
type ChainEdge struct {
Gap string
Reason string
Target string
Artifact string
Field string
Pin string
Detail string
Anchor string
Axes Axes
}
ChainEdge is one edge of the chain. Artifact and Field name what justifies it (LAC-V0-034); a non-empty Gap means the artifacts do not establish it and Reason says why (LAC-V0-035).
type ChainHunk ¶ added in v0.8.0
type ChainHunk struct {
Field string
ID string
Path string
Disposition string
Reason string
Old wireRange
New wireRange
Evidence []ChainEdge
Requirements []ChainEdge
Observations []ChainEdge
}
ChainHunk is one hunk of the sealed map and its outgoing edges.
type ChainRequirement ¶ added in v0.8.0
type ChainRequirement struct {
ID string
Anchor string
Disposition string
Reason string
Clause []ChainEdge
Hunks []ChainEdge
Claims []ChainEdge
Verification []ChainEdge
}
ChainRequirement is one obligation of a bound OCM map: the requirement at its pinned intent scope, the hunks and test claims the map lists for it, and the recorded verification result of the change revision.
type ChainSpan ¶ added in v0.8.0
ChainSpan is one cited span's bytes, read at the object id it pins.
type Clause ¶
type Clause struct {
Requirement Requirement
Spec *SpecEntry
Text string
Source Source
Err string
}
Clause is the answer for one requirement id.
type CodeBacklinks ¶
type CodeBacklinks struct {
Commit string
Requirements []RequirementLink
Gap string
Truncated bool
}
CodeBacklinks is the code page's list of citing requirements at one commit.
type CodeLink ¶
CodeLink is one path a requirement's Traceability row cites. ObjectID is the blob the path names at the pinned commit. Gap says why no link is rendered; a gap is never drawn as a link (LAC-V0-030).
type Column ¶
Column is one board column. Unmapped is the column for a status the tool did not enumerate; a card there is visible rather than dropped (LAC-V0-016).
type Control ¶
type Control struct {
Verb string
Label string
Enabled bool
Reason string
PayloadTemplate string
NeedsPayload bool
}
Control is one mutation the board offers for a ticket. Enabled is decided by the owning tool's own capability report, never by the console; a disabled control still renders, carrying the tool's reason (LAC-V0-013).
type Dashboard ¶
Dashboard invokes `corvint-dashboard-snapshot` in one repository. The console compiles no snapshot of its own: it runs the owning tool and renders what that tool wrote, exactly as the board runs `atm` (LAC-V0-004, LAC-V0-012).
type Detail ¶
type Detail struct {
TicketID string
Card Card
Record map[string]any
Blockers *Envelope
Show Source
BlockerSource Source
Envelope *Envelope
Err string
Untrusted []string
Requirements []string
}
Detail is one ticket as the detail pane shows it: the tool's own view, its blocker closure, and the attribution of both reads.
type Dogfood ¶
type Dogfood struct {
Profile string `json:"profile"`
Base string `json:"base"`
Target string `json:"target"`
Complete bool `json:"complete"`
Steps []DogfoodStep `json:"steps"`
OCMStatus any `json:"ocmStatus"`
Outcome *string `json:"localOutcomeEvidenceSha256"`
Anchor struct {
State string `json:"state"`
MergeBase *string `json:"mergeBase"`
} `json:"anchor"`
Check any `json:"dogfoodCheck"`
// PacketCoverage is absent from reports written before DCW-V0-016.
PacketCoverage []DogfoodPacket `json:"packetCoverage"`
// Path, ModifiedAt and Source describe where the report was read from.
// Absent is what distinguishes "no loop has run here" from "the loop ran
// and produced nothing", which LAC-V0-008 forbids collapsing together.
Path string `json:"-"`
ModifiedAt time.Time `json:"-"`
Absent bool `json:"-"`
Source Source `json:"-"`
Err string `json:"-"`
}
Dogfood is the rendered dogfood pane.
func ReadDogfood ¶
ReadDogfood reads the last dogfood report of one repository. The report is untracked local derived state, not committed evidence: it carries no content digest and no owning verifier, so the console states none of the six axes for it rather than supplying one (LAC-V0-007).
func (*Dogfood) NotProduced ¶
NotProduced counts the steps that did not produce.
type DogfoodPacket ¶ added in v0.8.0
type DogfoodPacket struct {
Step string `json:"step"`
Status string `json:"status"`
Reason string `json:"reason"`
PacketBytes int `json:"packet_bytes"`
BudgetBytes *int `json:"budget_bytes"`
WithinBudget bool `json:"within_budget"`
IncludedResults int `json:"included_results"`
OmittedResults int `json:"omitted_results"`
}
DogfoodPacket is one packet-compiling step's coverage entry, under the packet's own field names (DCW-V0-016). A NOT_PRODUCED entry carries a reason and no numbers.
func (DogfoodPacket) Produced ¶ added in v0.8.0
func (p DogfoodPacket) Produced() bool
Produced reports whether this step compiled a packet.
type DogfoodStep ¶
type DogfoodStep struct {
Name string `json:"name"`
Status string `json:"status"`
Reason string `json:"reason"`
}
DogfoodStep is one step of the loop and the reason it did or did not produce. A NOT_PRODUCED reason is the point of the pane: the loop's own account of what it could not do is what an operator needs to see, so it is never summarised away (docs/DOGFOOD.md).
func (DogfoodStep) Produced ¶
func (s DogfoodStep) Produced() bool
Produced reports whether this step produced its artifact.
type Envelope ¶
type Envelope struct {
Profile string `json:"profile"`
Command []string `json:"command"`
Outcome string `json:"outcome"`
Codes []string `json:"codes"`
Warnings []string `json:"warnings"`
Items []map[string]any `json:"items"`
Untrusted []string `json:"untrusted"`
Page map[string]any `json:"page"`
}
Envelope is one `taskman-command-result/0` reply, kept as the tool wrote it. Items stay untyped: the console renders the fields it understands and must not silently drop the ones it does not.
type Evidence ¶
type Evidence struct {
Schema string
GeneratedAt string
Digest string
ScanState string
Worktree string
HeadRev string
TreeRev string
DirtyCount string
Privacy []KeyValue
Families []MetricFamily
Sources []SnapshotSource
Issues []Issue
Total int
Source Source
Err string
Refused bool
Code string
}
Evidence is the Corvint evidence pane: the compiled snapshot, its families, its sources and its issues. It is the first console surface whose source states all six axes for every value, so nothing here is Unstated by default (LAC-V0-007).
type ExitError ¶
type ExitError struct{ Status int }
ExitError is an observed, ordinary non-zero exit of a fully reaped child. It is not a boundary failure: a tool may exit non-zero to carry its own REFUSED envelope, and only the caller can decide whether the envelope it read is consistent with that status.
type KeyValue ¶
type KeyValue struct{ Key, Value string }
KeyValue is one declared field rendered as the tool stated it.
type Listing ¶
type Listing struct {
Dir string
Revision string
Entries []Entry
Truncated bool
Source Source
Err string
}
Listing is one directory of a tree at one revision.
type Metric ¶
type Metric struct {
Name string
Unit string
Value string
Scope string
Dimensions string
SourceIDs []string
Exclusions []string
Axes Axes
Unmeasured bool
}
Metric is one rendered metric: the value the snapshot measured, the axes the snapshot stated for it, and every source that contributed to it.
type MetricFamily ¶
MetricFamily is one metric family and its rows.
type MutationRequest ¶
type MutationRequest struct {
Verb string
TicketID string
Expected string
Payload string
RequestID string
IssuedAt string
}
MutationRequest is one delegated change. RequestID and IssuedAt are minted when the form is rendered and travel with it, so resubmitting the same form replays the original request instead of committing a second one.
type MutationResult ¶
type MutationResult struct {
Request MutationRequest
Envelope *Envelope
Source Source
Conflict bool
Err string
}
MutationResult is what the owning tool answered.
type Options ¶
type Options struct {
Addr string // loopback host:port
Repo string // the repository whose ticket store is administered
Binary string // the `corvint-tasks` executable
// Specs is the repository holding `docs/specs/REQUIREMENTS.tsv` and
// `docs/specs/INDEX.json`, and the tree the code pane reads. It is
// separate from Repo because a ticket store and the spec corpus that
// governs it need not be the same repository (decision 0081).
Specs string
// Snapshot is the `corvint-dashboard-snapshot` executable. The evidence pane
// compiles no snapshot of its own: it runs this tool and renders what the
// tool wrote, the same delegation the board makes to `corvint-tasks` (LAC-V0-004).
Snapshot string
Timeout time.Duration
}
Options configure one console process.
type ProcessError ¶
ProcessError takes precedence over any captured tool envelope.
func (*ProcessError) Error ¶
func (e *ProcessError) Error() string
func (*ProcessError) Unwrap ¶
func (e *ProcessError) Unwrap() error
type Refusal ¶
type Refusal struct {
Heading string
Outcome string
Codes []string
Warnings []string
Err string
Source Source
}
Refusal is what refusalTemplate renders.
type Requirement ¶
Requirement is one row of `docs/specs/REQUIREMENTS.tsv`: a requirement id, the spec file that defines it, and the line it is defined on.
type RequirementLink ¶
RequirementLink is one requirement whose Traceability row cites a path.
type RequirementLinks ¶
RequirementLinks is the requirement page: the clause, and the code its owning spec's Traceability table cites, resolved at one commit.
type Revision ¶
Revision is the commit the console is reading at, plus whether the worktree differs from it.
type Roadmap ¶
type Roadmap struct {
Groups []RoadmapGroup
Envelope *Envelope
Source Source
Total int
Untrusted []string
Err string
Page int
PageSize int
PrevPage int
NextPage int
HasPrev bool
HasNext bool
TotalKnown bool
TotalCount int
}
Roadmap is the whole roadmap page: the grouped tickets, the read's own attribution, and the pagination `atm roadmap` reported.
type RoadmapGroup ¶
type RoadmapGroup struct {
Milestone string
Unmapped bool
Rows []RoadmapRow
}
RoadmapGroup is one milestone's tickets, in the order `atm roadmap` returned them. A ticket the tool assigned no milestone still renders, in its own group, rather than being dropped.
type RoadmapRow ¶
type RoadmapRow struct {
TicketID string
Title string
Milestone string
Order string
Owner string
Priority string
Status string
Kind string
Eligibility string
NextAction string
RequiredGates []string
GateResults string
Blockers *Envelope
BlockerSource Source
}
RoadmapRow is one ticket as the roadmap shows it: the fields `atm roadmap` reports, plus the blocker closure for a ticket the tool reports BLOCKED. Gate evidence (RequiredGates, GateResults) is rendered as the tool stated it, never upgraded to a pass/fail the tool did not report (IPR-02).
type Server ¶
type Server struct {
// contains filtered or unexported fields
}
Server keeps only its listener binding and per-start form secret. Domain values are read from their owning tools at request time (LAC-V0-004).
func New ¶
New builds a console bound to one repository. It refuses a non-loopback address: the console has no authentication because it is never reachable from another host, and those two facts must not come apart (LAC-V0-002).
type SnapshotSource ¶
type SnapshotSource struct {
ID string
Label string
AdapterID string
Profile string
VerifierID string
Digest string
Bytes string
Exclusions []string
Axes Axes
}
SnapshotSource is one contributing source of the snapshot, with the axes the snapshot stated for it.
type Source ¶
type Source struct {
Argv []string
Tool string
Revision string
Worktree string
ObservedAt time.Time
Axes Axes
Err string
Outcome string
Codes []string
Warnings []string
UntrustedIn []string
}
Source is the attribution of one rendered value: the exact invocation, the tool that answered, and the repository revision it answered about (LAC-V0-006). It travels with the value so the attribution is reachable without a second query.
type SpecEntry ¶
type SpecEntry struct {
Path string `json:"path"`
Title string `json:"title"`
ReqPrefix string `json:"reqPrefix"`
Intent string `json:"intent"`
Delivery string `json:"delivery"`
Claim string `json:"claim"`
}
SpecEntry is one spec's row in `docs/specs/INDEX.json`. Intent and delivery are the spec's own declared statuses; the console renders them beside the clause and never restates them as its own judgement (LAC-V0-018).
type SpecLookup ¶
type SpecLookup struct {
Root string
}
SpecLookup resolves a requirement id to its clause and its owning spec's declared status. It reads the two generated indexes at request time and keeps nothing (LAC-V0-004).
func (SpecLookup) Resolve ¶
func (l SpecLookup) Resolve(id string) *Clause
Resolve finds one requirement id. A missing index or a missing id is reported as such, never as an empty clause.
type Taskman ¶
type Taskman struct {
Binary string
Repo string
Version string
Revision string
Timeout time.Duration
}
Taskman invokes `atm` in one repository. It is the only way this console reaches the ticket store: nothing here imports corvint-taskman, reads its state directory, or writes anything it owns (decision 0081).
func (*Taskman) Mutate ¶
func (t *Taskman) Mutate(ctx context.Context, request MutationRequest) *MutationResult
Mutate performs one change by invoking the owning tool's own verb. The console writes nothing itself (LAC-V0-012), sends the expectedRevision the operator was shown, and never re-reads and retries on their behalf: a conflict is returned for the operator to re-read (LAC-V0-014).
func (*Taskman) ReadBoard ¶
func (t *Taskman) ReadBoard(ctx context.Context, caps *Capabilities) *Board
ReadBoard lists the queue and groups it into the columns the tool enumerates. A refusal is carried through as a refusal: the caller renders it, and the board stays empty of invented rows.
func (*Taskman) ReadCapabilities ¶
func (t *Taskman) ReadCapabilities(ctx context.Context) *Capabilities
ReadCapabilities asks the tool what it can do. Every board column and every control is decided from this, at request time.
func (*Taskman) ReadDetail ¶
ReadDetail reads one ticket and its blockers. Both reads are attributed separately, because a value derived from both can be no stronger than the weaker of them (LAC-V0-010).
func (*Taskman) ReadRoadmap ¶
ReadRoadmap reads one page of `atm roadmap`, grouped by the milestone the tool assigned. A ticket the tool reports BLOCKED gets its own blocker read; a ticket that is not blocked names no blocker read, so one roadmap page costs a handful of process invocations, not one per row.
type Unknown ¶
Unknown is one fact the tool reported it could not observe. It is rendered, never dropped: an unobservable fact is the difference between a measured zero and no measurement at all (LAC-V0-008).
type Worktree ¶
Worktree reads committed content from one repository. Every read names the immutable Git object it came from; the console never presents working-tree bytes as committed content (LAC-V0-019).
func (Worktree) CodeBacklinks ¶
func (w Worktree) CodeBacklinks(ctx context.Context, lookup SpecLookup, commit, path string) *CodeBacklinks
CodeBacklinks finds the requirements whose Traceability rows cite path at commit. Specs are located with one `git grep` over the commit's tree and then parsed; a mention outside a Traceability Implementation cell is not a citation. An id no longer in REQUIREMENTS.tsv is a gap, never a link to a page that could not resolve it.
func (Worktree) Head ¶
Head resolves the commit and reports whether the worktree is clean. A dirty worktree is labelled everywhere it matters rather than quietly ignored.
func (Worktree) HunkDetail ¶ added in v0.8.0
HunkDetail reads one hunk's lines at the revision its map pins and the bytes of every evidence span it cites, each at its own object id.
func (Worktree) List ¶
List reads one directory of the tree at revision. It lists the tree, not the worktree: an untracked file is not evidence at a revision, and a listing that mixed the two would name object ids for some entries and not others (LAC-V0-019).
func (Worktree) Read ¶
Read returns one path's content at the given revision, read through the object database. The object id is resolved first and the bytes are read from that id, so what is rendered is exactly what the id names.
func (Worktree) ReadChain ¶ added in v0.8.0
ReadChain compiles the chain for one sealed change, read at commit. change must already be a sealed map the listing at commit named.
func (Worktree) RequirementLinks ¶
func (w Worktree) RequirementLinks(ctx context.Context, lookup SpecLookup, commit, id string) *RequirementLinks
RequirementLinks resolves one requirement's cited code at commit. The owning spec is read at that commit's object, so the links are what that commit's Traceability table states, not what the worktree says now.