Skip to content
Good Grief

Fact vocabulary

A fact is a recorded observation about a flight, reported by the runner that carried it out. Facts are what the control plane checks the rules against: an obligation reads facts, and a work kind’s produces: lists the fact families its work can yield.

The facts a runner may report come from a fixed list, the fact vocabulary. A runner cannot report a fact outside it. The vocabulary has a version, which changes whenever a family, or a value a family may hold, is added or changed. gg version prints the version a release of gg reports.

This page describes fact vocabulary 0.44.0.

To list the facts one flight recorded, run gg facts <flight>.

Categories

Section titled “Categories”

Each family belongs to one of three categories, which say what the fact describes:

Category What it describes
subject A standing property of something that exists between flights, such as the environment the work ran in.
tree Something measured from the repository’s working tree that the flight touched. A flight with no repository cannot produce these.
flight The flight itself: what the agent did, what it said, who took it over, and where the work went. Any work kind that runs can produce these.

The category matters when the rules are checked. An obligation that reads a tree fact cannot apply to a flight that has no repository, so it is marked not attached rather than halting the flight.

Families

Section titled “Families”
Family Category What it records
environment.identity subject The environment the work ran in: a fingerprint of the operating system, architecture, runtime and image, the versions of tools such as Git, hashes of the repository’s dependency lock files, and which of the declared moves this machine was measured to enforce.
source.provenance tree What was actually put on disk: the repository, the ref requested and the ref it resolved to, the commit, whether that commit came from a fork, and how many files and bytes the tree held.
change.manifest tree The files the flight changed, at any point during its work, with line counts. This is the fact the scope check reads.
intent.read flight The file a flight’s intent named, as the runner read it: where, and at which commit.
loop.outcome flight What the agent’s run did: its attempts, the moves it used, how it ended and why.
loop.transcript flight Where the run’s transcript is kept, without carrying the transcript itself.
loop.session flight Where the agent’s own record of its session is kept, as a reference, without carrying it.
loop.model flight Which model one launch of the agent was given. A flight moved to another model while running has two.
loop.digest flight A summary of what the agent did, so that a person can pick the work up without reading the transcript.
loop.question flight A question the agent could not answer from the work itself.
loop.attended flight A session a person ran by hand, and how long the person held the terminal.
handoff.account flight What a person who took a flight over says they did, confirmed in their own name.
flight.nomination flight A work kind the agent nominates for a flight of its own, and why. The nomination asks; the destination decides whether a flight opens.
work-item.proposal flight A change the agent proposes be made to a work item in a tracker.
document.proposal flight An airspace document the flight drafted, asking that it be applied.
landing.proposal flight What the agent asks its own proposal be called, such as a pull request’s title and description.
destination.pushed flight A branch was pushed and nothing was proposed, such as when work is kept for a person to take over.
destination.landed flight Where the flight’s work landed, once a destination accepted it.
environment.reclaimed flight What preparing the environment removed from the machine the flight was given, before the flight’s application was started.
stack.performed flight What happened when the runner ran the project’s own script for bringing its application up or down.
preview.url flight Where the flight’s running application was published, so that a person asked to look at it knows where to go.

What a fact never carries

Section titled “What a fact never carries”

No family has a place for a file’s contents, a credential’s value or anything an agent printed. A fact that concerns a file names it, and a fact that concerns a transcript or a session says where it is kept, with its size and a hash. What leaves the machine explains this boundary.

Section titled “Related”