lab

Documentation

Overview

Package lab mechanises the lab conventions three hand-run experiments proved (itd-2609212137128014): a lab is a throwaway world pinned at one commit of a repository, run to answer one question, whose evidence lives at the operator level and whose knowledge enters the record only through capture.

The store is machine-scoped and keyed on the repository's root commit, the way the transcript and worktree stores are:

~/.abcd.noindex/lab/<root-sha>/index.jsonl        one registry line per lab
~/.abcd.noindex/lab/<root-sha>/<lab-id>/          one lab home
    INTENTION.md                          the question, before any mutation
    snapshot/                             a standalone clone at the pin
    home/                                 the lab's own HOME
    bin/                                  the work binary (and a test binary)
    state/preflight.md                    the preflight artefact
    state/probes/<probe>/                 one probe record per probe
    state/sweep.md                        the retraction sweep's artefact
    findings.md, corrections.md           running logs the harvest mines
    amendments.md                         procedure deltas the lab contributed
    harvest/harvest.md                    the assembled harvest

Every verb writes only under one lab home (the registry line is the store's own), and nothing is ever written into the repository a lab studies. Hand-run labs that predate the keyed layout sit beside the root-commit directories and are neither read nor written.

The package never writes to stdout: it returns results, and the front doors under internal/surface render them.

Index

• Constants
• Variables
• func SetAbcdRootCommitForTest(sha string) (restore func())
• func ValidID(s string) bool
• type Candidate
• type Check
• type Correction
• type Entry
• type Finding
• type Gap
• type Harvested
  • func Harvest(repoRoot, id string) (Harvested, error)
• type Instance
• type Listing
  • func List(repoRoot string) (Listing, error)
• type Minted
  • func Mint(repoRoot, question, pin string) (Minted, error)
• type Preflighted
  • func Preflight(repoRoot, id string) (Preflighted, error)
• type Probe
  • func Record(repoRoot, id, name string) (Probe, error)
• type SectionCoverage
• type Summary
• type Swept
  • func Sweep(repoRoot, id string) (Swept, error)

Constants

const (
	KindProduct   = "product"
	KindProcedure = "procedure"
	KindResult    = "result"
	KindGate      = "gate"
)

The finding kinds the harvest sorts on.

const (
	GroupIsolation  = "harness-isolation"
	GroupDualBinary = "dual-binary"
)

The two check groups the preflight runs.

Variables

var ErrHalted = errors.New("lab halted")

ErrHalted marks a gate that failed: the verb wrote its artefact and a finding, and the lab is halted until that gate passes again.

var ErrRefused = errors.New("refused")

ErrRefused marks a refusal the caller can act on (a bad argument, an unknown lab, a store path occupied by the wrong kind of thing). A front door maps it to a usage exit.

var StoreDisplay = abcdhome.Display("lab")

StoreDisplay names the store in a message, in tilde form, so no output carries the account's home path.

Functions

func SetAbcdRootCommitForTest

func SetAbcdRootCommitForTest(sha string) (restore func())

SetAbcdRootCommitForTest repoints the root commit the dual-binary gate applies to, so a test can treat a throwaway repository as abcd's own, and returns the restore.

func ValidID

func ValidID(s string) bool

ValidID reports whether s is a lab id as the store names one.

Types

type Candidate

type Candidate struct {
	Finding     string `json:"finding"`
	Title       string `json:"title"`
	FoundDuring string `json:"found_during"`
	Refutation  string `json:"refutation,omitempty"`
	Command     string `json:"command"`
}

Candidate is a product finding the harvest lists for filing through capture.

type Check

type Check struct {
	ID            string `json:"id"`
	Group         string `json:"group"`
	OK            bool   `json:"ok"`
	NotApplicable bool   `json:"not_applicable,omitempty"`
	Detail        string `json:"detail"`
}

Check is one preflight check's verdict. A check that does not apply to this lab passes (OK) and says so: NotApplicable is set, and Detail says why.

type Correction

type Correction struct {
	N         int        `json:"n"`
	Line      int        `json:"line"`
	Pattern   string     `json:"pattern"`
	Applied   bool       `json:"applied"`
	Invalid   string     `json:"invalid,omitempty"`
	Instances []Instance `json:"instances"`
}

Correction is one retracted claim: the literal text the lab's documents must no longer carry.

type Entry

type Entry struct {
	ID       string `json:"id"`
	RootSHA  string `json:"root_sha"`
	Pin      string `json:"pin"`
	Created  string `json:"created"`
	Question string `json:"question"`
}

Entry is one registry line: what a lab was minted for, and at which pin.

type Finding

type Finding struct {
	ID         string   `json:"id"`
	Title      string   `json:"title"`
	Kind       string   `json:"kind"`
	Status     string   `json:"status"`
	Probes     []string `json:"probes"`
	Evidence   []string `json:"evidence"`
	Refutation string   `json:"refutation,omitempty"`
	Gate       string   `json:"gate,omitempty"`
	Body       string   `json:"body,omitempty"`
}

Finding is one entry of a lab's findings log.

type Gap

type Gap struct {
	Finding string `json:"finding"`
	Reason  string `json:"reason"`
}

Gap is a finding the harvest cannot cite from the lab's own records.

type Harvested

type Harvested struct {
	ID         string            `json:"id"`
	Written    bool              `json:"written"`
	Artefact   string            `json:"artefact"`
	Sections   []string          `json:"sections"`
	Probes     []string          `json:"probes"`
	Candidates []Candidate       `json:"candidates"`
	Amendments []string          `json:"amendments"`
	Gaps       []Gap             `json:"gaps"`
	Coverage   []SectionCoverage `json:"coverage"`
	Halted     []string          `json:"halted"`
}

Harvested is the harvest's result.

func Harvest

func Harvest(repoRoot, id string) (Harvested, error)

Harvest assembles the lab's harvest in the lifeboat's section shape — intention, method, what worked, what is open, candidates, coverage — from the INTENTION, the findings log and the probe records, citing each finding's probe records by path. Its product findings are listed as capture candidates, each with the capture line that files it, found during this lab.

No claim outlives its input: a finding that cites no probe record or evidence file, or cites one that is missing or incomplete, is a gap, and a harvest with a gap is refused and writes nothing. A halted lab can still be harvested — halting is what ends a lab's mutation, and its gate findings lead the harvest.

type Instance

type Instance struct {
	File string `json:"file"`
	Line int    `json:"line"`
}

Instance is one place a retracted pattern still stands.

type Listing

type Listing struct {
	Store     string    `json:"store"`
	Labs      []Summary `json:"labs"`
	Unparsed  int       `json:"unparsed,omitempty"`
	RootSHA   string    `json:"root_sha"`
	StoreSeen bool      `json:"store_seen"`
}

Listing is the bare verb's read-only answer.

func List

func List(repoRoot string) (Listing, error)

List reads this repository's labs. It writes nothing and creates nothing.

type Minted

type Minted struct {
	Entry
	Home     string   `json:"home"`
	Snapshot string   `json:"snapshot"`
	Written  []string `json:"written"`
	Next     []string `json:"next"`
}

Minted is what mint laid down.

func Mint

func Mint(repoRoot, question, pin string) (Minted, error)

Mint lays down a new lab for question, pinned at pin (a revision of the repository at repoRoot; empty means HEAD): the lab home under this repository's lane of the store, a standalone clone of the repository detached at the pin, the lifecycle's documents, and one registry line. Nothing is written into the repository.

The clone runs under the isolated git environment, so no hook the operator's global configuration names fires while it is made, and its origin remote is removed, so nothing done in the lab world can be pushed back into the checkout it came from.

type Preflighted

type Preflighted struct {
	ID       string  `json:"id"`
	Passed   bool    `json:"passed"`
	Checks   []Check `json:"checks"`
	Artefact string  `json:"artefact"`
	Finding  string  `json:"finding,omitempty"`
	Lifted   string  `json:"lifted,omitempty"`
}

Preflighted is the preflight's result: every check, the artefact it wrote, and — when a check failed — the finding the halt recorded.

func Preflight

func Preflight(repoRoot, id string) (Preflighted, error)

Preflight runs the harness-isolation and dual-binary checks against the lab home and writes them as the lab's preflight artefact. A failed check halts the lab and records the refusal as a finding naming every failed check (ErrHalted); a passing preflight lifts a standing preflight halt. The finding stays in the log either way.

type Probe

type Probe struct {
	Lab      string   `json:"lab"`
	Name     string   `json:"name"`
	Dir      string   `json:"dir"`
	Files    []string `json:"files"`
	Artefact string   `json:"artefact"`
	Fill     string   `json:"fill"`
}

Probe is one probe record's scaffold.

func Record

func Record(repoRoot, id, name string) (Probe, error)

Record scaffolds one probe record under the lab's state/probes/: the five capture files, empty, and a record.md naming the artefact the probe observes (the work binary's vintage and sha256, when there is one). It refuses on a halted lab: a lab halted by a gate records nothing more until the gate passes, which is what keeps a refusal from being adapted around.

