Event log and random tape
Purpose
The ecosystem layer treats decisions and ecological processes as two sources of the same event. A harvest is a controlled event; a fire is an uncontrolled one. Every event is recorded in a deterministic log, and every stochastic draw is a pure function of a scenario seed and a draw key. Together they make a stochastic landscape run exactly replayable and let candidate schedules share the same random draws.
This page specifies the event record, the ordering key, the log format, the random tape, and the replay contract. It does not yet specify process effects, cohort state, or scenario aggregation; those are later P144 tasks.
Event record
An event is one state transition at a known time and place:
Field |
Type |
Meaning |
|---|---|---|
|
string |
Stable identifier, unique within a log. |
|
string |
The scenario the event belongs to. The log header must name the same scenario. |
|
string |
The source that produced the event, such as |
|
string |
The event type, such as |
|
number |
Absolute simulation time in years. |
|
integer |
The annual accounting year the event belongs to. |
|
string |
The execution phase within the year. |
|
integer |
Ordering priority within a phase; lower runs first. |
|
array of int |
Fragments touched by the event. |
|
array of int |
Sites touched by the event. |
|
array of int |
Blocks touched by the event. |
|
string or null |
Categorical severity, such as |
|
number or null |
Continuous severity in [0, 1]. |
|
number or null |
A process-specific magnitude, such as wind speed or mortality fraction. |
|
number or null |
Event area in hectares. |
|
string or null |
The event that caused this one, when the log is a causal chain. |
|
string |
Provenance identifier for the producer. |
|
number or null |
Confidence or detection probability in [0, 1]. |
|
object |
Additional JSON-scalar attributes, sorted by key. |
The canonical phases, in execution order, are forcing, ignition, propagation,
effect, treatment, growth, regeneration, and accounting. Disturbance and
management therefore happen before annual growth, and regeneration happens after it. A new phase
is a schema-version change, not a free label, because the phase is part of the execution order.
The ordering key is:
(time, phase rank, priority, spatial id, event id)
The spatial id is the smallest fragment, site, or block id the event names, or 0 when it names none. The event id is the final tie-breaker. The order never depends on dictionary insertion order or thread scheduling.
Compatibility
Event.from_disturbance_row adapts the existing femic.disturbance.v1 consumer row. The
row’s source_id becomes process_id and source, its year becomes time, and
its phase is treatment for harvest and salvage and effect otherwise. The disturbance
loader and the ws4 disturbance command keep working unchanged.
Log format
A log is one JSON object:
{
"schema_version": "ws4.event-log.v1",
"metadata": {
"scenario_id": "base",
"scenario_seed": 42,
"tape_algorithm": "philox-2x64-v1",
"package_hashes": {"fire": "<sha256>"},
"attributes": {}
},
"events": [ ... ],
"event_digest": "<sha256>"
}
The digest covers the metadata and the ordered events. Reading a log validates the schema
version, the closed top-level field set, the event records, the scenario identity, the
ordering, the uniqueness of event ids, and the digest. A mismatch fails with an
EventError rather than returning a partially valid log.
Random tape
Every primitive draw is a pure function of:
(scenario seed, process id, spatial unit id, year, draw index)
The tape uses a counter-based generator (Philox 2x64). There is no global generator and no call-order dependence. Two consequences matter for the optimizer:
Common random numbers. Two candidate schedules that ask for the same key receive the same draw. Differences between candidates are due to decisions, not noise.
Deterministic parallelism. Each spatial unit draws from its own stream, so a worker’s order does not change the result.
A caller that needs several scalar draws for one unit-year increments draw_index. A
caller that needs a vector uses size; the vector is drawn from the same counter block.
Replay
EventLog.verify_replay takes a runner from metadata to events. It rebuilds the log and
requires the same ordered event sequence. A changed event, a missing event, an extra event,
or a different scenario raises ReplayError. The runner is the process engine in a later
task; this page fixes the contract it must satisfy.
Command
ws4 ecosystem validate-log --events runs/base/events.json
ws4 ecosystem validate-log --events runs/base/events.json --json
The text report shows the scenario, seed, event count, year range, area, processes, event
types, and replay digest. --json emits the same summary as a stable JSON object.
Limits
The command validates the log, not the dataset it refers to. Referential integrity against fragments, sites, blocks, and the horizon is a later task.
No process is executed yet. The log is a record and a replay contract, not a fire model.
The random tape is one algorithm. A stored log that names another algorithm is rejected rather than silently replayed with the wrong generator.
The event record is a superset of the disturbance row, not a replacement for the FEMIC contract.