Document M6.5 persistence prerequisite and resolution proposal

This commit is contained in:
dingo
2026-09-27 09:18:14 -04:00
parent 70cd288327
commit 407477ec06
5 changed files with 129 additions and 1 deletions
+5
View File
@@ -435,3 +435,8 @@ M4.6 completed as measurement tooling and a policy review on 2026-09-26; see
[aggregate budget report](engineering/AGGREGATE_BUDGET.md). No automatic tier policy
qualified. M5 may proceed independently; production tier selection needs the
fidelity and target-host follow-ups listed in that report.
M6.5 sequencing review: [ADR-0054](adr/0054-m65-source-persistence-prerequisite.md)
is proposed because ADR-0051 requires persistence before rates while ADR-0053 defers
coupled persistence to M6.8. Its recommended prerequisite and task breakdown are
pending scope confirmation; the M6.5 completion criteria above remain unchanged.
+11 -1
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 53 ADRs.
diagrams, biological contracts, engineering constitution and 54 ADRs (including the proposed M6.5 prerequisite).
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).
@@ -653,3 +653,13 @@ rollback, changed retries, independent compartment balances and conservation.
This is in-memory ownership; no coupled recovery format or durable ACK is claimed.
No schema, simulation version, dependency or deployment changed. Next: M6.5 biology
adapters, including explicit conversion and active/alive validation.
## M6.5 prerequisite review (2026-09-27)
Implementation is pending resolution of [ADR-0054](adr/0054-m65-source-persistence-prerequisite.md).
ADR-0051 requires persisted source rate/residual/interval state before rate execution;
ADR-0053 defers the coupled format until M6.8. Recommended resolution: bring the
minimal coupled buffer codec forward, preserving the earlier guarantee. The proposal
breaks M6.5 into codec, explicit biological conversion contract, rate-driven fixture,
and qualification segments. No source-rate code or public interface changed in this
review; M6.5 remains incomplete. M6.4's validated behavior is unchanged.
@@ -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.
+1
View File
@@ -60,3 +60,4 @@ design. No unadopted candidate is a link dependency of the proof.
- [ADR-0051: Optional environmental fields](0051-optional-environmental-fields.md) - accepted for M6.2 finite sparse pages, local transfers and field snapshot v1.
- [ADR-0052: Environment views](0052-read-only-environment-views.md) - accepted for M6.3 bounded read-only footprint queries and freshness validation.
- [ADR-0053: Atomic environmental transfers](0053-atomic-environmental-transfers.md) - accepted for M6.4 tagged resource ownership, atomic local batches and bounded exact retries.
- [ADR-0054: M6.5 source persistence prerequisite](0054-m65-source-persistence-prerequisite.md) - proposed resolution of rate-persistence versus M6.8 sequencing; not implemented.
+8
View File
@@ -1792,3 +1792,11 @@ This evidence covers local in-memory atomicity. Coupled snapshots, allocation-fa
injection, process crash recovery and biological lifecycle integration are not claimed.
Linux/UBSan/TSan were not run locally; their existing Gitea jobs remain required CI
evidence. No cluster workload or World0 state was changed.
## M6.5 prerequisite review - 2026-09-27
Documentation-only review identified contradictory source-persistence sequencing in
ADRs 0050/0051 and 0053. ADR-0054 proposes a resolution; it is not accepted or
implemented. `git diff --check` passed. No source, public API, test, schema or build
configuration changed, so builds/sanitizers were not rerun for this proposal. The
M6.4 validation above remains historical evidence, not M6.5 completion evidence.