abczzz13 · abczzz13 · May 29, 2026 · May 29, 2026 · May 29, 2026 · May 29, 2026
@@ -22,8 +22,8 @@ jobs:
           - go-version: "1.26.x"
             go-label: go126
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-go@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
         with:
           go-version: ${{ matrix.go-version }}
           cache: true
@@ -36,7 +36,7 @@ jobs:
       - run: go test -race ./...
       - run: go test -coverprofile=coverage.out ./...
       - run: go tool cover -func=coverage.out
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: coverage-root-${{ matrix.go-label }}
           path: coverage.out
@@ -53,8 +53,8 @@ jobs:
           - go-version: "1.26.x"
             go-label: go126
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-go@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
         with:
           go-version: ${{ matrix.go-version }}
           cache: true
@@ -67,7 +67,7 @@ jobs:
       - run: GOWORK=off go -C observe/prometheus test -race ./...
       - run: GOWORK=off go -C observe/prometheus test -coverprofile=../../coverage-prometheus.out ./...
       - run: GOWORK=off go -C observe/prometheus tool cover -func=../../coverage-prometheus.out
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         with:
           name: coverage-prometheus-${{ matrix.go-label }}
           path: coverage-prometheus.out
@@ -76,8 +76,8 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-go@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
         with:
           go-version: "1.26.x"
           cache: true
@@ -86,15 +86,15 @@ jobs:
             go.sum
             observe/prometheus/go.mod
             observe/prometheus/go.sum
-      - uses: extractions/setup-just@v4
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
       - run: go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.8.0
       - run: just lint
 
   actionlint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-go@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
         with:
           go-version: "1.26.x"
           cache: true
@@ -103,7 +103,7 @@ jobs:
             go.sum
             observe/prometheus/go.mod
             observe/prometheus/go.sum
-      - uses: extractions/setup-just@v4
+      - uses: extractions/setup-just@53165ef7e734c5c07cb06b3c8e7b647c5aa16db3 # v4
       - run: go install github.com/rhysd/actionlint/cmd/actionlint@v1.7.10
       - run: just actionlint
 
@@ -121,10 +121,10 @@ jobs:
       group: benchmark-compare-${{ github.event.pull_request.number }}
       cancel-in-progress: true
     steps:
-      - uses: actions/checkout@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
         with:
           fetch-depth: 0
-      - uses: actions/setup-go@v6
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
         with:
           go-version: "1.26.x"
           cache: true
@@ -179,7 +179,7 @@ jobs:
             fi
           } >> "$GITHUB_STEP_SUMMARY"
 
-      - uses: actions/upload-artifact@v7
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
         if: always()
         with:
           name: benchmark-compare

