jobcompat 0.2.1 → 0.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47c2a0eafb9ae4ced87a7e13389e1ebd043a281d5b711f79bf668179592fea33
-  data.tar.gz: a2447a5027360b6bf7843c6c7766b6b8af1977a1e8308700d298e956b428d87e
+  metadata.gz: fe462bfac086361d10bc4be2bb535045c131d0cbabb9037b437789684665eb29
+  data.tar.gz: ecc7ee3319c763957771f3eff973ae3f7ace1b5deb43fda27de694b9fea8531f
 SHA512:
-  metadata.gz: f6d44307647aed53748ca8b429ecf7469bb79fac73644a9f559a4b7c89c97bb6c52d60da03edd604b787e4959366e775579fa7a140341f1153902eefda90f528
-  data.tar.gz: e338de388c16b907edcd05377460bbb741bc268033821a952e0e1ce65e49cc46bbe45348ca30414e65faddb3d9c7d179e15c5538c92373a07ae76e294c787f31
+  metadata.gz: 137621193e3cbbad8cc1c368718390ee4c65e7c0ed37a5ba2a2ae798b24d4fbd0aa05ba26673e26b968c44bb89cc36b6cfc2146bc11638eb2ead7e97d19c31a1
+  data.tar.gz: e91710462947c4376ccc8fcc3f3f167fc7dfd2e21e1fa9d61d0197d69538f4707aec557fb662c6a5ec2785bb4688744866545bbcd395734afb9dc3a97a15a55b

data/CHANGELOG.md

@@ -1,5 +1,17 @@
 # Changelog
 
+## 0.3.1 - 2026-11-07
+
+- Add optional `--explain` text output showing the evidence, decision, and boundary behind each surviving JC001–JC007 finding, including alias provenance for serialized identities.
+- Compatibility decisions, default text output, and JSON schema 3 content are unchanged; combining `--explain` with `--format json` fails with a config error before analysis.
+
+## 0.3.0 - 2026-10-05
+
+- Recognize static Sidekiq compatibility aliases, including finite chains and supported namespaces, to preserve old serialized identities across worker renames.
+- Normalize Class-object producers through aliases to the terminal Class name while preserving exact Client String identities.
+- Report relevant unresolved, cyclic, conflicting, or unsupported alias bindings conservatively as JC007.
+- Emit JSON schema 3 with effective serialized-identity worker results, alias metadata, and resolved_alias presence; direct worker summary counts and config schema 1 remain unchanged.
+
 ## 0.2.1 - 2026-10-04
 
 Canonical worker-name consistency:

data/README.md

@@ -36,10 +36,13 @@ From a Git repository containing native Sidekiq jobs:
 ```sh
 jobcompat check --base origin/main
 jobcompat check --base v0.1.0 --head HEAD --format json
+jobcompat check --base origin/main --explain
 ```
 
 Both refs resolve to commits. Staged and uncommitted changes are ignored. The command never checks out another revision or changes the working tree.
 
+`--explain` appends an `Explanation` section—evidence, decision, and boundary—to each remaining finding in text output. It shows why a rule fired from the static evidence jobcompat already collected: it runs no additional compatibility checks, cannot be combined with `--format json` (exit 2 config error), reports only static source evidence, and never turns an `unknown` result into a safety claim.
+
 ## Example output
 
 For a base one-argument producer and a HEAD worker that requires two arguments, text output includes:
@@ -54,7 +57,7 @@ ERROR JC001 ExportJob
   Risk: Jobs queued by the base revision may fail after deployment.
 ```
 
-The second direction appears only when HEAD also has a one-argument producer. Output includes source locations, suggested migration steps, resolved commit SHAs, and a summary. JSON output uses `schema_version: 2` and includes per-worker compatibility matrices.
+The second direction appears only when HEAD also has a one-argument producer. Output includes source locations, suggested migration steps, resolved commit SHAs, and a summary. JSON output uses `schema_version: 3` and includes per-serialized-identity compatibility matrices and alias provenance.
 
 ## How it works
 
@@ -140,9 +143,36 @@ jobcompat sees payload arities 1 and 2. A dynamic bulk row is retained as `dynam
 
 Positional `perform` parameters may be required, optional, rest, post-rest, or forwarding. Keyword parameters make the worker contract unknown in v0.2.
 
