meta: emit and cache package semantic summaries

[luoliwoshang]

Summary

Introduce package-level semantic metadata production, persistent cache storage, and a whole-program read-only view for future link-time dead-code analysis.

This PR implements the producer and data path:

• emit ordinary symbol reachability and function-level semantic demands from CL/SSA
• emit type children, concrete method slots, and structural interface method signatures
• serialize each package summary into a versioned, mmap-friendly .meta file
• write metadata on cache misses and mmap it on cache hits
• merge package-local symbol namespaces into a lazy GlobalSummary

Related design proposal: #1853

Scope and data flow

CL/SSA emission
  -> meta.Builder
  -> PackageMeta
  -> .meta build-cache entry
  -> cache-hit mmap loading
  -> GlobalSummary

The emitted facts are:

• OrdinaryEdges: ordinary calls and symbol references extracted from LLVM IR
• FuncDemand: interface conversion, interface method call, named reflection method, and dynamic reflection method demands
• TypeChildren: direct component types needed for type reachability
• MethodInfo: concrete method name/signature plus IFn and TFn symbols
• InterfaceInfo: structural interface method names and signatures

The existing dead-code-drop configuration currently gates whether these summaries are collected and required in cache entries. It does not make this PR responsible for deciding what is dead or rewriting linked IR.

Cache miss path

1. Cache use is bypassed when caching is disabled, the package is main, -a/force rebuild is active, or no package fingerprint is available.
2. For a package that was not loaded from cache, metadata collection is requested only when the dead-code-drop configuration is enabled.
3. cl.NewPackageExWithEmbedMeta creates a package-local meta.Builder only when metadata is requested.
4. CL/SSA records semantic facts while compiling. At package completion, FinishMetaCollection extracts ordinary LLVM symbol edges, builds the immutable PackageMeta, and attaches it to the compiled package.
5. Non-main packages are saved to the build cache. The archive is stored as usual; when metadata is enabled, PackageMeta.WriteTo writes a temporary .meta file which is atomically published with rename; the manifest is stored separately.

Cache hit path

1. The archive and manifest must exist and the manifest must parse successfully.
2. When metadata is enabled, the matching .meta file is mandatory. meta.Open validates its header and sections and maps it read-only; a missing or invalid file turns the lookup into a cache miss.
3. When metadata is disabled, the .meta file is neither required nor opened, and the package's Meta remains nil. Existing archive-only cache entries therefore remain usable.
4. A successful hit restores the archive path, linker arguments, runtime flags, and mapped PackageMeta, then marks the package as a cache hit. Compilation still registers package types, but does not rebuild metadata or regenerate package code.

The cache validation helper follows the same rule: archive and manifest are always required, while .meta is opened and closed for validation only when metadata is required.

Version 1 wire format

The file uses magic LLPM, version 1, little-endian uint32 values, and 4-byte-aligned sections.

Header (36 bytes)
  [0:4]   magic = "LLPM"
  [4:8]   version = 1
  [8:36]  seven absolute section offsets, in order:
            StringTable
            Symbols
            OrdinaryEdges
            FuncDemand
            TypeChildren
            MethodInfo
            InterfaceInfo

StringTable
  starts at byte 36
  concatenated string bytes
  zero padding to a 4-byte boundary

Symbols
  nsyms
  records[nsyms] = {nameOff, nameLen, reserved}          // 12 bytes

OrdinaryEdges: CSR<Symbol>
  nsyms
  offsets[nsyms+1]
  data[] = Symbol                                        // 4 bytes

FuncDemand: CSR<localFuncDemand>
  nsyms
  offsets[nsyms+1]
  data[] = {kind, target, extra}                         // 12 bytes

TypeChildren: CSR<Symbol>
  nsyms
  offsets[nsyms+1]
  data[] = Symbol                                        // 4 bytes

MethodInfo: CSR<localMethodSlot>
  nsyms
  offsets[nsyms+1]
  data[] = {nameOff, nameLen, mtype, ifn, tfn}           // 20 bytes

InterfaceInfo: CSR<localMethodSig>
  nsyms
  offsets[nsyms+1]
  data[] = {nameOff, nameLen, mtype}                     // 12 bytes

Header section offsets are absolute byte offsets. CSR offsets are record indexes into that section's flat data array, not byte offsets. Every CSR nsyms equals the Symbols count. Symbol values index the package-local Symbols section. Name offsets are relative to StringTable, name lengths exclude alignment padding, and the Symbols reserved field is written as zero. The final InterfaceInfo section extends to EOF.

FuncDemand.kind values are:

Value	Kind	Local payload
1	DemandUseIface	target is a type symbol
2	DemandIfaceMethod	target is an interface symbol; extra is its method index
3	DemandNamedMethod	target is a StringTable offset; extra is the string length
4	DemandReflectMethod	no additional payload

GlobalSummary

NewGlobalSummary interns every package-local symbol name into one global Symbol namespace and builds a locToGlb translation table for each package. Method names use a separate Name namespace.

For duplicate symbols, the summary selects one owner and prefers packages carrying semantic function, method, interface, or type facts over ordinary-edge-only copies. Public queries lazily translate the selected owner's package-local data into global IDs:

• OrdinaryEdges
• FuncDemands
• TypeChildren
• MethodSlots
• IfaceMethods

GlobalSummary borrows its input PackageMeta values. Mmap-backed package summaries must therefore remain open for the lifetime of the global summary and any aliased query results.

Tests

• metadata builder, binary validation, mmap lifetime, formatting, and global translation tests in internal/meta
• cache behavior for metadata-enabled and metadata-disabled entries in internal/build
• focused SSA/CL emission tests for type, method, interface, and reflection facts
• _testmeta golden tests covering emitted package summaries

Out of scope

This PR intentionally does not include the metadata consumer or mutate linked output. The following work has been removed and belongs in follow-up PRs:

• dead-code reachability decisions
• DCE pass integration
• LLVM global/type initializer override rewriting
• link-time dead-code override application
• _testdrop symbol-retention and drop regression cases

[codecov]

Codecov Report

❌ Patch coverage is 95.03817% with 39 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
internal/build/collect.go	22.22%	5 Missing and 2 partials ⚠️
internal/meta/builder.go	96.66%	4 Missing and 3 partials ⚠️
internal/build/cache.go	86.66%	2 Missing and 2 partials ⚠️
internal/meta/format.go	96.49%	2 Missing and 2 partials ⚠️
internal/meta/global.go	97.12%	2 Missing and 2 partials ⚠️
internal/meta/meta.go	95.74%	2 Missing and 2 partials ⚠️
cl/compile.go	66.66%	2 Missing and 1 partial ⚠️
internal/build/build.go	77.77%	1 Missing and 1 partial ⚠️
ssa/interface.go	92.85%	1 Missing and 1 partial ⚠️
ssa/package.go	88.23%	1 Missing and 1 partial ⚠️

📢 Thoughts on this report? Let us know!