@@ -0,0 +1,126 @@
+name: Coverage
+
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+permissions:
+  contents: read
+
+concurrency:
+  group: coverage-pages-${{ github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  coverage:
+    runs-on: ubuntu-latest
+    env:
+      GOWORK: off
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version: "1.26.x"
+          cache: true
+          cache-dependency-path: |
+            go.mod
+            go.sum
+            observe/prometheus/go.mod
+            observe/prometheus/go.sum
+
+      - name: Run coverage
+        run: |
+          set -euo pipefail
+          go test -coverprofile=coverage.out ./...
+          GOWORK=off go -C observe/prometheus test -coverprofile=../../coverage-prometheus.out ./...
+
+      - name: Build coverage site
+        run: |
+          set -euo pipefail
+          mkdir -p public/coverage
+
+          go tool cover -func=coverage.out | tee public/coverage/root.txt
+          go tool cover -html=coverage.out -o public/coverage/root.html
+          GOWORK=off go -C observe/prometheus tool cover -func=../../coverage-prometheus.out | tee public/coverage/prometheus.txt
+          GOWORK=off go -C observe/prometheus tool cover -html=../../coverage-prometheus.out -o ../../public/coverage/prometheus.html
+
+          root_pct=$(awk '/^total:/ {print $3}' public/coverage/root.txt)
+          prometheus_pct=$(awk '/^total:/ {print $3}' public/coverage/prometheus.txt)
+          root_num=${root_pct%%%}
+          root_int=${root_num%.*}
+
+          color="#e05d44"
+          if [ "$root_int" -ge 90 ]; then
+            color="#4c1"
+          elif [ "$root_int" -ge 75 ]; then
+            color="#dfb317"
+          fi
+
+          cat > public/coverage.svg <<EOF
+          <svg xmlns="http://www.w3.org/2000/svg" width="108" height="20" role="img" aria-label="coverage: $root_pct">
+            <linearGradient id="s" x2="0" y2="100%">
+              <stop offset="0" stop-color="#bbb" stop-opacity=".1"/>
+              <stop offset="1" stop-opacity=".1"/>
+            </linearGradient>
+            <clipPath id="r"><rect width="108" height="20" rx="3" fill="#fff"/></clipPath>
+            <g clip-path="url(#r)">
+              <rect width="63" height="20" fill="#555"/>
+              <rect x="63" width="45" height="20" fill="$color"/>
+              <rect width="108" height="20" fill="url(#s)"/>
+            </g>
+            <g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110">
+              <text aria-hidden="true" x="325" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="530">coverage</text>
+              <text x="325" y="140" transform="scale(.1)" fill="#fff" textLength="530">coverage</text>
+              <text aria-hidden="true" x="845" y="150" fill="#010101" fill-opacity=".3" transform="scale(.1)" textLength="350">$root_pct</text>
+              <text x="845" y="140" transform="scale(.1)" fill="#fff" textLength="350">$root_pct</text>
+            </g>
+          </svg>
+          EOF
+
+          cat > public/coverage/index.html <<EOF
+          <!doctype html>
+          <html lang="en">
+            <head>
+              <meta charset="utf-8">
+              <meta name="viewport" content="width=device-width, initial-scale=1">
+              <title>clientip coverage</title>
+            </head>
+            <body>
+              <h1>clientip coverage</h1>
+              <p><img src="../coverage.svg" alt="coverage: $root_pct"></p>
+              <ul>
+                <li>Root module: <strong>$root_pct</strong> (<a href="root.html">HTML</a>, <a href="root.txt">text</a>)</li>
+                <li>Prometheus adapter: <strong>$prometheus_pct</strong> (<a href="prometheus.html">HTML</a>, <a href="prometheus.txt">text</a>)</li>
+              </ul>
+            </body>
+          </html>
+          EOF
+
+      - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7
+        with:
+          name: coverage-site
+          path: public/
+          retention-days: 14
+
+  deploy:
+    if: github.event_name == 'push'
+    needs: coverage
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - uses: actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 # v7
+        with:
+          name: coverage-site
+          path: public/
+      - uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6
+      - uses: actions/upload-pages-artifact@7b1f4a764d45c48632c6b24a0339c27f5614fb0b # v4
+        with:
+          path: public/
+      - id: deployment
+        uses: actions/deploy-pages@d6db90164ac5ed86f2b6aed7e0febac5b3c0c03e # v4
@@ -0,0 +1,50 @@
+name: Fuzz
+
+on:
+  pull_request:
+  schedule:
+    - cron: "15 4 * * 1"
+  workflow_dispatch:
+    inputs:
+      fuzz-depth:
+        description: "How long to run each fuzz target"
+        required: true
+        default: smoke
+        type: choice
+        options:
+          - smoke
+          - deep
+
+permissions:
+  contents: read
+
+jobs:
+  fuzz-smoke:
+    runs-on: ubuntu-latest
+    env:
+      GOWORK: off
+      PR_FUZZTIME: 30s
+      DEEP_FUZZTIME: 5m
+      DEEP_FUZZ_MAX_HEADER_VALUE_LEN: "1048576"
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
+        with:
+          go-version: "1.26.x"
+          cache: true
+          cache-dependency-path: |
+            go.mod
+            go.sum
+      - name: Fuzz parser targets
+        run: |
+          set -euo pipefail
+          fuzztime="$PR_FUZZTIME"
+          if [ "${{ github.event_name }}" = "schedule" ] || [ "${{ inputs.fuzz-depth || 'smoke' }}" = "deep" ]; then
+            fuzztime="$DEEP_FUZZTIME"
+            export CLIENTIP_FUZZ_MAX_HEADER_VALUE_LEN="$DEEP_FUZZ_MAX_HEADER_VALUE_LEN"
+          fi
+          echo "Running parser fuzz targets for $fuzztime each with max header value length ${CLIENTIP_FUZZ_MAX_HEADER_VALUE_LEN:-default}"
+          go test -run '^$' -fuzz '^FuzzParseIP_RoundTripNormalization$' -fuzztime "$fuzztime" .
+          go test -run '^$' -fuzz '^FuzzParseRemoteAddr_RoundTripNormalization$' -fuzztime "$fuzztime" .
+          go test -run '^$' -fuzz '^FuzzParseXFFValues_ErrorShapeAndOutput$' -fuzztime "$fuzztime" .
+          go test -run '^$' -fuzz '^FuzzParseForwardedValues_ErrorShapeAndOutput$' -fuzztime "$fuzztime" .
@@ -0,0 +1,29 @@
+name: Scorecard
+
+on:
+  branch_protection_rule:
+  push:
+    branches: [main]
+  schedule:
+    - cron: "45 3 * * 2"
+
+permissions:
+  contents: read
+  security-events: write
+  id-token: write
+
+jobs:
+  scorecard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+        with:
+          persist-credentials: false
+      - uses: ossf/scorecard-action@05b42c624433fc40578a4040d5cf5e36ddca8cde # v2.4.2
+        with:
+          results_file: scorecard-results.sarif
+          results_format: sarif
+          publish_results: true
+      - uses: github/codeql-action/upload-sarif@7211b7c8077ea37d8641b6271f6a365a22a5fbfa # v4
+        with:
+          sarif_file: scorecard-results.sarif
@@ -13,8 +13,8 @@ jobs:
   govulncheck:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v6
-      - uses: actions/setup-go@v6
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6
+      - uses: actions/setup-go@4a3601121dd01d1626a1e23e37211e3254c1c06c # v6
         with:
           go-version: "1.26.x"
           cache: true

@@ -6,6 +6,21 @@ The format is based on Keep a Changelog and this project follows Semantic Versio
 
 ## [Unreleased]
 
+## [0.1.0] - 2026-05-29
+
+### Added
+
+- Added `FallbackReasonUnknown` for operational fallbacks triggered by unclassified strict errors.
+- Added threat-model, trusted-proxy configuration, and release checklist documentation.
+- Added CodeQL, OpenSSF Scorecard, fuzz smoke, and coverage publishing workflows with actions pinned by commit SHA.
+
+### Changed
+
+- README now documents the intended `v0.1.0` compatibility posture and links to generated coverage reports.
+- Unexpected extractor errors now fail closed instead of allowing source fallback.
+- Chain debug metadata now clones parsed chain slices before storing them on `Result`.
+- `just ci` now includes `govulncheck` through the `security` task.
+
 ## [0.0.8] - 2026-05-22
 
 ### Changed

@@ -105,6 +105,10 @@ CLIENTIP_ADAPTER_GOWORK=auto just test
 - README changes should stay user-facing and concise; detailed contributor guidance belongs here.
 - Public behavior changes should update `CHANGELOG.md` under `[Unreleased]`.
 
+## Releases
+
+See [docs/release.md](docs/release.md) for release tagging conventions, including the nested Prometheus adapter module tag format.
+
 ## Pull Requests
 
 - Describe the trust-boundary impact of the change, even when it is "none".

@@ -6,7 +6,7 @@ adapter_gowork := env_var_or_default("CLIENTIP_ADAPTER_GOWORK", "off")
 default:
   @just --list
 
-ci: test race coverage lint tidy-check actionlint
+ci: test race coverage lint tidy-check actionlint security
 
 fmt:
   gofumpt -extra -w .