refactor(kernel): address durable channel maintainability review

[kjgbot]

The channel handler could treat an unknown verb as receive, and erased engine errors required a runtime downcast to recover channel conflicts. This makes verb dispatch exhaustive and returns ChannelCommandError from the engine so the handler matches journal conflicts directly.

Channel projections now deserialize each fact once into its typed payload, retain the original journal entry for replay, and use typed fields for deduplication, offsets, and acknowledgement checks. Rejected appends do not create empty channel state. A TODO(epoch-compaction) marker referencing #212 identifies the retained-history fold and duplicate validation fold.

All four requested maintainability fixes from #215 are in 3abffd6. Existing tests are intact, with added regressions for unknown verbs and malformed facts. No stream/channel naming or schema changes.

#215 was externally squash-merged at 4c87d10 before these fixes were included. This follow-up uses the same feat/durable-channels-212 branch. Commit 7728014 incorporates that squash merge so the diff contains only the review fixes; its tree is identical to 3abffd6 (git diff --exit-code 3abffd6 HEAD emitted no output and exited 0). This PR remains for review; no PR merge was performed by this agent.

The workspace gate exited 0. Full captured output is committed at kernel/evidence/212/maintainability-workspace.txt and pasted below.

Workspace verification (exit 0)

cd kernel && cargo test --workspace

   Compiling relayflowd-core v0.1.0 (/Users/khaliqgant/AgentWorkforce/flows-212-channels-wt/kernel/relayflowd-core)
    Finished `test` profile [unoptimized + debuginfo] target(s) in 2.15s
     Running unittests src/lib.rs (target/debug/deps/relayflowd-399037c915557fdb)

running 36 tests
test engine::remote::worker_failure_detail_tests::a_string_output_is_carried_verbatim_and_trimmed ... ok
test engine::remote::worker_failure_detail_tests::a_null_or_blank_output_yields_no_detail ... ok
test engine::remote::worker_failure_detail_tests::an_output_at_the_boundary_is_not_truncated ... ok
test engine::remote::worker_failure_detail_tests::a_non_string_output_is_rendered_rather_than_dropped ... ok
test engine::boot_identity_tests::every_engine_in_this_process_shares_one_boot_id ... ok
test server::client::tests::resume_waits_while_the_heartbeat_renewed_lease_is_live ... ok
test server::liveness::tests::sweep_id_buckets_by_the_interval ... ok
test engine::remote::worker_failure_detail_tests::truncation_does_not_split_a_multi_byte_char ... ok
test server::channels::tests::unknown_verb_never_falls_through_to_receive ... ok
test exec_det::tests::timeout_has_an_explicit_completion_reason ... ok
test exec_det::tests::captures_deterministic_output ... ok
test engine::wake::claim_guard_tests::a_disarmed_guard_leaves_the_claim_alone ... ok
test server::liveness::tests::sweep_pass_healthy_subscription_is_a_noop ... ok
test server::liveness::tests::sweep_pass_latches_after_journaling_and_next_bucket_is_empty ... ok
test server::tests::agent::contract::an_agent_worker_attaching_without_pins_is_refused_at_attach ... ok
test server::tests::agent::contract::an_oversized_trajectory_tail_is_refused_at_step_complete ... ok
test engine::wake::claim_guard_tests::a_guard_only_releases_its_own_run ... ok
test engine::wake::claim_guard_tests::an_armed_guard_releases_the_claim_when_dropped ... ok
test engine::wake::claim_guard_tests::a_panic_between_claim_and_register_still_releases ... ok
test server::tests::agent::contract::agent_without_a_compatible_worker_parks_without_starting ... ok
test server::tests::hello_enforces_protocol_version ... ok
test server::tests::agent::contract::an_agent_worker_missing_a_declared_surface_parks_the_run_instead_of_erroring ... ok
test server::tests::run_resume_asks_the_registry_instead_of_treating_an_orphan_file_as_a_run ... ok
test server::tests::a_failed_disconnect_journal_append_is_retained_and_retried_not_dropped ... ok
test server::tests::agent::contract::an_llm_completion_claiming_an_effect_fails_closed_with_the_reason_journaled ... ok
test server::tests::run_start_fails_closed_on_an_unknown_verification_key ... ok
test server::tests::agent::contract::a_replacement_worker_that_never_reported_the_pinned_surface_is_not_dispatched_to ... ok
test server::tests::agent::pins::reset_worker_reporting_a_revision_other_than_its_pin_fails_closed_as_worker_error ... ok
test server::tests::run_resume_refuses_a_journal_that_never_recorded_its_run ... ok
test server::tests::run_resume_adopts_a_real_journal_whose_registry_row_is_missing ... ok
test server::tests::run_resume_refuses_a_valid_journal_that_belongs_to_another_run ... ok
test server::tests::agent::pins::consecutive_agent_steps_on_different_surfaces_each_start_from_their_own_pins ... ok
test server::tests::stopped_heartbeats_past_the_deadline_journal_lease_expired_and_release_the_step ... ok
test exec_det::tests::timeout_kills_the_whole_process_group ... ok
test server::tests::agent::pins::a_replacement_worker_at_a_different_revision_is_not_dispatched_the_stale_pins ... ok
test server::tests::an_entry_appended_during_watch_registration_is_delivered_exactly_once ... ok

