Run Your First WattSwarm Task End-to-End with the CLI

Submit a task contract to WattSwarm, execute it through the real runtime flow, and retrieve the finalized decision — all from the CLI.

Running your first task teaches you the complete WattSwarm lifecycle: you define a task contract, submit it to the kernel, trigger the real execution chain through a registered executor, and read back the finalized decision value and evidence summary.

Prerequisites

Before you start, make sure you have:

• The wattswarm binary built (cargo build --bin wattswarm)
• wattswarm-runtime built and running (cargo run --bin wattswarm-runtime -- --listen 127.0.0.1:8787)
• A node started with wattswarm node up
• The rt executor registered (wattswarm executors add rt http://127.0.0.1:8787)

If any of these steps are unfamiliar, follow the Quick Start guide first, then return here.

---

Creating a Task Contract

A task contract is the boundary object between your application and the WattSwarm kernel. It is a JSON document that tells the kernel what work to do, what a valid answer looks like, how much compute budget to allocate across execution stages, and when the task expires.

Create a file called task.json in your working directory:

task.json

{
  "protocol_version": "0.1",
  "task_id": "task-demo-001",
  "task_type": "swarm",
  "inputs": {
    "prompt": "Summarize the trade-offs between consistency and availability in distributed systems."
  },
  "output_schema": {
    "type": "object",
    "required": ["answer"],
    "properties": {
      "answer": { "type": "string" },
      "confidence": { "type": "number" }
    }
  },
  "budget": {
    "time_ms": 120000,
    "max_steps": 10,
    "cost_units": 100,
    "explore_cost_units": 40,
    "verify_cost_units": 30,
    "finalize_cost_units": 10,
    "reuse_verify_time_ms": 10000,
    "reuse_verify_cost_units": 5,
    "reuse_max_attempts": 2
  },
  "assignment": {
    "mode": "open",
    "claim": {
      "lease_ms": 30000,
      "max_concurrency": { "propose": 1, "verify": 1 }
    }
  },
  "acceptance": {
    "quorum_threshold": 1,
    "verifier_policy": {
      "policy_id": "vp.schema_only.v1",
      "policy_version": "1",
      "policy_hash": "sha256:placeholder",
      "policy_params": {}
    },
    "vote": { "commit_reveal": false, "reveal_deadline_ms": 5000 },
    "settlement": {
      "window_ms": 86400000,
      "implicit_weight": 1.0,
      "implicit_diminishing_returns": { "W": 10, "K": 3 },
      "bad_penalty": { "P": -5 },
      "feedback": { "mode": "none", "authority_pubkey": "" }
    },
    "da_quorum_threshold": 1
  },
  "expiry_ms": 1999999999000,
  "evidence_policy": {
    "max_inline_evidence_bytes": 65536,
    "max_inline_media_bytes": 1048576,
    "inline_mime_allowlist": ["text/plain", "application/json"]
  }
}

Field reference

Field	Type	Purpose
protocol_version	string	Contract schema version. Use "0.1" for the current kernel.
task_id	string	Unique identifier for this task. Use any stable string — UUIDs work well.
task_type	string	Must match one of the executor’s declared task_types from its /capabilities response.
inputs	object	Key-value pairs forwarded as-is to the runtime /execute endpoint. The prompt key is the standard way to pass a natural-language instruction.
output_schema	JSON Schema object	The kernel validates every candidate output against this schema before accepting it as a potential decision.
budget.time_ms	number	Wall-clock budget in milliseconds for the entire task.
budget.max_steps	number	Maximum number of execution steps allowed before the task is terminated.
budget.cost_units	number	Total cost budget across all stages combined.
budget.explore_cost_units	number	Hard cost gate for the explore stage. Execution cannot advance past this stage once the threshold is exceeded.
budget.verify_cost_units	number	Hard cost gate for the verify stage.
budget.finalize_cost_units	number	Hard cost gate for the finalize stage.
budget.reuse_verify_time_ms	number	Time budget allocated for knowledge-reuse verification attempts.
budget.reuse_verify_cost_units	number	Cost budget for knowledge-reuse verification.
budget.reuse_max_attempts	number	Maximum number of reuse verification attempts before falling back to fresh execution.
assignment	object	Claim and concurrency policy controlling how proposers and verifiers are scheduled.
acceptance	object	Quorum threshold, voting policy, verification policy binding, and settlement configuration.
expiry_ms	number	Unix epoch in milliseconds when the task expires. Set this far enough in the future that your execution chain can complete.
evidence_policy.max_inline_evidence_bytes	number	Maximum byte size for inline evidence payloads.
evidence_policy.max_inline_media_bytes	number	Maximum byte size for inline media evidence payloads.
evidence_policy.inline_mime_allowlist	string array	MIME types permitted for inline evidence (e.g. text/plain, application/json).

The output_schema field is what vp.schema_only.v1 (the default verification policy) validates against. Make sure every required field your executor returns is declared here, or verification will fail.

The acceptance.verifier_policy.policy_hash value must be the actual SHA-256 hash of the policy definition. When using task run-real, the kernel resolves this automatically. If you are submitting a raw task contract, run wattswarm executors check <name> to retrieve the correct hash for your runtime’s registered policies.

---

Submit the Task

Submit the task contract to the kernel’s local event log:

wattswarm --state-dir ./.ws-dev --store wattswarm.state task submit ./task.json

The kernel stores the contract and emits a TASK_CREATED event. At this point the task exists but has not been executed yet.

---

Run the Task

Trigger the full execution chain using a registered executor:

wattswarm --state-dir ./.ws-dev --store wattswarm.state \
  task run-real --executor rt --profile default --task-id task-demo-001

task run-real drives the complete lifecycle sequence internally:

TASK_CREATED
  → TASK_CLAIMED (propose)
  → CANDIDATE_PROPOSED
  → TASK_CLAIMED (verify)
  → EVIDENCE_AVAILABLE
  → VERIFIER_RESULT_SUBMITTED
  → VOTE_COMMIT
  → VOTE_REVEAL
  → DECISION_COMMITTED
  → DECISION_FINALIZED

The command blocks until the task reaches a terminal state and then prints the result as JSON.

---

Watch for Completion

If you want to poll the task state separately (for example, when running in compose where the worker drives execution asynchronously), use:

wattswarm --state-dir ./.ws-dev --store wattswarm.state task watch task-demo-001

The output shows the current state, whether a candidate has been committed, and whether the task has been finalized:

task=task-demo-001 state=Some(Finalized) committed=Some("cand-abc123") finalized=Some("cand-abc123")

---

Fetch the Decision

Once the task is finalized, retrieve the full decision record:

wattswarm --state-dir ./.ws-dev --store wattswarm.state task decision task-demo-001

The decision output includes:

{
  "task": "task-demo-001",
  "committed": "cand-abc123",
  "finalized": "cand-abc123"
}

Understanding the decision output

Field	Meaning
committed	The candidate ID that won the commit-reveal vote round.
finalized	The candidate ID that passed finality proof verification. Matches committed when no fork was detected.
candidate_output	The raw JSON object your executor returned as candidate_output from /execute. This is the actual answer.
confidence	The confidence value your executor included in candidate_output (if present).
finalized_at	Timestamp (ms) when DECISION_FINALIZED was emitted.
evidence_summary	Array of evidence references (inline digests and external ArtifactRef URIs) that supported the winning candidate.

The full decision memory — including quorum_result_json and reason_details — is persisted to the knowledge store for future reuse. Tasks of the same task_type can benefit from seed bundles drawn from previous decisions.

---

Using the UI Console

If you prefer a visual interface, all of the above steps are available through the built-in kernel console. Start the UI server:

wattswarm --state-dir ./.ws-dev --store wattswarm.state ui --listen 127.0.0.1:7788

Then open http://127.0.0.1:7788/ in your browser. The recommended operation order on the console matches the CLI workflow above:

1. Node → UP
2. Executors → ADD (name rt, base URL http://127.0.0.1:8787)
3. Executors → CHECK
4. Task → SAMPLE (optionally apply a preset)
5. Task → SUBMIT
6. Task → RUN-REAL
7. Task → WATCH / DECISION

The Task panel also includes a built-in TaskContract Minimal Reference snippet and preset helpers for common task shapes (swarm / arbitrage / security).