perf(qgemm): add checked Omega work ordering

docs/runtime/API.md

@@ -1,6 +1,6 @@
 # Omega Runtime API v0
 
-Omega Runtime API version: 0.9.0
+Omega Runtime API version: 0.10.0
 
 Status: first written version, 2026-10-19 (slice R1, omega-mv#594, tracking #593). Source of truth is the C headers in
 `src/`. This file describes them; `docs/runtime/omega_runtime_api.manifest` lists them; `make test-runtime-api` checks the
@@ -36,8 +36,9 @@ signature against the headers on every run.
 
 ## 2. Version and compatibility rule
 
-The version is MAJOR.MINOR.PATCH (semantic versioning), currently **0.9.0**. It is a property of the list of entries and
+The version is MAJOR.MINOR.PATCH (semantic versioning), currently **0.10.0**. It is a property of the list of entries and
 their behaviour, not of the library build. Changes so far:
+- 0.10.0: adds the experimental `omega_gpu_pf_qgemm_set_group` selector. Existing entry signatures and the default execution order are unchanged.
 - 0.9.0 (AmperePort, CUDApp#170): grows STABLE `OmegaGpuLaunch` with `target_sm` (a MAJOR-class change
   taken as MINOR under the major-version-zero rule); adds EXPERIMENTAL
   `omega_gpu_session_target_sm`. Zero-initialized legacy launches still mean sm_121, not auto-detect.
@@ -593,7 +594,7 @@ values, poison patterns) are in the INTERNAL list.
 | `src/omega_gpu_prefill_attn_api.h` | `OmegaGpuPrefillAttnInfo`, `OmegaGpuPrefillAttnMirrorView`, `omega_gpu_prefill_attn`, `omega_gpu_prefill_attn_release`, `omega_gpu_prefill_attn_dev`, `omega_gpu_prefill_attn_set_warps`, `omega_gpu_prefill_attn_set_fused`, `omega_gpu_prefill_attn_set_kv_mirror`, `omega_gpu_prefill_attn_kv_mirror_view`, `omega_gpu_prefill_attn_kv_mirror_invalidate`, `omega_gpu_prefill_attn_kv_mirror_forget`, `omega_gpu_prefill_attn_kv_mirror_available` | Causal prefill attention for Qwen3-30B-A3B, with an optional KV mirror; one model. |
 | `src/omega_gpu_moe_api.h` | `omega_gpu_moe_tensor_upload_bf16`, `omega_gpu_moe_tensor_upload_f32`, `omega_gpu_moe_tensor_free`, `omega_gpu_moe_tensor_shape`, `omega_gpu_matmul_resident_window_f32`, `omega_gpu_matmul_resident_window_bf16`, `omega_gpu_matmul_resident_windows_f32`, `omega_gpu_moe_reserve`, `omega_gpu_moe_prepare`, `omega_gpu_moe_seal`, `omega_gpu_moe_unreserve`, `omega_gpu_moe_cache_clear`, `omega_gpu_moe_set_cta_budget`, `omega_gpu_moe_cta_budget`, `omega_gpu_moe_window_byte_offset` | Column windows over a resident bf16 expert tensor (OWN-30B); tied to the serving pool. |
 | `src/omega_gpu_decode_graph.h` | `OmegaGpuDecodeGraphConfig`, `OmegaGpuDecodeGraphStats`, `OmegaGpuDecodeGraphVas`, `omega_gpu_decode_graph_create`, `omega_gpu_decode_graph_free`, `omega_gpu_decode_graph_set_layer`, `omega_gpu_decode_graph_set_final_norm`, `omega_gpu_decode_graph_token`, `omega_gpu_decode_graph_begin_token`, `omega_gpu_decode_graph_record_layer`, `omega_gpu_decode_graph_record_final`, `omega_gpu_decode_graph_end_token`, `omega_gpu_decode_graph_abort_token`, `omega_gpu_decode_graph_record_res`, `omega_gpu_decode_graph_record_swiglu`, `omega_gpu_decode_graph_list`, `omega_gpu_decode_graph_vas`, `omega_gpu_decode_graph_read`, `omega_gpu_decode_graph_set_stamps`, `omega_gpu_decode_graph_set_barrier`, `omega_gpu_decode_graph_barrier`, `omega_gpu_decode_graph_stamps`, `omega_gpu_decode_graph_kind_name`, `omega_gpu_decode_graph_set_flush_each`, `omega_gpu_decode_graph_set_prefetch`, `omega_gpu_decode_graph_prefetch` | One Qwen3-30B-A3B decode token as one command list; scheduling, barrier and prefetch modes are still measured. |
