# PreyLab resource accounting (F08, local model 14)

This is an observer diagnostic, not a cell sense. The engine uses model mass and model energy units; it does not predict biochemical calories. Light is the only modeled ambient energy supply. Oxidants and molecular chemistry are implicit. Automatic nutrient feeding adds **mineral mass**, not fuel. Deliberate scavenger feeding adds both mass and a declared organic energy budget.

## Pools and identities

| Pool | Material | Recoverable energy | Source |
| --- | ---: | ---: | --- |
| Living body, coat, toxin store, food vacuole | Yes | Usable `energy`, `reserve`, vacuole `energy` only | `population.js:materialTotal`; `accounting.js:recoverableEnergy` |
| Gamete and spore | `mass` | `energy` | `propagules.js` |
| Corpse | `mass` | `energy` | `population.js:depositCorpse` |
| Suspended detritus | 192 mass bins | Matching 192 `detritusEnergy` bins | `population.js:depositAt/withdrawDetritus` |
| Dissolved nutrient, nutrient patch | Yes | Zero | `ecology.js`; `population.js:decay` |
| Chemical packet | Yes | Zero; secretion fuel is spent at release | `chemistry.js` |

Structural mass does not imply recoverable energy. Energy in usable, reserve or vacuole pools is counted once even though the same organism has body mass. `foodEnergy` changes the fraction of that **existing** fuel transferred at predation: `clamp(0.2 + 0.5 × allele, 0, 1)` for algae, with the 200-unit meal limit; nonalgae transfer 78%. Its 0.5–1.6 range therefore gives 45–100% recovery. The historical multiplier that could award more fuel than the prey held was removed. The inherited allele and genome version 2 remain unchanged; old catalog snapshots retain their original locus values under this corrected interpretation.

The observer identity is `recoverable now + dissipated + exported = initial recoverable + captured light + deliberate external energy + residual`. `recoverable now` is scanned independently from living cells, propagules, corpses and detritus fuel. The signed residual and tolerance `1e-7 + 1e-10 × max(current, expected)` are displayed, never corrected by altering resources. The material report uses the existing `materialTotal` convention, which already includes cumulative `metabolicSink` and manual removal: `materialTotal = initialMineral + externalMineral + residual`. Checkpoints occur at most every 5 simulated seconds and retain 72 samples; pathway totals are bounded.

## Conversion rules

| Event | Input → destination | Loss, limit and refusal |
| --- | --- | --- |
| Photosynthesis | Light + withdrawn mineral → usable fuel | `model.js:step` and `population.js:feedPrototype`; available light, temperature, nutrient and fuel room limit capture. The withdrawn mineral enters the existing metabolic sink convention. |
| Reserve charge/mobilize | Usable → reserve → usable | `model.js:step`: 80% charge, 85% mobilization. Missing energy dissipates. Capacity comes from storage investment. |
| Active movement/upkeep, signaling, toxin and chemical release | Usable fuel → dissipated | Actual deductions in `model.js`, `grazer.js`, `signals.js`, `chemistry.js`, `toxicology.js`, `population.js`. Insufficient stores block or weaken release under existing rules. |
| Body/coat construction | Dissolved mineral + usable fuel → structure | 4 energy per body mass; 8 per coat mass. Energy and mineral availability bound construction. |
| Predation | Prey body → vacuole mass; fraction of prey fuel → vacuole energy | Remaining prey fuel dissipates. The prey is removed once. Existing diet, XYZ contact, handling and vacuole limits still apply. |
| Death | Body and food mass → corpse; usable, reserve and vacuole fuel → corpse energy | No energy is awarded for body mass itself. Manual erase exports both remaining material and fuel. |
| Scavenging | Corpse/detritus mass and its proportional remaining fuel → consumer | Omnivore vacuole stores only withdrawn corpse fuel. Crawlers and attached decomposers recover at most 78% × temperature factor; growth also pays 4 fuel per mass. Zero-fuel mineral remains cannot power feeding. |
| Algal debris metabolism | Detritus mass returned as spent debris; at most 78% of its measured fuel → usable | Remaining fuel dissipates. The allele enables the pathway but no longer creates fuel from mineral mass. |
| Corpse decay | Corpse mass → patch/detritus/rot packet; fuel follows detritus share | Fuel proportional to mineralized/rot material dissipates. Detritus mineralization spends the corresponding bin fuel. |
| Propagule release/fusion/expiry | Parent body + fuel → viable unit → offspring or spent detritus | Existing cap/space checks precede birth. Zygote fusion spends 2 energy; expired unit fuel dissipates. Failed placement retains the viable unit. |
| Deliberate scavenger feeding | External organic dose → detritus | 26 energy per mass unit is explicitly added to `ledger.externalEnergy`; ordinary nutrient dosing adds no fuel. |

Operations are ordered by the normal 20 ms simulation step. Release and birth continue through their existing functions; observer diagnostics do not create packets, organisms or nutrients. Renderer, focus and camera settings are excluded from the resource equations.

## Archive migration and compatibility

Population schema 14 adds `detritusEnergy[192]`, corpse `energy`, and bounded `accounting`. Version 13 and earlier archives receive **zero** unknown historical corpse/detritus fuel on the first migration. That is a conservative estimate, labeled `legacy-estimate`, never a repeated grant. `legacyEnergySnapshot` retains the preconversion detritus/corpse representation for review. Living usable energy, reserves, vacuole fuel, propagule fuel, identity, genome, ancestry and archive permissions remain untouched. A version 14 reload preserves the same origin, counters, pools and checkpoint history. Archive revision tokens and single-writer rules are unchanged. DNA remains design data and does not contain energy pools. Portable environment v1 has no organism or detritus fuel state.

## Reproduce and inspect

Use Settings → App → **Resource Accounting** for material, recoverable fuel, external inputs, dissipation, output and residual; **Export Trial Report** downloads bounded JSON. For a dark finite-source check: create an empty dish, turn the lamp and automatic nutrient feed off, place an alga and a floor scavenger, let the alga die, and observe corpse fuel move to detritus while the residual remains near zero. Use a deliberate scavenger feed to add a disclosed external organic dose. A dark mineral-only dish can retain inert cells but cannot gain usable energy from repeated mineral recycling.

Focused `test/preylab-accounting.test.mjs` covers funded prey yield, corpse decay/reload, deliberate feed and legacy migration. `scripts/verify-preylab-accounting-local.mjs` exercises real Lucee/MySQL POST → GET → revision POST → GET → next step. The local archive check on 2026-10-20 used archive `57303635-f79f-43c7-8790-688a80cea583`: 123.056008122 energy before reload, 123.033736443 after the next 20 ms step; signed residuals were 0 and 9.9e-13. JSON serialization rounds to roughly 12 decimal places. No offline catch-up was applied.

The full Node suite recorded 322 tests before the change (296 pass, 25 fail, one skipped) and 326 afterward (300 pass, 25 fail, one skipped). Its 25 failing test names are identical; the full outputs are in `preylab/evidence/f08-baseline-test.log` and `preylab/evidence/f08-final-test.log`. The seven focused accounting checks pass. This failure-name comparison is a regression screen, not proof that every old stochastic assertion is stable.

This local pass does not prove every multi-event ecosystem path balanced under all settings. The observer residual is deliberately exposed for cases not yet traced. Physical-phone FPS and a true 390×667 browser emulation were unavailable in this run. No production deployment was performed.