Add typed PredicateCell composition, views and selection (spec #406)

docs/tileop-usage/element-if.md

@@ -104,9 +104,10 @@ predicate::atomic_add(destination, byte_offsets, values, active);
 把这些调用放进循环就能编译。
 
 两条路径使用相同架构中的 predicate/ExecutionMask 概念，但公开支持边界
-不同。显式 adapters 首版只覆盖 Local VEC CUBE_M32、静态有效区域和
-FP32/S32/U32，尚无 predicate 逻辑组合；本页 element-if 已支持的组合条件
-不能据此推广到 `Predicate<Basis>`。显式 `atomic_add` 使用 MSCATTER_ADD
+不同。显式 adapters 支持 Local VEC CUBE_M16/M32 的静态比较、谓词逻辑
+组合、选择与受限 typed views/拼接；indexed memory 仍仅覆盖 M32，
+FP32/S32/U32。详细类型与形状边界见独立 adapters 文档，不能将本页
+pragma 支持范围与 `Predicate<Basis>` 混为一谈。显式 `atomic_add` 使用 MSCATTER_ADD
 ExecutionMask，本页 histogram 示例的已验收 profile 则使用 MGATHER.ADD，
 不能互相替代其 dtype、memory-order、返回值或验证结论。
 

docs/tileop-usage/options.md

@@ -18,7 +18,10 @@
 `predicate::compare_scalar` 的强类型结果可以直接供给
 `predicate::scatter`，或作为 `predicate::atomic_add<Invert>` 的
 ExecutionMask。`Invert` 是编译期布尔参数，默认 false，不属于
-`fixp::Options`。当前支持边界、byte-offset 单位和未支持的逻辑组合见
+`fixp::Options`。显式 `logical_and/or/xor` 组合产生 U8-basis PredicateCell，
+`select/select_scalar` 可选择不同 basis 的 Numeric payload；`subview` 保留
+basis，`concatenate` 只返回已封闭 parent。混合逻辑 `logical_numeric<6/7/8>`
+返回 Numeric U8 而非谓词。当前支持边界和 CELL/byte-offset 单位见
 [PredicateCell adapters](predicate-adapters.md)。
 
 ## 1. 快速开始

docs/tileop-usage/predicate-adapters.md

@@ -17,6 +17,10 @@ sufficient. Keep the new TileOP headers and matching compiler together. Do not
 replace headers in an older installed SDK before that compiler dependency is
 available.
 
+The spec #406 composition/view APIs additionally require matching LLVM
+PredicateCell result-identity propagation. The earlier adapter compiler alone
+does not establish that contract, even if a simple straight-line case compiles.
+
 Include `common/pto_tileop.hpp` when targeting Linx. The experimental
 `pto::predicate` API keeps a comparison result distinct from ordinary numeric
 Tiles and packed GPR predicates:
@@ -67,17 +71,19 @@ tree that takes precedence over the selected headers.
 
 ## Carrier and consumer contract
 
-The first implementation admits static valid shapes, Local VEC CUBE_M32,
+The adapters admit static valid shapes, Local VEC CUBE_M16/M32,
 FP32/S32/U32 comparison and value operands, and S64/U64 **byte displacements**.
-The value type, valid region and layout must match the comparison basis.
+Valid region and layout must match the predicate, but its comparison basis
+does not constrain the FP32/S32/U32 payload type. Indexed memory remains
+CUBE_M32-only. M16 supports comparison, logical composition, selection,
+typed subviews and concatenation, not indexed memory.
 Offsets may have a different physical capacity, but must cover that valid
 region. `destination` must have the same element type as `values`.
 
 `scatter` binds the PredicateCell directly to the explicit MSCATTER_MASK
 operand. It does not convert it with TCVT or reinterpret it as an ordinary
 numeric U8 Tile. This follows the executable
-`IndexedTLSUPredicateDescriptorLegal` helper; the instruction-page wording
-discrepancy is tracked in PTO-ISA/pto-spec #349.
+`IndexedTLSUPredicateDescriptorLegal` helper and the contracts in spec #406.
 
 `atomic_add` requires the compiler builtin `ew_mscatter_add_predicate` and
 emits MSCATTER_ADD with a PredicateCell ExecutionMask. `true` inverts the
@@ -87,11 +93,52 @@ addresses, probe memory or enqueue atomic RMWs. Structural legality checks
 still apply. Replacing inactive addends with zero is not equivalent.
 
 `Predicate<Basis>` cannot be default-constructed by callers or imported from
-an arbitrary U8 Tile. Its carrier is intentionally private. Ordinary TAND is
-not a PredicateCell logical operator. Predicate composition, GPR selection,
-first-set-bit operations, dynamic valid shapes, M16 and cross-call predicate
+an arbitrary U8 Tile. Its carrier is intentionally private. GPR selection,
+first-set-bit operations, dynamic valid shapes and cross-call predicate
 ABI/spill support are not provided by this experimental interface. Keep
 producer and consumers together in an optimized, inlined region.
 
+## Logical composition and selection
+
+```cpp
+auto lower = predicate::compare_scalar<CmpMode::GE>(values, low);
+auto upper = predicate::compare_scalar<CmpMode::LT>(values, high);
+auto active = predicate::logical_and(lower, upper);
+predicate::select(result, active, true_values, false_values);
+predicate::select_scalar(result, active, true_values, 0u);
+predicate::atomic_add(destination, byte_offsets, values, active);
+```
+
+`logical_and`, `logical_or` and `logical_xor` use U8 TAND/TOR/TXOR.
+Both inputs must have identical valid and physical shapes and layouts, but
+their original comparison bases may differ. The result is a private
+PredicateCell with **U8 basis**, not a Numeric U8 Tile. Numeric inputs are not
+implicitly admitted. `logical_numeric<6/7/8>(predicate, numeric)` explicitly
+combines a predicate with same-shape S8/U8 Numeric data and returns a **Numeric
+U8 Tile**, which cannot be passed as a typed predicate consumer argument.
+
+`select` selects between Numeric true/false Tiles; `select_scalar` selects
+between a Numeric true Tile and a raw scalar false value. The predicate basis
+may differ from the payload type. Valid shapes/layouts must still match.
+
+## Typed views and closed assembly
+
+`subview<OffsetCells, Columns>(predicate)` materializes a typed TMOV with
+B.SUBVIEW. Offsets are in **128-byte CELL units**, not elements or bytes.
+Columns must cover complete U8 CELLs (4 columns for M32, 8 for M16), fit the
+source valid region, and use at most 64KB view capacity. Basis is preserved.
+
+`concatenate(left, right)` emits INIT/LAST B.ASSEMBLE writers and returns only
+the closed parent. Both inputs must be U8-basis logical results with identical
+full physical rows, complete equal-size valid column regions and layout;
+writer capacity is at most 64KB. The output joins their columns. For example,
+an M32 32x8 logical result can be split into `subview<0, 4>` and
+`subview<1, 4>`, then concatenated. Arbitrary OPEN-parent mutation is not exposed.
+
+These calls do not request an ExecutionMask on the logical writer or expose
+MERGE. ZERO/MERGE, canonical-byte definedness and Q-generation pinning across
+wait/trap recovery remain model/runtime requirements; object tests do not
+prove those semantics or a complete TopK kernel.
+
 Object/assembly compilation checks are not model execution or TopK numerical
 validation. No ISA or model legality checks are relaxed by this interface.