-| `src/omega_gpu_prefill.h` | `OmegaPfWeights`, `omega_gpu_pf_rc_name`, `omega_gpu_pf_alloc_dev`, `omega_gpu_pf_alloc_host`, `omega_gpu_pf_free`, `omega_gpu_pf_upload`, `omega_gpu_pf_download`, `omega_gpu_pf_copy_va`, `omega_gpu_pf_stats`, `omega_gpu_pf_stats_reset`, `omega_gpu_pf_weights_upload`, `omega_gpu_pf_weights_free`, `omega_gpu_pf_weights_host_form`, `omega_gpu_pf_gemm_bm`, `omega_gpu_pf_gemm_tiles`, `omega_gpu_pf_gemm`, `omega_gpu_pf_gemm_set_shape`, `omega_gpu_pf_quant`, `omega_gpu_pf_qgemm_bm`, `omega_gpu_pf_qgemm_tiles`, `omega_gpu_pf_qgemm_tiles_va`, `omega_gpu_pf_qgemm`, `omega_gpu_pf_qgemm_set_shape`, `omega_gpu_pf_quant_record`, `omega_gpu_pf_qgemm_record` | Device-resident one-pass prefill for OWN-30B; arguments carry raw device addresses. |
+| `src/omega_gpu_prefill.h` | `OmegaPfWeights`, `omega_gpu_pf_rc_name`, `omega_gpu_pf_alloc_dev`, `omega_gpu_pf_alloc_host`, `omega_gpu_pf_free`, `omega_gpu_pf_upload`, `omega_gpu_pf_download`, `omega_gpu_pf_copy_va`, `omega_gpu_pf_stats`, `omega_gpu_pf_stats_reset`, `omega_gpu_pf_weights_upload`, `omega_gpu_pf_weights_free`, `omega_gpu_pf_weights_host_form`, `omega_gpu_pf_gemm_bm`, `omega_gpu_pf_gemm_tiles`, `omega_gpu_pf_gemm`, `omega_gpu_pf_gemm_set_shape`, `omega_gpu_pf_quant`, `omega_gpu_pf_qgemm_bm`, `omega_gpu_pf_qgemm_tiles`, `omega_gpu_pf_qgemm_tiles_va`, `omega_gpu_pf_qgemm`, `omega_gpu_pf_qgemm_set_shape`, `omega_gpu_pf_qgemm_set_group`, `omega_gpu_pf_quant_record`, `omega_gpu_pf_qgemm_record` | Device-resident one-pass prefill for OWN-30B; arguments carry raw device addresses. |
 | `src/omega_gpu_pfhost.h` | `omega_gpu_pf_router_rows`, `omega_gpu_pf_router_packed_bytes`, `omega_gpu_pf_router_pack`, `omega_gpu_pf_router_logits`, `omega_gpu_pf_moe_combine`, `omega_gpu_pf_router_set_rows` | Whole-prompt prefill router logits and MoE combine for OWN-30B; arguments carry raw device addresses. |
 
 ### 9.8 General matrix multiply (`src/omega_gpu_gemm_ex.h`, added in 0.8.0)

docs/runtime/omega_runtime_api.manifest

@@ -12,7 +12,7 @@
 # After a deliberate header change: edit the line here, run `tools/runtime_api_check.sh --bless` to refresh numbers, review the diff,
 # and bump the version (MAJOR/MINOR/PATCH, rule in API.md section 2; tools/runtime_api_semver.sh checks the bump against the base).
 # Names a manifest header declares that are NOT API go in omega_runtime_api.internal, each with a reason (the check fails otherwise).
-abi omega_runtime 0.9.0
+abi omega_runtime 0.10.0
 header src/omega_runtime_api.h
 header src/omega_gpu_platform.h
 header src/omega_gpu_session.h
@@ -38,9 +38,9 @@ header src/omega_gpu_pfhost.h
 header src/omega_gpu_gemm_ex.h
 # ---- version ----
 const OMEGA_RUNTIME_API_VERSION_MAJOR 0
-const OMEGA_RUNTIME_API_VERSION_MINOR 9
+const OMEGA_RUNTIME_API_VERSION_MINOR 10
 const OMEGA_RUNTIME_API_VERSION_PATCH 0
