Shim infrastructure: standardize unimplemented API failures #4

New Issue

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

hugo commented

2026-08-08 08:11:52 +00:00

Objective

Provide one unmistakable failure mechanism for callable signatures while preventing placeholder implementations from returning plausible results.

Deliverables

Add a typed NotImplemented error carrying the stable C# member ID for fallible APIs.
Add an unimplemented_api! mechanism for infallible constructors, accessors, operators, and trait methods.
Define rules for async methods, streams, callbacks, and stored traits.
Require real constants, enum discriminants, flag bits, and inert public data layouts instead of fake defaults.

Validation

Unit-test error formatting and member-ID propagation.
Prove placeholder panics cannot be confused with translated expected-error assertions.
Search for zero/false/empty/nil fallback bodies in generated shims and fail the coverage gate when found.

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 Provide one unmistakable failure mechanism for callable signatures while preventing placeholder implementations from returning plausible results. ## Deliverables - Add a typed `NotImplemented` error carrying the stable C# member ID for fallible APIs. - Add an `unimplemented_api!` mechanism for infallible constructors, accessors, operators, and trait methods. - Define rules for async methods, streams, callbacks, and stored traits. - Require real constants, enum discriminants, flag bits, and inert public data layouts instead of fake defaults. ## Validation - Unit-test error formatting and member-ID propagation. - Prove placeholder panics cannot be confused with translated expected-error assertions. - Search for zero/false/empty/nil fallback bodies in generated shims and fail the coverage gate when found. ## 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:52 +00:00

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

hugo commented

2026-08-08 09:45:10 +00:00

Implemented and verified in commit d3f5e27.

Implementation:

Added libremetaverse_types::NotImplemented with stable C# member-ID storage, accessor, Display, std::error::Error, and the generic not_implemented helper for fallible synchronous and async shims.
Added libremetaverse_types::unimplemented_api! for infallible constructors, accessors, operators, and trait methods. Its visible panic marker is deliberately distinct from typed Error results.
Every one of the 13 API crates now exposes the shared failure as crate::Error; the integration fixture proves all aliases have the exact shared type.
Documented strict rules for async methods, stream factories, callback registration, stored traits, constants, enum discriminants, flag bits, and inert layouts. Streams/callbacks fail before returning or storing anything.
Removed all 1,606 generated Default derives so the structural shell cannot manufacture plausible empty values.
Extended the mapping coverage checker to reject generated Default derives, false/true/zero/empty/nil fallbacks, and any generated function body lacking NotImplemented or unimplemented_api!. Updated the generator source so the derives do not return.

Review against the issue:

Unit tests verify exact error formatting and member-ID propagation.
A panic-classification test proves the infallible placeholder panics with its unique marker while the fallible helper returns Err, so translated expected-error assertions cannot confuse the two.
A workspace integration test verifies the shared Error contract in all 13 crates.
api/MAPPING-COVERAGE.md reports zero plausible generated fallback bodies/default derives.
No production behavior or platform-specific API was added.

Passing focused tests and gates:

cargo test -p libremetaverse-types --lib
cargo test -p libremetaverse-compat-tests --test shim_failure
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

Implemented and verified in commit d3f5e27. Implementation: - Added libremetaverse_types::NotImplemented with stable C# member-ID storage, accessor, Display, std::error::Error, and the generic not_implemented helper for fallible synchronous and async shims. - Added libremetaverse_types::unimplemented_api! for infallible constructors, accessors, operators, and trait methods. Its visible panic marker is deliberately distinct from typed Error results. - Every one of the 13 API crates now exposes the shared failure as crate::Error; the integration fixture proves all aliases have the exact shared type. - Documented strict rules for async methods, stream factories, callback registration, stored traits, constants, enum discriminants, flag bits, and inert layouts. Streams/callbacks fail before returning or storing anything. - Removed all 1,606 generated Default derives so the structural shell cannot manufacture plausible empty values. - Extended the mapping coverage checker to reject generated Default derives, false/true/zero/empty/nil fallbacks, and any generated function body lacking NotImplemented or unimplemented_api!. Updated the generator source so the derives do not return. Review against the issue: - Unit tests verify exact error formatting and member-ID propagation. - A panic-classification test proves the infallible placeholder panics with its unique marker while the fallible helper returns Err, so translated expected-error assertions cannot confuse the two. - A workspace integration test verifies the shared Error contract in all 13 crates. - api/MAPPING-COVERAGE.md reports zero plausible generated fallback bodies/default derives. - No production behavior or platform-specific API was added. Passing focused tests and gates: - cargo test -p libremetaverse-types --lib - cargo test -p libremetaverse-compat-tests --test shim_failure - 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

hugo closed this issue

2026-08-08 09:45:13 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/MetaCrate#4