From e7fec914e792bea49623f28599a8f6f39c5d21e6 Mon Sep 17 00:00:00 2001 From: dingo Date: Sat, 10 Oct 2026 22:04:48 -0400 Subject: [PATCH] Use region-wide cellular conservation totals --- docs/adr/0108-cellular-checkpoint-profile.md | 14 ++--- ...09-cellular-region-conservation-closure.md | 53 +++++++++++++++++++ docs/adr/README.md | 1 + docs/engineering/M11_3_DELIVERY_PLAN.md | 9 ++-- docs/engineering/VALIDATION.md | 5 +- schemas/cellular-lives-v1.md | 11 ++-- 6 files changed, 76 insertions(+), 17 deletions(-) create mode 100644 docs/adr/0109-cellular-region-conservation-closure.md diff --git a/docs/adr/0108-cellular-checkpoint-profile.md b/docs/adr/0108-cellular-checkpoint-profile.md index 99c1afb..9956883 100644 --- a/docs/adr/0108-cellular-checkpoint-profile.md +++ b/docs/adr/0108-cellular-checkpoint-profile.md @@ -23,8 +23,8 @@ together, and ADR-0107 additionally produces corpses and a heat transfer. the exact profile and version bundle of its predecessor. - The envelope is a complete single-region state closure, not a tick delta. It binds world, region, frame, the current 50 ms simulation tick and the cellular - rule/version bundle. It contains the finite habitat and its explicit opening - totals by source, every living life, every retained corpse, accumulated heat, + rule/version bundle. It contains the finite habitat and its explicit + region-wide opening totals, every living life, every retained corpse, accumulated heat, and the complete lineage archive. No field may be reconstructed from an absent section or a default. - Each living record binds its life/account identity (when player-controlled) @@ -40,10 +40,12 @@ together, and ADR-0107 additionally produces corpses and a heat transfer. living organism set; every live genome reference resolves; every birth/death is no later than the checkpoint tick; player account bindings are unique; all positions and footprints are inside the finite area; and all inventories, - corpses, habitat stock and heat satisfy their channel rules. For each source, - current stock plus all downstream holdings must reconcile to its explicit - opening total. Restore performs full validation and requires byte-identical - canonical re-encoding before readiness. + corpses, habitat stock and heat satisfy their channel rules. Every current + owner reconciles per channel to the explicit region-wide opening totals; + patch source labels remain opening provenance and are not propagated through + mixed inventories ([ADR-0109](0109-cellular-region-conservation-closure.md)). + Restore performs full validation and requires byte-identical canonical + re-encoding before readiness. - Cap the envelope at 8 MiB, with at most 256 living cells, 4,096 provisioned patches and 65,536 retained organisms/corpses. Validate lengths and counts before allocation. The existing archive and habitat codecs are nested with diff --git a/docs/adr/0109-cellular-region-conservation-closure.md b/docs/adr/0109-cellular-region-conservation-closure.md new file mode 100644 index 0000000..9938c5e --- /dev/null +++ b/docs/adr/0109-cellular-region-conservation-closure.md @@ -0,0 +1,53 @@ +# ADR-0109: Cellular region-wide conservation closure + +## Status + +Accepted M11.3 engineering correction to ADR-0108 (2026-10-10). Patch source +provenance remains unchanged. No gameplay rule or resource quantity changes. + +## Context + +ADR-0101 stores a source identity on each provisioned food patch. After uptake, +however, its energy and matter join a life's reserve and may later move between +reserve, body, heat and corpse. The existing `Inventory` ledger has no per-source +dimension, so it cannot truthfully report which source a mixed reserve came +from. ADR-0108's initial wording required per-source downstream reconciliation, +which would require tagging every inventory channel with provenance and would +change the accounting model. + +## Decision + +- Keep each patch's immutable source identity as opening provenance. Do not + propagate source tags through living inventories, heat or corpses. +- Profile 4 stores one explicit initial region total for each conserved channel. + The total includes all provisioned patch stocks, nursery funding and other + opening inventories. Every checkpoint validates that current habitat stock, + nursery balances, living body/reserve/heat, region heat, corpses and any other + explicit owner sum exactly to that initial total, channel by channel. +- Any external transfer after genesis must be represented as an explicit + versioned opening/closing transfer in the same durable publication. M11.3 has + no replenishment or cross-scale transfer, so its region total is constant. + +## Alternatives considered + +- **Per-source tagged balances:** rejected because the existing ledger and + biology contracts have no such dimension; copying source tags into every + transformed holding would be a new accounting model with additional storage + and rules. +- **Discard patch provenance on intake:** rejected because ADR-0101 requires + provenance to remain available for audit of the opening. +- **Check only that individual transfers conserve:** rejected because recovery + also needs a closed-world invariant that detects missing or duplicated owners. + +## Benefits and costs + +The existing four independent inventory channels remain the accounting unit, +and provenance stays auditable at the environmental opening. The checkpoint +cannot answer how much downstream biomass originated from one particular +patch source after mixing. + +## Consequences + +ADR-0108 and `schemas/cellular-lives-v1.md` use region-wide totals, not +per-source totals. The cellular owner must carry those totals through restore +and validate all represented accounts before publication and readiness. diff --git a/docs/adr/README.md b/docs/adr/README.md index f8d2c36..a7dc439 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -9,6 +9,7 @@ - [ADR-0106: Cellular contested patch arbitration trial](0106-cellular-contested-patch-arbitration.md) - accepted M11.3 trial resolves same-tick finite-stock claims by stable life identity, independent of connection order. - [ADR-0107: Cellular starvation and corpse transfer trial](0107-cellular-starvation-and-corpse-transfer.md) - accepted M11.3 death closure transfers body/reserve to a corpse and accumulated heat to the region heat owner. - [ADR-0108: Cellular life checkpoint profile](0108-cellular-checkpoint-profile.md) - accepted additive profile-4 state-closure direction; codec, SQL admission and recovery remain open. +- [ADR-0109: Cellular region-wide conservation closure](0109-cellular-region-conservation-closure.md) - corrects profile-4 accounting to conserved region totals per channel while retaining patch provenance. - [ADR-0058: Region durability contract](0058-region-durability-contract.md) - accepted M7.1 full checkpoint batches and explicit state closure; storage implementation follows. diff --git a/docs/engineering/M11_3_DELIVERY_PLAN.md b/docs/engineering/M11_3_DELIVERY_PLAN.md index 94e11e0..afa1826 100644 --- a/docs/engineering/M11_3_DELIVERY_PLAN.md +++ b/docs/engineering/M11_3_DELIVERY_PLAN.md @@ -74,9 +74,10 @@ No new dependency or renderer is required. If the selected spatial, checkpoint, or publication design conflicts with accepted architecture, stop that affected implementation and resolve the contract first. -ADR-0108 and `schemas/cellular-lives-v1.md` define an additive profile-4 state -closure while preserving profile 3. This is a contract only: codec/restore, SQL -allowlisting, a cellular region owner and crash-recovery evidence are still +ADR-0108/0109 and `schemas/cellular-lives-v1.md` define an additive profile-4 +state closure with region-wide channel conservation while preserving profile 3. +This is a contract only: codec/restore, SQL allowlisting, a cellular region owner +and crash-recovery evidence are still required before the first hands-on cellular probe. ## Delivery segments @@ -150,7 +151,7 @@ scoped change before starting the next segment. - 11.3c-5: ADR-0107 closes unaffordable maintenance in the same tick, moving body and reserve into a corpse candidate and accumulated heat to an explicit output. The durable heat owner and lineage/checkpoint publication remain open. -- 11.3d contract: ADR-0108 and `schemas/cellular-lives-v1.md` define a separate +- 11.3d contract: ADR-0108/0109 and `schemas/cellular-lives-v1.md` define a separate profile-4 checkpoint closure for lives, habitat, corpses, heat and lineage. No profile-4 code or durable tick publication is implemented yet. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index 9f49a5d..fd293ae 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -6022,8 +6022,9 @@ remain pending. ## 2026-10-10 — M11.3d profile-4 closure contract (implementation pending) -ADR-0108 and `schemas/cellular-lives-v1.md` specify an additive complete -cellular checkpoint while preserving profile 3. This is documentation only; +ADR-0108/0109 and `schemas/cellular-lives-v1.md` specify an additive complete +cellular checkpoint with region-wide channel conservation while preserving +profile 3. This is documentation only; no codec, SQL admission or recovery behavior is implemented or validated by this entry. `git diff --check` is the applicable local check. Profile-4 code, PostgreSQL CI and crash/restart tests remain required. diff --git a/schemas/cellular-lives-v1.md b/schemas/cellular-lives-v1.md index cba26f1..83e5f62 100644 --- a/schemas/cellular-lives-v1.md +++ b/schemas/cellular-lives-v1.md @@ -9,7 +9,7 @@ It is the complete payload for region checkpoint profile 4, The canonical little-endian envelope carries explicit lengths and versions for the region identity, 50 ms current tick, finite cellular area, provisioned -habitat and source opening totals, ordered living-cell records, ordered corpse +habitat and region-wide opening totals, ordered living-cell records, ordered corpse records, region heat and the complete lineage archive. Integers have fixed widths; records are sorted by stable identity/address. Decoders reject unknown versions, nonzero reserved fields, duplicate or noncanonical records, @@ -29,10 +29,11 @@ must exactly match or the payload is refused. Each corpse retains the dead organism identity, death tick, final position and transferable body/reserve inventory. Heat is a separate energy-only region -account. The habitat carries its finite patch stock and provenance plus the -explicit opening total for each source. For every ledger channel and source, -opening holdings must reconcile exactly to current habitat, living bodies and -reserves, corpses and heat according to the declared transfers. +account. The habitat carries its finite patch stock and immutable source +provenance. For every ledger channel, region-wide opening holdings must +reconcile exactly to current habitat, nursery, living bodies and reserves, +corpses and heat according to the declared transfers. Resource amounts do not +retain per-source tags after they leave a patch (ADR-0109). Restore requires exact world/region/frame and end-tick agreement with the manifest, complete organism/genome/archive closure, unique player bindings,