From 9d301d7b1da155fd4f69f4f037107e6c93e6820d Mon Sep 17 00:00:00 2001
From: clawbot <clawbot@openclaw>
Date: Sun, 8 Feb 2026 16:09:16 -0800
Subject: [PATCH] Add deterministic file ordering in Builder.Build()

Sort file entries by path (lexicographic, byte-order) before
serialization to ensure deterministic output. Add fixedUUID support
for testing reproducibility, and a test asserting byte-identical
output from two runs with the same input.

Closes #23
---
 mfer/builder.go      |  8 ++++++++
 mfer/builder_test.go | 35 +++++++++++++++++++++++++++++++++++
 mfer/manifest.go     |  1 +
 mfer/serialize.go    |  9 +++++++--
 4 files changed, 51 insertions(+), 2 deletions(-)

diff --git a/mfer/builder.go b/mfer/builder.go
index 22d4d4a..34f72be 100644
--- a/mfer/builder.go
+++ b/mfer/builder.go
@@ -4,6 +4,7 @@ import (
 	"crypto/sha256"
 	"errors"
 	"io"
+	"sort"
 	"sync"
 	"time"
 
@@ -54,6 +55,7 @@ type Builder struct {
 	files          []*MFFilePath
 	createdAt      time.Time
 	signingOptions *SigningOptions
+	fixedUUID      []byte // if set, use this UUID instead of generating one
 }
 
 // NewBuilder creates a new Builder.
@@ -179,6 +181,11 @@ func (b *Builder) Build(w io.Writer) error {
 	b.mu.Lock()
 	defer b.mu.Unlock()
 
+	// Sort files by path for deterministic output
+	sort.Slice(b.files, func(i, j int) bool {
+		return b.files[i].Path < b.files[j].Path
+	})
+
 	// Create inner manifest
 	inner := &MFFile{
 		Version:   MFFile_VERSION_ONE,
@@ -190,6 +197,7 @@ func (b *Builder) Build(w io.Writer) error {
 	m := &manifest{
 		pbInner:        inner,
 		signingOptions: b.signingOptions,
+		fixedUUID:      b.fixedUUID,
 	}
 
 	// Generate outer wrapper
diff --git a/mfer/builder_test.go b/mfer/builder_test.go
index a92994f..27e69de 100644
--- a/mfer/builder_test.go
+++ b/mfer/builder_test.go
@@ -92,6 +92,41 @@ func TestBuilderBuild(t *testing.T) {
 	assert.True(t, strings.HasPrefix(buf.String(), MAGIC))
 }
 
+func TestBuilderDeterministicOutput(t *testing.T) {
+	buildManifest := func() []byte {
+		b := NewBuilder()
+		// Use a fixed createdAt and UUID so output is reproducible
+		b.createdAt = time.Date(2025, 1, 1, 0, 0, 0, 0, time.UTC)
+		b.fixedUUID = make([]byte, 16) // all zeros
+
+		mtime := ModTime(time.Date(2025, 6, 1, 0, 0, 0, 0, time.UTC))
+
+		// Add files in reverse order to test sorting
+		files := []struct {
+			path    string
+			content string
+		}{
+			{"c/file.txt", "content c"},
+			{"a/file.txt", "content a"},
+			{"b/file.txt", "content b"},
+		}
+		for _, f := range files {
+			r := bytes.NewReader([]byte(f.content))
+			_, err := b.AddFile(RelFilePath(f.path), FileSize(len(f.content)), mtime, r, nil)
+			require.NoError(t, err)
+		}
+
+		var buf bytes.Buffer
+		err := b.Build(&buf)
+		require.NoError(t, err)
+		return buf.Bytes()
+	}
+
+	out1 := buildManifest()
+	out2 := buildManifest()
+	assert.Equal(t, out1, out2, "two builds with same input should produce byte-identical output")
+}
+
 func TestBuilderBuildEmpty(t *testing.T) {
 	b := NewBuilder()
 
diff --git a/mfer/manifest.go b/mfer/manifest.go
index 203c79c..bea4fa1 100644
--- a/mfer/manifest.go
+++ b/mfer/manifest.go
@@ -17,6 +17,7 @@ type manifest struct {
 	pbOuter        *MFFileOuter
 	output         *bytes.Buffer
 	signingOptions *SigningOptions
+	fixedUUID      []byte // if set, use this UUID instead of generating one
 }
 
 func (m *manifest) String() string {
diff --git a/mfer/serialize.go b/mfer/serialize.go
index 0a2898c..24c9001 100644
--- a/mfer/serialize.go
+++ b/mfer/serialize.go
@@ -50,8 +50,13 @@ func (m *manifest) generateOuter() error {
 		return errors.New("internal error")
 	}
 
-	// Generate UUID and set on inner message
-	manifestUUID := uuid.New()
+	// Use fixed UUID if provided, otherwise generate a new one
+	var manifestUUID uuid.UUID
+	if len(m.fixedUUID) == 16 {
+		copy(manifestUUID[:], m.fixedUUID)
+	} else {
+		manifestUUID = uuid.New()
+	}
 	m.pbInner.Uuid = manifestUUID[:]
 
 	innerData, err := proto.MarshalOptions{Deterministic: true}.Marshal(m.pbInner)