MGS3036: a project's configuration held whole

magus job fork, magus job apply, the client tool (magus\job.put) and a magusfile's magus\job.put refused a job because one of its write paths names a project's magusfile or magus.yaml whole:

[MGS3036] job: wave/slots holds a project's configuration whole: "magusfile.buzz",
  such as `magusfile.buzz#project.name`, `magusfile.buzz#project.targets.test`,
  `magusfile.buzz#build`. Every job that changes the workspace's configuration
  writes that file, so a whole-file hold blocks them all for one line; claim the
  declarations and keys the job changes instead

Nothing was written to the job store. A put that adds such a path to a job that already exists is refused the same way and leaves the job as it was.

Why

A target's slots, a source glob and a job setting are each one line of a magusfile or a magus.yaml, and every job that changes the workspace's configuration writes those files. A job that holds one whole serializes all of them behind its own line. Claims split the file: a magusfile's functions by name, its magus\project({...}) table by key path, and magus.yaml by key path.

Key claims

Inside the top-level magus\project({...}) call of a magusfile:

• magusfile.buzz#project.<key> holds one top-level key, such as project.sources.
• magusfile.buzz#project.<key>.<entry> holds one entry of a key whose value is a map: magusfile.buzz#project.targets.test holds the test entry of targets and nothing else.

In magus.yaml, magus.yaml#<key> holds a top-level key and magus.yaml#<key>.<sub> one key under it, such as magus.yaml#jobs.stale_after.

A claim on a key whose children are placed (project.targets, jobs) names every child, so fork refuses it as ambiguous with MGS3031. A key that does not exist yet is accepted, since the job may be about to add it.

What is refused

• A literal path to a magusfile or magus.yaml a project loads, at the root or in any project, including a file under a magusfiles/ directory.

What is not refused

• A claim (magusfile.buzz#project.targets.test) or a glob (**/*.buzz). A job holding one of these files through a glob narrows on its first write to it: its row gains a claim on each declaration or key the write changes, and the rest of the file is recorded as released, with its digest. From then on the glob no longer holds that file for the job.
• A checkout that cannot place the file's lines, because .gitattributes has no *.buzz diff=buzz or *.yaml diff=yaml line or its version control places none. Nothing smaller than the file could be claimed there. Neither is a file that declares nothing yet.
• A spell source a magusfile imports.

The release request

When another live job holds the file, the refusal also opens one attention request (outcome waiting) naming the holder and the file, with the claims the refused fork wanted as its files. A second refusal over the same holder and file lands on the same request, and a dry run (magus job apply --dry-run) opens none. The holder narrows its write paths, or exits, and the holder or the root closes the request:

magus session attention
magus session dispose <request>

What to do

Claim what the job changes:

magus job fork wave/slots --write-paths 'magusfile.buzz#project.targets.test'

See also

• Leases: write paths, claims, and what the guard enforces.
• MGS3031: a declaration claim nothing can grade.
• MGS3032: an unordered share of one claimable file.