Release: audit public API compatibility and SemVer surface #103

New Issue

hugo · 2026-08-08T08:26:27Z

hugo commented

2026-08-08 08:26:27 +00:00

Objective

Perform a final mapped API and Rust quality audit before versioning the first release.

Deliverables

Compare exported Rust items with the authoritative C# catalog/mapping and resolve every exclusion.
Review naming, ownership, trait object safety, async Send/Sync guarantees, non-exhaustive enums, errors, feature gating, and accidental public dependency types.
Record intentional idiomatic differences and migration recipes.

Validation

Public API coverage is 100% with zero unexplained mappings.
SemVer/API baseline tooling records the release surface.
Downstream compile fixtures and representative ports build cleanly.

Prerequisite

All implementation and program milestones are complete with their fixed parity suites green.

Project constraints

The released implementation is entirely native Rust and must pass the explicit no-CLR/no-bridge artifact audit.
Do not weaken API coverage or semantic parity to satisfy hardening, performance, or packaging goals.
Preserve reproducible evidence, update release documentation, and keep all default/live destructive boundaries explicit.

## Objective Perform a final mapped API and Rust quality audit before versioning the first release. ## Deliverables - Compare exported Rust items with the authoritative C# catalog/mapping and resolve every exclusion. - Review naming, ownership, trait object safety, async Send/Sync guarantees, non-exhaustive enums, errors, feature gating, and accidental public dependency types. - Record intentional idiomatic differences and migration recipes. ## Validation - Public API coverage is 100% with zero unexplained mappings. - SemVer/API baseline tooling records the release surface. - Downstream compile fixtures and representative ports build cleanly. ## Prerequisite All implementation and program milestones are complete with their fixed parity suites green. ## Project constraints - The released implementation is entirely native Rust and must pass the explicit no-CLR/no-bridge artifact audit. - Do not weaken API coverage or semantic parity to satisfy hardening, performance, or packaging goals. - Preserve reproducible evidence, update release documentation, and keep all default/live destructive boundaries explicit.

hugo added this to the 12 - Hardening and release milestone 2026-08-08 08:26:27 +00:00

hugo added the enhancement label 2026-08-08 08:26:27 +00:00

hugo referenced this issue from a commit

2026-08-12 01:35:45 +00:00

Audit public API and SemVer surface (#103)

hugo commented

2026-08-12 01:36:24 +00:00

Implemented and reviewed in commit d08b59c, pushed to main.

Implementation:

Added a deterministic native Rust API and SemVer audit with a checked 0.0.1 baseline, human-readable report, and reproducible JSON evidence.
The gate compares all 3,066 mapped public types and 30,789 mapped members with generated exports; hashes normalized public declarations for 15 crates; fixes crate versions and feature sets; and rejects duplicate destinations, unexplained mappings, naming or ownership drift, async/error-model mismatches, non-Send boxed futures, non-thread-safe callbacks, and accidental dependency types in mapped or actual public Rust signatures.
Corrected seven asyncness classifications (six async functions and one boxed future) and the ExpiringCache indexer error model, made six public dyn boundaries explicitly Send + Sync, and marked seven stable public error enums non-exhaustive.
Found and removed the actual reqwest::Client public API leak. HttpCapsClient now exposes a project-owned with_native_transport policy boundary while retaining the internal native implementation; focused redirect, streaming, decompression, limits, and progress behavior remains green.
Added tests/semver-port as a standalone runnable consumer covering value, OSD, imaging, RLV, lifecycle, dyn compatibility, async Send, Send/Sync, and native HTTP construction, plus an Ubuntu-only Rust 1.97 Gitea audit workflow.
Recorded intentional Rust migration recipes for naming, ownership, async traits, events, cancellation/disposal, enums/errors, features, and external boundary types.

Validation:

Rust 1.97: formatting, deterministic mapping/shim generation, exact API coverage, 11 audit-tool tests, strict Clippy for the audit/tool/core HTTP/representative port, downstream api-compile, representative port execution, dependency audit, documentation audit, and warning-free docs for every changed public crate all pass.
Related behavior: 263 core library tests were verified; the three localhost fake-grid socket tests pass when run with socket permission. Types 48, RLV 31, Vivox 3, WebRTC 6, JPEG 2000 feature 15, OpenJPEG adapter, native HTTP validation, and native HTTP redirect/streaming tests pass with zero ignored cases.
Scoped compatibility claim: the audit tool, complete downstream API fixture, and representative port compile on rustc 1.96.0. Primary development and CI remain Rust 1.97.
No OpenSim login is relevant to this API audit, so .env credentials were not read. No live test was replaced by a skip.

Implemented and reviewed in commit d08b59c, pushed to main. Implementation: - Added a deterministic native Rust API and SemVer audit with a checked 0.0.1 baseline, human-readable report, and reproducible JSON evidence. - The gate compares all 3,066 mapped public types and 30,789 mapped members with generated exports; hashes normalized public declarations for 15 crates; fixes crate versions and feature sets; and rejects duplicate destinations, unexplained mappings, naming or ownership drift, async/error-model mismatches, non-Send boxed futures, non-thread-safe callbacks, and accidental dependency types in mapped or actual public Rust signatures. - Corrected seven asyncness classifications (six async functions and one boxed future) and the ExpiringCache indexer error model, made six public dyn boundaries explicitly Send + Sync, and marked seven stable public error enums non-exhaustive. - Found and removed the actual reqwest::Client public API leak. HttpCapsClient now exposes a project-owned with_native_transport policy boundary while retaining the internal native implementation; focused redirect, streaming, decompression, limits, and progress behavior remains green. - Added tests/semver-port as a standalone runnable consumer covering value, OSD, imaging, RLV, lifecycle, dyn compatibility, async Send, Send/Sync, and native HTTP construction, plus an Ubuntu-only Rust 1.97 Gitea audit workflow. - Recorded intentional Rust migration recipes for naming, ownership, async traits, events, cancellation/disposal, enums/errors, features, and external boundary types. Validation: - Rust 1.97: formatting, deterministic mapping/shim generation, exact API coverage, 11 audit-tool tests, strict Clippy for the audit/tool/core HTTP/representative port, downstream api-compile, representative port execution, dependency audit, documentation audit, and warning-free docs for every changed public crate all pass. - Related behavior: 263 core library tests were verified; the three localhost fake-grid socket tests pass when run with socket permission. Types 48, RLV 31, Vivox 3, WebRTC 6, JPEG 2000 feature 15, OpenJPEG adapter, native HTTP validation, and native HTTP redirect/streaming tests pass with zero ignored cases. - Scoped compatibility claim: the audit tool, complete downstream API fixture, and representative port compile on rustc 1.96.0. Primary development and CI remain Rust 1.97. - No OpenSim login is relevant to this API audit, so .env credentials were not read. No live test was replaced by a skip.

hugo closed this issue

2026-08-12 01:37:05 +00:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: hugo/MetaCrate#103