feat!: release v3.0.0

.github/RELEASE_GUIDE.md

@@ -88,5 +88,5 @@ Only `feat`, `fix`, `perf`, and `refactor` commits trigger releases. Use `chore`
 
 The release workflow warms the proxy automatically. If it still shows stale data:
 ```bash
-GOPROXY=https://proxy.golang.org go list -m github.com/jasoet/pkg/v2@v2.x.x
+GOPROXY=https://proxy.golang.org go list -m github.com/jasoet/pkg/v3@v3.x.x
 ```

.github/workflows/ci.yml

@@ -2,10 +2,15 @@ name: CI
 
 on:
   push:
-    branches: [main]
+    branches: [main, next, 'release/v2']
     tags: ['*']
   pull_request:
-    branches: [main]
+    branches: [main, next, 'release/v2']
+
+env:
+  # Pinned so a blocking API gate is reproducible. Matches the golang.org/x/exp
+  # pseudo-version already in go.mod; bump both together.
+  GORELEASE_VERSION: v0.0.0-20251113190631-e25ba8c21ef6
 
 jobs:
   ci:
@@ -17,9 +22,35 @@ jobs:
     steps:
       - name: Checkout
         uses: actions/checkout@v6
+        with:
+          fetch-depth: 0
 
       - name: Lint
         run: nix develop --command golangci-lint run ./...
 
       - name: Test
-        run: nix develop --command go test -race -count=1 ./... -tags=!examples
+        run: nix develop --command go test -race -count=1 ./...
+
+      - name: Vet (including build-tagged code)
+        # Compiles and vets example/integration/argo-tagged files that the untagged
+        # build never sees, closing the gap where tagged code regressions slip past CI.
+        run: nix develop --command go vet -tags='example integration argo' ./...
+
+      - name: API compatibility check
+        # Breaking API changes are intended on the v3 line, so this gate is
+        # informational wherever `next` is involved and blocking everywhere else:
+        #   - ref_name == 'next'  : pushes to next
+        #   - base_ref == 'next'  : PRs targeting next
+        #   - head_ref == 'next'  : the next -> main v3 release PR. Without this
+        #     clause base_ref is 'main' and the blocking gate fires on the whole
+        #     intended v3 break set, making the release PR unmergeable.
+        if: github.ref_name != 'next' && github.base_ref != 'next' && github.head_ref != 'next'
+        run: nix develop --command go run golang.org/x/exp/cmd/gorelease@${{ env.GORELEASE_VERSION }}
+
+      - name: API compatibility report (informational on next)
+        if: github.ref_name == 'next' || github.base_ref == 'next' || github.head_ref == 'next'
+        # gorelease reports "no baseline version" until the first non-prerelease
+        # /v3 tag exists on main; that is expected for the v3 release PR and is
+        # why this run must not gate the merge.
+        continue-on-error: true
+        run: nix develop --command go run golang.org/x/exp/cmd/gorelease@${{ env.GORELEASE_VERSION }}

.github/workflows/release.yml

@@ -2,21 +2,25 @@ name: Release
 
 on:
   push:
-    branches: [main]
+    branches: [main, next, 'release/v2']
   workflow_dispatch:
 
 jobs:
   test:
     name: Test
     runs-on: [self-hosted, local, macOS, ARM64]
+    timeout-minutes: 45
     steps:
       - name: Checkout
         uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Test
-        run: nix develop --command go test -race -count=1 ./... -tags=!examples
+        run: nix develop --command go test -race -count=1 ./...
+
+      - name: Integration tests
+        run: nix develop --command bash -c "go list ./... | grep -v examples | xargs go test -count=1 -tags=integration -timeout=20m"
 
   release:
     name: Release
@@ -55,6 +59,6 @@ jobs:
           sleep 5
           LATEST_TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
           if [ -n "$LATEST_TAG" ]; then
-            echo "Warming Go proxy for github.com/jasoet/pkg/v2@${LATEST_TAG}"
-            GOPROXY=https://proxy.golang.org GO111MODULE=on nix develop --command go list -m "github.com/jasoet/pkg/v2@${LATEST_TAG}" || true
+            echo "Warming Go proxy for github.com/jasoet/pkg/v3@${LATEST_TAG}"
+            GOPROXY=https://proxy.golang.org GO111MODULE=on nix develop --command go list -m "github.com/jasoet/pkg/v3@${LATEST_TAG}" || true
           fi

