SemanticCompute

Development biography · earlier archive

Development profile compiled from project source and retained records in October 2026. Dates and test results describe those records; they do not imply a new build, live acceptance test or public release.

A numerical contract across backends

The problem. Floating-point code that "looks right" and passes a coarse allclose can still be wrong in ways that matter: a GPU port that fused a multiply-add where the CPU didn't, a backend that flushed denormals to zero, a reduction reassociated into a different rounding order, a NaN swallowed instead of propagated. These differences are invisible to a single tolerance check and expensive to find by hand — and they multiply across every backend a team targets (Apple GPUs, portable C, the browser via WebGPU, NVIDIA via CUDA). The industry-standard answer, numpy.allclose/torch.allclose, returns a single pass/fail and tells you nothing about the cause or the location.

What SemanticCompute is. It is a deliberately restricted, compute-oriented semantic middle layer — explicitly NOT an "arbitrary Swift to GPU" transpiler . A computation is written once as a typed intermediate representation (SLKernel). A single optimising front door (SLKernelCompiler) lowers that one IR to four backend languages, and a deterministic CPU reference executor (SLReferenceExecutor) is treated as ground truth. The product people actually reach for is the compatibility doctor (SLCompatibilityDoctor): it runs a kernel family against each backend and proves agreement with the CPU reference under a tolerance that is always stated, never hidden — or it reports, per coordinate, where the two diverge and classifies the cause.

Origin / motivation (as documented in-tree). The project's own source records the motivation behind its discipline rather than a marketing origin story. SLVersion.swift explains why even the version constant exists: "two sessions in one day lost time to the same question and could not answer it from the tool: which build am I actually talking to?" — so the build carries a machine-readable capability manifest and a build-commit stamp (committed value deliberately "unknown", real only in a release artefact). The README positions the whole tool as "the diagnostic layer beyond allclose", and AGENTS.md frames it as "a semantic compute substrate, not a general Swift-to-GPU transpiler" whose first duty is correctness. The honesty is structural: a governance test enforces that the CHANGELOG's top version equals the code's version , so release notes can never drift from what shipped.

Who it serves and how it works

Intended audience. GPU and kernel developers porting numerical code across backends; DSP and scientific-computing engineers who need auditable batch results; ML-kernel authors (Triton/CUDA/FlashAttention-style work) who need more than allclose; and regulated or safety-critical teams who must show why a result is trusted. A distinct, deliberate audience is AI agents: the MCP server lets an autonomous tool prove its own numerics. Commercial tiers reflect this split — a solo production tier and an enterprise/regulated tier.

Distinctive ideas. (1) Parity as a first-class, stated contract rather than an afterthought assertion. (2) The CPU reference as a deterministic oracle shared by every backend. (3) Shape-aware, cause-classified divergence — a mismatch is a located (x,y,z) coordinate with a named cause, not a bare "failed". (4) A hard honesty boundary: parity proves agreement, not correctness (two backends can agree on the same wrong answer), and it is blind to conditioning (a bit-exact result can still be numerically wrong). (5) "Prescribe, then re-verify" — the doctor may suggest a verified whole-op substitution from its own proven library, re-proved against the user's frozen reference, but never rewrites the user's kernel source and never self-certifies.

What it does, concretely. For each kernel family it emits the four backend sources, executes the ones the host supports, and compares each to the CPU reference under a chosen tolerance tier (.exact, .defaultFloat ≈ 1e-6/1e-5, .ulp(n), or custom). Where a family ships a higher-precision Double ground truth, the same machinery reports measured accuracy (SLAccuracy), not just cross-backend agreement. A curated "divergence zoo" of known-bad cases proves the doctor still catches what it should.

A concrete user journey. A developer has a hand-written Metal kernel they suspect disagrees with their NumPy reference. They pipe both arrays into the semanticcompute-parity CLI (or call sc_check_parity from an MCP client) with a stated tolerance. The doctor reports a divergence at a specific coordinate, classified as FMA contraction. They run sc_diagnose_divergence for the per-element cause map and a suggested remedy, apply the fix themselves, and re-run until the contract is green — then wrap their production GPU path in that same parity contract so the fast path is only ever trusted where it has been proven to match the reference.

Main modules / features (authored vs dependencies)

What a visitor can actually see / try:

• See: the animated parity scope (docs/scope.gif) and the live interactive page; a shareable HTML verification report (docs/verification-report.html).
• Try: the runnable examples (KernelBench-style generate-verify-fix loop; Triton/vLLM/FlashAttention output verification) and the --zoo failure lab.

Dependencies: none external in the Swift package — the four emitters are pure Swift and the manifest declares no third-party SwiftPM dependencies . The optional CUDA runner relies on an external NVIDIA toolchain/driver by nature.

Technical foundations & integrations (local packages named)

• One IR, four emit backends: SLKernel → Metal (MSL, SLMetalEmitter), portable C (fixed sl_run ABI, SLCEmitter), WebGPU (WGSL, SLWGSLEmitter), CUDA C++ (SLCUDAEmitter). Emission is always available; runtime executability is queried via SLBackendAvailability.
• IEEE-safe math discipline: Metal MTLMathMode.safe + precise:: builtins + an fp-contract pragma; C compiled -ffp-contract=off — so a CPU/GPU difference is the backend's real behaviour, not a build artefact.
• Local integration packages (in-tree, Integrations/):
• Integrations/SemanticComputeCUDA — the OPTIONAL, separate NVIDIA runner that executes and parity-verifies the emitted CUDA on real hardware (not part of the default build); carries committed on-device evidence.
• Integrations/VerifyNumericsPlugin — a verify-numerics SwiftPM command plugin that surfaces divergences as Xcode Issue-Navigator diagnostics.
• Integrations/python — Python-side integration/examples.
• Distribution design: source development with a separate semanticcompute-dist channel for binaries, documentation and a website; signed + notarised universal macOS binaries, container images, MCP bundle, checksums, SBOM, provenance.