-## Limitations and v0.2 non-goals
+### Worker rename and static compatibility aliases
+
+jobcompat recognizes plain static constant aliases to directly recognized jobs, including finite chains and supported namespaces:
+
+```ruby
+class MyNewJob
+  include Sidekiq::Job
+  def perform(id); end
+end
+
+MyOldJob = MyNewJob
+```
+
+Old queued `"MyOldJob"` payloads can resolve through the alias to the new worker contract, so this rename does not produce JC004. Arity incompatibilities still produce the normal findings under the persisted name.
+
+`MyOldJob.perform_async(1)` uses the aliased Class object: Sidekiq serializes its canonical name **MyNewJob**, not the source alias token. This also applies to scheduling, bulk, Setter calls, and Client constant payloads. During a rolling deployment, activating that producer can still cause JC005 MyNewJob if old processes cannot resolve the new identity. A compatibility alias alone does not make immediate new-name producer activation safe.
+
+By contrast, an explicit Client String keeps its exact identity:
+
+```ruby
+Sidekiq::Client.push("class" => "MyOldJob", "args" => [1])
+```
+
+jobcompat models that producer as MyOldJob, then follows the alias on the consumer side. This describes identity behavior; Client Strings also have different job-option/default semantics.
+
+Only unconditional plain constant assignments are trusted. Cycles, conflicting or repeated bindings, dynamic assignments, and conditional aliases warn when relevant. Excluded aliases can block an absence proof but are not trusted as compatibility paths. There is no const_set/autoload/const_missing support, conditional alias proof, runtime load-order proof, or heuristic rename detection. Recognition assumes successful application boot, just as direct worker recognition does.
+
+## Limitations and non-goals
 
-v0.2 checks **positional arity only**. It does not check value types, Hash internals, keyword compatibility, or JSON serialization. It supports native Sidekiq, not ActiveJob. Dynamic bulk collections are warning/unknown, Client payload variables are not followed, and custom wrappers are not analyzed. ActiveJob, arbitrary Client instances, Hash internal schemas, aliases, inheritance, concerns, arbitrary metaprogramming, feature flags, and general Ruby class/module or superclass conflict analysis remain outside scope.
+jobcompat checks **positional arity only**. It does not check value types, Hash internals, keyword compatibility, or JSON serialization. It supports native Sidekiq, not ActiveJob. Dynamic bulk collections are warning/unknown, Client payload variables are not followed, and custom wrappers are not analyzed. ActiveJob, arbitrary Client instances, Hash internal schemas, general Ruby aliases beyond the static subset above, inheritance, concerns, arbitrary metaprogramming, feature flags, and general Ruby class/module or superclass conflict analysis remain outside scope.
 
 No repository producer callsite does **not** prove an empty queue: queued, scheduled, retried, historical, and external jobs may exist. JC004 requires a completed static absence proof across tracked `.rb` source. An excluded or unrecognized declaration warns. JC005 is a structural rolling-deploy error conditional on an old Sidekiq process being able to consume the new job's queue. Queue isolation and feature flags are not analyzed. Dynamic source may warn or be missed. Working-tree edits are ignored.
 
@@ -171,7 +201,7 @@ Possible future work includes SARIF output and additional evidence sources. Othe
 
 ## Contributing
 
-Run `bundle exec rake test` and `gem build jobcompat.gemspec` with Ruby 3.3 or newer. Tests create temporary Git repositories and need no Redis or Sidekiq server. The [v0.1 specification](docs/spec-v0.1.md) remains the baseline; [the normative v0.2 delta](docs/spec-v0.2.md) defines the added producer coverage, and [the v0.2.1 delta](docs/spec-v0.2.1.md) defines shared canonical worker-name validation.
+Run `bundle exec rake test` and `gem build jobcompat.gemspec` with Ruby 3.3 or newer. Tests create temporary Git repositories and need no Redis or Sidekiq server. The [v0.1 specification](docs/spec-v0.1.md) remains the baseline; [the normative v0.2 delta](docs/spec-v0.2.md) defines the added producer coverage, [the v0.2.1 delta](docs/spec-v0.2.1.md) defines shared canonical worker-name validation, and [the v0.3 delta](docs/spec-v0.3.md) defines static compatibility aliases and serialized identity resolution.
 
 ## License
 

