Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
21 changes: 12 additions & 9 deletions content/docs/agent-skills/lightcone.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -188,7 +188,9 @@ integrates, so each intermediate result can be inspected:
4. **Materialize.** It runs `lc materialize local <output>`, which remakes what is stale,
dependencies first, and commits each output as it lands.

The work is done when `lc materialize --check` passes. A script that ran well under `lc run` is a
The work is done when `lc materialize --check` passes and `lc status` lists no output as
`no recipe`. The check covers only outputs that have a recipe, so an output declared without one
never fails it. A script that ran well under `lc run` is a
probe, not a result: nothing counts until `lc materialize` has produced it.

Each output lands at `results/<universe>/<output>.<format>`, a path `lc` composes from the
Expand Down Expand Up @@ -220,13 +222,14 @@ nothing a recipe sees.
### Status

The agent reads `lc` through its `--json` output, and quotes the reason `lc` gives for each output
rather than inferring one. Each output is in one of three states:
rather than inferring one. Each output is in one of four states:

| State | Means | What happens |
| --------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `current` | Matches the specification, made under this environment | Nothing |
| `behind` | Still matches the specification, but the environment has changed | Nothing, unless you want it remade |
| `stale` | Contradicts the specification, or its bytes were changed by something other than its run | The next `lc materialize` remakes it |
| State | Means | What happens |
| ----------- | --------------------------------------------------------------------------------------- | --------------------------------------------------------- |
| `current` | Matches the specification, made under this environment | Nothing |
| `behind` | Still matches the specification, but the environment has changed | Nothing, unless you want it remade |
| `stale` | Contradicts the specification, or its bytes were changed by something other than its run | The next `lc materialize` remakes it |
| `no recipe` | Declared in the specification, with no recipe to make it | Skipped by `lc materialize` until a recipe is written |

Every output going `behind` after a `uv add` is normal. Upgrading `lc` invalidates nothing.

Expand Down Expand Up @@ -341,5 +344,5 @@ archive or cite the analysis, the agent:
`ro-crate-metadata.json`, an [RO-Crate](https://www.researchobject.org/ro-crate/) description of
the project rendered from the repository.

It is ready when validation passes, `lc materialize --check` passes, and `ro-crate-metadata.json`
exists.
It is ready when validation passes, `lc materialize --check` passes, `lc status` lists no output as
`no recipe`, and `ro-crate-metadata.json` exists.
11 changes: 7 additions & 4 deletions content/docs/lightcone-cli/commands/materialize.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,6 @@ stronger consent than a flag.

```json
{
"ok": true,
"up_to_date": true,
"made": [],
"current": ["baseline/fit", "robust/fit", "baseline/fit_plot", "robust/fit_plot"],
Expand All @@ -110,12 +109,16 @@ stronger consent than a flag.
}
```

The first two keys are the ones to branch on: `ok` means everything attempted finished;
`up_to_date` means nothing needed doing (a failed run is never up to date, and `behind` outputs
don't count against it). `planned` is check mode's answer, mapping each would-run output to why;
There is no overall success key. `up_to_date` is the check's answer: nothing needed doing (a
failed run is never up to date, and `behind` outputs don't count against it). A run succeeded when
`failed` and `blocked` are empty. The exit code is 1 when any of `failed`, `blocked` or `planned`
is non-empty. `planned` is check mode's answer, mapping each would-run output to why;
`behind` maps each left-alone output to the commit that can rebuild its environment. `notes` carries
sandbox messages verbatim: denial remedies are built to be pasted.

An output declared without a recipe never appears in `planned`: a run skips it, so the check
passes over it. [`lc status`](/lightcone-cli/commands/status) lists it as `no recipe`.

## Examples

```bash
Expand Down
21 changes: 14 additions & 7 deletions content/docs/lightcone-cli/commands/status.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -20,12 +20,13 @@ lc status [OPTIONS]
mode: direct
sandbox: landlock (fs: declared, network: allowed)

· current baseline/fit a3f1f11
· current baseline/fit_plot a3f1f11
· behind robust/fit 00cc14e made under an earlier environment
! stale robust/fit_plot — no manifest — it has never been materialized
· current baseline/fit a3f1f11
· current baseline/fit_plot a3f1f11
· behind robust/fit 00cc14e made under an earlier environment
! stale robust/fit_plot — no manifest — it has never been materialized
· no recipe baseline/summary —

2 current · 1 behind · 1 stale
2 current · 1 behind · 1 stale · 1 no recipe
```

The header is repository facts: which mode the project executes in (and, for a containerized
Expand All @@ -44,13 +45,19 @@ commit is where the environment that produced it can be read back.
`--refresh` remakes.
- `stale`: contradicts the project: definition changed, an input's content changed, or the output
was edited by hand since it was made (a *foreign write*; the offending commit is named).
- `no recipe`: declared by the spec, but with no recipe to make it. Runs skip it, and
`lc materialize --check` passes over it. Write its recipe to make it.

## Report vs gate

`lc status` reports; **`lc materialize --check` gates.** Two verbs answering the same question with
different exit codes is how a script comes to depend on the wrong one, so the split is sharp: use
status for eyes, check for exit codes.

The gate covers only outputs that have a recipe, because it predicts what a run would do and a run
skips the rest. An analysis is finished when the check passes and status lists no `no recipe`
output.

## Options

| Option | Default | Effect |
Expand All @@ -64,7 +71,7 @@ status for eyes, check for exit codes.
"mode": "direct",
"image": null,
"sandbox": "landlock (fs: declared, network: allowed)",
"counts": {"current": 4, "behind": 0, "stale": 0},
"counts": {"current": 4, "behind": 0, "stale": 0, "no recipe": 0},
"outputs": [
{
"output": "baseline/fit",
Expand All @@ -79,7 +86,7 @@ status for eyes, check for exit codes.
}
```

Per output: the state, the reason (empty for `current`), the commit it was materialized at and its
Per output: the state, the reason (empty for `current` and `no recipe`), the commit it was materialized at and its
content identity (both empty if it never was), and `foreign_write`: the sha of a hand-edit's commit
when one was detected, which the prose `why` cannot carry for a machine consumer. For a
containerized project, `image` is `{"tag": ..., "state": "present" | "absent" | "unfetched"}`.
5 changes: 3 additions & 2 deletions content/docs/lightcone-cli/concepts.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -178,9 +178,10 @@ no sandbox, the recipe still runs, and its manifest says so.
- **`lc status`** shows each output's state and the commit it was made at. It runs nothing, works with
uncommitted changes, and always exits 0.
- **`lc materialize --check`** runs nothing either, and exits 1 if a run would make anything. Use it
in scripts and CI.
in scripts and CI. It covers only outputs that have a recipe: `lc status` lists any declared
without one as `no recipe`.

Both take `--json`. In the check's report, the `ok` and `up_to_date` keys are the ones to test.
Both take `--json`. In the check's report, `up_to_date` is the key to test.

## Publishing

Expand Down