From 407477ec063812fc08a05730d38786aec4861eb7 Mon Sep 17 00:00:00 2001 From: dingo Date: Sun, 27 Sep 2026 09:18:14 -0400 Subject: [PATCH] Document M6.5 persistence prerequisite and resolution proposal --- docs/ROADMAP.md | 5 + docs/STATUS.md | 12 +- ...054-m65-source-persistence-prerequisite.md | 104 ++++++++++++++++++ docs/adr/README.md | 1 + docs/engineering/VALIDATION.md | 8 ++ 5 files changed, 129 insertions(+), 1 deletion(-) create mode 100644 docs/adr/0054-m65-source-persistence-prerequisite.md diff --git a/docs/ROADMAP.md b/docs/ROADMAP.md index 12cde25..04b42c4 100644 --- a/docs/ROADMAP.md +++ b/docs/ROADMAP.md @@ -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. diff --git a/docs/STATUS.md b/docs/STATUS.md index 2faf13e..916c3a6 100644 --- a/docs/STATUS.md +++ b/docs/STATUS.md @@ -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. diff --git a/docs/adr/0054-m65-source-persistence-prerequisite.md b/docs/adr/0054-m65-source-persistence-prerequisite.md new file mode 100644 index 0000000..5e95f71 --- /dev/null +++ b/docs/adr/0054-m65-source-persistence-prerequisite.md @@ -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. diff --git a/docs/adr/README.md b/docs/adr/README.md index f3698e1..f42ad67 100644 --- a/docs/adr/README.md +++ b/docs/adr/README.md @@ -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. diff --git a/docs/engineering/VALIDATION.md b/docs/engineering/VALIDATION.md index e25f676..7f0ac36 100644 --- a/docs/engineering/VALIDATION.md +++ b/docs/engineering/VALIDATION.md @@ -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.