1.0 quality polish — code review, tests, bug fixes, documentation (#32)

Comprehensive quality pass targeting 1.0 release:

- Code review and refactoring
- Fix open bugs (#14, #16, #23)
- Expand test coverage
- Lint clean
- README update with build instructions (#9)
- Documentation improvements

Branched from `next` (active dev branch).

Reviewed-on: #32
Co-authored-by: clawbot <clawbot@noreply.example.org>
Co-committed-by: clawbot <clawbot@noreply.example.org>

mfer/builder.go

@@ -85,11 +85,12 @@ type FileHashProgress struct {
 
 // Builder constructs a manifest by adding files one at a time.
 type Builder struct {
-	mu             sync.Mutex
-	files          []*MFFilePath
-	createdAt      time.Time
-	signingOptions *SigningOptions
-	fixedUUID      []byte // if set, use this UUID instead of generating one
+	mu                sync.Mutex
+	files             []*MFFilePath
+	createdAt         time.Time
+	includeTimestamps bool
+	signingOptions    *SigningOptions
+	fixedUUID         []byte // if set, use this UUID instead of generating one
 }
 
 // SetSeed derives a deterministic UUID from the given seed string.
@@ -195,7 +196,7 @@ func (b *Builder) FileCount() int {
 // Returns an error if path is empty, size is negative, or hash is nil/empty.
 func (b *Builder) AddFileWithHash(path RelFilePath, size FileSize, mtime ModTime, hash Multihash) error {
 	if err := ValidatePath(string(path)); err != nil {
-		return err
+		return fmt.Errorf("add file: %w", err)
 	}
 	if size < 0 {
 		return errors.New("size cannot be negative")
@@ -219,6 +220,14 @@ func (b *Builder) AddFileWithHash(path RelFilePath, size FileSize, mtime ModTime
 	return nil
 }
 
+// SetIncludeTimestamps controls whether the manifest includes a createdAt timestamp.
+// By default timestamps are omitted for deterministic output.
+func (b *Builder) SetIncludeTimestamps(include bool) {
+	b.mu.Lock()
+	defer b.mu.Unlock()
+	b.includeTimestamps = include
+}
+
 // SetSigningOptions sets the GPG signing options for the manifest.
 // If opts is non-nil, the manifest will be signed when Build() is called.
 func (b *Builder) SetSigningOptions(opts *SigningOptions) {
@@ -239,9 +248,11 @@ func (b *Builder) Build(w io.Writer) error {
 
 	// Create inner manifest
 	inner := &MFFile{
-		Version:   MFFile_VERSION_ONE,
-		CreatedAt: newTimestampFromTime(b.createdAt),
-		Files:     b.files,
+		Version: MFFile_VERSION_ONE,
+		Files:   b.files,
+	}
+	if b.includeTimestamps {
+		inner.CreatedAt = newTimestampFromTime(b.createdAt)
 	}
 
 	// Create a temporary manifest to use existing serialization
@@ -253,15 +264,18 @@ func (b *Builder) Build(w io.Writer) error {
 
 	// Generate outer wrapper
 	if err := m.generateOuter(); err != nil {
-		return err
+		return fmt.Errorf("build: generate outer: %w", err)
 	}
 
 	// Generate final output
 	if err := m.generate(); err != nil {
-		return err
+		return fmt.Errorf("build: generate: %w", err)
 	}
 
 	// Write to output
 	_, err := w.Write(m.output.Bytes())
-	return err
+	if err != nil {
+		return fmt.Errorf("build: write output: %w", err)
+	}
+	return nil
 }