test result: ok. 36 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.57s

     Running unittests src/main.rs (target/debug/deps/relayflowd-9e21fa47745f4fb0)

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

     Running tests/crash_resume.rs (target/debug/deps/crash_resume-e6635a3f0d48512c)

running 36 tests
test concurrency::cancel_closes_the_lease_and_rejects_a_late_completion ... ok
test channels::channels_reject_foreign_workers_stale_attempts_and_invalid_acknowledgements ... ok
test agent::resume_without_a_worker_parks_immediately_instead_of_timing_out ... ok
test agent::rung_c_sigkill_after_final_effect_replays_results_without_redispatch ... ok
test concurrency::cancel_and_completion_race_has_one_terminal_fact ... ok
test concurrency::live_resume_leaves_an_active_lease_running ... ok
test concurrency::run_start_dispatches_every_independent_lane_before_any_completion ... ok
test concurrency::concurrent_resumes_lease_exactly_one_attempt ... ok
test agent::rung_c_sigkill_between_agent_completion_and_final_effect_memoizes_the_agent ... ok
test llm::llm_verification_exhaustion_is_a_declared_failure_kind ... ok
test agent::rung_c_crash_between_effect_election_and_the_provider_call_performs_it_exactly_once ... ok
test agent::rung_c_reset_sigkill_mid_edit_restores_pins_dedupes_effect_and_explains_attempts ... ok
test llm::sigkill_after_the_final_rung_b_effect_resumes_without_redispatching_llm ... ok
test llm::completed_llm_output_is_memoized_when_serve_dies_during_the_next_step ... ok
test llm::failing_llm_verification_schedules_a_durable_retry_and_succeeds ... ok
test concurrency::server_restart_recovers_every_parallel_lease_without_duplicate_success ... ok
test llm::serve_plumbs_watch_events_and_replayable_stream_verbs ... ok
test agent::rung_c_sigkill_boundaries_resume_only_unfinished_steps_via_real_cli ... ok
test pin_projection::rejected_completion_cannot_forge_inspect_retry_pins_over_the_real_socket ... ok
test llm::worker_killed_while_holding_a_lease_is_explained_and_released_on_cli_resume ... ok
test protocol_admission::every_mutating_run_verb_refuses_terminal_before_changing_state ... ok
test sigkill_after_cancel_request_resumes_to_one_canceled_fact ... ok
test sigkill_mid_step_replaces_and_explains_the_dead_attempt ... ok
test parallel_lifecycle::overlapping_agent_conflict_survives_server_crash_and_resume ... ok
test surface_identity::aliases_are_rejected_and_external_ancestors_serialize_over_real_sockets ... ok
test llm::sigkill_under_serve_mid_llm_releases_the_lease_and_finishes_via_cli_resume ... ok
test parallel_lifecycle::terminal_failure_drains_or_explains_every_live_sibling ... ok
test workspace_identity::workspace_aliases_are_refused_and_canonical_subtrees_serialize_over_real_sockets ... ok
test parallel_lifecycle::overlapping_agent_lanes_serialize_while_disjoint_lanes_merge_in_either_order ... ok
test worker_capacity::two_workers_receive_a_deterministic_fair_capacity_bounded_batch ... ok
test sigkill_under_serve_resumes_the_socket_started_run ... ok
test sigkill_sweep_covers_every_hello_step_boundary ... ok
test llm::sigkill_sweep_covers_before_and_between_the_rung_b_steps ... ok
test worker_capacity::default_capacity_one_reopens_only_after_durable_completion_or_crash ... ok
test channels::channels_sigkill_resume_redelivers_unacked_messages_with_exactly_once_effects ... ok
test parallel_lifecycle::renewed_parallel_leases_survive_the_original_grant_and_remain_distinct ... ok

