artifact-store/docs/ASSEMBLY-EXPERIMENT.md

Assembly Experiment

Status: draft / opt-in research line Created: 2026-05-15

This document defines an opt-in research line under artifact-store: can agentic coding adopt, extend, and eventually originate ffmpeg-grade hand- written assembly for the hot paths of an artifact-storage data plane?

This is a research experiment, not roadmap-critical work. The platform ambition (docs/PLATFORM-AMBITION.md) stands on its own merits whether or not we ever write a single line of assembly. The experiment runs alongside.

Why this experiment exists

ffmpeg is the empirical proof that hand-written assembly with runtime CPU dispatch still substantially outperforms even the best Rust-with-SIMD- intrinsics codebases for tight inner loops — often by 1.5–3× on the same hardware, sometimes more. The cost is steep: domain expertise, multi-arch maintenance, calling-convention discipline, microarchitecture awareness. ffmpeg has decades of contributor depth to amortise that cost.

We do not have that depth. The interesting question is whether large language models, used as coding agents, change the cost equation enough to make this approach viable for a focused project. If they do, an artifact substrate that competes on raw throughput-per-core has a real edge against generic object stores. If they do not, we adopt prebuilt asm-tuned libraries and lose nothing.

Strategic context

This experiment ties to the commercial horizon recorded in docs/PLATFORM-AMBITION.md. A sovereign-cloud artifact product that ingests, hashes, dedups, and serves bytes at noticeably higher throughput-per-core than commodity object stores has a defensible edge. "Cheaper per-GB than AWS" is a losing race; "more throughput per server, on hardware you already own" is not.

Constraints

Licence

• artifact-store is MIT No Attribution.
• ffmpeg's libavutil (where the storage-relevant asm lives) is LGPL 2.1+.
• We cannot copy LGPL-licensed asm into MIT-0 source.
• We can:
  • dynamically link to libavutil at runtime (users get both licences);
  • re-license a segregated optional native module under LGPL 2.1+ while the rest of the repo stays MIT-0, provided the module is its own package and the boundary is explicit;
  • read LGPL code and implement the same algorithm from scratch (algorithms are not copyrightable; specific source text is). This is the standard practice for clean-room reimplementation. Document the process per file.
  • prefer asm sources under permissive licences (BSD, Apache, CC0, public domain) where they exist.

Preferred upstream licences for the experiment, in order:

1. Public domain / CC0 (Intel reference, BLAKE3 reference)
2. Apache-2.0 / BSD / MIT (xxhash, zstd, ring)
3. LGPL via dynamic linking (libavutil)
4. Clean-room reimplementation inspired by LGPL (last resort)

Maintenance budget

The experiment is bounded. Any asm we adopt or write must:

• have a portable C / Rust fallback that is correctness-equivalent;
• be reachable through a runtime CPU-feature dispatch table (the ffmpeg pattern) so the binary still runs on machines without the relevant extension;
• carry a test that compares its output byte-for-byte against the fallback on randomised inputs;
• carry a microbenchmark with a recorded baseline so regressions are visible.

If we cannot meet those four bars for a candidate, we ship the library implementation and revisit later.

What ffmpeg actually has that is reusable here

Inspection of libavutil/x86/ (2026-05-15) found the following storage-relevant assets:

File / module	What it accelerates	Reuse value for artifact-store
x86/crc.asm	CRC-32 (LE + BE) via PCLMULQDQ	High. Fast non-crypto integrity check for chunks and network framing. Public function names ff_crc_le, ff_crc. LGPL — must dynamic-link or reimplement.
x86/aes.asm + aes_init.c	AES block cipher	Low–medium. ffmpeg's AES is unauthenticated. At-rest encryption needs AES-GCM, better adopted from Ring / BoringSSL / AWS-LC (permissive licences, FIPS-validatable).
x86/cpuid.asm + cpu.c	CPU feature detection	High (pattern, not code). Reimplement the ff_get_cpu_flags_x86() + AV_CPU_FLAG_* pattern under MIT-0. This is the dispatch backbone.
x86/x86inc.asm	Macro library for asm authoring	High (technique). Cross-platform calling conventions, register naming, function prologue/epilogue. ffmpeg's macros are the de-facto standard outside game-dev. NASM-syntax.
x86/x86util.asm	SIMD helper macros	Medium. Useful patterns; not directly liftable.
x86/emms.asm	MMX state clearing	Zero. Legacy.
sha.c	SHA-1 / SHA-224 / SHA-256	Zero. Pure C, no SIMD. We are better off with BLAKE3 (asm-tuned upstream) and SHA-NI via OpenSSL / Ring for SHA-256.
aes_ctr.c, blowfish.c, camellia.c, cast5.c, des.c	Block ciphers	Zero. Not relevant for our threat model.
adler32.c, crc.c	Reference integrity (C)	Zero. Use the asm-accelerated variants.

Everything in libavcodec (DCT, motion estimation, deblocking) and the video / audio / image-utility .asm files in libavutil is irrelevant to artifact-store and stays out of scope.

Candidate hot kernels for artifact-store, ranked

