Changelog

[Unreleased]

[0.10.0] — 2026-07-26

Adds the Orchestration family — the 6th behavioral family — for internal coordination failures: the program’s own logic failed to complete an operation. Not retryable; no user-facing fix (report the bug).

Added

• Orchestration Family — 6th behavioral family. Severity 5, exit code 70 (EX_SOFTWARE), HTTP 500. Sits between Infrastructure (4) and Corruption (6) in the severity order.
• NewOrchestration / WrapOrchestration / WrapOrchestrationf — family-specific constructors.
• Bridge reference implementation (examples/cmd/bridge/ + examples/checkout/) — canonical classify->enrich->handle flow with 19 tests.

Changed

• Corruption severity 5 -> 6 — bumped to preserve total order after inserting Orchestration at 5. Relative ordering of original families unchanged.
• IsValid() boundary now spans six constants (Rejection..Orchestration).
• Removed 52 phantom //nolint:hierarchical-errors directives across 13 files — linter was never installed.

Fixed

• examples/go.mod phantom replace directive — replaced bridge v0.0.0-... + local replace with real bridge v0.3.2. Same class of bug as the v0.6.0 hotfix.

Modules

• go-error-family -> v0.10.0, diagnose -> v0.2.2, agent -> v0.2.2, bridge -> v0.3.2, diagnose/git -> v0.5.2, diagnose/postgres -> v0.5.2, examples -> v0.3.0

[0.9.0] — 2026-07-24

Structured-logging hook for HandleError* and an HTTP error-path fix. The root package remains zero-dependency.

Added

• HandleConfig.Logger *slog.Logger — optional structured-logging hook. When set, HandleErrorWithContext emits a single slog record (family, code, retryable, exit_code, context.* keys) alongside the CLI output, classifying once and logging once. Nil (default) preserves the original behavior.
• errorfamilytest.AssertHTTPStatus(tb, err, want) — test assertion for HTTP status codes (checks HTTPStatuser override first, then family default).

Changed

• writeHTTPError respects per-error HTTPStatuser overrides — fixes a bug where WithHTTPStatus overrides were silently dropped on the HTTP error path. Status is now computed once from the classified family, then checked for a per-error override.
• LogError / LogErrorContext now emit exit_code — every structured log record includes the resolved BSD exit code.

[0.8.0] — 2026-07-23

BuildFlow-inspired error handling additions. All new APIs use only the Go standard library — the root package remains zero-dependency.

Added

• HTTPStatuser interface — sixth consumer interface. Errors implementing HTTPStatus() int override the family-based HTTP status per-error. Mirrors the ExitCoder pattern.
• Error.WithHTTPStatus(status int) *Error — copy-on-write mutator (0 = use family default). Example: NewRejection("battle.not_found", "...").WithHTTPStatus(404) returns 404 instead of family default 400.
• RegisterClassificationType[T error](family Family) — generic type-based classifier sugar. One-liner for the common “type T → Family F” case.
• RegisterClassificationTypeFor[T error](r *Registry, family Family) — variant targeting a custom Registry.
• ExitCoder interface — fifth consumer interface. Errors implementing ExitCode() int override the family-based exit code per-error.
• Error.WithExitCode(code int) *Error — copy-on-write mutator (0 = use family default).
• Error.WithContextAny(key string, value any) *Error — type-safe context attachment for non-string values.
• WrapOnce / WrapOncef — idempotent wrap. Returns the existing *Error unchanged if the chain already contains one.
• errorfamilytest.AssertExitCode and errorfamilytest.AssertHTTPStatus — test assertions for exit codes and HTTP status codes.
• safeCauseString — panic-recovery guard around cause.Error().
• Fuzz tests: FuzzWrapOnce, FuzzContextValueToString, FuzzWithExitCode, FuzzWithHTTPStatus, FuzzRegisterClassificationType.
• Benchmarks: BenchmarkWithExitCode, BenchmarkExitCodeOverride, BenchmarkWithHTTPStatus, BenchmarkHTTPStatusOverride.
• Examples: ExampleError_WithHTTPStatus, ExampleHTTPStatus, ExampleRegisterClassificationType.

Changed