test result: ok. 36 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 37.71s

     Running tests/event_wake.rs (target/debug/deps/event_wake-68806edfe23e584d)

running 3 tests
test matching_event_wakes_once_with_fresh_context ... ok
test two_racing_deliveries_of_one_event_produce_exactly_one_run ... ok
test a_resumed_run_dispatches_the_original_wake_context ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.05s

     Running tests/hn_monitor_integration.rs (target/debug/deps/hn_monitor_integration-503c7fe71dfd86ee)

running 1 test
test hn_story_event_wakes_monitor_once_with_story_context ... ok

test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.06s

     Running tests/invalid_schema_preflight.rs (target/debug/deps/invalid_schema_preflight-bb9367af18e074b7)

running 3 tests
test invalid_json_schema_is_refused_before_journal_or_command ... ok
test unbounded_json_schema_is_refused_before_journal_or_command ... ok
test legitimately_recursive_json_schema_still_starts ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 7.00s

     Running tests/parallel_driver.rs (target/debug/deps/parallel_driver-f38ce1eaf4ecefc1)

running 4 tests
test stop_after_one_holds_for_an_independent_deterministic_batch ... ok
test pause_before_second_independent_step_holds_the_driver_boundary ... ok
test backpressured_or_mismatched_lane_does_not_drop_a_later_dispatch ... ok
test crash_boundaries_resume_the_real_driver_with_one_effect_per_lane ... ok

test result: ok. 4 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.08s

     Running tests/subscription_liveness.rs (target/debug/deps/subscription_liveness-f71f7e88f8d163dc)

running 3 tests
test submit_event_upserts_subscription_row_and_sweep_flags_it_stale_after_budget ... ok
test stale_transition_is_journaled_as_subscription_stale_entry_in_the_last_known_run ... ok
test a_fresh_arrival_re_arms_the_latch_and_the_next_silence_can_stale_again ... ok

test result: ok. 3 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.05s

     Running unittests src/lib.rs (target/debug/deps/relayflowd_core-b1fe3b3250e9e7a2)

