Core-13 pure: add CI workflows, VM e2e tests, LLVM parity bridge (minimal); do not touch private docs

2025-09-07 07:28:53 +09:00
parent 07350c5dd9
commit d62114c705
383 changed files with 15221 additions and 382 deletions
--- a/docs/private/reference/jit/jit_events_json_v0_1.md
+++ b/docs/private/reference/jit/jit_events_json_v0_1.md
@ -0,0 +1,52 @@
+# JIT Events JSON (v0.1)
+
+最小のイベントJSONスキーマ。観測の足場として、値は安定キーのみを出力します。
+
+- 出力形態: 1行 = 1 JSON（JSONL）
+- 出力先: 標準出力 or `NYASH_JIT_EVENTS_PATH` で指定したファイル
+- phase分離:
+  - compile: `phase: "lower"`（明示opt-in: `NYASH_JIT_EVENTS_COMPILE=1`）
+  - runtime: `phase: "execute"`（既定ON可: `NYASH_JIT_EVENTS=1` または `NYASH_JIT_EVENTS_RUNTIME=1`）
+
+## フィールド（必須）
+- kind: 文字列（例: "hostcall"）
+- function: 文字列（現状は "<jit>" で固定）
+- phase: 文字列（"lower" | "execute"）
+- id: シンボル名（例: "nyash.map.get_hh"）
+- decision: 文字列（"allow" | "fallback"）
+- reason: 文字列（"sig_ok" | "receiver_not_param" | "policy_denied_mutating" | "sig_mismatch" など）
+- argc: 数値（観測引数数）
+- arg_types: 文字列配列（例: ["Handle","I64"]）
+
+任意フィールド（存在時のみ）
+- handle: 数値（JITハンドル）
+- ms: 数値（処理時間ミリ秒）
+
+## 出力例
+
+compile（lower）:
+```json
+{"kind":"hostcall","function":"<jit>","id":"nyash.map.get_hh","decision":"allow","reason":"sig_ok","argc":2,"arg_types":["Handle","Handle"],"phase":"lower"}
+```
+
+runtime（execute）:
+```json
+{"kind":"hostcall","function":"<jit>","id":"nyash.array.push_h","decision":"fallback","reason":"policy_denied_mutating","argc":2,"arg_types":["Handle","I64"],"phase":"execute"}
+```
+
+trap（execute 中の失敗）:
+```json
+{"kind":"trap","function":"<jit>","reason":"jit_execute_failed","ms":0,"phase":"execute"}
+```
+
+## 環境変数（抜粋）
+- NYASH_JIT_EVENTS=1: 既定のruntime出力
+- NYASH_JIT_EVENTS_COMPILE=1: compile（lower）出力
+- NYASH_JIT_EVENTS_RUNTIME=1: runtime出力
+- NYASH_JIT_EVENTS_PATH=path.jsonl: ファイルに追記
+- NYASH_JIT_THRESHOLD（未設定時）: 観測ONで自動的に1が補われます（Runner/DebugConfigBoxが補助）
+
+## 推奨の最小運用
+- 現象確認: `NYASH_JIT_EVENTS=1`（runtimeのみ）
+- 解析時のみcompile出力: `NYASH_JIT_EVENTS_COMPILE=1 NYASH_JIT_EVENTS_PATH=events.jsonl`
+- HostCall系の例では `NYASH_JIT_HOSTCALL=1` を明示
--- a/docs/private/reference/jit/jit_stats_json_v1.md
+++ b/docs/private/reference/jit/jit_stats_json_v1.md
@ -0,0 +1,76 @@
+JIT Stats JSON Schema — Version 1
+=================================
+
+This document describes the fields emitted in the JIT statistics JSON outputs (version=1).
+
+Sources
+- Unified JIT stats (VM-side): printed when `NYASH_JIT_STATS_JSON=1` (or CLI equivalent)
+- Box API: `new JitStatsBox().toJson()` returns a compact JSON, `summary()` returns a pretty JSON summary (via VM dispatch)
+
+Version
+- `version`: number — Schema version (currently `1`)
+
+Unified JIT Stats (JSON)
+- `version`: number — Schema version (1)
+- `sites`: number — Number of JIT call sites observed
+- `compiled`: number — Count of functions compiled by the JIT
+- `hits`: number — Sum of entries across all functions (hotness hits)
+- `exec_ok`: number — Count of successful JIT executions
+- `trap`: number — Count of JIT executions that trapped and fell back to VM
+- `fallback_rate`: number — Ratio `trap / (exec_ok + trap)` (0 when denominator is 0)
+- `handles`: number — Current number of live JIT handles in the registry
+- `abi_mode`: string — `"i64_bool"` or `"b1_bool"` (when toolchain supports b1)
+- `abi_b1_enabled`: boolean — Whether b1 ABI is requested by config
+- `abi_b1_supported`: boolean — Whether current toolchain supports b1 in signatures
+- `b1_norm_count`: number — Count of b1 normalizations (e.g., i64!=0 to b1)
+- `ret_bool_hint_count`: number — Count of functions lowered with return-bool hint
+- `phi_total_slots`: number — Total PHI slots encountered (always-on, LowerCore-based)
+- `phi_b1_slots`: number — PHI slots classified as boolean (heuristics)
+- `top5`: array of objects — Top hot functions
+  - `name`: string
+  - `hits`: number
+  - `compiled`: boolean
+  - `handle`: number (0 when not compiled)
+
+Compact Box JSON — `JitStatsBox.toJson()`
+- `version`: number — Schema version (1)
+- `abi_mode`: string — Current ABI mode for booleans (see above)
+- `abi_b1_enabled`: boolean — Whether b1 ABI is requested by config
+- `abi_b1_supported`: boolean — Whether current toolchain supports b1 in signatures
+- `b1_norm_count`: number — b1 normalizations count
+- `ret_bool_hint_count`: number — return-bool hint count
+- `phi_total_slots`: number — Total PHI slots (accumulated)
+- `phi_b1_slots`: number — Boolean PHI slots (accumulated)
+
+Summary Box JSON — `JitStatsBox.summary()`
+- Pretty-printed JSON containing:
+  - All fields from `toJson()`
+  - `top5`: same structure as unified stats
+
+Notes
+- Counters reflect process-lifetime totals (reset only on process start).
+- `phi_*` counters are accumulated per LowerCore invocation (function lower), independent of dump flags.
+- `abi_mode` switches to `b1_bool` when toolchain support is detected and b1 ABI is enabled.
+
+Examples
+```
+{
+  "version": 1,
+  "sites": 1,
+  "compiled": 0,
+  "hits": 1,
+  "exec_ok": 0,
+  "trap": 0,
+  "fallback_rate": 0.0,
+  "handles": 0,
+  "abi_mode": "i64_bool",
+  "abi_b1_enabled": false,
+  "abi_b1_supported": false,
+  "b1_norm_count": 0,
+  "ret_bool_hint_count": 0,
+  "phi_total_slots": 2,
+  "phi_b1_slots": 1,
+  "top5": [ { "name": "main", "hits": 1, "compiled": false, "handle": 0 } ]
+}
+```
+