Documentation
¶
Overview ¶
Package cardhdr is the card header's vocabulary: the kinds and routes a card's KIND and ROUTE lines may carry, and the one reader of a `KEY: value` header line. It is a leaf (standard library only) so every reader of a card header reads it the same way without importing another.
Index ¶
Constants ¶
const ( RouteFrontier = "frontier" RouteHeavy = "heavy" RoutePro = "pro" RouteFlash = "flash" )
The routes a card may carry: the four model classes. frontier is the most recent Astra or Fable model only; heavy is the headless subscription harnesses of one machine (claude, codex, grok; a class, never a model name: the owner, 2026-10-04); pro and flash are the rungs the bench harness picks its model from (nova-sprint routes --tier <route>, first allowed route). A card with no ROUTE line is flash. Every worker (a friend or a bench) advertises the types it runs on its desired record's tiers field (nova-sprint capacity bench --tiers ..., nova-config for a friend); the dealer matches a card's route against that, and a worker advertising nothing is flash,pro. Nothing in code names a worker.
const ( ClassModel = "model" ClassScript = "script" )
The classes a card's CLASS line may carry (docs/SPEC-SPRINT.md, the script read): a model card is worked, and read, by models; a script card is mechanical, made by a program its SCRIPT line names, so its read may be asked of a script reader before any model.
const ( EndNothing = "nothing to do" EndNoCommit = "no commit" )
EndNothing and EndNoCommit are how a member's failed finish begins when its child found nothing to do (verdict nothing) or committed nothing: no new work. The sprint returns such a rework to review at the head an earlier attempt pushed when a reader passed that head (docs/SPEC-SPRINT.md section 6), else it is failed work for the coordinator.
const EndLaunch = "launch refused"
EndLaunch is how a member's failed finish begins when it could not launch a taken card (no model, budget or deadline from its packet or its override): the member's failure, never the card's, like a staging refusal.
const EndNoResult = "no result"
EndNoResult is how a member's failed finish begins when its child ended, by itself and within its budget and deadline, having written no result at all (no RESULT.md shape): no work came back, so the sprint deals the card again on another route, within the redeal bound, as it does a take the provider failed, and judges nothing. Work that came back and is wrong is still the coordinator's to judge.
const EndPreExisting = "pre-existing"
EndPreExisting is how a member's failed finish begins when its child's gate was red only on failures the gate decision classed pre-existing (docs/SPEC-SPRINT.md section 5, the gate verdict): `pre-existing: <test>, ...`. The test fails without the card's change, at the base or on the machine, so the failure is the base's or the member's and never the card's: it has no failure class and is never the second identical failure (sprint.FailureClass).
const EndProvider = "provider failure"
EndProvider is how a member's failed finish begins when the provider failed the run: the member writes it (member.Judge) and the sprint's route stats count it.
const EndStaging = "staging refused"
EndStaging is how a member's failed finish begins when its machine refused the launch at staging, before any child ran (no bench mirror, the pushed head missing): the member's failure, never the card's; the sprint deals the card to another member (tla/CardContract.tla, StageRefused).
const KeyPaths = "PATHS"
KeyPaths is the card header's PATHS key, the one spelling of it: a card's PATHS line names the files and packages the work spans, and pkg/cardtree and pkg/decide read that line through this key, so a reader of a card header reads it the same way everywhere.
const RemainderKey = "remainder="
RemainderKey begins the report of a tree card that finished ok at the step before its failed step: `remainder=<id>-r<n> step <n> <verdict>: <why>`, the card the coordinator adds for the rest (docs/SPEC-SPRINT.md, a card is a tree of steps). The sprint carries such a report on its "work came back ok" note.
const RouteList = "frontier, heavy, pro or flash"
RouteList is the four classes as a refusal names them.
const TestRemedy = "" /* 147-byte string literal not displayed */
TestRemedy is what a card whose DONE-WHEN cannot be turned into a test is told, on every refusal.
Variables ¶
var KeyRE = regexp.MustCompile(`^([A-Za-z][A-Za-z0-9-]*):\s*(.*)$`)
KeyRE is the header line's shape: a key word at column 0, then a colon.
var Routes = []string{RouteFrontier, RouteHeavy, RoutePro, RouteFlash}
Routes is the four model classes in rank order, the set every ROUTE parse and list draws on.
Functions ¶
func IsModelID ¶
IsModelID says id is `<provider>/<model>`: a provider word with no slash, then a model name that may hold slashes of its own, neither empty, no blank or tab.
func KeyValue ¶
KeyValue reads one `KEY: value` line by the header's own rule, so the issue parser that fills a task record (taskcard.ParseIssue) and card push read a line the same way.
func ParseBase ¶
ParseBase reads a BASE value: `<ref>` (a branch, a tag or a sha) or `<ref>@<sha40>`, the form a card tree pins a base in (cardtree: `BASE: <ref>@<land>`). sha is the pin, "" when the value names none; ok is false for an empty ref or anything after the @ that is no full sha, so a pin is never read as its ref.
Types ¶
type Class ¶
type Class struct {
Name string // ClassModel or ClassScript
Script string // the program's command line, "" for a model card
Deadline time.Duration // the card's deadline, 0 when its DEADLINE line names none
}
Class is what a card's brief says of its class: `CLASS: model|script`, and for a script card `SCRIPT: <command>` (run from the repository root at the start commit) and the brief's `DEADLINE:` line, which bounds that run. A brief with no CLASS line is a model card. ReadClass is the one parser of these lines; the member's script reader reads the brief through it only.
func ReadClass ¶
ReadClass reads a brief's class lines from its header: the `KEY: value` lines at column 0 before the first `STEP` line, outside a fenced block (a step's own `SCRIPT: regex|go|lisp` is the card tree's and is never read here). The first CLASS, SCRIPT and DEADLINE lines win. why is "" or the one line naming what is wrong and what to write; with a why, c is what could be read, and a card whose class is unreadable is a model card.
type Model ¶
type Model struct {
Tier string // "" when line 1 names none
Pin string // provider/model, "" when the card pins none
Tokens string // a count or "unmetered", "" when the pin names none
Deadline int // seconds, 0 when the pin names none
}
Model is what a card's brief says of the model it runs on: the tier its line 1 names (`... tier: flash|pro|frontier`), and a pin, the header lines under line 1 `model: <provider>/<model>` with its `tokens: <n>|unmetered` and `deadline: <seconds>|<duration>` (both required with a pin, read only beside it). A pin bypasses the deal's draw among the tier's routes (docs/SPEC-SPRINT.md, the deal's route); the frame and the deal read the brief through ReadModel only, the one parser of these lines.
func ReadModel ¶
ReadModel reads a brief's model lines: the tier from line 1, the pin from the header block under it (the `key: value` lines up to the first blank line or line of prose, keys in any case). why is "" or the one line naming what is wrong and what to write; with a why, m is what could be read (its Tier as line 1 names it, known or not).
type TestLine ¶
type TestLine struct {
// Package and Name are `TEST: <package> <TestName>`: the Go package
// path the wrapper runs and the test it selects. Tags are the build
// tags the test needs (`TEST: -tags functional <package> <TestName>`),
// "" for none.
Package, Name, Tags string
// None is `TEST: none <why>`; Why is the reason the card has no test.
None bool
Why string
}
TestLine is a card's TEST value, read by ParseTest.
func ParseTest ¶
ParseTest reads a TEST value: `[-tags <tags>] <package> <TestName>` (the package one ./-relative or repository-relative Go package with no .. and no `...` pattern, the name a Go test name, the tags go test's -tags list) or `none <why>`. Anything else is refused: why is one line with the remedy, and the line is zero. A bare `none` is refused too: the reader must see why.
type Who ¶
type Who struct {
Only bool // only friend is a hard pin
Friend bool // a friend's card: WHO: friend [<name>] or WHO: only friend <name>
Name string // the friend it names, "" for any friend
}
Who is a preference or a hard pin from the brief header (docs/SPEC-SPRINT.md, WHO preference). `WHO: friend` is any friend, `WHO: friend <name>` prefers that friend, and `WHO: only friend <name>` waits for her alone. A card with no WHO line, or `WHO: -`, is unpinned: friends whose class covers its tier, then the fleet.
func ReadWho ¶
ReadWho reads a brief's WHO line from its header block (the `key: value` lines under line 1, up to the first blank line or line of prose, the key in any case), the one parser of it: the zero Who when the brief has none or says `WHO: -`. why is "" or the one line naming what is wrong and what to write.
Source Files