feat(pq-oid/ts): phase 3 - add migration compatibility layer (ENG-1916)

[eacet]

Summary

Package(s)

Languages

• TypeScript
• Rust

Checklist

• Tests pass for all modified packages
• Linting/formatting passes (biome check, cargo fmt)
• Both language implementations are consistent (or noted as follow-up)
• Package README updated if public API changed
• No unnecessary dependencies added

Related Issues

[eacet]

• chore(pq-algorithm-id/ts): phase 4 - release hardening and adoption validation (ENG-1917) #29
• feat(pq-oid/ts): phase 3 - add migration compatibility layer (ENG-1916) #28 👈 (View in Graphite)
• feat(pq-algorithm-id/ts): phase 2 - implement conversion and x509 mapping apis (ENG-1915) #27
• feat(pq-algorithm-id/ts): phase 1 - package foundation and canonical registry (ENG-1914) #26
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[greptile-apps]

Greptile Summary

This PR introduces a migration compatibility layer for the pq-oid package, marking its JOSE/COSE helpers as @deprecated in favour of the new canonical pq-algorithm-id package, and updates the READMEs of both packages to guide consumers through the transition.

Key changes:

• pq-oid/ts/src/index.ts: Internal COSE/JOSE imports are aliased, and the four functions (toJOSE, fromJOSE, toCOSE, fromCOSE) are re-exported as top-level named exports decorated with @deprecated JSDoc pointing to pq-algorithm-id equivalents. The same deprecation tags are added to their entries inside the OID object.
• pq-oid/ts/README.md: A "Migration Note" section is added explaining the package boundary, with a code snippet showing the new pq-algorithm-id API. However, the pre-existing usage example incorrectly documents OID.toCOSE('ML-DSA-65') as -48 — which is actually the value for ML-DSA-44 — while the newly added migration snippet in the same file correctly shows -49, creating a direct contradiction.
• pq-algorithm-id/ts/README.md: Fully replaces the placeholder with complete API documentation including behaviour notes, examples, and a suggested downstream adoption order.

Confidence Score: 3/5

• Safe to merge after fixing the contradictory COSE value documented for ML-DSA-65 in pq-oid/ts/README.md.
• The code change in index.ts is correct and low-risk. The only meaningful problem is a documentation bug: the pq-oid README's legacy usage example documents -48 as the COSE value for ML-DSA-65, while the implementation (and the migration snippet added in this same PR) both use -49. A developer following the compatibility-path examples would wire up the wrong COSE number.
• packages/pq-oid/ts/README.md — the COSE value for ML-DSA-65 in the usage example needs to be corrected from -48 to -49.

Important Files Changed

Filename	Overview
packages/pq-oid/ts/src/index.ts	Adds @deprecated JSDoc tags and re-exports toJOSE, fromJOSE, toCOSE, fromCOSE as named exports pointing to the existing mapping functions; correctly aliases internal imports to avoid naming conflicts. Logic is sound.
packages/pq-oid/ts/README.md	Adds migration note and compatibility path documentation, but the existing usage example incorrectly shows -48 as the COSE value for ML-DSA-65 (actual value is -49; -48 is ML-DSA-44), while the newly added migration snippet in the same file correctly shows -49 — making the README self-contradictory.
packages/pq-algorithm-id/ts/README.md	New README providing full API documentation for pq-algorithm-id. Values and examples are consistent with the actual registry implementation.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    Consumer["Consumer code"]

    subgraph pq-oid ["pq-oid (compatibility path)"]
        OID_toJOSE["OID.toJOSE() ⚠️ deprecated"]
        OID_fromJOSE["OID.fromJOSE() ⚠️ deprecated"]
        OID_toCOSE["OID.toCOSE() ⚠️ deprecated"]
        OID_fromCOSE["OID.fromCOSE() ⚠️ deprecated"]
    end

    subgraph pq-algorithm-id ["pq-algorithm-id (canonical)"]
        toJose["toJose()"]
        fromJose["fromJose()"]
        toCose["toCose()"]
        fromCose["fromCose()"]
        toOid["toOid()"]
        fromOid["fromOid()"]
        toX509["toX509AlgorithmIdentifier()"]
        fromX509["fromX509AlgorithmIdentifier()"]
    end

    Consumer -->|"legacy / compat"| pq-oid
    Consumer -->|"new code (migrate here)"| pq-algorithm-id
    OID_toJOSE -.->|"replace with"| toJose
    OID_fromJOSE -.->|"replace with"| fromJose
    OID_toCOSE -.->|"replace with"| toCose
    OID_fromCOSE -.->|"replace with"| fromCose

Loading

Comments Outside Diff (1)

1. packages/pq-oid/ts/README.md, line 54-56 (link)

   Incorrect COSE values in usage example

   The usage example documents OID.toCOSE('ML-DSA-65') as returning -48 and OID.fromCOSE(-48) as resolving to 'ML-DSA-65', but both are wrong. Looking at the actual implementation in packages/pq-oid/ts/src/mappings/cose.ts:

   'ML-DSA-44': -48,  // -48 belongs to ML-DSA-44
   'ML-DSA-65': -49,  // ML-DSA-65 is -49
   'ML-DSA-87': -50,
   

   -48 maps to ML-DSA-44, not ML-DSA-65. The migration note added in this very same file correctly shows -49, making the README self-contradictory. A user relying on the legacy compatibility path who reads only the usage section will use the wrong COSE value.

_{Last reviewed commit: a80f35e}

[claude]

LGTM — straightforward deprecation annotations and documentation updates.

Extended reasoning...

Overview

This PR adds a migration compatibility layer for pq-oid/ts as phase 3 of the pq-algorithm-id rollout. It touches three files: pq-oid/ts/src/index.ts (import aliasing + @deprecated JSDoc tags on JOSE/COSE exports), pq-oid/ts/README.md (migration note + new pq-algorithm-id usage example), and pq-algorithm-id/ts/README.md (comprehensive API documentation).

Security risks

None. The code changes are purely mechanical — renaming imports to add aliased re-exports with deprecation annotations. No runtime behavior changes. The packages deal with post-quantum algorithm identifiers (OIDs, COSE/JOSE mappings), but this PR does not modify any mapping logic or cryptographic code.

Level of scrutiny

Low scrutiny is appropriate. The index.ts changes are a textbook deprecation pattern: alias the internal import, re-export with a @deprecated JSDoc tag. The README changes are documentation only. No tests need updating since the exports are functionally identical.

Other factors

The inline bug comment identifies a pre-existing documentation error in pq-oid/ts/README.md where the COSE value for ML-DSA-65 is shown as -48 (should be -49). This error predates this PR — the PR merely makes it more visible by adding a correct example (toCose("ML-DSA-65"); // -49) alongside the old incorrect one. The bug is worth fixing but is not a blocker for this PR since it is in a code comment (README example), not executable code, and was not introduced by these changes.

[eacet]

Merge activity

• Mar 12, 12:35 PM UTC: A user started a stack merge that includes this pull request via Graphite.
• Mar 12, 12:38 PM UTC: Graphite rebased this pull request as part of a merge.
• Mar 12, 12:39 PM UTC: @eacet merged this pull request with Graphite.