Docs: Confusing Schedule Table Lifecycle and Transaction Semantics

[ferntheplant]

The schedule tables documentation does not describe critical lifecycle behaviors that differ between procedures and reducers, leading to
confusing errors and unexpected results.

Undocumented Behaviors

• Scheduled procedures delete the row before execution, so schedule_table.find(scheduled_id) returns null and .update() fails. Source:
  crates/core/src/host/scheduler.rs:510-520

    // For scheduled procedures, it's incorrect to retry them if execution aborts midway,
    // so we must remove the schedule row before executing.
    let reschedule = delete_scheduled_function_row(...);
    ScheduledProcedureStep::Procedure { params, reschedule }

• Scheduled reducers delete the row after execution, so the row is visible during reducer execution. Source:
  crates/core/src/host/scheduler.rs:590-593
• Interval schedules are never deleted—only one-shot schedules are removed. Source: crates/core/src/host/scheduler.rs:638-668
• The scheduler uses an in-memory queue separate from the database. Deleting a row doesn't immediately remove it from the queue; the queue
  entry fires, finds no row, and silently exits. Source: crates/core/src/host/instance_env.rs:384-386 and
  crates/core/src/host/scheduler.rs:343-364
• Row data is passed as a parameter (serialized to BSATN), which is how procedures receive the row data even though it's already deleted.
  Source: crates/core/src/host/scheduler.rs:740-747

Request

Please add documentation covering:

• When schedule rows are deleted (procedures vs reducers vs intervals)
• The transaction isolation of scheduled function execution
• The in-memory scheduler queue and its relationship to database state
• That row data should be accessed via the parameter, not by querying the schedule table

These behaviors are intentional (the source code has helpful comments explaining the rationale), but they're not visible in user-facing documentation.

[bfops]

Thank you for filing this! What do you think of #5265?

• The scheduler uses an in-memory queue separate from the database. Deleting a row doesn't immediately remove it from the queue; the queue
  entry fires, finds no row, and silently exits. Source: crates/core/src/host/instance_env.rs:384-386 and
  crates/core/src/host/scheduler.rs:343-364
• Row data is passed as a parameter (serialized to BSATN), which is how procedures receive the row data even though it's already deleted.
  Source: crates/core/src/host/scheduler.rs:740-747

These are implementation details that we don't think are meaningful to include in the docs, unless there's something user-impacting you think is important to call out here?

[ferntheplant]

Yup that seems great. The points you called out are fine to leave out I think - they didn't really affect my implementation