data/SECURITY.md

@@ -2,4 +2,8 @@
 
 If you find a vulnerability, use this repository's GitHub private vulnerability reporting. Please avoid posting an exploitable report in a public issue.
 
-Supported release: 0.1.x after publication. Security fixes will be released as a new gem version rather than replacing an existing one.
+## Supported releases
+
+The latest published minor release series is supported for security fixes. Older versions may receive fixes at the maintainer's discretion.
+
+Security fixes are published as new gem versions. Existing published gem versions are not replaced.

data/docs/architecture.md

@@ -1,7 +1,13 @@
-# jobcompat v0.2 architecture
+# jobcompat v0.3.0 architecture
 
-Status: implemented design for `0.2.0`
-Date: 2026-09-28
+Status: implemented design for `0.3.0`
+Date: 2026-10-05
+
+This document describes the current v0.3.0 architecture, extending the
+historical v0.1 and v0.2 design. References to those releases record inherited
+design decisions and additions. The current JSON output schema is 3;
+schema 2 describes historical v0.2 behavior. `docs/spec-v0.3.md` defines the
+normative v0.3.0 contract.
 
 ## 1. Architecture principles
 
@@ -214,7 +220,7 @@ The engine MUST be pure with respect to filesystem, Git, environment, clock, and
 Formatters receive a completed or failed result envelope. They MUST NOT recalculate compatibility or suppression. They render already matched suppression audit records without reconstructing omitted findings.
 
 - `Formatter::Text` renders concise human remediation.
-- `Formatter::Json` constructs schema-version-2 primitive Hash/Array data, preserving the v1 shape while extending producer `unknown_reason` values. It includes each finding's `revisions`, `directions`, and `unknown_reason` and each worker's base/head presence status, calls `JSON.pretty_generate`, and appends exactly one newline.
+- `Formatter::Json` constructs schema-version-3 primitive Hash/Array data, retaining the historical v0.2 fields and adding alias metadata and `resolved_alias` presence. It includes each finding's `revisions`, `directions`, and `unknown_reason` and each worker's base/head presence status, calls `JSON.pretty_generate`, and appends exactly one newline.
 
 Both consume already sorted results.
 
