feat(api): harden HAF indexer replay safety

README.md

@@ -753,6 +753,16 @@ The API workspace includes a resumable HAF sync skeleton. It reads HAF block-sea
 npm run indexer:run --workspace=@hivelore/api
 ```
 
+The indexer stores the last processed block number, operation index, and block hash. If a later HAF page shows a different hash for the checkpoint block, or the next block points at a different parent hash, the indexer deletes rebuildable `HiveEvent` rows from the fork point onward and replays the canonical rows. Projection writes are keyed by transaction ID and operation index, so replaying the same block range updates existing rows instead of double-counting events.
+
+To rebuild a range explicitly, pass the first block that should be replayed:
+
+```bash
+npm run indexer:replay --workspace=@hivelore/api -- 123456
+```
+
+Rebuild time is bounded by `INDEXER_BATCH_SIZE`, `INDEXER_MAX_BLOCKS_PER_RUN`, HAF latency, and database write throughput. With the default `INDEXER_MAX_BLOCKS_PER_RUN=1000`, one invocation rebuilds at most 1,000 blocks; larger backfills should be run repeatedly or under an always-on worker and timed in staging before relying on a public freshness SLO.
+
 Optional API environment variables:
 
 ```env

apps/api/package.json

@@ -7,6 +7,7 @@
     "predev": "prisma generate",
     "dev": "tsx watch src/server.ts",
     "indexer:run": "tsx src/indexer/runner.ts",
+    "indexer:replay": "tsx src/indexer/runner.ts --from-block",
     "search:reindex": "tsx src/scripts/reindex-search.ts",
     "smoke:hive-mainnet": "tsx src/scripts/hive-mainnet-smoke.ts",
     "prisma:generate": "prisma generate",

apps/api/prisma/migrations/20260907100000_add_indexer_block_hashes/migration.sql

@@ -0,0 +1,10 @@
+-- Add block linkage metadata so the HAF indexer can detect forked history and replay
+-- rebuildable projections from the divergent block.
+ALTER TABLE "HiveEvent"
+ADD COLUMN "blockHash" TEXT,
+ADD COLUMN "previousBlockHash" TEXT;
+
+ALTER TABLE "IndexerWatermark"
+ADD COLUMN "lastProcessedBlockHash" TEXT;
+
+CREATE INDEX "HiveEvent_blockHash_idx" ON "HiveEvent"("blockHash");

apps/api/prisma/schema.prisma

@@ -736,6 +736,8 @@ model HiveReference {
 model HiveEvent {
   id                  String            @id @default(cuid())
   blockNumber         BigInt
+  blockHash           String?
+  previousBlockHash   String?
   transactionId       String
   operationIndex      Int
   eventType           HiveEventType
@@ -749,6 +751,7 @@ model HiveEvent {
 
   @@unique([transactionId, operationIndex])
   @@index([blockNumber, operationIndex])
+  @@index([blockHash])
   @@index([eventType])
   @@index([blockchainTimestamp])
 }
@@ -757,6 +760,7 @@ model IndexerWatermark {
   name                        String    @id
   lastProcessedBlock          BigInt    @default(0)
   lastProcessedOperationIndex Int       @default(-1)
+  lastProcessedBlockHash      String?
   lastRunStartedAt            DateTime?
   lastRunFinishedAt           DateTime?
   createdAt                   DateTime  @default(now())