[HC-010] Hard cutover public C frontend API to explicit ownership and error contracts

[doublemover]

Hard cutover policy: the public frontend C API owns every contract explicitly. No borrowed result pointers, no undocumented lifetime, no silent null-argument behavior, no old ABI surface kept as a wrapper.

Source facts already established:

• native/objc3c/src/libobjc3c_frontend/api.h exposes result path pointers as const char *.
• frontend_anchor.cpp populates result paths from context-owned string storage.
• Null context, options, and result arguments return usage errors without a complete caller-owned diagnostic result.
• Public comments contain roadmap and lane text rather than a tight ABI contract.

Required public API tree:

• native/objc3c/src/libobjc3c_frontend/public/
  • objc3c_frontend.h: umbrella public include.
  • objc3c_frontend_version.h: ABI version and feature version.
  • objc3c_frontend_context.h: opaque context create and destroy.
  • objc3c_frontend_options.h: canonical compile options.
  • objc3c_frontend_result.h: owned compile result.
  • objc3c_frontend_diagnostic.h: diagnostic list API.
  • objc3c_frontend_string.h: owned string API.
  • objc3c_frontend_artifact.h: artifact path API.
  • objc3c_frontend_error.h: structured error API.
• native/objc3c/src/libobjc3c_frontend/internal/
  • context_impl.h/.cpp
  • options_bridge.h/.cpp
  • result_builder.h/.cpp
  • diagnostic_bridge.h/.cpp
  • string_arena.h/.cpp

Required API rules:

• Every returned string is an owned objc3c_frontend_string_t released by one public function.
• Every compile result is an owned objc3c_frontend_result_t released by one public function.
• Every diagnostic list is owned by its result.
• Null input returns a complete owned error result through dedicated constructors.
• Multiple contexts compile concurrently with separate state.
• One context serializes its own compile calls.
• ABI version mismatch returns a structured error.
• All old enum values and mode fields are deleted.

Required work:

• Replace raw const char * result fields with owned API accessors.
• Replace public lane and roadmap comments with concise ABI contract comments.
• Add API tests for ownership, null arguments, concurrent contexts, result destruction, diagnostic retrieval, and ABI version mismatch.
• Update the CLI runner to consume the new API only.
• Delete old public header aliases and old result structs.

Maximum effort shared hoist pass:

• Hoist string ownership to objc3c_frontend_string.*.
• Hoist diagnostic conversion to internal/diagnostic_bridge.*.
• Hoist artifact path conversion to public/objc3c_frontend_artifact.* and internal/result_builder.*.
• Hoist context state construction to internal/context_impl.*.

Acceptance criteria:

• Public headers contain ABI contracts only.
• No public result struct exposes raw context-owned pointers.
• rg "const char \*.*path|compatibility_mode|lane|roadmap|reserved future" native/objc3c/src/libobjc3c_frontend returns no public ABI surface.
• C API tests run under normal user privileges and pass.

[doublemover]

Current checkout evaluation after the hard-cutover integration commits: PARTIAL, keep open.

Landed work:

• The public C frontend API has moved toward explicit result/string/diagnostic ownership contracts.
• Native build, command-surface validation, and fast validation passed after the integration checkpoint.

Remaining blockers from the current checkout:

• The public/frontend surface still contains lane-E implementation comments in native/objc3c/src/libobjc3c_frontend/frontend_anchor_parts/frontend_anchor_part_001.inc.
• Public ABI headers still expose raw const char * inputs and string views. Some of those may be legitimate input/version surfaces, but closure needs a deliberate ownership classification rather than broad raw-pointer residue.
• The public/internal split still needs a final audit proving result, string, diagnostic, and artifact lifetimes are explicit at every boundary.

Do not close until the public ABI surface is free of lane/roadmap wording and the raw C string usage is intentionally documented or replaced.

[doublemover]

Public C API checkpoint (May 6, 2026): landed and pushed 7130e36f3 (HC-010 clarify public C API ownership).

Completed in this checkpoint:

• Removed stale lane/milestone roadmap comments from the frontend anchor surface.
• Made objc3c_frontend_string_t::data immutable as const char *; release remains owned by objc3c_frontend_string_release.
• Clarified borrowed option strings, result-owned strings, borrowed result accessors, and static version strings in the public C API headers.
• Added smoke coverage for the no-lane/no-roadmap public surface and immutable owned-string release contract.

Validation evidence:

• pytest tests/tooling/test_objc3c_c_api_smoke.py PASS: 5 passed, 2 skipped by compiler availability checks.
• pytest tests/tooling/test_objc3c_frontend_library_entrypoint_extraction.py PASS: 3 passed.
• python -m scripts.source_hygiene PASS, active_findings 0.
• git diff --cached --check PASS.

Current closure status: still open. The remaining #8141 audit still includes raw borrowed compile-option path inputs (input_path, clang_path, llc_path) and the broader result/API decomposition is not complete.

[doublemover]

Pushed checkpoint 7b2c532. Public C API option/string ownership wording and smoke coverage were tightened in native/objc3c/src/libobjc3c_frontend and tests/tooling. Validation evidence: python -m pytest tests/tooling/test_objc3c_c_api_smoke.py tests/tooling/test_objc3c_frontend_library_entrypoint_extraction.py passed with 8 passed and 2 skipped; git diff --check passed. #8141 remains open pending final public C API contract audit and any remaining owned-result/string/diagnostic/artifact closure checks.