# goesm architecture

goesm は、現在の Go toolchain を frontend とし、本物の Go package と Go semantics を、Go package ごとに 1 つの ESM としてそのまま build できる TypeScript file の tree (と TypeScript の runtime) へ lowering する基盤の PoC です。この tree は任意の ESM bundler (Vite、Rolldown、esbuild) や TypeScript を扱える runtime (Bun、type stripping を使う Node.js) が読み込みます。`goesm build` は便宜的にそれを esbuild で bundle します。
「Go っぽい言語を JavaScript に変換する」ものではありません。独自 syntax・独自 module system・独自 type system は持ちません。

## 1. Pipeline と責務

```
.go / go.mod / go.sum / go.work
        │  go command + golang.org/x/tools/go/packages   (internal/loader)
        ▼
parse / package load / type check  ── go/parser, go/types (Go が言語仕様の authority)
        │
        ▼
Go semantic lowering                ── internal/lower   (goesm の本体)
        │
        ▼
TypeScript tree + @goesm/runtime    ── goesm emit-ts: <dir>/<import path>.ts, <dir>/@goesm/runtime/*.ts
        │  任意の ESM bundler (Vite / Rolldown / esbuild) または TS を扱える runtime (Bun, Node.js)
        │  goesm build: esbuild Go API (internal/build)、便宜的なもの
        ▼
JavaScript ESM (+ goesm build では .go を指す source map)
```

| layer | 担当 | 担当しないこと |
|---|---|---|
| Go toolchain (`go list` / go/packages / go/types) | module・package 解決、go.mod / go.sum / go.work / GOPROXY、build constraints、parse、type check、定数畳み込み、init order | — |
| goesm (`internal/lower`) | Go の意味論を TS + runtime 呼び出しへ写像、type metadata、blocking 解析、source map の第一段 (TS→Go) | parse、型検査、module 解決、JS printing |
| `@goesm/runtime` | JS にない Go 意味論 (slice / map / pointer / interface / panic / defer / channel / select / 整数 wrap / 型 descriptor) | 型の判定 (すべて compile 時に go/types が済ませている) |
| host の bundler / runtime (`goesm build` では esbuild の Go API) | TS syntax stripping、JS printer、target lowering、bundling、tree shaking、minify、code splitting、最終 source map | Go 意味論の判断 |

## 2. Repository 構成

```
cmd/goesm/            CLI: goesm build / goesm emit-ts
internal/loader/      go/packages による frontend と診断 (go list / go/parser / go/types の layer 付き)
internal/natives/     goesm が持つ stdlib package の Go source 置換 (runtime、reflect、internal/reflectlite、sync、syscall/js)
internal/lower/       typed AST → TypeScript lowering
  program.go          whole-program 解析 (address-taken 変数、blocking 解析)
  emit.go decl.go     package = 1 TS module、型 descriptor、struct class、method table
  func.go stmt.go     関数本体・文 (defer、switch、select、range、range-over-func ...)
  expr.go types.go    式、変換、演算子、型 descriptor / zero value
  writer.go           位置 marker 付き code writer (source location を codegen 中に保持)
internal/sourcemap/   TS→Go の Source Map v3 builder
internal/build/       pipeline 結合、モジュールキャッシュ、TS tree の書き出し、esbuild Go API 呼び出し (goesm build) と split 用 resolver
runtime/              @goesm/runtime (TypeScript)。goesm binary に embed し、<dir>/@goesm/runtime/ に書き出す
test/                 end-to-end テスト (Node.js 実行、native Go との golden 比較)
testdata/             fixture module (普通の Go module。gofmt / go vet / go test がそのまま通る)
docs/                 GopherJS 比較、生成物の実例
```

## 3. Frontend: Go toolchain をそのまま使う

