next -> main (1.0.0 milestone) (#105)

Accumulating milestone branch. One squashed commit per closed issue; `next` is kept green and mergeable to `main` at any time without notice.

Landed so far:

- `chore: update golangci-lint to v2.12.2 with canonical config` (#54) — canonical v2-schema `.golangci.yml`, pins bumped in `Dockerfile` and `script/bootstrap`, tree at `0 issues.`. Three behaviour deltas are recorded in that PR's body: `Cache.StoreVariant` takes a context, `MetadataStorage.Store` no longer leaks temp files on failure, and the `signing_key` too-short error text gained a `value too short:` prefix.

Sequencing for the milestone is tracked in #103.

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

.golangci.yml

@@ -1,117 +1,34 @@
 version: "2"
 
+# Config schema uses the golangci-lint v2 layout (settings live under
+# linters.settings, not top-level linters-settings) so that the
+# thresholds below are actually applied by golangci-lint >= v2.
+
 run:
-  go: "1.24"
-  tests: false
+  timeout: 5m
+  modules-download-mode: readonly
 
 linters:
-  enable:
-    # Additional linters requested
-    - testifylint      # Checks usage of github.com/stretchr/testify
-    - usetesting       # usetesting is an analyzer that detects using os.Setenv instead of t.Setenv since Go 1.17
-    # - tagliatelle      # Disabled: we need snake_case for external API compatibility
-    - nlreturn         # nlreturn checks for a new line before return and branch statements
-    - nilnil           # Checks that there is no simultaneous return of nil error and an invalid value
-    - nestif           # Reports deeply nested if statements
-    - mnd              # An analyzer to detect magic numbers
-    - lll              # Reports long lines
-    - intrange         # intrange is a linter to find places where for loops could make use of an integer range
-    - gochecknoglobals # Check that no global variables exist
-
-    # Default/existing linters that are commonly useful
-    - govet
-    - errcheck
-    - staticcheck
-    - unused
-    - ineffassign
-    - misspell
-    - revive
-    - gosec
-    - unconvert
-    - unparam
-
-linters-settings:
-  lll:
-    line-length: 120
-
-  nestif:
-    min-complexity: 4
-
-  nlreturn:
-    block-size: 2
-
-  revive:
-    rules:
-      - name: var-naming
-        arguments:
-          - []
-          - []
-          - "upperCaseConst=true"
-
-  tagliatelle:
-    case:
-      rules:
-        json: snake
-        yaml: snake
-        xml: snake
-        bson: snake
-
-  testifylint:
-    enable-all: true
-
-  usetesting: {}
+  default: all
+  disable:
+    # Genuinely incompatible with project patterns
+    - exhaustruct      # Requires all struct fields
+    - depguard         # Dependency allow/block lists
+    - godot            # Requires comments to end with periods
+    - wsl              # Deprecated, replaced by wsl_v5
+    - wrapcheck        # Too verbose for internal packages
+    - varnamelen       # Short names like db, id are idiomatic Go
+  settings:
+    lll:
+      line-length: 88
+    funlen:
+      lines: 80
+      statements: 50
+    cyclop:
+      max-complexity: 15
+    dupl:
+      threshold: 100
 
 issues:
   max-issues-per-linter: 0
   max-same-issues: 0
-  exclude-rules:
-    # Exclude unused parameter warnings for cobra command signatures
-    - text: "parameter '(args|cmd)' seems to be unused"
-      linters:
-        - revive
-
-    # Allow ALL_CAPS constant names
-    - text: "don't use ALL_CAPS in Go names"
-      linters:
-        - revive
-
-    # Allow snake_case JSON tags for external API compatibility
-    - path: "internal/types/ris.go"
-      linters:
-        - tagliatelle
-
-    # Allow snake_case JSON tags for database models
-    - path: "internal/database/models.go"
-      linters:
-        - tagliatelle
-
-    # Allow generic package name for types that define data structures
-    - path: "internal/types/"
-      text: "avoid meaningless package names"
-      linters:
-        - revive
-
-    # Allow globals in the globals package (by design)
-    - path: "internal/globals/"
-      linters:
-        - gochecknoglobals
-
-    # Allow globals in main (Version/Buildarch set by ldflags)
-    - path: "cmd/"
-      linters:
-        - gochecknoglobals
-
-    # Allow blank imports for driver registration
-    - text: "blank-imports"
-      linters:
-        - revive
-
-    # Allow unused fx.Lifecycle parameters (required by fx signature)
-    - text: "parameter 'lc' seems to be unused"
-      linters:
-        - revive
-
-    # Allow unused context parameters in fx hooks
-    - text: "parameter 'ctx' seems to be unused"
-      linters:
-        - revive