Add finite producer capture and resource-limited growth process

This commit is contained in:
dingo
2026-09-20 08:56:46 -04:00
parent 28a0e40db8
commit af293b8b50
11 changed files with 499 additions and 5 deletions
+4 -1
View File
@@ -44,7 +44,7 @@ this proof. Production indexing awaits actual interaction workloads.
| ID / objective | Files/modules | Dependencies | Completion criteria | Tests / evidence | Risk |
|---|---|---|---|---|---|
| 2.1 Ratify accounting units and ledger | accounting/ledger.*, ENERGY_MODEL, ADR-0024 | M1, units ADR | Exact local units/ranges, finite inventories and atomic ordered transfers | Unit-type separation, rollback/overflow/replay, million-transaction independent balance checks | Mistaking conservation for valid biology |
| 2.2 Add abiotic source and producer | biology/metabolism, world/resources | 2.1 | Energy enters only through named source; uptake bounded by resources | Closed-box balance plus external source accounting | Arbitrary growth subsidies |
| 2.2 Add abiotic source and producer | processes/producer.*, ADR-0025 | 2.1 | Finite source capture, whole growth recipes, carried rate remainders and atomic owned ledger | Closed-box audit, independent fractional reference, finite-resource and arithmetic limits | Confusing synthetic process with organism biology |
| 2.3 Add consumer intentions and ingestion | biology/digestion, simulation/spatial | 2.2, 1.7 | Shared validated action path transfers matter/energy | Predator/prey transfer and dead-action rejection | Consuming twice in same tick |
| 2.4 Death and decomposition | biology/lifecycle, ecology | 2.3 | Active capability ends; corpse pool transfers conserved nutrients | Death terminality, decomposition limits, ledger audit | Nutrients double counted |
| 2.5 Reproduction and wildlife identity | biology/reproduction, genome identity | 2.4, reproduction contract | Sufficient resources required; child consumes parent budget | Insufficient investment, unique ID and ancestry tests | Free offspring or implicit player ownership |
@@ -56,6 +56,9 @@ M2.1's transfer-only ledger is implemented separately from the particle world.
M2.2 must define finite source flux, process-specific restrictions, rate residuals
and the atomic boundary between biological state and its inventories. Snapshot
integration requires its own versioned format; it is not provided by M1's codec.
M2.2 now supplies the isolated synthetic process contract and implementation.
M2.3 must establish interacting process ownership before introducing consumers;
the existing fixture is not itself a complete ecosystem or an organism model.
## M3 — Genome v0.1
+11 -3
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 24 ADRs.
diagrams, biological contracts, engineering constitution and 25 ADRs.
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,8 +61,8 @@ for the bounded proof; the general production ECS remains a later measured choic
| Priority | Work | Completion evidence |
|---|---|---|
| 1 | M2.2 finite source and producer process contract | Finite flux, typed rates/residuals, restricted energy conversion and atomic inventory/process state |
| 2 | M2.3–2.6 first headless energy cycle | Producer → consumer → death → decomposition → nutrients; seeded million-tick ecosystem evidence |
| 1 | M2.3 consumer and ingestion contract | Bounded shared process state, validated feeding transfers, waste/heat accounting and terminal activity rules |
| 2 | M2.4–2.6 first headless energy cycle | Death → decomposition → nutrients and funded reproduction; seeded million-tick ecosystem evidence |
| 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 |
M1.6 now implements [the sequential scheduler contract](architecture/SCHEDULER_CONTRACT.md):
@@ -97,6 +97,14 @@ Native Release, clang-tidy, ASan and formatting passed; Gitea run 1411 passed al
Linux checks, ECS, TSan and image publication. Validation details are recorded
in the engineering validation report.
M2.2 implements a synthetic finite-source producer process owning its ledger.
It captures energy, sends conversion losses to heat, and funds whole material
recipes from reserves and finite nutrients. Fractional rates and efficiency
carry exact remainders; tick/remainders and balances commit together. Tests cover
hand-calculated outcomes, 32 seeded reference/replay runs, source and nutrient
exhaustion, invalid tick/config rejection and u64 arithmetic limits. No organism,
genome, database, process snapshot or deployment is implied by this fixture.
Before biology, resolve the relevant heredity and energetic contracts rather
than treating proof particles as organisms. Exact game tick rate, NPC mutation,
logout treatment, species/extinction rules and multicellular transition remain
+76
View File
@@ -0,0 +1,76 @@
# ADR-0025: Finite synthetic producer process
## Status
Adopted for the M2.2 headless process fixture. Not organism biology or live-world
founder creation; genotype/development and player-origin lineage remain later gates.
## Context
The ledger conserves inventories but permits arbitrary transfers. Producer rules
must constrain usable energy, finite source capture, growth costs and rounding,
and commit their own state with inventories. No database is needed for this proof.
## Decision
Add an independently tested `evo::processes` library with `ProducerProcess` owning
one ledger. Four fixed reservoirs hold source energy, nutrient matter, producer
reserve/structure, and heat. Opening source energy and nutrients are explicit;
producer and heat start empty. Inspection is read-only; no arbitrary transfer API
or mutable ledger escapes. Heat never funds capture or growth.
Each exact next logical tick performs capture then growth. Capture quota is
integer picojoules per positive integer number of ticks. Consume at most this
quota and available source energy. A fixed efficiency in thousandths splits the
actual capture into producer reserve and heat. Growth quota is integer recipe
units per positive integer number of ticks. Each recipe unit requires a positive
energy cost and a nonzero C/N/P/other matter bundle; growth is the minimum of its
quota and all available energy/material constraints. Matter moves intact from
nutrients to producer structure; growth energy moves from reserve to heat.
Maintain separate remainder counters for capture rate, growth rate and conversion
efficiency. Quotient/remainder arithmetic avoids wide multiplication and retains
sub-quantum entitlement without floating point. Unfulfilled whole quotas are
discarded; they cannot accumulate while the source or nutrients are exhausted.
Fractional remainders persist. Conversion remainder follows actual captured
energy, never unfunded quota. Remainders are not additional physical inventory.
Compute the report and next remainders first, submit four ordered ledger legs
as one transaction with action ID equal to target tick, then publish scalar state
without throwing. A failed or duplicate/late/future tick changes nothing. The
first tick is 1. No host clock, variable dt, network, persistence or hidden RNG.
One owner provides sequential access. Copies are experiment branches only.
## Alternatives Considered
Public ledger access could recycle heat. Independent process/ledger commits could
lose fractional state or double-fund growth. Floating rates lose exact residuals.
A general dimensional library remains a gate before physical flux/area/time
equations; this fixture only divides already typed inventory quotas by tick
counts and does not choose watts, geometry, photosynthetic chemistry or a game rate.
## Benefits
Finite-source producer behavior, explicit heat losses, exact conserved matter,
resource-limited growth and atomic process/accounting state.
## Costs
One producer and four reservoirs only; no interactions, maintenance, starvation,
reproduction or persistent state format. Full ledger copying per tick remains
the bounded correctness baseline. Efficiency and recipe parameters are synthetic.
## Risks
Conservation alone cannot establish biochemical plausibility. Recipe units are
not cells or organisms. Rate remainder retention is a scoped fixture policy and
must be reviewed for future changing rates or resource replenishment. The finite
source models a prepaid budget, not a star that shuts off when locally depleted.
## Consequences
Tests must cover fractional rates/conversion, 0/100% capture, zero rates, source
and element exhaustion, energy-limited growth, u64 extremes, tick rejection,
copy/replay and independently recomputed conservation. A later process snapshot
must contain all inventories, config, tick and remainders together; M1's snapshot
does not serialize any of this. No production migration/version changes now.
+1
View File
@@ -17,6 +17,7 @@ Each record has the eight required sections.
0022 adopts the bounded sequential lifecycle-command scheduler for the proof.
0023 defines local periodic neighborhood queries and a measured linear baseline.
0024 adopts finite, typed energy/matter inventory transfers for M2.1.
0025 scopes finite capture, growth recipes and residual accounting for M2.2.
Every dependency adoption records exact version/commit and integrity hash,
transitive license obligations, maintenance/security review, owner and removal
+2 -1
View File
@@ -48,6 +48,7 @@ the simulation state. Durable account references live in orchestration mapping.
| core | Value types, deterministic algorithms, explicit version constants | Global state, threads, I/O |
| simulation (`evo_simulation`, alias `evo::simulation`) | State, stable tick ordering, component lifecycle, pure restore validation | Wall clock, transport, database or rendering |
| accounting (`evo_accounting`, alias `evo::accounting`) | Typed finite inventories, atomic conserved transfers, in-memory action watermark | Chemistry, minting resources, entity lifecycle or durable storage |
| processes (`evo_processes`, alias `evo::processes`) | Synthetic source/producer rules and atomic process/accounting state | Live organism ancestry, persistence, heat recycling or external I/O |
| biology | Genotype → development → phenotype; energetic transfers | Account rewards, player/NPC subclasses |
| world | Procedural base identity, spatial/environmental fields | Dense planet allocation, gameplay authority |
| persistence | Durable metadata, snapshots, replay batches, migration | Per-tick simulation decisions |
@@ -55,7 +56,7 @@ the simulation state. Durable account references live in orchestration mapping.
| backend | Identity adapters, account/world metadata, history queries, directory/lease coordination | Every noun deployed as a service |
| app / server | Tick pacing, I/O ownership, durable outcome barrier, metrics export | Alternative biological implementation |
Core, simulation, local snapshot codec, accounting and `evo-sim` are source modules
Core, simulation, local snapshot codec, accounting, processes and `evo-sim` are source modules
in the proof. Accounting has an independent tested contract; it is not yet wired
into particle state. Future rows are boundaries, not empty directories or dummy services.
Split a library when a real independently tested contract exists.
+29
View File
@@ -117,3 +117,32 @@ process operations and finite flux budgets. Never treat conservation as biologic
validity. There is no import/mint API, organism lifecycle, persisted ledger codec
or cross-ledger transaction in M2.1. Persistent integration must checkpoint both
inventories and action watermark atomically; M1 snapshots do not include them.
## Implemented M2.2 synthetic producer
[ADR-0025](../adr/0025-finite-producer-process.md) defines the independent
`evo::processes::ProducerProcess` fixture. It owns four reservoirs and exposes only
read-only balances and exact-next-tick advancement. Source energy and C/N/P/other
substrates are finite opening inventories. Capture divides actual source uptake
between reserve and heat. Growth moves a configured whole recipe from substrates
to structure and its energy cost from reserve to heat. The API cannot reuse heat.
```mermaid
flowchart LR
S[Finite source energy] -->|rate-limited capture| R[Producer reserve]
S -->|conversion loss| H[Heat]
N[Finite substrates] -->|funded recipe units| B[Producer structure]
R -->|growth energy cost| H
```
Rates are rational inventories/recipe units per integer tick count. Independent
carried remainders preserve capture, growth and efficiency fractions. Unfunded
whole quotas expire; no starvation debt or future burst accumulates. Remainders
and tick advance only after the ledger transaction succeeds. Arithmetic uses
quotient/remainder decomposition, not overflow-prone numerator multiplication.
This is a synthetic process, not a biological founder or organism. Its parameters
do not select photosynthetic chemistry, area, metabolic efficiency, world time
or the final units library. No producer state is attached to the particle world,
serialized, connected to PostgreSQL or deployed. Later persistent integration
must include config, reservoirs, tick and all three remainders in one checkpoint.
+18
View File
@@ -210,3 +210,21 @@ configuration passed 6/6 CTests. Ledger-suite times were 3.34s GCC Debug, 0.37s
Release, 2.46s Clang analysis and 8.78s Clang ASan/UBSan; these are CI test
durations, not controlled performance benchmarks. The image smoke/publication
job also passed, completing all four jobs. No deployment image pin was changed.
## M2.2 finite producer process (2026-09-19)
Native Release, clang-tidy and MSVC ASan passed 7/7 CTests; format-check passed.
Commands: `tools/windows-check.ps1 -Preset <release|analysis|asan> -Action check`
and Release `-Action format`. The producer suite compares hand-calculated ticks
and 32 seeds × 1,000 ticks against a small-domain cumulative arithmetic reference,
an independent replay branch and per-tick energy/element conservation audits.
It covers invalid config/ticks with unchanged state, fractional capture/growth,
efficiency endpoints, finite source exhaustion, all four limiting elements,
zero capture, maximum u64 capture with 50% carried conversion, and maximum recipe
and growth-cost multiplication. Particle goldens remain unchanged.
Allocation-failure injection and tick-counter exhaustion were not exercised;
the latter has an explicit guard but no arbitrary-state restore API. Tests use
in-memory copies, not serialized recovery. No photosynthetic chemistry, metabolic
model, database integration, throughput guarantee or deployment is claimed.
Linux CI is pending this source push.