running 57 tests
test clock::tests::simulated_clock_is_explicitly_advanced ... ok
test journal::tests::memory_journal_assigns_sequences_and_rolls_epochs ... ok
test channel::tests::malformed_payloads_and_invalid_new_channel_appends_leave_state_unchanged ... ok
test channel::tests::forged_deliveries_and_acknowledgements_fail_closed ... ok
test channel::tests::send_retry_is_stable_and_conflicting_content_is_rejected ... ok
test channel::tests::delivery_replay_and_independent_acknowledged_offsets ... ok
test machine::parallel_tests::machine_starts_every_runnable_step_in_authored_order ... ok
test machine::parallel_tests::every_declared_mutable_surface_participates_in_conflict_selection ... ok
test machine::parallel_tests::external_ancestor_and_descendant_paths_conflict_but_siblings_do_not ... ok
test machine::parallel_tests::failed_run_drains_open_siblings_before_terminal_entry ... ok
test machine::parallel_tests::workspace_ancestor_and_descendant_paths_conflict_but_siblings_do_not ... ok
test machine::parallel_tests::overlapping_agent_surfaces_are_serialized_in_authored_order ... ok
test machine::tests::cancel_request_closes_the_active_lease_before_the_terminal_fact ... ok
test machine::parallel_tests::disjoint_agent_lanes_merge_pins_in_either_completion_order ... ok
test machine::tests::all_backing_off_steps_return_timers ... ok
test machine::tests::durable_cancel_request_outranks_crash_recovery ... ok
test machine::parallel_tests::parallel_lanes_do_not_cross_the_dependency_barrier_early ... ok
test machine::tests::every_reason_label_matches_its_serialized_form ... ok
test machine::tests::crashed_attempt_does_not_consume_an_iteration ... ok
test machine::tests::machine_starts_runnable_step_with_stable_effect_key ... ok
test machine::tests::repeated_cancel_request_is_idempotent ... ok
test machine::tests::successful_memo_is_never_scheduled_again ... ok
test machine::tests::every_failed_run_terminates_with_declared_completion_reasons ... ok
test machine::tests::verification_failure_schedules_a_durable_retry ... ok
test machine::parallel_tests::crash_resume_preserves_each_parallel_lease_exactly_once ... ok
test retry::tests::jitter_is_repeatable_and_bounded ... ok
test machine::tests::worker_reported_failure_without_detail_still_records_a_verification ... ok
test machine::tests::reset_recovery_dispatches_the_original_pinned_revision ... ok
test machine::tests::manual_recovery_parks_needs_human_and_never_redispatches ... ok
test machine::tests::inspect_recovery_injects_the_dirty_pin_completion_reason_and_tail ... ok
test spec::tests::a_misspelled_step_level_key_is_a_parse_error ... ok
test schema::tests::in_document_uri_references_resolve_to_the_node_they_name ... ok
test schema::tests::refusal_names_the_cycle_it_found ... ok
test spec::tests::a_misspelled_verification_gate_key_is_a_parse_error_not_a_dropped_gate ... ok
test spec::tests::cycles_are_rejected ... ok
test spec::tests::preflight_data_is_fail_closed ... ok
test spec::tests::external_surface_paths_must_have_one_canonical_spelling ... ok
test spec::tests::spec_version_is_semver_and_gated ... ok
test spec::tests::unknown_root_and_nested_fields_are_rejected ... ok
test schema::tests::references_the_bound_leaves_opaque_are_refused_by_the_engine ... ok
test spec::tests::zero_agent_flow_is_valid ... ok
test spec::tests::workspace_mounts_and_worktrees_must_have_one_canonical_spelling ... ok
test state::tests::budget_decimal_strings_add_without_floats ... ok
test state::tests::a_completion_that_omits_a_surface_does_not_drop_it_from_the_pin_chain ... ok
test state::tests::journal_replays_data_gate_verdict_without_rerunning_completed_code ... ok
test state::tests::end_pin_chain_is_enforced_and_a_broken_chain_is_a_hard_error ... ok
test verify::tests::an_unbounded_schema_in_a_journal_fails_its_gate_instead_of_aborting ... ok
test verify::tests::deterministic_output_requires_successful_exit_and_content ... ok
test spec::tests::the_full_ladder_parses_in_the_one_dialect ... ok
test verify::tests::json_schema_is_a_control_gate ... ok
test schema::tests::a_property_named_ref_is_not_a_reference ... ok
test schema::tests::shared_declarations_and_boolean_schemas_are_validated ... ok
test schema::tests::every_accepted_corpus_schema_is_accepted ... ok
test spec::tests::sdk_boundary_rejects_a_10_000_step_cycle_with_a_typed_error ... ok
test schema::tests::every_refused_corpus_schema_compiles_but_is_refused_by_the_bound ... ok
test spec::tests::sdk_boundary_accepts_a_valid_10_000_step_reverse_chain ... ok
test schema::tests::deeply_nested_schemas_do_not_overflow_the_checker ... ok

test result: ok. 57 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.63s

     Running tests/spec_parity.rs (target/debug/deps/spec_parity-bbda6cf1e1cf1c19)

running 5 tests
test the_kernel_parses_the_event_triggered_spec_and_stamps_the_same_hash ... ok
test the_kernel_parses_the_deterministic_rung_and_stamps_the_same_hash ... ok
test the_kernel_parses_the_rung_c_agent_spec_and_stamps_the_same_hash ... ok
test the_kernel_parses_the_sdk_compiled_spec_and_stamps_the_same_hash ... ok
test the_kernel_parses_the_rung_b_spec_and_stamps_the_same_hash ... ok

test result: ok. 5 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.04s

     Running unittests src/lib.rs (target/debug/deps/relayflowd_journal-d13cb7954335385c)

