feat(v4/spec): VBSpec Stage A — symbolic shape contracts per brick

Adds cppmega_v4.spec.shape_contract with the foundation pieces needed
for the Visual-Builder spec layer (VisualBuilderSpec.md §3.1, §6 A).

  - ShapeExpr: tuple of textual arithmetic expressions over a fixed
    vocabulary of named dims (B, S, H, nh, nkv, head_dim, MLA LoRA
    splits, MoE counts, sliding/coarse params, SSM/MTP-specific dims).
    Sandboxed eval (empty globals + named-dims-only locals); raises
    ResolveError on missing names or non-positive results.

  - BrickShapeContract: dataclass declaring per-brick inputs / outputs
    (ShapeExpr per port) + symbolic element-count exprs for params /
    activations / kv-cache + frozenset of side-channel needs
    ('doc_ids', 'token_ids') + opaque_shape flag for data-dependent
    bricks (NSA, CSA/HCA, DSv4 sparse).

  - Registry: contract_for(kind), register_contract(kind, c),
    registered_kinds(). Pre-populated with contracts for ALL 22
    BLOCK_BUILDERS kinds (norm/proj, SDPA attention, MLA family, CCA,
    linear-attn, SSM, MoE, sparse, cross-attn / MTP).

CI tripwire test_every_block_builder_kind_has_contract guarantees
new bricks can't ship without a contract (roadmap §7 risk #3).

Tests (tests/v4/test_vbspec_stage_a.py, 45 cases):
  - ShapeExpr validation + arithmetic resolve (incl. complex MLA expr)
  - free_names() word-boundary check (head_dim doesn't match 'H')
  - missing-dim and non-positive-resolve errors
  - BrickShapeContract field validation (rank-1 byte exprs)
  - registry overrides + unknown-kind error
  - parametrized contract coverage over every BLOCK_BUILDERS kind
  - system: GDN / gated_attention / bailing_mla / MoE resolve under
    real Qwen3-Next + Ling 2.6 dim_envs with sane param/activation
    numbers; KV-cache scales linearly with S; MoE activations scale
    linearly with top_k; opaque bricks are flagged; doc_ids / token_ids
    needs are declared on the right bricks.

Full v4 regression: 647 passed / 5 skipped / 0 failed.

Author: apstenku123

cppmega_v4/spec/__init__.py

@@ -0,0 +1,28 @@
+"""Visual-Builder spec layer over V4 bricks.
+
+See ``VisualBuilderSpec.md`` (repo root) for the full design.
+
+Stage A surface (this commit):
+  - shape_contract.ShapeExpr / BrickShapeContract / contract_for /
+    register_contract / registered_kinds / ResolveError
+"""
+
+from __future__ import annotations
+
+from cppmega_v4.spec.shape_contract import (
+    BrickShapeContract,
+    ResolveError,
+    ShapeExpr,
+    contract_for,
+    register_contract,
+    registered_kinds,
+)
+
+__all__ = [
+    "BrickShapeContract",
+    "ResolveError",
+    "ShapeExpr",
+    "contract_for",
+    "register_contract",
+    "registered_kinds",
+]