Plumb TensorEncoding into TensorSpec.metadata (#469)

[michalharakal]

Closes #469.

Summary

First step of the P0-1 track in the NPU / IREE roadmap: make the existing TensorEncoding sealed interface flow through the graph IR, so that downstream compile stages (StableHLO converter, future IREE lowering) can preserve Q4_K / Q8_0 / TernaryPacked / TurboQuant layouts instead of silently re-materializing everything as FP32.

Two commits, each independently reviewable:

1. TensorSpec + TensorData encoding accessors

Additive helpers under sk.ainet.lang.tensor.ops:

• TENSOR_ENCODING_METADATA_KEY — single source of truth for the metadata key.
• TensorSpec.tensorEncoding: TensorEncoding? — extension getter. null means "unknown / not carried" — intentionally distinct from TensorEncoding.Dense.
• TensorSpec.withTensorEncoding(TensorEncoding?) — returns a copy with the encoding set (or removed when passed null), preserving all other metadata entries.
• TensorData<*, *>.inferTensorEncoding() — centralized mapping from concrete TensorData subclasses to TensorEncoding. Collapses to this is PackedBlockStorage -> this.encoding today (covers Q4_K, Q8_0, TernaryPacked, TurboQuant uniformly) but gives us a single hook for future non-packed layouts.

Unit-tested for: unset reads, round-trips on Q8_0 / Q4_K / TernaryPacked / Dense, clearing via null, preservation of unrelated metadata, and overwrite semantics. 8 cases total, all green.

2. TraceToGraphBuilder.finalize() propagation

When finalize() resolves an unresolved tensor through the session, it now also derives the tensor's encoding via inferTensorEncoding() and attaches it to:

• the produced weight / input node's output spec, and
• every outgoing edge's tensor spec.

Applies symmetrically to both branches — the weight-node branch (when extractFloatArray succeeds) and the input-placeholder branch (when it doesn't, which is exactly the path a Q8_0-backed weight used to fall into today, silently losing its quantization).

Scoping notes / surprise wins

• TensorSpec already has a metadata: Map<String, Any> field — zero schema change needed.
• TensorEncoding already models Q4_K, Q8_0, TernaryPacked, TurboQuantPolar, TurboQuantPolarQjl, Opaque, and Dense — no new enum.
• Every packed quantized TensorData already exposes encoding: TensorEncoding via the PackedBlockStorage interface, so the inference helper is one line.

Out of scope (follow-up PRs in the P0-1 track)

• Teaching StableHloConverter / quant-aware emitters to read tensorEncoding and emit stablehlo.uniform_quantize or quant dialect ops. The metadata has to flow first, then the emitter reads it.
• Plumbing at the loader boundary (StreamingGgufParametersLoader). The loader produces TensorData, not TensorSpec; the spec-level attachment already happens at the trace-builder boundary where the spec is actually born.
• Changing QuantizedMatmul.matmulAutoDispatch(). Runtime dispatch stays for CPU; the goal here is only that compile-time (IR) paths stop being blind to quantization.
• Parameterizing Tensor<DType, V> on a quant type parameter. Heavier redesign, and likely the wrong choice — keeping this as metadata on TensorSpec is lighter and composes better with the existing sealed TensorEncoding.

Test plan

• ./gradlew :skainet-lang:skainet-lang-core:jvmTest --tests \"sk.ainet.lang.tensor.ops.TensorSpecEncodingTest\" — 8/8 green
• ./gradlew :skainet-compile:skainet-compile-dag:jvmTest — green (no regressions from the finalize() change)
• CI: full multiplatform build across all targets

🤖 Generated with Claude Code

[github-actions]

📖 Documentation Preview

The documentation has been built successfully for this PR.

Generated Files:

• Operator documentation: docs/modules/operators/_generated_/
• JSON schema output: operators.json

Artifacts:

• Download the documentation-preview-471 artifact to view the complete documentation locally.

This comment will be updated automatically when the PR is updated.