running 28 tests
test registry::tests::a_registered_run_dedupes_across_boots ... ok
test registry::tests::releasing_a_claim_lets_the_same_boot_retry ... ok
test registry::tests::a_pre_migration_registry_gains_boot_id_and_its_claims_are_repairable ... ok
test registry::tests::registry_is_a_rebuildable_run_locator ... ok
test registry::tests::a_previous_boots_claim_with_no_run_is_repaired ... ok
test registry::tests::a_same_boot_claim_with_no_run_yet_is_a_duplicate_not_wreckage ... ok
test subscriptions::tests::last_run_for_subscription_returns_none_before_first_arrival ... ok
test subscriptions::tests::detect_without_latch_stays_available_for_the_next_sweep ... ok
test registry::tests::releasing_is_scoped_to_the_claiming_run ... ok
test subscriptions::tests::prune_sweep_claims_deletes_only_rows_older_than_cutoff ... ok
test subscriptions::tests::last_run_for_subscription_returns_the_lex_greatest_ulid_regardless_of_insertion ... ok
test subscriptions::tests::latch_is_a_no_op_if_a_fresh_event_arrived_between_detect_and_latch ... ok
test subscriptions::tests::sweep_does_not_re_emit_the_same_stale_row_on_a_later_tick ... ok
test subscriptions::tests::sweep_election_gives_the_first_caller_the_result_and_second_gets_empty ... ok
test subscriptions::tests::sweep_ignores_subscriptions_whose_silence_is_still_within_budget ... ok
test subscriptions::tests::sweep_marks_row_stale_when_silence_exceeds_budget ... ok
test subscriptions::tests::upsert_after_stale_re_arms_and_next_silence_can_re_emit ... ok
test subscriptions::tests::upsert_is_idempotent_across_bumps_and_preserves_event_type_updates ... ok
test channel::tests::stale_attempts_and_raw_forged_acknowledgements_cannot_change_offsets ... ok
test tests::failed_commit_is_returned_not_swallowed ... ok
test tests::effects_are_deduplicated_at_the_journal_boundary ... ok
test tests::an_unconfirmed_election_is_reclaimed_by_the_next_attempt_not_treated_as_done ... ok
test tests::append_is_durable_and_monotonic_after_reopen ... ok
test tests::rollover_is_atomic_scaffolding_for_epoch_resume ... ok
test channel::tests::channels_cross_segment_boundaries_and_terminal_runs_reject_mutations ... ok
test tests::terminal_run_refuses_every_later_entry_atomically ... ok
test channel::tests::failed_channel_writes_never_expose_delivery_or_advance_acknowledged_offset ... ok
test channel::tests::independent_connections_serialize_send_receive_and_acknowledgement ... ok

test result: ok. 28 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.17s

   Doc-tests relayflowd

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests relayflowd_core

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

   Doc-tests relayflowd_journal

running 0 tests

test result: ok. 0 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out; finished in 0.00s

[coderabbitai]

Important

• 🔍 Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Team

Run ID: dbf16d30-cd59-492b-982b-49227dd39ae2

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cubic-dev-ai]

No issues found across 8 files

_{Re-trigger cubic}

[kjgbot]

maintainability lens — PASS

Maintainability review — PR #216

Verdict: Solid maintainability lift on all four axes the change targets. No blockers.

What improved (with tests that would fail on regression)

• Removed a state-leak on failed apply. In the pre-diff channel.rs, ChannelAppended did self.messages.entry(p.channel).or_default() before the require() checks, so a rejected append still left an empty Vec under a new channel key. The new code (channel.rs:118–135 in diff) only inserts after every guard passes, and the new test at channel/tests.rs:270–274 explicitly asserts state == snapshot after both a malformed payload and an invalid new-channel append. That regression could not have been caught by the old suite.
• Eliminated implicit-contract expect() panics. offset() and the ack-idempotence branch previously did payload["offset"].as_u64().expect("validated acknowledgement") — a contract-by-comment. ChannelFact<P> (channel.rs:71–86 in diff) decodes once at apply-time and lets offset() return fact.payload.offset directly. Fewer landmines, and the invariant is now enforced at the type boundary instead of a stringly-typed key lookup.
• Killed the silent-fallthrough dispatch. Old server/channels.rs:71 had _ => ChannelCommand::Receive, so any unknown verb string was quietly dispatched as Receive. New code introduces ChannelVerb (server/channels.rs:9–13) with an early explicit unsupported_verb error, and unknown_verb_never_falls_through_to_receive (server/channels.rs:117–129) pins the exact (kind, message) tuple. A future refactor that reorders the guard would fail this test.
• Typed engine boundary error. ChannelCommandError (engine/channels.rs:12–36 in diff) replaces the error.downcast_ref::<JournalStoreError>() runtime type sniffing in the server handler with a match on typed variants. The channel_conflict classification is now checkable at compile time.

Concerns (non-blocking)

