feat(stepable): add ReorgJunctionBlock() returning *pbbstream.BlockMeta

[Copilot]

Extends the Stepable interface to expose full block metadata at the reorg junction point, giving callers timestamp visibility without a separate block lookup.

Interface changes

• ReorgJunctionBlock() BlockRef → renamed to ReorgJunctionBlockRef() BlockRef
• New ReorgJunctionBlock() *pbbstream.BlockMeta added, returning id, number, parentId, parentNum, libNum, and timestamp

type Stepable interface {
    Step() StepType
    FinalBlockHeight() uint64
    ReorgJunctionBlockRef() BlockRef          // renamed
    ReorgJunctionBlock() *pbbstream.BlockMeta // new
}

Implementation changes

• forkable/forkable.go: reorgJunctionBlock field changed to *pbbstream.BlockMeta; sentChainSwitchSegments now uses junction.Object.(*ForkableBlock).Block.ToBlocKMeta() instead of junction.AsRef(); processCompleteBlocks and wrapBlockForkableObject signatures updated accordingly
• cursor_resolver.go: resolve() return type and sendUndoBlocks param updated to *pbbstream.BlockMeta; junction block set via blkObj.Block.ToBlocKMeta()
• types.go / preprocess.go: reorgJunctionBlock field type changed; nil-safe ReorgJunctionBlockRef() derives a BlockRef from the meta fields
• Tests: testStepable mock updated; cursor_resolver_test.go calls ReorgJunctionBlockRef() for BlockRef-only assertions; forkable tests use new tinyBlkMeta() helper and compare Id/Number fields

Original prompt

Feature: Stepable — ReorgJunctionBlock returns BlockMeta

Goal

Improve the Stepable interface so that:

1. The existing ReorgJunctionBlock() BlockRef is renamed to ReorgJunctionBlockRef() BlockRef.
2. A new ReorgJunctionBlock() *pbbstream.BlockMeta is added, returning the full metadata of the
   junction block (id, number, parentId, parentNum, libNum, timestamp).

This gives callers timestamp visibility on the reorg junction point without having to look up the
block separately.

Current state

// interfaces.go
type Stepable interface {
    Step() StepType
    FinalBlockHeight() uint64
    ReorgJunctionBlock() BlockRef      // <-- to rename
}

Four concrete implementations:

Type	File	Field type
ForkableObject	forkable/forkable.go:469	reorgJunctionBlock bstream.BlockRef
wrappedObject	types.go:131	reorgJunctionBlock BlockRef
preprocessedForkableObject	preprocess.go:64	reorgJunctionBlock BlockRef
testStepable (test)	hub/subscription_test.go:111	—

The reorgJunctionBlock value originates in two places:

• forkable/forkable.go sentChainSwitchSegments (line 838):
  junctionBlock = junction.AsRef() where junction is a *forkable.Block whose Object field
  holds *ForkableBlock (which has the full *pbbstream.Block).
  → Can call junction.Object.(*ForkableBlock).Block.ToBlocKMeta() to get *pbbstream.BlockMeta.

• cursor_resolver.go resolve (line 191–203):
  reorgJunctionBlock = blkObj.Block.AsRef() where blkObj.Block is a *pbbstream.Block.
  → Can call blkObj.Block.ToBlocKMeta() directly.

Implementation steps

Step 1 — Update Stepable interface (interfaces.go)

type Stepable interface {
    Step() StepType
    FinalBlockHeight() uint64
    ReorgJunctionBlockRef() BlockRef          // renamed
    ReorgJunctionBlock() *pbbstream.BlockMeta // new
}

Step 2 — Update ForkableObject (forkable/forkable.go)

• Change field: reorgJunctionBlock *pbbstream.BlockMeta
• Rename method ReorgJunctionBlock() → ReorgJunctionBlockRef(), returning blk.AsRef()-style
  value derived from the meta (or nil).
• Add method ReorgJunctionBlock() *pbbstream.BlockMeta returning the field directly.
• Update wrapBlockForkableObject signature: last param becomes reorgJunctionBlock *pbbstream.BlockMeta.
• Update all call sites of wrapBlockForkableObject (in forkable.go).
• Update sentChainSwitchSegments: return type junctionBlock *pbbstream.BlockMeta;
  set it via junction.Object.(*ForkableBlock).Block.ToBlocKMeta().
• Update processCompleteBlocks signature: reorgJunctionBlock *pbbstream.BlockMeta.

Step 3 — Update wrappedObject (types.go)

• Change field: reorgJunctionBlock *pbbstream.BlockMeta
• Add ReorgJunctionBlockRef() BlockRef returning NewBlockRef(w.reorgJunctionBlock.Id, w.reorgJunctionBlock.Number) (nil-safe).
• Rename existing ReorgJunctionBlock() to ReorgJunctionBlock() *pbbstream.BlockMeta.

Step 4 — Update preprocessedForkableObject (preprocess.go)

• Change field: reorgJunctionBlock *pbbstream.BlockMeta
• Copy from forkableObj.ReorgJunctionBlock() (the new meta-returning method).
• Add ReorgJunctionBlockRef() BlockRef (nil-safe, derived from meta).
• Rename existing ReorgJunctionBlock() return type to *pbbstream.BlockMeta.

Step 5 — Update cursor_resolver.go

• resolve return type: reorgJunctionBlock *pbbstream.BlockMeta
• Line 203: reorgJunctionBlock = blkObj.Block.ToBlocKMeta()
• sendUndoBlocks param: reorgJunctionBlock *pbbstream.BlockMeta
• wrappedObject.reorgJunctionBlock field is now *pbbstream.BlockMeta so assignment is direct.

Step 6 — Update test mocks

• hub/subscription_test.go testStepable: add both ReorgJunctionBlockRef() and
  ReorgJunctionBlock() methods.
• cursor_resolver_test.go: callers of obj.(Stepable).ReorgJunctionBlock() should call
  ReorgJunctionBlockRef() if they only need a BlockRef, or the new method if they need meta.

Files touched

• interfaces.go
• types.go
• preprocess.go
• cursor_resolver.go
• forkable/forkable.go
• hub/subscription_test.go
• cursor_resolver_test.go

Notes

• ToBlocKMeta() already exists on *pbbstream.Block (pb/sf/bstream/v1/bstream.go:32).
• All nil-checks that previously tested BlockRef == nil should now test *BlockMeta == nil.
• CHANGELOG.md must be updated once implementation is complete.

Created from VS Code.