feat(compile): composite emission seam, GELU legalization pass, @Lowering (#1342, part 2)

[michalharakal]

Summary

Part 2 of #1342, on top of #1344: the op metadata becomes a per-target lowering decision.

• LoweringSpec + ConversionContext.emitComposite (sk.ainet.compile.hlo.lowering): one record per fused-able op — composite name, the node parameters that become composite_attributes, a version, and a single decomposition builder. spec.lower(...) emits stablehlo.composite "skainet.gelu" %x {composite_attributes = {approximate = false}, decomposition = @skainet_gelu_approximate_false_2x3xf32, version = 1 : i32} : (T) -> T plus one func.func private per (op, attributes, type) when context.granularity?.keepFused(op) is true, and the same builder's lines inline otherwise. This is the first consumer of OpGranularityPolicy, which was threaded through the converter but never read.
• Module trailer: helper functions are emitted after the entry function (ConversionContext.emitModuleTrailer, claimSymbol for dedup), so MlirParser still finds @main first and MlirValidator's module-wide SSA rule holds because the helper bodies draw names from the shared counter. The text-level StableHloOptimizer passes tolerate the two-function module (tested).
• Specs: GeluLowering.spec (skainet.gelu, attribute approximate) and ErfLowering.spec (skainet.erf); convertGelu and the erf case of UnaryMathConverter go through spec.lower. Portable emission is byte-identical to feat(ops)!: exact (erf) GELU and erf op (#1342, part 1) #1344.
• GeluApproximationLegalizationPass (skainet-compile-opt): a target with no erf lowering rewrites gelu(approximate = false) → gelu(approximate = true) and records legalizedFrom / maxAbsError = 4.8e-4 on the node plus a GELU_APPROX_LEGALIZED diagnostic; erf nodes are left to fail loudly. Opt-in per target via TargetOptimizers.registerDagPasses.
• @Lowering annotation (sk.ainet.lang.ops) on TensorOps.gelu / erf; OperatorDocProcessor writes a lowering field into operators.json (both FunctionDoc model copies default it to empty, so old JSON still deserializes); the coverage matrix gains a Lowering column (composite · decompose · native).
• Docs: a "Fused ops and stablehlo.composite" section in the HLO tutorial; CHANGELOG.

Nothing registers a fused policy or the legalization pass in-repo yet — both are seams a target plugs into (FusedOpAllowList("my-npu", setOf("gelu")), TargetOptimizers.registerDagPasses("my-npu") { … }), as the #1342 lowering-metadata section describes. Composite emission is currently unary-only (emitComposite requires one operand); SDPA (#1343) will extend it.

Test plan

• CompositeEmissionTest (hlo): composite + private fn after @main, MlirParser entry = @main, MlirValidator clean, inline when policy is null or decomposes gelu, dedup per (attributes, shape), skainet.erf, composite body ≡ inline decomposition modulo SSA names, convertWithOptimization on a two-function module
• GeluApproximationLegalizationPassTest (opt): rewrite + recorded parameters + diagnostics + edges, no-op on tanh nodes, idempotent, registry opt-in through dagPipelineFor vs a portable target
• OperatorDocProcessorTest.testLoweringFlowsIntoJson
• ActivationOperationsConverterTest / UnaryMath erf tests from feat(ops)!: exact (erf) GELU and erf op (#1342, part 1) #1344 unchanged
• apiDump, generateDocs (matrix column), scripts/pr-gate.sh --quick and full gate