Implement M6.7 bounded environmental interval scheduling

This commit is contained in:
dingo
2026-09-27 18:45:06 -04:00
parent 6dd0e49e45
commit ef40f38ed0
15 changed files with 360 additions and 3 deletions
+1 -1
View File
@@ -61,7 +61,7 @@ target_link_libraries(evo_ecology PUBLIC evo::accounting evo::biology)
target_compile_features(evo_ecology PUBLIC cxx_std_23)
evo_owned_target(evo_ecology)
add_library(evo_processes STATIC src/processes/producer.cpp src/processes/feeding.cpp src/processes/ecosystem.cpp src/processes/genome_strategy.cpp src/processes/ensemble.cpp src/processes/environmental_community.cpp src/processes/environmental_codec.cpp)
add_library(evo_processes STATIC src/processes/producer.cpp src/processes/feeding.cpp src/processes/ecosystem.cpp src/processes/genome_strategy.cpp src/processes/ensemble.cpp src/processes/environmental_community.cpp src/processes/environmental_codec.cpp src/processes/environmental_schedule.cpp)
add_library(evo::processes ALIAS evo_processes)
target_link_libraries(evo_processes PUBLIC evo::accounting evo::biology evo::world)
evo_owned_target(evo_processes)
+1
View File
@@ -23,6 +23,7 @@ network service. Dev verification manifests are separate from the simulation.
- [Versioned abiotic base generation](docs/world/BASE_GENERATION.md)
- [Actual validation results](docs/engineering/VALIDATION.md)
- [Current delivery status and next steps](docs/STATUS.md)
- [Bounded environmental intervals and resume](docs/architecture/ENVIRONMENTAL_SCHEDULING.md)
- [Opt-in ECS evaluation and measurements](docs/engineering/ECS_EVALUATION.md)
- [Sequential command scheduling and recovery](docs/architecture/SCHEDULER_CONTRACT.md)
- [Local periodic spatial queries](docs/architecture/SPATIAL_CONTRACT.md)
+8
View File
@@ -469,3 +469,11 @@ partial inventory, lifecycle and retry reports together; v1 stays byte-compatibl
Tests cover rollback, water headroom, shared caps, restored exact retries, history
eviction, malformed v2 envelopes and next-tick nutrient-fed growth. Next: M6.7
fixed environment interval scheduling; M6.8 retains the full integration proof.
M6.7 implemented (2026-09-27): ADR-0057 adds a stateless adapter for at most 64
explicit process ticks. World/frame, quantum and completed resource/process
revision are checked before work. Per-tick phases remain unchanged; a later tick
failure returns its committed prefix explicitly. Pause/resume needs no second
clock or snapshot format. Tests compare 1/3/17/64-wide batches to direct execution
for rules 1 and 2, restore between batches, partial failures and u64 boundaries.
Next: M6.8 integrated multi-seed ecosystem qualification and cost evidence.
+7 -2
View File
@@ -7,7 +7,7 @@ persistent simulation server. The founding vision remains unchanged.
## Completed implementation
- Vision, architectural pillars, risks, open-question register, architecture
diagrams, biological contracts, engineering constitution and 56 ADRs (including the accepted M6.6 terminal/decay contract).
diagrams, biological contracts, engineering constitution and 57 ADRs (including the accepted M6.7 interval scheduling contract).
Proposed/deferred choices remain distinct from accepted proof decisions.
- M0–M4 task breakdowns with dependencies, acceptance evidence and risks,
plus M5–M14 gates in [ROADMAP.md](ROADMAP.md).
@@ -61,7 +61,7 @@ for the bounded proof; the general production ECS remains a later measured choic
| Priority | Work | Completion evidence |
|---|---|---|
| 1 | M6.7 schedule local environment intervals | Explicit fixed intervals and phase order, bounded catch-up, pause/resume and stale boundary refusal |
| 1 | M6.8 validate the integrated environmental slice | Multi-seed full-cycle runs, per-channel conservation, restore/replay equivalence and cost report |
| Research | Improve aggregate fidelity and measure Linux/target-host costs | M4.6 found no qualifying width; see the aggregate budget report |
| 2 | Revisit the ADR-0031/0032 reproduction cost model | Reproduction is affordable only at the genome schema's floor; decide whether that is intended before M4 builds cohorts on it |
| Delivery gate | Add/update the dev workload when a deployable increment needs it; Argo is ready | Observe Job/pod completion separately from image publication; no World0 changes |
@@ -728,3 +728,8 @@ Partial bounded decay conserves matter and energy, restores with exact retry
history, and can supply the surviving producer on a later tick. V1 compatibility
is retained. See ADR-0056 and VALIDATION.md for scope and evidence. This does not
add mortality causes, decomposer kinetics, durable publication or player sessions.
M6.7 now schedules bounded explicit local intervals, checks stale/foreign boundaries
and reports committed prefixes on failed catch-up. Pause/restore/resume uses the
existing process envelope; no wall-clock debt is inferred. M6.8 is next. See
architecture/ENVIRONMENTAL_SCHEDULING.md for caller responsibilities.
@@ -0,0 +1,65 @@
# 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.
+2
View File
@@ -1,5 +1,7 @@
# Architecture decision records
- [ADR-0057: Environmental interval scheduling](0057-environmental-interval-scheduling.md) - accepted M6.7 bounded explicit intervals and committed-prefix results.
- [ADR-0056: Environmental terminal decay](0056-environmental-terminal-decay.md) - accepted for M6.6 retained corpses, bounded decay and rules/envelope v2.
Locked requirements outrank these records. Review architecture, ADRs, public
@@ -0,0 +1,46 @@
# Local environmental scheduling
Authority: ADR-0057. Adapter version 1 supports process rules/envelopes 1 and 2.
The adapter has no persisted state. Tick duration is read from immutable process
configuration; all rate residuals and committed tick live in the process envelope.
```mermaid
flowchart LR
H[Host supplies world, begin, end, quantum and inputs] --> A[Admit current boundary and at most 64 ticks]
A --> T[Execute one complete process tick]
T -->|success: record receipt| N{More inputs?}
N -->|yes| T
N -->|no| R[Return committed prefix and final tick]
T -->|failure: no changes for this tick| R
A -->|invalid| E[Reject with no progress]
```
`schedule_environment(community, interval)` returns expected<EnvironmentalIntervalResult,
EnvironmentalIntervalError>. `begin` is the completed read revision, `end` the
requested completed revision. `inputs[i]` applies at begin+i+1. Require matching
world/frame, immutable tick_microseconds, process tick and field command revision.
No duration multiplication is used, so intervals cannot overflow microseconds.
Subtract end-begin only after end>=begin; reject count>64 before accessing inputs.
Admission errors are identity, quantum, stale, range, backlog or input_count.
Result contains committed count, last_tick, fixed reports array (only committed
entries are meaningful), and optional failure {tick,cause}. Failure may exist with
zero committed ticks. A successful expected alone does not mean the full interval
completed. On failure, snapshot the owner normally; resume at last_tick with the
suffix, correcting the rejected input if appropriate. Failed ticks never enter
retry history. Reusing the old begin is stale once any prefix committed.
Empty matching intervals leave canonical bytes unchanged, including at u64 max.
Not calling the adapter also pauses biological time. No elapsed-time parameter or
automatic catch-up exists. Hosts with more than 64 inputs must issue bounded
prefixes; the adapter never silently drops pending work. The 64-tick limit bounds
one call's work, not accumulated world age or total host backlog storage.
Batch partitioning is observationally equivalent for the same ordered inputs:
compare flattened receipts and final canonical snapshots. This includes phase
ordering, resource exhaustion, rational rate residuals and terminal decay. It
does not justify integrating growth/feeding/decay once with a larger timestep.
The exact same quantum is required after restore; changing it needs a migration.
No world/account/region service is added. This fixture contains no player sessions;
pause/resume is not an implementation of the unresolved player logout policy.
+4
View File
@@ -1,5 +1,9 @@
# Sequential scheduler contract v1
The independent M6 environmental fixture uses a separate
[bounded interval adapter](ENVIRONMENTAL_SCHEDULING.md) in evo::processes. It
does not change this particle scheduler's transaction or retry semantics.
This implements the scoped decision in [ADR-0022](../adr/0022-sequential-command-scheduler.md).
It is a synthetic lifecycle proof, not a player input protocol.
+4
View File
@@ -1,5 +1,9 @@
# M6.5 environmental process contract v1
M6.7 exposes immutable `tick_microseconds()` and a stateless bounded
`schedule_environment` adapter. See [scheduling](../architecture/ENVIRONMENTAL_SCHEDULING.md)
for admission, partial progress, pause/resume and resource revision contracts.
M6.6 adds opt-in rules 2 under [ADR-0056](../adr/0056-environmental-terminal-decay.md).
The public config adds decay[10] in fg/pJ per tick; input adds terminal[2] flags
in actor order. Progress adds consumer_terminal; reports add consumer_transition
+26
View File
@@ -1949,3 +1949,29 @@ separate verification step; local Docker Linux engine/toolchain is unavailable.
Final native validation: Release 54/54 (3.66s), clang-tidy analysis 54/54 (13.37s),
ASan 54/54 (46.72s), format check and git diff --check passed. M6.6 is natively
qualified; the next gate is M6.7 interval scheduling. No deployment was changed.
## M6.7 local environmental intervals - 2026-09-27
ADR-0057 and ENVIRONMENTAL_SCHEDULING.md define the stateless interval adapter.
Admission validates world/frame, fixed quantum, completed process/field revision,
ordered endpoints, at most 64 ticks and an exact input count. Each process tick is
atomic; execution failure explicitly returns the committed prefix and failing tick.
No new scheduler state, snapshot format, biology rule, dependency or deployment.
Tests compare 130-tick streams under rules 1 and 2 against direct execution using
batch widths 1/3/17/64, flattened report equality and final canonical snapshots.
Every batch pauses without mutation and restores before continuing. Admission
cases include foreign/stale boundaries, quantum mismatch, missing/extra input,
65-tick backlog, u64-max backlog and reversed intervals. Failure at first, middle
and final tick preserves precisely the committed prefix, then restores and resumes
to the uninterrupted result. The existing valid u64-max checkpoint now also tests
scheduler pause and wrap refusal. Partial success is intentionally not a whole-batch
transaction; callers must inspect failure and committed count.
Executed tools/windows-check.ps1 -Preset release/analysis/asan -Action check:
Release 54/54 (6.44s); clang-tidy analysis 54/54 (14.20s); ASan 54/54.
After making the optional failure access explicitly guarded, rebuilt Release and
reran both environmental CTests: 2/2 passed. Analysis/ASan include that final guard.
Release format-check and git diff --check passed. Tests retain NDEBUG checks.
Linux/UBSan/TSan CI confirmation remains pending; native validation does not claim
a Linux or target-server run. Next is M6.8 integrated ecological qualification.
@@ -65,6 +65,9 @@ class EnvironmentalCommunity {
[[nodiscard]] EnvironmentalProgress progress() const noexcept {
return progress_;
}
[[nodiscard]] std::uint64_t tick_microseconds() const noexcept {
return config_.tick_microseconds;
}
private:
struct State {
@@ -0,0 +1,35 @@
#pragma once
#include "evo/processes/environmental_community.hpp"
#include <optional>
namespace evo::processes {
inline constexpr std::size_t max_environment_interval = 64;
struct EnvironmentalInterval {
world::WorldIdentity identity{};
std::uint64_t begin{}, end{}, tick_microseconds{};
std::span<const EnvironmentalInput> inputs;
};
enum class EnvironmentalIntervalError : std::uint8_t {
identity,
quantum,
stale,
range,
backlog,
input_count
};
struct EnvironmentalIntervalFailure {
std::uint64_t tick{};
CommunityError cause{};
auto operator<=>(const EnvironmentalIntervalFailure&) const = default;
};
// Successful admission may still return a failed tick after a committed prefix.
// Only reports[0..committed) are meaningful. See ENVIRONMENTAL_SCHEDULING.md.
struct EnvironmentalIntervalResult {
std::size_t committed{};
std::uint64_t last_tick{};
std::array<EnvironmentalReport, max_environment_interval> reports{};
std::optional<EnvironmentalIntervalFailure> failure;
};
[[nodiscard]] std::expected<EnvironmentalIntervalResult, EnvironmentalIntervalError>
schedule_environment(EnvironmentalCommunity& community, const EnvironmentalInterval& interval);
} // namespace evo::processes
+35
View File
@@ -0,0 +1,35 @@
#include "evo/processes/environmental_schedule.hpp"
namespace evo::processes {
std::expected<EnvironmentalIntervalResult, EnvironmentalIntervalError>
schedule_environment(EnvironmentalCommunity& community, const EnvironmentalInterval& interval) {
if (interval.identity != community.resources().fields().identity())
return std::unexpected{EnvironmentalIntervalError::identity};
if (interval.tick_microseconds != community.tick_microseconds())
return std::unexpected{EnvironmentalIntervalError::quantum};
if (interval.begin != community.progress().tick ||
interval.begin != community.resources().fields().last_command())
return std::unexpected{EnvironmentalIntervalError::stale};
if (interval.end < interval.begin)
return std::unexpected{EnvironmentalIntervalError::range};
const auto count = interval.end - interval.begin;
if (count > max_environment_interval)
return std::unexpected{EnvironmentalIntervalError::backlog};
if (count != interval.inputs.size())
return std::unexpected{EnvironmentalIntervalError::input_count};
EnvironmentalIntervalResult result;
result.last_tick = interval.begin;
for (const auto& input : interval.inputs) {
// Admission proved last_tick < end for each remaining input: no wrap.
const auto next = result.last_tick + 1;
auto report = community.advance(next, input);
if (!report) {
result.failure = EnvironmentalIntervalFailure{next, report.error()};
break;
}
result.reports[result.committed++] = *report;
result.last_tick = next;
}
return result;
}
} // namespace evo::processes
+118
View File
@@ -1,5 +1,8 @@
#include "evo/processes/environmental_community.hpp"
#include "evo/processes/environmental_schedule.hpp"
#include <algorithm>
#include <cstdio>
#include <limits>
#include <source_location>
#include <stdexcept>
#include <string>
@@ -406,6 +409,119 @@ void decay_continuation() {
}
}
}
void scheduled_intervals() {
for (std::uint64_t rules : {1U, 2U}) {
auto c = config();
c.rules = rules;
c.growth_numerator = 1;
if (rules == 2)
c.decay.fill(1);
auto create = [&]() {
auto made =
EnvironmentalCommunity::create(c,
resources({100, 100, 100, 100, 0, 0, 100, 0, 100, 0},
{10, 0, 0, 20, 10, 10, 0, 30, 0, 0}),
8000000);
CHECK(made);
return std::move(*made);
};
std::array<EnvironmentalInput, 130> inputs{};
std::array<EnvironmentalReport, 130> expected{};
auto reference = create();
for (std::size_t i = 0; i < inputs.size(); ++i) {
inputs[i] = {i % 7 == 0 ? 260000U : 290000U, i % 3 == 0 ? 0U : 1U, {}};
if (i == 1 || i == 8)
inputs[i].bite[0] = 1;
if (rules == 2 && i == 16)
inputs[i].terminal[1] = 1;
if (rules == 2 && i == 32)
inputs[i].terminal[0] = 1;
auto r = reference->advance(i + 1, inputs[i]);
CHECK(r);
expected[i] = *r;
}
for (std::size_t width : {1U, 3U, 17U, 64U}) {
auto o = create();
for (std::size_t begin = 0; begin < inputs.size();) {
const auto end = std::min(begin + width, inputs.size());
auto r = schedule_environment(*o, {identity, begin, end, 50000,
std::span{inputs}.subspan(begin, end - begin)});
CHECK(r && !r->failure && r->committed == end - begin && r->last_tick == end);
for (std::size_t j = 0; j < r->committed; ++j)
CHECK(r->reports[j] == expected[begin + j]);
auto saved = o->snapshot();
CHECK(saved);
auto pause = schedule_environment(*o, {identity, end, end, 50000, {}});
CHECK(pause && !pause->failure && pause->committed == 0 && pause->last_tick == end);
CHECK(o->snapshot() == saved);
auto restored = EnvironmentalCommunity::restore(*saved, identity, 8000000);
CHECK(restored);
o = std::move(*restored);
begin = end;
}
CHECK(o->snapshot() == reference->snapshot());
}
}
}
void interval_boundaries() {
auto o = make();
std::array<EnvironmentalInput, 65> inputs{};
inputs.fill({290000, 1, {}});
const auto initial = o->snapshot();
CHECK(initial);
const auto reject = [&](EnvironmentalInterval request, EnvironmentalIntervalError error) {
auto r = schedule_environment(*o, request);
CHECK(!r && r.error() == error);
CHECK(o->snapshot() == initial);
};
reject({{8, 9}, 0, 1, 50000, std::span{inputs}.first(1)}, EnvironmentalIntervalError::identity);
reject({identity, 0, 1, 50001, std::span{inputs}.first(1)},
EnvironmentalIntervalError::quantum);
reject({identity, 1, 2, 50000, std::span{inputs}.first(1)}, EnvironmentalIntervalError::stale);
reject({identity, 0, 65, 50000, inputs}, EnvironmentalIntervalError::backlog);
reject({identity, 0, std::numeric_limits<std::uint64_t>::max(), 50000, {}},
EnvironmentalIntervalError::backlog);
reject({identity, 0, 1, 50000, {}}, EnvironmentalIntervalError::input_count);
reject({identity, 0, 0, 50000, std::span{inputs}.first(1)},
EnvironmentalIntervalError::input_count);
auto maximum = schedule_environment(*o, {identity, 0, 64, 50000, std::span{inputs}.first(64)});
CHECK(maximum && !maximum->failure && maximum->committed == 64);
const auto saved = o->snapshot();
CHECK(saved);
auto stale = schedule_environment(*o, {identity, 0, 64, 50000, std::span{inputs}.first(64)});
CHECK(!stale && stale.error() == EnvironmentalIntervalError::stale);
auto reversed = schedule_environment(*o, {identity, 64, 63, 50000, {}});
CHECK(!reversed && reversed.error() == EnvironmentalIntervalError::range);
CHECK(o->snapshot() == saved);
for (std::size_t failed_at : {0U, 2U, 3U}) {
auto partial = make();
auto reference = make();
std::array<EnvironmentalInput, 4> commands{};
commands.fill({290000, 1, {}});
commands[failed_at].temperature_mK = 0;
auto r = schedule_environment(*partial, {identity, 0, 4, 50000, commands});
CHECK(r && r->failure && r->committed == failed_at && r->last_tick == failed_at);
const auto failure = r->failure;
if (!failure)
throw std::runtime_error("missing interval failure");
CHECK(failure->tick == failed_at + 1 && failure->cause == CommunityError::input);
for (std::size_t j = 0; j < failed_at; ++j)
CHECK(reference->advance(j + 1, commands[j]) == r->reports[j]);
CHECK(partial->snapshot() == reference->snapshot());
auto bytes = partial->snapshot();
CHECK(bytes);
auto restored = EnvironmentalCommunity::restore(*bytes, identity, 8000000);
CHECK(restored);
commands[failed_at].temperature_mK = 290000;
auto remaining = std::span{commands}.subspan(failed_at);
auto resumed = schedule_environment(**restored, {identity, failed_at, 4, 50000, remaining});
CHECK(resumed && !resumed->failure && resumed->committed == remaining.size());
for (std::size_t j = failed_at; j < commands.size(); ++j)
CHECK(reference->advance(j + 1, commands[j]));
CHECK((*restored)->snapshot() == reference->snapshot());
}
}
} // namespace
int main() {
try {
@@ -415,6 +531,8 @@ int main() {
terminal_decay();
terminal_codec_validation();
decay_continuation();
scheduled_intervals();
interval_boundaries();
return 0;
} catch (const std::exception& e) {
std::fprintf(stderr, "%s\n", e.what());
+5
View File
@@ -1,5 +1,6 @@
#include "evo/core/random.hpp"
#include "evo/processes/environmental_community.hpp"
#include "evo/processes/environmental_schedule.hpp"
#include <algorithm>
#include <chrono>
#include <cstdio>
@@ -340,6 +341,10 @@ void exhausted_tick() {
CHECK((*restored)->advance(maximum, input)); // exact retry remains legal
CHECK(!(*restored)->advance(0, input)); // cannot wrap
CHECK(!(*restored)->advance(maximum - 64, input)); // outside retained window
auto pause = schedule_environment(**restored, {identity, maximum, maximum, 50000, {}});
CHECK(pause && !pause->failure && pause->committed == 0 && pause->last_tick == maximum);
auto wrap = schedule_environment(**restored, {identity, maximum, 0, 50000, {&input, 1}});
CHECK(!wrap && wrap.error() == EnvironmentalIntervalError::range);
CHECK(bytes(**restored) == b);
}
void sequences(std::uint64_t ticks) {