feat: protocol 0.7.0 - source_hash format pin, JSON-shape anchors, RiskBand + CoverageSource sentinels (#4)

* feat: protocol 0.7.0 - pin source_hash format, add JSON-shape anchor fixtures

Closes #3.

- Pin FunctionIdentity::source_hash to a cross-producer-comparable format:
  first 8 bytes of SHA-256(canonical body bytes) rendered as 16 lowercase
  hex chars. Canonicalization rule: signature line, body, closing brace,
  no whitespace normalization. Producers that cannot canonicalize the
  same way MUST omit the field rather than emit a divergent format.
  Closes the cross-producer non-comparability gap that the 0.6.0
  "producer-defined, opaque string" wording allowed.
- New pub fn source_hash_for(body: &[u8]) -> String helper. Reuses the
  existing sha2 dependency, no new transitive deps. Anchor fixture pins
  source_hash_for(b"function foo() { return 1; }") to "74846e29a52fe863"
  so producers can self-test against the conformance value in their CIs.
- Tighten FunctionIdentity::stable_id_computed rustdoc with the literal
  phrase "NOT a validation gate"; consumers MUST NOT reject payloads
  whose stable_id differs from the computed value.
- Byte-level JSON-shape anchor fixtures for FunctionIdentity (full +
  minimal) plus anchor fixtures for blast_radius_id and importance_id
  parallel to the existing function_identity_id fixture.
- Per-field identity-stability assertions: function_identity_id is
  asserted invariant under independent mutation of start_column,
  end_line, end_column, source_hash. Refines the prior bundled
  function_identity_id_unchanged_by_columns into the per-field cases the
  rustdoc claims.
- IdentityResolution::Unresolved shape fixture documenting the wire
  bytes an MCP agent or cloud aggregator sees for a failed-join entry.
- Internal hex_prefix refactored to take a bytes count so the 4-byte
  truncation used by finding_id / hot_path_id / blast_radius_id /
  importance_id / function_identity_id and the 8-byte truncation used
  by source_hash_for share one auditable implementation.

PROTOCOL_VERSION and Cargo.toml [package].version both bumped 0.6.0 ->
0.7.0 in lockstep. 13 new tests, all green; clippy clean; doc-warning
clean; cargo publish --dry-run succeeds.

* feat: add Unknown sentinels to RiskBand and CoverageSource

Closes #5.

Adds `#[serde(other)] Unknown` to the two remaining public enums that
lacked the forward-compat sentinel. Surfaced by a /sweep audit of every
public enum in the crate after the 0.7.0 source_hash format pin landed:

- `RiskBand` (Response-side, `BlastRadiusEntry.risk_band`): future
  bands (`Critical`, `Negligible`) MAY now be added by producers as a
  minor bump; older consumers map unseen variants to Unknown rather
  than failing deserialization.
- `CoverageSource` (Request-side, `Request.coverage.sources`): future
  source kinds (`IstanbulDir`, `TraceEvent`, `RuntimeBeacon`) MAY be
  added by the CLI as a minor bump; sidecars that have not seen the
  new kind map it to Unknown and skip the entry.

Two new round-trip tests (`unknown_risk_band_round_trips`,
`unknown_coverage_source_round_trips`) lock the forward-compat
behaviour. Test count is now 61. Clippy / fmt / doc / publish all
green.

CHANGELOG `[0.7.0]` Added section gains a bullet. Module-level 0.7
overview block mentions the addition. No wire shape change for
existing payloads.

* ci: clear CI red on PR #4 (typos false positive + release.yml zizmor findings)

Fixes three failing CI checks on PR #4:

1. **Typos** (new failure caused by this PR): the byte-equal JSON anchor
   literal added in the 0.7.0 source_hash format pin contains the hex
   string `e25ba02c5e53651f`, which typos tokenizes on digit boundaries
   and flags `ba` as a misspelling of `by` / `be`. Adds the specific
   hex value to `[default.extend-identifiers]` in `_typos.toml` with a
   comment explaining the scope (panel-verified anchor; changing the
   test inputs would invalidate the cross-producer conformance fixture).
   Narrowly scoped to one identifier; does not whitelist `ba` globally.

2. **Actions Security (zizmor) - superfluous-actions** on
   `.github/workflows/release.yml`: replaces
   `softprops/action-gh-release@v3` with a `gh release create` shell
   step. Equivalent behaviour using the gh CLI already preinstalled on
   ubuntu-latest runners. Adds a re-run-safe guard that skips creation
   when the release already exists for the tag (e.g. workflow_dispatch
   re-runs on an existing tag). All inputs routed through env: vars per
   the workflow's existing security-note convention.

3. **Actions Security (zizmor) - use-trusted-publishing** on `cargo
   publish`: suppressed via `# zizmor: ignore[use-trusted-publishing]`
   inline pragma with a TODO comment documenting the migration path.
   Real migration to crates.io OIDC trusted publishing requires
   registering the trusted publisher on the crates.io web UI plus
   adding `id-token: write` permission to the job; that infra change is
   out of scope for this PR and tracked by the inline TODO.

4. **CI** (meta-job): aggregates the above; turns green automatically
   once Typos and Actions Security pass.

Local verification: cargo test (61 passed), clippy, fmt, doc, typos,
zizmor (no findings; 12 ignored, 1 suppressed) all clean.

Pre-existing context: main branch CI had been red for over a month due
to these two zizmor findings on release.yml. The Typos failure is
specific to this PR; the zizmor fixes incidentally unblock the
release pipeline ahead of v0.7.0 tagging.

Author: BartWaardenburg

.github/workflows/release.yml

@@ -134,6 +134,14 @@ jobs:
         shell: bash
         env:
           CARGO_REGISTRY_TOKEN: ${{ secrets.CARGO_REGISTRY_TOKEN }}
+        # zizmor: ignore[use-trusted-publishing]
+        # TODO(trusted-publishing): migrate to crates.io OIDC trusted
+        # publishing once the trusted publisher is registered for this
+        # crate on https://crates.io. Requires configuring the trusted
+        # publisher on the crates.io web UI, adding `id-token: write`
+        # permission to this job, and switching to cargo's OIDC-based
+        # publish flow. Token-based publish is the documented bootstrap
+        # path until that infra exists.
         run: cargo publish
 
       - name: Extract CHANGELOG slice for this version
@@ -166,12 +174,23 @@ jobs:
           } >> "$GITHUB_OUTPUT"
 
       - name: Create GitHub Release