@@ -364,12 +370,46 @@ UnresolvedEnqueueCall
 unknown_reason      Symbol | nil
 ```
 
-The reason values map one-to-one to the frozen baseline strings in `docs/spec-v0.1.md` plus the schema-v2 producer additions in `docs/spec-v0.2.md`; visitors do not invent free-form reason text.
+The reason values retain the frozen baseline strings in `docs/spec-v0.1.md` and the historical v0.2/schema-v2 producer additions in `docs/spec-v0.2.md`, with current alias additions defined in `docs/spec-v0.3.md`; visitors do not invent free-form reason text.
 
 Only after both revisions' worker names are known does the engine resolve these facts. This avoids ordering dependence between files and enables head calls to removed base workers.
 
 ## 7. Internal models
 
+### v0.3.0 serialized identity resolution
+
+The existing Analyzer Prism pass extracts direct worker facts together with
+selected-source ConstantBinding and AliasCandidate facts. AliasResolver
+builds a deterministic per-revision graph using the same constant-path
+and lexical namespace rules, with iterative cycle detection and strict
+binding uniqueness. DefinedConstantIndex remains separate presence proof;
+its excluded-file facts never become trusted alias edges.
+Selected ambiguous paths retain separate leaf-name binding blockers; the
+resolver checks them at alias edges and direct terminals without evaluating
+dynamic receivers. Unrecognized terminal declarations remain diagnostic
+proof locations.
+
+RevisionSnapshot retains direct `workers` for summary counts and adds
+`aliases`, effective consumer contracts by serialized identity, and presence
+helpers. A resolved alias carries terminal contract and every edge's proof
+locations; an unknown binding masks a conflicting direct consumer.
+The snapshot also retains selected binding facts so alias-related producer
+lookup stops at nearer non-worker class/module declarations.
+
+Engine normalizes Class-object calls through their own revision's alias
+graph to terminal identities, preserving known identity even with unknown
+arity. Exact Client Strings retain their identity. Diagnostic attribution
+is separate from known serialized producer identity, so an unknown alias
+cannot drive JC005.
+Class-object alias calls carry terminal declaration/include/perform proof.
+Opposite revision names cannot override local bindings during alias lookup;
+the existing non-alias cross-revision attribution is preserved.
+The bounded comparison set includes historical BASE aliases and relevant
+producer/binding identities; dormant HEAD aliases do
+not automatically add warnings. Existing rules consume effective contracts.
+Schema 3 exposes base_alias/head_alias and resolved_alias presence while
+summary.workers still counts direct worker facts.
+
 Models SHOULD be immutable `Data.define` values on Ruby 3.3. Constructors validate invariants at the boundary; rule methods do not repeatedly revalidate them.
 
 ### 7.1 `SourceLocation`

data/docs/implementation-plan-v0.3.1.md

@@ -0,0 +1,54 @@
+# jobcompat v0.3.1 implementation plan
+
+Baseline: `02751a57e21da3f548f6d6442b17a438026ef9e1` (v0.3.0). All changes
+stay uncommitted for independent review.
+
+## Change order
+
+1. `lib/jobcompat/explanation.rb` (new): `Explanation = Data.define(:evidence, :decision, :boundary)` plus a private builder module used by the Engine. Evidence entries, decision, and boundary are plain frozen strings; rendering responsibility stays with the Formatter.
+2. `lib/jobcompat/engine.rb`: `evaluate(with_explanations: false)`. At each
+   finding site (JC001, JC002, JC003, JC004, JC005, JC006, presence-unknown
+   JC007, and the aggregated JC007 roots) build an `Explanation` from the
+   producer group, contracts, presence result, alias resolution, and unknown
+   root already in scope, and store it in a
+   `{}.compare_by_identity` sidecar keyed by the finding hash object. The
+   sidecar is returned as `explanations:` only when requested. Finding and
+   worker rows are not modified.
+3. `lib/jobcompat/formatter.rb`: `text(envelope, explanations: nil)`. When a
+   non-nil sidecar maps the finding, render the fixed `Explanation:` /
+   `Evidence:` / `Decision:` / `Boundary:` block between the location lines
+   and `Suggested migration:`. `explanations: nil` keeps output
+   byte-identical. `json` untouched.
+4. `lib/jobcompat/cli.rb`: parse `--explain` (default false); reject
+   `--explain` with non-text format as `config_error` before repository
+   access; pass `with_explanations:` to `evaluate` and `explanations:` to
+   `Formatter.text` for the completed text path only.
+5. `lib/jobcompat/version.rb` -> 0.3.1; `Gemfile.lock` path spec version.
+6. `docs/spec-v0.3.1.md` (normative delta), this plan, README quick-start and
+   explanation notes, `CHANGELOG.md` `## 0.3.1 - Unreleased`.
+
+## Test order
+
+1. Unit `test/unit/explanation_test.rb`: Explanation VO shape; formatter
+   parity (nil sidecar byte-identical, unknown finding -> no section);
+   sanitization of hostile strings.
+2. Integration `test/integration/explain_command_test.rb`: CLI contract
+   (accept/combos/order/json rejection/failed envelope schema 3/help);
+   per-rule content for JC001 (both direction variants, alias-carried
+   identity), JC002, JC003 (no base leakage), JC004 (absence only;
+   outside-scope fixture must not claim absence), JC005 (conditional
+   rolling-deploy wording, Class-object terminal identity, exact Client
+   String identity), JC006 (no empty-queue claim), JC007 (alias cycle,
+   unresolved, splat producer, keyword contract); suppression behavior;
+   zero-finding behavior; determinism double-run; default-output regression
+   against committed expectations derived from the frozen 0.3.0 baselines.
+3. Full suite `rake test`; baseline runner `compare` (byte-identical after
+   version normalization only).
+4. `gem build`, package content inspection, isolated install, CLI smoke.
+
+## Regression evidence
+
+Frozen 0.3.0 outputs for JC001–JC007 (including alias-carried, client-string,
+and outside-scope variants), resolved alias rename, targeted suppression, and
+a no-findings comparison were captured before implementation and are
+re-compared after; only the version string may differ.