type SectionCoverage

type SectionCoverage struct {
	Section string `json:"section"`
	Status  string `json:"status"`
	Note    string `json:"note"`
}

SectionCoverage is one harvest section's grounding, in the lifeboat's grounded / partial / blank vocabulary.

type Summary

type Summary struct {
	Entry
	Home    string   `json:"home"`
	Probes  int      `json:"probes"`
	Halted  []string `json:"halted"`
	Missing bool     `json:"missing,omitempty"`
}

Summary is one lab as the bare listing shows it.

type Swept

type Swept struct {
	ID          string       `json:"id"`
	Passed      bool         `json:"passed"`
	Corrections []Correction `json:"corrections"`
	Files       int          `json:"files"`
	NotSwept    []string     `json:"not_swept"`
	Artefact    string       `json:"artefact"`
	Finding     string       `json:"finding,omitempty"`
	Lifted      string       `json:"lifted,omitempty"`
}

Swept is the retraction sweep's result.

func Sweep

func Sweep(repoRoot, id string) (Swept, error)

Sweep verifies every correction the lab recorded is applied: each retracted literal is searched for across the lab's own documents — the pattern, not the instance — and every place it still stands is listed. An unapplied or unreadable correction fails the sweep, and so does any document the sweep could not read while a correction is recorded (fail-closed: it is listed by path, never passed over). A failed sweep halts the lab and records the refusal as a finding (ErrHalted); a passing sweep lifts a standing sweep halt. The artefact and the finding name a correction by its number, never by its text, so neither becomes a new instance.