SKEEP-005: schedules — structured concurrency for compute, parallel SDPA, compile-lane metadata - #1262

Summary

SKEEP-005 — structured concurrency as a schedule on the execution context, in the spirit of Halide's algorithm/schedule split. The DSL describes what a network computes; a Schedule decides how independent work is mapped onto cores. No schedule vocabulary enters network {}; results are bit-identical to the sequential path; a request that cannot be honoured is visibly downgraded (trace event), never silently approximated.

Design record: docs/modules/skeep/pages/005-schedules-structured-concurrency.adoc (rendered in the Antora site under SKEEP → 005).

Engine (skainet-lang-core, skainet-backend-cpu)

• sk.ainet.context.schedule.Schedule — dependency-free contract (forRange(n, grain) { start, end -> }, Sequential, tasksFor/chunkFor), ScheduleHint + SCHEDULE_ATTRIBUTE_KEY.
• ExecutionContext.schedule (default Sequential) and withSchedule(...); ScheduledExecutionContext rebuilds ops on the same seam as withTensorDataFactory.
• TraceEvent.ScheduleDowngraded / ScheduleRegion (Perfetto + Android sinks).
• JVM CoroutineSchedule (runBlocking + coroutineScope, caller runs the first chunk, nested regions inline, fail-one-cancels-all, hardware(), dedicated()); platformDefaultSchedule() = hardware on the JVM, Sequential elsewhere.
• parallelChunks and the Panama Q4_K / Q5_K / FP32 kernels take the schedule (additive SPI overloads); DirectCpuExecutionContext(schedule = …) secondary constructor, DefaultCpuOps*(dataFactory, schedule).
• First consumer: scaledDotProductAttention parallel over (batch, head) with SDPA_PARALLEL_MIN_WORK keeping tiny decode calls inline.

Compile lane (skainet-lang-dag, skainet-compile-opt, skainet-compile-hlo)

• dag { schedule(parallel("heads")) { … } } / op(…, schedule = …) → node attribute skainet.schedule.
• ScheduleAnnotationPass validates dims per op, stamps GraphNode.metadata, rejects with diagnostics; wired as a core pass.
• StableHLO module header gains skainet.schedule = {…} beside skainet.tensor_layouts. IREE consumption is out of scope.

Thread-safety prerequisites

• KernelDispatch / KernelRegistry: volatile immutable snapshots, synchronized registration (JvmSynchronized optional-expectation annotation for common code).

Docs

• Explanation Algorithm and schedule, tutorial Schedule getting started backed by the executable ScheduleDemo sample (SamplesTest asserts bit-identity across schedules), dsl-principles table row, CHANGELOG.

Numbers (i7-9750H 6c/12t, JDK 25)

SdpaScheduleBench, hardware vs sequential: 3.4–4.8× on prefill shapes (seqQ 64), 2.0–2.7× on single-query decode; e.g. 32 heads × 4096 keys × 64 queries 2,859 ms → 836 ms. Downstream (SKaiNET-transformers per-head attention on this API): attn.fused_compute 8.99 s → 2.59 s at 512 ctx, Daily-StandAPP 3B decode 1.9 → 3.0 tok/s with byte-identical greedy output.

Verification

• scripts/pr-gate.sh full: all legs passed (JVM, apiCheck, JS/Wasm browser, linuxX64, assemble, Java consumer, tool tests, Android host).
• API dumps refreshed for lang-core, backend-cpu, lang-dag, compile-opt, compile-hlo, compile-dag — additive only, no removed lines.
• Antora site builds without errors.

Related

• KernelDispatch / KernelRegistry are not safe for concurrent reads #1259, parallelChunks hides a runBlocking(Dispatchers.Default) island inside synchronous kernels #1260 (filed while implementing), Panama FP32 matmul: first call in a JVM differs by an ULP from later calls (JIT-dependent reduceLanes order) #1261 (JIT-dependent reduceLanes ULP on first call; tests warm up first).
• Downstream PR: SKaiNET-developers/SKaiNET-transformers feature/attention-schedule (requires this branch; lock-step 0.54.0).

🤖 Generated with Claude Code