Files
aevolution/docs/adr/0054-m65-source-persistence-prerequisite.md
T
2026-10-08 12:08:53 -04:00

7.0 KiB

[Reviewed]

ADR-0054: M6.5 source persistence prerequisite

Status

Accepted by the maintainer, 2026-09-27. Bring coupled snapshot/restore into M6.5. M6.4 remains complete as a scoped in-memory transfer primitive. M6.5 follows the segments below and is not yet complete.

Context

The accepted contracts disagree about when coupled persistence is required:

  • ADR-0051, 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, Consequences: "M6.2-6.4 must persist units/version, mapping, compartments, source residuals and ownership atomically".
  • ADR-0053, Costs: "No persistence API for this owner until the combined-state gate."
  • M6.5 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

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

Acceptance brings the minimal coupled codec forward; revise scoped references together. Until complete rate/biology state is serialized, do not enable rate integration or report M6.5 as implemented. Existing tests and deployed behavior remain unchanged.