Publish mutation choices atomically with their checkpoint

ADR-0121, schema v35. A checkpoint whose trace carries mutation
selections publishes with its canonical mutation block and one result
byte per choice. SQL checks the block's order, matches each record to
one reserved choice of this region and to its trace selection (tick,
life, offer, operator, successor identity), binds it to the commit with
its result, refuses a choice already bound elsewhere and checks exact
retries. The four-argument publisher becomes an internal helper behind
a wrapper that refuses traces with selections.

C++ publication takes the results from its own replay rather than a
caller, prepared commits carry block and results through retry and
resolution, and recovery rebuilds the bound choices and requires the
replay's results to match. A PostgreSQL test feeds a v4 cell to its
first offer, publishes a reserved choice, recovers it and restarts a
host. Host and session admission follow in 11.4c-2.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
dingo
2026-10-13 19:23:39 -04:00
co-authored by Claude Opus 5.5
parent bf5c626f19
commit 1bbac48543
14 changed files with 897 additions and 28 deletions
+135 -15
View File
@@ -50,8 +50,60 @@ confirm(const RegionHead& head, const CellularPreparedCommit& prepared,
return std::unexpected{failure(PublicationError::receipt)};
return CommittedCheckpoint{head, prepared.manifest};
}
// The result byte for each mutation action (ADR-0121), from the replay's outcomes: the
// action's account names the predecessor life whose selection replayed at its tick.
std::optional<std::vector<std::uint8_t>>
mutation_results(const server::CellularLives& base,
std::span<const server::CellularMutationActionRecord> actions,
std::span<const server::CellularMutationOutcome> outcomes) {
if (actions.size() != outcomes.size())
return std::nullopt;
std::vector<std::uint8_t> results;
results.reserve(actions.size());
for (const auto& action : actions) {
const auto life =
std::ranges::find(base.lives(), action.account, &server::CellularOwnedLife::account);
if (life == base.lives().end() || life->identity.life != action.input.life_id)
return std::nullopt;
const auto outcome = std::ranges::find_if(outcomes, [&](const auto& candidate) {
return candidate.tick == action.tick && candidate.life_id == action.input.life_id;
});
if (outcome == outcomes.end())
return std::nullopt;
results.push_back(static_cast<std::uint8_t>(outcome->result));
}
return results;
}
std::size_t selection_count(const server::CellularBatch& trace) {
std::size_t count{};
for (const auto& tick : trace.ticks)
count += tick.mutations.size();
return count;
}
// The mutation block and results agree in shape with the trace: none without selections,
// otherwise one canonical record and one known result per selection.
bool prepared_mutations_are_canonical(const CellularPreparedCommit& prepared,
const CheckpointManifest& manifest,
const server::CellularBatch& trace) {
const auto selections = selection_count(trace);
if (prepared.mutations.empty())
return selections == 0 && prepared.results.empty();
const auto decoded = server::decode_cellular_mutation_action_block(
prepared.mutations, manifest.begin_tick, manifest.end_tick);
if (!decoded || decoded->size() != selections || prepared.results.size() != selections ||
std::ranges::any_of(prepared.results, [](std::uint8_t result) { return result > 2; }))
return false;
const auto encoded = server::encode_cellular_mutation_action_block(
*decoded, manifest.begin_tick, manifest.end_tick);
return encoded && *encoded == prepared.mutations;
}
bool prepared_is_canonical(const CellularPreparedCommit& prepared,
const CheckpointManifest& manifest, const server::CellularBatch& trace) {
if (!prepared_mutations_are_canonical(prepared, manifest, trace))
return false;
const auto decoded_actions = server::decode_cellular_action_block(
prepared.actions, manifest.begin_tick, manifest.end_tick);
const auto encoded_actions =
@@ -130,7 +182,8 @@ provision_cellular_region(Postgres& owner, const FilesystemObjectStore& objects,
if (!inserted) {
auto existing = load_region_checkpoint(owner, key, timeout);
if (existing && existing->manifest == *encoded)
return confirm(existing->head, CellularPreparedCommit{key, commit, *encoded, {}, {}},
return confirm(existing->head,
CellularPreparedCommit{key, commit, *encoded, {}, {}, {}, {}},
*manifest);
if (existing)
return std::unexpected{failure(PublicationError::rejected)};
@@ -145,7 +198,7 @@ provision_cellular_region(Postgres& owner, const FilesystemObjectStore& objects,
auto committed = load_region_checkpoint(owner, key, timeout);
if (!committed)
return std::unexpected{failure(PublicationError::unknown, {}, committed.error())};
CellularPreparedCommit prepared{key, commit, *encoded, {}, {}};
CellularPreparedCommit prepared{key, commit, *encoded, {}, {}, {}, {}};
auto confirmed = confirm(committed->head, prepared, *manifest);
if (!confirmed)
return std::unexpected{confirmed.error()};
@@ -299,8 +352,12 @@ retry_cellular_prepared(Postgres& db, const CellularPreparedCommit& prepared,
auto trace = server::decode_cellular_batch(prepared.trace);
if (!manifest || !trace || !prepared_is_canonical(prepared, *manifest, *trace))
return std::unexpected{failure(PublicationError::candidate)};
auto result = publish_cellular_checkpoint(db, prepared.manifest, {}, prepared.actions,
prepared.trace, timeout);
auto result = prepared.mutations.empty()
? publish_cellular_checkpoint(db, prepared.manifest, {}, prepared.actions,
prepared.trace, timeout)
: publish_cellular_mutation_checkpoint(
db, prepared.manifest, {}, prepared.actions, prepared.trace,
prepared.mutations, prepared.results, timeout);
if (!result) {
return std::unexpected{failure(result.error().kind == LeaseStoreError::unknown
? PublicationError::unknown
@@ -317,6 +374,10 @@ resolve_cellular_prepared(Postgres& db, const CellularPreparedCommit& prepared,
auto trace = server::decode_cellular_batch(prepared.trace);
if (!manifest || !trace || !prepared_is_canonical(prepared, *manifest, *trace))
return std::unexpected{LeaseStoreFailure{LeaseStoreError::invalid, {}}};
if (!prepared.mutations.empty())
return resolve_cellular_mutation_commit(
db, prepared.key, prepared.commit, prepared.manifest, {}, prepared.actions,
prepared.trace, prepared.mutations, prepared.results, timeout);
return resolve_cellular_region_commit(db, prepared.key, prepared.commit, prepared.manifest, {},
prepared.actions, prepared.trace, timeout);
}
@@ -326,7 +387,8 @@ publish_cellular_batch(Postgres& db, const FilesystemObjectStore& objects, const
const CommittedCheckpoint& predecessor, const server::CellularBatch& batch,
const server::CellularLives& candidate, Uuid commit,
const Sha256Digest& build, milliseconds timeout, const PublishHooks& hooks,
std::span<const server::CellularActionRecord> actions) {
std::span<const server::CellularActionRecord> actions,
std::span<const server::CellularMutationActionRecord> mutation_actions) {
const auto previous = decode_manifest(predecessor.manifest);
const auto predecessor_digest = sha256(predecessor.manifest);
auto committed_batch = batch;
@@ -351,9 +413,16 @@ publish_cellular_batch(Postgres& db, const FilesystemObjectStore& objects, const
candidate.format_version() != previous->cellular_versions.envelope ||
candidate.rules_version() != previous->cellular_versions.rules ||
candidate.tick() != batch.header.end_tick ||
std::ranges::any_of(committed_batch.ticks,
[](const auto& tick) { return !tick.mutations.empty(); }))
selection_count(committed_batch) != mutation_actions.size())
return std::unexpected{failure(PublicationError::candidate)};
std::vector<std::uint8_t> mutation_block;
if (!mutation_actions.empty()) {
auto encoded = server::encode_cellular_mutation_action_block(
mutation_actions, batch.header.begin_tick, batch.header.end_tick);
if (!encoded)
return std::unexpected{failure(PublicationError::candidate)};
mutation_block = std::move(*encoded);
}
auto predecessor_bytes = objects.get({previous->payload_sha256, previous->payload_bytes});
if (!predecessor_bytes)
@@ -361,10 +430,17 @@ publish_cellular_batch(Postgres& db, const FilesystemObjectStore& objects, const
auto base = restore_cellular_payload(*predecessor_bytes, *previous);
if (!base)
return std::unexpected{failure(PublicationError::predecessor)};
auto replay = server::replay_cellular_batch(**base, committed_batch);
std::vector<server::CellularMutationOutcome> outcomes;
auto replay = server::replay_cellular_batch(**base, committed_batch, outcomes);
const auto payload = candidate.snapshot();
if (!replay || (*replay)->snapshot() != payload ||
!server::match_cellular_actions_to_trace(**base, committed_batch, actions))
!server::match_cellular_actions_to_trace(**base, committed_batch, actions) ||
(!mutation_actions.empty() && !server::match_cellular_mutation_actions_to_trace(
**base, committed_batch, mutation_actions)))
return std::unexpected{failure(PublicationError::candidate)};
// The bound results are the replay's, never a caller's claim.
const auto results = mutation_results(**base, mutation_actions, outcomes);
if (!results)
return std::unexpected{failure(PublicationError::candidate)};
const auto payload_digest = sha256(payload);
@@ -384,13 +460,18 @@ publish_cellular_batch(Postgres& db, const FilesystemObjectStore& objects, const
if (auto stored = put_verified(objects, *trace, {*trace_digest, trace->size()}); !stored)
return std::unexpected{stored.error()};
CellularPreparedCommit prepared{previous->key, commit, *manifest_bytes, *trace, *action_block};
CellularPreparedCommit prepared{previous->key, commit, *manifest_bytes, *trace,
*action_block, mutation_block, *results};
if (hooks.before_transaction)
hooks.before_transaction();
auto committed = retry_cellular_prepared(db, prepared, timeout);
if (!committed)
return std::unexpected{committed.error()};
return PublishedCellularBatch{std::move(*committed)};
std::vector<server::CellularMutationResult> published_results;
published_results.reserve(results->size());
for (const auto result : *results)
published_results.push_back(static_cast<server::CellularMutationResult>(result));
return PublishedCellularBatch{std::move(*committed), std::move(published_results)};
}
std::expected<RecoveredCellularCheckpoint, RecoveryFailure>
@@ -429,6 +510,8 @@ recover_cellular_checkpoint(Postgres& db, const FilesystemObjectStore& objects,
return fail_with(RecoveryError::payload);
std::vector<server::CellularActionRecord> actions;
std::vector<server::CellularMutationActionRecord> mutation_actions_recovered;
std::vector<server::CellularMutationResult> mutation_results_recovered;
if (manifest->sequence != 0 && manifest->begin_tick == manifest->end_tick) {
auto migration = load_cellular_profile_migration(db, key, lease, manifest->commit, timeout);
if (!migration)
@@ -488,7 +571,8 @@ recover_cellular_checkpoint(Postgres& db, const FilesystemObjectStore& objects,
if (!migrated || (*migrated)->tick() != manifest->end_tick ||
(*migrated)->snapshot() != *payload)
return fail_with(RecoveryError::history);
return RecoveredCellularCheckpoint{std::move(*committed), *manifest, std::move(*state), {}};
return RecoveredCellularCheckpoint{
std::move(*committed), *manifest, std::move(*state), {}, {}, {}};
}
if (manifest->sequence != 0) {
auto action_bytes =
@@ -557,10 +641,42 @@ recover_cellular_checkpoint(Postgres& db, const FilesystemObjectStore& objects,
if (!batch_actions ||
!server::match_cellular_actions_to_trace(**base, *trace, *batch_actions))
return fail_with(RecoveryError::history);
auto replay = server::replay_cellular_batch(**base, *trace);
std::vector<server::CellularMutationOutcome> outcomes;
auto replay = server::replay_cellular_batch(**base, *trace, outcomes);
if (!replay || (*replay)->snapshot() != *payload)
return fail_with(RecoveryError::tail);
// ADR-0121: every selection in the trace has exactly one bound choice whose stored
// result is the replay's.
auto published =
load_cellular_mutation_publications(db, key, lease, manifest->commit, timeout);
if (!published)
return std::unexpected{RecoveryFailure{RecoveryError::store, published.error()}};
std::vector<server::CellularMutationActionRecord> mutation_actions;
std::vector<std::uint8_t> stored_results;
mutation_actions.reserve(published->size());
for (const auto& row : *published) {
auto action =
server::decode_cellular_mutation_input(row.account, row.action_id, row.input);
if (!action)
return fail_with(RecoveryError::history);
mutation_actions.push_back(*action);
stored_results.push_back(row.result);
}
if (mutation_actions.size() != selection_count(*trace) ||
(!mutation_actions.empty() &&
(!server::encode_cellular_mutation_action_block(mutation_actions, manifest->begin_tick,
manifest->end_tick) ||
!server::match_cellular_mutation_actions_to_trace(**base, *trace, mutation_actions))))
return fail_with(RecoveryError::history);
const auto replayed_results = mutation_results(**base, mutation_actions, outcomes);
if (!replayed_results || *replayed_results != stored_results)
return fail_with(RecoveryError::history);
for (const auto result : stored_results)
mutation_results_recovered.push_back(
static_cast<server::CellularMutationResult>(result));
mutation_actions_recovered = std::move(mutation_actions);
std::vector<ActionRef> refs;
refs.reserve(batch_actions->size());
for (const auto& action : *batch_actions)
@@ -583,7 +699,11 @@ recover_cellular_checkpoint(Postgres& db, const FilesystemObjectStore& objects,
}
actions = std::move(*batch_actions);
}
return RecoveredCellularCheckpoint{std::move(*committed), *manifest, std::move(*state),
std::move(actions)};
return RecoveredCellularCheckpoint{std::move(*committed),
*manifest,
std::move(*state),
std::move(actions),
std::move(mutation_actions_recovered),
std::move(mutation_results_recovered)};
}
} // namespace evo::persistence