[EiffL]

Why

ASTRA 0.1 changes what a spec is and who answers what. Universes live in astra.yaml, and the specification fixes where a result and its provenance record go and what makes a result stale. It names three tools: a validator, a checker and a runner, and gives the runner a layer of rules of its own.

This PR makes lc the runner and nothing else, on the astra-tools API of astra-project/astra-tools#138, whose data model is proposed in astra-project/astra-spec#117 (RFC 0009). It supersedes #268.

The split

Question	Who answers	How lc asks
Is the analysis valid? What are its results, where does each go, what does each read, what command makes it? Does each record still hold?	astra-tools	One call, astra.api.check, per verb
Which results to make now, in what order, where? Which environment, sandbox, storage, commit? What does a record say of its run?	lc	n/a

api.check returns the resolved analysis and one status per result, as plain data. lc imports astra through astra.api only, plus astra.scaffold (the empty spec) and astra.papers.cache (the viewer).

What the engine no longer does

ASTRA's model gives every path from the project root and each command already rendered, so the code that converted paths between frames and filled placeholders is gone.

• plan.build is lookups. A Task is ASTRA's own Result plus what a run needs resolved once from the model's references: the folder the recipe runs in, the file each entry reads, the options it is made with, what its recipe asks for.
• A task key is ASTRA's result id: fit#baseline, stage.fit#u1, and stage:fit#v1 for a result that belongs to another analysis (it was stage/fit#v1).
• One status per result, where there was one per place.
• Records are written by api.write_records, one at each place of a result, from the facts of the run. lc hashes its own files (assets.digest_file).
• The viewer's run route reads a record as the JSON it is, with no astra import.

The one rule lc adds to the checker's

The checker says what a result breaks in itself (Status.why). Whether a result that only reads a rebuilt one must be rebuilt too is lc's rule, in assets.classify: compare the bytes each result it reads has now with the bytes its record says were read. A task passes what its upstreams actually produced; the driver passes what their records say, or None while one may still be remade. A byte-identical rebuild still stops a cascade, with no second check and nothing asked of ASTRA from a worker.

The specification's runner rules

Each rule of the runner layer is kept in one place, and tests/test_runner_rules.py has a test named after each, on a real project. The suite reads the rules from the installed astra-spec, so a rule a later release adds fails there until it is answered. AGENTS.md has the table.

Rule	Where
UNRECORDED_RESULT, FALSE_RECORD, WRONG_WORKING_DIRECTORY	worker.execute
UNRECREATABLE_ENVIRONMENT	new check: a run is refused while a file the environment's identity reads is not tracked by git. A clean tree does not rule that out, since an ignored file is clean.
UNCOMMITTED_CHANGES	The dirty-tree refusal, and a new check as each made result arrives (below).
REBUILT_FROM_COMMIT	A result that belongs to an analysis declared with a commit is no task.
NOT_AT_COMMIT, STALE_INPUT	Kept by refusal: lc builds nothing from an analysis at a commit.
UNDECLARED_READ	The exec boundary, for files outside the project. Inside it the tree is readable whole, so there the rule is the author's to keep.
CODE_OUTSIDE_ANALYSIS	ASTRA finds it; lc reports it with every run and --check.

A behavior change to decide on

An edit or a commit while a run is in flight now fails the results that arrive after it. Before, the run finished, committed them, and warned that "the records name the starting commit, which no longer describes this code". That warning described a record that is false, and the specification makes both rules a MUST. Now such a result is restored and reported failed, with what was edited; results committed before the edit stand, and the edit itself is left untouched.

The cost is real: touching a README during a long run discards the results that finish afterwards. If that is too strict in practice, the check is one call in materialize._consume and can go back to a warning.

Dependencies

astra-tools is pinned by git to the head of astra-project/astra-tools#138 until that is released. astra-spec>=0.1.0rc1 is a direct dependency only so that a resolver accepts the release candidate.

Known gaps

• lc view's page needs @astra-spec/sdk and @astra-spec/ui for 0.1; the browser test fails in CI until then.
• .github/workflows/eval.yml and evals/ are still 0.0.14.
• What the record cannot hold is not kept: what the sandbox enforced, the image id, the uv version. A slot for runner attestation is a change to the specification.
• An analysis declared with a commit is refused wherever a result would be built from it. ASTRA's model has no command for such a result (the RFC's open question).
• lc run grants a probe no declared input while the spec is invalid, as only a valid analysis resolves. Files inside the project are readable anyway.
• No migration for 0.0.14 projects, by the no-back-compat rule.

Tests

Locally, with LC_SANDBOX_TESTS_REQUIRED=1 LC_CRATE_TESTS_REQUIRED=1: 1261 passed, 1 failed. ruff check and mypy src/ are clean.

The failure is tests/test_view_browser.py::test_open_dialog_follows_artifacts_and_late_provenance, the first known gap above: the page refuses a 0.1 analysis. It is left failing rather than marked expected, so the PR cannot merge with a viewer that does not work.

New or re-expressed tests pin:

• each runner rule, by its code (tests/test_runner_rules.py, 16 tests), including a result with two names being made once and recorded at each place, and the two mutation-checked boundary tests;
• an edit, a stage and a foreign commit while a run is in flight;
• classify on the level of each diagnostic in why, with read=None, with the recorded digest and with another;
• a task asking ASTRA nothing about the project (check, resolve and validate all raise inside it), and a run asking api.check once however far a remake cascades;
• what a task looks up: its folder, the file each entry reads, its decisions by ref, and keys for a result that belongs to another analysis;
• the crate's ids for decisions by ref and for a result of another analysis.

🤖 Generated with Claude Code