engine-orchestration

name	engine-orchestration
description	Use for task graph and execution changes in cli/src/engine/, command task membership, dependencies, startup task discovery, restart boundaries, Operation plans, ProcessMode, or task/resource parallelism. Not for a standalone Resource.

Engine Orchestration

Choose the boundary

Need	Owner
identity, eligibility, elevation, dependencies	Task
independent items with separate state	Resource
one idempotent multi-step workflow	Operation
pure parsing or transformation	plain module/function

Use resource-implementation for a concrete resource that does not alter scheduling.

Task graph rules

• Task::meta() is the source for TaskId, selector, display name, visibility, and update-only status. Prefer task_metadata!.
• Dependencies are the only ordering policy; catalog order is irrelevant.
• dependencies() block on predecessor failure. ordering_dependencies() wait without propagating failure.
• Dynamic instances use TaskId::dynamic::<Self>(stable_key) and are created once from the immutable startup configuration.
• A repository update that changes task/config inputs must use the guarded process restart boundary. Do not mutate config handles or discover tasks late.
• In the restarted child, remove repository synchronization only after target selection so retry selectors remain valid. Run preservation and sparse checkout as the strict first phase before remaining tasks.
• should_run() and needs_elevation() must be cheap and side-effect free. State produced by a prerequisite is checked in run_configured().
• Removing unmet work before graph execution must also skip its transitive dependents; an absent node does not propagate failure.

Convergence rules

• Use process_resources*() for item-shaped work.
• Use Operation plus process_operation() for workflow-shaped work.
• An operation computes one immutable plan in current_state() and passes that exact plan to preview() or apply(); never recompute it.
• Keep config read guards out of long-running or parallel work.
• Task parallelism uses scoped threads; resource parallelism uses Rayon. ctx.parallel gates both.

Process modes

Mode	Behavior
Strict	fix missing/incorrect; stop on error
Lenient	fix missing/incorrect; continue independent work
InstallMissing	install missing only
FixExisting	fix existing only

Use the matching ProcessOpts constructor and an existing canonical verb.

For focused graph, filtering, restart, discovery, and operation-plan coverage, use the task_execution and affected command suites listed under Integration test suites.