data/docs/implementation-plan-v0.3.md

@@ -0,0 +1,32 @@
+# v0.3.0 implementation plan
+
+Implement the normative delta in spec-v0.3.md in this order.
+
+1. Extend Analyzer's existing Prism pass with immutable AliasCandidate and
+   ConstantBinding facts. Propagate a narrow direct-statement context for
+   alias proof, while retaining baseline worker/producer discovery. Keep
+   DefinedConstantIndex responsible only for conservative presence.
+2. Build AliasResolver from selected binding inventory and direct workers.
+   Reuse one constant candidate helper. Iterate each chain with cycle
+   detection; reject duplicate/conflicting bindings and unsupported edges.
+   Retain deterministic chain, locations, and revision-free fingerprints.
+3. Extend RevisionSnapshot with aliases and effective consumer/presence
+   helpers. Preserve workers as direct facts and summary counts. Derive
+   alias contracts from terminal contracts with complete proof locations.
+4. Resolve producers using snapshot-local alias semantics. Keep identity
+   certainty separate from arity certainty and diagnostic attribution.
+   Preserve exact Client Strings and baseline non-alias attribution.
+5. Feed relevant serialized identities and effective consumers into Engine.
+   Keep JC001-JC007 logic and precedence; add alias warnings/metadata and
+   update identity wording. Emit schema 3 on completed and failed CLI output.
+6. Add focused AST/graph/producer unit tests and temporary Git rule,
+   deployment, JSON, determinism, Unicode, suppression, and security tests.
+   Update only intentional version/schema expectations in existing tests.
+7. Update README, architecture, changelog, version and lockfile. Run all
+   tests in available Ruby with UTF-8 locale, build and inspect the gem,
+   install into a temporary isolated destination, run CLI exit scenarios,
+   inspect the full diff, and remove only the generated package.
+
+Mandala tracks specification, aliases, producers, compatibility, validation.
+Only evidence-backed completed facets are marked done. No release operation
+is part of this plan.

data/docs/release-checklist-v0.3.0.md

