Files
aevolution/docs/adr/0057-environmental-interval-scheduling.md
T
2026-10-08 12:08:53 -04:00

3.6 KiB

[Reviewed]

ADR-0057: Bounded local environmental intervals

Status

Accepted for M6.7, 2026-09-27. A scheduling adapter for rules 1/2; no biology or snapshot version changes. Fixed tick duration remains fixture configuration.

Context

M6.5/6.6 persist atomic process ticks. Host catch-up must not multiply rates by elapsed wall time, integrate the same boundary twice, or hide partly committed work. The generic particle scheduler must not acquire biological dependencies.

Decision

Add a stateless adapter to evo::processes. A request names world/frame, completed read tick, exclusive-start/inclusive-end interval, expected tick duration and one input per tick. Admit only the current completed boundary, matching world/frame and duration, end>=begin, and at most 64 ticks. Reject longer requested backlogs without work; the host must divide them into explicit bounded batches. No input queue, clock, retained debt, new rates or hidden persistence state exists here.

Each interval expands to the existing ordered tick function. Rules 2 run terminal facts -> capture -> growth -> feeding -> decay -> atomic checkpoint. Rules 1 keep their earlier chain. Resource command revision equals process tick; check it at admission. Inputs are intentions, not externally computed resource deltas. One writer owns the call and input span; no callbacks or concurrent mutation.

Admission errors change nothing. After admission, each successful tick commits independently. A failed tick stops execution and returns the committed prefix's reports, final boundary, failed tick and cause. Earlier successful ticks remain committed; the failing tick and suffix do not. This is explicit partial progress, not a batch transaction. Host resumes from returned/current boundary and supplies the remaining inputs. A repeated old interval is stale, even if identical; individual retained tick retries remain available on the process owner.

An empty interval at the current boundary is a no-op/pause. Pause advances no biological time. Resume starts at the saved tick after restoring the existing complete community envelope. No wall-time catch-up or offline player policy is inferred. Requests target exactly one community; foreign world/frame is rejected. There is no cross-region transfer or distributed ownership claim.

Alternatives Considered

Variable delta time changes nutrient limits and ordering. A second scheduler clock duplicates persisted authority. Whole-batch cloning is unnecessary for host catch-up and adds allocations. Putting this in evo::simulation reverses the existing independent particle-kernel boundary. Silent partial success is unsafe.

Benefits

Bounded work and reports, unchanged tick semantics, canonical split/merge equality for identical per-tick input streams, and restart from the existing checkpoint.

Costs

Callers must inspect execution failure and committed count. A maximum of 64 reports is returned inline; caller owns this fixed output buffer (under 16KiB). No retained memory or heap allocations are introduced by the adapter.

Risks

Boundary revisions are local single-owner checks, not authentication or fencing. Future worker handoff must add leases. Combining many ticks into one ecological integration is not equivalent and is not supported. A host must retain unsubmitted inputs; this API cannot recover a host queue that was never journaled.

Consequences

Test merged/split/per-tick execution, partial failure/retry, zero-length pause, snapshot resume, maximum batch, stale/foreign boundaries, duration mismatch and u64 interval limits. M6.8 integrates and measures the complete ecological slice; M7 provides durable host publication.