-const OMEGA_RUNTIME_API_VERSION 9
+const OMEGA_RUNTIME_API_VERSION 10
 # ---- platform contract (src/omega_gpu_platform.h, ABI 1.2) ----
 struct OmegaGpuDeviceHandle 8 4 # STABLE
 field OmegaGpuDeviceHandle index 0 4 u32 1
@@ -954,6 +954,7 @@ fn omega_gpu_pf_qgemm_tiles fn(*const OmegaGpuFp8Tensor, *const u32, *mut c_void
 fn omega_gpu_pf_qgemm_tiles_va fn(u32, *const u64, *const u64, *const u32, *mut c_void, u32) -> u32 # EXPERIMENTAL
 fn omega_gpu_pf_qgemm fn(u32, u32, u32, u64, u32, u64, u64, u64, u64, *mut u64) -> i32 # EXPERIMENTAL
 fn omega_gpu_pf_qgemm_set_shape fn(u32, u32, u32) -> () # EXPERIMENTAL
+fn omega_gpu_pf_qgemm_set_group fn(u32) -> () # EXPERIMENTAL
 fn omega_gpu_pf_quant_record fn(*mut OmegaGpuCmdList, u32, u32, u32, u64, u64, u64) -> i32 # EXPERIMENTAL
 fn omega_gpu_pf_qgemm_record fn(*mut OmegaGpuCmdList, u32, u32, u32, u64, u32, u64, u64, u64, u64) -> i32 # EXPERIMENTAL
 fn omega_gpu_pf_router_rows fn() -> u32 # EXPERIMENTAL

mk/prefill-shape.mk

@@ -14,3 +14,14 @@ test-prefill-shape: $(OUT_DIR)/prefill-shape.so $(OUT_DIR)/gpu_qgemm_test $(OUT_
 ifeq ($(CUDAPP_OMC_HOST),1)
 	OMEGA_OMC="$(OMEGA_OMC)" OMEGA_BRIDGE="$(OMEGA_BRIDGE)" CC="$(CC)" python3 om/prefill-shape/mutants.py
 endif
+
+CARRIED_HOST_TESTS += test-prefill-order
+.PHONY: test-prefill-order
+$(OUT_DIR)/prefill-order.so: src/cudapp_om_prefill_order.c
+	@mkdir -p $(OUT_DIR)
+	$(CC) $(filter-out -MMD -MP,$(CFLAGS)) -shared -fPIC $< -o $@
+test-prefill-order: $(OUT_DIR)/prefill-order.so $(OUT_DIR)/gpu_qgemm_test
+	python3 om/prefill-shape/order-check.py $(abspath $(OUT_DIR))/prefill-order.so
+ifeq ($(CUDAPP_OMC_HOST),1)
+	OMEGA_OMC="$(OMEGA_OMC)" OMEGA_BRIDGE="$(OMEGA_BRIDGE)" CC="$(CC)" python3 om/prefill-shape/order-mutants.py
+endif

om/prefill-shape/.crumb

@@ -3,18 +3,18 @@
     "generated": {
       "children": [],
       "children_root": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-      "compiled_at": "2026-11-01T20:02:57Z",
+      "compiled_at": "2026-11-01T20:06:13Z",
       "compiler": "crumb-compile/1",
-      "digest": "sha256:ae913da5184e86a744633421c5efc316da0feddc1b05ef48f29068bf23cb3cb4",
+      "digest": "sha256:4c2da4b06b3a47de49eab897326282dd21ea66e3ae1947054c5fb6e42b500e83",
       "evidence_files": 0,
       "evidence_root": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
-      "files": 11,
-      "generated_at_commit": "572a73bfd138b78154172f7746504842a7168f9c",
-      "source_tree": "sha256:5a30b12b78795c04d77df1becd2e406ac22d55b56966c255817d06a22046309b"
+      "files": 20,
+      "generated_at_commit": "3751e1ab02034a48d1fbc1217c70d60dc97382fc",
+      "source_tree": "sha256:141935040c08042f989ba49e50d9b43736e36c5f10faedad3b3af5b42c158e6b"
     }
   },
   "layer": "native-policy",
   "name": "prefill-shape",
-  "purpose": "Checked Omega admission for bounded prompt matrix tile shapes and independent parity verification",
+  "purpose": "Checked Omega admission and work ordering for bounded prompt matrix tiles, with independent parity verification",
   "schema_version": "1.0.0"
 }

om/prefill-shape/README.md