Each kernel below is a candidate either for adoption (drop in a vetted permissive library), extension (start from a permissive baseline and optimise further), or origination (write fresh).

Tier 1 — adopt now, do not write

Kernel	Recommended source	Notes
BLAKE3	blake3 (C reference + Rust crate), Apache-2.0 / CC0	Already ships hand-tuned AVX-512, AVX2, SSE4.1, ARM NEON, ARM64. We will never beat upstream.
SHA-256 (compat)	OpenSSL / Ring / AWS-LC, permissive	Uses SHA-NI on supporting CPUs.
AES-GCM	Ring / BoringSSL, ISC / BSD	AES-NI + PCLMULQDQ for GHASH. Authenticated; what we actually need.
Zstandard	zstd (Facebook), BSD-3	Multi-GB/s with SIMD.
LZ4	lz4, BSD-2	Faster than zstd at lower ratio; useful for high-throughput cold paths.

Tier 2 — adopt + extend, this is where the experiment starts

Kernel	Baseline source	Extension question
FastCDC (rolling hash)	fastcdc-rs (MIT) or original C paper code	Can we squeeze a SIMD'd Gear-hash variant that maintains the same boundary distribution? Existing Rust impl is scalar.
CRC-32C (Castagnoli, for chunk integrity)	Intel reference white paper code (public domain)	PCLMULQDQ-accelerated; ffmpeg's crc.asm shows the technique under LGPL — reimplement under MIT-0 from the Intel paper.
xxhash3	xxhash (BSD-2)	Already SIMD'd; the extension is whether we can fuse it with our chunk-boundary loop to read each byte once.
Manifest canonicalisation hash	Whatever canonical-CBOR lib we pin	Likely no asm needed; included to monitor whether it ever appears on a profile.

Tier 3 — originate, only if profiles justify it

These are deliberately speculative. None of them are committed work.

• A fused "scan + chunk + hash" pass that reads each byte from the upload buffer once and emits chunk boundaries plus per-chunk BLAKE3 state in a single pass. Today this requires three passes (CDC, hash per chunk, hash for manifest root).
• A SIMD'd content-type sniffer for the first N kilobytes of unknown uploads.
• An AVX-512 implementation of a bloom / cuckoo filter probe for the "have I seen this hash?" hot path.
• Fast batch verification: given a list of (content_address, bytes) pairs, verify all of them in one SIMD-dispatched pass.

Experiment protocol

For each Tier 2 or Tier 3 candidate that we take on:

1. Frame the kernel. One function, one clear input / output, one measurable metric (bytes per second per core).
2. Baseline. Land a portable C or Rust implementation with full test coverage and a recorded microbenchmark number.
3. Dispatch. Wire the kernel through the runtime CPU-feature dispatcher (ffmpeg pattern, reimplemented MIT-0). Default path = the baseline.
4. Agentic asm attempt. Use the coding agent to author a NASM-syntax asm implementation targeting one ISA extension (start with AVX2 — most broadly available). The agent must:
   • produce annotated source with cycle-accurate comments where relevant;
   • include the test that compares its output to baseline on randomised input;
   • include the microbenchmark.
5. Independent review. A second pass — human or a fresh agent context — reviews for correctness, calling-convention compliance, and obvious microarchitectural issues (false dependencies, port pressure, unaligned loads, misuse of vzeroupper).
6. Land or shelve. If the asm beats the baseline by a meaningful margin (≥ 1.5×) and passes review, it lands behind the dispatcher. Otherwise it shelves with the benchmark numbers recorded so we know not to retry without new techniques.
7. Extend. Repeat for AVX-512, then ARM NEON, then SVE2, in that order of impact.

Each completed kernel produces an ADR-style note in docs/asm/ recording the algorithm, the source of inspiration, the licence chain, the benchmark numbers, and any microarchitectural notes.

What the experiment proves or disproves

A succeeding experiment delivers:

• a portable asm-accelerated data plane that competes with hand-tuned C storage stacks on throughput;
• a public record of which kernels the agentic approach handles well and which it does not;
• a reusable dispatcher and macro foundation that other projects can adopt.

A failing experiment delivers:

• a published record of where agentic coding plateaus on hot-path asm;
• an artifact-store data plane that is still very good — because the baseline is "use the asm-tuned library", which is already fast.

Either outcome is publishable. The downside is bounded.

Out of scope for this experiment

• Cryptography written by us. Use vetted libraries. Always.
• Architectures with small deployment footprints in this domain (RISC-V, POWER, MIPS). Revisit once x86_64 and ARM64 are solid.
• Kernel-bypass networking (DPDK, eBPF/XDP storage). Different experiment, different document if we ever pursue it.
• GPU offload. Different cost model; not addressed here.

Immediate next steps

None are committed. When the v1 baseline (WP-0001) lands and we have a real profile of where time is spent, the first candidate to pick up is almost certainly FastCDC + BLAKE3 in a single pass, because that is the documented bottleneck of every CAS-style storage system that has profiled it (restic, borg, kopia). Until then, this document is a holding place for the ambition.