Script entry points

Every wscript file that config-weave runs exports one or two named functions with a fixed signature. Validation compiles each script against the host API and checks that the exported functions exist with an accepted signature before anything runs. A script that does not satisfy its contract fails validation with a message naming the entry point. Each entry point accepts two signatures: a plain one that returns the result directly, and a fallible one that wraps it in Result[…, string] so the body can use ?. An Err returned from a resource or gatherer becomes the step's *error* status with the string as its message. A VM fault, such as an index out of bounds or unwrap() on None, is reported the same way. Where each script lives and what it may import is covered in The host API.

check

fn check(params: Value) -> CheckResult
fn check(params: Value) -> Result[CheckResult, string]

Exported by a resource script. Reports whether the host already matches the desired state and must never change the host. The engine calls it once at the start of every step, and again after a successful apply as the re-check. params is a Value::Map holding the step's properties with declared defaults applied and types validated; see The Value type. The re-check must return AlreadyConfigured, or the step reports *error* with the message apply claimed success but the re-check disagrees.

apply

fn apply(params: Value) -> ApplyResult
fn apply(params: Value) -> Result[ApplyResult, string]

Exported by a resource script. Brings the host to the desired state. The engine calls it only in apply mode, and only when check returned NotConfigured. It receives the same params map as check. After Success the engine runs check again, so apply must converge fully, and it must converge across processes: a later run in a fresh process must also see AlreadyConfigured.

gather

fn gather(params: Value) -> Value
fn gather(params: Value) -> Result[Value, string]

Exported by a gatherer script. Collects facts and returns them as a Value, normally a map. A playbook gather block binds the result to a variable named by its label. params is the gather's params block with the gatherer's declared defaults applied. A key the gatherer declares with returns … type = "symbol" must come back as the bare token, such as "systemd"; the engine binds it into the playbook as the symbol :systemd. A failed gather aborts the run before any step executes.

verify

fn verify(facts: Value) -> bool
fn verify(facts: Value) -> Result[bool, string]

Exported by a test's verify script. Runs inside the test instance after the three engine runs and makes custom assertions about the converged state. facts is a map of the test's gather results, keyed by gather label. Returning false or Err fails the test; the Err string becomes the failure message. A verify script compiles during validation on the host but only ever executes inside an instance. It may import helpers from lib/ like any other script. See The test block.

run

fn run(lab: Lab) -> bool
fn run(lab: Lab) -> Result[bool, string]

Exported by a scenario driver. Runs on the host, not inside a guest, against the live vmlab lab the scenario declared. Lab is an opaque handle from the testlab module, the one module available to scenario scripts on top of the host API. The script brings machines up by name, applies resources, reboots, and asserts. Returning false or Err fails the scenario. Scenarios compile during validation and run one at a time after the test groups.

CheckResult

enum CheckResult { AlreadyConfigured, NotConfigured, RebootRequired }

The value check returns. It is ambient in every resource script; no use is needed. Each variant decides what the engine does next, as the table shows. The full lifecycle is in The convergence contract.

ApplyResult

enum ApplyResult { Success, RebootRequired }

The value apply returns. Ambient in every resource script.

Step statuses

{ "step": "make-a", "status": "already_configured" }

The statuses a step can report, as printed in human output and as the stable status id in --json output. The first six are the outcomes of the lifecycle; *not run* marks a step left undispatched when a run halts early, or blocked by a dependency that errored or did not run.