-        uses: softprops/action-gh-release@b4309332981a82ec1c5618f44dd2e27cc8bfbfda # v3.0.0
-        with:
-          name: ${{ steps.changelog.outputs.title }}
-          tag_name: ${{ steps.version.outputs.tag }}
-          body: ${{ steps.changelog.outputs.body }}
-          draft: false
-          prerelease: false
+        shell: bash
         env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          TAG: ${{ steps.version.outputs.tag }}
+          TITLE: ${{ steps.changelog.outputs.title }}
+          BODY: ${{ steps.changelog.outputs.body }}
+        run: |
+          set -euo pipefail
+          # All inputs are derived from this workflow's own steps (version
+          # extraction + CHANGELOG slice), not from external event payload,
+          # so direct env-var consumption by `gh release create` is safe.
+          # If the release already exists for this tag (re-run path), skip
+          # creation rather than failing the job.
+          if gh release view "$TAG" >/dev/null 2>&1; then
+            echo "::notice::release $TAG already exists; skipping gh release create"
+            exit 0
+          fi
+          gh release create "$TAG" \
+            --title "$TITLE" \
+            --notes "$BODY"

CHANGELOG.md

@@ -7,6 +7,90 @@ crate adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 Pre-1.0 minor bumps may still contain breaking changes; see `CLAUDE.md` and
 `.claude/rules/protocol-versioning.md` for the full policy.
 
