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

67 lines
3.6 KiB
Markdown

[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.