Clarify concurrency semantics and polish docs/examples

.github/copilot-instructions.md

@@ -36,5 +36,6 @@
 ## API and Compatibility Notes
 - Do not introduce new usage of deprecated `Cause()`; prefer `errors.Is`/`errors.As` compatible flows and `Unwrap`/`Unwraps`.
 - Keep `errs.Join` behavior stable: ignore nil arguments and return nil when all arguments are nil.
+- Keep thread-safety semantics clear: `errs.Errors` is container-safe, but contained error values (including `errs.Error`) are not guaranteed goroutine-safe.
 - Treat changes to exported symbols, function signatures, and observable error formatting behavior as potentially breaking.
 - Error string and JSON formatting are validated by tests; when output behavior changes, update README examples and test expectations in the same change.

README.md

@@ -84,6 +84,12 @@ For multiple causes, it returns all causes as a slice.
 - If `WithCause` is given multiple times, the last cause is used
 - `errs.Join(...)` ignores `nil` arguments and returns `nil` if all arguments are `nil`
 
+### Concurrency notes
+
+- `errs.Errors` is goroutine-safe for container operations such as `Add`, `ErrorOrNil`, and `Unwrap`.
+- Errors stored in `errs.Errors` are not guaranteed to be goroutine-safe.
+- `errs.Error` has mutable state (`Context` map), so avoid concurrent mutation while formatting or encoding the same instance.
+
 ### Create new error instance with cause
 
 ```go

errlist.go

@@ -11,6 +11,9 @@ import (
 )
 
 // Errors is multiple error instance.
+//
+// Errors protects concurrent access to the container itself, but each contained
+// error may still be non-thread-safe.
 type Errors struct {
 	mu   sync.RWMutex
 	errs []error
@@ -167,7 +170,7 @@ func (es *Errors) Unwrap() []error {
 	if len(es.errs) == 0 {
 		return nil
 	}
-	cpy := make([]error, len(es.errs), cap(es.errs))
+	cpy := make([]error, len(es.errs))
 	copy(cpy, es.errs)
 	return cpy
 }

errs.go

@@ -18,6 +18,9 @@ const (
 
 // Error type is a implementation of error interface.
 // This type is for wrapping cause error instance.
+//
+// Error is not goroutine-safe. Its Context field is a mutable map and can be
+// modified by SetContext or direct field access.
 type Error struct {
 	wrapFlag bool
 	Err      error

example_test.go

@@ -65,9 +65,9 @@ func ExampleErrors() {
 		}()
 	}
 	wg.Wait()
-	fmt.Println("error ount =", len(errlist.Unwrap()))
+	fmt.Println("error count =", len(errlist.Unwrap()))
 	// Output:
-	// error ount = 100000
+	// error count = 100000
 }
 
 /* Copyright 2019-2023 Spiegel