jobcompat 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 47c2a0eafb9ae4ced87a7e13389e1ebd043a281d5b711f79bf668179592fea33
-  data.tar.gz: a2447a5027360b6bf7843c6c7766b6b8af1977a1e8308700d298e956b428d87e
+  metadata.gz: 6b1df789562ba30ff3474a112bd44e602d68b833b7d34c92b936f8e508e20484
+  data.tar.gz: ba09c1c7f2ce1f22d44cf690559e395584be8492c5abbbad85d492281b6849cd
 SHA512:
-  metadata.gz: f6d44307647aed53748ca8b429ecf7469bb79fac73644a9f559a4b7c89c97bb6c52d60da03edd604b787e4959366e775579fa7a140341f1153902eefda90f528
-  data.tar.gz: e338de388c16b907edcd05377460bbb741bc268033821a952e0e1ce65e49cc46bbe45348ca30414e65faddb3d9c7d179e15c5538c92373a07ae76e294c787f31
+  metadata.gz: c4e50e2e13f1bc1d3a3e667b63a3865bd01260f8b9bd462db724c0aa44641fd555f191a3059548df2ca408e13a081d3daeb993e4a805a7b9617d79034a36643b
+  data.tar.gz: aff92fbf9b66f5320958497d79a07fbf0defe4b56f1da444fddf69340478f72677e2cad601c5e9951d4de5e76a27f71095ba741e2c0d437be42a8eec75f9413a

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 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

@@ -54,7 +54,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 +140,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
 
