feat(asm): resolve external GOOBJ symbols from archive data

docs/DEFERRED.md

@@ -8,49 +8,27 @@ why, the options on the table, and the trigger that should reopen it.
 
 ## GOOBJ external (cross-package) symbol references
 
-**Status:** deferred (v0.15.0, 2026-08-02).  The GOOBJ emitter resolves only
-symbols defined in the file being assembled; a reference to any other symbol
-is rejected.
+**Status:** resolved (v0.29.0+, 2026-08-07).
 
-**Why it is deferred.**  GOOBJ symbol references are *positional*: a
-reference is a `{PkgIdx, SymIdx}` pair, where `SymIdx` is the index of the
-symbol in the *referenced package's* symbol-definition table.  That ordering
-is not derivable from the reference site — it lives in the referenced
-package's gc export data (the iexport binary format, which evolves with the
-toolchain).  `cmd/asm` reads it with `cmd/internal` readers gasm cannot
-import, so emitting external references means either parsing export data
-ourselves or taking a dependency that does.
+**Approach taken.**  Instead of parsing the compiler's iexport data (which
+would have required either `golang.org/x/tools` or an in-house parser), the
+resolver reads the **GOOBJ data directly** from the target package's `.a`
+archive.  The `.a` file contains a `_go_.o` member whose GOOBJ format is the
+same one gasm writes — the parser reuses the same layout (`blkSymdef`,
+`blkNonpkgdef`, the string table), so no new dependency was needed.
 
-**What works today.**  Single-package objects: every symbol the file defines
-(as `TEXT` or `GLOBL`, static or exported) and every reference to them.
-This covers the production use case — the go-flac / go-lz4 kernels carry no
-`FUNCDATA`/`PCDATA`, hence no references into `runtime`, and the Go side
-references the assembly symbols, never the reverse.  Such a package builds
-with its assembly object replaced by a gasm-emitted one.
+**How it works.**
 
-**The options, when we return.**
+1. `go list -json -export <pkg>` finds the target package's `.a` file.
+2. `extractGOOBJ` reads the ar archive, finds the `_go_.o` member, skips
+   the `"go object …\n!\n"` preamble and parses the GOOBJ header.
+3. `goobjFile.symbols()` walks `blkSymdef` and `blkNonpkgdef` in definition
+   order — the same order the linker uses — to build the symbol → index
+   mapping.
+4. `resolveExternalSymbols` wires the resolved `{PkgIdx, SymIdx}` into the
+   GOOBJ emission.
 
-1. **`golang.org/x/tools/go/gcexportdata` as a production dependency.**
-   The straightforward path: read each imported package's export file
-   (paths from `-importcfg` or `go list -export`), assign symbol indices in
-   its symbol order, write `PkgIndex`/`Autolib` entries (fingerprints from
-   the export files' build IDs) and positional references.  Robust across
-   toolchain versions — `x/tools` tracks the format.  **Cost:** the first
-   production dependency beyond the standard library, an explicit deviation
-   from the "production code depends only on the standard library"
-   principle in the README.  Requires the user's explicit agreement.
-2. **A minimal iexport parser of our own.**  Preserves self-containment.
-   Substantial effort and inherently fragile: the format is an internal
-   contract that changes with Go releases, so the parser needs a
-   version-gated fallback and regression tests against several toolchains.
-3. **Shell out to the toolchain for symbol metadata.**  Consistent with the
-   existing GOOBJ preamble probe (which already runs `go tool asm`), but no
-   toolchain command exposes a package's symbols *in definition-index
-   order* — `go tool nm` sorts differently — so this does not solve the
-   core problem on its own; it would only feed option 1 or 2.
-
-**Trigger to reopen.**  An assembly file that needs a cross-package
-reference — in practice `FUNCDATA $…, runtime·…(SB)` (stack maps / GC
-metadata written in assembly), or any kernel that calls into another
-package directly.  Until then, option 3's limitation is moot and the
-single-package emitter suffices.
+The resolver is invoked automatically when `img.Externals` is non-empty; it
+runs `go list` as a subprocess (consistent with `toolchainObjectPreamble`
+which already calls `go tool asm`).  All symbol data is cached per package
+for the lifetime of the GOOBJ emission.