@@ -0,0 +1,109 @@
+# jobcompat v0.3.0 release checklist
+
+This document prepares jobcompat v0.3.0 for release. Checked boxes record completed preparation evidence. Unchecked boxes are final tag, publication, GitHub Release, or post-publication gates. This preparation does not authorize creating or pushing `v0.3.0`.
+
+**Pushing `v0.3.0` triggers the Release workflow and may publish the gem to RubyGems. Treat tag push as a publication action.**
+
+## Release identity
+
+- Repository: `cottondesu/jobcompat`, branch `main`.
+- Gem and CLI version: `0.3.0`; intended annotated tag: `v0.3.0`.
+- Intended release date: `2026-10-05`. If execution is delayed and publication is no longer intended for this date, update the release date consistently before committing or tagging; never backdate publication.
+- JSON schema: `3`; `.jobcompat.yml` configuration schema: `1`.
+- Ruby: `>= 3.3`; Prism: `>= 1.9, < 2`; no new runtime dependencies.
+- Implementation commit: `642e2c4c838db78d4e7ae6dd9ff3b958b6336483` (`Add worker rename alias compatibility`), parent `6f6c2deecad10111d70455dd343e1f89a3af088c`.
+- Implementation CI: run `37302967087`.
+- Release candidate SHA: determined by this preparation commit; record the exact SHA and its exact CI run in the final preparation report. The release-preparation commit, not the implementation commit, must become the eventual tag target if its exact CI passes.
+
+## Reviewed implementation
+
+- [x] Fresh independent review: SHIP; 0 BLOCKER and 0 MAJOR.
+- [x] Final checked-in suite baseline: 189 tests, 1,942 assertions, 0 failures, 0 errors, 0 skips.
+- [x] Reviewer documentation MINOR resolved before the implementation commit.
+- [x] Analysis does not execute source, boot Rails or Sidekiq, or connect to Redis.
+
+## Implementation CI evidence
+
+Implementation commit `642e2c4c838db78d4e7ae6dd9ff3b958b6336483` passed GitHub Actions run `37302967087`:
+
+- [x] Ruby 3.3 tests and gem build succeeded.
+- [x] Ruby 3.4 tests and gem build succeeded.
+- [x] Ruby 4.0 tests and gem build succeeded.
+
+This implementation CI does not replace the required official CI on the release-preparation commit.
+
+## Release-only local validation
+
+- [x] `LANG=C.UTF-8 bundle exec rake test` under Ruby 3.4.8 / Prism 1.9.0: 189 tests, 1,942 assertions, 0 failures, 0 errors, 0 skips.
+- [x] `git diff --check` passes.
+- [x] `gem build jobcompat.gemspec` succeeds; package inspected and generated `.gem` removed after inspection.
+- [x] Both v0.3.0 release documents are packaged under the existing `docs/*.md` gemspec policy; package contains no generated or local tooling files.
+- [x] Installed the candidate gem into a fresh isolated destination; `jobcompat --version` prints `jobcompat 0.3.0`.
+- [x] The full suite and alias integration scenarios verify safe alias 0, JC001 1, JC005 1, warning-only alias uncertainty 0, invalid config 2, and invalid ref 2.
+- [x] Alias integration scenarios verify safe alias resolution, Class-object producer identity, exact Client String identity, and schema 3 fields; product tests were not changed.
+
+## Publication prerequisites
+
+- [ ] Manually confirm GitHub environment `release` exists, its required reviewer/protection is intact, and its tag deployment rule remains acceptable. Do not weaken the environment.
+- [ ] Manually confirm the RubyGems Trusted Publisher for `jobcompat` matches owner `cottondesu`, repository `jobcompat`, workflow `release.yml`, and environment `release`. Do not introduce a long-lived RubyGems API key.
+
+## Public-state precheck (2026-10-05)
+
+- [x] RubyGems lists `0.2.1`, `0.2.0`, and `0.1.0`; `0.3.0` is absent.
+- [x] The local `v0.3.0` tag is absent; remote tags include `v0.2.1` and no `v0.3.0`.
+- [x] GitHub Releases include `v0.2.1`, `v0.2.0`, and `v0.1.0`; `v0.3.0` is absent.
+- [x] Historical `v0.2.1` annotated tag object is `b9ca1f7a3d0818ee23beff48907cb3d6a2e0eb1c`, peeled commit is `6f6c2deecad10111d70455dd343e1f89a3af088c`, and the GitHub Release and RubyGems version are present.
+- [ ] Immediately before final release execution, repeat all v0.3.0 absence checks. Stop if any already exists; never overwrite it.
+
+## Release workflow audit
+
+The inspected `.github/workflows/release.yml` is unchanged. It triggers on tag pushes matching `v*`; the Ruby 3.3 / 3.4 / 4.0 test matrix gates `publish` through `needs: test`. Publication runs on Ruby 4.0 in environment `release`, grants GitHub OIDC `id-token: write`, checks tag/version and public metadata, configures RubyGems credentials with `rubygems/configure-rubygems-credentials`, then runs `gem push`.
+
+- [x] Workflow trigger, test matrix, publish dependency, Ruby version, environment, OIDC permission, tag/version gate, metadata gate, and publication command audited.
+- [ ] Confirm the GitHub release environment and RubyGems Trusted Publisher manually before the final tag action.
+
+## Release-note examples and content
+
+- [x] Release notes were compared with `docs/spec-v0.3.md`, `README.md`, implementation, and tests for alias resolution, Class-object normalization, exact Client Strings, JC004/JC005, JC007 reasons, schema 3 fields, and config schema 1.
+- [x] The alias integration scenarios and full local suite passed against the unchanged candidate implementation.
+
+## Tag gate
+
+**Pushing `v0.3.0` triggers the Release workflow and may publish `jobcompat 0.3.0` automatically. Treat tag push as a publication action.** Before any separately approved final release execution:
+
+- [ ] Release-preparation commit is fixed and its exact SHA identified.
+- [ ] Exact release-preparation SHA has green official CI, including Ruby 3.3, Ruby 3.4, and Ruby 4.0.
+- [ ] GitHub `release` environment gate has been manually verified.
+- [ ] RubyGems Trusted Publisher settings have been manually verified.
+- [ ] RubyGems `0.3.0`, local and remote `v0.3.0` tags, and GitHub Release `v0.3.0` are still absent.
+- [ ] Separate final release execution approval has been obtained.
+
+## Future tag requirements
+
+Documented for the separately approved release-execution phase; do not perform during preparation:
+
+- Create an annotated `v0.3.0` tag pointing exactly to the verified release-preparation commit, not `642e2c4c838db78d4e7ae6dd9ff3b958b6336483`.
+- Never create a lightweight tag, force a tag, or move an existing tag.
+
+## Release workflow verification
+
+- [ ] Release workflow triggered by `v0.3.0`.
+- [ ] Workflow tag resolves to the approved release-candidate SHA.
+- [ ] Ruby 3.3, Ruby 3.4, and Ruby 4.0 test jobs succeed.
+- [ ] Publish job starts only after tests; environment approval succeeds.
+- [ ] Tag/version and metadata gates succeed.
+- [ ] Publish-job tests and gem build succeed.
+- [ ] OIDC credentials setup and gem push succeed.
+- [ ] RubyGems publicly lists version `0.3.0`; do not infer publication solely from workflow status.
+
+## Post-publication
+
+- [ ] Verify RubyGems version `0.3.0`, Ruby `>= 3.3`, Prism `>= 1.9, < 2`, metadata URLs, and package contents.
+- [ ] Install from public RubyGems in a fresh environment and verify `jobcompat --version`.
+- [ ] Run representative CLI checks against the installed public gem.
+- [ ] Create or verify GitHub Release `v0.3.0` using the reviewed release notes and confirm it points to the correct tag.
+- [ ] Record the release workflow URL.
+
+## Rollback
+
+Do not overwrite or reuse `0.3.0`, move `v0.3.0`, or rewrite existing release history after publication. Fix forward with a later version. If a published gem must be removed, follow the official [RubyGems yank procedure](https://guides.rubygems.org/removing-a-published-gem/); yanking does not remove copies already installed.

data/docs/release-notes-v0.3.0.md

@@ -0,0 +1,115 @@
+# jobcompat v0.3.0 release notes
+
+jobcompat v0.3.0 adds static worker-rename compatibility analysis for native Sidekiq. Supported aliases can keep old serialized worker names resolvable during rolling deployments. The release also models the difference between Sidekiq producers that pass a Class object and Client producers that pass an exact String identity.
+
+## Highlights
+
+- Recognize supported static compatibility aliases such as `OldJob = NewJob`.
+- Resolve finite alias chains and supported namespaces conservatively.
+- Avoid a false JC004 when a retained old serialized identity still resolves through a safe alias.
+- Normalize Class-object producer identities through aliases to their terminal Class names.
+- Preserve exact `Sidekiq::Client` String identities.
+- Report relevant alias uncertainty as JC007 instead of assuming compatibility.
+- Upgrade JSON output to schema version 3 and include alias provenance.
+
+## Safe worker rename compatibility aliases
+
+For a rename, keep a static alias while old payloads may still be retained:
+
+```ruby
+class NewExportJob
+  include Sidekiq::Job
+
+  def perform(id)
+  end
+end
+
+OldExportJob = NewExportJob
+```
+
+Queued, retried, or scheduled payloads already serialized as `"OldExportJob"` can resolve through this alias to the `NewExportJob` contract. A safe alias can therefore prevent JC004 for `OldExportJob` while those payloads may still run.
+
+An alias does not hide a real argument incompatibility. If the terminal worker no longer accepts an old payload's positional arity, jobcompat can still report JC001 or JC006 under the existing rules.
+
+Supported aliases are unconditional plain constant assignments, including supported namespace forms. Finite chains are resolved; for example, `LegacyExportJob = PreviousExportJob` and `PreviousExportJob = ExportJob` make `ExportJob` the effective consumer. This is a documented static subset, not general Ruby constant or alias resolution.
+
+## Serialized identity: Class objects vs exact Strings
+
+Ruby aliases refer to the same Class object. Given:
+
+```ruby
+OldExportJob = NewExportJob
+OldExportJob.perform_async(1)
+```
+
+the source token is `OldExportJob`, but the value passed to Sidekiq is the `NewExportJob` Class object. Sidekiq serializes that object's canonical name, so jobcompat models the persisted identity as `NewExportJob`. During a rolling deployment, activating this producer can still produce JC005 for `NewExportJob` if the old fleet does not recognize that name.
+
+**Keeping `OldExportJob = NewExportJob` protects retained old `"OldExportJob"` payloads, but calling `OldExportJob.perform_async(...)` is not a mechanism for continuing to enqueue the old serialized class name.**
+
+An explicit Client String has different identity behavior:
+
+```ruby
+Sidekiq::Client.push(
+  "class" => "OldExportJob",
+  "args" => [1]
+)
+```
+
+Here the serialized identity remains exactly `OldExportJob`; jobcompat models that String as-is and can resolve it through the consumer-side alias. Client String pushes are described to explain identity modeling, not as the default rename strategy; their job-option and default semantics differ.
+
+## Conservative alias uncertainty
+
+jobcompat does not assume compatibility when Ruby behavior is ambiguous. Relevant uncertainty is reported as JC007 with one of these reasons:
+
+- `alias_target_unresolved`: the target cannot be proven to end at a recognized worker.
+- `alias_cycle`: aliases refer back to each other.
+- `alias_binding_conflict`: the same constant has conflicting definitions or writes.
+- `unsupported_alias_assignment`: the assignment is conditional, dynamic, operator-based, or otherwise outside the supported syntax.
+
+Unknown does not mean compatible. jobcompat does not execute application source to resolve these cases. It supports plain static assignments such as `OldJob = NewJob`, supported qualified paths, and supported namespace bodies. It does not resolve `const_set`, `autoload`, `const_missing`, conditional aliases, dynamic right-hand-side evaluation, runtime load order, general Ruby constant evaluation, or heuristic renames.
+
+## JSON schema 3
+
+**v0.3.0 changes JSON `schema_version` from 2 to 3.** `workers[]` now represents compared serialized worker identities and exposes alias provenance. Each worker result includes `base_alias` and `head_alias`; the presence value `resolved_alias` identifies a successfully resolved alias. `summary.workers.base` and `.head` continue to count directly recognized Sidekiq workers, not aliases.
+
+The `.jobcompat.yml` configuration schema remains `version: 1`. Do not change the configuration version to 3.
+
+## Compatibility contracts
+
+No new JC rule was added. JC001–JC007 IDs, severities, JC001/JC003 precedence, the three rolling-deployment directions, exit codes, and suppression identity remain unchanged. The configuration schema remains version 1, Ruby `>= 3.3` remains required, and Prism `>= 1.9, < 2` remains the supported range.
+
+## Upgrade notes
+
+**Consumers that parse jobcompat JSON must update to accept `schema_version: 3` before upgrading to v0.3.0.** Do not assume that a schema 2 consumer can read schema 3 unless that consumer explicitly supports new schema versions and fields.
+
+No `.jobcompat.yml` version change is needed. Keep a compatibility alias for as long as old serialized identities can remain in queues, retries, schedules, or other retained payloads. Plan producer activation separately: calling an aliased Class object's Sidekiq API serializes the terminal Class name.
+
+## Known limitations
+
+Analysis covers positional arity for native Sidekiq workers only. ActiveJob and keyword compatibility are unsupported. jobcompat does not inspect Hash internal schemas, payload value types, live Redis contents, general dataflow, arbitrary Client instances, wrapper inference, runtime load order, or general aliasing and metaprogramming. It does not execute application code.
+
+No repository producer callsite does not prove an empty queue. Queued, scheduled, retried, historical, and external jobs may still exist; static analysis does not establish runtime queue contents.
+
+## Installation
+
+```bash
+gem install jobcompat --version 0.3.0
+```
+
+Bundler users can add:
+
+```ruby
+gem "jobcompat", "~> 0.3.0", require: false
+```
+
+Then fetch the comparison ref and run:
+
+```bash
+jobcompat check --base origin/main
+```
+
+or:
+
+```bash
+bundle exec jobcompat check --base origin/main
+```