Complete M7.5 durable batch outcomes and commit resolution
ADR-0063: manifest v2 (360 bytes) binds a per-tick validation trace object and a canonical decision block by SHA-256. Publication replays the trace from the committed predecessor's verified payload and requires every report and the candidate bytes, derives deaths deterministically, uploads payload and trace with verified read-back, then sends manifest and decisions to one fenced statement. RegionBatch seals at a terminal transition or 64 ticks and refuses ticks until durable confirmation. Schema v5 records the checkpoint, its decisions and outbox rows atomically; a unique index keeps one terminal outcome per actor (EVL08), triggers make commits/decisions immutable (EVL09), an exact retry of a committed ID returns the original receipt, changed bytes conflict, and read-only resolve_region_commit answers committed/absent/ conflict. Outbox pending/acknowledge give idempotent at-least-once delivery. Recovery reconciles durable deaths with restored lifecycle (and archive deaths for the lineage profile). Validated: Windows CTest 58/58; Linux GCC Debug/Release, clang-tidy and ASan/UBSan CTest 58/58 each; PostgreSQL suites Release, analysis, ASan (lost response, committed-after-timeout, terminated orphan retry, changed bytes, repeated/partial/reordered decisions, gap, outbox redelivery, history quarantine); five mutations each caught. No Docker/Gitea CI, process kill, broker or deployment. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
@@ -0,0 +1,119 @@
|
||||
# ADR-0063: Batch evidence, durable outcomes and commit resolution
|
||||
|
||||
## Status
|
||||
Accepted for M7.5, 2026-09-28. Builds on ADR-0058 (full checkpoint batches),
|
||||
ADR-0060 (fencing) and ADR-0061/0062 (publication, profiles). No region host,
|
||||
broker or deployment is added; M7.6 hosts drive these APIs.
|
||||
|
||||
## Context
|
||||
ADR-0058 requires irreversible outcomes to become final only through the same
|
||||
fenced transaction as the state that produced them, with exact reconciliation of
|
||||
ambiguous commits. M7.4 published full checkpoints but recorded no decisions, no
|
||||
outbox and no batch trace. Its retries could only compare the head, and the
|
||||
database had no record of why a death happened.
|
||||
|
||||
The environmental profiles have exactly two actors, whose only permanent outcome
|
||||
is death, and deaths are terminal. The PostgreSQL adapter bounds each parameter
|
||||
to 4 KiB and each call to 16 parameters (ADR-0059).
|
||||
|
||||
## Decision
|
||||
**Manifest v2** (360 bytes) appends to v1 the trace length and SHA-256, the
|
||||
decision count and the decision-block SHA-256; one reserved field must be zero.
|
||||
The commit digest therefore binds the whole batch. v1 manifests from M7.4 commits
|
||||
still decode, but only v2 is written.
|
||||
|
||||
**Validation trace** (schemas/region-batch.md) records the ordered
|
||||
input/report pair for every tick. Its 96-byte header binds the profile, region,
|
||||
predecessor commit and digest, and the tick range, so a trace cannot be replayed
|
||||
elsewhere. Each tick is a 304-byte step, up to 19,552 bytes total. It is stored as
|
||||
an immutable object beside the payload.
|
||||
|
||||
**Staging replays** the trace from the committed predecessor's verified payload
|
||||
and must reproduce every report and the candidate bytes exactly. A missing or
|
||||
corrupt predecessor stops publication (`predecessor`).
|
||||
|
||||
**Decisions** are 24-byte records (tick, actor, outcome, archived organism),
|
||||
derived deterministically from terminal transitions. They are ordered by
|
||||
(tick, actor), with at most one per actor and ticks inside the batch. Their
|
||||
organism is 0 for environmental-v1 and the bound organism for the lineage
|
||||
profile. The block is capped at 8 records, which keeps it within one adapter
|
||||
parameter; these profiles can produce at most 2. The decision identity is
|
||||
(region, outcome, actor, tick), with no hashing needed.
|
||||
|
||||
`RegionBatch` records at most one pending batch per state:
|
||||
- It seals itself at the first terminal transition, so the whole region pauses
|
||||
at an irreversible outcome. It also seals at 64 ticks, or when the host flushes.
|
||||
- A sealed batch refuses ticks until `confirm(end_tick)`.
|
||||
- Outcomes are provisional until a receipt arrives.
|
||||
|
||||
**Schema v5**:
|
||||
- `publish_region_checkpoint(manifest, decisions)` validates the decision block
|
||||
against the manifest digest, then checks for an existing commit ID. Identical
|
||||
bytes return the original receipt without mutation or authority; anything else
|
||||
is EVL07.
|
||||
- A new commit then takes the fenced path. In the same statement it inserts the
|
||||
commit (with its decision block), the head, the decisions and the outbox rows.
|
||||
A repeated death is EVL08, backed by a unique index on terminal outcomes.
|
||||
- `resolve_region_commit` is read-only and answers committed (with the receipt),
|
||||
absent or conflict.
|
||||
- `load_region_decisions` supports recovery reconciliation.
|
||||
- `pending_region_outbox` and `acknowledge_region_outbox` give at-least-once
|
||||
delivery; acknowledgement is idempotent.
|
||||
- Triggers forbid UPDATE, DELETE and TRUNCATE of commits and decisions, and allow
|
||||
outbox rows only a first delivery timestamp (EVL09).
|
||||
- The runtime role's audited function set grows to ten.
|
||||
|
||||
**Recovery** loads decisions and requires lifecycle agreement:
|
||||
- one death per terminal actor, none for an active actor;
|
||||
- no death after the head tick, and organisms match the profile;
|
||||
- for the lineage profile, each death equals the archive's death at the same tick.
|
||||
|
||||
Disagreement quarantines the region with `history`.
|
||||
|
||||
**Ambiguity**: after `unknown`, the host keeps its batch sealed and resolves the
|
||||
exact prepared bytes.
|
||||
- Committed: adopt the receipt.
|
||||
- Absent: retry the same bytes, and only while the lease is valid.
|
||||
- Conflict: fail closed. A timeout is never treated as a rollback.
|
||||
|
||||
## Alternatives Considered
|
||||
- **The whole request in the database**: exceeds adapter bounds and duplicates
|
||||
object storage; the trace digest binds it instead.
|
||||
- **Hashed event IDs**: need SHA-256 in portable code; the structured identity is
|
||||
unique by construction.
|
||||
- **Retry by reloading the head**: cannot tell a lost response from a concurrent
|
||||
successor, and cannot detect changed bytes.
|
||||
- **Idempotency after the lease check**: would refuse a truthful receipt to a
|
||||
writer whose lease expired after its commit.
|
||||
|
||||
## Benefits
|
||||
- Deaths are durable exactly once, with their causing state.
|
||||
- Lost responses resolve without guessing.
|
||||
- The chain carries verifiable per-tick evidence.
|
||||
- Delivery can be repeated without touching the simulation.
|
||||
|
||||
## Costs
|
||||
- Every batch restores and replays its predecessor: about 7 ms in local Release
|
||||
for these payloads, versus about 4 ms without replay in M7.4.
|
||||
- Two objects are written per batch, and orphans double.
|
||||
- History tables only grow.
|
||||
|
||||
## Risks
|
||||
- The database still cannot validate the trace or the payload contents; a
|
||||
compromised host with a valid lease can publish a self-consistent fiction
|
||||
(ADR-0058).
|
||||
- Owner roles can disable the triggers.
|
||||
- The outbox has no consumer yet.
|
||||
- Profiles with births or more outcome types need their own identity and closure
|
||||
rules.
|
||||
- An absent resolution does not prove a delayed original can never arrive; the
|
||||
unique ID and head guard make the two converge.
|
||||
|
||||
## Consequences
|
||||
- M7.6 hosts must use `RegionBatch`, flush by deadline, pause while sealed, and
|
||||
resolve before any further tick after `unknown`.
|
||||
- M7.7 exercises kills at each boundary.
|
||||
- A broker or projection consumer is later operations work and must deduplicate
|
||||
by the decision identity.
|
||||
- Manifest v3, or new decision kinds, require new profile or history values and a
|
||||
migration.
|
||||
@@ -73,3 +73,4 @@ design. No unadopted candidate is a link dependency of the proof.
|
||||
- [ADR-0060: Fenced region ownership](0060-fenced-region-ownership.md) - accepted for M7.3 database-time leases, guarded head advance, runtime grants and selected timings.
|
||||
- [ADR-0061: Checkpoint publication](0061-checkpoint-publication.md) - accepted for M7.4a manifest v1, immutable filesystem objects, OpenSSL SHA-256 and verified recovery.
|
||||
- [ADR-0062: Lineage checkpoint profile](0062-lineage-checkpoint-profile.md) - accepted for M7.4b archive codec, LineageRegion closure and history-capable profile 2.
|
||||
- [ADR-0063: Batch outcomes](0063-batch-outcomes.md) - accepted for M7.5 manifest v2, validation trace replay, durable decisions/outbox and commit resolution.
|
||||
|
||||
Reference in New Issue
Block a user