Control

Where triggers put demand into the graph and let it propagate, the control verbs act on one Pond, without propagating. They're the operator's hands-on tools — for nudging a Pond after a patch, quieting part of the graph, or stopping something that's gone wrong.

duckstring control {wake|force|sleep|kill|clear} {pond}

All verbs accept -c for the Catchment and -m/-v to target a specific major or version. wake and force open the live status view until the Pond settles (--silent to skip; --watch to keep it open).

Wake — run if there's new input

duckstring control wake sales

Wake gives a Pond a single, non-propagating pull: it runs once when its Sources already hold fresher data — and waits for that if they don't yet — without soliciting the Sources to produce anything. Compare a Tap, which sends pull all the way upstream; Wake consumes what exists.

It's the gentle nudge: "catch up on whatever's there." Waking a failed or killed Pond also clears that state.

Force — recompute now

duckstring control force sales

Force re-runs the Pond immediately at its current freshness — no upstream change required. Its inputs are the same, so its freshness doesn't advance, and therefore nothing downstream re-runs: the recompute is contained to this Pond.

That containment is the point. The canonical use is after deploying a patch: the transform logic changed but the input data didn't, so you want this Pond's output rebuilt without replaying the lineage or waking the consumers. (If downstream should see the change — say the fix alters the published tables — follow up with a wake on the consumer, or let its standing demand pick the change up naturally.) Force also clears a failed/killed state.

Sleep — withdraw demand

duckstring control sleep reports
duckstring control sleep reports --upstream

Sleep clears all demand from the Pond — pull tokens and push targets — and cancels its standing trigger. It is gentle by design: a Pond Run already started completes normally; the Pond just won't start new work until demanded again.

--upstream extends the sleep to every ancestor, which is the clean way to quiet an entire lineage. Without it, upstream Ponds still holding their own demand keep running; only this Pond stops consuming.

Sleep is the right verb for maintenance windows and for pausing a noisy pipeline: nothing is lost, nothing is interrupted, and any trigger re-establishes the flow.

Kill — stop now

duckstring control kill sales

Kill is the hard stop: the Pond's worker process is terminated mid-run, the running Pond Run is cancelled (recorded as killed in run history), and the Pond is parked in a killed state. Killed is terminal and deliberate — no retry budget applies, no Source update revives it, and everything downstream that requires this Pond is blocked. It stays parked until an operator issues wake, force, or clear.

Use it on runaway work: a Ripple stuck on a hung connection, a transform chewing through resources, a run you know is producing garbage.

Clear — reset without running

duckstring control clear sales

Clear resets a failed or killed Pond to idle without running it: the failure state is dropped, the halted run is abandoned (it won't be re-detected as a failure), and downstream Ponds unblock. Use it when the run shouldn't be repeated — the failure was transient, or you'd rather wait for the next natural trigger than force a recompute. Covered in depth in Fault Tolerance.

How the verbs relate

	runs the Pond?	needs fresher Sources?	advances freshness?	clears failed/killed?
Wake	once, when input allows	yes (waits)	yes	yes
Force	immediately	no	no	yes
Sleep	no — stops new work	—	—	no
Kill	no — stops current work	—	—	no (causes killed)
Clear	no	—	—	yes

In demand-model terms: Wake is a one-shot pull that doesn't re-arm Sources; Force is a recompute at unchanged freshness; Sleep removes demand; Kill removes the worker. The same four verbs appear as the Control row in the web UI sidebar.