spellruntime

var AffectedSource string

AffectedSource / GraphSource are magus.affected's and magus.graph's returns - the in-process verbs beside ls, which had the same annotation gap Projects did. Ship with "magus".

var Builtins = sync.OnceValue(loadBuiltins)

Builtins is the built-in spell registry, keyed by runtime spell name (spells.Descriptor.Name, e.g. "go", "ts"), loaded once. This is the registry callers use: users refer to a spell by its name, and registration is by name. The source directory a spell was authored in (e.g. "golang" for "go") has no runtime presence.

var BuiltinsHash = sync.OnceValue(func() string {
	b, err := json.Marshal(Builtins())
	if err != nil {
		panic("magus/spell: marshal builtin spells: " + err.Error())
	}
	h := sha256.New()
	_, _ = h.Write(b)
	return hex.EncodeToString(h.Sum(nil))
})

BuiltinsHash is the SHA-256 of a stable serialization of the built-in registry, hex-encoded; it changes when any built-in spell's spec changes (mixed into cache keys). Hashing the resolved registry rather than the raw bytecode keeps it tied to spell semantics, not the Buzz compiler's output.

var CharmModuleSource string

CharmModuleSource is the pure-Buzz mirror of the charm host module (std/charm.go), shipped as the magus/charm declarations. Unlike the type mirrors it is hand-written (charm's constructors are logic, not a struct), kept in lockstep with the Go module by charm_parity_test. A self-contained built-in command spell imports it (`import "magus/charm"`) to build patches with charm.after / charm.set / ... instead of hand-written positional pointers; it is pure Buzz with no host calls, so it compiles into a bare built-in.

var CharmTypeSource string

var CommandSource string

var CommitAuthorSource string

CommitAuthorSource / CommitSource / TagSource are the generated Buzz mirrors of types.CommitAuthor, types.CommitRecord, and types.VCSTag. Ship with "vcs": vcs.commit/vcs.history return Commit, vcs.tags returns [Tag]. CommitAuthor must precede Commit (Commit.author is CommitAuthor); the co-located SemverVersion (see above) must precede Tag (Tag.version is SemverVersion).

var CommitSource string

var CrossTargetRefSource string

CrossTargetRefSource / TargetSpellUseSource / InputRefSource / OutputRefSource / TargetGraphNodeSource / TargetGraphProjectSource / TargetGraphSource are the generated Buzz mirrors of magus.targets's result (types.TargetGraphOutput and the node/ref types it nests). Ship with "magus" (magus.targets is a magus.* method). Declare-before-use order, since each nested type is referenced by the next: the four leaves have no struct-valued fields so their relative order does not matter; then TargetGraphNode (referencing all four), TargetGraphProject, then TargetGraph.

var ErrNotASpell = errors.New("magus/spell: a spell module must `export fun mgs_getName`")

ErrNotASpell signals that a Buzz module is simply not a spell - it exports no mgs_getName - rather than a malformed one. Speculative discovery (a local import tried as a spell before falling back to a plain module) treats this as a quiet "not a spell, move on"; an explicit spell load still surfaces it as an error.

var ExecResultSource string

ExecResultSource is the generated Buzz `object ExecResult` mirror of types.ExecResult (see cmd/magus-utils types). Ships with "os": proc.exec / os.execSh return it, and magus's own describe-style methods (magus.build, ...) that also return ExecResult reuse the same mirror once "os" is imported for the exec call that produced it in the first place.

var FileInfoSource string

FileInfoSource is the generated Buzz mirror of the fs.stat result. Ships with "fs".

var GraphSource string

var HTTPResponseSource string

HTTPResponseSource is the generated Buzz mirror of an http.* response. Ships with "http".

var HintSource string

HintSource is the generated mirror of spells.Hint: one {match, then} failure classification a command op declares. It must PRECEDE CommandSource in the bundle - Command.hints is [Hint] - and it references nothing itself.

var InputRefSource string

var ManifestSource string

ManifestSource is the generated mirror of spells.Manifest: the file a project's dependencies are declared in, plus the lockfiles its ecosystem resolves them into. It belongs in magus/spell for the same reason Path does - mgs_listManifests is authored before any host module is invoked - and it references no other mirror (its fields are a str and a [str]), so its position in the bundle is free.

var ModuleFieldEntrySource string

ModuleFieldEntrySource / ModuleMethodEntrySource / ModuleSource are magus.modules / magus.module's returns. Ship with "magus". ModuleFieldEntry and ModuleMethodEntry must precede Module (its fields/methods are lists of them).

var ModuleMethodEntrySource string

var ModuleSource string

var OptionalContract = []contractEntry{
	{Name: "mgs_listRequiredGlobs", Field: "needs", Shape: ShapePaths},
	{Name: "mgs_listProvidedGlobs", Field: "provides", Shape: ShapePaths},
	{Name: "mgs_listClaimedGlobs", Field: "claims", Shape: ShapePaths},
	{Name: "mgs_listIgnoreDirs", Field: "ignore_dirs", Shape: ShapePaths},
	{Name: "mgs_listManifests", Field: "manifests", Shape: ShapeManifests},
	{Name: "mgs_getTools", Field: "tools"},
	{Name: "mgs_getLanguage", Field: "language"},
	{Name: "mgs_isOpaque", Field: "opaque"},
	{Name: "mgs_listTargets", Field: "ops"},
}

OptionalContract is the canonical list of optional mgs_ functions a spell module may export (mgs_getName is required and handled separately by the resolver). Resolve calls each present function and stores its result under Field. Treat as read-only.

MGS functions take no arguments. They run while Magus is discovering a spell, before there is a selected target or execution context; a target's magus.Context would therefore be fabricated data at this boundary. Per-invocation typed inputs belong on ordinary exported spell functions instead. Every scalar and list contribution (needs, provides, version_cmd, opaque) resolves uniformly. The "ops" entry (mgs_listTargets) is the exception: resolveOps post-processes it to extract function-valued op handlers into command records (the form the built-in spells use). Record-shaped ops pass through unchanged. See docs/engines.md.

var OutputRefSource string

var PatchOpSource string

PatchOpSource / CharmTypeSource / CommandSource are the generated Buzz `object` mirrors of spells.PatchOp, spells.Charm, and types.Run: the {cmd, args, charms} command a command target's handler hands to its cb callback, down to the RFC 6902 ops. Unlike the other object mirrors they are inlined into self-contained built-ins (every command spell references Run), so they ship in the magus/spell bundle (see builtinModuleSources). Order matters in that bundle: PatchOp precedes Charm (Charm.ops is [PatchOp]) precedes Run (Run.charms is {str: Charm}).

var PathSource string

PathSource is the generated lexical filesystem-reference type used by spell metadata. It belongs in magus/spell because declarations such as inputs and manifests are authored by spells before any host module is invoked.

var ProjectEntrySource string

ProjectEntrySource / ProjectsSource are the generated Buzz mirrors of types.ProjectEntry and types.ProjectsOutput: what magus.ls returns. They close a documented gap - magus.ls's own doc told readers to annotate `> Projects` while no such type existed, so the annotation it recommended did not compile. Ship with "magus" (magus.ls is a magus.* method, not a bare-import host module). ProjectEntry must precede Projects (Projects.projects is [ProjectEntry]).

var ProjectSource string

ProjectSource is the generated Buzz `object Project` mirror of spells.Project: one project a workspace-provider spell's list_projects contract returns. It ships in the magus/spell bundle beside the other shapes a spell AUTHORS; it references no other mirror, so its position in that bundle is free.

var ProjectsSource string

var RunSource string

var SecretSource string

SecretSource is the generated mirror of spells.Secret - what a provider spell's resolve_secret op returns. It references nothing, so it has no ordering constraint in the bundle.

var SemverNextSource string

var SemverVersionSource string

SemverVersionSource / SemverNextSource are the generated Buzz mirrors of semver.parse's and semver.next's results. Ship with "semver". No ordering dependency between the two (SemverNext's fields are plain strings), but they live next to each other since the two host methods are a pair.

SemverVersionSource is ALSO co-located into the "vcs" bundle: vcs.tags returns [Tag] and Tag.version is a SemverVersion, so `import "vcs";` alone still needs it in scope. An import line inside vcs's bundle cannot reach "semver" - a synthetic module's companion source is only collected, never executed, so an import inside it is inert - hence duplicating the generated string into both bundles at assembly time.

var ServiceSource string

ServiceSource is the generated Buzz `object Service` mirror of spells.Service: the {command, readiness, stop} a service op returns, each field a Command (command is the process; readiness/stop are optional). It ships in the magus/spell bundle so a spell can author a service op; it must follow CommandSource there (Service's fields are typed Command).

var SpellModuleSource = strings.Join([]string{PathSource, ManifestSource, TargetModuleSource, PatchOpSource, CharmTypeSource, HintSource, CommandSource, ServiceSource, VersionKeySource, VersionBoundsSource, ToolSource, ProjectSource, SecretSource}, "\n")

SpellModuleSource is the magus/spell bundle: the spell-authored value types in their declare-before-use order (PatchOp before Charm before Command before Service, each referencing the prior; Target and Project have no cross-references so their position is free). Shared by the runtime registration (modules.go) and the built-in inliner (builtinModuleSources) below, so the two can't drift apart.

var TagSource string

var TargetGraphNodeSource string

var TargetGraphProjectSource string

var TargetGraphSource string

var TargetModuleSource string

TargetModuleSource is the generated Buzz `object Target` mirror of types.Target (see cmd/magus-utils types), the canonical work-unit value type. It is consumed both at runtime (as part of the magus/spell declarations) and at built-in generation time (inlined into each built-in via SelfContainedBuiltinSource).

var TargetRunSource string

TargetRunSource / RunSource are the generated Buzz mirrors of one run and the targets in it (types.StatusTargetRun and types.StatusRun), the same shape `magus status` reports. They exist so a caller can ITERATE a run - each target's state (queued/running/passed/failed/cached), how long it took, and the output ref it minted - rather than parsing magus's own console output back out of a string.

TargetRun precedes Run, because Run.targets is a list of it and a struct-valued field mirrors as its bare type name, which must already be declared.

var TargetSpellUseSource string

var ToolSource string

ToolSource is the generated mirror of spells.Tool: everything a spell declares about one binary it drives. It must FOLLOW VersionKeySource and VersionBoundsSource in the bundle - Tool.key is a VersionKey and Tool.supported is a VersionBounds - and Command is already declared ahead of all three.

var URLSource string

URLSource is the generated Buzz mirror of encoding.parseUrl's result. Ships with "encoding".

var VersionBoundsSource string

VersionBoundsSource is the generated mirror of spells.VersionBounds - the window of versions a probed tool is allowed to report, as an inclusive min and an exclusive below. It ships in the magus/spell bundle so a spell can declare what its ops need, and it references nothing, so it has no ordering constraint against the others.

var VersionKeySource string

VersionKeySource is the generated mirror of spells.VersionKey - what a probed tool contributes to the cache key - together with the VersionComponent enum its upTo field is typed as. It ships in the magus/spell bundle so a spell can declare mgs_getVersionKey, and it carries its own enum, so it has no ordering constraint against the others.