docs: Simulation execution and shutdown chapter of The Ixa Book

docs/book/src/SUMMARY.md

@@ -14,6 +14,7 @@
   - [Properties](topics/properties.md)
   - [Indexing](topics/indexing.md)
   - [Burn-in Periods and Negative Time](topics/burn-in-and-negative-time.md)
+  - [Execution and Shutdown](topics/execution-and-shutdown.md)
   - [Handling Errors](topics/handling-errors.md)
   - [Performance and Profiling](topics/performance.md)
   - [Profiling Module](topics/profiling-module.md)

docs/book/src/first_model/next-steps.md

@@ -14,7 +14,9 @@ in its entirety.
 1. Currently the simulation runs until `MAX_TIME` even if every single person
    has been infected and has recovered. Add a check somewhere that calls
    `context.shutdown()` if there is no more work for the simulation to do. Where
-   should this check live? _Hint: Use `context.query_entity_count`._
+   should this check live? _Hint: Use `context.query_entity_count`._ See
+   [Common Shutdown Patterns](../topics/execution-and-shutdown.md#common-shutdown-patterns)
+   for context on explicit stop conditions.
 2. Analyze the data output by the incident reporter. Plot the number of people
    with each `InfectionStatus` on the same axis to see how they change over the
    course of the simulation. Are the curves what we expect to see given our

docs/book/src/first_model/setup.md

@@ -130,7 +130,8 @@ The `run_with_args()` function does the following:
 3. Finally, it kicks off the simulation by executing `context.execute()`. Of
    course, our model doesn't actually do anything or even contain any data, so
    `context.execute()` checks that there is no work to do and immediately
-   returns.
+   returns. (See
+   [Execution and Shutdown](../topics/execution-and-shutdown.md).)
 
 If there is an error at any stage, `run_with_args()` will return an error
 result. The Rust compiler will complain if we do not handle the returned result,

docs/book/src/topics/burn-in-and-negative-time.md

@@ -19,6 +19,8 @@ A common but fragile solution is to run a separate “initialization” simulati
 Ixa provides a simpler mechanism: treat burn-in as part of the same execution. Instead of resetting time or stitching simulations together, you allow the timeline to extend into negative values. You then designate `0.0` as the beginning of your analysis window.
 
 Negative time is not a special execution mode in Ixa. It is simply earlier simulation time. The event queue, scheduling rules, and execution semantics are identical before and after `0.0`. What may differ is your model logic. You may choose to disable transmission, suppress reporting, use alternate parameters, or run simplified dynamics during burn-in. These differences arise from your code, not from special treatment by the framework.
+For details about the execution lifecycle itself, see
+[Execution and Shutdown](execution-and-shutdown.md).
 
 ## The Core Pattern
 

docs/book/src/topics/reports.md

@@ -409,6 +409,11 @@ pub fn init(context: &mut Context) {
 }
 ```
 
+Periodic plans are passive. They reschedule themselves after each report, but they do not keep the simulation running
+after active plans are exhausted. This means a periodic report can run at the final active simulation time, while later
+periodic report callbacks remain queued without being executed unless more active work is scheduled. See [Execution and
+Shutdown](execution-and-shutdown.md) for details about active and passive plans.
+
 The implementation of `write_aggregate_sir_report_item` is straightforward: We
 fetch the values from the data plugin, construct an instance of
 `AggregateSIRReportItem`, and "send" it to the report.

docs/book/src/topics/topics.md

@@ -3,6 +3,7 @@
 - [Properties](properties.md)
 - [Indexing](indexing.md)
 - [Burn-in Periods and Negative Time](burn-in-and-negative-time.md)
+- [Execution and Shutdown](execution-and-shutdown.md)
 - [Handling Errors](handling-errors.md)
 - [Performance and Profiling](performance.md)
 - [Profiling Module](profiling-module.md)

examples/births-deaths/README.md

@@ -33,7 +33,7 @@ scheduled for each individual. Once the person recovers, these plans are removed
 from the data structure. However, if the person dies before recovering, these
 plans are canceled at the time of death. The infection status of recovered
 individuals remains as recovered for the rest of the simulation, which will stop
-when the plan queue is empty.
+when no active plans remain and shutdown work is complete.
 
 ## Population manager