• Root module reverted from encoding/json/v2 to encoding/json — the GOEXPERIMENT=jsonv2 requirement (introduced in v0.7.0) has been removed. JSON output is byte-identical; only 2 call sites were affected.
• HTTPStatus(err) checks HTTPStatuser first — a per-error override wins over the family default.
• writeHTTPError no longer double-classifies — the Classify result is reused for both the response body and the status code.
• ExitCode(err) checks ExitCoder first — a non-zero custom exit code wins over the family default.
• Error.Error() / Summary() / formatVerbose() use safeCauseString for cause rendering.

[0.7.0] — 2026-07-09

Changed (BREAKING)

• Migrated root module to encoding/json/v2 — required GOEXPERIMENT=jsonv2 on Go 1.26. Reverted in v0.8.0.

[0.6.1] — 2026-07-05

Fixed

• Removed local replace directives and phantom require from published go.mod files. Root module is now genuinely zero-dependency.
• Examples extracted to separate module — examples/ has its own go.mod (requires root + diagnose). This keeps the root module truly zero-dependency.

[0.6.0] — 2026-07-05

Added

• RegisterClassifier / RegisterClassifiers — predicate-based classification for dynamic third-party errors (*sqlite.Error). Stored lock-free behind atomic.Pointer[[]Classifier], copy-on-write.
• Code(err) string — public code extraction wrapping errors.AsType[Coded].
• TemplateForCode(code) — registry-then-builtin template lookup for HTTP/gRPC boundaries.
• Wrap{Family}f variants — WrapRejectionf, WrapConflictf, WrapTransientf, WrapCorruptionf, WrapInfrastructuref. Nil-safe.
• HTTPStatus(err) / HTTPHandler(fn) — net/http middleware writing safe JSON responses. Never leaks err.Error().
• LogError(err, logger) / LogErrorContext — structured log/slog logging with family/code/retryable/context fields.
• errorfamilytest subpackage — AssertFamily, AssertCode, AssertRetryable, AssertContext, AssertContextMissing.
• Classification pipeline now 6 steps — classifiers added as step 5.

[0.5.0] — 2026-06-22

Added

• Registry type with Clone() for inherit-and-extend, test isolation, and scoped error handling.
• Family.Severity() — total order for multi-error classification.
• Family.HTTPStatus() — canonical family to HTTP status mapping.
• Family.RetryPolicy() — advisory retry defaults (Transient: 3 attempts, 100ms-5s).
• Error.JSON() — canonical JSON view for API boundaries.
• RegisterStdlibDefaults(reg) — pre-registered classifications for common stdlib errors.

Changed

• Copy-on-write errors — WithContext/WithCause/WithTimestamp return a NEW *Error.
• {key} template syntax — replaced {{.key}} to avoid collision with Go’s text/template.
• Severity-ordered multi-error classification — worst family wins, deterministic regardless of argument order.
• Lock-free sentinel lookup — atomic.Pointer[sentinelMap], ~5x faster, zero allocations.

[0.4.0] — 2026-06-17

Added

• TextMarshaler/TextUnmarshaler for Family/Audience — enables YAML/JSON config integration.
• ParseAudience / ParseStatus — case-insensitive string parsing for all enums.
• Family.Audience() — User / Ops / All for presentation-layer decisions.
• Integration tests.

Changed

• HandleConfig.Diagnose bool removed — diagnostics run whenever DiagnosticFunc is set.
• agent.Config.Enabled returns error — calling Analyze on a disabled agent is a programming error.

[0.3.0] — 2026-06-01

Added

• HandleErrorWithContext — context-propagating handler (canonical entry point).
• HandleErrorDetailedWithConfig — configurable structured result.
• CommandRunner interface — mock injection for testable diagnostic rules.
• ContextKey typed strings — replaces raw strings in rule specs.
• WithTimestamp — copy-on-write timestamp setter.

[0.2.0] — 2026-05-26

Changed

• Modularized diagnostic rules — git moved to diagnose/git, postgres to diagnose/postgres.

Added

• Fuzz tests and benchmarks.

[0.1.1] — 2026-05-16

Changed

• License changed to MIT.
• README rewritten (removed fabricated API docs).

[0.1.0] — 2026-05-10

Added

• Initial release.
• Family enum, interfaces, Error struct, constructors, Classify, HandleError, diagnostic rules, debug agent, templates.