.gitignore

@@ -229,4 +229,6 @@ temporal.db
 .worktrees/
 
 # Node.js (semantic-release)
-node_modules/
+node_modules/
+# Superpowers workflow scratch (task briefs, reports, review diffs)
+.superpowers/

.golangci.yml

@@ -1,4 +1,4 @@
-# golangci-lint configuration for github.com/jasoet/pkg/v2
+# golangci-lint configuration for github.com/jasoet/pkg/v3
 # Go utility library with focus on reliability, security, and performance
 
 version: "2"

.releaserc.json

@@ -1,6 +1,14 @@
 {
   "branches": [
-    "main"
+    "main",
+    {
+      "name": "next",
+      "prerelease": true
+    },
+    {
+      "name": "release/v2",
+      "range": "2.13.x"
+    }
   ],
   "plugins": [
     [
@@ -78,7 +86,7 @@
           ]
         },
         "writerOpts": {
-          "headerPartial": "## [{{version}}]({{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}) ({{date}})\n\n**Full Changelog**: {{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}\n\n```\ngo get github.com/jasoet/pkg/v2@{{currentTag}}\n```"
+          "headerPartial": "## [{{version}}]({{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}) ({{date}})\n\n**Full Changelog**: {{host}}/{{owner}}/{{repository}}/compare/{{previousTag}}...{{currentTag}}\n\n```\ngo get github.com/jasoet/pkg/v3@{{currentTag}}\n```"
         }
       }
     ],

AI_PATTERN.md

@@ -1,15 +1,15 @@
 # AI Pattern Guide
 
-Guide for AI assistants working on projects that **use** `github.com/jasoet/pkg/v2`. This file is an index — read the linked READMEs and examples for full details.
+Guide for AI assistants working on projects that **use** `github.com/jasoet/pkg/v3`. This file is an index — read the linked READMEs and examples for full details.
 
 ## Quick Start
 
 ```go
-import "github.com/jasoet/pkg/v2/<package>"
+import "github.com/jasoet/pkg/v3/<package>"
 ```
 
 **Go Version:** 1.26+ (generics required)