* `golang.org/x/tools/go/packages` で `NeedSyntax|NeedTypes|NeedTypesInfo|NeedDeps` を読み込みます。module 解決・`go.work`・`GOPROXY`・`go.sum` 検証はすべて go command の仕事で、goesm は一切再実装していません。
* 入力は Go の package pattern (`./main`, `example.com/app/...`)。`import "./foo.go"` のような独自 import はありません。
* `-toolexec prog` (`build` / `emit-ts`、または `GOFLAGS` の `-toolexec`) で、compile が見る source を書き換える tool (OpenTelemetry の compile-time instrumentation など、[docs/otelc.ja.md](https://goesm.dev/ja/reference/otelc.md)) を組み込めます。goesm は target 向けに `go list -deps -export` を `prog` を toolexec program として実行し、compiler の代わりに goesm 自身の recorder を置きます (`internal/toolexec`)。recorder は各 compile の Go file を記録し、build の一時 directory にあるものは内容を保存してから compiler を実行します。package 自身の file と異なる記録済み file が overlay になります。go command は `GOMODCACHE` 以下 (依存 module と、`GOTOOLCHAIN` で download した toolchain の stdlib) の overlay を拒否するため、それらの file については、go command にはディスク上のままの package を list させ、goesm が overlay の file を代わりに parse し、追加 file を package に加え、追加された import を package path で解決して、go/packages と同じ方法で自ら型検査します (`loader/check.go`)。go command は cache 済みの compile では tool を実行しないため、記録は compile の action ID ごとに user cache directory に保存し、goesm は compiler が報告する version に印を付けて、これらの compile を通常の build とは別に cache させます。
* `-overlay file` (`build` / `emit-ts`) は go command 自身の overlay 形式 (`go build -overlay`, `packages.Config.Overlay`) を受け取ります。絶対パスでディスク上のファイルを置き換え・追加でき、存在しないディレクトリにも置けます。Go を別のファイルに埋め込むホスト (Vue SFC 向けの gosfc) は `//line` directive 付きの Go ファイルを生成してこの経路で渡します。位置は常に `//line` を反映する `token.FileSet.Position` 経由で取るため、go/types の診断と goesm の source map はホストのファイル (`Summary.vue:17:21`) を指します。
* target の build constraints は `GOOS=js GOARCH=wasm` (既存 port のうち JS host に最も近いもの)。`int` は 64-bit として型検査されます。
* **Go version を固定しない**: go/parser と go/types は goesm binary にリンクされるため、goesm が理解できる最新 syntax は「goesm を build した toolchain」の syntax です。そこで goesm は `go tool goesm` (go.mod の `tool` directive) や `go run` で、その module が選ぶ toolchain により都度 build される前提にしています。toolchain の方が新しい場合は `loader.VersionHint` がそれを診断します。この PoC 自体 Go 1.27 で build し、Go 1.27 の generic methods を fixture で通しています (`testdata/semantics/generics`)。

## 4. AST から直接 lowering するか、x/tools/go/ssa か

**判断: typed AST (go/ast + go/types) から直接 lowering する。** SSA は採用しません。

| 基準 | typed AST | go/ssa |
|---|---|---|
| 1. 最新 Go syntax への追従 | go/types が受理すれば即使える。新構文は lowering 1 箇所の追加で済む | x/tools の SSA builder 側の対応待ちが発生する (generic methods、range-over-func 等は SSA 側の実装が先に必要) |
| 2. Go semantics の正確性 | 評価順・defer・named result 等は lowering で明示的に扱う必要がある | SSA は評価順を明示化済みで有利 |
| 3. 実装量 | 構造化制御フローを JS の制御構文へそのまま写せる | basic block + phi を JS に戻す relooper/stackifier が必要で大きい |
| 4. source location | AST node の位置をそのまま marker として埋め込める | 命令単位の位置は粗く、構造化後に再対応が必要 |
| 5. runtime semantics の将来実装 | async/await、try/finally、label 付き break が JS の構造に素直に乗る | goroutine の再開点などは state machine 化が前提になる |

2. の不利は、評価順に関わる箇所 (多値代入、defer の引数評価、range 式の一回評価など) を lowering 側で temp に落とすことで補っています。GopherJS も同じく typed AST ベースです。

## 5. Lowering 方式

* **1 Go package = 1 TypeScript module = 1 ES module**。`goesm emit-ts -o <dir>` は Go package `p` の module を `<dir>/<p>.ts` (`example.com/app/main.ts`、`strings.ts`、`internal/bytealg.ts`) に、runtime を `<dir>/@goesm/runtime/index.ts` に書き出します。natives は `natives.ts`、その他の runtime file も同じ directory に並びます。この tree が goesm の主な出力です。
  * module 同士は `.ts` で終わる相対 specifier で import し合います。Go の import は `import * as mathx from "./mathx.ts"`、runtime は `import * as $rt from "../../@goesm/runtime/index.ts"` になります (`internal/bytealg.ts` では `import * as $natives from "../@goesm/runtime/natives.ts"`)。Go の import path は `@` で始まらないので、runtime が package と衝突することはありません。resolver は不要で、TypeScript (`allowImportingTsExtensions`)、Vite、Rolldown、esbuild、Bun、Node.js の type stripping がこの specifier をそのまま解決します。
  * `goesm build` (既定) は esbuild がこの tree を plugin なしで 1 bundle (`dist/main.js`) にまとめます。
  * `goesm build -split` は package ごとに `dist/example.com/app/mathx.js` を出し、runtime は `dist/@goesm/runtime/index.js` と `dist/@goesm/runtime/natives.js` になります。小さな内蔵 resolver が他の entry point (package の module と runtime) の import を external にして `.ts` を `.js` に書き換えるので、Go の import は `import * as mathx from "./mathx.js"` という ESM dependency として残ります。
* **JS 呼び出し ABI。** JavaScript は、entry package (ビルドの起点の package) の export された関数とメソッドを wrapper (`internal/lower/jsexport.go`) 経由で呼びます。wrapper は宣言の Go の型に従い、`//goesm:import` と同じ変換表 (`runtime/src/jsabi.ts`) を逆向きに使って、引数を JavaScript から、戻り値を JavaScript へ変換します。文字列は JS の文字列、スライスは配列、構造体はプレーンオブジェクトになり、最後の `error` は `GoError` として投げます。メソッドを持つ構造体型へのポインタ、空でないインターフェース、チャネルは Go の値のままハンドルとして渡ります。entry package の構造体クラスのメソッドも wrapper を呼びます。数値は変換せずに渡すので、数値だけの呼び出しは JS の関数呼び出しと同じコストです。文字列の変換は inline で行います。Go のコードは wrapper ではなく関数そのものを呼び、module の `$goesm` 表は関数そのものを型記述子と一緒に並べます。他の package の module は Go の表現のまま export します。利用者向けの説明は [docs/js-exports.ja.md](https://goesm.dev/ja/reference/js-exports.md) にあります。
* 名前: Go の識別子は `$` を含まないので、goesm が導入する名前はすべて `$` を含みます (`User$type`, `User$Adult`, `$rt`, `$t3`)。1 つの関数宣言内の Go object には一意な JS 名を振るため、Go の shadowing を JS の scope 規則で再現する必要がありません。
* 定数式は go/types が評価した値をそのまま出力します (iota、型付き定数、`unsafe.Sizeof` 等)。
* package 変数は `types.Info.InitOrder` の順で初期化し、次に `init()`、entry package に `func main` があれば最後に `main()` を実行します。初期化式に副作用のない変数 (定数、複合リテラルとそのアドレス、関数リテラル、他の package-level の変数と関数の組み合わせ) は初期化式を `/* @__PURE__ */` の式として宣言し、defined type は `$rt.defined` (module が `$rt.flushTypes()` を呼んだときに underlying type と method を設定する callback を持つ pure な呼び出し) で宣言します。これで bundler は使われない表や型 (method ごと) を落とします。`strings.ToUpper` だけを使う library の bundle は 363 KB から 88 KB (gzip で 27 KB) に、`fmt` の hello world は gzip で 222 KB から 132 KB になります。さらに副作用の解析 (`internal/lower/effects.go`) が、値の計算以外に効果を持たない初期化式を呼び出しの先まで調べて見つけます。自分で確保したメモリや局所変数への書き込みは効果に数えません。そうした初期化式も pure な式として宣言します。package 変数への代入しかしない `init` 関数は、到達可能なコード (`internal/lower/reach.go`) がそのいずれかの変数を使う場合に限り実行します。到達可能なコードが使わない副作用のない初期化式は出力しません。バンドラーを通さずに package の TypeScript を実行すると、その式が評価されるためです。Connect のサービスを 1 つ提供する Cloudflare Worker では、net/http の TLS の既定値、crypto/tls の表、nistec の P-256 の表、x/text の正規化の表が TLS、X.509、楕円曲線を残していました。これらの解析と、後述の block 解析を到達可能なコードに限ることで、bundle は 4.5 MB (gzip で 1.18 MB) から 1.9 MB (gzip で 457 KB) になりました。
* 生成 TS は型を持ちます。Go の型は go/types が決めており、TS の型はそれに従います。tree 全体 (生成 module と runtime) は strict mode に `verbatimModuleSyntax` と `erasableSyntaxOnly` を加えた tsc で型検査が通るので、type stripping を行う runtime (Node.js 22.18 以上、Bun) でもそのまま動きます。`TestTSC` は CI の必須 check です。fixture と examples を、exported な Go API を使う consumer と一緒に型検査します。consumer の `@ts-expect-error` は、exported API が Go の型を持つこと (`Total(items: $rt.S<Item>): number`、block する関数は `Promise<number>` を返す) を確認します。exported な signature と struct の class は正確に型付けし、内部の一時変数や wrapper は `any` です。型 parameter は制約から型付けします (core type、または `number` / `string`)。native Go との結果比較は引き続き意味論の gate です。

### 値の表現

| Go | JS 表現 | 備考 |
|---|---|---|
| bool, float64 | boolean, number | |
| float32 | number (`Math.fround` で丸め) | |
| int8/16/32, uint8/16/32 | number、演算ごとに wrap (`\|0`, `>>>0`, `<<24>>24`, `Math.imul`) | 正確 |
| int64, uint64 | bigint。演算のたびに `BigInt.asIntN` / `asUintN(64, ...)` で wrap | 正確 |
| int, uint, uintptr | number | **2^53 を超えると不正確、64-bit wrap なし** (既知の差分) |
| string | JS string、1 code unit = 1 byte | `len`、index、slice、比較、不正 UTF-8 が Go と一致。JS 境界 (export の wrapper と `//goesm:import`) で `toJSString` / `fromJSString` (ASCII の文字列はそのまま。runtime は ASCII と判定した直近 2 個の文字列を覚えているので、JS から `strings.ToUpper` を通って戻る文字列の走査は 1 回)。64 byte 以上の `[]byte(s)` と `string(b)` は engine の `TextEncoder` と windows-1252 の `TextDecoder` を使い (ASCII の扱いは Go と同じ)、それ以外の byte があれば byte ごとの loop に戻る |
| struct | 生成 class の instance (`$clone` / `$set`) | 値 copy は lowering が挿入。object identity がそのまま address。構造体の値変数をフィールドの読み出しにだけ使う range ループは、要素を copy せず、読むフィールドをローカル変数に読み込みます |
| array | JS array | struct と同じく copy は明示的 |
| slice | `Slice{$array,$offset,$length,$capacity}`、nil は `null`。`$array` は JS array で、`make`・`append`・`[]byte(s)` で作った `[]byte` では `Uint8Array` (Go の array の slice と literal は JS array のまま)。65 バイトから 4 KiB のものは共有の 16 KiB slab の view です (V8 はそれより大きい `Uint8Array` の領域を heap の外に 1 個 1〜3 µs かけて確保するため)。値が関数の外に出ない (make・添字アクセス・`len`/`cap` だけに使う) ローカルの `[]bool` 変数もバイト列で持ち (boolean の配列の 4 分の 1 のメモリ)、読み出しはインラインの `!!b[i]` で boolean に戻し (helper 経由だと V8 で sieve が 1.5 倍遅かった)、書き込みは 1 か 0 です。`s[i]` の境界チェックはインラインで、添字が構造上範囲内のとき (`for i := range s`、`lo >= 0` の `for i := lo; i < len(s); i++`、`s := make([]T, n)` の後の `i < n`、`n := len(s)` の後の `for i := range n` と `i < n` で、`s`・`n`・`i` を他で代入しない) は省きます。array の要素は、256 要素の表へのバイトの添字、`x&0xff` のようにマスクした添字、array または array の長さ以下の定数までのループの添字なら境界チェックを省きます。構造体または array を要素とする backing array では、どの slice の長さよりも後ろの要素を、slice が初めて届いたとき (re-slice、`append`、`unsafe.Slice`) に作ります。そのため `make([]T, 0, n)` や伸長した slice への `append` は要素を 1 回だけ作ります | append / re-slice の aliasing が Go と同じ |
| map | JS `Map` の上の `GoMap`、nil は `null`。bool・整数・string・channel の key はそのまま `Map` の key で値を直接持ち (`Map` の等価性がこれらでは Go と同じ)、それ以外の key は Go equality で hash して `[key, value]` を持つ | struct / interface / NaN key、nil map の panic |
| pointer | `*struct` / `*array` は object 自体。それ以外は `.v` を持つ object (`Cell` / `FieldPtr` / `IndexPtr`) | `&x == &x`、`&s.f == &s.f` を cache で保証 |
| interface | `t` (型 descriptor) と `v` (値) を持つオブジェクト、nil は `null`。動的型の箱クラスのインスタンスか、素の `Iface` (下記) です。struct の値の箱は struct の class のサブクラスに属する struct のオブジェクトで、その prototype が `t` と、オブジェクト自身を返す `v` を持ちます。箱にするときの割り当ては 1 つです。同様に、箱クラスを持つ struct 型へのポインタは、それ自体が interface 値です。struct の class の prototype がポインタ型の `t`・`v`・method を持つので、変換では何も割り当てません。それ以外の struct へのポインタについては、interface 値は変更されないため、ポインタから最後に作った値を struct 自体に symbol で持たせ、同じポインタを再び変換するときは割り当てない | 動的型を保持。`MyInt(1)` と `int(1)` を区別、nil `*T` を入れた interface は non-nil |
| func | JS function | |
| chan | runtime `Chan` | |
| 型 parameter | 型引数の表現そのもの (erasure) | 型 descriptor を dictionary 引数で受け取る |

### 複数の戻り値

ブロックしない関数は、複数の戻り値のうち最初の値を返し、残りを `runtime/src/results.ts` の戻り値レジスタ `$rt.$R.r1`、`$rt.$R.r2` などに置きます。呼び出し側は、ほかの Go のコードが動く前に、呼び出しの直後にそれを読みます。`n, err := parse(s)` は `const $1 = parse(s); let n = $1; let err = $rt.$R.r1;` に、`return n, nil` は `return ($rt.$R.r1 = null, n)` になります。map の参照と型アサーションの comma-ok 形式である `$rt.mapLookup` と `$rt.assertOk` も同じ方式です。Go のコードを呼ぶ値を返す return 文は、レジスタに書く前に値を順に一時変数へ評価し、戻り値の型が同じ呼び出しを返す `return f()` は結果をそのまま引き渡します。戻り値を配列で返すと、V8 がインライン化しない呼び出しのたびに配列を割り当てます。`strconv.Atoi` 型の解析ループ、`utf8.DecodeRuneInString` のループ、comma-ok の map 参照は、レジスタにすると Node と Bun で 1.2〜1.5 倍速くなりました。

ブロックする関数、つまり async function は、従来どおり戻り値の配列で resolve します。呼び出し側が再開する前にほかの goroutine が動き、レジスタを上書きしうるためです。呼び出し側は await から戻った時点で `$rt.untuple(await f())` のように配列をレジスタに移すので、呼び出しの後のコードはどちらの関数を呼んでも同じ形になります。どちらにもなりうる関数値や interface method の呼び出しも、これで動きます。native も配列を返し、native を包む関数がそれをレジスタに移します。JavaScript からはどちらの形も見えません。export wrapper は複数の戻り値を配列で返し、`$goesm` の表の `tuple` はテスト harness のために戻り値を集めます。

### 64-bit 整数

`int64` と `uint64` は BigInt、`int`・`uint`・`uintptr` は JS の number のままです。64 bit 全体が必要な Go のコード (hash、乱数、`time` の nanosecond、JSON 中の ID、`math.Float64bits`) は明示的に 64-bit 型を使い、`int` は index や個数に使われます。後者は number の方が数倍速く、配列や文字列が持てる範囲では正確です。

演算は inline で書きます (`BigInt.asIntN(64, a * b)`)。V8 はこれを機械語の演算に compile します。除算・剰余・shift は小さな runtime helper を呼びます (0 除算 panic、Go の shift の意味論)。2 つの世界の間の変換は明示的で (`BigInt(i)`、`Number(x)`)、2^53 を超える `int64` を `int` に変換すると丸められます。exported 関数はこれらの型を `bigint` で受け取り・返します。

`bench/int64.mjs` で、goesm が lower し得る表現を、goesm が出力する形で書いた 4 つの workload で比較しました (5 回の最良値、Node 22 / Bun 1.3):

| workload | number (不正確) | BigInt | `{hi, lo}` object | uint32 の local 2 つ | 2^53 を超えたら BigInt の number |
|---|---|---|---|---|---|
| counter と合計 (小さい値) | 13 / 6 ms | 136 / 1003 ms | 260 / 397 ms | 141 / 55 ms | 124 / 30 ms |
| 4 MiB の FNV-1a 64 | 38 / 32 ms | 35 / 498 ms | 170 / 241 ms | 104 / 101 ms | 306 / 849 ms |
| xorshift64* | n/a | 209 / 684 ms | 97 / 273 ms | 113 / 86 ms | n/a |
| Unix nanosecond (加算・除算・剰余) | 13 / 45 ms | 41 / 296 ms | 758 / 978 ms | 306 / 845 ms | 147 / 359 ms |

V8 (Chrome、Node、Deno) では BigInt が 4 つ中 3 つで最速の正確な表現で、hash では number とほぼ同じです。JavaScriptCore (Safari、Bun) では uint32 2 つより 3〜18 倍遅くなります。2 分割は lowering と JS API で、すべての `int64` の変数・field・引数・戻り値を 2 倍にします。BigInt は lowering と exported API を単純に保ち、どこでも正確なので、これを表現として採用しました。

ループの中で多く演算するローカル変数については、値の表現を変えずに 2 分割の経路を使います。実装は `internal/lower/split64.go` にあります。最も深いループでの演算が BigInt との変換より多い `int64` と `uint64` のローカル変数は、`x$hi` と `x$lo` の 2 つの int32 のローカル変数で持ちます。この変数の加算、減算、乗算、ビット演算、定数でのシフトは、int32 の演算と `Math.imul` になります。BigInt に変換するのは、値が関数の演算から出る箇所だけです。たとえば、関数の呼び出し、メモリへの格納、戻り値がこれにあたります。これにより、FNV-1a 64 は V8 でも JavaScriptCore でもネイティブに近い速さで動きます。xorshift のように、ローカル変数の `int64` か `uint64` のフィールド 1 つに、そのフィールド、ローカル変数、定数から代入する文が続く場合も、その間はフィールドをローカル変数に写して計算し、最後に 1 回だけ書き戻します (`internal/lower/fieldpromo.go`)。テストのために、`GOESM_SPLIT64=off` でこの lowering を止め、`GOESM_SPLIT64=all` ですべての候補に適用できます。

### 型 metadata

すべての named type は runtime descriptor (`$rt.named(pkgPath, name)`) を持ち、underlying 型、field (名前・pkgPath・tag・embedded)、value / pointer の method set (method 名と signature descriptor) を登録します。複合型 (`[]T`, `map[K]V`, `func(...)`, `struct{...}`, `interface{...}`) は構造で memoize されるため、**descriptor の同一性 = Go の type identity** です。interface 判定はこの method table で行い、TypeScript の structural typing には依存しません。unexported method は pkgPath で修飾されます。interface 経由の呼び出しは、interface 値自身を receiver の引数として渡す、interface 値の method の呼び出し (`x.$M(x, ...)`) なので、呼び出し箇所ごとにそこを通る少数の型に対する inline cache が効きます。interface 経由で method が呼ばれる、generic でないパッケージレベルの型は箱クラスを持ちます。箱クラスの prototype は、interface 値がそのまま値である場合 (struct の値と struct へのポインタ) はその型の method 関数そのものを持ち、値を保持する箱では値を取り出す method を持ちます。そのため、JS の class の method と同じく hidden class ごとに既知の関数へ解決され、エンジンがインライン化できます (`internal/lower/box.go`)。それ以外の型、つまり generic な型、名前のない型、runtime の型の interface 値は素の `Iface` で、その method は型の method table (`t.mt`) を通して呼びます。Go のリンカーと同じく、table には動的に呼ばれうる method だけを載せます。対象は、プログラム中の interface 型の method と名前・signature が一致する method と、runtime が panic の表示に使う `String() string` です。プログラムが reflection で method を列挙する場合 (`Method`、`MethodByName`、`NumMethod`) は、exported な method をすべて載せます。そのうち関数を残すのは、到達可能なコードが `Method` か `MethodByName` を呼ぶときの、interface の値に格納される型の exported な method だけです。`MethodByName` の引数が定数なら、その名前の method だけを残します。protobuf の descriptor の整形が `Get` を呼ぶのがその例です。それ以外の method は呼び出すコードからだけ参照されるので、使わなければバンドラーが削除します。`time.Time` の 47 個の method をすべて載せていたときは、`time` を使うだけで `Format` やエンコーダーが残っていました (`internal/lower/methods.go`)。table に載せた method も、到達可能なコードが interface 経由で呼ぶ場合に限り関数を残します (`internal/lower/reach.go`)。到達可能なコードが interface の値に格納しない型の table は空です。その型を動的な型とする interface の値は存在しないためです。table に載せると、method の signature がそこに現れる型を残してしまいます。到達可能なコードの起点は、entry package の関数、package の初期化、JavaScript が handle に対して呼ぶ method です。プログラムの module のほかの package は entry が使う部分だけを数えるので、生成された connect-go の package のクライアント側はサーバーに含まれません。runtime 自身が `Error` と `String` を呼ぶのは、panic として表示する値と JavaScript へ渡す値に対してだけです。そのため、`strconv.Atoi` を呼んで error を nil と比べるだけのプログラムには、`NumError.Error` も、それが使う `strconv.Quote` と表も残りません。同じ理由で、struct 型の class が JS の method を持つのは、それが API になる entry package だけです (JS calling ABI)。

### Generics: type erasure + runtime type dictionary

* 関数・method のコードは 1 つだけ生成し (erasure)、型引数は runtime 型 descriptor の **dictionary 引数**として先頭に渡します: `First($T_T, values)`。
* descriptor があるので、zero value (`var x T`)、interface 変換 (`any(x)`)、`==`、aggregate の copy、`new(T)`、`make([]T)` を型引数に応じて正しく行えます。
* generic type の instance (`Stack[Pair[string,int]]`) も memoize された descriptor になり、`a.(Pair[string,int])` と `a.(Pair[string,string])` を区別します。
* Go 1.27 の generic methods は、receiver の型引数 → method の型引数の順に dictionary を渡します。interface を満たさないため method table には載りません。
* 理由: specialization はコード量が型引数の数だけ増え、JS bundle では不利です。TS generics に残すだけでは runtime に型情報が無く、zero value・interface 変換・reflect が実装できません。erasure + dictionary は Go の gc (GC-shape stenciling + dictionaries) と同じ考え方で、最も単純かつ reflect に繋がります。TS 側には可読性のため `<T>` を残しますが、意味は持たせていません。

### defer / panic / recover

```ts
function F() {
  let $r0 = zero;                 // 結果変数 (named result はその名前)
  const $d = new $rt.Defers();
  $body: try {
    ...; $r0 = expr; break $body; // return は結果を代入してから defer へ
  } catch ($e) { $d.fail($e); } finally { $d.run(); }
  return $r0;                     // defer が named result を書き換えた値を返す
}
```

* panic は `GoPanic` (JS Error) を throw。値は interface 値として保持し、runtime error は `runtime.Error` を実装する型 (`Error()` / `RuntimeError()`) を持ちます。JS の `TypeError` (nil 参照) は nil pointer dereference の runtime error に変換します。ポインタ経由のフィールドや要素のアクセス (`p.f`、`*p`、`*[N]T` の `p[i]`) は明示的な nil チェックをせずこれに頼ります (明示的なチェックがあると V8 の高速なプロパティアクセスが効かなくなるため)。entry package の exported な関数と method、JS から呼び戻される Go の関数は wrapper で包み、JS からは引き続き `GoPanic` に見えます。
* defer の関数値と引数は defer 文の時点で評価し、closure に閉じ込めます。
* recover() は deferred 関数自身の中でだけ recover します。各 deferred call は、静的に分かる場合 (関数、具象型の method、関数リテラル、`recover` builtin) は呼ぶ関数を記録し、recover() を呼ぶ関数は入口でその呼び出しかどうかを問い合わせます (`const $rf = $rt.recoverFrame("main.F")`。再帰呼び出しは該当しない)。答えは recover() が panic を recover する frame なので、await の後でも効きます。defer された `recover()` は、それを defer した関数が呼んだものとして扱います。
* JS 側から見ると、捕捉されない panic は `GoPanic` 例外になり、`--enable-source-maps` で stack が `.go` の行を指します (テスト済み)。

### goroutine / channel / select

* **blocking 解析** (whole program): channel 操作 (default 付き select の case を除く)、default 無しの select、channel の range、blocking 関数の呼び出し/defer、blocking し得る動的呼び出しを含む関数を blocking とし、`async function` に lowering します。blocking 点はすべて `await`。それ以外は同期関数のままです (await のコストを払わない)。動的呼び出しは保守的に解決します。関数値経由の呼び出しは、同じ signature を持ち、どこかで値として使われる関数 (その場で呼ばれない関数 literal、callee 以外の位置で参照される関数や method) に届き得るとみなします。ただし、関数 literal、宣言された関数、nil しか代入されず、address も取られない関数型の変数の呼び出しは、それらにしか届かないとみなします (`internal/lower/funcvars.go`)。そのため、コンポーネントの `update := func() {...}` は、ほかの `func()` の値が block するプログラムでも同期のままです。interface method の呼び出しは、interface 値に格納され得て、その interface を実装する型の同名 method に届き得るとみなします。格納され得る型とは、どこかで interface 型へ変換される型 (代入、引数、return、composite literal の要素、send、map の key、明示的な変換、`append`、`panic`)、すべての instantiation の型引数、そしてそれらから field・要素・pointer で辿れる型 (reflection 用) です。このため block する `io.PipeWriter.Write` があっても `io.Writer.Write` の呼び出しすべてが async になることはなく、program が pipe を `io.Writer` に格納しない限り `fmt.Println` は同期のままです。method を宣言した interface を埋め込む interface 経由の呼び出しは、外側の interface で数えます。`hash.Hash` の `Write` が届くのは hash の実装であり、すべての `io.Writer` ではありません。blocking は引数にも依存し得ます。宣言された関数の interface 型と関数型の parameter のうち、代入もアドレス取得もされないものを追跡し、その parameter に対して呼ぶ method を記録します。別の関数の同種の parameter へ渡す場合も、渡した先での呼び出しを含めます。その呼び出しを通してのみ block する関数には同期版の複製 `F$sync` を作り、そこで引数が block し得ない呼び出しは複製を呼びます。たとえば `fmt.Fprintf` に `io.Writer` として渡す `*strings.Builder` や、`func()` として渡す block しない関数 literal がこれに当たります。このため program が `fmt.Fprintf` で pipe に書き込んでいても、`fmt.Sprintf` とそこから呼ぶ `Formatter` は同期のままです。関数型の parameter が呼び出し、nil との比較、同種の parameter への受け渡しにしか使われない場合、その parameter は外へ漏れません。このとき、関数の静的な呼び出しでその parameter に渡す関数 literal、関数、method 値は関数値として数えません。そのようにしか使わない局所変数を介して渡す場合も同様で、`sync.OnceFunc` が `Once.Do` に渡す関数がその例です。parameter 経由の呼び出しは、それらの引数のいずれかが block し得る場合に限り block します。関数が関数値や interface 経由、`go` 文、package 変数の初期化式からも呼ばれる場合は、parameter の型を持つすべての関数値も数えます。range-over-func の body は iterator に渡す yield 関数です。block し得る body は async な callback になり、解析はそれを yield 型の関数値として数えるので、それを呼び得る iterator は await します。entry package が決まると、そこから到達可能なコードについて解析をやり直します (`internal/lower/program.go` の `refineBlocking`)。このとき interface 経由の呼び出しが届くのは到達可能なコードが interface の値に格納する型の method だけ、関数値の呼び出しが届くのは到達可能なコードの関数値だけ、追跡する parameter に渡るのは到達可能な呼び出しの引数だけです。実行されないコードが他のコードを待たせることはありません。Connect のリクエストを処理する Worker では、connect-go のクライアントの stream と net/http のクライアントが使う `io.Pipe` のために `io.Reader` の `Read` が block し、protobuf の `Format` method を通じてすべての `fmt.Sprintf` が async になっていました。Worker はそのコードを実行しません。到達不能なコードには最初の解析の結果を使います。
* **Mutex**: goroutine が `sync.Mutex` を lock 済みで見つけるのは、保持者が block しているときだけです。そこで `Lock` は同期関数で、待ちません。goesm は block した goroutine が保持し得る critical section を見つけます。`Lock` から同じ block 内の対応する `Unlock` まで (`defer Unlock` なら末尾まで。`Unlock` の無い `if` の branch や block 内の `Lock` なら、`if c { mu.Lock() }; ...; if c { mu.Unlock() }` のように、外側の文の列でそれを unlock する最初の後続の文まで) の間に block する操作があるもの、そして対応する `Unlock` の無い `Lock`、または `Unlock` に届く前に抜ける経路 (`return`、`panic`、`runtime.Goexit` やそれを呼び得る関数の呼び出し、block の外への `break`・`continue`・`goto`) のある `Lock` です。section は mutex を直接 (変数や struct field の path、これを mutex の key と呼びます) か、間接的に (pointer 経由、`sync.Locker` 経由 (それを制約とする型パラメータも含む)、`f().Lock()` のように名前が無いもの) lock します。直接の `Lock` / `RLock` は、その key にそのような section があるとき、または間接的な section があり、かつその key の mutex が escape する (address を取られる、method value や `RLocker` で使われる、interface に格納される型に埋め込まれている) とき、待機する (async な) `lockSlow` / `rLockSlow` になります。間接的なものは、間接的な section があるか、保持される key が escape するときに待ちます。このとき `Locker.Lock` は `lockerSlow` になり、`sync` package の mutex なら待ち、それ以外の Locker は呼び出して、それが埋め込まれた mutex の Lock で lock 済みだった場合は次の unlock の後に再試行します。これを blocking 解析と交互に、変化がなくなるまで繰り返します。`(*sync.Mutex).Lock(&mu)` のような method expression は `mu.Lock()` と同じに扱います (埋め込まれた mutex から promote された method は除く)。文で区切られない section は保持されたものとみなします: `TryLock`、`if` / `switch` の初期化文や defer の中の `Lock`、`Lock` の method value (`lock := mu.Lock`)。同じ規則で待つ可能性のある `Lock` の method value や method expression の値は待機版に bind され、その型の関数値 (`func()`、`func(*sync.Mutex)`) の呼び出しは async になります。`go` 文の関数値と引数は文を実行する goroutine が評価するので、その中の block する操作も数えます。`sync` package 自身の lock (`Cond.Wait`、`RLocker`) は解析の対象外です。
* `go f(x)` は関数値と引数をその場で評価し、`$rt.go(closure)` が microtask として起動します。
* channel は runtime 内の buffer と送受信 wait queue で表現し、即時完了できる場合は同期的に値を返し、block する場合だけ Promise を返します。unbuffered の handoff、close (待機中 sender への panic を含む)、`select` (ready な case から一様ランダム、default、nil channel は永久 block) を実装しています。
* つまり「async/await に変換すれば Go と同じ」とは扱っていません。blocking の意味論は wait queue という runtime 側の境界にあり、async/await は「goroutine を中断・再開する手段」に限定しています。`runtime.Goexit` (deferred 呼び出しは実行され、`recover` では止まらない) と `sync` の置換 (§9) はこの境界の上に実装しました。deadlock 検出、goroutine-local な panic 状態、timer も同様に載せます。
* JS 境界: blocking する exported 関数は Promise を返します (例: `await Example()` は 42)。
* **プログラム**: main package の module は `$rt.runMain` で `main` を実行します。Go と同じく、`main` が return すると (他の goroutine が動いていても) process は終了し、`os.Exit` は deferred 呼び出しを実行せずにその code で終了し、どこでも recover されない panic は `panic: ...` と `goroutine 1 [running]:`、JS の stack を標準エラーに出して status 2 で終了します。package の初期化中の panic も同じです: main module は最初に `@goesm/runtime/program.ts` を import し、これが捕捉されない例外を同じ crash に変えるので、すべての依存 package の変数初期化と `init` 関数も対象になります。`main` 内の `runtime.Goexit` は main goroutine だけを終わらせ、他の goroutine がすべて終わると `fatal error: no goroutines (main called runtime.Goexit) - deadlock!` を出します。`main` が block したまま host の event loop が空になると (Node と Bun の `beforeExit`。JavaScript のコードが求めた終了は含まない)、もう goroutine を起こせるものはないので、Go と同じ `fatal error: all goroutines are asleep - deadlock!` を出して status 2 で終了します。この監視は `program.ts` が始めるので、永久に block する `init` 関数も Node では同じく報告されます。Bun は決着しない top-level `await` で spin し続けるため、そのような program は Bun では止まりません。process の無い browser では、recover されない panic は `reportError` で報告し、block した `main` はそのまま block し続け、`os.Exit` は deferred 呼び出しを実行せずに goroutine を巻き戻します (recover はできません)。

### インクリメンタルビルド: モジュールキャッシュ

ビルド時間のうち最も大きな部分は、パッケージの lowering です。goesm.dev の `site` パッケージは 77 個のパッケージを含み、その大半は標準ライブラリです。このビルドでは、読み込みと型検査に約 0.28 秒、プログラム全体の解析に約 0.23 秒、lowering に約 0.64 秒かかります。そこで `internal/build` は、各パッケージのモジュールをキャッシュに保存し、キーがキャッシュにないパッケージだけを lowering します。実装は `internal/build/cache.go` にあります。フロントエンドと解析は、毎回のビルドで実行します。パッケージのモジュールはプログラム全体に依存するからです。たとえば、同じ signature の関数値がプログラムのどこかで block しうる場合、関数は async になります。また、別のパッケージが代入するパッケージ変数は `Cell` を必要とします。

パッケージのモジュールのキーは、次の要素から作ります。1 つ目は goesm の実行ファイルです。lowering、ランタイム、natives は実行ファイルに含まれます。2 つ目は `GOESM_SPLIT64` です。3 つ目は、そのパッケージがエントリかどうかです。4 つ目は、そのパッケージと、それが依存するすべてのパッケージについての、import path、ファイル、解析結果のダイジェストです。ファイルについては、名前、Go のバージョン、内容をキーに含めます。解析結果のダイジェストは `lower.Program.Facts` が計算し、lowering が読む解析結果を表します。このダイジェストには、パッケージが宣言する関数、関数リテラル、range-over-func 文、変数について解析が決めた事項を含めます。具体的には、async かどうか、同期でのみ実行するかどうか、同期版の複製を作るかどうか、`Cell` に入れるかどうか、linkname の pull と provider です。さらに、lowering がパッケージ自身のノードについて問い合わせる `CallBlocks`、`RangeBlocks`、`WaitLock`、`WaitLockVal`、`SyncClone` の答えも含めます。ダイジェスト内の位置はファイル内のオフセットで表すので、編集が変えるのは、その編集が影響するパッケージのダイジェストだけです。lowering が、ダイジェストの対象外である `Program` の要素を読むようになると、`TestFactsCoverProgram` が失敗します。パッケージの lowering で生じた警告は、モジュールと一緒に保存します。

キャッシュは、ユーザーキャッシュディレクトリの `goesm/modules` に置きます。`GOESMCACHE` で場所を変更でき、`GOESMCACHE=off` でキャッシュを無効にできます。go コマンドのビルドキャッシュと同じく、5 日間使われなかったエントリは削除します。goesm.dev の `site` は、1 つのパッケージを編集した後の再ビルドに、キャッシュがない場合の 1.2 秒ではなく 0.7 秒かかります。サイト全体の `astro build` は、11.1 秒から 8.7 秒になります。`TestModuleCache` は、キャッシュから取り出したモジュールが lowering の結果とバイト単位で一致することを確かめます。他のプログラムが保存した標準ライブラリのモジュールも、この確認の対象です。`TestModuleCacheFollowsFacts` は、あるパッケージの変更が依存先の解析結果を変えた場合に、その依存先を lowering し直すことを確かめます。

## 6. runtime 構成 (`runtime/src`、`<dir>/@goesm/runtime/*.ts` として出力)

| file | 責務 |
|---|---|
| `types.ts` | 型 descriptor (reflect.Kind 準拠の kind、named / 複合型の memoize、method table、generic instance、`error`) |
| `iface.ts` | interface 値、box / assert / type switch (具体型の case は 1 回読んだ動的型と比較)、`==`、map 用 hash key |
| `slice.ts` | slice、append / copy / bounds check、core type を持たない型 parameter への index |
| `map.ts` | Go map |
| `ptr.ts` | Cell / field pointer / element pointer、型 parameter 経由の load / store |
| `string.ts` | byte string ⇔ UTF-8 / rune、JS 境界変換 |
| `int.ts` | 整数除算・剰余 (0 除算 panic)、shift、64-bit bit 演算、min / max |
| `panic.ts` | GoPanic、runtime error 型、Defers、recover |
| `chan.ts` | channel、select、goroutine の起動と数、`main` の実行 (終了 status、crash 出力、deadlock) |
| `complex.ts` | 複素数 |
| `host.ts` | 標準出力・標準エラー (Node / Bun / Deno の `fs` への write、browser では console)、process の終了 |
| `print.ts` | `print` / `println` builtin (Go runtime の書式) |
| `natives.ts` | Go の body を持たない stdlib 関数の実装 (§9)。それを必要とする stdlib の module だけが import する独立した module で、関数ごとに 1 export なので使われないものは tree shaking で落ちる |
| `fmt.ts`、`json.ts` | `fmt.Sprintf` と `encoding/json` の `Marshal`・`Unmarshal` の高速経路。`natives.ts` が import する。`natives.ts` と同じく runtime を `index.ts` 経由でだけ使うので、`-split` build でも runtime は 1 つ |
| `interop.ts` | 型 descriptor に従う Go 値 → JSON 形 JS 値 (golden テスト) |
| `jsabi.ts` | `//goesm:import` のための Go 値 ⇔ JS 値の変換 ([docs/js-imports.ja.md](https://goesm.dev/ja/reference/js-imports.md))。文字列、数値、平らな struct は lowering がインラインで変換し、それ以外は descriptor を渡して `goToJS` / `jsToGo` を呼ぶ |

fixture を通すのに必要なものから実装しており、scheduler や reflect の先行実装はしていません。

## 7. reflect / unsafe / メモリ表現の方針

* **reflect**: codegen は named type identity、field 名・tag・embedded、method set (名前・signature)、型引数を runtime descriptor として常に残し、`Kind` は reflect と同じ番号です。`reflect` package はその上の Go source で置換しています (§9)。`reflect.Type` は interface 値の descriptor、`reflect.Value` は (descriptor, 値)、addressable なら (descriptor, goesm の pointer) で、`Set` はその pointer 経由で書き込みます。これにより `fmt`、`encoding/json` (内部は Go 1.27 の json v2、または後述の encoding/json 自身の encoder と decoder) を自身の Go source から compile できます。メモリアドレスが必要なもの (`UnsafeAddr`、`NewAt`、`StructOf`) は panic し、block する関数の `Value.Call` も panic します。reflect 経由の channel 操作は block しない場合のみ動きます。
* **pointer 表現**: 現在は「aggregate は object 自体、他は accessor object」。`unsafe.Pointer` との相互変換を将来入れるため、pointer 生成は `ptr.ts` の関数に集約してあり、表現を差し替えられます。
* **unsafe / linear memory**: 「JS に pointer は無いので非対応」とはしません。予定している方向は、(1) `[]byte` 等の数値 slice を TypedArray backing にする (slice の backing store は `slice.ts` の private な表現)、(2) `unsafe.Pointer` を (ArrayBuffer, byte offset) または (object, field) の tagged 表現にし、`unsafe.Slice` / `unsafe.String` / `unsafe.Add` を DataView 上で実装する、(3) 必要な package だけ linear memory (ArrayBuffer) 上に struct を layout する、の段階的導入です。現状は次のとおりです:
  * `unsafe.Pointer` は pointer object そのものを保持するので、`*T` → `unsafe.Pointer` → `*T` は恒等変換です (`strings.Builder`、`sync/atomic.Pointer`、`internal/race` がこれに依存)。
  * `unsafe.String(&b[i], n)`、`unsafe.String(unsafe.SliceData(b), n)`、`unsafe.Slice(&a[i], n)`、`unsafe.SliceData(s)` は slice / array の要素に対して動きます (同じ backing array 上の slice)。`unsafe.Slice(unsafe.StringData(s), n)` は copy しますが、byte は不変なので区別できません。
  * 型 parameter の `unsafe.Sizeof` / `Alignof` は wasm の size で descriptor から計算します。
  * pointer は由来 (provenance) を保持します: `unsafe.StringData(s)` は元の string を、`unsafe.SliceData` は backing array を覚えているので、それらに対する (および単一の変数を指す pointer に対する) `unsafe.String` と `unsafe.Slice` が動きます。
  * メモリの再解釈 (異なる `T` への `(*T)(unsafe.Pointer(&u))`) は、protobuf などの library が頼る layout については動きます (`runtime/src/unsafe.ts`): pointer 変数を別の pointer 型として読む (`sync/atomic` 向けの `(*unsafe.Pointer)(unsafe.Pointer(&p))`)、同じ layout の struct、string (`{data, len}`)・slice (`{data, len, cap}`、読み取り専用)・空 interface (`{type, data}`) を写した header struct で、これらは元の値の view になります。古い library が zero-copy のために書く `*(*string)(unsafe.Pointer(&b))` のように `[]byte` 変数を `string` として読む場合と、`string` を `[]byte` として読む場合は、読むたびに作るコピーになります。それ以外の再解釈は goesm 診断です (依存 package では関数が stub になります、§9)。`uintptr(unsafe.Pointer(p))` は pointer ごとに安定して異なる代理のアドレスで、表示 (`%p`) や identity の map には足り、pointer が生きている間は同じ pointer に戻せます。
  * protobuf-go の生成 message の高速経路が行う field offset による pointer 演算 (`unsafe.Pointer(uintptr(p) + off)`、`unsafe.Add`): 結果は `p` が指す struct / array への (object, byte offset) のアドレスで、`*T` に変換すると `reflect` が報告する wasm の layout (`StructField.Offset`) でその offset にある field / 要素を、入れ子の struct や array にも降りて見つけます。struct の先頭 field は struct 自身 (protobuf の `messageState` の手法)、`reflect.NewAt` はこのアドレスを受け取り、`[]*T` の field を pointer だけを持つ struct の slice (protobuf の `[]pointer`) として読むと要素を包み/剥がす view になり、`unsafe.Pointer` の比較はアドレスを比較します。field の途中を指す offset や、異なる layout の型として field を読むと panic します。stdlib でこれを行う少数の関数は natives に置き換えています (`math.Float64bits`、`slices.overlaps` など)。

## 8. Source maps と diagnostics

* lowering は式・文の文字列に Go の位置 marker を埋め込み、writer が出力列を確定させた時点で mapping を記録します。codegen の途中で位置情報を捨てません。
* 生成 TS ごとに TS→Go の Source Map v3 を作り、TS に inline で添付します (`emit-ts` は module の隣に `<p>.ts.map` としても書き出します)。`goesm build` では esbuild がそれを読み込んで最終的な **JS→.go** の map を合成します (`sourcesContent` に Go source を含む)。他の bundler が合成するとは限りません。Vite 8.3 と Bun 1.3 では最終的な map は生成された `.ts` file を指します。Node の `--enable-source-maps` で panic の stack が `panics.go:NN` を指すことをテストしています。
* 診断は layer を区別します:
  * `file.go:4:17: ... [go/types]` / `[go/parser]` / `[go list]` — Go frontend の error。元の `.go` 位置。
  * `file.go:6:9: reinterpreting *int64 as *[2]int32 through unsafe.Pointer is not supported [goesm lowering]` — goesm の未対応。Go の compile error とは別物として表示。
  * stdlib package では、goesm がまだ lowering できない関数は error にしません。呼ばれると panic する stub (`goesm: <func> is not supported yet`) になり、CLI がその数を報告します (`-v` で最初の理由とともに一覧)。大半のプログラムはこれらに到達せず (`internal/abi` の gc 型 layout、complex など)、到達しないものは tree shaking で落ちます。
  * `internal error: esbuild rejected TypeScript generated by goesm ... [esbuild]` (`goesm build`) — goesm の bug。Go の error に見せかけません。

## 9. stdlib

方針は「通常の Go source をそのまま compile する」で、TS への手移植はしません。GopherJS の natives と同様に、gc runtime に結び付いた少数の package には target 固有の置換が必要ですが、goesm ではそれも **Go source** として持ちます (`internal/natives/goroot/<import path>/`):

| 置換する package | 置換の内容 |
|---|---|
| `runtime` | 他の package が使う exported API (`GOOS`、`Error`、`Goexit`、`Gosched`、`KeepAlive`、`Caller`、`MemStats` など)。scheduling とメモリは `@goesm/runtime` 側 |
| `reflect` | runtime の型 descriptor の上の全 API (type、value、`Set*`、`Call`、`MakeFunc`、map、slice、`Convert`、`DeepEqual`、`VisibleFields` など)。`fmt` と `encoding/json` に足りる範囲 |
| `internal/reflectlite` | `Type` = runtime の型 descriptor、`Value` = (descriptor, 値 or pointer)。`errors.Is` / `errors.As`、`sort.Slice`、`context` に足りる範囲 |
| `sync` | `Mutex` と `RWMutex` は同期的に lock し、block を跨いで保持される mutex (§5) だけ待つ (async)。`WaitGroup` と `Cond` は channel で待つ。`Once`、`Map`、`Pool` は普通の Go |
| `syscall/js` | js/wasm の `syscall/js` API を JS の値そのものの上に実装 (`Value` が値を持つ)。goesm は stdlib を js/wasm 向けに compile するので、`os`・`syscall`・`time` はこれを通じて host に届く。`js.Global().Get("fs")` は `globalThis.fs` が何であっても常に goesm 自身の file system で、`syscall` package が期待する callback API を持ち、return する前に callback を呼ぶ (Node・Bun・Deno では `node:fs` の上に、browser では console を使う代替)。そのため `os.Stdout` と `os.Stderr` はどこでも動き、呼び出し側を async にしない。`process` は host のもの、browser では最小限の代替。引数が真偽値・数値・文字列・`Value`・`Func`・nil だけの `Value.Get`・`Set`・`SetIndex`・`Call`・`Invoke`・`New` の呼び出しは、`ValueOf` のために引数を 1 つずつ box する代わりに、変換済みの引数を JavaScript の配列で受け取り、ASCII の定数名をそのまま受け取る非公開の版に lower される (`internal/lower/jsvalue.go`) |

仕組み:

* loader は `packages.Config.ParseFile` を設定します。go/packages が `$GOROOT/src` 以下の置換対象 package の file を parse するとき、最初の file が置換 source になり、残りは空 file になります。したがって go/types はすべての importer を置換後の package に対して型検査し、go command が解決した package graph は変わりません。`packages.Config.Overlay` ではできません: `go tool goesm` の toolchain がある module cache 以下の file は go command が overlay を拒否します。
* 型検査済みの import (置換後) で到達できる package だけを lowering するので、gc runtime の内部 (`internal/runtime/*` など) は外れます。
* package は build tag `purego` と `math_big_pure_go` 付きで load します。stdlib が assembly も持つところでは portable な Go のコードが選ばれます (gc が assembly 無しで build するときと同じ)。
* stdlib の Go の body を持たない関数 (assembly、`//go:linkname` 宣言、置換で body を省いたもの) は `runtime/src/natives.ts` に、`types.Func.FullName` から決まる名前の export として実装します。export の有無は goesm が compile 時に確認します。メモリを再解釈する Go body を持つ関数も、短い固定 list (`natives.Override`) で natives に置き換えます: `math.Float64bits` など、64-bit の `math/bits` 関数 (BigInt の半分ずつで計算)、`internal/strconv.formatBits` (Go の body が `uint64` の桁を `uint` 経由で狭めるため)、`slices.overlaps`、`internal/abi.NoEscape`。結果が IEEE 754 で決まる math の関数 (`Floor`、`Ceil`、`Trunc`、`Round`、`RoundToEven`、`Sqrt`、`Abs`、`Signbit`、`Copysign`、`Inf`) も JS の builtin にしています。Go の body の bit 操作より数倍速くなります。
* **patch** (`internal/natives/patch/<import path>/<file>.go`) は、それ以外は自身の source から compile する package の一部の宣言だけを変えます。patch の宣言は package 内の同名の宣言を置き換え (元の宣言はその場で `_` に rename するので、型検査はされますが出力はされません)、import とともに同名の file に追加されます。patch は元の file が import しない package も import できます。go command は package の import を file から列挙するので、その package の blank import を加えた file を overlay として渡します (internal/loader の `patchImports`)。`time` はこの方法で patch しています: gc runtime が実装する `Sleep`、`Timer`、`Ticker` と timer 関数を host の `setTimeout` (natives.ts の `armTimer`) の上で動かし、timer の関数は発火時に新しい goroutine で実行します。その他の patch は、`unsafe.Pointer` 経由で memory を読むコードや、gc が compiler で実装するものを置き換えます: `sync/atomic.Value`、`hash/maphash` (runtime が hash)、`log/slog.Value` の string と group、`crypto/internal/fips140/subtle.XORBytes`、`alias.AnyOverlap` と SHA-3 の置換関数、`crypto/internal/fips140/check` の自己検証 (FIPS 140 mode は有効にできない) と、FIPS 140 mode でだけ実行する自己テスト `CAST` と `PCT` (これを呼ぶ `init` 関数が、import するすべてのプログラムにハッシュ、AES、鍵導出を残していた)、`crypto/internal/constanttime`、`internal/abi` の escape hint、`context` の `cancelCtx.Err` (閉じ済みの channel を待つので `Context.Err` が async になってしまう)。package を host につなぐ patch もあります: `os/signal` は `process.on` で signal を受け、`os.Executable` は Node.js と Bun では script を返し、`net/http` の client は常に `fetch` を使います (js/wasm port は Go 自身のテストのため Node.js 上では process 内の偽 network を使う)。dialer が素の `net.Dialer` のものである Transport (OpenTelemetry の OTLP/HTTP exporter が作る) も、port ならそれで process 内の network に dial しますが、`fetch` を使います。この patch は otelc などの instrumentation が書き換える元の `RoundTrip` を残して呼びます: `//goesm:original name` directive を持つ patch 関数は、置き換える宣言を `_` ではなく `name` に rename します。ブラウザ以外では client は fetch に `redirect: "manual"` を指定し、redirect はネイティブと同じく `http.Client` 自身がたどります。そのため `CheckRedirect`、cookie jar、10 回の上限が効きます。ブラウザはこの指定に中身のない応答しか返さないので、ブラウザでは fetch がたどります。`net/http` の server も host につないでいます。`Server.ListenAndServe` は偽 network で listen する代わりに host 自身の HTTP server で処理します。Node.js では `node:http`、Bun では `Bun.serve`、Deno では `Deno.serve` を使います。`Close` と `Shutdown` は、登録した listener を通じてその server を止めます。`runtime/src/http.ts` の `fetchHandler` は、`http.Handler` を Cloudflare Workers、`Deno.serve`、service worker 向けの fetch handler にします。どちらも patch の同じ Go 関数を使います。この関数は Fetch API の `Request` から server 側の `*Request` を作り、handler を goroutine で実行します。request の body は最初に全部読みます。`ResponseWriter` は、handler が戻った時点で body を 1 つの `Response` にまとめます。handler が flush した場合は body を `ReadableStream` にするので、Server-Sent Events や Connect の server streaming が動きます。`unique` は置換しています: 1 つの Go map が正準値を保持し、解放はしません。`math/big` の word 関数は 32-bit word に patch し、`crypto/internal/fips140/bigmod` と `crypto/internal/boring/bbig` は 32-bit limb 版に置換し、`crypto/internal/fips140/nistec` の P-256 の表は alias せずに decode し、`iter` の coroutine は goroutine 上で動かします。速度のため、`fmt.Sprintf` は文字列・bool・整数・float64 の `%v %d %s %t %x %X %f %F` を、1 回だけ解析した書式で整形し (`runtime/src/fmt.ts`)、それ以外のよく使う書式 (文字列・bool・事前宣言型の数値の `%v %d %s %t %x %X %f %e %g`、`-`・`0`・幅・浮動小数点数の精度) を文字列の連結で組み、数値は engine (`toString`・`toFixed`・`toExponential`) で整形し、それ以外 (他の verb やフラグ、名前付き型、引数の過不足) は fmt 自身のコードに任せます。`encoding/json` の `Marshal` と `Unmarshal` は、単純な値 (bool・数値・文字列・slice・配列・key が文字列の map・pointer・`any`、tag が名前と `omitempty` だけの struct。どこにも method がないもの) なら `runtime/src/json.ts` で処理し (`Marshal` は値を JS の値に変換して engine の `JSON.stringify` に渡し、Go と同じく後から HTML の文字を escape する。`Unmarshal` は型ごとに作る decoder で入力を 1 回だけ読む)、それ以外 (marshaler、埋め込み field、他の tag option、decode 先の nil でない slice・map・pointer、エラー) は最初から package の Go のコードに任せます。そのコードは数倍の大きさの json v2 ではなく、encoding/json 自身の実装 (`GOEXPERIMENT=nojsonv2`) の encoder と decoder です。patch で組み込み、json v2 を v1 の option で使った場合と同じ出力と戻り値になるよう変えています。エラー (json v2 の offset と JSON Pointer の path を持つ `UnmarshalTypeError`、メソッドのエラーはそのまま、それぞれの後も decode を続ける)、途中までの結果、受け付ける map の key、struct tag の解釈、不正な UTF-8 の出力がその対象です。入力と `MarshalJSON` メソッドの出力は runtime (`jsonSyntax`) が検査します。json v2 だけが呼ぶ `MarshalJSONTo` か `UnmarshalJSONFrom` という名前のメソッドを encoding/json の外で宣言するプログラムは json v2 を使います (internal/lower/json.go の `JSONv2`)。`testdata/programs/jsonlegacy` が、ランダムな JSON の文字列と値で両者を native Go と比べます。goesm が lower する `json.Unmarshal` の呼び出しは、代わりに runtime の `jsonDecode` を使います。これは 1 回の読み取りで処理できない入力も扱い、jsontext と同じ構文検査をしてから v1 の merge の規則でその場に decode し、`encoding/json` 自身と同じ文言、offset、field のエラーを返します。decode 先の型をこれで必ず処理できる呼び出し (method、配列、すでに pointer を持ちうる interface のいずれもない型) は package の何も参照しません。そのような呼び出しだけを持つ package は `encoding/json` を import しないので、json v2、jsontext、reflect の大部分を残す初期化も入りません。struct に JSON を decode するだけのプログラムは、minify 後 553 KB から 36 KB になります。ASCII 文字列の `strings` の `ToUpper` と `ToLower` は engine の `toUpperCase` と `toLowerCase`、区切りありの `Split` と `Join` は engine の `split` と `join`、`TrimSpace` と区切りが空の `Split` は `unicode` の表と `utf8` の decoder を残さずに natives.ts で文字列を走査し、`strings.Builder` は文字列の連結で伸ばし (engine 内では rope。`Cap` は `[]byte` だった場合の値)、整数と文字列の `slices.Sort` (つまり `sort.Ints` と `sort.Strings` も) は engine 組み込みの sort です (等しい要素は区別できないため。浮動小数点数は NaN と -0 のため Go の pdqsort のまま)。呼び出す場所で要素の型が整数か文字列の型と決まっている呼び出しはこの sort を直接呼ぶので、それだけをソートするプログラムには `Sort` とその pdqsort が残りません (`internal/lower/sortcall.go`)。ASCII 以外の rune の `unicode` の `ToUpper` と `ToLower` は engine の `toUpperCase` と `toLowerCase` で、engine の完全な対応が複数の rune になる場合は Go の単純な対応を返すので、大文字小文字を変換するプログラムにも `CaseRanges` が残りません。`internal/strconv` の `FormatFloat` と `AppendFloat` は float64 の桁を engine の `toExponential` と `toFixed` から取り (natives.ts の `ftoaDigits`。engine はちょうど中間の値を切り上げるので、Go と同じく偶数に丸め直す)、`fmt` の `fmtInteger` は 2^53 未満の値の桁を `uint64` ではなく `uint` で計算し、`internal/strconv` の多倍長 decimal は 32-bit platform と同じく 1 回に最大 28 bit ずつ shift します (`uint` 上の 60 bit の shift では桁が失われる)。`Atoi` の遅い経路は 10 進数に限った `ParseInt` を展開したものなので、`Atoi` を使っても `ParseInt` と `ParseUint` の基数、bit 数、区切りの `_` の処理は残りません。`fmt.Print`、`Println`、`Printf` と、`os.Stdout` か `os.Stderr` に書く `Fprint`、`Fprintln`、`Fprintf` は、プログラムがこれらの変数に代入せず、アドレスも取らず、閉じもしない場合、fmt の patch の `printStd` で文字列を書きます (`internal/lower/printcall.go`)。そのため、出力するだけのプログラムには `*os.File`、`internal/poll`、`syscall` のファイルの表が残りません。`regexp` は、すべてのパターンがコンパイル時にわかるプログラムがエンジンの `RegExp` で照合するように patch します。goesm はコンパイル時に各パターンを Go の `regexp/syntax` で解析し、RegExp が同じ一致を返し、バックトラックによる検索が最悪でも入力の長さの 2 乗に比例する時間で終わる場合に変換します。条件は、繰り返しの中に capture group と空文字列に一致する部分式がないこと、オートマトンの曖昧さが `^(\S+)\s+(.*)$` のような次数 1 の多項式までであることです。先頭に固定されないパターンでは、次数 1 の曖昧さは、分け方を試す範囲に一致の先頭になり得る文字が含まれない場合に限ります (`internal/lower/regexpjs.go`)。Go のエンジンは線形時間で照合するので、長い入力では RegExp のほうが時間がかかることがあります。たとえば `\d+x` は、数字の並びの各位置から一致を試します。そのプログラムには regexp のパーサーとエンジンが残りません。日付をパターンと `strconv.Atoi` で解析するカレンダーのパッケージは、`time` だけを使うものより gzip 後に 4.5 KB 大きくなります。変換しない場合は 55 KB 大きくなります。ほかのパターンをコンパイルし得るプログラムは、すべてのパターンを Go のエンジンで照合します。
* 置換・patch・override・natives は goesm に compile される固定の集合です。適用されるのは `$GOROOT/src` 以下の file だけで、依存 package の内容がこれを増やすことはできません。
* goesm が lower できない third-party 依存の関数は、stdlib の関数と同じく panic する stub になり、警告が出ます。program 自身の package は完全に lower できる必要があります。
* Go package 間の `//go:linkname`: target 付きの body の無い宣言 (compile-time instrumentation が hook を呼ぶために生成する "pull") は、その名前の Go 関数を呼びます (`internal/lower/linkname.go`)。呼び出しは ES module の import ではなく `@goesm/runtime` の symbol table を経由するので、link された package 同士でも Go の初期化順序が保たれます: 提供側の package は変数の初期化後に関数を登録し、それより前の結果を返さない呼び出しはそれまで延期されます。
* `//go:embed` は `string`、`[]byte`、`embed.FS` の変数を package directory の file で、package の他の変数より先に初期化します。
* instrumentation 向けの goroutine-local storage: otelc が追加する `runtime` の関数 (`GetTraceContextFromGLS` など) を program が使うと、各 goroutine が 2 つの値を持ち、新しい goroutine は生成元の値のコピー (otelc の `newproc1` patch と同じく `OtelContextCloner` で clone) で始まり、各 `await` は再開時に実行中の goroutine を戻します (`$rt.resumeG`)。使わない program にはコストがかかりません。

現状 (`go test ./test -run TestStdlibStatus -v`、golden テストは `testdata/semantics/stdlibuse`):

* Go source のまま compile でき native Go と一致: `errors` (`Is`、`As`、`Join`、`Unwrap`)、`strings` (検索、split、fields、大文字小文字、`Builder`、`Replacer`、`EqualFold`)、`strconv` (整数の format、`Atoi`、quote、`NumError`)、`sort`、`slices`、`maps`、`sync`、`unicode`、`unicode/utf8`、`math/bits`、`strconv` の 64-bit parse と最短表現の float format (`testdata/semantics/int64s`)。
* `fmt` (verb、flag、幅と精度、`Stringer` / `error` / `Formatter` / `GoStringer`、`%w` 付き `Errorf`、`Sscanf`)、`reflect`、`encoding/json` (struct tag、embedded、map、`RawMessage`、`Marshaler` / `TextMarshaler`、`Decoder` の stream、`UseNumber`、error) は `testdata/programs/fmtverbs`、`reflection`、`jsoncodec`、`jsonlegacy` で native Go と一致します。
* `time` (`Sleep`、`Stop` / `Reset` 付きの `Timer`、`Ticker`、`AfterFunc`、`select` 内の `After`、時計、`Duration`、format と parse) は `testdata/programs/timers` で native Go と一致します。
* `crypto` の hash と暗号 (MD5、SHA-1、SHA-2、SHA-3、HMAC、AES-GCM、CTR)、`crypto/rand` (host の `crypto.getRandomValues`)、`math/rand`、`math/rand/v2`、`hash/maphash`、`sync/atomic.Value`、slice から配列 pointer への変換は `testdata/programs/stdlibmisc` で native Go と一致します。
* `math/big` (`testdata/programs/mathbig`) と公開鍵暗号 (`crypto/rsa`、`crypto/ecdsa`、`crypto/ecdh`、`crypto/ed25519`、`crypto/x509`。`testdata/programs/cryptopk`) は native Go と一致します。`uint` が JS の number なので、goesm では `math/big.Word` は `uint32` (32-bit platform と同じ `_W = 32`)、`crypto/internal/fips140/bigmod` は 32-bit limb を使います。乗算の内側ループと `bits.{Add,Sub,Mul,Div,Rem}32` は native です。P-384、P-521、Ed25519 の 64-bit limb の体演算は BigInt 上で動くので遅いです。
* `iter.Pull` / `Pull2` (`testdata/programs/iterpull`): `Pull` か `Pull2` を参照する program では、yield を直接呼ぶだけで他にブロックしない関数リテラルのシーケンスに、本体を JS のジェネレータにしたものも付けます (`internal/lower/seqgen.go`)。`Pull` はそのジェネレータを同期的に進めます。それ以外のシーケンスは goroutine 上の coroutine として動かし、`coroswitch` は channel で制御を渡します (patch)。coroutine の関数リテラルは、`Pull` か `Pull2` を参照する program でだけ blocking 解析上の関数値として数えます。`next` と `stop` は、ローカル変数として呼ぶだけであれば、そうした program でも関数値として数えません (`TestAsyncStaysLocal`)。

## 10. Tooling compatibility と security

* `.go` file は普通の Go で、goesm 専用 syntax・magic comment はありません。唯一の directive である `//goesm:import` は JavaScript を呼ぶコードだけが使い ([docs/js-imports.ja.md](https://goesm.dev/ja/reference/js-imports.md))、それを使うコードは goesm でしかビルドできなくなります。fixture は `go vet` / `go build` / `go run` がそのまま通り、golden テストはまさに native Go 実行と比較しています。package graph は go command が解決したもので、govulncheck 等の call graph も変わりません。
* 依存 package を import しても goesm 側でコードは実行されません。compiler plugin や third-party の extension 機構はありません。esbuild の plugin は `goesm build -split` で使う goesm 自身の resolver だけで、出力した tree には plugin は不要です。stdlib の置換、patch、natives (§9) は goesm 内の固定の集合で、`$GOROOT/src` にだけ適用されます。stdlib 以外で body の無い Go 関数は、`//go:linkname` が program 内の別の Go 関数を指す場合を除いて error であり、goesm への hook にはなりません。`-toolexec` は `go build -toolexec` と同じく、user が指定した program を実行します。
* 懸念点: (1) go/packages は `go list` を実行するので、`GOFLAGS` などの環境、`go.work`、`GOPROXY` からの module 取得について go command と同じ trust 境界を継承します (goesm がそれを広げることはありません)。(2) 生成コードは Go の型安全性に依存しており、goesm の lowering bug は JS 上の memory safety ではなく誤動作として現れます (JS 自体は memory safe)。(3) 生成 ESM は `globalThis.reportError` 等の host API を使います。DOM は `syscall/js` から使い ([docs/dom.ja.md](https://goesm.dev/ja/reference/dom.md))、goesm 独自の DOM binding はありません。(4) `GoPanic` の message や source map の `sourcesContent` は Go source を含むため、公開 bundle に Go source が載ります (`SourcesContent` を外すオプションは未実装)。

## 11. 実装済み / 未実装 / native Go との差分

**実装済み (native Go との golden テストで確認)**: package import、関数、多値返却、named result、closure、struct (値 copy、method、pointer method、embedding と promotion、複合リテラルの key としての promote された field、比較)、array、slice (aliasing、append、copy、re-slice、nil)、map (struct / interface key、comma-ok、delete、nil map、range)、pointer (変数・field・要素・`new`、identity)、defer (評価順・named result の変更・LIFO)、panic / recover (runtime error、re-panic)、interface (dispatch、type assertion、type switch、比較、nil interface と nil pointer の区別)、generics (generic 関数、制約と制約の method、interface 経由も含む generic type、型引数に従う演算子と変換、Go 1.27 generic methods、型 identity、generic 関数の local type (gc と同じく関数の型 parameter を先頭の暗黙の型引数として取る))、method value / method expression、switch / fallthrough / label 付き break・continue、`goto` (後方への jump は state machine になる)、range over int、range-over-func (入れ子の文からの break / continue / return、label 付き branch、body 内の `defer` (外側の関数の frame に積む) と `goto`、body 内の blocking 操作と select、yield を誤用する iterator に対する Go と同じ panic)、Go 1.22 の per-iteration loop 変数 (それより前の Go version の file では共有)、Go package 間の `//go:linkname`、`//go:embed`、`//goesm:import` による JavaScript と TypeScript の呼び出し (`TestJSImport` で期待出力と比較)、変換した引数と戻り値による JavaScript からの Go の呼び出し (`TestJS`)、`-toolexec` による compile-time instrumentation、8/16/32-bit 整数の wrap、整数 0 除算 panic、UTF-8 string と rune、goroutine、unbuffered / buffered channel、close、channel の range、select (default 含む)、`runtime.Goexit` / `Gosched`、package 変数の init order と `init()`、§9 に挙げた stdlib package。

**未実装** (goesm 診断になるか、動作しないもの):
* 64-bit の `int` と `uint` の正確な表現 (number のまま、§5 参照)
* §7 を超える `unsafe` と `reflect`
* Go が知らない未完了の処理 (JavaScript の timer、I/O) が host に残っている間の deadlock 検出、goroutine の preemption、goroutine-local な recover 状態

**native Go との既知の差分** (最初の 2 項目は `TestKnownGaps` の `IntWrap`・`UintWrap`・`AppendCap` で差分が存在することを固定。残りは決定的に比較できないため文書のみ):
* `int` と `uint` は 2^53 を超えると不正確、64-bit overflow で wrap しない (`uint(0)-1` が `-1`)。`int64` と `uint64` は正確。ただし負の `i` の変換 `uint(i)` を直接大小比較する場合 (bounds check の慣用句 `uint(i) < uint(len(s))`) は wrap した値として比較する。
* 変数宣言を越える後方 `goto` は、Go なら新しい変数を作るところで同じ変数を再利用する。違いが分かるのは jump の前に作った closure だけ。
* `append` の capacity 拡張は近似 (size class の丸めなし)。`cap()` の値が gc と異なることがある。
* map の range 順は挿入順 (Go はランダム)。どちらも仕様上未定義。
* deferred 関数が実行時にしか分からない場合 (関数値、interface の method) は、そこから呼んだ関数の中の `recover()` も効く (Go では直接呼んだときだけ)。
* goroutine は blocking 点でしか切り替わらない (協調的)。blocking する exported 関数は JS からは Promise を返す。データ競合と並列実行への影響は [docs/concurrency.ja.md](https://goesm.dev/ja/reference/concurrency.md) にまとめている。
* 動的呼び出しの blocking 判定は保守的 (§5) なので、不要な `await` が入ることがある (意味は変わらない)。
* `print` / `println` は Go ランタイムと同じ書式で stderr に出力するが、ポインタ・map・channel・func・スライス・interface の値は実アドレスではなく固定のアドレスを表示する。
* `sync`: 解析 (§5) が同期のままにした `Lock` は、待つ必要があると panic する。解析はこれを起こさないはずなので、goesm の bug である。最初の呼び出しの関数が block している間に 2 回目の `Once.Do` を呼ぶと、待たずに panic する。unlock 済み `Mutex` の unlock などの誤用は fatal error ではなく recover できる panic。`runtime.Caller` / `Callers` / `Stack` は何も報告せず、`SetFinalizer` は何もしない。
* `unicode.ToUpper` と `ToLower`、つまり ASCII 以外の `strings.ToUpper` と `ToLower` は engine の Unicode のバージョンに従います。engine のものより新しいバージョンで追加された大文字と小文字の組 (Node.js 24 では Unicode 17 のもの) は変換しません。
* Bun では JavaScriptCore が NaN の payload を保たないので、NaN の `math.Float64bits` が Go と異なることがある。
* `time`: timer の channel は `GODEBUG=asynctimerchan=1` と同じく buffer が 1 つある (`len(t.C)` が 1 になり得る)。`Stop` と `Reset` は channel を空にするので、Go 1.23 と同じくその後に古い値を受信することはない。`Timer` と `Ticker` には unexported field が 1 つ多く、`%+v` で表示される。timer は host の event loop が処理できたときに発火するので、走り続ける goroutine があると遅れる。
* `net/http` の server である `ListenAndServe` と `fetchHandler`: request の body は handler の実行前に全部読む。response は、書き込みで buffer が埋まった時点ではなく、handler が戻るか flush した時点で送る。HTTP/2、`ListenAndServeTLS` による TLS、`Hijack`、trailer、1xx の情報応答はない。`net.Listener` を渡す `Serve` は偽 network を使い、`Shutdown` は処理中の request を待たずに戻る。`Server` の field のうち `Addr`、`Handler`、`BaseContext`、`ErrorLog` 以外は無視する。

## 12. 次に実装すべき 3 項目

1. **goroutine runtime の完成**: goroutine-local な panic / recover 状態 (async 境界を跨ぐ recover)。
2. **64-bit 演算の速度**: `int64`/`uint64` は BigInt なので、64-bit limb の上に作られたコード (P-384 / P-521 の体演算、`crypto/ed25519` など) は native よりかなり遅い。goesm で `math/big` と `crypto/internal/fips140/bigmod` が使う 32-bit word のように、重いものから 32-bit や number ベースの経路にする。
3. **bundle size**: 使われない package 変数と型は落ちるようになったが、`fmt` は `reflect` とその method から届くものすべてを残す (`fmt` の hello world は gzip で約 130 KB)。