-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 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
+
+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 +198,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/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.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
+```

data/docs/spec-v0.3.md

@@ -0,0 +1,238 @@
+# jobcompat v0.3.0 delta specification
+
+Status: normative for 0.3.0. This document extends `spec-v0.2.1.md`,
+which retains the v0.2 and v0.1 contracts except where overridden here.
+MUST and MUST NOT state requirements. No application Ruby is executed.
+
+## Versioned and frozen contracts
+
+Gem and CLI version: 0.3.0. Completed and failed JSON envelopes MUST use
+`schema_version: 3`. Configuration version remains exactly 1; version 2 is
+invalid. Ruby >= 3.3 and Prism >= 1.9, < 2 remain unchanged. No dependency
+on Sidekiq is introduced. JC001-JC007 IDs, severities (JC001-JC005 ERROR,
+JC006-JC007 WARNING), exit policy, suppression identity, and deployment
+directions remain unchanged. ERROR requires provable structural
+incompatibility. Unknown and unsupported evidence never establishes
+compatibility; missing producers never establishes an empty queue.
+Analysis reads committed Git objects and ignores working-tree edits.
+
+## Terminology and serialization
+
+**Serialized worker identity** is the exact String in a Sidekiq payload's
+`"class"` field. All compatibility comparisons use that identity.
+**Direct worker** is a canonical class recognized through the existing
+direct `Sidekiq::Job` or legacy `Sidekiq::Worker` include and reopened-class
+discovery. **Compatibility alias** is a statically provable constant
+binding to another constant whose graph terminates in one recognized
+direct worker in the same revision. **Alias terminal** is that final
+direct worker after zero or more supported edges.
+**Class-object producer** passes a Ruby Class object (worker APIs,
+Setter APIs, or Client constant payloads). **Exact-string producer** passes
+an already serialized identity through Client push or push_bulk.
+
+For `OldJob = NewJob`, Ruby retains the Class object's canonical name
+`NewJob`. Class-object producers through OldJob MUST therefore normalize
+to NewJob. This applies to perform_async, perform_in, perform_at,
+perform_bulk, all four `.set(...)` forms, and Client push/push_bulk with a
+constant. A Client `"class" => "OldJob"` MUST retain exactly OldJob on the
+producer side; consumer lookup MAY resolve OldJob through its alias.
+There is no namespace prefixing or Unicode normalization of exact Strings.
+
+The model freezes Sidekiq's Class-to-String normalization as observed in
+[Sidekiq 8.1.6 JobUtil](https://github.com/sidekiq/sidekiq/blob/v8.1.6/lib/sidekiq/job_util.rb#L38-L55)
+and its [Class-object producer path](https://github.com/sidekiq/sidekiq/blob/v8.1.6/lib/sidekiq/job.rb#L191-L196).
+The [official rename FAQ](https://github.com/sidekiq/sidekiq/wiki/FAQ#how-do-i-safely-rename-a-worker)
+describes a compatibility alias for retained old payloads. Client Strings
+have different job-option/default semantics; their identity behavior is
+documented here without recommending them as a migration strategy.
+
+## Supported syntax and namespace semantics
+
+Only Prism ConstantWriteNode and ConstantPathWriteNode with plain `=`
+and a ConstantReadNode or static ConstantPathNode RHS after safe
+single-expression parentheses unwrapping prove an alias. The assignment
+MUST be a direct unconditional statement in the Program body or a valid
+Class/Module body, with all enclosing contexts supported.
+
+Supported examples are `OldJob = NewJob`, `OldJob = (NewJob)`,
+`::OldJob = ::NewJob`, top-level `Admin::OldJob = Admin::NewJob`, and
+`module Admin; OldJob = NewJob; end`. Existing declaration rules determine
+the LHS canonical name. An unrooted qualified LHS in lexical nesting or
+an unsupported namespace MUST NOT prove an alias. An unrooted qualified
+RHS inside lexical nesting is unsupported_alias_assignment. Rooted RHS
+references and qualified top-level RHS references are exact.
+
+Unqualified RHS lookup uses the existing lexical namespace stack in
+reverse order, then the root name. For nested Admin/Jobs, NewJob candidates
+are Admin::Jobs::NewJob, Admin::NewJob, NewJob. The first selected-source
+binding wins lookup; a binding with an unknown value MUST block fallback
+to a farther known worker. No inherited-constant lookup is added.
+
+Assignments below if/unless/case/loops/blocks/lambdas/begin/rescue/ensure,
+modifier conditions, singleton classes, methods, or expression wrappers
+are unsupported. Even an unconditional begin wrapper is unsupported.
+Or/and/operator writes, multiple assignment targets, dynamic RHS,
+ternary RHS, calls, and Class.new MUST NOT become resolved aliases.
+Named unsupported writes enter the inventory so relevant identities can
+warn and conflicts cannot be hidden. const_set/autoload/const_missing
+remain outside alias discovery.
+
+## Selected binding inventory and graph
+
+During the existing Prism traversal, record selected-source class/module
+declarations and named writes, plus alias candidates. Presence facts in
+DefinedConstantIndex MUST remain separate from alias graph facts.
+Exactly one supported alias binding and no other binding to its LHS is
+required. Duplicate aliases, even identical ones, alias plus class/module,
+or alias plus unsupported writes produce alias_binding_conflict. No
+source-order winner is selected. Existing reopened direct class fragments
+are allowed and merged as before; they are not conflicts by themselves.
+An alias that reaches a conflicting binding MUST remain unknown.
+Selected ambiguous constant paths also retain leaf-name conflict evidence:
+an assignment or declaration such as `self::OldJob = OtherJob` cannot be
+ignored when its leaf may affect an alias or a reached terminal. These
+facts conservatively block resolution without evaluating the receiver.
+Excluded or differently named ambiguous facts do not enter this proof.
+
+Each revision resolves its own graph independently. Finite chains have
+no arbitrary length cap. Iterative traversal detects cycles without
+recursive stack overflow. Resolved chain order follows edges, for example
+`[OldJob, MiddleJob, NewJob]`. A cycle chain closes with its repeated
+identity, for example `[OldJob, MiddleJob, OldJob]`. A missing or
+unrecognized terminal is alias_target_unresolved. Failed suffixes
+propagate their reason and proof to aliases depending on them.
+
+Only selected files supply trusted edges. Excluded declarations/writes
+may block absence through the presence pass, but MUST NOT resolve aliases.
+An excluded OldJob alias yields outside_analysis_scope for a removal
+transition; a selected alias targeting an excluded worker yields
+alias_target_unresolved. File movement alone does not alter identity
+compatibility. All keys preserve Prism's exact UTF-8 codepoints.
+
+## Effective consumers and relevant identities
+
+Snapshot workers remain directly recognized workers. An effective
+consumer map resolves serialized identity S to either direct worker S or
+the terminal contract of supported alias S. A conflicting alias masks an
+otherwise recognized direct consumer at the same identity. Resolved
+aliases retain resolution status even when the terminal signature is
+unknown (keyword_parameters, missing_perform, multiple_perform_definitions).
+Effective alias contracts carry every edge location and the terminal's
+declaration/include/perform proof. No new location role is introduced.
+
+Comparison identities MUST include all direct workers in either revision,
+all resolved BASE aliases (historical queues may retain their names),
+aliases present in both revisions, aliases matching an opposite direct
+worker, and aliases referenced by visible producers or needed to explain
+unknown producer identity. A dormant HEAD-only alias is not automatically
+a worker result or standalone warning. The full graph may still be built.
+The common-alias criterion refers to constant-to-constant candidates,
+including unsupported static forms; unrelated dynamic/literal writes such
+as VERSION = "1" do not become relevant merely by existing in both
+revisions. They still block conflicting bindings and are diagnosed when
+referenced by a producer or matched to an opposite worker identity.
+
+## Producer resolution
+
+Class-object resolution first performs existing lexical/root lookup in
+the producer's own snapshot, including alias bindings. A resolved alias
+normalizes to its terminal direct identity. An unknown alias MUST NOT
+guess its syntactic name as a serialized identity. Such a call retains a
+separate attributed alias name for diagnostics and comparison relevance,
+but cannot drive JC005. Existing cross-revision non-alias attribution
+remains available only when no local alias/binding narrows that proof.
+When alias lookup applies, a nearer selected non-worker class/module
+binding stops fallback and leaves producer identity unknown. Opposite
+revision names cannot override a selected local binding. Normalized
+Class-object alias producers retain edge and terminal declaration,
+include, and perform locations; unresolved targets retain any selected
+declaration that prevents recognition.
+
+Exact-string resolution remains exact and does not canonicalize aliases.
+Producer identity certainty and arity certainty MUST be distinct:
+resolved alias plus `*args` retains the terminal identity and splat_arguments;
+unknown alias plus literal args retains unknown identity. Known identity
+with unknown arity can still drive JC005. Existing Hash source-order,
+dynamic-key, bulk-row, lexical producer, and Client String rules persist.
+
+## Rules, unknown reasons, and proof
+
+JC001: old serialized payload accepted by BASE but rejected by HEAD,
+including alias consumers. JC002: HEAD accepted payload rejected by BASE,
+under its serialized identity. JC003: HEAD producer/consumer mismatch.
+JC001 owns a repeated HEAD mismatch at the same identity/arity before
+JC003. JC001 OldJob and JC003 NewJob from a Class alias producer remain
+distinct findings. JC006 narrowing/witness precedence remains unchanged.
+
+JC004 requires absence of a BASE effective serialized identity in HEAD.
+A resolved alias blocks removal; a relevant unknown alias warns rather
+than passing or proving absence. Removing a BASE resolved alias can cause
+JC004 even if its terminal still exists. JC005 requires HEAD known
+serialized producer identity with an effective HEAD consumer and proven
+BASE absence, conditional on old processes consuming that queue. An
+exact-string alias producer can cause JC005 for the alias; a Class-object
+alias producer can cause JC005 only for the terminal. BASE resolved aliases
+block absence; unresolved aliases warn. Existing presence budget/error
+behavior and conservative absence proof remain frozen.
+
+JC007 adds exactly four reasons: alias_target_unresolved (supported edge
+does not reach a recognized worker), alias_cycle, alias_binding_conflict,
+and unsupported_alias_assignment. Existing contract/arity reasons retain
+their meanings. Alias warning messages describe the unresolved binding
+and risk to the persisted identity; remediation suggests an explicit
+static alias only if it matches runtime behavior, or manual inspection.
+
+BASE alias uncertainty affects head_to_base. HEAD alias uncertainty affects
+base_to_head and additionally head_to_head only with a HEAD producer for
+that same serialized identity. A Class call normalizing to another name
+does not manufacture head_to_head for its source alias. Alias evidence
+fingerprints contain reason, exact identity, lexical scope, normalized
+assignment/enclosing tokens, target reference, and structural chain, but
+exclude revision, paths, lines, and columns. Stable binding/occurrence
+ordering preserves distinct evidence and cross-revision aggregation.
+
+## JSON schema 3 and determinism
+
+workers[] now represents compared serialized identities, sorted by exact
+name. Every result has base_alias and head_alias, null for a direct or
+absent binding, otherwise an object with exactly status, target, chain,
+unknown_reason. Resolved status has terminal target and null reason;
+unknown status has null target and its alias reason. Conflict or unsupported
+assignment chains start with the alias alone; unresolved target chains
+include the missing target, and cycle chains close the cycle.
+
+Presence values are recognized_worker, resolved_alias,
+defined_unrecognized, outside_scan_scope, absent, unverified, not_checked.
+Unknown aliases use defined_unrecognized even in a direct binding conflict.
+Effective contracts appear in base_contract/head_contract for resolved
+aliases; unresolved aliases have null contracts. Producer arities and
+matrix statuses use known serialized identity and effective consumers.
+summary.workers continues to count direct worker facts only, never aliases.
+Suppressions match the finding's exact serialized worker identity.
+
+Inputs and graph processing use stable sorting. Chains follow structural
+edge order. Repeated text/JSON for identical refs/config/toolchain MUST be
+byte-identical, including cycles, conflicts, and Unicode names.
+
+## Boundaries and acceptance
+
+Recognition assumes normal successful application boot, as direct worker
+recognition already does; it does not prove file load order or Zeitwerk
+behavior. No general constant evaluator/dataflow, inheritance/concerns,
+source execution, Rails/Sidekiq boot, Redis/network access, keyword
+compatibility, value/Hash schema analysis, ActiveJob, Client instances,
+wrappers, queue/feature-flag simulation, manual alias config, heuristic
+rename detection, JC008, SARIF, --explain, or coverage report is added.
+
+Acceptance requires supported AST/context and namespace tests, finite and
+cross-file graph tests, cycles/conflicts/unknown terminals, reopened and
+unknown-contract targets, all Class-object and exact-string producer
+families, separate identity/arity uncertainty, every JC rule and precedence,
+staged rename and alias removal, excluded-source presence proof, exact
+Unicode/suppression behavior, schema 3 (success and failure), unchanged
+config version 1, deterministic output, existing regressions, source
+non-execution/worktree/index immutability, offline tests, gem packaging,
+isolated CLI install/scenarios, and full validation in UTF-8 locale.
+Locally unavailable Ruby 3.3/4.0 matrix entries remain official CI work.
+The implementation phase MUST leave an uncommitted candidate and MUST NOT
+commit, push, tag, release, publish, or alter historical v0.2.1 artifacts.

data/lib/jobcompat/aliases.rb

@@ -0,0 +1,86 @@
+module Jobcompat
+  ConstantBinding = Data.define(:name, :kind, :location, :fingerprint_parts)
+  AliasCandidate = Data.define(:name, :reference, :root, :namespace, :supported, :location, :fingerprint_parts)
+  AliasResolution = Data.define(:name, :status, :target, :chain, :unknown_reason, :locations, :fingerprint_parts, :static_reference) do
+    def resolved? = status == "resolved"
+    def as_json
+      {status: status, target: target, chain: chain, unknown_reason: unknown_reason}
+    end
+  end
+
+  module ConstantLookup
+    def self.candidates(reference, root, namespace)
+      return [reference] if root
+      return [] if namespace.nil?
+      (namespace.reverse.map { |prefix| "#{prefix}::#{reference}" } + [reference]).uniq
+    end
+  end
+
+  class AliasResolver
+    def initialize(workers, bindings, candidates, ambiguous_bindings = [])
+      @workers = workers
+      @bindings = bindings.group_by(&:name)
+      @candidates = candidates.group_by(&:name)
+      @ambiguous_bindings = ambiguous_bindings.group_by(&:name)
+    end
+
+    def resolve
+      @candidates.keys.sort.to_h { |name| [name, resolve_identity(name)] }.freeze
+    end
+
+    private
+
+    def resolve_identity(name)
+      chain, locations, parts, visited = [], [], [], {}
+      current = name
+      reason = nil
+      loop do
+        chain << current
+        if visited[current]
+          reason = "alias_cycle"
+          break
+        end
+        visited[current] = true
+        candidates = @candidates.fetch(current, [])
+        bindings = @bindings.fetch(current, []).sort_by { |item| [item.location.path, item.location.line, item.location.column] }
+        ambiguous = @ambiguous_bindings.fetch(current.split("::").last, []).reject { |item| bindings.any? { |binding| binding.location == item.location } }
+        if candidates.empty? && @workers.key?(current) && ambiguous.empty?
+          return resolution(name, current, chain, nil, locations, parts)
+        end
+        locations.concat((bindings + ambiguous).map(&:location))
+        parts << [current, (bindings + ambiguous).map(&:fingerprint_parts).sort_by(&:inspect)]
+        unless ambiguous.empty?
+          reason = "alias_binding_conflict"
+          break
+        end
+        if candidates.empty?
+          reason = "alias_target_unresolved"
+          break
+        end
+        if bindings.length != 1
+          reason = "alias_binding_conflict"
+          break
+        end
+        candidate = candidates.first
+        unless candidate.supported
+          reason = "unsupported_alias_assignment"
+          break
+        end
+        lookup = ConstantLookup.candidates(candidate.reference, candidate.root, candidate.namespace)
+        target = lookup.find { |identity| @bindings.key?(identity) || @workers.key?(identity) }
+        unless target
+          chain << lookup.first
+          reason = "alias_target_unresolved"
+          break
+        end
+        current = target
+      end
+      resolution(name, nil, chain, reason, locations, parts)
+    end
+
+    def resolution(name, target, chain, reason, locations, parts)
+      AliasResolution.new(name, reason ? "unknown" : "resolved", target, chain.freeze, reason,
+                          locations.uniq.freeze, parts.freeze, @candidates.fetch(name).any? { |candidate| candidate.reference })
+    end
+  end
+end

data/lib/jobcompat/analysis.rb

@@ -1,5 +1,6 @@
 require "prism"
 require_relative "canonical_worker_name"
+require_relative "aliases"
 
 module Jobcompat
   Location = Data.define(:revision, :path, :line, :column, :role, :excerpt) do
@@ -56,14 +57,32 @@ module Jobcompat
   end
 
   class RevisionSnapshot
-    attr_reader :label, :ref, :sha, :workers, :calls, :unknowns, :index, :files_scanned, :tracked_ruby
+    attr_reader :label, :ref, :sha, :workers, :aliases, :bindings, :calls, :unknowns, :index, :files_scanned, :tracked_ruby
 
-    def initialize(label:, ref:, sha:, workers:, calls:, unknowns:, index:, files_scanned:, tracked_ruby:)
+    def initialize(label:, ref:, sha:, workers:, calls:, unknowns:, index:, files_scanned:, tracked_ruby:, aliases: {}, bindings: [])
       @label, @ref, @sha, @workers, @calls, @unknowns, @index, @files_scanned, @tracked_ruby = label, ref, sha, workers, calls, unknowns, index, files_scanned, tracked_ruby
+      @aliases = aliases
+      @bindings = bindings.group_by(&:name).freeze
+    end
+
+    def consumer(name)
+      binding = aliases[name]
+      return workers[name] unless binding
+      return unless binding.resolved?
+      terminal = workers.fetch(binding.target)
+      terminal.with(name: name, locations: (binding.locations + terminal.locations).uniq,
+                    declaration_locations: (binding.locations + terminal.declaration_locations).uniq,
+                    fingerprint_parts: [binding.fingerprint_parts, terminal.fingerprint_parts])
+    end
+
+    def presence(name)
+      binding = aliases[name]
+      return binding.resolved? ? "resolved_alias" : "defined_unrecognized" if binding
+      index.status(name, recognized: workers.key?(name))
     end
 
     def check_presence(names, repository, config)
-      unresolved = names.reject { |name| index.status(name, recognized: workers.key?(name)) != "absent" }
+      unresolved = names.select { |name| presence(name) == "absent" }
       return if unresolved.empty?
       consumed = 0
       eligible = []
@@ -105,11 +124,12 @@ module Jobcompat
     PATH_CONSTANT_BINDINGS = [Prism::ConstantPathWriteNode, Prism::ConstantPathOrWriteNode,
                               Prism::ConstantPathAndWriteNode, Prism::ConstantPathOperatorWriteNode,
                               Prism::ConstantPathTargetNode].freeze
-    attr_reader :fragments, :calls, :unknowns
+    attr_reader :fragments, :calls, :unknowns, :bindings, :alias_candidates, :ambiguous_bindings
 
     def initialize(revision, path, source, index:, presence_only: false)
       @revision, @path, @source, @index, @presence_only = revision, path, source, index, presence_only
       @fragments, @calls, @unknowns = [], [], []
+      @bindings, @alias_candidates, @ambiguous_bindings = [], [], []
     end
 
     def analyze
@@ -122,7 +142,7 @@ module Jobcompat
         end
         raise Error.new(diagnostics.first[:message], category: "parse_error", location: diagnostics.first[:location], diagnostics: diagnostics)
       end
-      walk(result.value, [], [], nil)
+      walk(result.value, [], [], nil, true)
       self
     end
 
@@ -156,19 +176,30 @@ module Jobcompat
 
     private
 
-    def walk(node, namespace, scope, statement)
+    def walk(node, namespace, scope, statement, alias_context = false, alias_statement = nil)
       return unless node.is_a?(Prism::Node)
       case node
+      when Prism::ProgramNode
+        walk(node.statements, namespace, scope, nil, alias_context)
       when Prism::StatementsNode
-        node.body.each { |child| walk(child, namespace, scope, child) }
+        node.body.each { |child| walk(child, namespace, scope, child, alias_context, alias_context ? child : (alias_statement || child)) }
       when Prism::ClassNode, Prism::ModuleNode
         constant = self.class.constant(node.constant_path)
         name, valid = declaration_name(constant, namespace)
         location = loc(node, "worker_declaration")
         @index.add(name, location, selected: !@presence_only, ambiguous: !valid) if name
+        if name && !@presence_only
+          @bindings << ConstantBinding.new(name, "declaration", location,
+                                            [scope, self.class.normalize(node.constant_path.location.slice), node.class.name])
+        end
         if !name && node.constant_path.is_a?(Prism::ConstantPathNode)
           @index.add(node.constant_path.name.to_s.encode(Encoding::UTF_8), location, selected: !@presence_only, ambiguous: true)
         end
+        unless valid || @presence_only
+          leaf = name&.split("::")&.last || node.constant_path.name.to_s.encode(Encoding::UTF_8)
+          @ambiguous_bindings << ConstantBinding.new(leaf, "declaration", location,
+                                                     [scope, self.class.normalize(node.constant_path.location.slice), node.class.name])
+        end
         new_scope = scope + [name || "<unsupported_class>"]
         if node.is_a?(Prism::ClassNode) && valid && !@presence_only
           body = node.body.is_a?(Prism::StatementsNode) ? node.body.body : []
@@ -185,24 +216,25 @@ module Jobcompat
                                    [@path, new_scope, self.class.normalize(node.constant_path.location.slice), include_tokens])
         end
         child_namespace = valid && namespace ? namespace + [name] : nil
-        walk(node.superclass, namespace, scope, statement) if node.is_a?(Prism::ClassNode) && node.superclass
-        walk(node.body, child_namespace, new_scope, nil) if node.body
+        walk(node.superclass, namespace, scope, statement, false, alias_statement) if node.is_a?(Prism::ClassNode) && node.superclass
+        body_context = alias_context && node.equal?(statement) && valid
+        walk(node.body, child_namespace, new_scope, nil, body_context, body_context ? nil : alias_statement) if node.body
       when Prism::DefNode
         method_scope = node.receiver ? [self.class.normalize(node.receiver.location.slice), node.name.to_s] : node.name.to_s
         child_scope = scope + [method_scope]
-        walk(node.receiver, namespace, scope, statement) if node.receiver
-        walk(node.parameters, namespace, child_scope, node.parameters) if node.parameters
-        walk(node.body, namespace, child_scope, nil) if node.body
+        walk(node.receiver, namespace, scope, statement, false, alias_statement) if node.receiver
+        walk(node.parameters, namespace, child_scope, node.parameters, false, alias_statement) if node.parameters
+        walk(node.body, namespace, child_scope, nil, false, alias_statement) if node.body
       when Prism::SingletonClassNode
-        walk(node.expression, namespace, scope, statement)
+        walk(node.expression, namespace, scope, statement, false, alias_statement)
         singleton_scope = scope + [["singleton_class", self.class.normalize(node.expression.location.slice)]]
-        walk(node.body, namespace, singleton_scope, nil) if node.body
+        walk(node.body, namespace, singleton_scope, nil, false, alias_statement) if node.body
       when Prism::CallNode
         extract_call(node, namespace, scope, statement) unless @presence_only
-        node.compact_child_nodes.each { |child| walk(child, namespace, scope, statement) }
+        node.compact_child_nodes.each { |child| walk(child, namespace, scope, statement, false, alias_statement || statement) }
       else
-        constant_write(node, namespace) if SIMPLE_CONSTANT_BINDINGS.any? { |type| node.is_a?(type) } || PATH_CONSTANT_BINDINGS.any? { |type| node.is_a?(type) }
-        node.compact_child_nodes.each { |child| walk(child, namespace, scope, statement) }
+        constant_write(node, namespace, scope, alias_statement || statement, alias_context && node.equal?(statement)) if SIMPLE_CONSTANT_BINDINGS.any? { |type| node.is_a?(type) } || PATH_CONSTANT_BINDINGS.any? { |type| node.is_a?(type) }
+        node.compact_child_nodes.each { |child| walk(child, namespace, scope, statement, false, alias_statement || statement) }
       end
     end
 
@@ -214,10 +246,12 @@ module Jobcompat
       [((rooted || segments.length > 1) ? segments : (namespace.empty? ? [] : namespace.last.split("::")) + segments).join("::"), true]
     end
 
-    def constant_write(node, namespace)
+    def constant_write(node, namespace, scope, statement, alias_context)
       if SIMPLE_CONSTANT_BINDINGS.any? { |type| node.is_a?(type) }
         prefix = namespace.nil? || namespace.empty? ? [] : namespace.last.split("::")
-        @index.add((prefix + [node.name.to_s.encode(Encoding::UTF_8)]).join("::"), loc(node, "worker_declaration"),
+        name = (prefix + [node.name.to_s.encode(Encoding::UTF_8)]).join("::")
+        valid = !namespace.nil?
+        @index.add(name, loc(node, "worker_declaration"),
                    selected: !@presence_only, ambiguous: namespace.nil?)
       else
         target = node.is_a?(Prism::ConstantPathTargetNode) ? node : node.target
@@ -228,6 +262,22 @@ module Jobcompat
           @index.add(target.name.to_s.encode(Encoding::UTF_8), loc(node, "worker_declaration"), selected: !@presence_only, ambiguous: true)
         end
       end
+      return if @presence_only
+      unless valid
+        leaf = name&.split("::")&.last || target.name.to_s.encode(Encoding::UTF_8)
+        @ambiguous_bindings << ConstantBinding.new(leaf, "write", loc(node, "worker_declaration"),
+                                                   [scope, self.class.normalize(node.location.slice), self.class.normalize((statement || node).location.slice)])
+      end
+      return if name.nil?
+      plain = node.is_a?(Prism::ConstantWriteNode) || node.is_a?(Prism::ConstantPathWriteNode)
+      reference = self.class.constant(node.value) if node.respond_to?(:value)
+      supported = plain && valid && alias_context && reference &&
+                  (reference.last || reference.first.length == 1 || namespace.empty?)
+      location = loc(node, "worker_declaration")
+      parts = [scope, self.class.normalize(node.location.slice), self.class.normalize((statement || node).location.slice), reference]
+      @bindings << ConstantBinding.new(name, "write", location, parts)
+      @alias_candidates << AliasCandidate.new(name, reference && reference.first.join("::"), reference && reference.last,
+                                              namespace, !!supported, location, parts)
     end
 
     def sidekiq_include?(node)
@@ -421,7 +471,7 @@ module Jobcompat
       selected = entries.select { |entry| @config.scan?(entry.path) }
       tracked = entries.select { |entry| entry.path.end_with?(".rb") }
       index = DefinedConstantIndex.new
-      fragments, calls, unknowns, errors = [], [], [], []
+      fragments, calls, unknowns, errors, bindings, alias_candidates, ambiguous_bindings = [], [], [], [], [], [], []
       @repository.each_blob(selected) do |entry, bytes|
         path = entry.path
         begin
@@ -429,6 +479,9 @@ module Jobcompat
           fragments.concat(result.fragments)
           calls.concat(result.calls)
           unknowns.concat(result.unknowns)
+          bindings.concat(result.bindings)
+          alias_candidates.concat(result.alias_candidates)
+          ambiguous_bindings.concat(result.ambiguous_bindings)
         rescue Error => error
           errors << error
         end
@@ -470,8 +523,9 @@ module Jobcompat
           workers[name] = Contract.new(name, required, rest ? nil : required + optional, forwarding ? "forwarding" : "positional", signature, nil, locations, declarations, fingerprint_parts)
         end
       end
-      RevisionSnapshot.new(label: label, ref: ref, sha: sha, workers: workers, calls: calls, unknowns: unknowns, index: index,
-                           files_scanned: selected.length, tracked_ruby: tracked)
+      aliases = AliasResolver.new(workers, bindings, alias_candidates, ambiguous_bindings).resolve
+      RevisionSnapshot.new(label: label, ref: ref, sha: sha, workers: workers, aliases: aliases, calls: calls, unknowns: unknowns, index: index,
+                           files_scanned: selected.length, tracked_ruby: tracked, bindings: bindings)
     end
   end
 end

data/lib/jobcompat/cli.rb

@@ -98,7 +98,7 @@ module Jobcompat
     end
 
     def envelope(status, findings, suppressions, workers, diagnostics, summary)
-      {schema_version: 2, tool: {name: "jobcompat", version: VERSION}, status: status,
+      {schema_version: 3, tool: {name: "jobcompat", version: VERSION}, status: status,
        comparison: {deployment_model: "rolling", base: {ref: @base, sha: @base_sha}, head: {ref: @head, sha: @head_sha}},
        configuration: {path: @loaded_config}, findings: findings, suppressions: suppressions, workers: workers,
        diagnostics: diagnostics, summary: summary}

data/lib/jobcompat/engine.rb

@@ -4,7 +4,7 @@ module Jobcompat
     REVISIONS = %w[base head].freeze
     TITLES = {
       "JC001" => "Old payload rejected by new worker", "JC002" => "New payload rejected by old worker",
-      "JC003" => "Current producer/consumer mismatch", "JC004" => "Worker class absent from HEAD source",
+      "JC003" => "Current producer/consumer mismatch", "JC004" => "Worker identity absent from HEAD source",
       "JC005" => "New worker enqueued before old fleet can understand it", "JC006" => "Worker contract narrowed without sufficient producer evidence",
       "JC007" => "Compatibility could not be proven"
     }.freeze
@@ -13,13 +13,18 @@ module Jobcompat
 
     def initialize(base, head)
       @base, @head = base, head
-      @names = (base.workers.keys + head.workers.keys).uniq.sort
-      @calls = {"base" => resolve(base.calls), "head" => resolve(head.calls)}
+      @lookup_names = (base.workers.keys + head.workers.keys + base.aliases.keys + head.aliases.keys).uniq
+      @calls = {"base" => resolve(base), "head" => resolve(head)}
+      referenced = calls.values.flatten.flat_map { |call| [call[:worker], call[:attributed_worker]] }.compact
+      shared_aliases = (base.aliases.keys & head.aliases.keys).select { |name| base.aliases[name].static_reference || head.aliases[name].static_reference }
+      @names = (base.workers.keys + head.workers.keys +
+                base.aliases.values.select(&:resolved?).map(&:name) +
+                shared_aliases + referenced).uniq.sort
       @calls_by_worker = {"base" => calls["base"].group_by { |call| call[:worker] },
                           "head" => calls["head"].group_by { |call| call[:worker] }}
       @presence_requests = {
-        "head" => (base.workers.keys - head.workers.keys).sort,
-        "base" => (head.workers.keys - base.workers.keys).select { |name| @calls_by_worker["head"].key?(name) }.sort
+        "head" => @names.select { |name| base.consumer(name) && !head.consumer(name) },
+        "base" => @names.select { |name| head.consumer(name) && !base.consumer(name) && @calls_by_worker["head"].key?(name) }
       }
     end
 
@@ -30,8 +35,8 @@ module Jobcompat
     def evaluate
       findings = []
       workers = @names.map do |name|
-        b = base.workers[name]
-        h = head.workers[name]
+        b = base.consumer(name)
+        h = head.consumer(name)
         bc = @calls_by_worker["base"].fetch(name, [])
         hc = @calls_by_worker["head"].fetch(name, [])
         base_presence = presence(base, name, b, presence_requests["base"].include?(name))
@@ -39,21 +44,21 @@ module Jobcompat
         if b && !h
           if head_presence == "absent"
             findings << finding("JC004", name, ["base", "head"], ["base_to_head"], nil, nil,
-                                "The worker class is absent from HEAD tracked Ruby source.",
+                                "The serialized worker identity is absent from HEAD tracked Ruby source.",
                                 "Queued, retried, or scheduled jobs may still reference this class name.",
-                                ["Keep a compatibility class until retained jobs can no longer run."],
-                                b.declaration_locations + b.locations.select { |loc| loc.role == "consumer" } + hc.map { |call| call[:location] })
+                                ["Keep the worker class or a supported compatibility alias until retained jobs can no longer run."],
+                                b.declaration_locations + contract_proof(b) + producer_proof(hc))
           else
-            findings << presence_unknown(name, head_presence, b.declaration_locations + head.index.locations(name), "base_to_head", "head")
+            findings << presence_unknown(name, head_presence, b.declaration_locations + head.index.locations(name), "base_to_head", "head") unless head.aliases.key?(name)
           end
         elsif h && !b && !hc.empty?
           if base_presence == "absent"
             findings << finding("JC005", name, ["base", "head"], ["head_to_base"], nil, nil,
-                                "HEAD can enqueue a worker class absent from base tracked Ruby source.",
+                                "HEAD can enqueue a serialized worker identity absent from base tracked Ruby source.",
                                 "If an old Sidekiq process can consume this job during the rolling deployment, it cannot resolve the new worker class.",
-                                ["Deploy the worker class before activating its producer."], h.declaration_locations + hc.map { |call| call[:location] })
+                                ["Deploy the worker class or compatibility alias before activating its producer."], h.declaration_locations + producer_proof(hc))
           else
-            findings << presence_unknown(name, base_presence, h.declaration_locations + base.index.locations(name), "head_to_base", "base")
+            findings << presence_unknown(name, base_presence, h.declaration_locations + base.index.locations(name), "head_to_base", "base") unless base.aliases.key?(name)
           end
         end
 
@@ -66,7 +71,7 @@ module Jobcompat
             head_same = head_groups.fetch(arity, []).select { |call| !h.accepts?(call[:arity]) }
             directions = ["base_to_head"]
             directions << "head_to_head" unless head_same.empty?
-            locations = group.map { |call| call[:location] } + b.locations.select { |loc| loc.role == "consumer" } + h.locations.select { |loc| loc.role == "consumer" } + head_same.map { |call| call[:location] }
+            locations = producer_proof(group) + contract_proof(b) + contract_proof(h) + producer_proof(head_same)
             findings << finding("JC001", name, head_same.empty? ? ["base", "head"] : ["base", "head"], directions, arity, nil,
                                 "Base emits #{arity} #{argument_word(arity)}, but the HEAD worker accepts #{h.display_range}.",
                                 "Jobs queued by the base revision may fail after deployment.",
@@ -82,14 +87,14 @@ module Jobcompat
               findings << finding("JC003", name, ["head"], ["head_to_head"], arity, nil,
                                   "HEAD emits #{arity} #{argument_word(arity)}, but its worker accepts #{h.display_range}.",
                                   "Current HEAD jobs can fail when executed.", ["Align the enqueue payload with the HEAD perform signature."],
-                                  group.map { |call| call[:location] } + h.locations.select { |loc| loc.role == "consumer" })
+                                  producer_proof(group) + contract_proof(h))
               current_removed_witness ||= b&.known? && b.accepts?(arity)
             elsif b&.known? && !b.accepts?(arity)
               findings << finding("JC002", name, ["base", "head"], ["head_to_base"], arity, nil,
                                   "HEAD emits #{arity} #{argument_word(arity)}, but the base worker accepts #{b.display_range}.",
                                   "A new producer can enqueue work that an old worker cannot execute during a rolling deploy.",
                                   ["Deploy the optional worker argument first.", "Start enqueueing the new argument in a later release."],
-                                  group.map { |call| call[:location] } + b.locations.select { |loc| loc.role == "consumer" } + h.locations.select { |loc| loc.role == "consumer" })
+                                  producer_proof(group) + contract_proof(b) + contract_proof(h))
             end
           end
         end
@@ -101,12 +106,13 @@ module Jobcompat
                                 "The HEAD worker removed #{label} #{removed.join(', ')} from the base contract; no qualifying producer witness was found.",
                                 "No repository producer callsite found does not prove that no queued, scheduled, retried, historical, or externally enqueued payload exists.",
                                 ["Keep the broader signature through the retention window, or document a proven drain."],
-                                b.locations.select { |loc| loc.role == "consumer" } + h.locations.select { |loc| loc.role == "consumer" })
+                                contract_proof(b) + contract_proof(h))
           end
         end
 
         {
           name: name, base_presence: base_presence, head_presence: head_presence,
+          base_alias: base.aliases[name]&.as_json, head_alias: head.aliases[name]&.as_json,
           base_contract: b&.as_json, head_contract: h&.as_json,
           producer_arities: {base: bc.filter_map { |call| call[:arity] unless call[:reason] }.uniq.sort,
                              head: hc.filter_map { |call| call[:arity] unless call[:reason] }.uniq.sort,
@@ -122,35 +128,72 @@ module Jobcompat
 
     private
 
-    def resolve(raw_calls)
-      raw_calls.sort_by { |call| [call.path, call.location.line, call.location.column, call.method,
+    def resolve(snapshot)
+      snapshot.calls.sort_by { |call| [call.path, call.location.line, call.location.column, call.method,
                                   call.arity.nil? ? Float::INFINITY : call.arity, call.unknown_reason.to_s] }.filter_map do |call|
         worker = nil
+        attributed_worker = nil
+        binding = nil
+        binding_locations = []
+        identity_reason = nil
         if call.receiver
           candidates = if call.resolution_mode == "exact_string" || call.root
                          [call.receiver]
-                       elsif call.namespace.nil?
-                         []
                        else
-                         (call.namespace.reverse.map { |prefix| "#{prefix}::#{call.receiver}" } + [call.receiver]).uniq
+                         ConstantLookup.candidates(call.receiver, false, call.namespace)
                        end
-          worker = candidates.find { |name| @names.include?(name) }
+          worker = producer_identity(snapshot, candidates, call.resolution_mode)
+          attributed_worker = worker
+          if worker && call.resolution_mode != "exact_string" && snapshot.aliases.key?(worker)
+            binding = snapshot.aliases[worker]
+            worker = binding.resolved? ? binding.target : nil if binding
+            binding_locations = snapshot.workers.fetch(binding.target).locations if binding.resolved?
+          elsif worker && alias_lookup?(candidates, call.resolution_mode) && snapshot.bindings.key?(worker) && !snapshot.workers.key?(worker)
+            binding_locations = snapshot.bindings.fetch(worker).map(&:location)
+            identity_reason = "worker_not_recognized"
+            worker = nil
+          elsif worker && call.resolution_mode != "exact_string" && !snapshot.workers.key?(worker) && (base.aliases.key?(worker) || head.aliases.key?(worker))
+            worker = nil
+          end
           client_target = %w[client_constant exact_string].include?(call.resolution_mode)
-          next unless worker || client_target || (!call.root && call.namespace.nil?)
+          next unless worker || attributed_worker || client_target || (!call.root && call.namespace.nil?)
         end
-        reason = call.unknown_reason
+        identity_reason ||= binding && !binding.resolved? ? binding.unknown_reason : nil
+        identity_reason ||= "alias_target_unresolved" if worker.nil? && attributed_worker
+        reason = identity_reason || call.unknown_reason
         reason ||= "dynamic_client_class" if call.receiver && worker.nil? && %w[client_constant exact_string].include?(call.resolution_mode)
         reason ||= call.namespace.nil? ? "unsupported_constant_path" : "dynamic_receiver" if worker.nil?
-        {worker: worker, location: call.location, arity: call.arity, reason: reason, raw: call}
+        {worker: worker, attributed_worker: attributed_worker, identity_known: !worker.nil?, identity_reason: identity_reason,
+         location: call.location, locations: [call.location] + (binding&.locations || []) + binding_locations,
+         arity: call.arity, reason: reason, raw: call}
+      end
+    end
+
+    def producer_identity(snapshot, candidates, mode)
+      if alias_lookup?(candidates, mode)
+        local = candidates.find { |name| snapshot.bindings.key?(name) || snapshot.workers.key?(name) || snapshot.aliases.key?(name) }
+        return local if local
       end
+      candidates.find { |name| @lookup_names.include?(name) }
+    end
+
+    def alias_lookup?(candidates, mode)
+      mode != "exact_string" && candidates.any? { |name| base.aliases.key?(name) || head.aliases.key?(name) }
     end
 
     def presence(snapshot, name, contract, queried)
-      return "recognized_worker" if contract
+      return snapshot.presence(name) if contract || snapshot.aliases.key?(name)
       return "not_checked" unless queried
       snapshot.index.status(name)
     end
 
+    def producer_proof(group) = group.flat_map { |call| call[:locations] }
+
+    def contract_proof(contract)
+      return contract.locations if base.aliases.key?(contract.name) || head.aliases.key?(contract.name)
+      contract.locations.select { |location| location.role == "consumer" }
+    end
+
     def cell(producers, consumer, status)
       return "not_applicable" if producers.empty?
       known = producers.filter_map { |call| call[:arity] unless call[:reason] }
@@ -196,22 +239,32 @@ module Jobcompat
     def unknown_findings
       roots = []
       [base, head].each do |snapshot|
-        snapshot.workers.each do |name, contract|
-          next if contract.known?
+        @names.each do |name|
+          contract = snapshot.consumer(name)
+          next if !contract || contract.known?
           parts = ["consumer_contract", contract.unknown_reason, name, contract.fingerprint_parts]
           roots << {revision: snapshot.label, kind: "consumer_contract", reason: contract.unknown_reason, worker: name,
                     locations: contract.locations, parts: parts, offset: contract.locations.first&.line || 0}
         end
+        snapshot.aliases.each do |name, binding|
+          next if binding.resolved? || !@names.include?(name)
+          producer_locations = calls[snapshot.label].select { |call| call[:identity_reason] && call[:attributed_worker] == name }.flat_map { |call| call[:locations] }
+          roots << {revision: snapshot.label, kind: "consumer_alias", reason: binding.unknown_reason, worker: name,
+                    locations: binding.locations + producer_locations,
+                    parts: ["consumer_alias", binding.unknown_reason, name, binding.fingerprint_parts, binding.chain], offset: 0}
+        end
         snapshot.unknowns.each do |item|
           roots << {revision: snapshot.label, kind: item.kind, reason: item.reason, worker: item.worker,
                     locations: item.locations, parts: [item.kind, item.reason, item.worker, item.fingerprint_parts], offset: item.locations.first&.line || 0}
         end
         calls[snapshot.label].each do |call|
           next unless call[:reason]
+          next if call[:identity_reason] && snapshot.aliases.key?(call[:attributed_worker])
           raw = call[:raw]
-          kind = %w[dynamic_receiver unsupported_constant_path safe_navigation_receiver].include?(call[:reason]) ? "producer_receiver" : "producer_arity"
-          roots << {revision: snapshot.label, kind: kind, reason: call[:reason], worker: call[:worker],
-                    locations: [call[:location]], parts: [kind, call[:reason], call[:worker], raw.fingerprint_parts],
+          kind = call[:identity_reason] || %w[dynamic_receiver unsupported_constant_path safe_navigation_receiver].include?(call[:reason]) ? "producer_receiver" : "producer_arity"
+          diagnostic_worker = call[:worker] || (call[:identity_reason] && call[:attributed_worker])
+          roots << {revision: snapshot.label, kind: kind, reason: call[:reason], worker: diagnostic_worker,
+                    locations: call[:locations], parts: [kind, call[:reason], diagnostic_worker, raw.fingerprint_parts],
                     offset: [call[:location].line, call[:location].column]}
         end
       end
@@ -227,20 +280,35 @@ module Jobcompat
           when ["producer_arity", "base"], ["producer_receiver", "base"] then ["base_to_head"]
           when ["producer_arity", "head"], ["producer_receiver", "head"] then ["head_to_base", "head_to_head"]
           when ["consumer_contract", "base"], ["worker_identity", "base"] then ["head_to_base"]
+          when ["consumer_alias", "base"] then ["head_to_base"]
+          when ["consumer_alias", "head"]
+            @calls_by_worker["head"].key?(root[:worker]) ? ["base_to_head", "head_to_head"] : ["base_to_head"]
           else ["base_to_head", "head_to_head"]
           end
         end.uniq
         if first[:kind] == "producer_arity" && first[:worker]
-          head_only_new = head.workers.key?(first[:worker]) && !base.workers.key?(first[:worker])
+          head_only_new = head.consumer(first[:worker]) && !base.consumer(first[:worker])
           directions.delete("head_to_base") if head_only_new && group.any? { |root| root[:revision] == "head" } && base.index.status(first[:worker]) == "absent"
         end
+        alias_reason = %w[alias_target_unresolved alias_cycle alias_binding_conflict unsupported_alias_assignment].include?(first[:reason])
+        message = alias_reason ? alias_message(first[:worker], first[:reason]) : "#{first[:reason]} prevents a complete positional compatibility check."
+        risk = alias_reason ? "Compatibility for jobs serialized as #{first[:worker]} cannot be proven from selected source." : "The affected producer or consumer contract is unknown."
+        remediation = alias_reason ? ["Use one explicit static alias if it matches runtime behavior, or inspect the deployment manually."] : ["Use supported explicit syntax or inspect this call manually."]
         finding("JC007", first[:worker], group.map { |root| root[:revision] }.uniq, directions, nil, first[:reason],
-                "#{first[:reason]} prevents a complete positional compatibility check.",
-                "The affected producer or consumer contract is unknown.", ["Use supported explicit syntax or inspect this call manually."],
+                message, risk, remediation,
                 group.flat_map { |root| root[:locations] })
       end
     end
 
+    def alias_message(name, reason)
+      case reason
+      when "alias_target_unresolved" then "#{name} is bound as a compatibility alias, but its target cannot be resolved to a supported Sidekiq worker."
+      when "alias_cycle" then "Compatibility alias resolution for #{name} enters a constant-alias cycle."
+      when "alias_binding_conflict" then "#{name} has multiple or conflicting constant bindings, so its runtime job class cannot be proven."
+      when "unsupported_alias_assignment" then "#{name} is assigned through syntax or control flow that does not prove one unconditional static compatibility alias."
+      end
+    end
+
     def finding_sort_key(item)
       loc = item[:locations].first
       [item[:severity] == "error" ? 0 : 1, item[:rule_id], item[:worker] || "\u{10ffff}", item[:payload_arity] || Float::INFINITY,

data/lib/jobcompat/version.rb

@@ -1,3 +1,3 @@
 module Jobcompat
-  VERSION = "0.2.1"
+  VERSION = "0.3.0"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: jobcompat
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - jobcompat contributors
@@ -44,18 +44,23 @@ files:
 - docs/competitive-analysis.md
 - docs/implementation-plan-v0.2.1.md
 - docs/implementation-plan-v0.2.md
+- docs/implementation-plan-v0.3.md
 - docs/implementation-plan.md
 - docs/release-checklist-v0.1.0.md
 - docs/release-checklist-v0.2.0.md
 - docs/release-checklist-v0.2.1.md
+- docs/release-checklist-v0.3.0.md
 - docs/release-notes-v0.1.0.md
 - docs/release-notes-v0.2.0.md
 - docs/release-notes-v0.2.1.md
+- docs/release-notes-v0.3.0.md
 - docs/spec-v0.1.md
 - docs/spec-v0.2.1.md
 - docs/spec-v0.2.md
+- docs/spec-v0.3.md
 - exe/jobcompat
 - lib/jobcompat.rb
+- lib/jobcompat/aliases.rb
 - lib/jobcompat/analysis.rb
 - lib/jobcompat/canonical_worker_name.rb
 - lib/jobcompat/cli.rb