Repository navigation
id: implement: journaled region-seam export/import #3870
Description
Implements the accepted design from #2818. See the design note doc/2026-11-01_design_id2818.md and design PR #3875.
Build the journaled handoff for an application-owned entity crossing between spatial region shard-worlds. Use dedicated source/destination journal entries plus coordinator open/close records. The required local order is prepare/validate → persist typed record → apply in-memory state → acknowledge. Keep region journals independent; do not emulate a cross-region transaction or put entity payloads in the coordinator journal.
Phased packets
- Journal/schema/checkpoint foundation — typed handoff records, entity-addressed input, world journal version 3 bump/rollback compatibility, and compaction preservation for active handoffs, epochs, tombstones, and receipts.
- Program contract + source export/fence — pure
prepare_entity_transferhook, region-sharded mode gate, complete bounded entity payload, persist-before-apply source record, and source-side stale-write rejection. No receipt until apply/replay succeeds. - Destination import — module/schema/digest validation, persist-before-apply import, idempotency by handoff ID, durable receipt only after apply/replay, and failure tests.
- Coordinator/recovery — journal start and observed receipts, retry/reconcile after crashes, and region-map switch only after matching durable receipts and a durable completion record.
- Client/operations — explicit transit/stuck status, fail-closed entity reads/writes while in transit, stale-route response, metrics/alerting, and feature-gated end-to-end acceptance.
Dependencies: 1 → 2 → 3 → 4 → 5. Each packet is separately mergeable after its predecessor. Follow the design note's recommended defaults; the open questions for Drew are recorded there and do not block the protocol work.
Acceptance
- No entity duplication or silent loss across any injected failure point.
- Source mutations are fenced at durable export; destination is routable only after completion.
- Exact retries are idempotent; conflicting imports fail closed.
- Actor crash between journal append and in-memory apply recovers by replay before returning a receipt.
- Coordinator and region restart/replay/compaction retain correct ownership and recovery state.
- No cross-region transaction, automatic rollback after export, or durable client write queue.
Acceptance criteria
- All five phased packets land in dependency order (1 → 2 → 3 → 4 → 5), each separately merged after its predecessor — filed as code issues id: implement #3870 phase 1 — journal/schema/checkpoint foundation for region-seam handoff #3900 (phase 1), id: implement #3870 phase 2 — program transfer contract + source export/fence #3901 (phase 2), id: implement #3870 phase 3 — destination import for region-seam handoff #3902 (phase 3), id: implement #3870 phase 4 — coordinator state machine + recovery for region-seam handoff #3903 (phase 4), id: implement #3870 phase 5 — client/operations surface + gated enablement for region-seam handoff #3904 (phase 5).
- No entity duplication or silent loss across any injected failure point (crashes between prepare/persist/apply/acknowledge, coordinator restart, region-map switch).
- Source mutations are fenced at durable-record time; a receipt exists only after destination apply/replay succeeds.
- Region journals stay independent: no cross-region transaction emulation, no entity payloads in the coordinator journal.
Activity
dezren39 commentedon Nov 1, 2026
agent-note:v1 — task 5859 triage record for #3870 (lane D worker, 2026-11-01).
Grounding (verified fresh this shift, main 33aefa7)
doc/2026-11-01_design_id2818.mdis in PR design(id): #2818 region-seam handoff format #3875 (OPEN, branchdesign/id-2818, docs-only).pkgs/id/src/world/mod.rs—JournalEntryenum at :468-475,CrossWorldWriteas acceptance-policy only at :579-585, journal versioning at :646-683 (current max version 2),WorldProgramtrait at :871-925 with opaque input + whole-program snapshot and NO entity transfer hooks. Confirms the design's premise: this adds a transfer contract; no region coordinator or entity export/import exists today.world/actor.rs:248-259,375-392).Decision (already fixed by #2818 design + #3870 body — this triage routes it, it does not re-decide)
Journaled intent → source export/fence → destination import → coordinator completion, for application-owned entities only. Required local order everywhere: prepare/validate → persist typed record → apply in-memory state → acknowledge. Region journals stay independent; the coordinator journal holds membership/region-map/handoff records and NEVER entity payloads; no cross-region transaction is emulated.
Recommendation / invariants the packets must hold
Adopt the design's defaults (its §9 questions are non-blocking, below). Invariants (design §7): no duplicate writer (export fences source before destination can become routable); no silent loss (source export is the durable recovery copy until completion is verified); exactly-once effect per
handoff_idunder at-least-once delivery; monotonic owner epochs; compaction preserves active handoffs, fences/tombstones, receipts, and epochs; 16 KiB v1 payload cap with oversize refused before fencing.Phased packets filed + enqueued (dependency chain 1 → 2 → 3 → 4 → 5; gated packets park on claim until their predecessor lands)
repo-health:v1:fix:developing-today/code:issue:3900repo-health:v1:fix:developing-today/code:issue:3901(gated on id: implement #3870 phase 1 — journal/schema/checkpoint foundation for region-seam handoff #3900)repo-health:v1:fix:developing-today/code:issue:3902(gated on id: implement #3870 phase 2 — program transfer contract + source export/fence #3901)repo-health:v1:fix:developing-today/code:issue:3903(gated on id: implement #3870 phase 3 — destination import for region-seam handoff #3902)repo-health:v1:fix:developing-today/code:issue:3904(gated on id: implement #3870 phase 4 — coordinator state machine + recovery for region-seam handoff #3903)Questions for Drew
None that block. The design's three open questions (§9: transfer unit = app-owned entity; transit reads rejected with status-only response; 16 KiB v1 cap) proceed on the design's recommended defaults, exactly as #3870's body directs ("Follow the design note's recommended defaults; the open questions for Drew are recorded there and do not block the protocol work"). A ruling on #2818 can amend a default before its phase lands.
dezren39 commentedon Nov 1, 2026
Intake review
Related: design code issue #2818 and design PR #3875 (
doc/2026-11-01_design_id2818.md); phase issues #3900–#3904 are already filed and in flight (phase 1 claimed, phases 2–5 parked behind it at intake time).Notes: This parent tracks the set; the per-phase acceptance lives on each phase issue. The design note's open questions for Drew are recorded there and explicitly do not block the protocol work.
Risks: The failure-injection matrix is the substance of this epic — a phase that lands without its crash-point tests leaves the journal's core promise unverified. Compaction preserving active handoffs/epochs/tombstones/receipts (phase 1) is the easiest place to silently lose state.
Suggested approach: Keep the parent as the set tracker: each phase's PR references this issue, and the parent closes when phase 5's feature-gated end-to-end acceptance passes.
— fleet monitor intake enrichment, 2026-11-01 run (protocol §5). Acceptance criteria appended to the body where missing; labels normalized.
dezren39 commentedon Nov 1, 2026
agent-note:v1 — CORRECTION to the task 5859 triage record above (lane D worker, 2026-11-01).
The phase task IDs in that record were mis-transcribed for phases 3–5 (an off-by-one from a garbled tool delivery). Verified just now against the live queue, the correct mapping is:
(Task 5868 is an unrelated CI triage task, not part of this set.) The dedupe keys in the original record are unchanged and correct. Current live state: task 5864 is claimed (phase 2 in progress); tasks 5865/5866/5867 are parked on their predecessor gates, as designed.
developing-today commentedon Nov 3, 2026
agent-note:v1
state: triaged (coverage pass)
Coverage pass 2026-11-03: reviewed in the fleet-wide per-issue pass (drift / overlap / already-handled / stale / blockers / ordering). Verdict: still live; queued in repo-health-code-pilot as triage at priority 40 (priority/normal). If this is already handled at current main, the triage closes it with evidence; if it needs splitting, the triage files the split.
Found via: coverage pass 2026-11-03
dezren39 commentedon Nov 3, 2026
Triage (task 8286, lane code-e): implementation tracker is live and correctly ordered — no new work to route.
Verified fresh 2026-11-03 against GitHub + the queue:
doc/2026-11-01_design_id2818.md); id: implement: journaled region-seam export/import #3870 implements that accepted design.Blocker/ordering (recorded per the coverage acceptance): the only thing between the current state and phase 3 is PR #3931 merging and #3901 closing. Nothing needs Drew (the design note's open questions are recorded there as non-blocking). No follow-up task was enqueued from this triage: dedupe showed the phase-2 port (task 8542) and the phase-3 parked task already cover the next steps, and a duplicate would violate the one-task-per-item rule. This tracker stays open until all five phases land.