API mapping: define the complete C# to Rust signature schema #3

New Issue

hugo · 2026-08-08T08:11:51Z

hugo commented

2026-08-08 08:11:51 +00:00

Objective

Define the reviewed mapping record and compatibility rules used to translate every C# public member into an idiomatic but recognizable Rust signature.

Deliverables

Create api/RUST-MAPPING.tsv or an equivalent structured format keyed by stable C# documentation ID.
Record Rust crate, module, item path, full signature, ownership, asyncness, error model, overload decision, and mapping status.
Specify mappings for properties, indexers, events, delegates, optional/ref/out parameters, inheritance, generics, nullability, operators, flags, and extensible enums.
Add schema validation and human-readable coverage reporting.

Validation

Reject duplicate C# IDs, duplicate Rust destinations, unresolved referenced types, invalid status values, and stale catalog entries.
Demonstrate representative mappings from every assembly.
Document migration naming rules in RUSTREWRITE.md.

Prerequisite

Stage 0 project setup is complete. Do not implement production behavior in this milestone.

Project constraints

Implement the public surface in native Rust only; no CLR hosting, FFI bridge, subprocess, RPC, or C# fallback.
Preserve recognizable API concepts while applying the documented Rust mapping rules.
Do not weaken parity requirements or add functional behavior outside this issue.
Update the API mapping, coverage report, public docs, and relevant handover status in the same change.

## Objective Define the reviewed mapping record and compatibility rules used to translate every C# public member into an idiomatic but recognizable Rust signature. ## Deliverables - Create `api/RUST-MAPPING.tsv` or an equivalent structured format keyed by stable C# documentation ID. - Record Rust crate, module, item path, full signature, ownership, asyncness, error model, overload decision, and mapping status. - Specify mappings for properties, indexers, events, delegates, optional/ref/out parameters, inheritance, generics, nullability, operators, flags, and extensible enums. - Add schema validation and human-readable coverage reporting. ## Validation - Reject duplicate C# IDs, duplicate Rust destinations, unresolved referenced types, invalid status values, and stale catalog entries. - Demonstrate representative mappings from every assembly. - Document migration naming rules in `RUSTREWRITE.md`. ## Prerequisite Stage 0 project setup is complete. Do not implement production behavior in this milestone. ## Project constraints - Implement the public surface in native Rust only; no CLR hosting, FFI bridge, subprocess, RPC, or C# fallback. - Preserve recognizable API concepts while applying the documented Rust mapping rules. - Do not weaken parity requirements or add functional behavior outside this issue. - Update the API mapping, coverage report, public docs, and relevant handover status in the same change.

hugo added this to the 02 - Full public API signature shim milestone 2026-08-08 08:11:51 +00:00

hugo added the enhancement label 2026-08-08 08:11:51 +00:00

hugo commented

2026-08-08 09:37:11 +00:00

Implemented and verified in commit 3179d7a.

Implementation:

Added api/RUST-MAPPING.tsv with one reviewed row for all 30,789 compiled public members. Each row records the stable C# ID/signature, Rust crate/module/item path and full signature, ownership, asyncness, error model, overload decision, mapping kind, and status.
Added api/RUST-TYPES.tsv covering all 3,066 public types, all 142 external signature types, and the two support traits referenced by public inheritance metadata. External library objects map to project-owned cross-platform boundaries; external member surfaces are not copied.
Added the standard-library-only tools/generate_rust_mapping.py generator/checker and api/MAPPING-COVERAGE.md. Validation rejects duplicate C# IDs, duplicate member destinations, stale or missing catalog IDs, unresolved referenced types and generic bounds, invalid statuses, missing assembly representatives, malformed signatures, and macOS-specific targets.
Documented properties, indexers, events, delegates, optional/ref/out/in parameters, nullability, inheritance, generics, operators, flags, extensible enums, overload naming, and cross-platform replacement rules in RUSTREWRITE.md and api/README.md.

Review against the issue:

Public types: 3,066/3,066; public members: 30,789/30,789; external types: 142/142.
13/13 assemblies have representative mappings.
5,090 properties, 11 indexers, 268 events, 40 delegates, 46 flags enums, 470 optional parameters, 6,144 ref parameters, 555 out parameters, 360 async signatures, and 7,137 renamed overloads are covered.
80 CLR delegate BeginInvoke/EndInvoke members remain explicit intentional differences because native Rust callbacks replace the CLR asynchronous programming model.
Adversarial checks confirmed duplicate IDs, duplicate destinations, stale rows, invalid status values, and unresolved types are rejected.

Passing gates:

python3 tools/generate_rust_mapping.py --check
git diff --check
cargo fmt --all -- --check
cargo check --workspace --all-targets
cargo test --workspace --no-run
cargo clippy --workspace --all-targets --all-features -- -D warnings
cargo doc --workspace --no-deps

No production behavior, CLR dependency, FFI bridge, subprocess, RPC, or C# fallback was added.

Implemented and verified in commit 3179d7a. Implementation: - Added api/RUST-MAPPING.tsv with one reviewed row for all 30,789 compiled public members. Each row records the stable C# ID/signature, Rust crate/module/item path and full signature, ownership, asyncness, error model, overload decision, mapping kind, and status. - Added api/RUST-TYPES.tsv covering all 3,066 public types, all 142 external signature types, and the two support traits referenced by public inheritance metadata. External library objects map to project-owned cross-platform boundaries; external member surfaces are not copied. - Added the standard-library-only tools/generate_rust_mapping.py generator/checker and api/MAPPING-COVERAGE.md. Validation rejects duplicate C# IDs, duplicate member destinations, stale or missing catalog IDs, unresolved referenced types and generic bounds, invalid statuses, missing assembly representatives, malformed signatures, and macOS-specific targets. - Documented properties, indexers, events, delegates, optional/ref/out/in parameters, nullability, inheritance, generics, operators, flags, extensible enums, overload naming, and cross-platform replacement rules in RUSTREWRITE.md and api/README.md. Review against the issue: - Public types: 3,066/3,066; public members: 30,789/30,789; external types: 142/142. - 13/13 assemblies have representative mappings. - 5,090 properties, 11 indexers, 268 events, 40 delegates, 46 flags enums, 470 optional parameters, 6,144 ref parameters, 555 out parameters, 360 async signatures, and 7,137 renamed overloads are covered. - 80 CLR delegate BeginInvoke/EndInvoke members remain explicit intentional differences because native Rust callbacks replace the CLR asynchronous programming model. - Adversarial checks confirmed duplicate IDs, duplicate destinations, stale rows, invalid status values, and unresolved types are rejected. Passing gates: - python3 tools/generate_rust_mapping.py --check - git diff --check - cargo fmt --all -- --check - cargo check --workspace --all-targets - cargo test --workspace --no-run - cargo clippy --workspace --all-targets --all-features -- -D warnings - cargo doc --workspace --no-deps No production behavior, CLR dependency, FFI bridge, subprocess, RPC, or C# fallback was added.

hugo closed this issue

2026-08-08 09:37:14 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/MetaCrate#3