S4000 Kernel Factory

An auditable, CAKE-inspired control plane for searching, validating, and promoting GPU kernels for the MTT S4000.

Project status: alpha / control-plane prototype. The offline control plane is implemented and tested. This repository does not claim a production-ready S4000 kernel: G0 and every hardware-dependent acceptance row remain blocked until they are backed by observed S4000/MUSA evidence.

Why this project exists

Kernel search is only useful when its measurements can be trusted. This project separates candidate generation from the trusted lab that compiles, executes, checks, benchmarks, and promotes candidates. It records an append-only history and refuses to turn simulation, missing tools, or incomplete evidence into a hardware success.

The implementation covers the HLD's PR0–PR10 control plane:

• immutable task, workload, numerical, candidate, and release contracts;
• Grid, Random, Evolutionary, and optional Codex proposal policies sharing one bounded search view;
• durable experiment state, at-least-once work queues, idempotent budgets, and content-addressed artifacts;
• generic PhysicalSchedule IR plus S4000-specific verification and lowering;
• isolated correctness oracles, safety checks, clean benchmarking, statistical promotion, and independent release qualification;
• deterministic simulation studies for representation, verifier, profiling, complex-kernel, frontier-workload, and environment-evolution experiments;
• evidence-aware stage gates, requirement mapping, and completion audits.

See the architecture for the trust boundaries and the acceptance crosswalk for the HLD-to-code mapping.

Quick start

Requirements: Python 3.10 or newer. No S4000 hardware is needed for the offline path.

git clone <repository-url>
cd kernel-factory
python3 -m venv .venv
source .venv/bin/activate
python3 -m pip install -e '.[dev]'
python3 scripts/validate.py
python3 -m kernel_factory probe --output artifacts/target-manifest.json
python3 -m kernel_factory demo --workspace .kernel-factory/demo

The probe command exits successfully even when the target is absent because a truthful negative observation is a valid probe result. Inspect g0_passed in its output before attempting any hardware claim.

To generate a self-contained, fresh offline evidence bundle:

python3 scripts/reproduce_offline.py --output .kernel-factory/offline-run

This command treats the expected hardware-blocked audit exit as a valid offline outcome and writes a machine-readable run-summary.json. Pass a genuine Codex SDK smoke artifact with --codex-smoke if that optional integration is being audited.

Hardware path

Hardware execution is intentionally a separate trust lane. Start with the S4000 hardware runbook and the copyable inputs under examples/g0-campaign. G0 requires six observed, content-addressed evidence classes and a frozen ecosystem tuple before later hardware stages may run.

Development

make lint       # static checks and formatting check
make test       # unit/integration tests with coverage
make validate   # complete local repository quality gate
make build      # sdist + wheel and metadata verification

Generated evidence, databases, coverage files, and local run workspaces are not source-controlled. See artifacts/README.md for the artifact boundary.

Documentation

• Documentation index
• Architecture and trust model
• HLD acceptance crosswalk
• S4000 G0 hardware runbook
• Optional Codex SDK integration
• Contributing
• Security policy
• Release process

License

Licensed under the Apache License 2.0. S4000/MUSA names are used only to identify the target platform; see NOTICE.