• Error-impl inconsistency. ChannelCommandError hand-rolls Display + Error while its sibling ChannelError (channel.rs:55–61) uses #[derive(thiserror::Error)]. Two idioms for the same concept adds ambient cost for the next maintainer; converting to thiserror is a one-line change.
• internal_error(error.into()) at server/channels.rs re-wraps a typed JournalStoreError back into anyhow::Error just to satisfy the helper's signature. The type discipline gained upstream is thrown away at the last mile. Fine for now; worth an internal_error overload if more typed errors land.

Notes

• The TODO(epoch-compaction): #212 comment (relayflowd-journal/src/channel.rs:27–29) is exactly the kind of comment that ages well: it names the successor design ("bounded epoch channel snapshots"), the precondition ("before archived segments can be removed"), and cites the tracking issue. A see also insert_entry pointer would save the next reader one grep.
• The unknown_verb_never_falls_through_to_receive test uses a single verb string. A tiny table over 2–3 unknown verbs would tighten it, but the current test is sufficient to catch the specific regression class.
• ChannelFact<P> stays private; deliveries() still returns &JournalEntry for API stability. Correct call — widening later is easier than narrowing.

REVIEW_PASSED

[kjgbot]

history lens — PASS

Blockers: none. PR #216 passes the HISTORY lens at 7728014, against base b5896a8. I reviewed the requested history, AGENTS.md, RFC-0001, DRIVE-LOG, NEXT, DIRECTIVES, and the PR’s commit messages.

Notes

• No previously removed failure pattern is reintroduced. kernel/relayflowd/src/server/channels.rs:37–47 rejects unknown verbs explicitly, while lines 102–108 preserve channel-conflict classification through typed matching. This is consistent with DRIVE-LOG’s earlier repairs preserving structured errors across boundaries.
• kernel/relayflowd-core/src/channel.rs:71–107 retains original journal entries alongside typed payloads. Replay remains a projection of committed facts, consistent with settled decisions Close Gate 1 deterministic crash-resume rung #2 and flow/drive f59e279 08271341 #7. Lines 122–143 validate an append before inserting channel state, strengthening rejection behavior.
• The commit subject “address durable channel maintainability review” accurately describes the changes. The added regressions in kernel/relayflowd-core/src/channel/tests.rs:228–274 and kernel/relayflowd/src/server/channels.rs:116–129 match the README’s description; the supplied diff removes no existing tests.
• kernel/evidence/212/README.md:8–10 identifies the literal workspace-test command and its committed transcript, maintainability-workspace.txt:1–262. This avoids the DRIVE-LOG’s recurring unsupported-evidence pattern. I inspected the recorded evidence; I did not rerun the test suite or perform mutation verification.

Concerns — non-blocking

kernel/relayflowd-journal/src/channel.rs:27–29 documents retained-history folding and duplicate validation, with bounded epoch snapshots deferred under #212. Settled decision #8 remains incompletely realized, but this diff adds a follow-up marker rather than introducing that limitation or removing working compaction behavior. Under the requested scope, it is not grounds for rejection.

REVIEW_PASSED

[kjgbot]

structure lens — PASS

→ Read docs/RFC-0001-everything-is-a-relayflow.md
→ Read AGENTS.md

$ wc -l kernel/relayflowd-core/src/channel.rs kernel/relayflowd-core/src/channel/tests.rs kernel/relayflowd/src/engine/channels.rs kernel/relayflowd/src/server/channels.rs kernel/relayflowd-journal/src/channel.rs 2>/dev/null
331 kernel/relayflowd-core/src/channel.rs
226 kernel/relayflowd-core/src/channel/tests.rs
25 kernel/relayflowd/src/engine/channels.rs
94 kernel/relayflowd/src/server/channels.rs
93 kernel/relayflowd-journal/src/channel.rs
769 total