+## [0.7.0] - 2026-05-21
+
+### Changed (additive producer constraint)
+
+- **`FunctionIdentity::source_hash` format is now pinned**, closing the
+  cross-producer non-comparability gap that issue #3 surfaced. The field
+  was previously documented as "opaque, producer-defined", which let each
+  producer pipeline (`fallow-v8-coverage`, `oxc_coverage_v8`, the Istanbul
+  ingester, browser / node beacons) emit incompatible hash formats
+  (`sha256-hex`, `xxh3-base64`, `blake3-truncated`) and rendered the
+  tiebreaker useless across pipelines.
+
+  Pinned format (added in protocol 0.7.0, MUST hold across producers):
+  the first 8 bytes of `SHA-256(<canonical body bytes>)` rendered as 16
+  lowercase hex characters. Canonical body bytes are the bytes the
+  producing compiler or parser sees for the function, including the
+  signature line and the closing brace, with NO whitespace
+  normalization. Producers that cannot canonicalize the bytes the same
+  way as their siblings MUST omit the field rather than emit a
+  divergent format.
+
+  Migration for producers shipping a non-conforming `source_hash` today:
+  switch the producer to the new `source_hash_for` helper in this crate,
+  or omit the field. No wire shape change for consumers; the field stays
+  `Option<String>`.
+
+### Added
+
+- **`source_hash_for(body: &[u8]) -> String`** helper computing the
+  canonical `FunctionIdentity::source_hash` value. Reuses the existing
+  `sha2` dependency. No new transitive deps. Producers MUST route every
+  `source_hash` value through this helper so cross-producer agreement
+  holds by construction.
+- **Anchor fixture** `source_hash_for_anchor_fixture` pinning
+  `source_hash_for(b"function foo() { return 1; }")` to the literal
+  string `"74846e29a52fe863"`. Producers self-test against this fixture
+  in their own CIs to detect divergence at the source rather than at
+  cross-surface join time.
+- **`function_identity_full_json_shape_anchor_fixture`** and
+  **`function_identity_minimal_json_shape_anchor_fixture`** locking the
+  byte-level JSON output of `FunctionIdentity` for the every-field-set
+  and the minimum-required (all `Option`s `None`) shapes. Catches silent
+  field-reorder regressions and `skip_serializing_if` drift.
+- **`identity_resolution_unresolved_shape_fixture`** documenting the
+  on-wire shape an MCP agent or cloud aggregator sees for a failed-join
+  entry where `resolution = "unresolved"` and columns / `source_hash`
+  are absent.
+- **`blast_radius_id_anchor_fixture`** and
+  **`importance_id_anchor_fixture`** parallel to the existing
+  `function_identity_id_anchor_fixture`. Locks the canonical hash
+  inputs and truncation for the remaining stable-ID helpers so every
+  producer can self-test agreement.
+- **Per-field stability assertions** for `function_identity_id`:
+  separate tests pin invariance under independent mutation of
+  `start_column`, `end_line`, `end_column`, and `source_hash`. The
+  prior `function_identity_id_unchanged_by_columns` test bundled all
+  four metadata fields; the per-field cases catch a future regression
+  where the helper accidentally starts hashing one specific metadata
+  field but not the others.
+- **Tightened rustdoc** on `FunctionIdentity::stable_id_computed`. The
+  method is now explicitly documented as a diagnostic helper, NOT a
+  validation gate. Consumers MUST NOT reject payloads whose `stable_id`
+  differs from the computed value; doing so would turn every such
+  consumer into a hard-fail on the next protocol major that evolves the
+  hash inputs.
+- **`Unknown` sentinel variants** on `RiskBand` and `CoverageSource`,
+  closing the last two forward-compat gaps surfaced by a /sweep audit
+  of every public enum in the crate. Adds `#[serde(other)] Unknown` to
+  both. Future producers MAY add new variants (`Critical` / `Negligible`
+  for `RiskBand`; `IstanbulDir` / `TraceEvent` / `RuntimeBeacon` for
+  `CoverageSource`) as additive minor bumps; consumers that have not
+  seen the new variant yet map it to `Unknown` rather than failing
+  deserialization. Closes the latent gap that future variant additions
+  on either enum would have required a major bump. Closes #5.
+
+### Other
+
+- `PROTOCOL_VERSION` bumped to `"0.7.0"`. `Cargo.toml [package].version`
+  matches per `.claude/rules/protocol-versioning.md`.
+- Internal `hex_prefix` refactored to take a `bytes` count so the 4-byte
+  truncation used by `finding_id` / `hot_path_id` / `blast_radius_id` /
+  `importance_id` / `function_identity_id` and the 8-byte truncation
+  used by `source_hash_for` share one auditable implementation.
+
 ## [0.6.0] - 2026-05-20
 
 ### Added

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "fallow-cov-protocol"
-version = "0.6.0"
+version = "0.7.0"
 edition = "2021"
 rust-version = "1.75"
 license = "MIT OR Apache-2.0"

_typos.toml

@@ -3,3 +3,12 @@ extend-exclude = [
     "Cargo.lock",
     "target/",
 ]
+
+# SHA-256 prefix anchor values used by FunctionIdentity / source_hash_for
+# tests inside src/lib.rs. typos tokenizes hex strings on digit boundaries
+# and would otherwise flag substrings like `ba` (inside e25ba02c5e53651f)
+# as misspellings of `by` / `be`. Each entry is the exact 16-hex output of
+# `source_hash_for` or `function_identity_id` pinned in the test source;
+# changing the test inputs would invalidate the panel-verified anchors.
+[default.extend-identifiers]
+e25ba02c5e53651f = "e25ba02c5e53651f"