-**Install:** `go get github.com/jasoet/pkg/v2@latest`
+**Install:** `go get github.com/jasoet/pkg/v3@latest`
 **v1 (no OTel):** `go get github.com/jasoet/pkg@v1.6.0` — preserved on [`release/v1`](https://github.com/jasoet/pkg/tree/release/v1) branch, unmaintained.
 **Project Template:** See [PROJECT_TEMPLATE.md](PROJECT_TEMPLATE.md) for recommended project structure, wiring patterns, test tiers (E2E), Swagger/OpenAPI setup, and Taskfile targets.
 
@@ -80,7 +80,6 @@ cfg, err := config.LoadString[AppConfig](yamlContent, "APP")
 |---------|-------------|--------|----------|
 | [otel](./otel/) | OpenTelemetry unified config (tracing, metrics, logging) | [README](otel/README.md) | [examples_test.go](otel/examples_test.go), [instrumentation_example_test.go](otel/instrumentation_example_test.go) |
 | [config](./config/) | Type-safe YAML config with env overrides and validation | [README](config/README.md) | [examples/](examples/config/) |
-| [logging](./logging/) | Structured logging with zerolog + OTel LoggerProvider | [README](logging/README.md) | [examples/](examples/logging/) |
 | [db](./db/) | Multi-database (PostgreSQL, MySQL, MSSQL) with GORM + migrations | [README](db/README.md) | [examples/](examples/db/) |
 | [docker](./docker/) | Container executor with dual API (functional + struct) | [README](docker/README.md) | [examples/](examples/docker/) |
 | [server](./server/) | HTTP server with Echo, health checks, graceful shutdown | [README](server/README.md) | [examples/](examples/server/) |
@@ -99,28 +98,35 @@ cfg, err := config.LoadString[AppConfig](yamlContent, "APP")
 ### Connect to a Database
 
 ```go
-pool, _ := db.ConnectionConfig{
-    DBType: db.Postgresql, Host: "localhost", Port: 5432,
-    Username: "user", Password: "pass", DBName: "mydb",
-    OTelConfig: otelConfig,
-}.Pool()
+pool, _ := db.NewPool(
+    db.WithConnectionConfig(db.ConnectionConfig{
+        DBType: db.Postgresql, Host: "localhost", Port: 5432,
+        Username: "user", Password: "pass", DBName: "mydb",
+    }),
+    db.WithOTelConfig(otelConfig),
+)
 ```
 
 > [db/README.md](db/README.md) for migrations, multi-DB, connection pooling.
 
 ### Start an HTTP Server
 
 ```go
-cfg := server.DefaultConfig(8080, operation, shutdown)
-server.StartWithConfig(cfg)
+srv, _ := server.New(
+    server.WithPort(8080),
+    server.WithOperation(operation),
+    server.WithShutdown(shutdown),
+)
+go func() { <-shutdownSignal; _ = srv.Shutdown(context.Background()) }()
+err := srv.Start() // blocks until Shutdown
 ```
 
 > [server/README.md](server/README.md) for health checks, middleware, EchoConfigurer.
 
 ### Add Retry Logic
 
 ```go
-cfg := retry.DefaultConfig().WithName("db.connect").WithOTel(otelConfig)
+cfg := retry.New(retry.WithName("db.connect"), retry.WithOTelConfig(otelConfig))
 err := retry.Do(ctx, cfg, func(ctx context.Context) error { return db.Ping(ctx) })
 ```
 

CONTEXT.md

@@ -0,0 +1,69 @@
+# pkg
+
+A Go utility library of independent packages, each wrapping one concern (HTTP, gRPC,
+database, containers, workflows) with OpenTelemetry instrumentation built in. Consumers
+import only the packages they need.
+
+## Language
+
+### Package kinds
+
+**Utility package**:
+A package whose wrapped dependency is incidental to why a consumer imports it — `rest`,
+`config`, `db`, `docker`, `server`, `grpc`, `compress`, `concurrent`, `retry`, `ssh`,
+`base32`. Third-party types are hidden from public signatures.
+_Avoid_: wrapper package, helper package
+
+**SDK-integration package**:
+A package whose whole purpose is to make a specific vendor SDK easier to use — `temporal`
+and `argo`. Vendor types appear in public signatures deliberately, because the consumer is
+writing against that SDK anyway.
+_Avoid_: leaky package, thin wrapper
+
+**Selective de-leak**:
+The decision to hide a third-party type behind a library-owned one in a utility package
+while deliberately keeping it visible in an SDK-integration package. See
+[ADR 0004](docs/adr/0004-selective-de-leak-of-third-party-types.md).
+_Avoid_: abstraction, encapsulation
+
+**Escape hatch**:
+A public method that deliberately returns a third-party type inside an otherwise de-leaked
+package, because no library-owned shape would carry the same information. Documented as
+such, never an oversight.
+_Avoid_: leak, loophole, backdoor
+
+### Conventions
+
+**Convention contract**:
+The set of rules every configurable package must satisfy — functional options constructor,
+`OTelConfig` field with the non-serialized tags, `WithOTelConfig` option, instrumentation
+through `otel.Layers`, and `Example*` tests behind README snippets.
+_Avoid_: standard, style guide
+
+**Convention test**:
+A test in `internal/archtest` that enforces the convention contract mechanically, by
+reflection over registered config structs and by compile-time assignment of each package's
+`WithOTelConfig`. Adding a package means extending the registry.
+_Avoid_: architecture test, lint rule
+
+**OTel injection point**:
+`WithOTelConfig(*otel.Config)` — the single supported way to give a package its telemetry
+providers. See [ADR 0002](docs/adr/0002-otel-config-is-injected-never-serialized.md).
+_Avoid_: otel setup, telemetry config
+
+**Docs-of-record**:
+An `Example*` test that a README snippet is copied from, so documentation cannot drift from
+a compiling API. A README code block without one is not trusted.
+_Avoid_: sample, snippet test
+
+### Release lines
+
+**v3 line**:
+Work on the `next` branch, published as `v3.0.0-next.N` prereleases, merged to `main` as
+`v3.0.0`. The only line receiving features. See
+[ADR 0001](docs/adr/0001-freeze-v2-and-ship-v3-as-one-big-bang.md).
+
+**Frozen line**:
+`release/v2`, pinned at v2.13.1, open to emergency patches only. `release/v1` is closed
+entirely at v1.6.0.
+_Avoid_: legacy, deprecated, maintenance branch