livery.workshop¶
The devkit: what every repository in the livery ecosystem runs. A
repository depends on the workshop, and footman mounts it through its
project rung: the rendered tasks.py mounts nothing, and every verb
below arrives through that dependency.
The extension model¶
The workspace contract (workshop.toml at the root) lists the
workspace's extensions in [workspace] extensions, and each
package's contract lists the extensions the package is composed of
in its own extensions; a package that lists none holds none. Every
extension is one kind: the root's list takes any of them, and a
package's list one that composes something in a package. A list's set is
the list and every extension it requires, and the installed set is
the root's set and every package's set. The workspace's own tests/
directory holds the root's set, so a root lists the language its own
tests are written in. No list's order means
anything: the installed set mounts in composition order, each
extension after the ones it requires and ties alphabetical, and each
list is written as its canonical list. Those lists are the whole of
discovery: a package installed by accident never changes a
repository. The root's list is required; a contract without it
refuses at mount and prints the line to add. The base,
livery.workshop, is never listed: importing its plugin registers
its task surface and then mounts the installed set. The instance
always wins last: its own files (CLAUDE.project.md,
anything below the plugin line in tasks.py) are seeded once and
never rewritten.
Contract keys are kebab-case, at the root and in every package's
contract: a key spelled with underscores refuses on read, naming its
spelling and the file to rename it in. Every key is declared by the
extension that reads it, and a contract holds nothing else: a key no
extension declares, a key of an extension no list takes, a value of
the wrong type and a value outside its allowed set each refuse on
read, naming the file, the key, what the table takes, and the nearest
spelling. An extension's keys are taken in the root's contract while
the installed set holds it, and in a package's contract while the
root's set or the package's own set holds it. While a list names an
extension no installed distribution declares, what that extension
requires is unknown, so no installed extension's key refuses as one no
list takes until fm sync installs it; a key no installed extension
declares still refuses. The base declares its
own keys the way an extension does, in the contract.toml its
package ships beside its code, the keys of extension.toml among
them.
The declarations compose into one JSON Schema per contract, and the
judge validates a contract against it. fm sync writes the same
schemas, one file per contract under .workshop/schema/:
workshop.json for the root's contract, package.json for a
package's, extension.json for an extension.toml. Each holds the keys
of the base and of the extensions of the installed set; a key of an
installed extension no list holds stays in it as a key that takes no
value and names its extension. The files follow what is
installed and listed, and they are written for the checkout alone,
never committed. The composed .taplo.toml points Taplo, the language
server behind Even Better TOML and other editors' TOML support, at
each file by path from the root, so an editor completes and validates
a contract as it is typed and refuses what the judge refuses. Each
key's doc is its description there, shown when a person hovers the
key; every key the base and the listed extensions declare carries one. The
schema says what shape a contract has; a rule a schema cannot say
stays with the code that reads the key.
The workshop's wheel, livery-workshop, ships the base alone. Every
extension of the livery distributions ships in a distribution of its
own, named livery-extensions-<name> after the name a contract lists:
| Extension | Distribution |
|---|---|
basedpyright |
livery-extensions-basedpyright |
changelog |
livery-extensions-changelog |
clang-format |
livery-extensions-clang-format |
clang-tidy |
livery-extensions-clang-tidy |
claude |
livery-extensions-claude |
cmake |
livery-extensions-cmake |
conan |
livery-extensions-conan |
coverage |
livery-extensions-coverage |
cpp |
livery-extensions-cpp |
docs |
livery-extensions-docs |
lfs |
livery-extensions-lfs |
mkdocstrings |
livery-extensions-mkdocstrings |
mypy |
livery-extensions-mypy |
nanobind |
livery-extensions-nanobind |
pyrefly |
livery-extensions-pyrefly |
pytest |
livery-extensions-pytest |
python |
livery-extensions-python |
ruff |
livery-extensions-ruff |
ty |
livery-extensions-ty |
A workspace gets an extension by listing it: fm sync installs the
distribution of each extension its lists hold, and of each extension
those require. An extension's distribution requires the distribution
of each extension it requires: conan's requires cpp's, nanobind's
requires python's, cpp's and conan's, and mkdocstrings' requires
docs'.
An extension is declared by an entry point in the workshop.extensions
group, mapping the name a contract lists to the package that ships it.
Beside that package sits its extension.toml, which the mount and the
contract judge read without importing the extension. The file is a
contract like workshop.toml: kebab-case keys, every key judged, and a
refusal naming the file, the key, what the table takes and the nearest
spelling. Every key is optional to the mount:
[extension] description, what the extension does in a sentence or two, which opens its block in the agent's guidance and on the site's development pages; the conformance kit requires it;[extension] api-version, the extension API it was written for, refused at mount when it is not this workshop's;[extension] plugin, the footman plugin carrying its verbs, mounted in composition order;[extension] requires, the extensions it cannot work without, which join every set that holds it, whatever they declare, and come before it in composition order; a list's canonical form leaves them out;[extension] dormant-until, what another extension does for this one by declaring a[for.<this>]table, as a verb: coverage saysmeasures. Until a listed extension contributes such a table, this one is dormant: it registers no step and no job, its plugin still mounts, andfm extensionsandfm doctorsay what it waits for and which installed extensions would wake it,nothing listed measures; cmake and pytest would. A listing kept for a contributor still to come is a statement of intent, so it is named, never refused;[phases.<phase>], a phase the extension declares, in the grammar the base declares its own in:level,packagefor a phase run over one package at a time orworkspacefor one run over the workspace once;gated, whetherfm checkruns it;after, the phases it follows in the train's order;verb, whetherfm <phase>is generated; andkeys, the keys the engine running it gives its steps, each with its type. A phase no declaration names refuses naming the declared ones, and two extensions declaring one phase refuse naming both.;[phases.<phase>.<step>], a step the extension adds to a package's lifecycle phase, with the keys every step takes:main,"module:function"in its own package or the tool's words;after, the steps it runs after; and the context keys itprovides, each with its type, andreads. The step runs once per package whose set holds the extension, so it names noscopeand noextensions. Itsdeletesnames the steps of the base or of an extension it requires that never run for such a package, each"<owner>:<phase>.<step>"to the reason;[queries.<name>], a query the extension declares, in the grammar the base declares its own in:combine, how the answers make one,union,nearest,agreedor a"module:function";level,packagefor a question about one package orworkspacefor one about the workspace;default, the answer while nobody answers; andvalues, the only answers it takes. Two extensions declaring one query refuse naming both;[queries], the queries the extension answers, each query's name to the"module:function"that answers it, called with the package or the workspace root, or[queries.<name>] value, a literal answer; an answer to a query nobody declares refuses naming the declared ones;[categories], the categories the extension gives the paths of each package whose set holds it, each category to the patterns it takes; a package whose extensions declare categories is answered by them and the base's rules, and its own[categories]wins over both;[fragments."<target>"], a file the extension's code writes, or a directory of them when the target ends in/:render, the"module:function"called with the workspace root, which answers the file's text, or nothing for no file, and for a directory each file's path under it to its text or to the shipped file it links to;localfor files that belong to this checkout alone. The fragment lives while the installed set holds the extension, and two extensions writing one path refuse;[toolroom] requires, the tools it runs, its verbs' and its steps',["docker?>=27"], one of the sites the tool profile reads;[contract.<contract>.<table>], the contract keys it reads, each a table with itstypes, and itsvaluesanddocwhere it has them;[phases.<phase>.<step>], each step it adds to a phase of the gate,[phases.format.ruff]forfm format.ruff, registered under the listed name, which the gate prints beside each; a step declaredenabled = falseregisters only while the root contract turns it on at the step's own address,[phases.<phase>.<step>] enabled = true;[for.<target>], the same tables, read only while the target is installed and applied only while it is listed, its[for.<target>.queries]answers, its[for.<target>.fragments]files and its[for.<target>.toolroom] requiresamong them: cmake's[for.coverage]table requires Microsoft's coverage engine on Windows, so a workspace locks it only while it lists coverage. A query is declared at the top level alone. The files the extension ships undercontent/for/<target>/root/andcontent/for/<target>/package/are delivered while the table applies, as itscontent/root/andcontent/package/files always are; a directory there for a target the file declares no table for refuses, naming both;[replaces]and[deletes], a shipped file of the base or of an extension it requires,"<owner>:<name>", that its own file of that name replaces or that it deletes, to the reason;[templates.<name>], a template, whose verbfm new.package.<name>creates a package from it:doc, one line saying what a package born from it is;extensions, the extensions such a package lists; andextends, another template whose files the birth writes first. Its files live undercontent/templates/<name>/beside theextension.toml. A workspace offers a template while its installed set holds the extension that declares it, and reads it at a birth alone.
A step whose verdict is its tool's exit code is the tool's words, and needs no code:
[phases.format.ruff]
main = ["ruff", "format", "--check", "--force-exclude", "{arguments}", "{paths}"]
fix = ["ruff", "format", "--force-exclude", "{arguments}", "{paths}"]
extensions = ["python"]
tools = ["ruff"]
claims = [{ category = "source", suffixes = [".py", ".pyi"] }]
extensions names the extensions whose packages the step judges: a
package whose set, its list and what the list requires, holds one of
them. A package that lists no extension holds
none, so no such step judges it. A step that names none judges the
workspace.
main is the template: the tool's name, as tools names it, and the
arguments that judge; fix and safe-fix are the templates that
rewrite under --fix and --safe-fix, safe-fix falling back to
fix. A template places what the workshop gives it: {paths} stands
where the paths the run reaches go, and a template without it runs
whole, once with no path, so the tool reads its own configuration;
{arguments} stands where the words after -- on the step's verb go,
and a template without it takes none. Each stands alone as one word.
The workshop splits a long path list into the fewest calls under the
command-line limit, runs the tool through its toolroom handle, and a
non-zero exit refuses, every call's reason in one refusal. A package
step is called from the package's directory with the package's files.
env gives each call variables over the run's own, and a word may
name a placeholder the workshop answers: {cache}, the step's
directory under .workshop/.cache/; {package}, the package a call
judges; and {compile-commands}, that package's compilation database,
without which the call is skipped. matrix names a placeholder of its
own and its values, one call per value in parallel, each its own
verdict:
[phases.typecheck.mypy]
main = [
"mypy", "--platform={platform}", "--cache-dir={cache}/{platform}",
"{arguments}", "{paths}",
]
matrix = { platform = ["linux", "darwin", "win32"] }
fm explain typecheck.mypy prints the template a step runs and what
the workshop puts where {paths} and {arguments} stand. The
conformance kit's words-are-answerable clause refuses a placeholder
nothing answers, a matrix key no word names, a tool the step does not
require, and a package's placeholder in a step that judges the
workspace whole.
A step the words cannot say, one whose verdict is not its tool's exit
code or whose paths need reshaping first, names the functions that run
it instead, main and fix as "module:function" in the extension's
own package, each imported when the step runs, and safe-fix a
function of its own where the fix has a safe mode. A workspace step in
code that declares no inputs narrows by the packages the run
reaches, which its code asks scoped_packages for, and one with
inputs is selected by them; a step in code that names tools wraps
them and takes the words after --. The mount reads each reference
from its module's source. A module outside the package, or a name the
module does not define at its top level, refuses naming the file and
the key before anything runs.
An entry names its extension, either as the string or as a table
entry's name. An entry takes no version, ? or scope: an
extension's version comes from its wheel, and the lock pins it. A root
[phases.<phase>.<step>] table that turns on a step no listed
extension declares off refuses in layering.graph, naming the steps
declared off.
A footman plugin that declares no extension is never offered as one.
The mount registers a [for.<target>] table once both its owner and its
target are mounted, so a house with opinions on several languages
contributes to each only where the language is listed. Cooperation is
greedy: an extension contributes to every target of the installed set
it declares a table for. That includes a target listed later, and a
target a later release of the extension declares a table for, with no
change to the lists. A root entry opts the workspace out with
without, the targets the extension contributes nothing to:
Here the house, with a table for each language, contributes to python
and nothing to cpp, and a language listed later gets its contribution.
layering.graph names an entry whose without names a target the
extension declares no table for, or one the installed set does not
hold, naming the entry and the target. Its --fix writes an entry
whose without is empty as the name alone. A package opts out of one
step at the step's address in its own contract,
[phases.<phase>.<step>] enabled = false.
fm extensions prints the base, then each extension in mount order,
who requires it, the packages whose sets hold it, its tools, the
targets it contributes to (for:), the targets its entry leaves out
(without:), whether it is dormant and what would wake it, and each
step it declares off with whether the root contract turns it on.
A package's extensions names the extensions it is composed of. Its
set is that list and every extension the list requires, transitively,
whatever those extensions declare: requires alone composes a package.
Two extensions that cannot share a package are refused by
the rules of the phase they both add steps to, two providers of one
context key or two owners of one executable, never by a rule over the
pair. A package writes its set as its canonical list, the minimal
one: no extension another listed one requires, in composition order.
In that order an extension comes after what it requires; ties go
alphabetically. layering.graph names a list in any other form,
and its --fix rewrites it. A package's entry is the extension's name
alone, with no options.
The root's list is written the same way: its canonical list holds no
extension another listed one requires, unless the entry carries a
without, since an opt-out has no other place to be written, and comes
in composition order. layering.graph names a root list in any other
form, and its --fix rewrites it, keeping each entry's comment lines.
The mount takes the installed set in composition order, and every
order the workshop reads follows it: the order steps register in, and
so the order the gate's rewriters run in under --fix, each also
after the steps it names in after; the order a workspace-level query
is answered in; the order shipped files compose in; and the order of
the guidance. Neither list's order changes any of them. A step of an
extension goes into a phase the base, the extension itself or an
extension it requires declares, and a step of its [for.<target>]
table also into one the target declares; any other refuses at mount,
naming the declarer and both ways to write the step. A step's
replaces and deletes, and an extension's [replaces] and
[deletes], name what the base or an extension it requires
declares, and a [for.<target>] step's also what the target
declares; the mount refuses any other. Any extension mounts from
either list. So an extension's content, tools and distribution belong
to the workspace while any list holds it: one that only a package
lists joins the dev group, and fm sync installs it. While no
installed distribution declares it, the mount names it with the list
that brings it. A set is named by its canonical list joined with +,
such as cmake+cpp.
fm sync installs a newly listed extension the way the workspace
resolves it, before it renders anything else:
- It writes the project file alone. Its dev group now names the
extension's distribution. This write reads the contracts without
judging their keys: until the extension is installed, no
declaration says which keys are its, so the root's
[python]table would refuse the sync that installs python. - It runs
uv sync, which locks and installs through the project file's[tool.uv.sources]and indexes. An extension the workspace sources from a path or from git installs from there, even when an index also offers it. - It continues in a fresh process, which mounts the extension, judges every contract over the installed declarations, and renders every file with it. A key no installed extension declares, such as a misspelt table, refuses there.
When no installed distribution declares the extension after the
install, the sync refuses, naming it and the list that brings it.
Before that refusal, and when the install fails, the sync puts
pyproject.toml, its receipt and uv.lock back as they were.
The base declares its phases in the [phases] section of its
contract.toml: sync, clean, build, format, lint,
typecheck, typecomplete, examples, drift, provenance,
layering, test, stamp, publish, verify, configure and
run. The gated ones, build, format, lint, typecheck,
typecomplete, examples, drift, provenance, layering and
test, are what fm check runs, and each has a verb, fm <phase>,
with a sub-task per step. fm sync runs sync once over the
workspace, after it installs the tools and before uv sync, and an
extension the root lists adds steps to it as one a package lists does.
A step there runs once, and one that declares scope = "package" runs
once for each package whose set holds an extension its extensions
names. A step that runs once and names extensions runs while a
package's set holds one of them, and not at all while none does: conan's
step makes the one default profile once, however many packages hold
conan.
A package-level phase, clean, build, stamp, publish, verify
or run, runs its steps once per package, and each extension of the
package's set may add steps to it, as many as it needs:
[phases.build.bindings]
main = "acme.native._build:bindings"
reads = ["abi"]
[phases.build.wheel]
main = "acme.native._build:wheel"
after = ["build.bindings"]
provides = { wheel = "path" }
An extension whose packages must not run a step another extension of
their set adds deletes it, with the reason. The nanobind extension, a
distribution of its own, livery-extensions-nanobind, builds a
package's platform wheels, so in a set that holds nanobind python's
uv build never runs, and neither do the conan steps that would build
and publish the recipe the package consumes. Its own stamp step writes
the version and raises the floors in both the pyproject and the
recipe, since one step of a package provides the files the phase
changed, so python's and conan's stamp steps go too:
[phases.stamp.nanobind]
main = "livery.extensions.nanobind._stamp:stamp"
reads = ["version", "floors"]
provides = { changed = "strs" }
[phases.stamp.nanobind.deletes]
"python:stamp.python" = "this step writes the version and the pyproject's floors through python's stamp"
"conan:stamp.conan" = "the recipe names no version, and this step raises its floors through conan"
A package whose set does not hold the deleting extension runs the deleted step as before. A deletion names a step an installed extension or the base declares that runs once per package, and states its reason; any other refuses, naming the file and the step. The walk names each package a registered step skips for a deletion, with the deleting extension and its reason.
Every phase runs through one walk, the gate's phases included: each
step is a footman step inside one parallel() block, so footman owns
the concurrency, the record, the capture and the cancellation. A step
of a package-level phase runs once per package in scope, a step of a
workspace-level phase once. Independent steps run concurrently; a
step starts once the steps it names in after and the providers of
the keys it reads have run, for the same package. A step that fails
is the walk's verdict, raised again once every step ran: the steps
that depend on it are not run and say so, and the steps that depend
on nothing failed still run. A step that needs cleanup on failure
does it itself. Each step receives the one PhaseContext: it writes
the keys its table provides with provide and reads the ones it
reads with read. A value of another type than the declared one
(str, int, bool, path, strs, paths or table), and a key
the step's table does not declare, refuse naming the step. Two steps
providing one key, a key nobody provides, two extensions declaring
one step, and an order with no start refuse before any step runs, and
layering.graph names them for each package.
A phase's declaration names the keys the engine running it gives its steps, which a step reads like any other and no extension provides. The engine gives each phase its own; a key the phase does not declare, or a value of another type, refuses before any step runs:
| Phase | Keys the engine gives | Key the release train reads back |
|---|---|---|
stamp |
version (str), the version to write; floors (table), each member released with the package, by its path, to the version it releases at, empty for a member released alone. Each step writes the version into its own manifests and raises there each floor they declare on one of those members, and the base raises the floor of each of the package's [[depends]] edges on one in its workshop.toml |
changed (strs), the files written |
build |
isolated (bool), the side; configuration (str), the preset: the train builds isolated in release, fm check on the tree in instrumented, and fm run on the tree in debug. epoch (int), the build's source date, from the train; 0 takes the build tool's own |
dist (path), where the artifacts are |
test |
isolated (bool), true on the train's legs; resolution (str), floor, latest or head; release-dirs (paths), the co-released set's dist/ directories. fm check gives none of them, which is the tree side |
resolved (table), each distribution the leg installed, to its version |
publish |
version (str) and registry-target (table), the resolved registry's fields, which RegistryTarget.from_table reads back; prebuilt (bool), true when a job of the run built the package and the run collected it into dist/ |
published (bool), whether anything uploaded |
verify |
version (str), the released version; tree (path), checked out at its receipt tag; interpreter, index and extras (str) |
exit-code (int), the verification's |
run |
executable (str), the executable to start. The words after -- are the context's arguments, as they are for every step, and the step that starts the executable records its exit code with exit |
A phase whose keys hold isolated has two sides: the tree, and the
isolated one, from a copy of the sources in a fresh environment. A
step declares isolated = true to serve the isolated side alone,
isolated = false for the tree alone, and neither for both; the walk
runs it on the side the engine gives. isolated on a step of a phase
without the key refuses. fm check runs the tree side, so a step
serving the isolated side alone is none of the gate's steps: the
release train runs it, once per resolution [release] prove lists
(Releases). A step of the build phase, which runs once
per package and which fm check runs, joins the gate's steps when it
serves the tree side: cmake's build.configure and build.compile
build each package that holds cmake before its test.ctest runs. The
cmake extension is a distribution of its own,
livery-extensions-cmake, listed as cmake in a package's
extensions. The builds of python, conan and nanobind serve the
isolated side alone: each builds what a release publishes, which the
gate does not build.
The release train stamps, builds, tests and publishes a package, and
fm release.verify verifies a released version, through these phases:
the steps the package's extensions add to them. A phase its extensions
add no step to refuses the release, naming the phase, and a phase whose
steps provide nothing under the key the train reads back refuses,
naming the phase and the key. The version the train reads and stamps is
its extensions' answer to the current-version query, and a package
whose extensions answer none refuses, naming the query. The registry it
publishes a package to is its extensions' answer: the one ecosystem
their distributions answer names, and the probe of that registry
their registry answer gives, which the train polls until an upload is
served.
An extension also answers queries, questions the base or another extension declares:
[queries]
public-modules = "acme.native._answers:public_modules"
executables = "acme.native._answers:executables"
[queries.editor-extensions]
value = ["acme.editor"]
A query is declared with the rule that combines its answers, by the
base in its contract file and by an extension under [queries.<name>]
in its own; a handle, Query("docs.members"), names it and types its
answer. A package-level query is asked with a package,
answer(package, query), and each extension of the package's set that
answers is asked in composition order; a workspace-level one is asked
with the workspace root, answer(root, query), and the installed set
answers in composition order. The answers combine by the query's
rule, and with nobody answering the query's declared default stands,
or the rule's answer over nothing. The base declares:
| Query | Level | Answer | Combined |
|---|---|---|---|
public-modules |
package | the modules that declare the public API | the union |
module-roots |
package | the names other packages reference the code by | the union |
references |
package | what each source references: its file, its module name, each name with how the source makes the reference, and the names its language's conventions account for | the union; a file outside the package, or one two extensions answer for, refuses |
version-files |
package | every file stamp's steps write, versions and floors: the release keeps and restores them, and the local act refuses while one has changes of its own |
the union |
current-version |
package | the version the manifests declare | one value every answer agrees on |
requirements |
package | each required distribution to its constraint | the union; a name valued twice refuses |
requirement-writers |
package | the functions that write a requirement on a sibling into the manifests, each a RequirementWriter called with the package, the sibling and the floor, and each taking a sibling of its own ecosystem alone |
the union, and every writer is called; a sibling no writer takes refuses, naming the sibling's set |
test-requirements |
package | each distribution the tests require beyond the requirements, to its constraint; a package whose set answers it has a home for its test edges | the union; a name valued twice refuses |
test-requirement-writers |
package | the functions that write a test requirement on a sibling into the manifests, called as the requirement writers are | the union, and every writer is called; a sibling no writer takes refuses, naming the sibling's set |
distributions |
package | each released distribution's ecosystem and name | the union |
registry |
package | the registry the package releases to, as a probe of the versions it serves | one value every answer that is not empty agrees on |
compile-commands |
package | the build's compilation database | the answer of the extension no other answering one requires |
executables |
package | the executables fm run starts |
the union; a name two extensions answer refuses |
host-tools |
package | what the host must provide and no store installs, such as a C compiler; fm doctor and fm env.check name each one that does not resolve |
the union |
editor-extensions |
workspace | the marketplace ids the rendered .vscode/extensions.json recommends |
the union |
python.dev-group |
workspace | the lines of the root project file's dev dependency group |
the union |
python.docs-group |
workspace | the lines of the root project file's docs dependency group |
the union |
release-notes |
workspace | the provider that writes each release's notes | one answer, the nearest by requires |
store.series |
workspace | the state store's series an extension keeps, which the janitor bounds and fm store.ls lists |
the union |
job-built-members |
workspace | each member a job of the release point builds before the wave, its path to the job's name | the union; a member two answers give different jobs refuses |
checkout-inputs |
workspace | the inputs the checkout step of the rendered GitHub and Gitea workflows passes to the checkout action, each name to its value as the workflow writes it; GitLab's runner checks out by itself and reads none | the union; an input two answers give different values refuses, and so does one the step sets from the job's declaration (ref, fetch-depth, fetch-tags, token) or a value that is not a string |
ci.fold |
workspace | how the gate job folds a file a check leg's shards each left into the platform leg's one file, by the file's name: a function called with the shards' files in shard order | the union; a file two answers fold refuses, and a file nobody folds is red by name in the fold |
reaches |
workspace | what a change reaches beyond its own packages and their dependents: functions, each called with the run's Changes, that map each changed path they widen to why and to the paths of the members it reaches; asked while a changed path lies inside a package |
the union; every member an answer names runs with its dependents, and an answer that raises, or names a path outside the members, runs everything |
A name no extension declares refuses with the nearest one; an answer
refuses when it is off the query's values. A package-level query is
asked of the package's set alone, and a workspace-level one of every
extension the workspace mounts, so any extension answers either:
nanobind, which composes a package, answers the workspace-level
job-built-members.
An extension also answers under [for.<target>.queries], in the same
grammar. That answer is asked only while the target is listed and the
extension's listing contributes to it, by the rule that registers a
[for.<target>] table's steps, so an answer for an unlisted target
never runs. An extension that answers one query at its top level and in
a [for] table, both asked, answers a union query with every item of
both, once each; a query of any other rule refuses, naming both places.
fm run <package>[:<executable>] -- <arguments> starts one of the
executables a package's extensions answer under executables, and
exits with its exit code. A package with one executable needs no name,
and inside a package's directory the package may be left out;
completion offers each package:executable. First the gate's build
phase runs over the package's dependency closure, dependencies first,
on the build phase's tree side in the debug configuration, and
passes over each package whose files and dependencies are unchanged
since its last good build in this checkout, so a second run with
nothing changed starts at once. Then the run phase runs every
step the package's set adds to it, except that of the extensions
answering executables only the owner's steps run: the step that
starts the executable reads the phase's executable key and the
context's arguments, and records the exit code with exit, which
the verb exits with. An extension that answers executables adds a step to
the run phase, or its declaration refuses. The python extension
answers with the scripts a package's pyproject.toml names under
[project.scripts], and its step starts the one the workspace's
environment holds, which fm sync installs.
Each installed template is a verb: fm new.package.<template> <name>
creates a package under packages/<name> from the template, and wires
it into the workspace. The installed templates are the base's and those
of each extension the installed set holds that an installed
distribution declares. The workshop makes their verbs when it loads,
from the declarations it reads as it mounts the installed set, and
makes them again when the installed set changes.
fm new.package --help lists each with its doc, and fm new.package
alone refuses as any group does, naming them. The birth writes the
package-base seeds every package starts from, the base's docs page
and what the listed extensions add to it, then the files of each
template the born one extends, the template extended first and the born
one last; for a path two of them write, the later one wins. The
package's contract lists the born template's extensions in their
canonical form. Every written file is the workspace's own from then on,
and nothing records the template: an extension that needs to know what
a package is reads it from the package's own manifests, as python reads
its scripts. The templates the livery distributions declare, each
available while the extension that declares it is installed. The base
declares workshop-extension, which extends python's
python-library, so its verb refuses, naming python, until the
workspace lists python:
| Template | Declared by | Lists | Extends | Options |
|---|---|---|---|---|
python-library |
python | ["python"] |
--command |
|
workshop-extension |
the base | ["python"] |
python-library |
--app; fixes --command to none |
nanobind-module |
nanobind | ["nanobind"] |
python-library |
fixes --command to none |
cpp-package |
conan | ["cmake", "conan"] |
--package-type |
A template declares its creation options, and its verb takes them as
options: fm new.package.<template> <name> --<option>=<answer>. An
option is a table under
[templates.<name>.options.<option>] in the file that declares the
template:
[templates.cpp-package.options.package-type]
doc = "conan's package type, which the recipe's package_type and the CMake target follow"
choices = ["library", "application", "header-library", "static-library", "shared-library"]
default = "library"
Its doc is required, and the verb's --help, completion and the
conformance kit's declaration-documented clause read it. It takes
either choices, a list of the answers it takes, or a type, one of
str, int and bool; a bool option is spelled --<option> and
--no-<option>. An option without a default is required. A template
that extends another takes the other's options too, and its fixes
table gives an answer to one of them, which a birth from it then takes
no answer for: workshop-extension writes fixes = { command = "" },
since its one script is the App's. Declaring an option of a template it
extends again refuses; fixing one is the way to change it. The
declaration also refuses an option named name, the package's name
every template's verb takes first, or help, footman's own flag.
Every answer is checked before anything is written. An option the
template does not take is an unknown option, a required one without an
answer is named, and an answer outside the option's choices or type is
refused, naming the option and what it takes. Each option is an
ordinary option of the template's verb, with its choices as a
Literal, its doc as its help line and its default as its default,
so footman's completion manifest lists every template's options and
choices as data, and a completion runs no code of the template's.
Each answer renders the template's files as a variable: the option's
name with its hyphens as underscores, so --package-type is
package_type, and an option without an answer renders its default. A
.jinja file that renders to whitespace alone is not written, so a file
depends on an answer by wrapping its whole body in
{% if command %} and {% endif %}; that is how python-library
writes its __main__.py and the test of it only with --command. The
answers are not stored: a step that needs one later reads the file the
answer wrote, as fm run reads the script from [project.scripts].
fm new.package.python-library <name> --command=<script>adds the script<script>to[project.scripts], which runsmain()in the package's__main__.py, and a test of it. Without it the package has no script.fm new.package.workshop-extension <name> --app=<script>adds the branded App:_app.pyand the script<script>, which runs the workshop with the extension's verbs. Without it the package puts nothing onPATH.fm new.package.cpp-package <name> --package-type=<type>writes conan's package type into the recipe'spackage_type, and the CMake target that follows from it: a library static or shared as conan'ssharedoption says forlibrary,STATICorSHAREDforstatic-libraryandshared-library, an interface library over the header forheader-library, and a program with the library its tests link forapplication.
A creation installs nothing. A template needs its own extensions,
those of each template it extends, and the extension that declares each
template of that chain, the base aside. A template has its verb while
the installed set holds the extension that declares it; for any other
template, fm new.package.<template> meets footman's refusal of an
unknown task. Every creation, a template's verb and fm ci.scale
alike, writes the member through one function, and that birth refuses
before it writes anything, in this order:
- A template, or a template it extends, that no installed extension
declares, while the workspace's lists hold an extension no installed
distribution declares yet, refuses naming each such extension and
fm sync, which installs it. - A template that extends one no installed extension declares, while
the part of its chain that resolves needs an extension the
workspace's lists do not hold, refuses naming each with its
distribution: list it in
[workspace] extensionsand runfm sync, then create the package. - A template no installed extension declares refuses, naming the installed templates.
- A template whose
extendsleads back to it, or names a template nobody declares, refuses naming the cycle or the installed templates. - A template that needs an extension the workspace's lists do not
hold refuses, naming each with its distribution: list it in
[workspace] extensionsand runfm sync, then create the package. - A template that needs an extension the lists hold and no installed
distribution declares yet refuses, naming each and
fm sync.
So a workspace whose root lists the stock list creates a
python-library at once, and lists cmake and conan before it
creates a cpp-package: until a list holds conan, which declares the
template, fm new.package.cpp-package does not exist, and with conan
listed and cmake not, it refuses naming cmake. A workspace whose lists
hold no python has no fm new.package.python-library, and its
fm new.package.workshop-extension, whose template lists python and
extends python-library, refuses naming python.
Two extensions declaring one template refuse every birth, naming both.
A package's contract that writes template refuses: the template is
read at the birth alone.
From any directory inside a workspace, a verb resolves the workspace
at the directory that holds the root's workshop.toml: a package's own
contract below it is passed over, and nothing is written into the
package's directory.
An extension's wheel carries its requirements. Each requires target
is a dependency of the wheel, so the resolver holds the two to the
range the wheel states. A target that ships in the same wheel needs
none, since one wheel has one version. The composed dev group lists
each stack distribution once. The conformance kit's
requirements-in-metadata clause judges the wheel's metadata against
the declaration.
The workshop asks two questions about a path, and fm explain <path>
prints both answers with the extension that supplied each. Its
category says what the file is to its package, source, test,
test-support, configuration, and what an extension adds (prose,
example, asset, nav). An extension declares a
pattern table under [categories] in its extension.toml, and a
package takes the tables of the extensions it holds over the base's
own table, which names the documentation's paths and calls the rest
configuration. The most specific pattern wins. Between patterns of
one specificity in two tables, the extension later in composition
order wins: an extension wins over the extensions it requires, and of
two that do not require one another the later in alphabetical order
wins. The base's table comes last. Two patterns of one table at one
specificity that claim one path refuse naming both. A package
reassigns its own paths in its contract, on this axis alone:
Its channel says who wrote the file and where to edit it,
answered by ranked rules an extension may add to. The workspace root is a
unit of its own, with notes/, the site's files and README.md
categorised beside its tests, and a src/ at the root refuses in
layering.graph, since the root is never a package. A CI job may
declare the files its entries read as inputs, the table a step
declares: a pull request's run that changed none of them, nor the
sources of the extension that contributed the job, skips the job's
entries with a line saying so. The docs extension's gate job reads the
workspace's docs/, zensical.toml and README.md and each package's
pages, nav, assets, examples and generated pages, so a pull request
that changes only notes/ skips the site build, and fm explain
prints claimed by: gate/docs on a file the build reads. On a
contract it also names the schema the contract is judged by, and the
owners whose keys that schema holds.
A step also says what its tool needs of the workspace. Its tools
reach the tool profile while a package it judges exists, each
requirement naming step <name> as its site, so unregistering a
step removes its tool. What the base template leaves to the listed
extensions, they answer through workspace-level queries: the dev
dependency group's tool lines and the docs dependency group's lines are
the union of the answers in composition order, and a rendered template
reads any workspace-level query by its name, queries['python.dev-group'],
an extension's own declared query included: the pytest extension's
template reads the words other extensions add to its addopts from
queries['python.test.addopts']. The docs extension answers
python.docs-group with zensical, the site's builder, and the
mkdocstrings extension with its python handler, so a workspace that
lists neither composes an empty docs group.
The documentation site is an extension of its own,
livery-extensions-docs, listed as docs. It owns the site's
assembly, the docs verbs, the docs.config, docs.members and
docs.theme queries, and the docs phase every docs verb runs before
it assembles the site's config and the deploy phase fm docs.publish
runs on the built site, and it arrives through its own task entry
point. A package's [docs] table is the extension's whole, so it
refuses, naming docs, while the workspace does not list the extension.
The base reads no [docs] table and imports no extension, which
layering.base-imports-no-extension enforces.
The python API reference is an extension of its own,
livery-extensions-mkdocstrings, listed as mkdocstrings; it requires
docs. Its step of the docs phase writes each python package's reference
into the package's generated tree, a page per module and the api nav
block that lists them, and it answers docs.config with the python
handler's tables. It also holds the two lint steps that judge the
docstrings the reference publishes, lint.docrefs and
lint.docstrings. A workspace that does not list it renders no API
reference and installs no mkdocstrings.
The coverage extension, livery-extensions-coverage, adds a step to
each of the docs extension's two phases in its [for.docs] table,
which draws the coverage pages of each package whose [docs] coverage
names an htmlcov report.
A step is named by its phase and its own name, test.pytest for the
step pytest of the phase test, and that name is everything a
person types: a phase's verb runs its steps and each step is a
sub-task of it, generated from the registry. fm test runs every
step of the test phase and fm test.pytest the one, over the named
paths or the workspace. A verb offers exactly the flags its steps
read: --fix and --safe-fix where a step can fix, --point where
one selects tests by CI point, so fm test --point=nightly runs the
nightly's tests and fm test.ctest offers no point at all, and
--shard where one runs its share of a sharded check leg. A phase
whose verb already exists is served by it: fm provenance is the
provenance phase's verb.
A step's own verb hands the tool it wraps the words after --:
fm test.pytest packages/strongroom -- -k slow runs that package's
suite with pytest's -k slow, and fm lint.ruff -- --statistics gives
ruff its flag. The words before -- stay paths. A phase's verb runs
several tools, so it refuses words after -- and names the steps'
own verbs that take them; fm check refuses them the same way. A
step that wraps no tool, such as fm drift.check, refuses them too.
A step says it takes them with {arguments} in its template, or by
naming tools when it runs code, and its code reads them from the
context's arguments: cmake's build.configure names cmake, so
fm build.configure -- -DACME_FAST=ON hands cmake its flag.
A step's options are what a package may set in its own contract,
each with a type and a default; every step carries enabled, and
pytest's test step carries parallel. The step's own table reaches
them, and a phase's table reaches every step of the phase:
[phases.typecomplete.basedpyright] # the step, as the gate names it
enabled = false # skipped by name in the gate's output
[phases.test] # every step of the phase, whatever its tool
parallel = false # the suites run under -n 0, each in a run of its own
The deeper table wins key by key: the phase's table, then the step's. An option no step the table reaches declares, a step or phase no registered step has, and a value of the wrong type each refuse, naming the vocabulary.
An extension's steps and categories are judged by the conformance kit,
livery.workshop.testing: a Subject names the extension, the sets of
extensions to probe it with, each as the list a package writes, and
the steps it registers; each clause in CLAUSES returns
the violations the subject commits, each naming its clause, and an
extension's own suite runs every clause on its subject. The clauses so
far: a per-package configuration file has one owner among the steps
whose fragments name an extension; a path's
category is the most specific rule's, the nearer table winning a tie
between tables and two rules of one table never tying; every step a
step runs after is registered or declared by an installed extension,
and following them never leads back to it; an extension's
extension.toml, read under the name its distribution lists it by as
the mount reads it, holds only declared keys, each of its type, and
every reference in it names a function its module defines; importing a module a reference names registers nothing, which
the kit proves by importing each in a process of its own; every task a
CI job's entries name is one the extension defines, read from its
sources; every category a step's claims name is one the workshop
knows, every suffix starting with a dot; the plugin an
extension.toml names is an installed footman.tasks entry point;
an extension.toml carries an [extension] description, and every
verb its plugin defines and every contract key, template, template
option, step option and environment variable it declares carries its doc line, each one missing named
(declaration-documented); every extension a template lists composes something in a package, unless
another it lists requires it, and the set of the template's list holds
every extension the template's chain needs (template-composes); a step's
fragments render with the kit's probe answers, the
composed pyproject.toml still parses, and a per-package file matches
its render until a person edits it, when the drift gate names it; and
once a step is withdrawn and no other step renders its per-package
file for the package's extensions, an unedited copy is removed and an
edited one kept;
and in the gate's walk over a probe workspace holding one package of
each set, with the step bodies recording instead of running, every
step of a phase the gate runs that can fix rewrites before any judge
starts and is not judged again, every such step names the extension
that registered it by the name a workspace lists it under, which the
gate prints, and a step with no file to read is named and never
started. The workshop's own steps pass the same clauses in its test
suite, probed with a package that lists nothing and one listing each
installed extension that composes something in a package.
An extension composes something in a package when it, or an
extension it requires, declares a step in a package-level phase, an
answer to a package-level query or [categories], at its top level or
in a [for.<target>] table, or when a step of any installed extension
names it in extensions, itself or through a per-package fragment.
The installed declarations decide it alone: code that reads a
package's set is not seen. Workspace-level steps and answers, contract
keys, tools, shipped files, CI jobs, verbs and templates compose
nothing in a package. Of the extensions the livery distributions
ship, cmake, conan, cpp, nanobind and python compose, and the others
do not. For an installed extension no list names, fm doctor names
a package's extensions beside [workspace] extensions when it
composes.
A package's list takes only an extension that composes something in
a package, itself or through an extension it requires. layering.graph
names any other entry, says what the extension does instead, such as
"its steps judge every package that holds python or conan", and points
to [workspace] extensions. Its --fix moves the entry to the root's
list with its comment lines and writes both lists in their canonical
form. An entry another entry of the list requires is left out of the
canonical list instead, and is not moved. A template's list follows the
same rule: a template's verb refuses to create a package from a template
that lists such an extension, or extends one that does, before it writes
anything. Because the proof reads
declarations alone, an extension whose only effect on a package lives
in its code, such as a workspace answer that varies with which
packages list it, is refused in a package's list and is listed in
[workspace] extensions instead.
Every extension lives under livery.extensions, a namespace any
distribution can add an extension to.
A task's name links to its page through a URL template. A workspace
sets one in [workspace] docs-url, which the base's own hook hands to
footman: {path} is the task's address joined by slashes, {slug}
joined by dashes. That key comes before the docs extension's links
under its site-url, and footman's own configured docs-url before
both.
An extension contributes CI jobs in its extension.toml, as the docs
extension declares the gate point's docs job in [ci.jobs.gate.docs].
A workspace that does not list the extension renders no such job. A
contributed job sits before the first job of its point that waits for
it, else before the point's verdict job, else last. A table naming a
job the point already has, declared, inherited or contributed, joins
it instead of adding one; a join's needs join the needs of a job the
point has of its own, and a join of a job the point inherits names
none. A join of a point's own verdict job may name judges, tasks that
judge the run: they run before the job collects the run's rows, and a
red one stops the job before the verdict and the stamp, as a red
builtin entry does; judges on any other job refuses.
The formatter and the linter are an extension with a distribution of
its own, livery-extensions-ruff, listed as ruff. Listed, it
registers format.ruff and lint.ruff, which join the format and
lint phases, and fm sync writes the root ruff.toml they read,
which a bare ruff reads too. A package's own settings go in its own
ruff.toml, which extends the root one with extend = "../../ruff.toml";
its per-file ignores go under [lint.extend-per-file-ignores], because
a per-file-ignores table of its own replaces the workspace's.
Unlisted, the extension registers nothing and writes nothing.
The type checker basedpyright is an extension of its own too,
livery-extensions-basedpyright, listed as basedpyright. Listed, it
registers typecheck.basedpyright, and fm sync writes the root
pyrightconfig.json, which the editor and a bare basedpyright read;
the repository's own settings go in its region at the end. It declares
typecomplete.basedpyright off, and a root contract with
[phases.typecomplete.basedpyright] enabled = true registers it too; it
verifies that each package's public API is type-complete.
fm new.project lists basedpyright, changelog, coverage,
mkdocstrings, pytest, python and ruff, which takes the site's
docs in through mkdocstrings. python is there for the
workspace's own tests and tasks.py: the root's tests hold the root's
set. --extensions names another list, and the birth writes either as
its canonical list.
mypy is an extension of its own as well, livery-extensions-mypy,
listed as mypy. Listed, it registers typecheck.mypy, which checks
linux, darwin and win32 with a cache each under .workshop/.cache/mypy/,
and fm sync writes the root mypy.ini, which a bare mypy reads. A
new project does not list it.
A package's documentation examples are files under docs/examples/,
python files a page shows whole or by named section through the
snippets extension: a fence whose one line is the snippet marker
followed by the quoted repository-relative path of the file, with
pytest extension's examples.pytest step runs each file as one test
through the function the python extension answers
python.examples.runner with, which starts pytest from the workspace
root; a failure reports the example's own file and line. An example is
never a test module: pytest's own collector leaves it alone, named or
not, so a test_* function in it is code a reader sees and never a
test the workspace runs. A run over named files runs the named
examples; a whole walk runs the package's directory. A conftest.py beside the examples is
the package's setup around them, never an example: it reaches every
example item through the example marker, as footman's does to run
each inside a captured registry, and naming it runs every example.
The example category is claimed by the ruff extension's lint.ruff,
for names only, by examples.pytest and by the site; a page's prose reaches the site
build and no test, and an example file reaches the examples step and
the site.
A step record also owns its configuration. Its fragments, one per
rendered file, are what the render writes for it: a [tool.*] table
of the root pyproject.toml, composed in step-name order, which a
step an extension withdraws takes with it. A tool that reads one
file per project gets a file of its own instead, written by its
extension under the name the tool looks for: ruff's ruff.toml,
pytest's pytest.toml and coverage's .coveragerc. A tool that
searches upward from each file, clang-format and clang-tidy in a
C or C++ package, gets a managed file where it looks,
rendered from the fragment of the record whose extensions the
package holds, the first step by name when two have one, and judged
by the drift gate, with a .workshop-rendered receipt beside it so a
withdrawn step's file goes only when nobody edited it and an edited
one is kept as a local override. A package's own lines ride the tool's
inheritance, a deeper file with InheritParentConfig. The editor
follows the same set: .vscode/settings.json takes each record's
lines, and .vscode/extensions.json recommends the extension ids the
records carry and nothing else, with a region for the repository's
own.
A step record also says which files it judges: its claims, named
in categories rather than as globs, each with the rules the step
withholds there and the suffixes it reads. A category names what a
file is for, not its language, so ruff claims a native package's
configuration and reaches its conanfile.py alone, which a scoped
gate hands it by name. fm explain prints the steps whose claims
reach a file, and the per-file ignores in ruff.toml render from the
claims over the tables of the extensions the packages hold, so the
docstring rules stop at the tests of every package without a table
typed by hand.
An extension's prose, its voice, its standards, its rules, is a set of
fragments in sections the base orders: identity, voice, standards,
rules, workflow, gate, verbs, compositions, tools. A fragment is a
file in the extension's content/fragments/ named
<section>.<topic>[.<audience>].md, or a registration with a render
that answers each audience from the registries, and two fragments of
one name refuse at sync naming both files. fm sync delivers the
agent's set flat under .workshop/fragments/, a shipped file byte for
byte and an edited copy kept and named, and writes the entry file from
it in section order, the repository's own fragments/ last. The gate,
verbs, compositions and tools sections render from the registries, so
no fragment names a checker by hand. The verbs section lists the verbs
of the base, of each plugin no extension carries and of the
repository's own tasks file, then gives each extension of the installed
set a block read from its declaration: its description, its verbs with
the first line of each one's help, its templates, its contract keys and
step options with their docs and where each is written, the steps it
declares off with the switch that turns each on, and the installed
extensions it contributes to and those its root entry leaves out with
without, as fm extensions prints them. Listing an extension is the
whole step: the next fm sync delivers its block. The compositions
section names each set of extensions the packages hold, by the
shortest list that composes it, with its packages and the gate phases
that judge them.
Each rule over the sources is a step of the layering phase: the
base's two (the base importing no extension, and the sibling
references, whose fix writes the edges the graph already reaches), and
an extension's own, declared as [phases.layering.<step>] with
main = "module:function", called with the gate's context. The base's
two read each package's references answer, one record per source:
the file, the name other code references it by, each name the source
references, and the names its language's conventions account for. Each
name says whether the source makes the reference at import time or
lazily, inside a function or a method body, and whether only a type
checker makes it or the source runs without it. A record names a file
inside its package, and one extension answers for each file. The
python extension answers for python sources from one parse per gate,
memoised by the file's path, size and modification time, and its own
three steps read the same parse, over the files a narrowed run reaches
or every source: private-reaches, which allows a reach into another
distribution's private name only where the root contract's
[[python.private-reaches]] lists it; runner-terminal, which holds a
module that imports the runner to livery.footman.attended(); and
declared-imports, which holds each import a package's src makes to
the distributions its pyproject.toml declares. The python extension
is a distribution of its own, livery-extensions-python, and its page
describes each step.
A step's fix runs inside the gate's rewrite, before the judges.
The sibling references' fix writes each edge's requirement before the
edge. The package's set answers requirement-writers with its
writers, and test-requirement-writers with those of a test edge's
requirement, and every one is called. Each takes a sibling of its own
ecosystem alone: python writes into pyproject.toml for a sibling that
holds python, and conan writes into conanfile.py for a conan package,
a sibling that holds conan and whose recipe names a reference. Conan
opens the recipe's requires tuple when the recipe declares no
requirement. A sibling no writer takes refuses, naming the sibling's
set, and nothing is written. A requirement written into a member's
pyproject.toml moves the uv lock, so the fix locks again, and the
fix's judge reads the contracts as the fix left them.
layering.graph judges each edge of a contract against the package's
manifests. A build or runtime edge is a requirement, at the edge's
floor, and a requirement on a sibling is an edge. A test edge is a
test requirement, at the edge's floor, in a package whose set answers
test-requirements; python answers it with the test extra of
[project.optional-dependencies], which the release's isolated leg
installs the wheel with. The fix of layering.graph writes each test
requirement that is missing or names another floor, through the
writers the set answers test-requirement-writers with, and locks
again when a member's pyproject.toml moved. A test edge in a set
that answers no test-requirements, and a tool edge, have no home in
a manifest, and nothing judges them there.
Each extension may carry a content/ directory; fm sync delivers it:
guidance fragments into .workshop/fragments/, skills and hooks into
.claude/ as links (a local override is kept and named), and the
managed CLAUDE.md stub whose imports end at the instance's own
CLAUDE.project.md.
An extension's fragment can write a root file only while a member
needs it. The conan extension, a distribution of its own,
livery-extensions-conan, writes conanws.yml at the root while a
member's set holds conan, listing each such member by its path, and
removes the file with the last of them. Its page describes the file.
A composed file is the extensions', judged byte for byte, and some of
them carry lines of your own. Those lines live in a region: a pair of
marker comments the composition writes, such as
# -- workshop: region tables, yours to edit; the render keeps it --
and # -- workshop: end tables --. fm sync reads what stands
between the markers from the committed file and writes it back in
place, so it keeps your lines and fm drift still compares the whole
file: an edit inside a region is yours, an edit outside it is drift,
and a removed marker is drift too. The root
pyproject.toml carries a tables region for your own tables, as
does the root ruff.toml; the root .gitignore carries a rules
region, .vscode/settings.json a settings region, tasks.py a
tasks region below the mount, and the changelog extension's
cliff.toml in each package an own region. fm explain <file> names a
file's regions and their lines. A managed file whose format has no
comments keeps your lines as a tail after the lines the render owns.
The variables an extension declares¶
An extension declares each environment variable it needs in an
[env.<NAME>] table of its extension.toml. The conan extension
declares its home:
[env.CONAN_HOME]
value = "{place}/conan"
always = true
doc = "conan's cache takes one writer at a time, so each CI job, loop pass and scale fixture keeps a home of its own"
value and doc are required, and always is false when absent.
The value takes the placeholder grammar of a step in words and
answers one placeholder, {place}: a directory of the variable's
own. Every other brace form refuses when the declaration is read,
{UPPER} and {env.HOME} among them, naming the form, so a
placeholder added later changes the meaning of no declared value. A
name a shell cannot export refuses too. A [for.<target>] table
declares no variable, and two extensions that declare one variable
refuse, naming both.
always makes the extension's value beat one the runner sets for
every job, where the job's environment is formed: in setup.sh and in
fm env.emit --github. A loop pass and the scale fixture form the
environment of what they start the same way. Everywhere else, every
fm run among them, the environment wins: a variable it already
carries keeps its value, as the cascade's variables do. So a job's
later runs keep the value its entry placed, and a nested run keeps the
one its parent set.
The workshop sets the variables the extensions of the workspace's
installed set declare, and each place names the directory {place}
stands for:
| Where | {place} |
|---|---|
every fm run, through the cascade's hook, where the environment carries no value |
on a CI job, the job's own directory: RUNNER_TEMP on a GitHub or Gitea job, .workshop under CI_PROJECT_DIR on a GitLab one; on a desk, none |
setup.sh, for the steps before fm |
the same directory; the script stops a job whose runner names none |
fm env.emit --github, which persists them for a job's later steps |
RUNNER_TEMP; a job without one refuses |
a pass of the loop, fm ci.e2e |
the directory of the development environment the pass runs on |
the scale fixture, fm ci.scale |
the fixture's directory |
A value naming {place} is not set where nothing names a directory,
so on a desk conan's own default home stands.
The tools a workspace requires¶
Six sites declare tool requirements, each in the one requirement
grammar, name?>=floor@scope: ruff, ruff>=0.16,
dotnet_coverage@windows, tea>=1.1@linux,macos-arm. A scope names
platforms (every locked host of one) or host keys, each excluded with a
leading !, so tea@!windows-arm is every locked host but one. ?
marks a tool optional: the lock takes it where the catalogue can serve
it and never refuses it, its entry says optional, and what it left
out is printed when the lock is written; fm toolroom.sync names an
optional tool its host lacks. The sites: the base, in its contract
file's [toolroom] requires, for uv, which makes the venv every step
runs in, so a workspace with no package requires it too; the steps that
judge a present package, each naming its tools, which is how ruff,
pytest and the checkers reach a python workspace; a listed extension,
the workspace's or one a package's set holds, as [toolroom] requires
in its extension.toml, for the tools it runs, which is how cmake
brings cmake and ninja, conan brings conan, and nanobind brings cmake,
ninja, conan and the cmake-conan provider, and in a [for.<target>]
table, for what it needs while that table applies; a plugin the project
mounts through its direct dependencies, as a tuple in a data module its
workshop.tools entry point names under the plugin's own name, loaded
without the plugin's tasks, which is how forge's dev verbs bring
docker?; a package instance, in its workshop.toml under
[toolroom] requires, for what its extensions cannot know; and the
project, in the root contract's [toolroom] requires, for what belongs
to the repository. The root contract's [toolroom] index names where the
catalogue is read from, the published index's URL or a directory
holding the index or the records that build one. The repository that
authors the records reads them directly.
[workspace] hosts names the hosts the workspace supports, in the
scope tokens a requirement takes after @: a platform (macos), a
host key (linux-arm), and either with ! to remove it. Without the
key every host key is supported. The lock covers every supported host,
so a requirement without a scope must resolve on all of them. fm
sync on another host says so once; in CI, and from fm toolroom.add, it
refuses, naming the host and the supported set.
uv's cache is one per machine and grows with every environment synced,
a loop's births included: fm doctor measures it against
[workspace] uv-cache-limit, 10G when unset, and fm doctor --fix runs
uv cache prune when it is over. A machine that needs a larger cache
raises the limit in workshop.toml.
fm toolroom.lock resolves every site's requirements against the
catalogue and writes toolroom.lock at the root: one version per tool for
the whole repository, the newest that satisfies every floor and
resolves on every host the tool is required on, refusing by name
otherwise. A tool required on some of the locked hosts alone is
locked on those, its entry names them, and a scope no locked host
matches locks nothing, which the lock says per requirement. fm
toolroom.add <requirement> declares a tool at the project site, locks it
and materialises it; fm toolroom.lock --upgrade-tool=<tool> moves one entry to the
newest eligible version, and every package with it, since no package
runs a version of its own.
Entering the environment materialises the bundle the sites require:
fm sync supplies every tool locked for this host through the
machine's store, skipping one locked for other hosts alone, the
downloaded kinds from the catalogue's deployment for this host through
[toolroom] sources (folders or URLs in the store's layout, consulted
before the origin) and the delegated kinds through their installer, in
one of three modes per tool: link puts its entry points in the
checkout's .workshop/bin, path its own directories on PATH, none
neither, for a tool reached only through a typed handle or its env.
A download with paths takes path, one with none and a system tool
take none, unless the record or the root contract's [toolroom] modes
says otherwise; every installer's kind takes path. A system tool is the machine's own: the store installs
nothing for it and holds the copy on PATH to the highest of the
record's floor and the sites' floors, naming the site whose floor it
is under. A tool named in the root contract's [toolroom] host-allowed
may be served by a copy already on the machine: fm sync looks on PATH
first, and a copy that satisfies the
floor (the requirement's, else the record's minimum, else any
version) serves with nothing installed, while one that is absent or
below the floor is passed over with a note and the locked version
serves. A tool a step reads its verdict from (format, lint,
typecheck, typecomplete, test), uv, and a tool an extension writes
the release notes with take no allowance, and the lock refuses one
by name: a linter that varies by machine makes the gate disagree with
CI, and a release's entries must not depend on the machine. The lock's entry carries
allow-host, so every checkout agrees on which tools may vary. Each
tool leaves a receipt under .workshop/receipts/, this checkout's
statement of what it installed: the exact version, the host, the
deployment's digest and what reached PATH, and for a host-served
tool source: host with the version its copy printed, as the release
train's receipt is a release's statement. fm env.emit carries the
receipts' paths and variables, and fm env.check names each required
tool's receipt and the drift when the lock's deployment has moved
under it, a tool with no receipt that still resolves from PATH being
named and not a problem. fm enters the environment for itself as
well: every invocation applies the same PATH entries and variables to
its own process before any task runs, so the locked tools resolve from
any shell, an agent's, a CI step's or a bare terminal's, and an entered
shell adds only completion. The rendered .vscode/settings.json makes
the editor's integrated terminal an entered shell from its first
prompt, one profile per platform. A sync whose first act moved the checkout hands the rest to a
fresh process on the code now on disk, since the modules it loaded
are the old code; a re-run that cannot start is named and the sync
continues on the loaded code. A sync whose uv sync moved or removed
the distribution of the workshop, or of an extension it mounted, hands
the rest over the same way, before anything reads it again: the lock
can replace an index's wheel with an editable member at another path,
and this process found the workshop's own files or the extension where
the wheel was. There a re-run that cannot start refuses, and the next
fm sync completes.
The stubs the four type checkers read are materialised too. fm
toolroom.restub writes them into typings/ at the root, pyright's
default stub path and a search path the rendered configuration hands
mypy, ty and pyrefly: one stub per tool the lock holds, at the locked
version, as livery.toolroom.stubs modules with livery.toolroom.handles
beside them declaring the handles for the installed tools package's
index to import, under the namespace package and never inside the tools
package's own directory; a tool the
workspace does not deploy gets no stub. fm sync, the lock verbs
and the entry script write them as well, so a checkout and a CI runner
type against the same stubs. The store renders each stub from the
locked version's own surface, from the records or the index, so no
source holds a stub; a receipt under .workshop/state/ names the lock and
the source the last write rendered from, and while both stand nothing
is read or written. fm env.check counts them and names their
absence.
The task surface¶
fm check: format, lint, four gating type checkers, public-API type-completeness, the tests with per-package coverage floors, and the render gate. Type-completeness covers what each root declares in its__init__; a namespace root, one with no__init__, declares nothing. A public package beneath a root keeps its own import path and is declared in the root's__init__as well, imported underTYPE_CHECKINGand listed in__all__, and the verifier follows the declaration into it;py.typedsits at the distribution's root. Every gate walks the step registry the same way, whole or narrowed, on a machine or on a leg, through the one walk every phase runs through: under--fixevery fixer that applies rewrites first, one at a time, then every judge runs in one parallel block, each a footman step, the steps a judge runs after among them, a step that rewrote not judged again; a step whose claims reach no file of its scope is named and no process starts for it.fm check <paths>checks exactly those files, or a directory's: every step whose claims reach one of them runs over them alone, and nothing is recorded as proved;--safe-fixfixes without removing code, the post-edit hook's mode;--pointselects a CI point's tests. A named path that is no file or directory in the workspace refuses, since checking nothing there would pass; the steps pass nothing through to a tool, so a tool's own arguments after--refuse the same way.--shard=<i>of<n>runs one shard of a sharded check leg: a step that declaresshardamong its flags runs on every shard and runs its share, and every other step runs whole on the first shard alone, so a shard other than the first leaves those steps out and prints one line for each,<phase>.<step>: left to the first shard (this leg is <i>of<n>). On the first shard every step runs and nothing is printed. Inside CI the leg's label ends in the shard,check-ubuntu-latest-3.14-2of3, so the legs pass no flag. A sharded run on a machine records no tree as proved, since a share of the gate ran; a shard outside the form,0of2, refuses naming it. On a machine the gate is the reflex: it runs what the working tree changed since the nearest tree this checkout's own green gates proved (the one with the fewest changed paths, a green check of the dirty tree included), the packages that delta can influence (their dependents' closure over the[[depends]]graph), and records the working tree as proved, so the tenth commit of a branch pays for what the tenth commit touched and a tree the record already proves runs nothing;--fullruns everything. A delta confined to a package's test files runs the package's whole suite and no dependent's, since nothing imports a test, after the package's gate build when its tests run on a build (a C++ package's ctest); a changed conftest or helper, and a source change, run the suite and its dependents'. A suite is never narrowed to the changed test files: the tests a change reaches are more than the ones it edits. A change inside a package reaches further when a listed extension says so through thereachesquery: while pytest is listed, python widens a change to a module pytest loads as a plugin to every member pytest runs over. The gate prints one line for each path an answer widens, with why, and runs everything when an answer raises. A machine's test run sets the runner's variables, so a test that reads them is judged here as on the legs. The chain of records rests on a full gate here or on the nearest tree in HEAD's history that CI's record holds: a fresh branch off main starts proved, and one cut before main's own run is green pays for that merge's changes in its first step. A change outside the packages runs everything and roots a new chain, with exceptions. Prose and the site's own files, a file undernotes/, a markdown file anywhere, the rootdocs/tree, or the rootzensical.toml, affect no package, and neither do the root files no package's steps read: the licence, the CI files and the code-owners file, the editor's and the agent's settings, git's own files,setup.sh, the release's member list,overrides/, and the render's receipt. A change that adds or removes a package is that package's: the entries naming it in the root files, and the lock's entries it moves, reach it alone. The workspace's owntests/directory is a unit of its own, which holds the root's set: a change under it formats, lints, type-checks, and runs those tests alone, by the steps whose extensions the root's set holds, and the record supplies every package's suite. A root whose set holds no python runs none of its own tests, and the test step prints a line saying why. Each workspace step runs when a file it reads changed, and judges those files:lint.doclinksthe changed pages, and every page when a file is deleted or moved or a heading is removed;lint.docrefsthe cross-references in every docstring the site renders, against the anchors the site renders, when a source, an authored page, a contract, an extension's declaration or a manifest changed;layering.graphonly when a contract or a manifest changed; the layering phase's rule steps the changed sources, and every one when the graph changed;drift.checka tracked composed or generated file when it, or what it is made from, changed;provenance.checkthe changed content files. A step whose own code changed reads everything. A diff that reaches no package and no file a step reads runs nothing. A workspace that declares[ci] affected-legs = truehas its CI check legs run that scoped gate, measured by the same rule from CI's own record: from the proved tree nearest the checkout's, or from the merge base with the pull request's base branch when the record proves none. A push to main whose tree no run proved measures the same way from the previous push's tree, and pays the whole gate when the record proves none in reach, since on main the merge base is the push itself. A pull request's run on GitHub tests the merge of its head onto the base branch, so its row names the two commits merged, and the next push's run rebuilds that merge and gates only what changed since it. The workspace steps are selected the same way, and the gate job after a green verdict stamps the tree it proved on theworkshop/verifiedrecord, naming the check legs that ran, so a later run of the same tree, such as main's run after a squash of a branch on its tip, skips the gate in seconds on every leg whose platform the entry names. An entry proves its tree for those platforms alone: after a pull request's run on one platform, the merge's run ends that platform's leg at once, runs the whole gate on the others, and its stamp names every platform. A narrowed run stamps too when the tree it narrowed against is on the record in full: every package it skipped is byte-identical to that base tree's, so their verdicts carry over, and the row names the base. Without such a base a narrowed run stamps nothing. The release train reads the same record before it waits on main's run.-
fm <phase>andfm <phase>.<step>: one phase's steps, or one step, generated from the step registry and run over the named paths or the workspace the wayfm check <paths>runs them, with nothing recorded as proved; each offers exactly the flags its steps read.fm test.pytest packages/strongroomruns one package's suite, andfm test.pytest packages/strongroom -- -k slowhands pytest the words after--. -
The check legs run on every runner the contract names, with the newest Python of a derived matrix; the nightly point runs the whole matrix, floor included, so the floor's legs cost runner minutes at night and no pull request time, and a floor-only failure reaches a person the next morning. A declared
[ci] python-versionsruns at the gate as declared. On a Windows leg of a GitHub-shaped workspace the entry pointsTEMPandTMPunder the runner's own temp: the hosted runners keep the workspace, the uv cache, and that temp on the fast working drive and the system temp on the slow system drive, so the tests' files and the environments they build share the drive with the cache and uv links instead of copying.[ci] windows-temp = "system"leaves the system temp, for a runner without a separate working drive;"runner"asks for the move on any forge. - A pull request's check legs run on the runners
[ci] pull-request-runnersnames, the first runner[ci] runnersnames when the key is absent; a push to main, a dispatch and the nightly run every runner[ci] runnersnames. A one-runner pull request carries the other legs' coverage rows from main's record, so a package whose floor needs the platform legs' fresh rows on a pull request lists every runner, as the workshop's own repository does. The rendered gate workflow carries both lists as literals and alegsjob picks one by the event, computing nothing. A pull request that changes a line only another platform reaches is red by name on a narrowed run:fm submit --every-runnerlabels itci:every-runnerthrough the forge, the label starts a run (the workflow runs onlabeled), and thelegsjob takes the full list while the label is there. A person sets the same label on the forge by hand. The repository's configuration creates the label (fm workflow.configure), and the coverage union expects every leg from a labelled pull request. - A runner's check leg runs as the shards the contract gives it.
[ci] shardsmaps a runner label to a count, one for a runner it does not name, soshards = { "windows-latest" = 4 }splits the Windows leg intocheck-windows-latest-3.14-1of4to4of4and leaves every other runner one leg;[ci] pull-request-shardsholds the counts for a pull request's legs, judged against its runners, and[ci] shardsapplies when it is absent;[ci] shards-maxcaps every count, 4 when absent. The keys hold the counts the check legs' shard list is derived from:livery.workshop.check_shardsnames the gate's shard legs andlivery.workshop.pull_request_shardsa pull request's, and a key that names a runner the runner lists do not hold, a count below 1 or above the cap, or one that is not a whole number, refuses naming the key and the runner. A shard's label is its platform leg,check-<os>-<python>, with-<i>of<n>at the end; the platform leg keys every record below the gate job's fold.fm ci.run --shard=<i>of<n>runs one shard of a leg: the shard ends the label every entry reads inWORKSHOP_LEGand the job's display name,check (<os>, <python>, <i>of<n>), which the forge lists the job by, and thecheckentry runsfm check --shard=<i>of<n>. A leg that runs as one shard of one carries no shard in its label or its display name, and itscheckentry runsfm checkbare. Each shard partitions the run's items, the test files of its test step, by the platform leg'sdurationsrows: longest first, each item into the shard with the least summed seconds, ties by name, an item no row names at the row's median, the first shard's sum starting at the rows' head, the time of the steps only it runs, so every shard of a run computes the same partition and every item lands in exactly one shard. The rendered check job carries the shards as literals. On GitHub and Gitea, while every count is one, its matrix is theosandpythonlists; when any count is above one it isincludeentries, one per runner, Python and shard in that order, each{os, python, shard}with the shard spelled<i>of<n>; a runner with one shard has its entry without the shard key, and the one call passes--shard="${{ matrix.shard }}", which reaches that runner's leg empty and runs it as one shard of one. The forge names each job by the entry's values in order,check (windows-latest, 3.14, 2of4), and a one-shard runner's as the unsplit leg,check (ubuntu-latest, 3.14), the name its rows are keyed by. When a pull request's runners or counts differ from every other event's, alegsjob holds both matrices as literals, the event picks one, and the check job reads it withfromJSON; both literals take theincludeshape when any count on either event is above one. On GitLab the one check job runs on the first runner, as that runner's count throughparallel: matrix,SHARDtaking1of2and2of2, and its call passes--shard="$SHARD"; GitLab reads the first runner's count alone, since its one document serves every event. Each shard leaves what it partitioned in.workshop/fm-shard.json, and its one write carries that record in its timing row. The gate job'sci.foldentry, before any judge reads the run's refs, folds each platform's shards into one leg: it refuses, naming the platform, the shards and what differs, unless every shard the matrix produces left a ref with a row and its record, the shards name one scope, one item set, one list of durations rows read under one bound, no item ran in two shards, and the items they ran are together the set they partitioned. The folded ref is keyed by the platform leg: the timing row with the first shard's tasks, every shard's package sums added and seconds per item merged, named by the platform's own display name, and every other file the shards' entries left folded by the extension that leaves it, through theci.foldquery (the coverage extension concatenates its parts per suite). The shards' refs are dropped once the folded ref is put, so a fold that dies midway is re-run as its own recovery. Below the fold the coverage records, the verified stamp, the speed marks and the janitor's key set see one leg per platform; the forge's rows of the shards stay in the run'smetricsfile, times alone, andfm ci.timingsprints each shard's wall and queue times under the platform's section. A platform none of whose shards left a record partitioned nothing: the gate skipped on every shard, the tree already proved or nothing affected, or no step that reads the shard ran. Its shards fold on their scopes and files alone and the fold says so; one shard with a record beside one without is red by name. Each record names the attempt of the run the shard ran in, as the runner counts them: a rerun of the failed jobs alone keeps the per-run refs the first attempt's passing shards left, and the shard that reruns partitions afresh from the record as it then is, so the fold reads one platform from two attempts with two partitions. Where the partitions differ and the attempts differ, the refusal names the attempts and says to rerun the whole run;fm ci.rerundoes that by itself whenever the contract splits a check leg, and says so in one line. A run with no sharded platform says so and folds nothing. On GitLab a job run asparallel: matrixis listed ascheck: [<i>of<n>], and the job's display name spells the shard that way. - A check leg's gate runs profiled, so the leg writes a Chrome trace
of every task, step and test it ran, and its timing row is read
from that trace;
[ci] timing, on unless the contract says otherwise, governs the profiled run and the row.[ci] profile, off unless asked, pushes the trace itself to a channel of its own: refs no sync mirrors and no gate reads, so a checkout pays for a trace only when someone asks for one.fm ci.profilethen assembles a whole run into one timeline, and a profiled local command carries the run it caused. See CI profiles for the file, the verbs, and the contract keys. The push is observational: origin refusing it is a printed line and never a leg's verdict. - On a GitHub-shaped workspace every job restores the tool store
before it enters, under the runner's temp, the working drive, where
the checkout and the venv are and where the store's links into the
checkout stay links: the data directory the entry places there,
keyed by
toolroom.lockwith the OS and architecture, falling back to the nearest archive under its prefix, so a moved lock restores what is unchanged and saves a fresh archive at the end. A restored store is a tier the store verifies on access, andfm ci.runsweeps it before the save, so the archive carries the trees the tools run from and not the artifacts they were extracted from. uv's cache is placed on the same drive, so the sync links wheels into the venv instead of copying, and is not cached: the wheels it would hold arrive faster from the index than from an archive. A leg that builds native packages also restores conan's home from the same drive, keyed by the recipes with the OS and architecture and falling back under its prefix, so a third-party package from Conan Center is compiled once per key and downloaded from the cache afterwards; the cache is the speed extension and Conan Center the origin, so a miss costs time, never a red leg. The other lanes cache nothing until they have a cache action. Tests are namespaced by their path (pytest's importlib mode, set in the pytest extension'spytest.toml), so two packages may share a test file's name; a helper module in a package'stests/carries the package's name, and the session refuses to start otherwise. - Every CI job keeps each variable an extension declares with a
directory of its own, an
[env]value naming{place}, in the job's own directory. A declaration withalwaysbeats a value the runner sets for its jobs where the entry forms the job's environment, as conan'sCONAN_HOMEdoes, and the job's later runs keep it: conan's cache takes one process at a time, and a runner that takes several jobs at once would otherwise have two of them write one cache. On a GitHub or Gitea runner the directory isRUNNER_TEMP, the job's temporary directory, placed bysetup.sh github. On a GitLab runner it is.workshopunderCI_PROJECT_DIR, the job's checkout, placed bysource setup.sh gitlab: GitLab clones each of the jobs that run at the same time into its own path, and git ignores.workshop/. The entry places the variables before its sync builds a native member, and refuses a job whose runner does not set that variable or names a directory that does not exist, naming the declared variable and the extension that declares it. fm start: open the work. An issue number assigns and branches<kind>/<number>-<slug>, a quoted title files the issue first, and<kind>/<slug>starts a branch that belongs to no issue, whose submit closes nothing. Every form branches from a fetchedorigin/maininto a worktree under the runner's home, provisioned and entered when a person is at the terminal: where the shell hook is installed the worktree is entered in that shell, with its environment loaded and nothing to leave, and without the hook a child shell opens there instead (--open=codeopens the editor,--open=noneprints the path);--no-worktreereuses this checkout.fm commit <type> "<subject>": a conventional commit on a proved tree. It stages the change (--onlynarrows), derives the scope from the packages the change touches, runs the affected gate first in its fix mode (--no-checkskips), validates the subject the wayfm submitvalidates a title, and refuses onmainand on a reserved branch. A package whose only changes are the files the engine composes into it stays out of the scope: a template's change renders into every package, and its scope is the template's owner.git commitkeeps working.fm integrate: bringorigin/maininto the branch by merge. A merge rewrites nothing, so every other copy of the branch stays valid, and the squash erases it at landing; a conflict stops with git's own words. When the merge moveduv.lock, the root manifest, or a member's, the verb matches the environment to it and names what moved, so the next gate runs on the merged environment. Every command makes that check before it runs: the venv follows the lock and the manifests, and one that drifted is synced, then the command runs again on the installed code.fm submit: get the branch onto the remote, verified. Its local gate is the reflex; when the chain of this machine's green gates proves HEAD's tree, back to a full gate here or a tree in HEAD's history that CI's record holds, it skips the gate and names the chain, from a record in the checkout's git directory that never leaves the machine. A row proves its tree for a week: the tree id covers the pins, not the machine's tools.--armedlets it land,--fixheals mechanical gate findings into the branch, and the follow classifies the verdict with stable exit codes; a follow that sees the merge from a linked worktree removes the tree and its branch, naming the directory to go to, and keeps a tree holding something the merge did not take.--no-closesubmits without the close footer, for preparatory work the merge must leave open; a pull request already green when--armedasks is merged directly, since a forge that arms only a blocked pull request refuses.fm submit.merge [pr]lands a green, deliberately-unarmed PR;fm submit.arm [pr]arms one the way--armeddoes, andfm submit.disarm [pr]takes arming off and leaves the PR open. The three act on this branch's PR, or on the one numbered (123or#123) from any checkout. A merged PR is done forsubmit.armandsubmit.merge, which say so and succeed, and too late forsubmit.disarm, which refuses; a PR closed without merging refuses in all three.fm abandon [branch]gives a feature up, this one or a named one, its worktree with it.fm statusandfm ci.*stand beside them, all on livery-forge.fm doctoris footman's; the workshop registers its forge and host checks with it, so one verb reports the runner, the forge and the machine.fm driftkeeps the composed and generated files byte-identical to what the listed extensions and the contract write, and namesfm syncas the remedy;fm new.package.<template> <name>creates a member from an installed template and wires it in.fm release.prepareandfm release.check-tagrun the path-tag train (packages/<pkg>/v<semver>); a workshop release also publishes the template snapshot, tagged in lockstep.fm release.verifytests a member's released version from the index against its own tests at the release tag.fm janitorsweeps the runner's directories and the state store: footman's cache, then what the workshop leaves in the data directory (the worktrees of closed issues and merged branches, whichfm startsweeps first, the checkout's local branches whose pull request merged, and files and folders no code writes any more), then every series the workshop keeps, in the scope the run has: the checkout's local series on a machine, the remote series too inside CI, where the merge point's gate job runs it after every green run. Windows are enforced, aged rows and orphaned refs go, anything holding work stays and is named, the config directory is reported and never touched, and--dry-runsays what would go. The same work runs wherever it is called from: what is safe to remove is decided by the rule that proves it, never by who is watching.fm updatebrings an instance up to date: floors to the latest released tags, content, render, then the submit flow. Nothing changed means nothing happens.
Where a test runs¶
A test declares the CI points it runs at. Without a marker it runs
at the default points, the gate (a pull request's legs) and the
merge (main's run). @pytest.mark.only_at("nightly") runs it at the
named points and nowhere else; @pytest.mark.also_at("release")
adds points to the default ones. The job runner names the point to
every child it spawns, and the workshop's pytest plugin deselects
the rest; a local fm check selects for the gate, and
fm test --point=nightly selects for a point on demand.
A [[ci.schedule]] entry in workshop.toml attaches a task to a
point's job; every = "1w" or "2w" runs it on Mondays, or on the
Monday of an even ISO week, and any other run of the point skips it
naming the day it runs next. On Windows, a test whose child exits with
STATUS_CONTROL_C_EXIT, the status a console control event leaves,
gets a section in its failure report: the command, the process and
its worker, the run, every control event the process itself saw, and
every process attached to the console, so one sighting carries what
the next reader needs.
The nightly point runs the whole check with its own tests selected
in, and never skips on the verified record or narrows.
fm ci.dispatch --point=nightly starts the nightly now, on main
unless --ref names another, and follows the run to its verdict.
The run it follows is its own: the one the forge's answer names.
A forge whose answer names no run (a GitHub or Gitea server without
the run's details) leaves it the one dispatched run of that ref, at
the commit origin names for it, that appeared after the dispatch. A
run of another ref is never followed. When two such runs appear, as
when two dispatches on one ref start together, it refuses and names
both. When none appears within a minute, it says so, names the
dispatched runs of other refs or commits that did, and exits 14.
fm ci.status --point=nightly and fm ci.logs --point=nightly read
the newest nightly run by workflow rather than by commit, so a
failure only the nightly meets reaches a person through fm.
--only names the scheduled tasks a dispatched nightly runs,
comma-separated, and the run skips every other entry, the doctor and
the check among them, saying so; a name the nightly does not run
refuses before anything is dispatched. A rehearsal of a branch runs the
loop alone: fm ci.dispatch --point=nightly --ref=<branch> --only=ci.e2e.
A tool refresh asked to submit observes nothing off the default branch,
since it submits from the default branch alone; the balancer asked to
submit does the same.
A package contributes a point of its own with [[ci.point]] in its
workshop.toml: name (a workflow file name and a job name at once),
task, and optionally args, every, runners (the root contract's
when absent) and pythons (the newest gate Python when absent). The
point runs on the clock and by hand, one job on those runners and
Pythons calling the task through fm ci.run, with the job token and
nothing more: a permission, a secret or an environment in the table
refuses, as does a builtin name, a name two packages claim, a cadence
that is not one, or a task no extension mounts. Removing the package
removes its workflow: fm drift reports the file as retired and
fm sync deletes it.
On GitLab the clock is a pipeline schedule, a project setting rather
than a line in the pipeline document: fm workflow.configure creates
one per point that runs on the clock, named workshop: <point>, and
deletes the ones it named for points no longer declared. GitHub and
Gitea keep the clock in the workflow file and reconcile nothing.
fm ci.dispatch --point=gate starts the gate the same way. A
dispatched gate is the full gate: the check verb reads the event and
narrows on a pull request alone, and it sets the verified record
aside as the nightly does, so a dispatch proves the tree it checks
out whatever the record already says. The shell spells one call on
every event; nothing passes --full.
Coverage floors¶
Each package's coverage floor is an extension of its own,
livery-extensions-coverage, listed as coverage. A package states
its policy in the [coverage] table of its workshop.toml, a table the
extension declares, so it refuses, naming coverage, while the workspace
does not list the extension. The extension's entry coverage.leg joins
each check leg and its judge coverage.union joins the gate job, which
judges every package's floor on the union of what every leg measured.
The test extensions measure for it, each through its [for.coverage]
table: pytest the python suites, cmake the native builds. Its page
describes the floors, the record that carries each suite's parts
across runs, and the site's coverage pages.
Test speed¶
The speed marks are off until the contract declares
[ci] speed-marks = true: a hosted runner's test time varies by tens
of seconds between two runs of one tree, so a mark taken from such
runs says nothing about the suite. Declare the key on runners that
keep a steady clock. While the key is absent the gate job drops any
marks left from before, so a later opt-in starts from the recorded
timings alone. On, the gate job judges each check leg's summed
test time per package against a mark on the state store. The mark is the median of the
leg's last five green runs for the package, recorded once five are
seen; it moves down when that median beats it by more than five per
cent, so a suite cannot regress slowly. A run over the mark by more
than fifteen per cent and twenty seconds warns in the gate job's
output, naming the leg's slowest tests and the ones that grew most
against their own medians; the second run over in a row on the
ubuntu leg is red, and the other legs warn only. A new heavy test is
a cost someone chose: fm speed.accept <package> <seconds>
--reason=<why> raises the mark, on the ubuntu leg unless --leg
names another. The marks are judged on the CI legs alone: a
machine's clock is not a leg they were taken on, so fm check on a
machine prints each package's summed time and reads no mark, and
fm speed.judge is unavailable outside CI. fm ci.timings shows
the marks beside the timings.
Balancing the check legs¶
fm ci.balance reads the same timing rows and proposes how many
runners each platform's tests should be split over, so every
platform's check leg ends at about the same time. Per platform, a
runner and a Python, it takes the newest ten rows whose check jobs
ran the full gate and succeeded, folds the shards of one platform
into one reading, and takes the medians of four measures: the fixed
setup F, every step the forge timed except the call; the summed wall
O of the gate steps that are not test steps, which the first shard
alone runs; the summed test time S over every package; and the
parallelism p the test step reached, S over its wall. The first
shard's tests wait about O while those steps run, so its slice is
lighter by the O p seconds of tests they hold back, and the shards
split S + O p evenly. It predicts the leg's wall at n shards as
F + max(O, (S / p + O) / n), the first shard with no tests left at
the floor, and the runner seconds as about n F + S / p + O, and prints
both for every
count up to the cap, [ci] shards-max (4 when absent) or a --max
under it. The slowest platform takes the
largest count whose every added shard saved at least its own setup;
every other platform takes the smallest count whose wall is within
15% of the slowest platform's, or the cap, named. The pull request
counts follow the same rule over the pull request's runners when they
are fewer than [ci] runners names. The proposal prints as the TOML
[ci] shards and [ci] pull-request-shards would hold, with the
predicted wall of the slowest leg beside its wall at one shard. A
platform with fewer than three such rows keeps its count and is
named, and a store that cannot be read prints why and proposes
nothing. Without a flag the verb changes nothing.
fm ci.balance --write rewrites [ci] shards, and [ci]
pull-request-shards when the pull request runners are fewer, in the
root workshop.toml, when a count differs from the contract's and
the predicted wall at the proposed counts differs from the wall at the
contract's counts by more than 10%: the hysteresis, so two readings
that predict about the same wall do not move a count back and forth.
The run wall decides, over [ci] runners; when only the pull
request's counts differ, the pull request wall does. The rewrite
keeps every comment and every other key, writes each table on one
line, leaves a count of one out of a table and removes a table that
would be empty, and adds a key the contract lacks under a one-line
comment; [ci] shards-max is read and never written. It prints what
each key becomes and the wall it read, or why nothing was written: no
platform with enough rows, no count changed, or a wall that moved
less. The workflows carry the counts as literals, so fm sync
renders them next, which the last line says.
fm ci.balance --submit lands the same change for a person to merge:
from origin's default branch alone, and on another branch it names
the branch, writes nothing and exits green, so a nightly dispatched on
a branch skips it. A change that is due goes on the day's branch,
chore/balance-<date>, started in this checkout from a fetched
origin/main; the contract is rewritten, fm sync renders the
workflows at the counts, the change is committed as chore(ci): the
check legs run as <counts> and submitted unarmed, its gate run by the
submit, and the checkout returns to where it was. Origin is asked for
the day's branch before anything in the checkout changes: one holding
these counts means the day's balance is already submitted, and one
holding other counts stops, naming both, for a person to merge or
close its pull request first. Nothing due means no branch and no pull
request. The pull request is never armed: a count change is merged by
hand. This repository's nightly runs it once a day through a
[[ci.schedule]] entry, task = "ci.balance" with args =
["--submit"] and once = true, before the tool refresh. A count can
also be set by hand in the contract; the next write that is due
replaces it.
The runner footprint¶
fm ci.footprint sums the same timing rows into runner-minutes, so a
workspace that inherited a runner matrix sees what it spends. Every
job of every run in the window, or of the newest --since runs, is
counted on one runner label: a check leg on the runner its job name
lists, check (macos-latest, 3.14) or check (windows-latest, 3.14,
2of4), and every other job, the gate job, the docs build and the
release jobs, on the first runner [ci] runners names, where the
workflow places them. The folded row of a platform's shards is not a
job the forge ran and is left out; the shards' own rows carry its
minutes. The verb prints the window, its first and last day and its
span, one line per runner label and kind with the jobs and the
minutes, the total, and the minutes per 30 days from the span, at
least one day. A job without a wall time, still running when the
gate job collected or never started, is counted apart and priced as
nothing. On GitHub, when the repository is public, the same minutes
are also priced at GitHub's published
rates for the standard runners
of a private repository, by the class the label names (ubuntu or
linux, windows, macos), a label of no class named as unpriced, with
the total and the USD per 30 days: a public repository is not billed
for standard runners, and the price says what the matrix would cost
one that is. On another forge, or on a private GitHub repository,
nothing is priced. An empty window fails naming what fills it: the
gate job of a run on the forge writes one row per run.
The state store¶
Every row the workshop keeps across runs is a row of the state
store, which livery-git ships and the workshop builds with its own
policy: JSON files on git refs, refs/workshop/* on the remote and
refs/workshop-local/* in the checkout's git directory. The workshop
declares the series, says who may write (a CI run), which identity
every commit carries (the tools') and which variable a published
listing travels in; the transport, the snapshots and the janitor are
the library's. A default
clone or fetch never downloads the remote namespace, no refspec
names the local one, and every row carries the schema the store
stamped and the time it wrote it. A machine's gate never reaches
origin: fm sync and fm start mirror the remote row series the
workspace declares, metrics, verified, speed/marks and the listed
extensions' own, into refs/workshop-origin/*, one ref per series and
never a keyed family, and stamp the fetch with the names; fm check
reads those series from the mirror alone, so a hung SSH agent cannot
hold the gate. The mirror is what the last sync saw, by design; a
checkout the store was never fetched into reads it as unreachable,
roots its chain on a full gate, and names the sync. A read inside
that gate of any other remote ref, a family's key or a listing of its
keys, fails naming the ref and the mirror's scope, never as an
absence: a verb that needs a family opens a live snapshot. fm store.ls
says which of the two each remote item is. The remote series are written by
CI only, fm coverage.accept and fm speed.accept the exceptions;
a local run reads them and writes only the local ones, which the
checkout's worktrees share and a fresh clone starts without. Only the
wire is a git process: every row is read, and every commit written,
in the checkout's own object store as bytes, so a remote read is one
fetch, a remote write one fetch and one push, a local read or write
none, and a series of three hundred rows costs no more processes than
one of three. A verb that reads several series takes one snapshot of the
remote namespace: one listing of the store's refs and the branches
together, then one fetch of the refs the checkout lacks, and every
read inside answers from the local object store, so fm store.ls
and fm ci.timings cost two round trips. A read inside the snapshot
of a ref the verb did not name brings the ref's key group, every
sibling at its depth, in one fetch, so a loop over a family's keys
costs one round trip; a block opened inside another brings what it
names against the shared listing. The job runner takes one
snapshot for the whole job and publishes it to the entries it runs,
so the gate job lists once for its union, collect, judge, stamp, and
janitor. A write keeps its compare-and-swap on the listed sha, its
push's own report is its verdict, and it records the sha it pushed
for the reads and the entries after it. A check leg writes its
per-run ref once, in its last entry, ci.leg: its timing row and
every file the leg's other entries left for it, the coverage
extension's measured suites among them. The gate job's collect folds
the sections its judges left into the run's row, a number per
package each, which fm ci.timings renders as a trend, and the
job's last entry drops the per-run refs once every leg has completed
green, so a red attempt leaves them for its re-run. A point with no
gate job (the nightly, the release, a point a package contributes)
ends each of its jobs with ci.metrics.record: the job's half from
the traces its entries left, the run's row collected from every half
present, and the refs dropped by the last job to finish.
| series | a row is | window | writer |
|---|---|---|---|
metrics |
one run: every job's times, the run's wall, and the sections its judges left, the coverage extension's percentages among them | 300 | the gate job; each job of a point without one |
run/<id>/<leg> |
a job's half of its timing row, and the files its entries left, the suites the coverage extension measured with the scope it ran among them, until the run's last green job drops it | none | the leg |
durations/<leg> |
one run on one platform leg: the seconds each item (a test file) took, every phase of every test in it summed over the leg's shards | 30 | the gate job's collect, after the fold |
verified |
a tree a green gate proved, with its scope and the base it composed on | 200 | the gate job |
coverage/<base>/<leg> |
the coverage extension's record on one leg, main's or a branch's: one row per suite, its parts in the line format as its last run judged them, at the closure each was measured at, replaced in place, a row it replaced or removed kept a day; each file's fixed facts once under facts/, beside the rows; a branch's goes with the branch |
none | main's gate job at a merge; a branch's own pull request runs |
coverage/marks |
the coverage extension's mark of a package, and who set it | 400 | the gate job, fm coverage.accept |
speed/marks |
a package's test time mark on one check leg and who set it | 400 | the gate job, fm speed.accept |
gate-record (local) |
a tree this checkout's fm check proved green |
200, 7 days | a green local gate |
fetched (local) |
when origin's row series were last mirrored into refs/workshop-origin/*, which series, and how many refs |
1 | fm sync, fm start |
diagnostics (local) |
the follow classifier's inputs for an unmerged ending | 20 | every unmerged follow |
The durations family is one series per platform leg,
check-<os>-<python>, one row per run, {"run": "<id>", "items":
{"<item>": <seconds>}, "head": <seconds>}, the newest thirty kept,
written by the gate job's collect from each check leg's folded row
once the run's metrics file has landed; a series of a leg the matrix
no longer produces is the janitor's to drop. The head is the test
seconds the first shard's unsplit steps hold back: the summed wall of
the gate steps outside the test phase, times the parallelism the
other shards' tests reached (the leg's own test step's, unsharded),
or the longest such step when no parallelism reads. A shard of that
leg reads the newest five rows stamped before the committer time of
the commit it checked out and takes the median per item, and the
median head, a row without one counting as 0; a row the
store stamped at or after that time reaches no shard, so every shard
of a run reads the same rows whatever lands while the run is in
flight. A series that cannot be read is printed as the reason and the
leg runs as one shard of one; an absent series reads as no rows. A
shard reads the verified record under the same bound, for the tree
its change is measured from and for the skip on a proved tree: a row
another run stamps while the shards start counts for all of them or
for none, so they measure from one tree and skip together. An
unsharded leg reads the whole record.
fm store.ls lists them with what each holds; fm store.show
<series> prints a series' rows newest first through the same reader
the verdicts use, --key=<leg>,<package> for one series of a family
and --json for the rows as they are. fm ci.timings renders the
metrics series: per job and metric the latest, p50, and p90 over
the window, then the movers. A platform that ran as shards is one
section, its folded row, with a line per shard under it giving the
shard's wall and queue times from the newest run; the shards' own
rows are no sections, and the movers and the speed and coverage
sections read the platform legs alone. fm janitor bounds every series in the
scope it runs in, windows, ages, and orphans, the remote ones from
the merge point's gate job after every green run. The site's deploy
phase draws its coverage pages from main's coverage record, the union
main's gate judged whatever its legs ran.
Where a test lives¶
Every pytest under a workshop venv runs apart from the machine's live
runner state. footman's pytest plugin points footman's data, cache,
and config directories at a fresh temporary home for the session,
before the first test and for every child process a test starts, so a
test neither reads the developer's config, tokens, worktrees, and
caches nor writes into them; a variable the outer environment already
set is kept. The one deliberate exception is a live test reading the
dev containers' credentials through
livery.forge.testing.shared_env_path, which skips without the file.
footman's plugin also guards the process-global task registry: a test
that leaves tasks there fails at its teardown naming them, and the
next test never inherits them. A module first imported under a
test's patch gets the original back when the test ends. livery-git's
pytest plugin gives every test's git a global config of the
session's own, with one identity.
The workshop adds one guard to footman's footman.test_guards group,
which puts back what an extension mount writes after every test: the
listed extensions' steps, the jobs they add to the CI points and join,
the task tree a run keeps, and the mount's record. A step one test
mounted therefore never judges the changes of a later test on the same
worker. The guard also drops the check leg's label from the session's
environment, so a test that drives the gate in-process runs as no
shard.
The forge lane belongs to livery.forge; the workshop orchestrates
local, git, and forge steps and never hands a raw forge verb to a
user.