feat(pq-algorithm-id/ts): phase 1 - package foundation and canonical registry (ENG-1914)

[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
• 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 👈 (View in Graphite)
• main

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

[greptile-apps]

Greptile Summary

This PR introduces the TypeScript foundation for the pq-algorithm-id package — a canonical registry that maps post-quantum algorithm names (ML-KEM, ML-DSA, SLH-DSA) to their JOSE, COSE, and X.509 identifier representations, delegating OID derivation to the existing pq-oid dependency.

Key changes:

• New registry.ts builds a frozen, module-level IdentifierRecord map covering all 18 NIST PQC algorithms; lookup and listing helpers are exported as pure functions.
• New types.ts defines the public type surface (IdentifierRecord, X509ParametersPolicy, JoseIdentifier, CoseIdentifier, MappingTarget, etc.).
• New errors.ts provides a structured, typed error hierarchy (AlgorithmIdentifierError and three subtypes) with machine-readable code fields.
• Three test suites verify OID contract compatibility with pq-oid, registry invariants, and parity with the upstream algorithm list.
• tsconfig.json now uses composite: true with a project reference to pq-oid/ts, enabling incremental TypeScript builds.

Issues found:

• X509ParametersPolicy and IdentifierRecord in types.ts are declared as interface but should be type aliases per the project convention — neither is extended or implemented anywhere.
• IDENTIFIER_RECORDS_BY_NAME is cast as Record<AlgorithmName, IdentifierRecord> (widening the type to claim full coverage), which would hide a future divergence between ALGORITHM_NAMES and the upstream AlgorithmName union at the type level. The runtime guard in getIdentifierRecord and the parity test mitigate this, but switching to Partial<Record<...>> would make the guard load-bearing at compile time too.
• The JOSE/COSE invariant test uses listIdentifierRecords().find(...) inside a loop, producing O(n²) iteration where getIdentifierRecord would be cleaner.

Confidence Score: 4/5

• This PR is safe to merge with minor style fixes; no logic or runtime correctness issues were found.
• The implementation is well-structured, all 18 algorithms are covered, the registry is properly frozen, and three test suites provide solid coverage including parity against the upstream package. The only issues are a convention violation (interface vs type) and a type-level cast that could hide future drift — both are low-risk given the existing parity test.
• packages/pq-algorithm-id/ts/src/types.ts (interface vs type) and packages/pq-algorithm-id/ts/src/registry.ts (type cast on map).

Important Files Changed

Filename	Overview
packages/pq-algorithm-id/ts/src/types.ts	Defines core public types; X509ParametersPolicy and IdentifierRecord should be type aliases instead of interface per project convention.
packages/pq-algorithm-id/ts/src/registry.ts	Builds frozen canonical registry from pq-oid; the as Record<AlgorithmName, IdentifierRecord> cast widens the map type beyond its actual contents, masking future divergence at the type level (mitigated by runtime guard and parity test).
packages/pq-algorithm-id/ts/src/errors.ts	Clean custom error hierarchy with structured codes; new.target.name ensures correct subclass naming — no issues found.
packages/pq-algorithm-id/ts/src/index.ts	Re-exports all public API surface cleanly; no issues found.
packages/pq-algorithm-id/ts/tests/registry-invariants.test.ts	Good invariant coverage; the JOSE/COSE test uses a linear scan inside a loop (O(n²)) where the exported getIdentifierRecord lookup would be cleaner and more idiomatic.
packages/pq-algorithm-id/ts/tests/registry-parity.test.ts	Validates that the local registry stays in sync with pq-oid's canonical algorithm list and OID round-trips; no issues found.
packages/pq-algorithm-id/ts/tests/pq-oid-contract.test.ts	Lightweight smoke test verifying the pq-oid dependency API surface; no issues found.
packages/pq-algorithm-id/ts/package.json	Adds pq-oid runtime dependency and bun test script; tsc -b aligns with the new composite/project-reference setup.
packages/pq-algorithm-id/ts/tsconfig.json	Adds composite: true and a project reference to pq-oid/ts, enabling incremental builds; no issues found.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    consumer["Consumer\n(external package)"]
    index["index.ts\n(public API)"]
    registry["registry.ts\n• ALGORITHM_NAMES\n• IDENTIFIER_RECORDS\n• IDENTIFIER_RECORDS_BY_NAME"]
    types["types.ts\n• IdentifierRecord\n• X509ParametersPolicy\n• JoseIdentifier / CoseIdentifier\n• MappingTarget"]
    errors["errors.ts\n• AlgorithmIdentifierError\n• UnknownAlgorithmError\n• UnsupportedMappingError\n• UnknownIdentifierError"]
    pqoid["pq-oid (dep)\n• AlgorithmName type\n• OID.fromName / OID.toName\n• Algorithm.list()"]

    consumer --> index
    index --> registry
    index --> types
    index --> errors
    registry --> types
    registry --> errors
    registry --> pqoid
    types --> pqoid

Loading

_{Last reviewed commit: 3f64865}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3f6486510e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[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:35 PM UTC: @eacet merged this pull request with Graphite.