@@ -27,6 +27,21 @@ Before the change, all four 27B projection shapes refused 128-row generation. Th
 
 The subsequent [full host-suite receipt](large-shape-full-host-validation.json) records all 77 targets passing on the candidate source. It includes the failed absolute-output-path invocation and its correction. GPU and full-model qualification remain pending.
 
+## Grouped work-order experiment
+
+The separate grouped-order candidate revisits the mechanism in historical Omega commit `86211a39965bd903b6be482cfc784c7dd58733a5`. It schedules nearby matrix jobs over the same weight panel before advancing to another panel. Historical chip screens motivated that work, but their shared-machine measurements and sampled-row checks do not qualify this implementation or a full model.
+
+`order.om` owns the grid and coordinate-remapping instruction plan. Group 0 keeps the original order. Groups 1 through 5 gather consecutive row tiles into groups of powers of two. The Omega plan checks input and grid bounds before returning success. Jobs beyond the last tile branch out before reading the tile table. The existing C emitter interprets only the plan's primitive instructions; it does not calculate the coordinate mapping.
+
+The private plan is 64 unsigned words: grid x, grid y, instruction count, then five-word records `(operation, destination, source1, source2, immediate)`. Register roles are column coordinate, row coordinate, temporary and tile count. Operations are AND-immediate, shift-right-immediate, multiply-add-immediate, constant load, unsigned greater-or-equal predicate, and predicate branch. The prefix emits the mapping plus a tail guard; the output-store prefix repeats the same mapping. Matrix arithmetic and the existing wait distance are unchanged.
+
+Select a candidate with `omega_gpu_pf_qgemm_set_group(group)` before model work begins. Never change it while a model operation is in flight. This composes with the existing shape test knob. Default group 0 remains unchanged. `order-check.py` independently interprets the plan and verifies coverage, uniqueness and boundaries; `order-mutants.py` checks source faults. The matrix simulator exercises groups 0, 1, 3 and 4 across direct/indexed inputs and partial tiles. GPU and full-model correctness and speed remain unqualified.
+
+The complete 78-target host suite and API version check pass. On the full 27B reader, group4 and group0 preserve every output-score bit and next-token choice in all six frozen cases. Repeated 5,017-token reading was 18.817 seconds with group0 and 16.199 seconds with group4 in this shared-machine screen. This is not quiet-machine qualification. Group0 remains the default. `order-validation.json` records source identities, checks and per-case observations. The separate 128-row full-model attempt was refused by an older prefill-cache register cap before its first matrix; that correction is being verified on the parent branch and is not part of this tested group4 binary.
 The first full-model 128-row trial exposed an older cache-admission cap: it refused the generated 152-register declaration before the first matrix launch. The cache now honors the generator's existing opt-in budget, bounded by the allocator's hardware ceiling. The default declaration cap and the launch/record register-file checks remain enforced. `cache-check.c` reproduces the real cache call without a GPU by stopping at code allocation: it fails on the original library and passes the correction, including absent-opt-in and over-budget refusals. The correction also passes the matrix simulator and admission mutants. The corrected full-model run passed all six complete-score comparisons. The repeated 5,017-token read was 14.759 seconds versus 18.817 seconds in the comparison run. These are shared-machine observations, not quiet qualification; the full-host correction suite remains pending. See `large-shape-gpu-validation.json`. See `cache-admission-regression.json`.
 
+With the cache-budget correction included, the 128-row/group4 combination passed all six full-model score and next-token comparisons. The repeated 5,017-token read took 14.348 seconds versus 18.817 seconds for 64-row/group0. Group5 at 128 rows took 15.379 seconds in the same screening series. These are shared-machine observations. `order-combined-validation.json` records every compared setting and the complete selected-candidate comparison. The combined host rerun and serving qualification remain pending; no default changed.
+
+The subsequent full host rerun completed successfully: all 78 targets passed at runtime source `28b533c95a2dce42cb14c9d8bc4a05847a5981a0`. See `order-combined-full-host-validation.json` for the command, timing and log digest. This does not qualify the later scoped API or serving performance.
+
 The subsequent full host rerun completed successfully: all 77 targets passed at runtime source `572a73bfd138b78154172f7746504842a7168f9c`. See `cache-full-host-validation.json` for the command, timing and log digest. This does not qualify the later scoped API or serving performance.

