hakorune/docs/development/runtime/C_CORE_ABI.md

# C Core ABI (Design Stage) — Phase 22.2

Status: design-stage shim; defaults OFF; behavior unchanged.

Purpose
- Define a minimal, stable C ABI boundary to enable future replacement of selected Rust runtime paths when Hakorune is compiled to native EXE via LLVM.
- Keep Rust path authoritative while stubbing C calls behind env+feature gates; ON/OFF parity must hold.

Conventions
- Encoding: UTF‑8, null-terminated (const char*). No ownership transfer.
- Return: `int` (0 = success; negative values reserved for future detailed errors).
- Threading: functions must be reentrant; stateful access goes via (type_id, instance_id).

Functions (initial)
- `int ny_core_probe_invoke(const char* target, const char* method, int32_t argc)`
  - No-op probe for diagnostics; safe to call for any target/method pair.
- `int ny_core_map_set(int32_t type_id, uint32_t instance_id, const char* key, const char* val)`
  - Design stub for MapBox.set. Current implementation is no-op; Rust path performs the actual mutation.

Gates & Features
- Build: `cargo build --release -p nyash-rust --features c-core`
- Env:
  - `HAKO_C_CORE_ENABLE=1` — enable c-core probe routing
  - `HAKO_C_CORE_TARGETS=MapBox.set,ArrayBox.push` — limit targets (default: MapBox.set)
  - Tags: `[c-core:invoke:<Box>.<method>]`

Call Sites (Rust)
- PluginLoaderV2 (enabled): `src/runtime/plugin_loader_v2/enabled/ffi_bridge.rs`
  - When gated ON + targeted, call C shim then continue with the original Rust path (parity preserved).

Validation
- Parity canaries compare ON/OFF outputs (and rc) for MapBox.set; later for ArrayBox.push/get/size.
- Failure/unavailable paths must fall back immediately to the Rust path.

Roadmap
- Expand ArrayBox (push → get → size) with the same staged approach.
- Formalize error codes and minimal state API only after parity is stable.
-												Phase 22.1 WIP: SSOT resolver + TLV infrastructure + Hako MIR builder setup

Setup infrastructure for Phase 22.1 (TLV C shim & Resolver SSOT):

Core changes:
- Add nyash_tlv, nyash_c_core, nyash_kernel_min_c crates (opt-in)
- Implement SSOT resolver bridge (src/using/ssot_bridge.rs)
- Add HAKO_USING_SSOT=1 / HAKO_USING_SSOT_HAKO=1 env support
- Add HAKO_TLV_SHIM=1 infrastructure (requires --features tlv-shim)

MIR builder improvements:
- Fix using/alias consistency in Hako MIR builder
- Add hako.mir.builder.internal.{prog_scan,pattern_util} to nyash.toml
- Normalize LLVM extern calls: nyash.console.* → nyash_console_*

Smoke tests:
- Add phase2211 tests (using_ssot_hako_parity_canary_vm.sh)
- Add phase2220, phase2230, phase2231 test structure
- Add phase2100 S3 backend selector tests
- Improve test_runner.sh with quiet/timeout controls

Documentation:
- Add docs/ENV_VARS.md (Phase 22.1 env vars reference)
- Add docs/development/runtime/C_CORE_ABI.md
- Update de-rust-roadmap.md with Phase 22.x details

Tools:
- Add tools/hakorune_emit_mir.sh (Hako-first MIR emission wrapper)
- Add tools/tlv_roundtrip_smoke.sh placeholder
- Improve ny_mir_builder.sh with better backend selection

Known issues (to be fixed):
- Parser infinite loop in static method parameter parsing
- Stage-B output contamination with "RC: 0" (needs NYASH_JSON_ONLY=1)
- phase2211/using_ssot_hako_parity_canary_vm.sh fork bomb (needs recursion guard)

Next steps: Fix parser infinite loop + Stage-B quiet mode for green tests

											
										
										
											2025-11-09 15:11:18 +09:00
+								# C Core ABI (Design Stage) — Phase 22.2
 								Status: design-stage shim; defaults OFF; behavior unchanged.
 								Purpose
 								- Define a minimal, stable C ABI boundary to enable future replacement of selected Rust runtime paths when Hakorune is compiled to native EXE via LLVM.
 								- Keep Rust path authoritative while stubbing C calls behind env+feature gates; ON/OFF parity must hold.
 								Conventions
 								- Encoding: UTF‑8, null-terminated (const char*). No ownership transfer.
 								- Return: `int` (0 = success; negative values reserved for future detailed errors).
 								- Threading: functions must be reentrant; stateful access goes via (type_id, instance_id).
 								Functions (initial)
 								- `int ny_core_probe_invoke(const char* target, const char* method, int32_t argc)`
 								  - No-op probe for diagnostics; safe to call for any target/method pair.
 								- `int ny_core_map_set(int32_t type_id, uint32_t instance_id, const char* key, const char* val)`
 								  - Design stub for MapBox.set. Current implementation is no-op; Rust path performs the actual mutation.
 								Gates & Features
 								- Build: `cargo build --release -p nyash-rust --features c-core`
 								- Env:
 								  - `HAKO_C_CORE_ENABLE=1` — enable c-core probe routing
 								  - `HAKO_C_CORE_TARGETS=MapBox.set,ArrayBox.push` — limit targets (default: MapBox.set)
 								  - Tags: `[c-core:invoke:<Box>.<method>]`
 								Call Sites (Rust)
 								- PluginLoaderV2 (enabled): `src/runtime/plugin_loader_v2/enabled/ffi_bridge.rs`
 								  - When gated ON + targeted, call C shim then continue with the original Rust path (parity preserved).
 								Validation
 								- Parity canaries compare ON/OFF outputs (and rc) for MapBox.set; later for ArrayBox.push/get/size.
 								- Failure/unavailable paths must fall back immediately to the Rust path.
 								Roadmap
 								- Expand ArrayBox (push → get → size) with the same staged approach.
 								- Formalize error codes and minimal state API only after parity is stable.