$ git -C /Users/khaliqgant/AgentWorkforce/flows-ops log --oneline -5 2>/dev/null; echo "---"; ls kernel/relayflowd-core/src/
b5896a8 feat(kernel): durable channels with acknowledged delivery and crash replay (#215)
5c9758b fix(workflows): drive sync guard still required the pre-#205 sdk/ path (#211)
de43f9e chore(release): v2.0.1
a1734c9 drive: cloud run b9742721 (#207)
9c1aa86 docs(next): point drive runs at #174 instead of human-blocked credential work (#210)

channel
channel.rs
clock.rs
entry.rs
event.rs
journal.rs
lib.rs
machine
machine.rs
retry.rs
schema.rs
spec
spec.rs
state
state.rs
verify.rs

$ grep -n "ChannelAppendedPayload|ChannelDeliveredPayload|ChannelAcknowledgedPayload|struct ChannelFact|enum EntryType" kernel/relayflowd-core/src/channel.rs kernel/relayflowd-core/src/entry.rs 2>/dev/null
kernel/relayflowd-core/src/channel.rs:29:pub struct ChannelAppendedPayload {
kernel/relayflowd-core/src/channel.rs:40:pub struct ChannelDeliveredPayload {
kernel/relayflowd-core/src/channel.rs:48:pub struct ChannelAcknowledgedPayload {
kernel/relayflowd-core/src/channel.rs:109: let p: ChannelAppendedPayload = serde_json::from_value(entry.payload.clone())?;
kernel/relayflowd-core/src/channel.rs:133: let p: ChannelDeliveredPayload = serde_json::from_value(entry.payload.clone())?;
kernel/relayflowd-core/src/channel.rs:156: let p: ChannelAcknowledgedPayload = serde_json::from_value(entry.payload.clone())?;
kernel/relayflowd-core/src/channel.rs:233: serde_json::to_value(ChannelAppendedPayload {
kernel/relayflowd-core/src/channel.rs:249: serde_json::to_value(ChannelDeliveredPayload {
kernel/relayflowd-core/src/channel.rs:272: serde_json::to_value(ChannelAcknowledgedPayload {
kernel/relayflowd-core/src/entry.rs:9:pub enum EntryType {

→ Read kernel/relayflowd/src/engine/channels.rs

Structure review — PR #216

This is a clean, structural refactor that moves three pieces toward the RFC's "helpers over primitives / typed vocabulary / fail-closed" discipline, and nothing toward the anti-patterns.

What it does, structurally:

1. ChannelFact<P> in kernel/relayflowd-core/src/channel.rs (lines ~71–76, maps ~82–88). A private generic wrapper over { entry: JournalEntry, payload: P } that decodes the payload once and reads typed fields (fact.payload.offset, .producer) instead of re-indexing entry.payload["offset"] with .as_u64().expect(...). This is exactly "helpers over primitives": the three stringly-typed JSON maps become three typed BTreeMaps, while the public boundary (offset(), deliveries() -> impl Iterator<&JournalEntry>, apply, decide, message) keeps returning/expecting JournalEntry, so the journal-protocol boundary is preserved — nothing reaches around it. Good.

2. ChannelCommandError in engine/channels.rs (lines ~10–33) and pub use channels::ChannelCommandError in engine.rs. Replaces anyhow's lossy error.downcast_ref::<JournalStoreError>() (a server/channels.rs dispatch smell) with a typed two-variant error (OpenRun vs Journal). Typed error, empty anyhow surface shrinks. Aligned with RFC covenant 2 ("typed failure").

3. ChannelVerb enum in server/channels.rs (lines ~9–14). The meaningful change: the prior _ => &[] / _ => ChannelCommand::Receive silently routed any unknown verb to receive. Now unknown verbs return ("unsupported_verb", ...). This is a real fail-closed fix matching AGENTS.md rule 4 and RFC §settled-decision 7/13, with a regression test (unknown_verb_never_falls_through_to_receive) pinning it.

Concerns (not blockers):

• ChannelFact<P> is instantiated three times for three sibling projections; a single enum ChannelFact { Appended(..), Delivered(..), Acknowledged(..) } would collapse the duplication, but the three-typed-map shape faithfully mirrors the prior structure and reads well. Defer.
• Manual Display/source impls on ChannelCommandError are thiserror-shaped boilerplate; check whether relayflowd already depends on thiserror and use it if so (DRY).
• relayflowd-journal/src/channel.rs gains a TODO(epoch-compaction): #212 fold note — legitimate deferred-work marker, but note it duplicates read_entries folding that insert_entry also performs; confirm the duplication is the bounded kind the TODO describes rather than new dead code (AGENTS.md rule 6).

File size: all touched files ≤331 lines, well under the 500-line smell threshold.

No product logic entered the kernel; no new primitive added where a helper belongs; no file outgrew its purpose.

REVIEW_PASSED

[kjgbot]

🎯 review-swarm: PASSED (M:pass H:pass S:pass)

Lens transcripts posted as sibling comments above.