om/prefill-shape/order-check.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
+# Independent external oracle. Not a production dependency.
+import ctypes,itertools,sys
+lib=ctypes.CDLL(sys.argv[1]);fn=lib.omega_native_qgorder
+fn.argtypes=[ctypes.POINTER(ctypes.c_uint64),ctypes.c_void_p]+[ctypes.c_uint64]*5
+fn.restype=ctypes.c_uint32
+
+def plan(group,cols,tiles,guard=1):
+    out=(ctypes.c_uint64*64)();result=ctypes.c_uint64(99)
+    rc=fn(ctypes.byref(result),out,64,group,cols,tiles,guard)
+    assert rc==0,rc
+    return result.value,list(out)
+
+def execute(p,x,y):
+    r=[x,y,0,0];pred=False
+    for i in range(p[2]):
+        op,d,a,b,imm=p[3+5*i:8+5*i]
+        assert max(d,a,b)<4
+        if op==1:r[d]=r[a]&imm
+        elif op==2:r[d]=r[a]>>imm
+        elif op==3:r[d]=r[a]*imm+r[b]
+        elif op==4:
+            assert imm==896+11*4
+            r[d]=execute.tiles
+        elif op==5:pred=r[a]>=r[b]
+        elif op==6:
+            if pred:return None
+        else:raise AssertionError('unknown opcode')
+    return (r[0],r[1])
+
+def cover(p,cols,tiles):
+    execute.tiles=tiles;seen=set()
+    for x,y in itertools.product(range(p[0]),range(p[1])):
+        mapped=execute(p,x,y)
+        if mapped is None:continue
+        if mapped in seen or not (0<=mapped[0]<cols and 0<=mapped[1]<tiles):return False
+        seen.add(mapped)
+    return seen==set(itertools.product(range(cols),range(tiles)))
+
+cases=0
+for g in range(6):
+    shapes=list(itertools.product([1,3,17],[1,15,16,17,65]))+list(itertools.product([40,128,272],[64,65]))
+    for c,t in shapes:
+        ok,p=plan(g,c,t);assert ok==1
+        assert (p[0],p[1])==(c*(1<<g),(t+(1<<g)-1)//(1<<g))
+        assert cover(p,c,t),(g,c,t)
+        ok,e=plan(g,c,t,0);assert ok==1
+        assert e[2]==(0 if g==0 else 3)
+        assert e[3:18]==p[3:18]
+        cases+=1
+for g,c,t,guard,want in [(5,2047,65535,1,1),(5,2048,65535,1,0),(6,1,1,1,0),(0,0,1,1,0),(0,1,0,1,0),(0,65536,1,1,0),(0,1,65536,1,0),(0,1,1,2,0),(2**64-1,1,1,1,0),(0,2**64-1,1,1,0),(0,1,2**64-1,1,0)]:
+    ok,p=plan(g,c,t,guard);assert ok==want
+    if not ok:assert p[:3]==[0,0,0]
+    cases+=1
+out=(ctypes.c_uint64*64)();v=ctypes.c_uint64()
+assert fn(None,out,64,1,1,1,1)==32
+assert fn(ctypes.byref(v),None,64,1,1,1,1)==32
+assert fn(ctypes.byref(v),out,63,1,1,1,1)==32
+ok,p=plan(4,3,17)
+for name,mutate in [('drop_guard',lambda q:q.__setitem__(2,3)),('wrong_mask',lambda q:q.__setitem__(7,7)),('wrong_row_stride',lambda q:q.__setitem__(17,8)),('floor_grid',lambda q:q.__setitem__(1,1)),('skip_row',lambda q:q.__setitem__(14,0))]:
+    q=p.copy();mutate(q);assert not cover(q,3,17),name
+    print(name+': caught')
+print('PASS grouped-grid coverage and boundary oracle',cases,'cases')

om/prefill-shape/order-combined-full-host-validation.json

@@ -0,0 +1,18 @@
+{
+  "status": "PASS",
+  "runtime_source_commit": "28b533c95a2dce42cb14c9d8bc4a05847a5981a0",
+  "targets": 78,
+  "exit_code": 0,
+  "started": "2026-11-01T19:51:53.584886+00:00",
+  "ended": "2026-11-01T19:58:35.997653+00:00",
+  "command": [
+    "make",
+    "-j4",
+    "OUT_DIR=../optimize27-qg-order-build",
+    "test",
+    "test-runtime-api-semver",
+    "RUNTIME_API_BASE=572a73bfd138b78154172f7746504842a7168f9c"
+  ],
+  "log_sha256": "669e90dfddd238b8b81e05829acb2633c2ad4b4c0ded9aa15a8d237478a0f858",
+  "scope": "Complete local host suite at the named runtime source. Not server performance qualification."
+}