Add primitive to generate persistent ID mappings

[matthewhorridge]

Summary

We need a new primitive to generate standardized IDs while persisting a lookup table so future runs can reuse the same mappings.

Motivation

Current primitives can only do deterministic transformations (e.g., regex padding). When we need to avoid ID clashes across sources while preserving referential consistency over time, we need a persistent mapping from source IDs to new standardized IDs.

Proposed behavior

• Input: source ID values (string or numeric).
• Output: standardized ID values, generated when first seen.
• Persist a mapping file (e.g., CSV/JSON) that records source -> standardized ID.
• On subsequent runs, reuse the existing mapping for previously seen IDs and append new entries for new IDs.
• Support configurable prefixes (e.g., PU, PR) and zero-padding/width.

Example use case

Harmonize RADx-UP and RADx-rad record_id values into a single namespace without collisions, while preserving stable IDs across repeated harmonizations.

Suggested API shape

A primitive like:

GenerateId(prefix="PU", width=7, mapping_path="mappings/ids.csv")

Files

• src/harmonization_framework/primitives/*
• rule serialization should support this new operation.