|
|
|
@@ -0,0 +1,104 @@
|
|
|
|
|
# ADR-0054: M6.5 source persistence prerequisite
|
|
|
|
|
|
|
|
|
|
## Status
|
|
|
|
|
Proposed, 2026-09-27. No rate-driven implementation is authorized by this proposal.
|
|
|
|
|
M6.4 remains complete as a scoped in-memory transfer primitive. M6.5 is pending
|
|
|
|
|
resolution of the prerequisite below, not complete.
|
|
|
|
|
|
|
|
|
|
## Context
|
|
|
|
|
The accepted contracts disagree about when coupled persistence is required:
|
|
|
|
|
|
|
|
|
|
- [ADR-0051](0051-optional-environmental-fields.md), Decision: "Before
|
|
|
|
|
adding rates, persist rate identity, denominator, residual and interval watermark in
|
|
|
|
|
a new compatible format or explicit migration; never synthesize these on restore."
|
|
|
|
|
- [ADR-0050](0050-environmental-units-and-coupling.md), Consequences:
|
|
|
|
|
"M6.2-6.4 must persist units/version, mapping, compartments, source residuals and ownership atomically".
|
|
|
|
|
- [ADR-0053](0053-atomic-environmental-transfers.md), Costs:
|
|
|
|
|
"No persistence API for this owner until the combined-state gate."
|
|
|
|
|
- [M6.5](../ROADMAP.md) requires defined source flux funding capture;
|
|
|
|
|
M6.8 currently owns integrated snapshot/restore. The units contract additionally
|
|
|
|
|
requires an area-budgeted rational pJ/tick rate in M6.5.
|
|
|
|
|
|
|
|
|
|
Field snapshot v1 cannot encode organism accounts, retry history, source identity,
|
|
|
|
|
rate configuration, residual or interval progress. Saving fields and a sidecar after
|
|
|
|
|
separate commits would not satisfy atomic restore. M5 LocalWorldFiles publishes
|
|
|
|
|
terrain state only. Existing in-memory M2 ProducerProcess is not a persistence
|
|
|
|
|
solution and its separate ledger cannot become a second spendable copy of fields.
|
|
|
|
|
|
|
|
|
|
The repository working agreement requires stopping affected implementation and
|
|
|
|
|
proposing a resolution when architecture conflicts. This record exposes the mismatch
|
|
|
|
|
rather than silently interpreting the later scope statement as superseding ADR-0051.
|
|
|
|
|
|
|
|
|
|
## Decision (recommended, pending scope confirmation)
|
|
|
|
|
Bring the minimal coupled binary-buffer snapshot/restore contract forward into the
|
|
|
|
|
M6.5 prerequisite. Keep durable filesystem publication and region crash recovery in
|
|
|
|
|
M7; a canonical buffer codec is not a durable acknowledgment or fencing mechanism.
|
|
|
|
|
Explicitly amend ADR-0053's deferral and roadmap sequencing upon acceptance. Leave
|
|
|
|
|
ADR-0051's no-unpersisted-rates requirement intact.
|
|
|
|
|
|
|
|
|
|
Do not add a field-only rate codec: the first rate-enabled fixture must restore one
|
|
|
|
|
aggregate containing all state that can affect its continuation. Introduce a new
|
|
|
|
|
versioned fixture envelope; preserve terrain and field v1 formats as nested payloads.
|
|
|
|
|
Reject partial, incompatible or malformed aggregates before publishing any owner.
|
|
|
|
|
No migration of a field-only snapshot may invent organism balances or source history.
|
|
|
|
|
|
|
|
|
|
### Reviewable implementation order
|
|
|
|
|
|
|
|
|
|
| Segment | Objective and affected modules | Acceptance and tests | Main risk |
|
|
|
|
|
|---|---|---|---|
|
|
|
|
|
| 6.5a | Define coupled state and codec schema; world transfer owner, schemas, tests | Canonical round trip of terrain binding, fields, accounts/capacities, command watermark and full retry window; exact retry after restore; malformed lengths/versions/history and budget rejection | Valid inventories with lost idempotency |
|
|
|
|
|
| 6.5b | Define versioned producer/consumer fixture rules and conserved conversions; processes contract and narrow world transaction boundary | Review explicit incident-to-reserve/heat and dissolved-to-organic nutrient mappings; water remains water; feeding moves existing biomass; all inventories have one owner | Arbitrary retagging disguised as biology |
|
|
|
|
|
| 6.5c | Implement fixture plus complete rate/biology envelope before enabling advance; processes adapter and codec tests | Save immutable rate/source identity, numerator/denominator, area, residuals, last interval, biological config, progress and lifecycle with 6.5a state; restore reproduces next outcome | Scalar progress committed separately from inventories |
|
|
|
|
|
| 6.5d | Qualify M6.5 and update gate status | Source-off/starvation, nutrient/water limits, temperature boundaries, seeded replay, independent conservation, failed-step rollback, stale/duplicate input, Release/tidy/sanitizers | Synthetic coefficients silently becoming game rules |
|
|
|
|
|
|
|
|
|
|
M6.8 retains the full producer-consumer-death-decomposition-regrowth integration,
|
|
|
|
|
long-run ecology and cost report. Earlier codec coverage does not mark M6.8 complete.
|
|
|
|
|
No database, networking, graphics, dependency or deployment is needed for 6.5a-d.
|
|
|
|
|
|
|
|
|
|
### Biology questions to settle in 6.5b
|
|
|
|
|
|
|
|
|
|
M6.4 intentionally permits only same-tag transfers. M6.5 needs explicit capture
|
|
|
|
|
conversion and nutrient incorporation plus organism-to-organism feeding. Extend the
|
|
|
|
|
transaction boundary with a restricted process contract, not mutable store access or
|
|
|
|
|
external credit/debit setters. Publication must include process progress and resources
|
|
|
|
|
in one nonthrowing phase. Use no live duplicate M2 ledger.
|
|
|
|
|
|
|
|
|
|
Specify the finite source allocation and projected area bound, including fractional
|
|
|
|
|
entitlement under source exhaustion. Preserve the M6.1 rule that an unfunded source
|
|
|
|
|
integration cannot advance its residual/watermark. Define how the enclosing fixture
|
|
|
|
|
tick reports that condition without silently adopting M2's different quota policy.
|
|
|
|
|
|
|
|
|
|
Name the carbon and organic-other inputs explicitly: there is no inorganic-carbon
|
|
|
|
|
field, and neither terrain nor water is edible carbon/other. Any experiment using
|
|
|
|
|
prepaid organic carbon must describe itself as a synthetic resource fixture, not a
|
|
|
|
|
complete photosynthetic chemistry model. Read-only temperature is a host fixture
|
|
|
|
|
input until a thermal field exists. Reuse documented M3 budget rules where applicable;
|
|
|
|
|
no new maintenance, reproduction, resurrection or offline progression policy is implied.
|
|
|
|
|
|
|
|
|
|
## Alternatives Considered
|
|
|
|
|
1. **Strictly in-memory M6.5 exception.** Explicitly amend ADR-0051 and the units
|
|
|
|
|
contract to permit rate state in a nonserializable fixture until M6.8. Smaller
|
|
|
|
|
immediate gate, but moves restore-continuation evidence later. Must prohibit any
|
|
|
|
|
claim that field snapshots can resume it. Requires an explicit scoped decision.
|
|
|
|
|
2. **Only fixed stock uptake.** Insufficient: does not demonstrate the required
|
|
|
|
|
area-budgeted source rate and capture conversion. Cannot mark M6.5 complete.
|
|
|
|
|
3. **Independent sidecar or second ledger.** Reject: permits inconsistent recovery
|
|
|
|
|
cuts or duplicated authority and does not preserve the coupled contract.
|
|
|
|
|
|
|
|
|
|
## Benefits
|
|
|
|
|
Preserves existing persistence expectations, exposes the sequencing conflict, and
|
|
|
|
|
makes rate remainders/retry history part of executable continuation tests early.
|
|
|
|
|
|
|
|
|
|
## Costs
|
|
|
|
|
M6.5 grows to include a bounded codec and hostile-input tests previously scheduled
|
|
|
|
|
for M6.8. A complete fixture format needs an explicit version before rate execution.
|
|
|
|
|
|
|
|
|
|
## Risks
|
|
|
|
|
Premature schema generalization; constrain the envelope to this bounded fixture.
|
|
|
|
|
Buffer round trips do not prove disk crash consistency, host-loss safety or region
|
|
|
|
|
ownership. Keep those delivery gates separate and unclaimed.
|
|
|
|
|
|
|
|
|
|
## Consequences
|
|
|
|
|
After acceptance, revise the scoped ADR and roadmap references together before code.
|
|
|
|
|
Until then, do not enable rate integration, weaken persistence requirements, or report
|
|
|
|
|
M6.5 as implemented. Existing tests and deployed behavior remain unchanged.
|