docs(L1): add minor block commit-status fix review doc

[ping-ke]

Summary

Adds the review doc for the goquarkchain minor block commit-status fix, in both Chinese (minor-commit-status-review.md) and English (minor-commit-status-review.en.md).

This is documentation only (lives in the pm repo). The actual code changes ship as 3 stacked PRs in the goquarkchain repo; this doc gives reviewers the whole picture before they look at the diffs.

What the doc covers

• Background — a minor block has several independent states (body present / state present / broadcast+report done / commit marker present). The old code conflated "body present" with "committed", which broke crash recovery, head rewind, root reorg, and sidechain replay / sync retry.
• Approach — three ordered steps, one per PR:
  1. fix/minor-chain-head-locking — serialize rewind / root reorg / import under a consistent lock order; publish head state atomically.
  2. fix/minor-block-commit-status — split "body present" from "committed"; the marker is written by the shard layer only after broadcast/report succeed (incl. the force insert recovery mechanism).
  3. fix/minor-sidechain-body-anchor — use body-only / pruned bodies as sync anchors and recover history blocks missing their marker.
• Per-PR theme, commits, files, key points, and reviewer focus.
• Test plan — a risk→test mapping (by test name), including gaps still to be covered (multi-block chain-order commit, gap split / in-batch dedup).
• Non-goals — read-side snapshot atomicity (tracked in Minor root reorg publish is still not atomic for lock-free readers goquarkchain#693) and the "converge by retry" stance.

Suggested review order

Read the doc → PR1 → PR2 → PR3. The PRs have a strict dependency chain(concurrency → semantics → feature).

Notes

• Chinese and English versions are kept in sync; update both together on future edits.

[ping-ke]

Summary

Adds the review doc for the goquarkchain minor block commit-status fix, in both Chinese (minor-commit-status-review.md) and English (minor-commit-status-review.en.md).

This is documentation only (lives in the pm repo). The actual code changes ship as 3 stacked PRs in the goquarkchain repo; this doc gives reviewers the whole picture before they look at the diffs.

What the doc covers

• Background — a minor block has several independent states (body present / state present / broadcast+report done / commit marker present). The old code conflated "body present" with "committed", which broke crash recovery, head rewind, root reorg, and sidechain replay / sync retry.
• Approach — three ordered steps, one per PR:
  1. fix/minor-chain-head-locking — serialize rewind / root reorg / import under a consistent lock order; publish head state atomically.
  2. fix/minor-block-commit-status — split "body present" from "committed"; the marker is written by the shard layer only after broadcast/report succeed (incl. the force insert recovery mechanism).
  3. fix/minor-sidechain-body-anchor — use body-only / pruned bodies as sync anchors and recover history blocks missing their marker.
• Per-PR theme, commits, files, key points, and reviewer focus.
• Test plan — a risk→test mapping (by test name), including gaps still to be covered (multi-block chain-order commit, gap split / in-batch dedup).
• Non-goals — read-side snapshot atomicity (tracked in Minor root reorg publish is still not atomic for lock-free readers goquarkchain#693) and the "converge by retry" stance.

Suggested review order

Read the doc → PR1 → PR2 → PR3. The PRs have a strict dependency chain(concurrency → semantics → feature).

Notes

• Chinese and English versions are kept in sync; update both together on future edits.

[ping-ke]

Summary

Adds the review doc for the goquarkchain minor block commit-status fix, in both Chinese (minor-commit-status-review.md) and English (minor-commit-status-review.en.md).

This is documentation only (lives in the pm repo). The actual code changes ship as 3 stacked PRs in the goquarkchain repo; this doc gives reviewers the whole picture before they look at the diffs.

What the doc covers

• Background — a minor block has several independent states (body present / state present / broadcast+report done / commit marker present). The old code conflated "body present" with "committed", which broke crash recovery, head rewind, root reorg, and sidechain replay / sync retry.
• Approach — three ordered steps, one per PR:
  1. fix/minor-chain-head-locking — serialize rewind / root reorg / import under a consistent lock order; publish head state atomically.
  2. fix/minor-block-commit-status — split "body present" from "committed"; the marker is written by the shard layer only after broadcast/report succeed (incl. the force insert recovery mechanism).
  3. fix/minor-sidechain-body-anchor — use body-only / pruned bodies as sync anchors and recover history blocks missing their marker.
• Per-PR theme, commits, files, key points, and reviewer focus.
• Test plan — a risk→test mapping (by test name), including gaps still to be covered (multi-block chain-order commit, gap split / in-batch dedup).
• Non-goals — read-side snapshot atomicity (tracked in Minor root reorg publish is still not atomic for lock-free readers goquarkchain#693) and the "converge by retry" stance.

Suggested review order

Read the doc → PR1 → PR2 → PR3. The PRs have a strict dependency chain(concurrency → semantics → feature).

Notes

• Chinese and English versions are kept in sync; update both together on future edits.

[ping-ke]

Summary

Adds the review doc for the goquarkchain minor block commit-status fix, in both Chinese (minor-commit-status-review.md) and English (minor-commit-status-review.en.md).

This is documentation only (lives in the pm repo). The actual code changes ship as 3 stacked PRs in the goquarkchain repo; this doc gives reviewers the whole picture before they look at the diffs.

What the doc covers

• Background — a minor block has several independent states (body present / state present / broadcast+report done / commit marker present). The old code conflated "body present" with "committed", which broke crash recovery, head rewind, root reorg, and sidechain replay / sync retry.
• Approach — three ordered steps, one per PR:
  1. fix/minor-chain-head-locking — serialize rewind / root reorg / import under a consistent lock order; publish head state atomically.
  2. fix/minor-block-commit-status — split "body present" from "committed"; the marker is written by the shard layer only after broadcast/report succeed (incl. the force insert recovery mechanism).
  3. fix/minor-sidechain-body-anchor — use body-only / pruned bodies as sync anchors and recover history blocks missing their marker.
• Per-PR theme, commits, files, key points, and reviewer focus.
• Test plan — a risk→test mapping (by test name), including gaps still to be covered (multi-block chain-order commit, gap split / in-batch dedup).
• Non-goals — read-side snapshot atomicity (tracked in Minor root reorg publish is still not atomic for lock-free readers goquarkchain#693) and the "converge by retry" stance.

Suggested review order

Read the doc → PR1 → PR2 → PR3. The PRs have a strict dependency chain(concurrency → semantics → feature).

Notes

• Chinese and English versions are kept in sync; update both together on future edits.

[ping-ke]

Summary

Adds the review doc for the goquarkchain minor block commit-status fix, in both Chinese (minor-commit-status-review.md) and English (minor-commit-status-review.en.md).

This is documentation only (lives in the pm repo). The actual code changes ship as 3 stacked PRs in the goquarkchain repo; this doc gives reviewers the whole picture before they look at the diffs.

What the doc covers

• Background — a minor block has several independent states (body present / state present / broadcast+report done / commit marker present). The old code conflated "body present" with "committed", which broke crash recovery, head rewind, root reorg, and sidechain replay / sync retry.
• Approach — three ordered steps, one per PR:
  1. fix/minor-chain-head-locking — serialize rewind / root reorg / import under a consistent lock order; publish head state atomically.
  2. fix/minor-block-commit-status — split "body present" from "committed"; the marker is written by the shard layer only after broadcast/report succeed (incl. the force insert recovery mechanism).
  3. fix/minor-sidechain-body-anchor — use body-only / pruned bodies as sync anchors and recover history blocks missing their marker.
• Per-PR theme, commits, files, key points, and reviewer focus.
• Test plan — a risk→test mapping (by test name), including gaps still to be covered (multi-block chain-order commit, gap split / in-batch dedup).
• Non-goals — read-side snapshot atomicity (tracked in Minor root reorg publish is still not atomic for lock-free readers goquarkchain#693) and the "converge by retry" stance.

Suggested review order

Read the doc → PR1 → PR2 → PR3. The PRs have a strict dependency chain(concurrency → semantics → feature).

Notes

• Chinese and English versions are kept in sync; update both together on future edits.

[ping-ke]

Summary

Adds the review doc for the goquarkchain minor block commit-status fix, in both Chinese (minor-commit-status-review.md) and English (minor-commit-status-review.en.md).

This is documentation only (lives in the pm repo). The actual code changes ship as 3 stacked PRs in the goquarkchain repo; this doc gives reviewers the whole picture before they look at the diffs.

What the doc covers

• Background — a minor block has several independent states (body present / state present / broadcast+report done / commit marker present). The old code conflated "body present" with "committed", which broke crash recovery, head rewind, root reorg, and sidechain replay / sync retry.
• Approach — three ordered steps, one per PR:
  1. fix/minor-chain-head-locking — serialize rewind / root reorg / import under a consistent lock order; publish head state atomically.
  2. fix/minor-block-commit-status — split "body present" from "committed"; the marker is written by the shard layer only after broadcast/report succeed (incl. the force insert recovery mechanism).
  3. fix/minor-sidechain-body-anchor — use body-only / pruned bodies as sync anchors and recover history blocks missing their marker.
• Per-PR theme, commits, files, key points, and reviewer focus.
• Test plan — a risk→test mapping (by test name), including gaps still to be covered (multi-block chain-order commit, gap split / in-batch dedup).
• Non-goals — read-side snapshot atomicity (tracked in Minor root reorg publish is still not atomic for lock-free readers goquarkchain#693) and the "converge by retry" stance.

Suggested review order

Read the doc → PR1 → PR2 → PR3. The PRs have a strict dependency chain(concurrency → semantics → feature).

Notes

• Chinese and English versions are kept in sync; update both together on future edits.

[ping-ke]

Summary

Adds the review doc for the goquarkchain minor block commit-status fix, in both Chinese (minor-commit-status-review.md) and English (minor-commit-status-review.en.md).

This is documentation only (lives in the pm repo). The actual code changes ship as 3 stacked PRs in the goquarkchain repo; this doc gives reviewers the whole picture before they look at the diffs.

What the doc covers

• Background — a minor block has several independent states (body present / state present / broadcast+report done / commit marker present). The old code conflated "body present" with "committed", which broke crash recovery, head rewind, root reorg, and sidechain replay / sync retry.
• Approach — three ordered steps, one per PR:
  1. fix/minor-chain-head-locking — serialize rewind / root reorg / import under a consistent lock order; publish head state atomically.
  2. fix/minor-block-commit-status — split "body present" from "committed"; the marker is written by the shard layer only after broadcast/report succeed (incl. the force insert recovery mechanism).
  3. fix/minor-sidechain-body-anchor — use body-only / pruned bodies as sync anchors and recover history blocks missing their marker.
• Per-PR theme, commits, files, key points, and reviewer focus.
• Test plan — a risk→test mapping (by test name), including gaps still to be covered (multi-block chain-order commit, gap split / in-batch dedup).
• Non-goals — read-side snapshot atomicity (tracked in Minor root reorg publish is still not atomic for lock-free readers goquarkchain#693) and the "converge by retry" stance.

Suggested review order

Read the doc → PR1 → PR2 → PR3. The PRs have a strict dependency chain(concurrency → semantics → feature).

Notes

• Chinese and English versions are kept in sync; update both together on future edits.

[ping-ke]

Summary

Adds the review doc for the goquarkchain minor block commit-status fix, in both Chinese (minor-commit-status-review.md) and English (minor-commit-status-review.en.md).

This is documentation only (lives in the pm repo). The actual code changes ship as 3 stacked PRs in the goquarkchain repo; this doc gives reviewers the whole picture before they look at the diffs.

What the doc covers

• Background — a minor block has several independent states (body present / state present / broadcast+report done / commit marker present). The old code conflated "body present" with "committed", which broke crash recovery, head rewind, root reorg, and sidechain replay / sync retry.
• Approach — three ordered steps, one per PR:
  1. fix/minor-chain-head-locking — serialize rewind / root reorg / import under a consistent lock order; publish head state atomically.
  2. fix/minor-block-commit-status — split "body present" from "committed"; the marker is written by the shard layer only after broadcast/report succeed (incl. the force insert recovery mechanism).
  3. fix/minor-sidechain-body-anchor — use body-only / pruned bodies as sync anchors and recover history blocks missing their marker.
• Per-PR theme, commits, files, key points, and reviewer focus.
• Test plan — a risk→test mapping (by test name), including gaps still to be covered (multi-block chain-order commit, gap split / in-batch dedup).
• Non-goals — read-side snapshot atomicity (tracked in Minor root reorg publish is still not atomic for lock-free readers goquarkchain#693) and the "converge by retry" stance.

Suggested review order

Read the doc → PR1 → PR2 → PR3. The PRs have a strict dependency chain(concurrency → semantics → feature).

Notes

• Chinese and English versions are kept in sync; update both together on future edits.