@xyo-network/event-kit-statement-graph 0.1.4 → 0.1.7

package/README.md

@@ -30,27 +30,41 @@ const replay = await createFinalizedEventKitReplayController({
 
 await replay.sync()
 
+// A bounded worker still reports the real live finalized head while advancing
+// its durable projection by at most the requested number of blocks.
+await replay.sync({ maxBlocks: 4_096, signal })
+
+// The durable projection exposes its exact canonical XL1 root.
+const at = replay.anchor() // { block, hash } or null before the first commit
+
 const handshakes = createEventKitHandshakeReadModel({
   body: hash => replay.body(hash),
   viewer: replay.viewer(),
 })
 ```
 
-The candidate controller walks one finalized block at a time through Statement
-Graph with the exact Event Kit object-schema allowlist. Each block is staged
-before publication. An unresolved Statement Graph event, a missing or corrupt
-claimed object, or a missing or corrupt challenge/response attachment records
-an explicit blocked boundary and leaves `indexedThrough` before that block. A
-later `sync()` retries the same block; unavailability is never interpreted as
-absence or revocation.
-
-Published Statement Graph `0.5.0` admits consensus-elevated, subject-bearing
+The controller bulk-stages contiguous finalized ranges through Statement Graph
+with the exact Event Kit object-schema allowlist. The default full `sync()`
+catches up to the independently observed live head; `sync({ maxBlocks, signal })`
+lets a bounded worker retain that real `finalizedHead` while advancing
+`indexedThrough` by at most `maxBlocks`. A staged range is published only after
+every publisher-scoped object and required challenge/response attachment in it
+is verified. An unresolved Statement Graph event, a missing or corrupt claimed
+object, or a missing or corrupt attachment records the earliest affected block
+as an explicit blocked boundary and leaves `indexedThrough` before that block.
+A clean prefix is re-scanned and may be committed first. A later `sync()` retries
+the same blocked block; unavailability is never interpreted as absence or
+revocation. Cancellation retains only prefixes whose atomic checkpoint save has
+already resolved.
+
+Published Statement Graph `0.5.3` admits consensus-elevated, subject-bearing
 Claims and decodes Claim bodies from finalized block carriers while resolving
 claimed objects and acceptance attachments through the datalake. The Gate 2
 live rerun against that release remains the acceptance boundary.
 
-Statement Graph `0.5.0` uses fold version 4 and scan-checkpoint format 2. Event
-Kit's publisher-scoped outer checkpoint is also format 2. Only the exact
+Statement Graph `0.5.x` uses fold version 4 and scan-checkpoint format 2. Event
+Kit's publisher-scoped outer checkpoint is format 3 and binds
+`indexedThrough` to the exact canonical XL1 root hash. Only the exact
 current checkpoint and ordered Event Kit schema policy are accepted. Missing,
 additional, reordered, or version-suffixed policy entries fail closed as
 invalid content; no alternative-policy reader or in-place migration exists.
@@ -61,6 +75,10 @@ invalid content; no alternative-policy reader or in-place migration exists.
 - `indexedThrough` is the highest block whose Event Kit projection was fully
   committed, or `null` before the floor block has been indexed.
 
+`anchor()` returns the durable `{block, hash}` pair for `indexedThrough`. A
+height-only checkpoint from the previous format is replayed from the floor; it
+is never upgraded into root-bound evidence by assumption.
+
 The strict `EventKitReplayCheckpointZod` checkpoint binds network, chain ID,
 publisher, datalake source identity, floor block, Statement Graph fold version,
 and the ordered schema policy. It retains the complete canonical

package/dist/neutral/finalizedReplayController.d.ts

@@ -10,20 +10,35 @@ export interface EventKitReplayCheckpointStore {
 export interface FinalizedEventKitReplayOptions extends EventKitReplayCheckpointIdentity {
     readonly bodies: BodyReader;
     readonly chain: FinalizedBlockViewer;
+    /** Maximum contiguous blocks staged before one atomic checkpoint save. */
+    readonly checkpointBatchSize?: number;
     readonly checkpointStore: EventKitReplayCheckpointStore;
+    /** Maximum blocks requested by each Statement Graph bulk read. */
+    readonly scanBatchSize?: number;
 }
 export interface FinalizedEventKitReplayStatus {
     readonly blocked?: ReplayBlockedState;
     readonly finalizedHead: number;
     readonly indexedThrough: number | null;
 }
+export interface FinalizedEventKitReplayAnchor {
+    readonly block: number;
+    readonly hash: string;
+}
+export interface FinalizedEventKitReplaySyncOptions {
+    /** Advance at most this many blocks while still reporting the uncapped live finalized head. */
+    readonly maxBlocks?: number;
+    readonly signal?: AbortSignal;
+}
 export interface FinalizedEventKitReplayController {
+    /** Exact canonical XL1 root retained with the current durable projection. */
+    anchor(): Readonly<FinalizedEventKitReplayAnchor> | null;
     /** Resolve a verified lifecycle or acceptance-attachment body from the durable projection. */
     body(hash: string): Readonly<Record<string, unknown>> | undefined;
     snapshot(): Readonly<EventKitReplayCheckpoint>;
     status(): FinalizedEventKitReplayStatus;
     /** Walks clean finalized blocks and stops before the first unavailable body boundary. */
-    sync(): Promise<FinalizedEventKitReplayStatus>;
+    sync(options?: FinalizedEventKitReplaySyncOptions): Promise<FinalizedEventKitReplayStatus>;
     /** Snapshot viewer; request it again after `sync()` to observe the new checkpoint. */
     viewer(): StatementGraphViewer;
 }

package/dist/neutral/finalizedReplayController.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"finalizedReplayController.d.ts","sourceRoot":"","sources":["../../src/finalizedReplayController.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAA;AAMnF,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EAErB,MAAM,sCAAsC,CAAA;AAQ7C,OAAO,KAAK,EACV,wBAAwB,EACxB,gCAAgC,EAChC,kBAAkB,EAGnB,MAAM,uBAAuB,CAAA;AAO9B,MAAM,WAAW,6BAA6B;IAC5C,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IACxB,oFAAoF;IACpF,IAAI,CAAC,UAAU,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D;AAED,MAAM,WAAW,8BAA+B,SAAQ,gCAAgC;IACtF,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;IACpC,QAAQ,CAAC,eAAe,EAAE,6BAA6B,CAAA;CACxD;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC;AAED,MAAM,WAAW,iCAAiC;IAChD,8FAA8F;IAC9F,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;IACjE,QAAQ,IAAI,QAAQ,CAAC,wBAAwB,CAAC,CAAA;IAC9C,MAAM,IAAI,6BAA6B,CAAA;IACvC,yFAAyF;IACzF,IAAI,IAAI,OAAO,CAAC,6BAA6B,CAAC,CAAA;IAC9C,sFAAsF;IACtF,MAAM,IAAI,oBAAoB,CAAA;CAC/B;AAgRD,wBAAsB,uCAAuC,CAC3D,UAAU,EAAE,8BAA8B,GACzC,OAAO,CAAC,iCAAiC,CAAC,CAkB5C;AAED,uFAAuF;AACvF,wBAAgB,yCAAyC,CACvD,OAAO,CAAC,EAAE,OAAO,GAChB,6BAA6B,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAA;CAAE,CAazF"}
+{"version":3,"file":"finalizedReplayController.d.ts","sourceRoot":"","sources":["../../src/finalizedReplayController.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,yCAAyC,CAAA;AAMnF,OAAO,KAAK,EACV,UAAU,EACV,oBAAoB,EAErB,MAAM,sCAAsC,CAAA;AAQ7C,OAAO,KAAK,EACV,wBAAwB,EACxB,gCAAgC,EAChC,kBAAkB,EAGnB,MAAM,uBAAuB,CAAA;AAO9B,MAAM,WAAW,6BAA6B;IAC5C,yEAAyE;IACzE,IAAI,IAAI,OAAO,CAAC,OAAO,CAAC,CAAA;IACxB,oFAAoF;IACpF,IAAI,CAAC,UAAU,EAAE,wBAAwB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAC1D;AAED,MAAM,WAAW,8BAA+B,SAAQ,gCAAgC;IACtF,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAA;IAC3B,QAAQ,CAAC,KAAK,EAAE,oBAAoB,CAAA;IACpC,0EAA0E;IAC1E,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IACrC,QAAQ,CAAC,eAAe,EAAE,6BAA6B,CAAA;IACvD,kEAAkE;IAClE,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAA;CAChC;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,OAAO,CAAC,EAAE,kBAAkB,CAAA;IACrC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,cAAc,EAAE,MAAM,GAAG,IAAI,CAAA;CACvC;AAED,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED,MAAM,WAAW,kCAAkC;IACjD,+FAA+F;IAC/F,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAA;CAC9B;AAED,MAAM,WAAW,iCAAiC;IAChD,6EAA6E;IAC7E,MAAM,IAAI,QAAQ,CAAC,6BAA6B,CAAC,GAAG,IAAI,CAAA;IACxD,8FAA8F;IAC9F,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,GAAG,SAAS,CAAA;IACjE,QAAQ,IAAI,QAAQ,CAAC,wBAAwB,CAAC,CAAA;IAC9C,MAAM,IAAI,6BAA6B,CAAA;IACvC,yFAAyF;IACzF,IAAI,CAAC,OAAO,CAAC,EAAE,kCAAkC,GAAG,OAAO,CAAC,6BAA6B,CAAC,CAAA;IAC1F,sFAAsF;IACtF,MAAM,IAAI,oBAAoB,CAAA;CAC/B;AA4ZD,wBAAsB,uCAAuC,CAC3D,UAAU,EAAE,8BAA8B,GACzC,OAAO,CAAC,iCAAiC,CAAC,CAwB5C;AAED,uFAAuF;AACvF,wBAAgB,yCAAyC,CACvD,OAAO,CAAC,EAAE,OAAO,GAChB,6BAA6B,GAAG;IAAE,QAAQ,CAAC,KAAK,EAAE,SAAS,wBAAwB,EAAE,CAAA;CAAE,CAazF"}

package/dist/neutral/index.d.ts

@@ -2,7 +2,7 @@ export type { ActiveSourceWakeGrantAuthorizerOptions } from './activeSourceWakeG
 export { createActiveSourceWakeGrantAuthorizer } from './activeSourceWakeGrantAuthorizer.ts';
 export { createCheckpointStatementGraphViewer } from './checkpointViewer.ts';
 export { EventKitClaimedObjectSchemas, EventKitClaimedObjectSchemaSet, } from './eventKitSchemaPolicy.ts';
-export type { EventKitReplayCheckpointStore, FinalizedEventKitReplayController, FinalizedEventKitReplayOptions, FinalizedEventKitReplayStatus, } from './finalizedReplayController.ts';
+export type { EventKitReplayCheckpointStore, FinalizedEventKitReplayController, FinalizedEventKitReplayOptions, FinalizedEventKitReplayStatus, FinalizedEventKitReplaySyncOptions, } from './finalizedReplayController.ts';
 export { createFinalizedEventKitReplayController, createMemoryEventKitReplayCheckpointStore, } from './finalizedReplayController.ts';
 export type { StatementGraphGrantReadModelOptions } from './grantReadModel.ts';
 export { createStatementGraphGrantReadModel } from './grantReadModel.ts';

package/dist/neutral/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,sCAAsC,EAAE,MAAM,sCAAsC,CAAA;AAClG,OAAO,EAAE,qCAAqC,EAAE,MAAM,sCAAsC,CAAA;AAC5F,OAAO,EAAE,oCAAoC,EAAE,MAAM,uBAAuB,CAAA;AAC5E,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,2BAA2B,CAAA;AAClC,YAAY,EACV,6BAA6B,EAC7B,iCAAiC,EACjC,8BAA8B,EAC9B,6BAA6B,GAC9B,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,uCAAuC,EACvC,yCAAyC,GAC1C,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAA;AAC9E,OAAO,EAAE,kCAAkC,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAA;AAC1E,YAAY,EACV,sBAAsB,EACtB,0BAA0B,EAC1B,iCAAiC,EACjC,0BAA0B,EAC1B,sBAAsB,EACtB,4BAA4B,EAC5B,qCAAqC,EACrC,4CAA4C,EAC5C,iCAAiC,EACjC,uBAAuB,EACvB,sBAAsB,EACtB,6BAA6B,EAC7B,wCAAwC,EACxC,2CAA2C,EAC3C,yBAAyB,EACzB,gCAAgC,EAChC,sCAAsC,EACtC,gCAAgC,EAChC,yBAAyB,EACzB,4BAA4B,EAC5B,mCAAmC,EACnC,8CAA8C,EAC9C,iDAAiD,EACjD,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,wBAAwB,EACxB,gCAAgC,EAChC,4BAA4B,EAC5B,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,mCAAmC,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,uBAAuB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,sCAAsC,EAAE,MAAM,sCAAsC,CAAA;AAClG,OAAO,EAAE,qCAAqC,EAAE,MAAM,sCAAsC,CAAA;AAC5F,OAAO,EAAE,oCAAoC,EAAE,MAAM,uBAAuB,CAAA;AAC5E,OAAO,EACL,4BAA4B,EAC5B,8BAA8B,GAC/B,MAAM,2BAA2B,CAAA;AAClC,YAAY,EACV,6BAA6B,EAC7B,iCAAiC,EACjC,8BAA8B,EAC9B,6BAA6B,EAC7B,kCAAkC,GACnC,MAAM,gCAAgC,CAAA;AACvC,OAAO,EACL,uCAAuC,EACvC,yCAAyC,GAC1C,MAAM,gCAAgC,CAAA;AACvC,YAAY,EAAE,mCAAmC,EAAE,MAAM,qBAAqB,CAAA;AAC9E,OAAO,EAAE,kCAAkC,EAAE,MAAM,qBAAqB,CAAA;AACxE,OAAO,EAAE,gCAAgC,EAAE,MAAM,yBAAyB,CAAA;AAC1E,YAAY,EACV,sBAAsB,EACtB,0BAA0B,EAC1B,iCAAiC,EACjC,0BAA0B,EAC1B,sBAAsB,EACtB,4BAA4B,EAC5B,qCAAqC,EACrC,4CAA4C,EAC5C,iCAAiC,EACjC,uBAAuB,EACvB,sBAAsB,EACtB,6BAA6B,EAC7B,wCAAwC,EACxC,2CAA2C,EAC3C,yBAAyB,EACzB,gCAAgC,EAChC,sCAAsC,EACtC,gCAAgC,EAChC,yBAAyB,EACzB,4BAA4B,EAC5B,mCAAmC,EACnC,8CAA8C,EAC9C,iDAAiD,EACjD,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,gCAAgC,GACjC,MAAM,8BAA8B,CAAA;AACrC,YAAY,EACV,wBAAwB,EACxB,gCAAgC,EAChC,4BAA4B,EAC5B,kBAAkB,EAClB,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,uBAAuB,CAAA;AAC9B,OAAO,EACL,mCAAmC,EACnC,2BAA2B,EAC3B,4BAA4B,EAC5B,qBAAqB,EACrB,oBAAoB,EACpB,qBAAqB,GACtB,MAAM,uBAAuB,CAAA"}

package/dist/neutral/index.mjs

@@ -225,6 +225,8 @@ import {
   WakeSubscriptionAcceptanceSchema as WakeSubscriptionAcceptanceSchema2,
   WakeSubscriptionAcceptanceZod
 } from "@xyo-network/event-kit-schemas";
+import { PayloadBuilder as PayloadBuilder2 } from "@xyo-network/sdk";
+import { isBlockBoundWitness } from "@xyo-network/xl1-protocol";
 import { STATEMENT_FOLD_VERSION as STATEMENT_FOLD_VERSION2 } from "@xyo-network/xl1-statement-graph-schemas";
 import {
   resolveVerifiedBodies,
@@ -249,7 +251,7 @@ import {
   StatementScanCheckpointZod
 } from "@xyo-network/xl1-statement-graph-sdk";
 import { z } from "zod";
-var EVENT_KIT_REPLAY_CHECKPOINT_VERSION = 2;
+var EVENT_KIT_REPLAY_CHECKPOINT_VERSION = 3;
 var ResolvedReplayBodyZod = z.strictObject({
   body: z.record(z.string(), z.unknown()),
   hash: HashZod2
@@ -273,6 +275,7 @@ var EventKitReplayCheckpointZod = z.strictObject({
   floorBlock: BlockNumberZod,
   foldVersion: z.literal(STATEMENT_FOLD_VERSION),
   indexedThrough: z.union([BlockNumberZod, z.null()]),
+  indexedThroughHash: z.union([HashZod2, z.null()]),
   network: z.string().min(1),
   objectSchemas: z.tuple(EventKitClaimedObjectSchemas.map((schema) => z.literal(schema))),
   publisher: NormalizedAddressZod2,
@@ -280,6 +283,22 @@ var EventKitReplayCheckpointZod = z.strictObject({
   sourceId: z.string().min(1),
   version: z.literal(EVENT_KIT_REPLAY_CHECKPOINT_VERSION)
 });
+var LegacyEventKitReplayCheckpointIdentityZod = z.looseObject({
+  chainId: ChainIdZod,
+  floorBlock: BlockNumberZod,
+  network: z.string().min(1),
+  publisher: NormalizedAddressZod2,
+  sourceId: z.string().min(1),
+  version: z.literal(2)
+});
+function checkpointIdentityError(checkpoint, identity) {
+  if (checkpoint.chainId !== identity.chainId) return `chainId ${checkpoint.chainId} != ${identity.chainId}`;
+  if (checkpoint.floorBlock !== identity.floorBlock) return `floorBlock ${checkpoint.floorBlock} != ${identity.floorBlock}`;
+  if (checkpoint.network !== identity.network) return `network ${checkpoint.network} != ${identity.network}`;
+  if (checkpoint.sourceId !== identity.sourceId) return `sourceId ${checkpoint.sourceId} != ${identity.sourceId}`;
+  if (checkpoint.publisher !== identity.publisher) return `publisher ${checkpoint.publisher} != ${identity.publisher}`;
+  return void 0;
+}
 function appliedKey(record) {
   return `${record.txHash}:${record.eventHash}:${record.hashIndex}`;
 }
@@ -328,7 +347,7 @@ function sameClaimRecords(left, right) {
   });
 }
 function progressIntegrityError(checkpoint) {
-  const { indexedThrough } = checkpoint;
+  const { indexedThrough, indexedThroughHash } = checkpoint;
   if (indexedThrough !== null && indexedThrough > checkpoint.finalizedHead) {
     return `indexedThrough ${indexedThrough} exceeds finalizedHead ${checkpoint.finalizedHead}`;
   }
@@ -341,6 +360,9 @@ function progressIntegrityError(checkpoint) {
   if (indexedThrough !== null && checkpoint.scan === null) {
     return "scan checkpoint is missing for indexed state";
   }
+  if (indexedThrough === null !== (indexedThroughHash === null)) {
+    return "indexedThrough and indexedThroughHash must be present together";
+  }
   if (indexedThrough === null && checkpoint.applied.length > 0) {
     return "applied events exist before floorBlock has been indexed";
   }
@@ -512,26 +534,21 @@ async function persistedBodyIntegrityError(checkpoint) {
 }
 async function loadEventKitReplayCheckpoint(value, identity) {
   if (value === void 0 || value === null) return { status: "missing" };
+  if (typeof value === "object" && value !== null && value.version === 2) {
+    const legacy = LegacyEventKitReplayCheckpointIdentityZod.safeParse(value);
+    if (!legacy.success) {
+      return { detail: "recognized Event Kit replay checkpoint v2 has invalid identity", status: "corrupt" };
+    }
+    const mismatch2 = checkpointIdentityError(legacy.data, identity);
+    return mismatch2 === void 0 ? { status: "missing" } : { detail: mismatch2, status: "identity-mismatch" };
+  }
   const parsed = EventKitReplayCheckpointZod.safeParse(value);
   if (!parsed.success) {
     return { detail: "recognized Event Kit replay checkpoint has invalid content", status: "corrupt" };
   }
   const checkpoint = parsed.data;
-  if (checkpoint.chainId !== identity.chainId) {
-    return { detail: `chainId ${checkpoint.chainId} != ${identity.chainId}`, status: "identity-mismatch" };
-  }
-  if (checkpoint.floorBlock !== identity.floorBlock) {
-    return { detail: `floorBlock ${checkpoint.floorBlock} != ${identity.floorBlock}`, status: "identity-mismatch" };
-  }
-  if (checkpoint.network !== identity.network) {
-    return { detail: `network ${checkpoint.network} != ${identity.network}`, status: "identity-mismatch" };
-  }
-  if (checkpoint.sourceId !== identity.sourceId) {
-    return { detail: `sourceId ${checkpoint.sourceId} != ${identity.sourceId}`, status: "identity-mismatch" };
-  }
-  if (checkpoint.publisher !== identity.publisher) {
-    return { detail: `publisher ${checkpoint.publisher} != ${identity.publisher}`, status: "identity-mismatch" };
-  }
+  const mismatch = checkpointIdentityError(checkpoint, identity);
+  if (mismatch !== void 0) return { detail: mismatch, status: "identity-mismatch" };
   const bodyIntegrityError = await persistedBodyIntegrityError(checkpoint);
   if (bodyIntegrityError !== void 0) return { detail: bodyIntegrityError, status: "corrupt" };
   const integrityError = checkpointIntegrityError(checkpoint);
@@ -540,6 +557,8 @@ async function loadEventKitReplayCheckpoint(value, identity) {
 }
 
 // src/finalizedReplayController.ts
+var DEFAULT_CHECKPOINT_BATCH_SIZE = 4096;
+var DEFAULT_SCAN_BATCH_SIZE = 4096;
 function requireHead(value) {
   const head = Number(value);
   if (!Number.isSafeInteger(head) || head < 0) {
@@ -553,6 +572,19 @@ function requireFloor(value) {
   }
   return value;
 }
+function requirePositiveInteger(value, fallback, name) {
+  const selected = value ?? fallback;
+  if (!Number.isSafeInteger(selected) || selected < 1) {
+    throw new TypeError(`${name} must be a positive safe integer, received ${String(selected)}`);
+  }
+  return selected;
+}
+function requireMaxBlocks(value) {
+  if (value !== void 0 && (!Number.isSafeInteger(value) || value < 0)) {
+    throw new TypeError(`maxBlocks must be a nonnegative safe integer, received ${String(value)}`);
+  }
+  return value;
+}
 function replayContract(options, throughBlock) {
   return {
     eventBodyCorpus: { sourceId: options.sourceId },
@@ -572,6 +604,7 @@ function initialCheckpoint(options) {
     floorBlock: options.floorBlock,
     foldVersion: STATEMENT_FOLD_VERSION2,
     indexedThrough: null,
+    indexedThroughHash: null,
     network: options.network,
     objectSchemas: [...EventKitClaimedObjectSchemas],
     publisher: options.publisher,
@@ -615,21 +648,23 @@ function mergeBodies(existing, additions) {
   }
   return [...merged].map(([hash, body]) => ({ body, hash: HashZod3.parse(hash) })).toSorted((left, right) => left.hash.localeCompare(right.hash));
 }
-async function stageBlock(options, prior, block) {
-  const result = await scanFinalizedStatements(
-    options.chain,
-    options.bodies,
-    replayContract(options, block),
-    {
-      batchSize: 1,
-      ...prior.scan === null ? {} : { resumeFrom: prior.scan },
-      strict: { rejectAmbiguousSchemaDeclarations: true },
-      through: block
-    }
-  );
-  const applied = result.fold.applied.filter(
-    (record) => normalizeAddress3(record.subject) === options.publisher
-  );
+async function exactBlockHash(chain, block, chainId) {
+  const raw = await chain.block.blockByNumber(block);
+  if (!Array.isArray(raw) || raw.length !== 2 || !Array.isArray(raw[1])) {
+    throw new TypeError(`finalized block ${block} is unavailable`);
+  }
+  const header = raw[0];
+  if (!isBlockBoundWitness(header) || header.block !== block || header.chain !== chainId) {
+    throw new TypeError(`finalized block ${block} does not match the configured chain`);
+  }
+  const hash = await PayloadBuilder2.hash(PayloadBuilder2.omitStorageMeta(header));
+  const storageHash = header._hash;
+  if (typeof storageHash === "string" && storageHash !== hash) {
+    throw new TypeError(`finalized block ${block} has invalid storage hash metadata`);
+  }
+  return HashZod3.parse(hash);
+}
+async function stageAppliedBlock(options, applied) {
   const appliedObjectHashes = uniqueStrings(applied.map((record) => record.objectHash));
   const objects = await resolveVerifiedBodies(options.bodies, appliedObjectHashes);
   const missingObjects = appliedObjectHashes.filter((hash) => !objects.bodies.has(hash));
@@ -655,19 +690,72 @@ async function stageBlock(options, prior, block) {
     ...schemaMismatchedObjects,
     ...missingAttachments
   ]).map((hash) => HashZod3.parse(hash));
-  const isBlocked = result.unresolved.length > 0 || objectHashes.length > 0 || corrupt.length > 0;
   return {
-    applied,
     bodies: new Map([...objects.bodies, ...attachments.bodies]),
+    corrupt,
+    objectHashes
+  };
+}
+async function stageRange(options, prior, fromBlock, throughBlock, signal) {
+  signal?.throwIfAborted();
+  const beforeHash = await exactBlockHash(options.chain, throughBlock, options.chainId);
+  signal?.throwIfAborted();
+  const result = await scanFinalizedStatements(
+    options.chain,
+    options.bodies,
+    replayContract(options, throughBlock),
+    {
+      batchSize: requirePositiveInteger(options.scanBatchSize, DEFAULT_SCAN_BATCH_SIZE, "scanBatchSize"),
+      ...prior.scan === null ? {} : { resumeFrom: prior.scan },
+      ...signal === void 0 ? {} : { signal },
+      strict: { rejectAmbiguousSchemaDeclarations: true },
+      through: throughBlock
+    }
+  );
+  signal?.throwIfAborted();
+  const throughHash = await exactBlockHash(options.chain, throughBlock, options.chainId);
+  signal?.throwIfAborted();
+  if (beforeHash !== throughHash) {
+    throw new Error(`finalized block root changed while staging through ${throughBlock}`);
+  }
+  if (result.head !== throughBlock || result.checkpoint.contract.throughBlock !== throughBlock) {
+    throw new RangeError(
+      `finalized range scan stopped at ${result.head}/${result.checkpoint.contract.throughBlock}; requested ${throughBlock}`
+    );
+  }
+  const applied = result.fold.applied.filter((record) => record.block >= fromBlock && record.block <= throughBlock && normalizeAddress3(record.subject) === options.publisher);
+  const appliedByBlock = Map.groupBy(applied, (record) => record.block);
+  const unresolvedByBlock = Map.groupBy(
+    result.unresolved.filter((event) => event.block >= fromBlock && event.block <= throughBlock),
+    (event) => event.block
+  );
+  const relevantBlocks = [.../* @__PURE__ */ new Set([...appliedByBlock.keys(), ...unresolvedByBlock.keys()])].toSorted((left, right) => left - right);
+  const bodies = /* @__PURE__ */ new Map();
+  for (const block of relevantBlocks) {
+    signal?.throwIfAborted();
+    const staged = await stageAppliedBlock(options, appliedByBlock.get(block) ?? []);
+    for (const [hash, body] of staged.bodies) bodies.set(hash, body);
+    const unresolvedEvents = unresolvedByBlock.get(block) ?? [];
+    if (unresolvedEvents.length > 0 || staged.objectHashes.length > 0 || staged.corrupt.length > 0) {
+      return {
+        applied,
+        blocked: {
+          atBlock: block,
+          corrupt: staged.corrupt,
+          objectHashes: staged.objectHashes,
+          unresolvedEvents
+        },
+        bodies,
+        scan: result.checkpoint,
+        throughHash
+      };
+    }
+  }
+  return {
+    applied,
+    bodies,
     scan: result.checkpoint,
-    ...isBlocked ? {
-      blocked: {
-        atBlock: block,
-        corrupt,
-        objectHashes,
-        unresolvedEvents: result.unresolved
-      }
-    } : {}
+    throughHash
   };
 }
 var DefaultFinalizedEventKitReplayController = class {
@@ -678,6 +766,9 @@ var DefaultFinalizedEventKitReplayController = class {
     this.#options = options;
     this.#checkpoint = checkpoint;
   }
+  anchor() {
+    return this.#checkpoint.indexedThrough === null || this.#checkpoint.indexedThroughHash === null ? null : Object.freeze({ block: this.#checkpoint.indexedThrough, hash: this.#checkpoint.indexedThroughHash });
+  }
   body(hash) {
     return this.#checkpoint.bodies.find((entry) => entry.hash === hash)?.body;
   }
@@ -691,8 +782,8 @@ var DefaultFinalizedEventKitReplayController = class {
       indexedThrough: this.#checkpoint.indexedThrough
     };
   }
-  sync() {
-    const result = this.#syncTail.then(async () => await this.#syncOnce());
+  sync(options) {
+    const result = this.#syncTail.then(async () => await this.#syncOnce(options));
     this.#syncTail = result.then(
       () => true,
       () => false
@@ -702,8 +793,55 @@ var DefaultFinalizedEventKitReplayController = class {
   viewer() {
     return createCheckpointStatementGraphViewer(this.#checkpoint);
   }
-  async #syncOnce() {
+  async #commitRange(fromBlock, throughBlock, finalizedHead, signal) {
+    const staged = await stageRange(this.#options, this.#checkpoint, fromBlock, throughBlock, signal);
+    signal?.throwIfAborted();
+    if (staged.blocked !== void 0) {
+      const blockedAt = staged.blocked.atBlock;
+      if (blockedAt > fromBlock) {
+        const prefixBlocked = await this.#commitRange(fromBlock, blockedAt - 1, finalizedHead, signal);
+        if (prefixBlocked) return true;
+      }
+      const exact = await stageRange(this.#options, this.#checkpoint, blockedAt, blockedAt, signal);
+      signal?.throwIfAborted();
+      if (exact.blocked === void 0) {
+        await this.#commitStaged(exact, blockedAt, finalizedHead, signal);
+        return blockedAt === throughBlock ? false : await this.#commitRange(blockedAt + 1, throughBlock, finalizedHead, signal);
+      }
+      const blocked = EventKitReplayCheckpointZod.parse({
+        ...this.#checkpoint,
+        blocked: exact.blocked,
+        finalizedHead
+      });
+      signal?.throwIfAborted();
+      await this.#options.checkpointStore.save(blocked);
+      this.#checkpoint = blocked;
+      return true;
+    }
+    await this.#commitStaged(staged, throughBlock, finalizedHead, signal);
+    return false;
+  }
+  async #commitStaged(staged, throughBlock, finalizedHead, signal) {
+    const committed = EventKitReplayCheckpointZod.parse({
+      ...this.#checkpoint,
+      applied: mergeApplied(this.#checkpoint.applied, staged.applied),
+      bodies: mergeBodies(this.#checkpoint.bodies, staged.bodies),
+      blocked: void 0,
+      finalizedHead,
+      indexedThrough: throughBlock,
+      indexedThroughHash: staged.throughHash,
+      scan: staged.scan
+    });
+    signal?.throwIfAborted();
+    await this.#options.checkpointStore.save(committed);
+    this.#checkpoint = committed;
+  }
+  async #syncOnce(rawOptions) {
+    const maxBlocks = requireMaxBlocks(rawOptions?.maxBlocks);
+    const signal = rawOptions?.signal;
+    signal?.throwIfAborted();
     const finalizedHead = requireHead(await this.#options.chain.finalization.headNumber());
+    signal?.throwIfAborted();
     if (finalizedHead < this.#checkpoint.finalizedHead) {
       throw new RangeError(
         `finalized head regressed from ${this.#checkpoint.finalizedHead} to ${finalizedHead}; refusing to roll back`
@@ -714,39 +852,26 @@ var DefaultFinalizedEventKitReplayController = class {
       throw new RangeError(`finalized head ${finalizedHead} is behind indexedThrough ${indexedThrough}`);
     }
     let next = indexedThrough === null ? this.#options.floorBlock : indexedThrough + 1;
-    let changed = finalizedHead !== this.#checkpoint.finalizedHead;
-    while (next <= finalizedHead) {
-      const staged = await stageBlock(this.#options, this.#checkpoint, next);
-      if (staged.blocked !== void 0) {
-        const blocked = EventKitReplayCheckpointZod.parse({
-          ...this.#checkpoint,
-          blocked: staged.blocked,
-          finalizedHead
-        });
-        await this.#options.checkpointStore.save(blocked);
-        this.#checkpoint = blocked;
-        return this.status();
-      }
-      const committed = EventKitReplayCheckpointZod.parse({
-        ...this.#checkpoint,
-        applied: mergeApplied(this.#checkpoint.applied, staged.applied),
-        bodies: mergeBodies(this.#checkpoint.bodies, staged.bodies),
-        blocked: void 0,
-        finalizedHead,
-        indexedThrough: next,
-        scan: staged.scan
-      });
-      await this.#options.checkpointStore.save(committed);
-      this.#checkpoint = committed;
-      changed = false;
-      next += 1;
+    const remaining = next <= finalizedHead ? finalizedHead - next + 1 : 0;
+    const budget = maxBlocks === void 0 ? remaining : Math.min(maxBlocks, remaining);
+    const target = budget === 0 ? next - 1 : next + budget - 1;
+    const checkpointBatchSize = requirePositiveInteger(
+      this.#options.checkpointBatchSize,
+      DEFAULT_CHECKPOINT_BATCH_SIZE,
+      "checkpointBatchSize"
+    );
+    while (next <= target) {
+      signal?.throwIfAborted();
+      const throughBlock = Math.min(target, next + Math.min(checkpointBatchSize, target - next + 1) - 1);
+      if (await this.#commitRange(next, throughBlock, finalizedHead, signal)) return this.status();
+      next = throughBlock + 1;
     }
-    if (changed || this.#checkpoint.blocked !== void 0) {
+    if (this.#checkpoint.finalizedHead !== finalizedHead) {
       const observed = EventKitReplayCheckpointZod.parse({
         ...this.#checkpoint,
-        blocked: void 0,
         finalizedHead
       });
+      signal?.throwIfAborted();
       await this.#options.checkpointStore.save(observed);
       this.#checkpoint = observed;
     }
@@ -757,9 +882,15 @@ async function createFinalizedEventKitReplayController(rawOptions) {
   const options = {
     ...rawOptions,
     chainId: ChainIdZod2.parse(rawOptions.chainId),
+    checkpointBatchSize: requirePositiveInteger(
+      rawOptions.checkpointBatchSize,
+      DEFAULT_CHECKPOINT_BATCH_SIZE,
+      "checkpointBatchSize"
+    ),
     floorBlock: requireFloor(rawOptions.floorBlock),
     network: rawOptions.network.trim(),
     publisher: NormalizedAddressZod3.parse(rawOptions.publisher),
+    scanBatchSize: requirePositiveInteger(rawOptions.scanBatchSize, DEFAULT_SCAN_BATCH_SIZE, "scanBatchSize"),
     sourceId: rawOptions.sourceId.trim()
   };
   if (options.network.length === 0) throw new TypeError("network must not be empty");
@@ -874,7 +1005,7 @@ import {
   PublisherServiceZod,
   SOURCE_WAKE_EVENT_KIND as SOURCE_WAKE_EVENT_KIND2
 } from "@xyo-network/event-kit-schemas";
-import { PayloadBuilder as PayloadBuilder2 } from "@xyo-network/sdk";
+import { PayloadBuilder as PayloadBuilder3 } from "@xyo-network/sdk";
 import { XyoAddressZod as XyoAddressZod2 } from "@xyo-network/sdk-protocol/address";
 function handshakeEvidence(record) {
   return {
@@ -914,12 +1045,12 @@ async function verifiedHandshakeObjectBody(viewer, record) {
   const object = await viewer.object(record.objectHash);
   if (object?.assurance !== "resolved" || object.declaredSchema !== record.objectSchema || object.params === null) return void 0;
   const body = { schema: object.declaredSchema, ...object.params };
-  return await PayloadBuilder2.dataHash(body) === record.objectHash ? body : void 0;
+  return await PayloadBuilder3.dataHash(body) === record.objectHash ? body : void 0;
 }
 async function verifiedHandshakeAttachmentBody(resolver, hash) {
   const body = resolver?.(hash);
   if (body === void 0) return void 0;
-  return await PayloadBuilder2.dataHash(body) === hash ? { ...body } : void 0;
+  return await PayloadBuilder3.dataHash(body) === hash ? { ...body } : void 0;
 }
 function firstHandshakeRevocation(revocations, target) {
   const blocks = revocations.filter((item) => item.target === target).map((item) => item.block);