Current maturity by feature (evidence, versions, dates)

The project agent inspected source and retained release evidence on 17 October 2026. No new native build, benchmark or full test run was performed for this profile.

• Inspected version: v1.29.0 in the reporting worktree. Source-verified: SLVersion.swift:21 (major 1, minor 29, patch 0) AND Tools/sca/semanticcompute.cdx.json both read 1.29.0 — they agree. Tagged 2026-10-13 per release lineage (not re-verified against the tag this session).
• Kernel-family library: 270+ families, each held to the full five-checkpoint bar (CPU reference + SLSemanticContract + legality + backend lowering + doctor parity, then catalogue registration). In-tree count: ~283 .init(name:) entries in KernelFamilyCatalog.swift (this worktree's [Unreleased] adds Fuzz-Factory + MNA netlist families, so it is slightly AHEAD of the tag; release record ≈274). The supported release-level description is 270+ families; unreleased worktree additions are separate.
• Three backends — executed + parity-verified IN CORE: Metal (Apple GPUs), portable C (clang → dlopen), WGSL (on a real WebGPU device via wgpu→Metal, naga-validated; execution-parity-tested on affine + loop-IR matmul under the doctor's tolerance). Evidence: BACKENDS.md.
• CUDA — EMISSION in core, executed by the OPTIONAL external runner: SLBackendKind.cuda's own doc comment states emission-only in the default build; on-device execution/parity is Integrations/SemanticComputeCUDA. Committed evidence file Integrations/SemanticComputeCUDA/cuda-parity-evidence.txt; BACKENDS.md records 16 on-device comparisons passing twice on 2× RTX 5080 (driver 570.211.01) and an earlier 13-comparison run on 2× RTX 5060 Ti. The documented boundary is three executed and parity-verified backends in core, plus the optional externally verified CUDA runner.
• Performance: measured per DSP_PROVING_GROUND.md on Apple M3 Pro, -c release, with a dead-code-elimination barrier, GPU vs FAIR multithreaded CPU and vs scalar: Goertzel bank (4096×16384) ≈28× fair / ≈199× scalar; transcendental synth ≈2.6× fair / ≈7× scalar; pointwise add (4.2M, bandwidth-bound) ≈1.2× (a wash); Goertzel tiny (8×256, real-time) 0.02× (GPU loses). The fair comparison is the relevant figure; earlier 205×/280× were debug-build artefacts, corrected. Batch, not real-time.
• Tests / CI: source-verified fact — GovernanceGateTests + a CI doc-sync step enforce CHANGELOG-top == SLVersion.string . Exact passing test COUNTS are NOT reported by the project agent on 17 October 2026 (read-only); release records cite a large, growing suite (hundreds to ~1,000+ across milestones). Exact test-count claims need the matching release CI result.
• Cross-platform: library + CLI + MCP build and pass on macOS and Linux (Swift 6.2) per release records; not re-run this session.
• Licensing/distribution maturity: signed/notarised dist through the 1.2x line; signed binaries 1.23.0+ require an online licence entitlement before CLI/MCP/Live ops (1.24.0+ extends to MCP resources/prompts) — per docs/pricing.html. Billing→licence-issuance wiring and the source-private flip are NOT yet complete (roadmap).

Roadmap, limitations, FAQs

Roadmap :

• Normalised execution-contract derivation from a generic SLKernel (beyond specimen-family CPU paths).
• Descriptor-driven lowering.
• First-class normalised boundary semantics (stencils are currently 3×3 clamp-to-edge; boundary facts not yet first-class).
• Richer 2D parity reporting beyond flat buffers; broader generic semantic execution.
• Commercialisation: billing→licence issuance wiring; EULA lawyer review; source-private flip (planned).

Limitations:

• Not a general transpiler — a restricted compute IR by design.
• Parity proves agreement, not truth, and is blind to conditioning; correctness needs an independent oracle per family.
• CUDA is emit-in-core, execute-out-of-core (no CUDA runtime in the default build).
• Performance is workload/hardware-specific; small/real-time/bandwidth-bound kernels may be a wash or a loss.
• Accuracy figures exist only where a family ships a Double ground truth.
• Commercial licence; no free production tier; signed binaries 1.23.0+ enforce an online entitlement.

FAQs:

• Isn't this numpy/torch allclose? No — the diagnostic layer beyond allclose: locates the divergence by coordinate, classifies the cause, states the tolerance, across four lowered backends vs one typed reference.
• Do all four backends run on my machine? Three execute in core (Metal, portable C, WGSL). CUDA is emitted/validated in core; running it needs the optional NVIDIA runner and an NVIDIA GPU.
• If CPU and GPU agree, is my kernel correct? Not necessarily — they can agree on the same wrong answer, and parity can't see conditioning. Pair it with an independent oracle; where a Double ground truth exists, accuracy is measured directly.
• Will it rewrite my kernel to fix it? No — it can prescribe a verified whole-op substitution re-proved against the caller’s frozen reference, but never edits your source and never self-certifies.
• Does it phone home? The numerical verification path is local. Optional JSONL metrics are also local and disabled by default. Signed commercial binaries perform an online licence check; source builds do not.