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

## Summary

<!-- What does this PR do? Keep it brief. -->

## Package(s)

<!-- Which package(s) are modified? -->

## 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

<!-- Link any related issues: Fixes #123, Closes #456 -->

Author: eacet

packages/pq-algorithm-id/ts/README.md

@@ -1,6 +1,11 @@
 # pq-algorithm-id
 
-Algorithm identifier mappings (JOSE, COSE, X.509)
+Canonical post-quantum algorithm identifier mappings across `name`, `oid`, `jose`, `cose`, and `x509` descriptor shapes.
+
+Package boundary:
+
+- `pq-oid`: low-level OID primitives (constants, OID encode/decode)
+- `pq-algorithm-id`: multi-identifier mapping and normalization API
 
 ## Installation
 
@@ -11,11 +16,60 @@ npm install pq-algorithm-id
 ## Usage
 
 ```typescript
-import { } from 'pq-algorithm-id';
+import {
+  fromCose,
+  fromJose,
+  fromOid,
+  fromX509AlgorithmIdentifier,
+  toCose,
+  toJose,
+  toOid,
+  toX509AlgorithmIdentifier,
+} from 'pq-algorithm-id';
+
+// Name/OID lookup
+toOid('ML-DSA-65'); // '2.16.840.1.101.3.4.3.18'
+fromOid('2.16.840.1.101.3.4.3.18'); // 'ML-DSA-65'
+
+// JOSE/COSE mapping (currently ML-DSA only)
+toJose('ML-DSA-65'); // 'ML-DSA-65'
+fromJose('ML-DSA-65'); // 'ML-DSA-65'
+toCose('ML-DSA-65'); // -49
+fromCose(-49); // 'ML-DSA-65'
+
+// X.509 descriptor mapping
+toX509AlgorithmIdentifier('ML-KEM-768');
+// {
+//   oid: '2.16.840.1.101.3.4.4.2',
+//   parameters: { kind: 'absent' }
+// }
 
-// Coming soon
+fromX509AlgorithmIdentifier({
+  oid: '2.16.840.1.101.3.4.3.18',
+  parameters: null,
+});
+// {
+//   oid: '2.16.840.1.101.3.4.3.18',
+//   parameters: { kind: 'null' }
+// }
 ```
 
+## Behavior Notes
+
+- `fromOid`, `fromJose`, and `fromCose` are strict lookups (no trimming, no case normalization).
+- `toX509AlgorithmIdentifier(name)` emits `parameters: { kind: 'absent' }` by default.
+- `fromX509AlgorithmIdentifier(input)` accepts `parameters` as `undefined`, `null`, `{ kind: 'absent' }`, or `{ kind: 'null' }`.
+- Unsupported mappings (for example `toJose('ML-KEM-512')`) throw typed errors.
+
+## Adoption Order
+
+Suggested downstream migration order:
+
+1. `pq-key-encoder`
+2. `pq-cose`
+3. `pq-jws`
+4. `pq-jwk`
+
 ## License
 
 MIT

packages/pq-oid/ts/README.md

@@ -21,6 +21,12 @@ npm install pq-oid
 bun add pq-oid
 ```
 
+## Migration Note
+
+`pq-oid` remains the low-level OID primitive package. For canonical multi-identifier mapping (`name`/`oid`/`jose`/`cose`/`x509`), use `pq-algorithm-id`.
+
+The JOSE/COSE helpers in `pq-oid` are still available for compatibility and are now deprecated in favor of `pq-algorithm-id`.
+
 ## Usage
 
 ```typescript
@@ -43,7 +49,7 @@ OID.toName('2.16.840.1.101.3.4.3.18')       // 'ML-DSA-65'
 OID.toBytes('2.16.840.1.101.3.4.4.1')       // Uint8Array
 OID.fromBytes(bytes)                         // '2.16.840.1.101.3.4.4.1'
 
-// JOSE/COSE mappings (ML-DSA only)
+// JOSE/COSE mappings (ML-DSA only, compatibility path)
 OID.toJOSE('ML-DSA-65')                     // 'ML-DSA-65'
 OID.toCOSE('ML-DSA-65')                     // -48
 OID.fromJOSE('ML-DSA-65')                   // 'ML-DSA-65'
@@ -68,6 +74,16 @@ Algorithm.listByType('sign')                // ML-DSA + SLH-DSA variants
 Algorithm.listByFamily('ML-DSA')            // ['ML-DSA-44', 'ML-DSA-65', 'ML-DSA-87']
 ```
 
+For new identifier mapping code:
+
+```typescript
+import { fromJose, toCose, toOid } from 'pq-algorithm-id';
+
+toOid('ML-DSA-65');      // '2.16.840.1.101.3.4.3.18'
+fromJose('ML-DSA-65');   // 'ML-DSA-65'
+toCose('ML-DSA-65');     // -49
+```
+
 ## Supported Algorithms
 
 ### ML-KEM (FIPS 203) — Key Encapsulation

packages/pq-oid/ts/src/index.ts

@@ -1,8 +1,8 @@
 // Main exports for pq-oid package
 
 import { decodeOid, encodeOid } from './encoding';
-import { fromCOSE, toCOSE } from './mappings/cose';
-import { fromJOSE, toJOSE } from './mappings/jose';
+import { fromCOSE as fromCOSEMapping, toCOSE as toCOSEMapping } from './mappings/cose';
+import { fromJOSE as fromJOSEMapping, toJOSE as toJOSEMapping } from './mappings/jose';
 import {
   // Lookup functions
   fromName,
@@ -37,6 +37,18 @@ export { SlhDsa } from './slh-dsa';
 // Re-export all types
 export * from './types';
 
+/** @deprecated Use toJose() from 'pq-algorithm-id'. */
+export const toJOSE = toJOSEMapping;
+
+/** @deprecated Use fromJose() from 'pq-algorithm-id'. */
+export const fromJOSE = fromJOSEMapping;
+
+/** @deprecated Use toCose() from 'pq-algorithm-id'. */
+export const toCOSE = toCOSEMapping;
+
+/** @deprecated Use fromCose() from 'pq-algorithm-id'. */
+export const fromCOSE = fromCOSEMapping;
+
 // Unified OID object with all constants and functions
 export const OID = {
   // ML-KEM OID constants
@@ -74,10 +86,14 @@ export const OID = {
   fromBytes: decodeOid,
 
   // JOSE mapping functions
+  /** @deprecated Use toJose() from 'pq-algorithm-id'. */
   toJOSE,
+  /** @deprecated Use fromJose() from 'pq-algorithm-id'. */
   fromJOSE,
 
   // COSE mapping functions
+  /** @deprecated Use toCose() from 'pq-algorithm-id'. */
   toCOSE,
+  /** @deprecated Use fromCose() from 'pq-algorithm-id'. */
   fromCOSE,
 };