magus v0.4.3 is out. See what's new
¶ View markdown source · ✎ Suggest an edit
1 min read

MGS3031: a declaration claim nothing can grade

magus job fork, the magus_job tool and magus\job.put refused a job because one of its write paths claims a declaration (<file>#<declaration>) that no footprint could ever check:

[MGS3031] job: wave/notes claims a declaration no footprint can grade:
  "notes.txt" has no diff driver, so no changed line of it can be placed in a
  declaration; give `*.txt` one in .gitattributes (`magus doctor` lists the
  managed ones). Claim the whole file instead, or fix what is named

Nothing was written to the job store.

Why

A claim like run.go#executeStages lets two jobs start on one file. It holds only because magus can say, from the job's diff, which declaration every changed line lands in. That placement is git's: the file's diff driver (the diff= attribute) names the declaration each line sits under. A claim on a file with no driver, on a pattern, or in a checkout whose version control places no lines would read as a boundary and check nothing, so it is refused rather than recorded.

What is refused

  • An empty declaration: run.go#.
  • A pattern: internal/*.go#Run. A declaration lives in one file.
  • A file with no diff driver: magus manages drivers for Go, Python, Rust, Markdown, TypeScript and Buzz in its .gitattributes block. Any other extension needs a *.<ext> diff=<driver> line of your own.
  • A checkout with no version control, or one that does not place changed lines. Only git does today.
  • A path that contains #, spelled bare: notes/a#b.md when that file exists reads both as the path and as a claim on notes/a. Spell the path ./notes/a#b.md or notes/a\#b.md; the escaped form also takes a claim, notes/a\#b.md#Intro.

What to do

Claim the whole file, which is what the job was going to be graded against anyway:

magus job fork wave/notes --write-paths notes.txt

Or give the extension a driver, then fork again with the claim.

See also

  • Leases: write paths, claims, and what the guard enforces.
  • MGS3018: a directory as a job write path.
sandbox diagnosticsLanding page for the sandbox that confines magus spells to the workspace, plus its MGS2xxx diagnostics for denied reads, writes, execs, and env leaks. magus jobThe POSIX child lifecycle over delegated work: fork declares a job, exec takes the lease on it in this checkout, exit returns it with its result, wait verifies that result, and run submits one of the server's own jobs. Jobs and leasesThe surface magus gives an agent that fans work out - the working-state checkpoint, the declared job store, the lease a holder takes on a job, the console Jobs view, the recorded spawn, and verifying a result against the diff since the checkpoint. magus\guard.commandRegister one Buzz function the agent guard calls on every agent shell command, to add a deny or an advisory from your repository's own rules. magus ships the seam and no rules.
MGS3031jobsleaseswrite pathsforkagentsfootprintclaims
Last updated (a9ff8609)
Glossary

Spell

A language/runtime adapter (e.g. go, md) that maps generic targets onto a toolchain's real commands. See spells.

Buzz

The language magusfiles are written in (the .buzz engine). See engines.

Job

The unit of delegated work, and one row of the job store: what an orchestrating agent handed out, with its goal, the checkpoint it was cut against, the paths it may write or must not touch, and the one check it runs. A job's holder is either a session, for work an orchestrator handed out, or the server, for its own maintenance. The store records; the agent guard is what reads those facts back when grading a write. See doctrine.

A job is not a run. magus run build web is a run, and no job exists for it. A job causes runs: its check executes as one, and a server job records the invocation of its last one. Jobs are listed with magus ls jobs and in the console's Jobs view; runs are listed in the Runs view.

Run

One target executing under one magus invocation, such as magus run test web or magus affected ci. A run keeps its captured output behind an output reference. Every magus run is a run whether or not any job asked for it; see Job for how the two relate.

Lease

The grant a holder takes on a job: the write and read paths that job declared, enforced in the checkout that took it with magus job exec. A job is the piece of work; a lease is permission over it.

Conventions

Placeholders

Angle brackets mark a value you replace with your own - never type the brackets:

magus run <target>
magus completion <shell>    # e.g. bash, zsh, fish

<target>, <path>, <shell>, <name> and the like are stand-ins, not literal text.