build: align just test coverage gate with CI package list

Assisted-by: GLM 5.2

.gitea/workflows/release.yml

@@ -0,0 +1,157 @@
+# Release — gasm binaries. Runs on version tags (v0.28.0) pushed to main.
+name: Release
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: fedora
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - goos: linux
+            goarch: amd64
+          - goos: linux
+            goarch: arm64
+          - goos: linux
+            goarch: riscv64
+          - goos: linux
+            goarch: loong64
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.26"
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Validate tag and build
+        id: build
+        env:
+          VERSION: ${{ gitea.ref_name }}
+        run: |
+          set -euo pipefail
+
+          if ! echo "$VERSION" | grep -qE '^v[0-9]+(\.[0-9]+){0,2}([-+].*)?$'; then
+            echo "ERROR: expected a semver tag like v1.2.3, got: '$VERSION'"
+            exit 1
+          fi
+
+          VERSION_NO_V="${VERSION#v}"
+          echo "version_no_v=${VERSION_NO_V}" >> "$GITEA_OUTPUT"
+
+          mkdir -p bin
+          GOOS=${{ matrix.goos }} GOARCH=${{ matrix.goarch }} CGO_ENABLED=0 \
+            go build -ldflags "-s -w -X main.version=${VERSION_NO_V}" \
+              -o "bin/gasm-${VERSION_NO_V}-${{ matrix.goos }}-${{ matrix.goarch }}" \
+              ./cmd/gasm
+
+      - name: Upload artifact
+        uses: actions/upload-artifact@v3
+        with:
+          name: gasm-${{ matrix.goos }}-${{ matrix.goarch }}
+          path: bin/gasm-${{ steps.build.outputs.version_no_v }}-${{ matrix.goos }}-${{ matrix.goarch }}
+          if-no-files-found: error
+
+      - name: Smoke test
+        if: matrix.goos == 'linux' && matrix.goarch == 'amd64'
+        run: |
+          chmod +x bin/gasm-${{ steps.build.outputs.version_no_v }}-${{ matrix.goos }}-${{ matrix.goarch }}
+          ./bin/gasm-${{ steps.build.outputs.version_no_v }}-${{ matrix.goos }}-${{ matrix.goarch }} --version
+
+  release:
+    runs-on: fedora
+    needs: build
+    permissions:
+      releases: write
+    steps:
+      - uses: actions/checkout@v7
+
+      - name: Download all artifacts
+        uses: actions/download-artifact@v3
+        with:
+          path: dist
+
+      - name: Extract CHANGELOG section
+        env:
+          VERSION: ${{ gitea.ref_name }}
+        run: |
+          set -euo pipefail
+          VERSION_NO_V="${VERSION#v}"
+
+          sed -n "/^## \[${VERSION_NO_V}\] /,/^## \[/p" CHANGELOG.md \
+            | sed '$d' \
+            | tail -n +2 \
+            > release-body.md
+
+          if [ ! -s release-body.md ]; then
+            echo "ERROR: no CHANGELOG section found for ${VERSION_NO_V}"
+            echo "Expected a heading like: ## [${VERSION_NO_V}] — YYYY-MM-DD"
+            exit 1
+          fi
+
+      - name: Create release
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_SERVER_URL: ${{ gitea.server_url }}
+          GITEA_REPOSITORY: ${{ gitea.repository }}
+          GITEA_REF_NAME: ${{ gitea.ref_name }}
+        run: |
+          set -euo pipefail
+
+          BODY=$(sed -e 's/\\/\\\\/g' -e 's/"/\\"/g' -e 's/\t/\\t/g' -e 's/\r//g' release-body.md | sed ':a;N;$!ba;s/\n/\\n/g')
+          BODY="\"${BODY}\""
+
+          response=$(curl -sS -w '\n%{http_code}' \
+            -H "Authorization: token ${GITEA_TOKEN}" \
+            -H "Content-Type: application/json" \
+            -X POST \
+            "${GITEA_SERVER_URL}/api/v1/repos/${GITEA_REPOSITORY}/releases" \
+            -d "{\"tag_name\":\"${GITEA_REF_NAME}\",\"name\":\"${GITEA_REF_NAME}\",\"body\":${BODY},\"draft\":false,\"prerelease\":false}")
+
+          http_code=$(echo "$response" | tail -1)
+          payload=$(echo "$response" | sed '$d')
+
+          echo "HTTP ${http_code}"
+          if [ "$http_code" != "201" ]; then
+            echo "Failed to create release: ${payload}"
+            exit 1
+          fi
+
+          RELEASE_ID=$(echo "$payload" | grep -oE '"id"[[:space:]]*:[[:space:]]*[0-9]+' | head -1 | grep -oE '[0-9]+')
+          echo "Created release ID=${RELEASE_ID}"
+          printf '%s' "${RELEASE_ID}" > release-id.txt
+
+      - name: Upload assets
+        env:
+          GITEA_TOKEN: ${{ secrets.GITEA_TOKEN }}
+          GITEA_SERVER_URL: ${{ gitea.server_url }}
+          GITEA_REPOSITORY: ${{ gitea.repository }}
+          GITEA_REF_NAME: ${{ gitea.ref_name }}
+        run: |
+          set -euo pipefail
+          RELEASE_ID=$(cat release-id.txt)
+
+          for binary in dist/gasm-*/gasm-*; do
+            [ -f "$binary" ] || continue
+            fname=$(basename "$binary")
+            echo "Uploading ${fname}..."
+            http_code=$(curl -sS -o /dev/null -w '%{http_code}' \
+              -H "Authorization: token ${GITEA_TOKEN}" \
+              -H "Content-Type: application/octet-stream" \
+              -X POST \
+              --data-binary "@${binary}" \
+              "${GITEA_SERVER_URL}/api/v1/repos/${GITEA_REPOSITORY}/releases/${RELEASE_ID}/assets?name=${fname}")
+            echo "  HTTP ${http_code}"
+            if [ "$http_code" != "201" ]; then
+              echo "Failed to upload ${fname}"
+              exit 1
+            fi
+          done
+
+          echo "Release ${GITEA_REF_NAME} is live."

.gitea/workflows/test.yml

@@ -0,0 +1,96 @@
+# Test — gasm-devkit. Runs on push and pull request to development.
+name: Test
+
+on:
+  push:
+    branches: [development]
+  pull_request:
+    branches: [development]
+
+jobs:
+  vet:
+    runs-on: fedora
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.26"
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: gofmt
+        run: |
+          set -euo pipefail
+          unformatted=$(gofmt -l .)
+          if [ -n "$unformatted" ]; then
+            echo "These files need gofmt:"
+            echo "$unformatted"
+            exit 1
+          fi
+
+      - name: go vet
+        run: go vet ./...
+
+  test:
+    runs-on: fedora
+    needs: vet
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.26"
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Install gcc
+        run: dnf install -y gcc
+
+      - name: go test -race
+        run: go test -race -count=1 ./...
+
+      - name: Coverage gate — 80 % minimum
+        run: |
+          set -euo pipefail
+          # Exclude packages inherently untestable without hardware:
+          # debug — interactive ptrace, requires a live process
+          # cmd/gasm — CLI glue, covered by integration tests
+          go test -coverprofile=coverage.out \
+            sourcedock.dev/petrbalvin/gasm-devkit/arch \
+            sourcedock.dev/petrbalvin/gasm-devkit/asm \
+            sourcedock.dev/petrbalvin/gasm-devkit/ast \
+            sourcedock.dev/petrbalvin/gasm-devkit/format \
+            sourcedock.dev/petrbalvin/gasm-devkit/lexer \
+            sourcedock.dev/petrbalvin/gasm-devkit/lint \
+            sourcedock.dev/petrbalvin/gasm-devkit/lsp \
+            sourcedock.dev/petrbalvin/gasm-devkit/parser \
+            sourcedock.dev/petrbalvin/gasm-devkit/token \
+            sourcedock.dev/petrbalvin/gasm-devkit/verify
+          coverage=$(go tool cover -func=coverage.out | awk '/^total:/ { gsub("%", "", $3); print $3 }')
+          echo "Total coverage: ${coverage}%"
+          if awk -v c="$coverage" 'BEGIN { exit !(c+0 < 80) }'; then
+            echo "ERROR: coverage ${coverage}% is below the 80% threshold"
+            exit 1
+          fi
+
+  build:
+    runs-on: fedora
+    needs: test
+    steps:
+      - uses: actions/checkout@v7
+
+      - uses: actions/setup-go@v6
+        with:
+          go-version: "1.26"
+
+      - name: Download dependencies
+        run: go mod download
+
+      - name: Build
+        run: go build -ldflags="-s -w" -o bin/gasm ./cmd/gasm
+
+      - name: Smoke test
+        run: ./bin/gasm --version

.gitignore

@@ -10,3 +10,6 @@ coverage.out
 # Editor detritus
 *.swp
 .DS_Store
+
+# Scratch / temporary work
+_scratch/

AGENTS.md

@@ -0,0 +1,119 @@
+# AGENTS.md — gasm-devkit
+
+Repository rules for AI agents and contributors. Read before modifying any
+code in this repository.
+
+## AI Contribution Policy
+
+AI agents may assist with code, documentation, tests, and review in this
+repository. All AI-assisted changes must:
+
+- Follow the code style and conventions in this file.
+- Include the trailer `Assisted-by: <model-name>` in every commit message.
+- Not commit directly to `main` — work on `development`.
+- Pass the full Definition of Done before any commit.
+
+## Workflow
+
+- **Branching.** `development` is the working branch. `main` is
+  release-only: merge from `development`, then tag. Never commit directly
+  to `main`.
+- **Release procedure.**
+  1. Bump `version` in `justfile` and `cmd/gasm/main.go`.
+  2. Update `CHANGELOG.md` with a new `## [X.Y.Z] — YYYY-MM-DD` section.
+  3. Update `README.md` and `docs/ARCHITECTURE.md` if user-visible
+     behaviour changed.
+  4. Run the Definition of Done (below).
+  5. Commit on `development`.
+  6. `git checkout main && git merge --ff-only development`.
+  7. `git tag vX.Y.Z`.
+  8. `git checkout development`.
+  9. `GOBIN=~/.local/bin just install-bin`.
+
+## Commit Messages
+
+Conventional Commits, subject line only, imperative mood, lowercase after
+the colon:
+
+```
+feat(asm): add EVEX gather and scatter with VSIB addressing
+```
+
+Allowed types: `feat`, `fix`, `docs`, `style`, `refactor`, `perf`, `test`,
+`chore`, `ci`, `build`, `revert`.
+
+Every commit ends with exactly one trailer, using the model that
+assisted with the change:
+
+```
+Assisted-by: <model-name>
+```
+
+Replace `<model-name>` with the actual model (e.g. `DeepSeek V4 Pro`).
+
+No body, no footers, no trailing period on the subject.
+
+## Code Style
+
+Language: Go 1.26 (`toolchain go1.26.5`).
+
+### Formatter
+
+`gofmt` — zero diff. Run `just fmt` before committing.
+
+### Linter
+
+`go vet` — zero warnings. Run `just build` before committing.
+
+### Tests
+
+`go test -race -count=1 ./...` — all green, coverage ≥ 80 % (hard gate,
+enforced by `just test`).
+
+### Dependencies
+
+- **Production code:** standard library only. No third-party imports in
+  shipped code.
+- **Test code:** `golang.org/x/arch` is the sole test dependency (decode
+  oracle for round-trip validation). It is never linked into the binary.
+- **No cgo, no C, no external toolchains, no JavaScript.**
+
+### Error Handling
+
+Explicit `if err != nil`. Wrap with `fmt.Errorf("context: %w", err)`.
+No panics outside `main`. The one exception: the JIT trampoline's
+`recover`-guarded decoder hot path, which converts bounds panics to
+sentinel errors.
+
+### Assembly
+
+Plan 9 syntax (Go's assembler dialect). Hand-written — no code generators
+except `_gen/gen.go` for instruction tables (which parses the Go
+toolchain source). Every instruction table is committed; no runtime
+dependency on the Go toolchain.
+
+### File Naming
+
+- `_amd64.s`, `_arm64.s`, `_riscv64.s`, `_loong64.s` for
+  architecture-specific assembly.
+- `_linux_amd64.go` for platform-specific Go files.
+- `_test.go` suffix for test files.
+
+## Definition of Done
+
+A task is not complete until all of these pass:
+
+1. `just build` — `go vet` + `gofmt` check, zero errors, zero warnings.
+2. `just test` — full suite with `-race`, coverage ≥ 80 %.
+3. `just fmt` — produces no diff.
+4. Diagnostics — zero warnings across the project.
+5. Non-trivial changes reviewed.
+
+## Licence
+
+BSD-3-Clause. Every source file carries the SPDX header:
+
+```
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+```

CHANGELOG.md

@@ -0,0 +1,823 @@
+# Changelog
+
+All notable changes to gasm-devkit are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Conventional Commits](https://www.conventionalcommits.org/).
+
+## [development]
+
+Unreleased changes on the `development` branch.
+
+## [0.29.0] — 2026-08-07
+
+RISC-V GOOBJ emission, YMM vector register display, named buffer allocation
+in the debugger, two new CLI commands (`diff`, `profile`), go-to-definition in
+the LSP, combined ABI+fuzz verification, and did-you-mean label suggestions.
+A `--map` flag for `diff` and `--call`/`--buf` flags for `verify` extend the
+new CLI commands. A signature-parser fix corrects grouped Go parameters.
+
+### Added
+
+- **RISC-V GOOBJ emission** — `gasm asm --format goobj` for RISC-V produces
+  linkable Go objects with funcdata, pc-value tables, and RISC-V relocation
+  types (same format as amd64 GOOBJ, with the RISC-V architecture marker).
+- **`gasm diff`** — compare the machine code of two assembly files byte-for-byte;
+  shows which functions differ and the first few differing bytes.
+- **`gasm profile`** — show the basic-block structure of each function: labels,
+  offsets, frame size, and NOSPLIT flag.
+- **LSP go-to-definition** — `textDocument/definition` navigates from a label
+  reference to its definition.
+- **did-you-mean** — when the RISC-V assembler encounters an undefined label, it
+  suggests the closest existing label using Levenshtein distance.
+- **YMM vector register display** — `regs` in the debugger now shows YMM
+  registers via `PTRACE_GETFPREGS` (falls back to XMM when XSAVE is unavailable).
+- **Named buffer allocation** — `gasm debug --buf name:size:pattern` allocates
+  buffers in the debuggee filled with `zero`, `ones`, `seq`, or a hex pattern;
+  buffer pointers are placed into the argument block at the matching positions.
+- **Crash input storage** — `FuzzResult.CrashInput` stores the input that caused
+  a crash or mismatch for reproducibility.
+- **ABI + fuzz combined** — `gasm verify --fuzz` now runs ABI checks (sentinel
+  registers, canary, stack bounds) alongside differential fuzz testing.
+- **`gasm diff --map`** — compare functions whose names differ between files
+  (e.g. `--map wideCopyAVX2=wideCopyAVX512` pairs two variants regardless
+  of suffix). Unmapped functions fall back to the original name match.
+- **`gasm verify --call`** — invoke a single function with user-supplied buffers
+  (`--buf name:size:pattern`) instead of the smoke/abi/fuzz sweeps. Patterns:
+  `zero`, `ones`, `seq`, or a hex blob. Useful for partial functions (e.g.
+  decoders) that crash on random input but should succeed on valid data.
+  The arg block is printed before and after the call, showing return values.
+- **`gasm verify --ground-truth`** now documented in `--help` (was already a flag,
+  just missing from the help text).
+
+### Fixed
+
+- **Signature parser** — grouped Go parameters like `dst, src []byte` are now
+  parsed correctly (both get type `[]byte`). Previously the first name was
+  treated as its own type (`dst` with size 8), causing wrong ABI0 arg-block
+  layout in both `verify --call` and the fuzzer.
+- **Flaky JIT tests** — `runtime.KeepAlive` guards and package-level buffers
+  prevent GC from collecting heap objects whose addresses were passed to JIT
+  code via `unsafe.Pointer`; all verify tests pass 100/100 under `-race`.
+
+### Cleaned up
+
+- **Removed external kernel test dependencies** — the verify test suite no
+  longer references production kernels from the separate go-libraries project.
+  The remaining test suite uses only `testdata/verify/*.s` kernels, which are
+  part of this repository.  Coverage is identical locally and in CI (80.3 %).
+
+### Verified
+
+- `gasm diff` detects byte-level differences; `--map` pairs differently-named
+  functions for comparison.
+- `gasm verify --call` invokes functions with user-supplied buffers; the arg
+  block is printed before and after the call, showing return values.
+- LSP go-to-definition resolves labels across functions and files.
+
+## [0.28.0] — 2026-08-03
+
+RISC-V encoder: full RV64IMAFDC instruction set with RVC compression, MOV
+pseudo-instruction, SB/global symbol references, ELF64 object emission, and
+ground-truth verification against `GOARCH=riscv64 go tool asm`.
+
+### Added
+
+- **RISC-V encoder** — RV64I, RV64M, RV64A, RV64F/D, FMA, CSR, JALR.
+- **MOV pseudo-instruction** — load, store, reg-to-reg, immediate, frame mapping.
+- **RVC compression** — 22 compressed instruction types (C.LDSP, C.SDSP, C.FLDSP,
+  C.FSDSP, C.ADDI, C.LI, C.LUI, C.ADDIW, C.MV, C.ADD, C.SUB, C.XOR, C.OR, C.AND,
+  C.SLLI, C.SRLI, C.SRAI, C.ANDI, C.BEQZ, C.BNEZ, C.J, C.JR).
+- **SB/global symbols** — `MOV $sym(SB)`, `MOV sym(SB)`, `MOV rd, sym(SB)`
+  encoded as AUIPC pairs with R_RISCV_PCREL_HI20/LO12 relocations.
+- **GLOBL/DATA** — data section layout in `AssembleFileRISCV`.
+- **ELF64 emission** — `gasm asm --format elf` produces EM_RISCV objects
+  (.text, .data, .symtab, .rela.text).
+- **`gasm verify --ground-truth`** — byte-exact comparison against
+  `GOARCH=riscv64 go tool asm`.
+- **`gasm verify --profile`** — function layout listing for RISC-V.
+- **CALL** — AUIPC + JALR pair encoding.
+
+### Fixed
+
+- Parser: bare-number offset before `(SP)` no longer misidentified as pseudo.
+- MOV: `MOV $sym(FP/SP), rd` now returns an explicit error instead of silent fallback.
+- RVC: C.LDSP/C.SDSP/FLDSP/FSDSP immediate encoding now matches Go toolchain
+  (bit-interleaved format).
+
+### Verified
+
+- 118 RISC-V tests, asm coverage 83.3%.
+- Ground-truth: C.LDSP, C.SDSP, C.FLDSP, C.FSDSP byte-exact vs Go toolchain.
+
+## [0.27.0] — 2026-08-01
+
+Subprocess isolation for `--fuzz`: each function is fuzzed in its own child
+process, so a partial function (decoder) that faults on random garbage is
+reported as "CRASH (partial function, use --ground-truth)" without killing
+the parent.  CRASH is informational (exit 0); only MISMATCH is an error.
+
+### Fixed
+
+- `gasm verify --fuzz` no longer crashes the process on partial functions.
+
+## [0.26.0] — 2026-07-31
+
+Universal differential fuzzing: `gasm verify --fuzz` needs no hand-written
+reference.  It parses the `// func` signature from the assembly source,
+generates typed random inputs (slices with random content, ints, pointers to
+fixed arrays), JIT-executes BOTH the gasm-assembled and the go-tool-asm-
+assembled versions with independent buffer copies, and compares the result
+area bit-for-bit.
+
+### Added
+
+- `verify`: `FuzzFunc` / `ExtractSignatures` / `parseFuncSig` — universal
+  differential fuzz driven by the conventional `// func` comment.  Each
+  version gets its own buffer set (deep copy) so functions that write to
+  their arguments (histogram increments) don't corrupt the other's input.
+- `gasm verify --fuzz [-n N]`: runs the differential fuzz for every function
+  with a parseable signature.  Total functions (wideCopy, pack16, decorrelate,
+  analyze, autocorr) pass; partial functions (decoders that fault on malformed
+  input) should use `--ground-truth` instead.
+
+### Known limitation
+
+`--fuzz` crashes the process for partial functions (e.g. LZ4 decoders) whose
+over-copy paths read past the buffer on random garbage input.  Subprocess
+isolation (fork per function) is planned.  Use `--ground-truth` for decoders.
+
+## [0.25.0] — 2026-07-30
+
+Universal ground-truth verification: `gasm verify --ground-truth` assembles
+any `.s` file with both gasm and `go tool asm`, then compares the machine
+code byte-for-byte per function (relocation sites masked).  No hand-written
+reference needed — the Go toolchain IS the oracle.
+
+### Added
+
+- `verify`: `GroundTruth` — shells out to `go tool asm`, parses the GOOBJ
+  output (minimal reader: block offsets, nonpkg symbol table, data index)
+  and returns per-function code bytes.
+- `gasm verify --ground-truth`: compares gasm's output against the Go
+  assembler's, reporting MATCH/MISMATCH per function with the first
+  differing byte.  Relocation disp32 fields (static-symbol references the
+  linker fills) are masked before comparison.
+- Verified: go-lz4 AVX2 2/2, go-flac AVX2 17/17 functions byte-identical.
+
+## [0.24.0] — 2026-07-29
+
+The full analyze family and stereo PCM decode are now differentially tested.
+15 of 17 go-flac AVX2 kernels have bit-for-bit differential coverage; the
+two remaining (autocorrAVX2 — FMA reassociation, lpcResidualAVX2 — complex
+multi-arg) are deferred.
+
+### Added
+
+- `verify`: `analyzeO3RangeAVX2` and `analyzeO4RangeAVX2` differential tests
+  (200 iterations each, same harness as O1/O2/Res).
+- `verify`: `decodeStereo16AVX2` differential test (500 random interleaved
+  stereo PCM buffers, both channels compared sample-by-sample).
+
+## [0.23.0] — 2026-07-28
+
+The analyze family and 24-bit PCM decode join the differential suite.
+
+### Added
+
+- `verify`: `analyzeO2RangeAVX2` and `analyzeResRangeAVX2` differential
+  tests (200 iterations each, shared harness with O1: zigzag fold, partial
+  sum, overflow flag and Len32 histogram).
+- `verify`: `decodeMono24AVX2` differential test (500 random 24-bit PCM
+  buffers, sign-extension compared sample-by-sample).
+
+## [0.22.0] — 2026-07-27
+
+The remaining go-flac encoder kernels join the differential suite.
+
+### Added
+
+- `verify`: `analyzeO1RangeAVX2` differential test (300 random partitions:
+  zigzag fold, partial sum, overflow flag and the 32-bin Len32 histogram
+  compared element-by-element against the portable Go reference).
+- `verify`: `fastStereoSumsAVX2` differential test (300 random stereo
+  frames: the four zigzag-fold entropy sums compared against the scalar
+  loop).
+
+### Verified
+
+- `gasm fmt` doc-comment indentation confirmed correct: comments before
+  every TEXT are at column 0 (the RET-detection logic handles multi-exit
+  functions).
+
+## [0.21.0] — 2026-07-26
+
+Differential testing extended to all four production kernels and the CLI
+exposes the full dynamic-analysis toolkit.
+
+### Added
+
+- `verify`: go-flac AVX2 differential tests — `decodeMono16AVX2` (500
+  random PCM buffers), `pack16AVX2` (500 random int32→int16 packings) and
+  all four decorrelation kernels (200 iterations each: left-side, side-right,
+  mid-side, interleave) compared bit-for-bit against the portable Go
+  references.
+- `verify`: go-lz4 AVX-512 differential tests — `decodeBlockAVX512` (3 000
+  fuzzed LZ4 blocks + known answers) and `wideCopyAVX512` (0–1024 bytes)
+  against the same portable oracle as the AVX2 suite.
+- `gasm verify --abi`: runs each NOSPLIT function with sentinel registers
+  and a red-zone canary, reporting violations.
+- `gasm verify --profile`: lists the static basic-block count per function.
+
+## [0.20.0] — 2026-07-25
+
+Coverage profiling: the third pillar of Phase 3.  Static basic-block
+enumeration from the assembler's label map, combined with multi-input path
+diversity measurement — how many observationally distinct execution paths a
+test corpus exercises.
+
+### Added
+
+- `verify`: `Kernel.Blocks` / `Kernel.BlockCount` — enumerate basic blocks
+  from the assembler's local-label map (every jump target is a block
+  boundary; the function entry is always a block).  `decodeBlockAVX2` has
+  27 blocks.
+- `verify`: `Kernel.ProfilePaths` — run the function with a corpus of
+  argument blocks and collect distinct output fingerprints (the result
+  words); reports path diversity as a lower bound on code coverage.
+
+### Note
+
+INT3-based per-block hit counting was prototyped but deferred: Go's runtime
+signal management (sigaltstack, handler re-installation) makes raw
+rt_sigaction handlers fragile in a Go process.  The static + path-diversity
+approach delivers the project's goal (proving the SIMD path and tail handling
+execute) without fighting the runtime.
+
+## [0.19.0] — 2026-07-24
+
+Runtime ABI checks: the second pillar of Phase 3.  The JIT trampoline now
+has an ABI-checking variant that sets sentinels in the callee-saved registers
+(BP, R14) before entering the assembled function and verifies they survive on
+return, plus a red-zone canary (128 bytes below SP filled with 0xA5) that
+detects any illegal write below the stack pointer.
+
+### Added
+
+- `verify`: `CallChecked` / `Kernel.CallFuncChecked` — ABI-checking JIT call
+  with sentinel registers and red-zone canary; returns an `ABIReport`
+  (BPClobbered, R14Clobbered, RedZoneHit).
+- `verify`: the raw `leaveJITCheckedRaw` trampoline — a TEXT symbol with no
+  ABIInternal wrapper (address obtained via GLOBL/DATA), so the JIT
+  function's RET lands directly in the check code and sees the registers
+  exactly as the function left them.
+- Tests: deliberate BP/R14 clobberers detected; both go-lz4 kernels
+  confirmed ABI-clean (BP preserved, R14 preserved, red zone intact).
+
+## [0.18.0] — 2026-07-23
+
+Differential testing: the JIT-assembled go-lz4 `decodeBlockAVX2` kernel is
+fuzzed against a portable Go reference — 5 000 valid LZ4 blocks compared
+bit-for-bit, plus 2 000 hostile (random garbage) inputs with matching error
+codes.  This is the automated form of the project's bit-identical contract.
+
+### Added
+
+- `verify`: differential fuzz tests — a random LZ4 block generator produces
+  valid blocks (literals, overlapping matches, extension bytes) and the
+  JIT-assembled kernel's output is compared byte-for-byte against a portable
+  Go decoder; a hostile-input suite confirms error-code agreement on random
+  garbage (no crashes, same classification).
+
+## [0.17.0] — 2026-07-22
+
+Phase 3 begins: dynamic analysis.  A JIT execution substrate that assembles
+Plan 9 amd64 kernels into executable memory and calls them directly — pure Go
+(stdlib only, `syscall.Mmap` + an assembly trampoline), no cgo, no external
+toolchain.
+
+### Added
+
+- `verify` package: JIT infrastructure — `Map` copies machine code into a
+  W^X memory mapping, `Call` invokes it through an ABI0 trampoline that
+  switches to a prepared stack and back.  `Load`/`LoadSource`/`LoadAST`
+  parse, assemble and map a `.s` file in one step; `Kernel.CallFunc`
+  marshals the argument block and returns results.
+- `gasm verify` subcommand: assembles a file, JIT-loads it and reports the
+  available functions; with `-smoke`, calls each NOSPLIT function with
+  zeroed arguments to confirm the trampoline works end-to-end.
+- Integration tests: the go-lz4 `decodeBlockAVX2` and `wideCopyAVX2`
+  kernels (699 and 146 bytes) assemble, map and execute correctly —
+  known-answer LZ4 blocks decode bit-for-bit, wide copies of 0–1024 bytes
+  match, malformed input returns the correct error codes.
+
+### Verified
+
+- `just test` (race, 84.6 % total coverage, verify 82.2 %).
+- `gasm verify` on both go-lz4 kernels: all functions JIT-load and
+  smoke-test clean.
+
+## [0.16.0] — 2026-07-21
+
+The scalar conversions between vector and general-purpose registers — the
+last of the amd64 EVEX instruction set.
+
+### Added
+
+- `asm`: the GPR-interchanging conversions, byte for byte against the Go
+  assembler (28 ground-truth cases including memory sources and extended
+  GPRs): vector to GPR — the signed and truncated VCVT{,T}S{D,S}2SI{,Q}
+  in both VEX and EVEX, and the unsigned VCVT{,T}S{D,S}2USI{L,Q}
+  (EVEX only); GPR to vector — VCVTSI2SD{L,Q}/VCVTSI2SS{L,Q} (VEX and
+  EVEX) and VCVTUSI2SD{L,Q}/VCVTUSI2SS{L,Q} (EVEX only), whose preserved
+  vector source sits in vvvv (three Plan 9 operands).
+
+## [0.15.0] — 2026-07-20
+
+The last of the EVEX conversions and narrowing/extending moves — the EVEX
+instruction set is now complete save for the GPR-interchanging forms.
+
+### Added
+
+- `asm`: the unsigned and truncating conversions — VCVTPD2PS (and the X/Y
+  spellings, whose length the spelling fixes), VCVTPD2UDQ (X/Y),
+  VCVTTPD2UDQ (X/Y), VCVTTPD2UQQ, VCVTPS2UDQ, VCVTTPS2UDQ, VCVTPS2UQQ,
+  VCVTTPS2UQQ, VCVTTPD2QQ, VCVTTPS2QQ, VCVTUQQ2PD, VCVTUQQ2PS (X/Y) and
+  VCVTQQ2PS X/Y.
+- `asm`: the remaining sign/zero-extending moves (VPMOVSXBD/BQ/WQ and
+  VPMOVZXBD/BQ/WD/WQ, VEX and EVEX) and the complete signed and unsigned
+  narrowing stores (VPMOVS{DB,QB,DW,QW,QD,WB}, VPMOVUS{DB,QB,DW,QW,QD,WB},
+  VPMOVDB, VPMOVQW).
+- `asm`: the mask/vector conversions (VPMOVM2B/W/D/Q and VPMOVB2M/W2M/
+  D2M/Q2M), whose K register is a genuine operand rather than a mask and
+  which therefore take no masking suffixes.
+
+## [0.14.0] — 2026-07-19
+
+The floating-point helper and conversion tail of the AVX-512 set, plus
+gather and scatter with VSIB addressing — every encoding verified byte for
+byte against the Go assembler.
+
+### Added
+
+- `asm`: the floating-point helpers — reciprocals and reciprocal square
+  roots (VRCP14/VRSQRT14 PD/PS/SD/SS), exponents and mantissas (VGETEXP*,
+  VGETMANT*), scaling by powers of two (VSCALEF*), rounding (VRNDSCALE*),
+  reduction (VREDUCE*), immediate fixup (VFIXUPIMM*) and range selection
+  (VRANGE*), and floating-point class tests (VFPCLASSPD/PS X/Y/Z and
+  VFPCLASSSD/SS — a new immediate form whose reg field carries the opmask
+  destination).
+- `asm`: **gather and scatter with VSIB addressing.**  The gathers take
+  both Go spellings: the VEX form with a vector mask register (OP mask,
+  vsib, dst) and the EVEX form with an explicit K mask (OP vsib, K, dst),
+  where the EVEX L'L field follows the VSIB index register rather than the
+  data register (a ZMM index with an YMM destination encodes L'L = 10, as
+  the Go assembler emits).  The scatters (VSCATTER*/VPSCATTER*) are EVEX
+  only (OP src, K, vsib).  All eight gather and eight scatter widths.
+- `asm`: the remaining conversions — VCVTQQ2PS (the 512-bit source sets
+  the length), VCVTPD2QQ/UQQ, VCVTPS2QQ, VCVTUDQ2PD/PS, the half-precision
+  VCVTPH2PS and VCVTPS2PH (the extract layout with an immediate).
+
+## [0.13.0] — 2026-07-18
+
+The wider AVX-512 set: ternary logic, permutes, compares, expand/compress,
+the opmask instructions and the EVEX rounding/SAE/broadcast suffixes — every
+encoding verified byte for byte against the Go assembler.
+
+### Added
+
+- `asm`: the wider EVEX/AVX-512 set, across roughly sixty new ground-truth
+  cases: ternary logic (VPTERNLOGD/Q), the lane shuffles/inserts/extracts
+  (VSHUF{F,I}{32,64}X{2,4}, the VINSERT*/VEXTRACT* {F,I}{32,64}X{2,4,8}
+  family, VPALIGNR), compares with an opmask destination (VCMPPD/PS/SD/SS —
+  a new NDS-plus-immediate form with the K register in the reg field), the
+  permutes (VPERMB/W, VPERMI2/T2 D/Q/PD), the wider integer families
+  (VPMADDWD/UBSW, VPMULHUW, VPACKSSWB/USWB/SSDW/USDW, VPABS B/W/D/Q, the
+  VPROL*/VPROR* rotates, the word shifts and the EVEX W1 qword shifts),
+  expand/compress (VEXPANDPD/PS, VPEXPANDD/Q, VCOMPRESSPD/PS, VPCOMPRESSD/
+  Q), the broadcasts (VPBROADCASTB/W from a GPR or memory, VBROADCASTSS/
+  SD), the opmask-register instructions (KAND/KOR/KXNOR/KADD/KUNPCK/KNOT/
+  KSHIFTL/KORTEST B/W/D/Q and KMOVQ, whose width the L/W/pp bits select),
+  the packed single arithmetic (VADD/VSUB/VMUL/VDIV/VMIN/VMAX PS), the
+  aligned moves (VMOVAPS/APD, VMOVDQA32/64, VMOVSS), the replicating moves
+  (VMOVSLDUP/VMOVSHDUP), the conversions (VCVTPS2DQ, VCVTTPS2DQ) and the
+  remaining extending and narrowing moves (VPMOVSXBW, VPMOVZXBW, VPMOVWB,
+  VPMOVQB).
+- `asm`: the EVEX mnemonic suffixes the Go assembler accepts — the rounding
+  modes `.RN_SAE`, `.RD_SAE`, `.RU_SAE`, `.RZ_SAE` (the EVEX b bit with the
+  rounding control in L'L), suppress-all-exceptions `.SAE`, and memory
+  broadcast `.BCST` (the b bit, the vector length preserved, disp8×N scaled
+  by the element size) — each combinable with the `.Z` zeroing suffix,
+  validated against the Go assembler's bytes, and rejected on instructions
+  that do not support them.
+
+## [0.12.0] — 2026-07-17
+
+GOOBJ emission: gasm-assembled functions drop into a `go build` without the
+Go assembler.
+
+### Added
+
+- `asm`: **GOOBJ object output.**  `gasm asm --format goobj -p <pkgpath>`
+  writes the Go toolchain's own object format — the one `cmd/link` consumes
+  directly: the functions as non-package symbols qualified with the package
+  path (exactly as `cmd/asm` records assembly symbols), the `GLOBL` data,
+  one serialized `FuncInfo` per function (argument/frame sizes, the asm
+  func flag, the start line, the file table) and the four pc-value tables
+  (`pcsp`, `pcfile`, `pcline`, `pcinline`).  The `pcsp` table carries the
+  real stack deltas: the assembler now tracks every stack-adjustment
+  boundary through the prologue (`PUSHQ BP`, `SUBQ $frame, SP`) and each
+  `RET`'s epilogue, so frame-pointer functions unwind correctly.  The
+  object preamble — the version-and-experiment header the linker compares
+  verbatim — is captured from the installed `go tool asm`, so the output is
+  always consistent with the toolchain that links it.
+- `asm`: relocations against file-local `GLOBL` symbols become `R_PCREL`
+  entries in the GOOBJ output, with the instruction's displacement field
+  left zero for the linker to fill (as `cmd/asm` leaves it).
+
+### Fixed
+
+- `parser`: 64-bit `DATA` literals above `MaxInt64`
+  (`DATA mask<>+8(SB)/8, $0x800f…`) parse as unsigned and keep their bit
+  pattern, instead of being rejected as non-integer.
+
+### Verified
+
+- End-to-end: a gasm-emitted GOOBJ swapped into a `go build` in place of
+  the toolchain's assembly object links and runs with output identical to
+  the baseline binary (stack-argument calls and a `GLOBL` relocation
+  resolved by the Go linker).  All 17 go-flac AVX2 kernel functions emit as
+  a GOOBJ that `go tool nm` reads back with every symbol intact.
+
+## [0.11.0] — 2026-07-16
+
+Linkable object output: external symbols and relocatable ELF / Mach-O
+objects.
+
+### Added
+
+- `asm`: **object-file emission.**  `gasm asm --format elf` writes an
+  ELF64 relocatable object and `--format macho` a Mach-O x86-64
+  `MH_OBJECT`: a code section (`.text` / `__TEXT,__text`) and a data
+  section (`.data` / `__DATA,__data`), a symbol table with one symbol per
+  `TEXT` and `GLOBL` (file-local `<>` symbols local, the rest global), and
+  one PC-relative relocation per static-symbol reference
+  (`R_X86_64_PC32` / `X86_64_RELOC_SIGNED`, the −4 addend the form needs).
+  The ELF output is verified end-to-end: a gasm-emitted object links with
+  a C driver and runs, resolving both a file-local constant and an
+  external symbol; the Mach-O output is verified structurally with
+  `debug/macho`.
+- `asm`: **external symbol references.**  A reference to a symbol no
+  `GLOBL` in the file defines no longer aborts assembly — it is recorded
+  as an external relocation (`Image.Externals`, `FuncLayout.Relocs`) and
+  becomes an undefined global symbol in the object output.  The raw image
+  format (`--format raw`, the default) still reports them: only an object
+  file can represent a reference the linker must resolve.
+
+### Changed
+
+- `gasm asm` takes a `--format raw|elf|macho` flag selecting what `-o`
+  writes; without `--format` the behaviour is unchanged (the concatenated
+  image).
+
+## [0.10.0] — 2026-07-15
+
+The EVEX floating-point and conversion set: the packed-double arithmetic,
+the scalar SD/SS forms, VMOVDDUP and the width-changing conversions, each
+verified byte for byte against the Go assembler.
+
+### Added
+
+- `asm`: the rest of the common EVEX/VEX floating-point set — packed double
+  arithmetic (VSUBPD, VDIVPD, VMINPD, VMAXPD, VUNPCKLPD and the EVEX form of
+  VUNPCKHPD), the scalar double and single operations (VSUBSD, VDIVSD,
+  VMINSD, VMAXSD and the full VADDSS/VSUBSS/VMULSS/VDIVSS/VMINSS/VMAXSS
+  family in both VEX and EVEX — the EVEX scalar forms exist for masked and
+  zeroing use), and VMOVDDUP (lane duplication, VEX and EVEX).
+- `asm`: the width-changing conversions — VCVTDQ2PS and VCVTPS2PD (VEX and
+  EVEX; the destination sets the length for PS→PD), the EVEX form of
+  VCVTDQ2PD, and the packed-double → dword family: VCVTPD2DQ/VCVTTPD2DQ
+  (EVEX-512 only, a ZMM source and an XMM destination) and their X/Y
+  spellings (VCVTPD2DQX/Y, VCVTTPD2DQX/Y), whose length follows the wider
+  source — a new operand form, since the destination is always XMM while
+  VEX.L / EVEX.L'L ride with the source (fixed by the spelling even for a
+  memory source).
+- `asm`: masking and zeroing on every new form — the scalar SD/SS
+  arithmetic, the unpacks, VMOVDDUP and the conversions all accept the
+  explicit K1–K7 operand and the `.Z` suffix the way Go writes them.
+
+### Documented
+
+- VCVTPS2PD follows the Go assembler's encoding, which omits the F3
+  mandatory prefix (VEX.pp / EVEX.pp = 00) that Intel's maps prescribe; the
+  Go toolchain's machine code is the project's byte-for-byte oracle, and
+  gasm reproduces it exactly (and round-trips through the x86 decoder, which
+  shares the convention).
+
+### Verified
+
+- 58 new ground-truth cases — every instruction extracted from the Go
+  toolchain's own assembly (go build + an executable-segment dump), checked
+  byte for byte and round-tripped through the decoder, covering disp8×N for
+  the scalar (×8/×4), duplication (×8/×32/×64) and conversion (×8/×16/×32)
+  memory operands, the 5-bit register fields and the masked/zeroing P2
+  byte.  All four go-flac/go-lz4 kernels still assemble byte-identically
+  and lint clean.
+
+## [0.9.0] — 2026-07-14
+
+AVX-512 masking and a wider EVEX integer set.
+
+### Added
+
+- `asm`: **EVEX masking** the way Go writes it — an explicit `K1`–`K7`
+  operand placed among the operands (merging mask), and a `.Z` mnemonic
+  suffix for zeroing (`VPADDD.Z Z1, Z2, K2, Z3`).  Supported across the NDS,
+  reg/rm, immediate-shift, align, extract, convert and move forms, including
+  masked comparisons with a K destination (`VPCMPEQD Z0, Z3, K2, K1`).  K0 is
+  rejected as an explicit mask, and `.Z` without a mask is an error, matching
+  the Go assembler.
+- `asm`: the common AVX-512 F/BW integer set — VPADDB/W, VPSUBB/W, VPANDD/Q,
+  VPANDND/Q, VPMULLW, VPAVGB/W, the signed/unsigned min/max family for
+  B/W/D/Q elements, the variable shifts VPSLLVD/Q, VPSRLVD/Q, VPSRAVD/Q, the
+  EVEX forms of VPSHUFD/VPSHUFB, and the VMOVDQU8/VMOVDQU16 move aliases.
+  Register indices 16–31 encode correctly (the mod=11 quirk carries rm[4]
+  in X̄).  All verified byte for byte against the Go assembler.
+- `lint`: masked EVEX forms (`.Z` suffix, K operands) are recognised by
+  `unknown-instruction` and exempted from `operand-count`.
+
+### Fixed
+
+- `asm`: EVEX register–register operands with indices 16–31 encoded rm[4]
+  into B̄ instead of X̄ (the EVEX mod=11 extension quirk), producing wrong
+  prefix bytes for X16+/Y16+ r/m operands.
+
+## [0.8.0] — 2026-07-13
+
+Standard CLI ergonomics.
+
+### Added
+
+- `gasm --help` prints a proper top-level help (description, commands,
+  flags, examples), and every subcommand now answers `-h`/`--help` with its
+  own usage block (usage line, description, flag defaults), exiting 0.  An
+  unknown command points at `gasm --help` instead of dumping the whole usage.
+
+### Changed
+
+- The version is primarily available as the standard `gasm --version` / `-V`
+  flag; the `gasm version` spelling remains as an alias.
+
+## [0.7.0] — 2026-07-12
+
+The formatter behaves like `go fmt` and canonicalises block separation.
+
+### Added
+
+- `gasm fmt` now works like `go fmt`: with no arguments — or with a directory
+  argument — it reformats every `.s` file below it in place and lists the
+  changed files, skipping `.` and `_` directories (`.git`, `_refs`, …).
+  Explicit file arguments keep the `-w` / standard-output behaviour.
+
+### Changed
+
+- `format`: canonical blank-line layout — a new block (a label, `TEXT` or
+  `GLOBL`) is preceded by exactly one blank line, neither more nor less.
+  Comments leading a block stay with it (the blank line goes before them),
+  stacked labels share their block, the function's first label keeps hugging
+  its `TEXT`, and runs of blank lines collapse to one.  The output remains
+  idempotent and round-trips through the parser.  All four go-flac/go-lz4
+  kernels were reformatted with this release and remain byte-identical when
+  assembled.
+
+## [0.6.0] — 2026-07-11
+
+Calibrated to the Go ABI: `register-clobber` stops reporting legal code, and
+the encoder learns the legacy SSE moves.
+
+### Changed
+
+- `lint`: **`register-clobber` is now calibrated to the Go ABI**
+  (`cmd/compile/abi-internal.md`), not the platform ABI.  Go's stack-based
+  ABI0 has no System V style callee-saved registers — amd64 `BX`, `R12`–`R15`
+  and the arm64/riscv64/loong64 scratch sets are caller-saved or permanent
+  scratch, and hand-written kernels may clobber them freely.  The rule now
+  audits only the registers Go fixes across calls: the frame pointer and the
+  goroutine pointer (amd64 `BP`/`R14`, arm64 `R18`/`R28`/`R29`, riscv64
+  `X27`, loong64 `R22`), and the goroutine pointer is reported only when the
+  function can reach the runtime (is not `NOSPLIT` or makes a call) — the
+  ABI0 transition restores it on those paths, and NOSPLIT call-free leaves
+  may use it, exactly as the runtime's own assembly does.  Both go-flac
+  kernels now lint with zero diagnostics.
+
+### Fixed
+
+- `lint`: the liveness analysis took the destination operand to be the
+  *first* operand on arm64, riscv64 and loong64; Plan 9 spelling puts it last
+  on every architecture Go supports.  The def/use and save/restore
+  classification on those architectures was inverted.
+- `format`: a comment that follows a `RET` (typically the next function's doc
+  comment) is no longer indented as if it were still inside the finished
+  function body.
+
+### Added
+
+- `asm`: the legacy (non-VEX) SSE moves — `MOVOU`/`MOVO` (the Plan 9 names
+  for MOVDQU/MOVDQA), `MOVUPS`/`MOVAPS`/`MOVUPD`/`MOVAPD` and the scalar
+  `MOVSD`/`MOVSS` — and `VMOVDQU64` in the EVEX set.  All verified byte for
+  byte against the Go assembler.
+
+## [0.5.0] — 2026-07-10
+
+EVEX / AVX-512: the go-flac AVX-512 kernel now assembles, byte-identically to
+the Go toolchain, completing the production-kernel coverage.
+
+### Added
+
+- `asm`: **EVEX (AVX-512) encoding** — the four-byte EVEX prefix with the
+  5-bit register fields (Z0–Z31, X/Y 16–31, with the reg-r/m X̄ quirk and
+  V'̄ shared between vvvv and the SIB index), opmask registers (K0–K7) as
+  operands and as mask destinations, and the compressed disp8×N displacement
+  (the multiplier follows the memory operand's size, as the Go assembler's
+  opcode tables prescribe).  Covers every AVX-512 instruction the go-flac
+  kernels use: VPXORD/Q, VPADDD, VPSUBD/Q, VPUNPCK*DQ, VPMULLD/Q, VPERMD,
+  VPSLLD/VPSRAD/VPSRAQ, VALIGND, VPCMPEQD (K destination), VMOVDQU32,
+  VMOVUPD, VCVTQQ2PD, VPMOVSXDQ, the narrowing stores VPMOVDW/VPMOVQD, the
+  extracts VEXTRACTI64X4/VEXTRACTF64X4, VFMADD231PD, VADDPD, VMULPD, the
+  broadcasts VPBROADCASTD/Q (GPR and memory sources take different opcodes)
+  and the mask moves KMOVW/KTESTW.  Masking/zeroing suffixes are out of scope
+  — the kernels use neither.
+- `asm`: `AssembleFile` now accepts file-defined global (`non-<>`) symbols
+  too; a reference is external only when no `GLOBL` in the file defines it.
+
+### Fixed
+
+- `asm`: registers X16–Y31 force the EVEX encoding of dual-form mnemonics;
+  previously a `VPBROADCASTD AX, Y30` fell into the VEX encoder, which cannot
+  represent indices above 15 and silently truncated them.
+- `asm`: the VEX encoder now rejects vector register indices 16–31 instead of
+  encoding a truncated (wrong) register.
+
+### Verified
+
+- All 10 functions of the go-flac `avx512_amd64.s` kernel assemble
+  byte-identically to the Go toolchain's machine code (the disp32 of the one
+  `VMOVDQU32 idx16(SB), Z13` load is linker-filled in Go and resolved within
+  gasm's own image — checked to reach the right constant bytes).  The AVX2
+  kernel's 17 functions remain byte-identical.
+
+## [0.4.0] — 2026-07-09
+
+The standalone assembler reaches the whole go-flac AVX2 kernel: static
+symbols assemble, and all 17 kernel functions now match the Go toolchain's
+machine code byte for byte.
+
+### Added
+
+- `asm`: **file-level assembly** — `AssembleFile` turns a parsed file into an
+  `Image`: the function bodies in source order followed by a data section
+  built from the file's `GLOBL`/`DATA` directives (each symbol 16-aligned).
+- `asm`: **static-symbol (`SB`) operands** — `mask<>(SB)` references encode as
+  RIP-relative loads with a patched disp32, resolved against the image layout
+  so the output is self-consistent and position-independent.  External
+  (non-file-local) symbols are rejected with a clear error: they need
+  object-file emission.
+- `gasm asm` prints the data section and symbol map alongside the functions
+  and writes the whole image (code + data) with `-o`.
+
+### Verified
+
+- All 17 functions of the go-flac `avx2_amd64.s` kernel assemble
+  byte-identically to the Go toolchain's machine code; the only differing
+  bytes are the displacements of the two `VMOVDQU mask24<>(SB), X15` loads,
+  which the Go linker fills at link time and gasm resolves within its own
+  image (checked to reach the right constant bytes).
+
+## [0.3.0] — 2026-07-08
+
+The assembler reaches byte-identical parity with the Go toolchain on the
+production go-flac AVX2 kernels: every one of the 15 kernel functions that
+avoid global symbols now assembles to exactly the Go assembler's bytes (the
+two holdouts load a file-local constant through `SB` and wait on relocation
+support).
+
+### Added
+
+- `asm`: the scalar instruction families the kernels use — `CMOVcc` and
+  `SETcc` (conditions spelled exactly like the jumps), `LZCNT`/`TZCNT`
+  (legacy `F3 0F BD/BC`), the sign/zero-extending moves (`MOVBLZX`, `MOVBQZX`,
+  `MOVWLZX`, `MOVWQZX`, `MOVWLSX`, `MOVLQSX`), `CVTSL2SD`/`CVTSQ2SD` (the
+  legacy SSE encoding, as the Go assembler emits it), the traditional
+  three-operand `IMUL3{W,L,Q}`, and the variable-count vector shifts
+  (`VPSRLQ X0, Y8, Y8` — the count in an XMM register or memory takes the
+  ordinary NDS form).
+- `asm`: **jump relaxation** — jumps start in the short (rel8) form and
+  expand to rel32 when the settled displacement does not fit, iterating the
+  layout to a fixed point (CALL is always rel32).
+- `asm`: **jump-to-jump folding** — a conditional jump to a label whose only
+  instruction is an unconditional jump is redirected to the ultimate
+  target, replicating the Go toolchain's linker, which chases such chains
+  before it encodes branches.
+- `parser`: leading negative displacements with a base and index
+  (`LEAQ -4(DX)(R9*4), R9`) parse into a fully populated address.
+
+### Fixed
+
+- `asm`: `CMP` with a register or memory operand computed **second − first**
+  instead of first − second, silently inverting every condition that followed
+  (`CMPQ SI, R10; JGE` tested R10 ≥ SI).  The encoding now always records
+  first − second — `CMP r/m, r` with the first operand in r/m, `CMP r, r/m`
+  with the first operand in reg — and is byte-identical to the Go assembler.
+- `asm`: register-to-register `MOV` now uses the `r/m ← r` opcode (reg =
+  source), the Go assembler's choice; the output is byte-identical.
+
+## [0.2.0] — 2026-07-07
+
+The Phase 2 assembler grows the SIMD set: shuffles, extract/insert, permute
+and the moves, on top of the Phase 1 VEX forms.
+
+### Added
+
+- `asm`: four new VEX (AVX/AVX2) operand forms, each validated by round-trip
+  decoding through `golang.org/x/arch` **and** byte-for-byte against the
+  machine code the real Go assembler emits:
+  - the immediate shuffle (`VPSHUFD`, `VPERMQ`),
+  - the three-operand-plus-immediate form (`VSHUFPD`, `VPERM2I128`,
+    `VINSERTI128`),
+  - the lane extract (`VEXTRACTI128`, `VEXTRACTF128` — the YMM source occupies
+    the ModRM.reg field, the XMM/memory destination the r/m field),
+  - the direction-sensitive moves (`VMOVDQU`, `VMOVUPD`, `VMOVD`, `VMOVQ`,
+    `VMOVSD` — each direction picks its own opcode and VEX.W; a vector→vector
+    move uses the store-form layout, matching the Go assembler),
+  - the no-operand `VZEROUPPER`, and `VPERMD` in the NDS form,
+  - the floating-point and FMA set (`VADDPD`, `VMULPD`, `VXORPD`,
+    `VUNPCKHPD`, the scalar `VADDSD`/`VMULSD`, `VCVTDQ2PD`, `VFMADD231PD`).
+  With the scalar set and the earlier NDS / reg-rm / immediate-shift forms,
+  the encoder now covers every integer, shuffle and FP instruction the
+  go-flac AVX2 kernels use.
+- `asm`: `CMP` accepts the immediate in the second operand position
+  (`CMPL CX, $31`) — the spelling the Go assembler accepts — encoding it
+  identically to the immediate-first form.
+
+### Fixed
+
+- `asm`: an unused VEX.vvvv field is now stored as `1111` (v̄vvv = 1111), as
+  the hardware requires — the previous value (`0000`) made the two-operand
+  reg/rm forms (VPMOVSXWD, VPBROADCASTD, VMOVMSKPS, …) raise #UD on real CPUs
+  and differ from the Go assembler's bytes.  The round-trip decoder ignores
+  the field on these instructions, which is why the byte-for-byte Go
+  comparison (added this release) is now part of the test suite.
+
+## [0.1.0] — 2026-07-06
+
+Initial release — the Phase 1 foundation.
+
+### Added
+
+- `token`, `lexer`, `ast`, `parser`: a hand-written, error-tolerant front end
+  for Plan 9 assembly.  The lexer splices C-preprocessor line continuations
+  (`\` before a newline) so multi-line `#define` macros parse as one opaque
+  directive.  Validated against the production AVX2/AVX-512 kernels in
+  `go-libraries/go-flac` and the Go runtime's `src/runtime/*.s` for all four
+  architectures, with zero parse errors.
+- `arch`: register files and **complete** instruction tables for amd64,
+  arm64, riscv64 and loong64, with the middle-dot symbol separator and static
+  (`<>`) symbols.  Instruction names are generated from the Go toolchain's own
+  assembler source (`just gen`) — the `anames` opcode lists plus the common
+  opcodes and the per-architecture front-end aliases (arm64 `B`/`BL`, the
+  `.P`/`.W` addressing suffixes, loong64 `JAL`, the x86 conditional-jump
+  spellings) — so every mnemonic the real assembler accepts is recognised.
+- `lint`: conservative rules — `unknown-instruction`, `operand-count`,
+  `undefined-label`, `duplicate-label`, `missing-ret`,
+  `missing-textflag-include`, `abi-argsize` and `unreachable-code`.  Macro
+  invocations are recognised (in-file `#define` names and underscore
+  identifiers) and the label/RET heuristics are suppressed in macro-using
+  files.  `abi-argsize` parses the `// func` signature with the Go parser and
+  checks the declared TEXT argument size against Go's ABI0 layout;
+  `unreachable-code` flags dead code after `RET`, suppressed where reachability
+  is undecidable (PC-relative jumps, register-indirect branches, `#ifdef`).
+  Register liveness is computed by dataflow over the control-flow graph (basic
+  blocks, def/use, iterative backward iteration) and drives `register-clobber`,
+  an audit that flags a callee-saved register written but never saved/restored.
+  `funcdata-pcdata` validates the structure of `FUNCDATA`/`PCDATA` directives.
+  Zero error-severity diagnostics across the 90-file Go runtime corpus and the
+  production go-flac kernels (the `register-clobber` audit additionally reports
+  the go-flac kernels' unsaved callee-saved register use for review).
+- `format`: an idempotent canonical formatter (operand spacing and per-function
+  mnemonic alignment) that preserves comments and round-trips through the
+  parser.
+- `lsp`: a Language Server Protocol server over stdio providing completion,
+  hover documentation, document symbols, publish-diagnostics and semantic-token
+  highlighting.
+- `asm`: a standalone amd64 (x86-64) assembler — an instruction encoder (REX/
+  ModR-M/SIB/displacement/immediate plus the scalar instruction set, and VEX/
+  AVX2 SIMD across three operand forms — NDS, reg/rm and immediate-shift —
+  covering the bulk of the integer SIMD set) validated by round-trip decoding
+  against `golang.org/x/arch`, and an assembler that drives the parser's AST
+  into the encoder with local-label resolution and `FP`/`SP` frame mapping
+  (plus Go prologue/epilogue generation), producing output byte-identical to the
+  Go assembler for the supported operand forms.
+- `cmd/gasm`: the `gasm` binary with `tokens`, `parse`, `fmt`, `lint`, `asm`
+  and `lsp` subcommands.
+- `_gen`: the generator that rebuilds the architecture instruction tables from
+  the Go toolchain source (`just gen`).

CONTRIBUTING.md

@@ -0,0 +1,94 @@
+# Contributing to gasm-devkit
+
+## Prerequisites
+
+- Go 1.26 or later (`toolchain go1.26.5`)
+- `just` command runner
+- A Linux, FreeBSD, or macOS host on amd64 or arm64
+
+## Development Setup
+
+```sh
+git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
+cd gasm-devkit
+just install        # download module dependencies
+just build          # go vet + gofmt check
+just test           # full test suite with race detector
+```
+
+## Commands
+
+Every just recipe:
+
+| Recipe | What it does |
+|--------|-------------|
+| `just` | List all recipes |
+| `just install` | `go mod download` |
+| `just build` | `go vet ./...` + `gofmt -l .` check — zero errors required |
+| `just test` | `go test -race -count=1 -coverprofile=coverage.out ./...` + 80 % coverage gate |
+| `just fmt` | `gofmt -w .` |
+| `just run -- lint file.s` | Run the CLI with `go run` (args after `--`) |
+| `just install-bin` | Install `gasm` into `$GOBIN` with the release version stamped |
+| `just gen` | Regenerate `arch/*_gen.go` instruction tables from the Go toolchain |
+| `just uninstall` | Remove build artefacts (`coverage.out`, `gasm`, `*.test`) |
+
+## Running a Single Test
+
+```sh
+go test -run TestVexGroundTruth ./asm/
+go test -run TestDifferentialLZ4Fuzz ./verify/
+```
+
+## Testing the Debugger
+
+The interactive debugger (`gasm debug`) requires a compiled binary —
+`go run` does not work for the child process. Install first:
+
+```sh
+just install-bin
+gasm debug --func add testdata/verify/basic_amd64.s
+```
+
+## Code Style
+
+See [AGENTS.md](AGENTS.md) for the full style guide. Key points:
+
+- `gofmt` — zero diff.
+- `go vet` — zero warnings.
+- Standard library only in production code; `golang.org/x/arch` in tests.
+- No cgo, no C, no JavaScript.
+- Hand-written Plan 9 assembly; tables generated only via `_gen/gen.go`.
+
+## Branches and Releases
+
+- `development` is the working branch.
+- `main` is release-only: `git merge --ff-only development`, then `git tag vX.Y.Z`.
+- Conventional Commits: `feat(asm): add EVEX gather and scatter`.
+- Every commit ends with `Assisted-by: <model-name>`.
+
+## CI
+
+There is no CI pipeline in this repository. The Definition of Done
+(`just build` + `just test` + `just fmt`) is enforced locally.
+
+## AI-Assisted Contributions
+
+AI agents may assist with code, documentation, tests, and review. All
+AI-assisted changes must:
+
+- Include the trailer `Assisted-by: <model-name>` in the commit message
+  (e.g. `Assisted-by: DeepSeek V4 Pro`).
+- Follow the [AGENTS.md](AGENTS.md) rules.
+- Pass the Definition of Done before committing.
+
+Attribute agent authorship in issues and pull requests on one trailing
+line:
+
+```
+_Assisted-by: DeepSeek V4 Pro_
+```
+
+## Questions
+
+Open an issue at
+[sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit/issues).

README.md

@@ -0,0 +1,362 @@
+# gasm-devkit
+
+Developer tooling for **GAsm** — Go's built-in Plan 9 assembler.
+
+[sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit)
+
+Go ships an assembler but no tooling for it.  There is no syntax highlighting,
+no autocomplete, no linter, no static analyser, no formatter, no standalone
+assembler and no debugger for `.s` files.  Developers write assembly blind,
+validate it by benchmark, and debug it by print statement.
+
+gasm-devkit is the missing toolkit.  It is a single, self-contained binary —
+`gasm` — that brings proper developer tooling to Plan 9 assembly:
+
+```
+gasm tokens   dump the lexical token stream
+gasm parse    parse and report syntax errors
+gasm fmt      canonicalise formatting (gofmt for assembly)
+gasm lint     static checks
+gasm lsp      language server (completion, hover, symbols, diagnostics, highlighting)
+gasm asm      standalone assembler                  (Phase 2)
+gasm verify   dynamic analysis & verification       (Phase 3)
+gasm debug    source-level debugger                 (Phase 4)
+gasm diff     compare machine code of two .s files
+gasm profile  show basic-block structure of functions
+```
+
+> **Status: Phase 4 — done, Phase 5 underway.**  Phase 1 (the language
+> foundation, linter, formatter and language server) shipped in v0.1.0;
+> Phase 2 (the standalone assembler — the full amd64 instruction set plus
+> ELF, Mach-O and GOOBJ object emission) in v0.12.0; Phase 3 (dynamic
+> analysis — JIT execution, differential testing, ABI checks and coverage
+> profiling) in v0.25.0; Phase 4 (interactive debugger — ptrace-based,
+> breakpoints, watchpoints, stepping, vector register display, named buffer
+> allocation) in v0.27.0; RISC-V encoder (RV64IMAFDC + RVC, ELF emission,
+> ground-truth, GOOBJ) in v0.28.0–v0.29.0.  See [Roadmap](#roadmap).
+
+## Architecture support
+
+gasm-devkit targets every architecture Go's assembler speaks.  The instruction
+tables are **generated from the Go toolchain's own assembler source**
+(`cmd/internal/obj/<arch>`), so gasm-devkit recognises *every* mnemonic the
+real assembler accepts — not a hand-maintained subset that drifts and rots.
+
+| Architecture | GOARCH      | File suffix    | Instructions recognised            |
+|--------------|-------------|----------------|------------------------------------|
+| AMD64        | `amd64`     | `_amd64.s`     | 1600 + common opcodes + traditional aliases |
+| ARM64        | `arm64`     | `_arm64.s`     | 538 + common opcodes               |
+| RISC-V       | `riscv64`   | `_riscv64.s`   | 961 + common opcodes               |
+| LoongArch    | `loong64`   | `_loong64.s`   | 799 + common opcodes               |
+
+"Common opcodes" are the instructions shared by every architecture (`RET`,
+`JMP`, `NOP`, `CALL`, `TEXT`, `FUNCDATA`, `PCDATA`, …).  AMD64 additionally
+carries the traditional conditional-jump spellings (`JZ`, `JNZ`, `JA`, `JC`,
+…) that the assembler accepts as aliases.  Regenerating the tables is one
+command — `just gen` — and requires only a Go installation; the committed
+output has no runtime dependency on the toolchain.
+
+The target *architectures* above are what the toolkit analyses.  The toolkit
+itself is portable Go and builds on Linux, FreeBSD and macOS, on amd64 and
+arm64 hosts.
+
+## Roadmap
+
+The work is delivered in four phases.  Each phase is completed and hardened
+before the next begins.  The ordering follows a dependency chain: understand
+the code statically (Phase 1), make it runnable (Phase 2), then run it and
+observe or control it (Phases 3–4).
+
+### Phase 1 — language foundation, editor tooling and static analysis · *done*
+
+Everything needed to read, understand, check, format and highlight GAsm —
+without executing it.
+
+| Capability | Status |
+|------------|--------|
+| Lexer — permissive, position-aware scanner for all four architectures | done |
+| Parser — line-oriented, error-tolerant, full AST with source positions | done |
+| Instruction + register tables for amd64, arm64, riscv64, loong64 (generated, complete) | done |
+| Linter — `unknown-instruction`, `operand-count`, `undefined-label`, `duplicate-label`, `missing-ret`, `missing-textflag-include`, `abi-argsize`, `unreachable-code`, `register-clobber`, `funcdata-pcdata` | done |
+| Formatter — idempotent, comment-preserving, per-function alignment; a `RET` terminates the body for indentation, so the next function's doc comment stays at column 0; exactly one blank line before every block (label, `TEXT`, `GLOBL`) and runs of blanks collapsed; directory / no-argument mode reformats every `.s` in place, `go fmt`-style | done |
+| Language server — completion, hover, document symbols, diagnostics, semantic-token highlighting | done |
+| CLI — `gasm tokens / parse / fmt / lint / lsp` | done |
+| Real-world validation against production AVX2 / AVX-512 kernels | done |
+| Lint hardening — zero false positives across the Go runtime corpus (90 files, all four architectures): macro-invocation handling, branch aliases (`B`/`BL`/`JAL`), addressing suffixes (`.P`/`.W`), terminal `UNDEF` | done |
+| Static analysis — `abi-argsize` (argument/result area computed from the `// func` signature under Go's ABI0 layout and checked against the TEXT declaration) and `unreachable-code` (dead code after `RET`, suppressed where reachability is undecidable: PC-relative jumps, register-indirect branches, `#ifdef`) | done |
+| Static analysis — register liveness (CFG construction + per-instruction def/use + iterative backward dataflow) driving `register-clobber`, calibrated to the **Go ABI** (not System V): flags writes to the registers Go fixes across calls — the frame pointer and the goroutine pointer (`R14` on amd64, `R28`/`R29` on arm64, `X27` on riscv64, `R22` on loong64, plus the OS-reserved `R18` on arm64) — that are never saved/restored; the goroutine pointer is reported only when the function can reach the runtime (not `NOSPLIT`, or makes calls), matching how the runtime's own assembly uses it. `funcdata-pcdata` structural validation of `FUNCDATA`/`PCDATA` operands and indices | done |
+
+> **Limitation — macros.** gasm-devkit reads `.s` source as written; it does
+> **not** run the C preprocessor, so `#define` macros are not expanded.  Files
+> that use macros (the runtime's `asm_*.s`, `race_*.s`, `sys_*.s`, …) parse
+> cleanly, and macro *invocations* are recognised and never flagged, but the
+> `undefined-label` and `missing-ret` heuristics are suppressed in macro-using
+> files because labels a macro defines are invisible without expansion.  Full
+> macro expansion is future work (it pairs naturally with the Phase 2
+> assembler).  Hand-written, macro-free kernels — such as everything in
+> `go-libraries` — are analysed in full.
+
+### Phase 2 — standalone assembler · *done*
+
+Assembly without the Go toolchain in the loop.
+
+- **`gasm asm`:** a standalone assembler that turns a `.s` file into machine
+  code directly — pure Go, no `go build`, no external toolchain.  Useful for
+  fast iteration, for environments without a full Go installation, and as the
+  execution substrate that Phases 3 and 4 build on.
+
+Done so far:
+
+- An amd64 (x86-64) **instruction encoder** — REX/ModR-M/SIB/displacement/
+  immediate machinery and the scalar instruction set (MOV, the ALU group, TEST,
+  LEA, INC/DEC/NEG/NOT, shifts, IMUL and IMUL3, PUSH/POP, JMP/CALL/Jcc,
+  CMOVcc, SETcc, LZCNT/TZCNT, the sign/zero-extending moves — MOVBLZX and
+  friends, MOVLQSX — and CVTSL2SD/CVTSQ2SD), validated by round-tripping
+  every encoding through `golang.org/x/arch`'s decoder and byte-for-byte
+  against the Go assembler.
+- An **assembler** that drives the parser's AST into the encoder with local-
+  label resolution — jumps start in the short (rel8) form and expand to rel32
+  when the displacement does not fit, and jump-to-jump chains are folded the
+  way the Go toolchain folds them — so `gasm asm <file>` emits machine code
+  for each `TEXT` function.
+- **File-level assembly with static data** — `GLOBL`/`DATA` symbols are laid
+  out in a data section behind the code and references to them (`mask<>(SB)`)
+  are encoded RIP-relative with the displacement resolved within the image,
+  so the output is self-consistent and position-independent.  References to
+  symbols no `GLOBL` in the file defines are recorded as relocations and
+  carried into the object-file output.
+- **GOOBJ emission** — `gasm asm --format goobj -p <pkgpath>` writes the Go
+  toolchain's own object format (the one `cmd/link` consumes directly), so
+  gasm-assembled kernels drop into a `go build` without the Go assembler:
+  the functions as non-package symbols, `GLOBL` data, one `FuncInfo` per
+  function and the pc-value tables (`pcsp` with the real prologue/epilogue
+  stack deltas, `pcfile`, `pcline`, `pcinline`).  Verified end-to-end by
+  swapping a gasm-emitted object into a `go build` in place of the
+  toolchain's, linking and running — bit-identical behaviour.
+- **Object-file emission** — `gasm asm --format elf` / `--format macho`
+  writes a relocatable object (a `.text` and a `.data` section, a symbol
+  table — file-local `<>` symbols local, the rest global — and one
+  `R_X86_64_PC32` / `X86_64_RELOC_SIGNED` relocation per static-symbol
+  reference) that links with the system toolchain: external references
+  resolve against undefined symbols, file-local ones against the data
+  section.  Verified end-to-end by linking a gasm-emitted object with a C
+  driver and running it.
+- **`FP`/`SP` frame mapping** — the pseudo-registers are translated onto the
+  hardware stack pointer (`x+N(FP)` → `(N+8)(SP)` for a zero frame, `(N+frame+
+  16)(SP)` with a frame pointer; locals via `x-N(SP)`), and the Go-style
+  prologue/epilogue is generated for functions with a frame.  The output is
+  **byte-identical to the Go assembler** for these cases (verified against
+  `go tool objdump`).
+- **SIMD (VEX / AVX2)** — the VEX prefix machinery (2-byte C5 and 3-byte C4)
+  with XMM/YMM vector registers, validated by round-trip decoding **and**
+  byte-for-byte against the Go assembler's machine code, across eight operand
+  forms: the three-operand NDS form (VPADDD/Q, VPSUBD/Q, VPXOR, VPOR, VPAND/N,
+  VPCMPEQD, VPCMPGTQ, VPUNPCK*, VPMULLD, VPMULDQ, VPSHUFB, VPACKSSDW,
+  VPERMD), the two-operand reg/rm form (VPMOVSXWD/DQ, VPMOVZXDQ,
+  VPBROADCASTD/Q, VPMOVMSKB, VMOVMSKPS, VCVTDQ2PD), the immediate-shift and
+  variable-count shifts (VPSLLD/Q, VPSRAD, VPSRLD/Q with an immediate or an
+  XMM/memory count), the immediate shuffle (VPSHUFD, VPERMQ), the
+  three-operand-plus-immediate form (VSHUFPD, VPERM2I128, VINSERTI128), the
+  lane extract (VEXTRACTI128, VEXTRACTF128), the direction-sensitive moves
+  (VMOVDQU, VMOVUPD, VMOVD, VMOVQ, VMOVSD), the no-operand VZEROUPPER, and
+  the floating-point set: the packed double arithmetic
+  (VADDPD/VSUBPD/VMULPD/VDIVPD/VMINPD/VMAXPD), the unpacks
+  (VUNPCKHPD/VUNPCKLPD), the scalar SD and SS operations, VMOVDDUP, the
+  width-changing conversions (VCVTDQ2PS, VCVTPS2PD, VCVTDQ2PD and the
+  VCVTPD2DQX/Y / VCVTTPD2DQX/Y spellings, whose VEX.L follows the wider
+  source) and VFMADD231PD.
+- **SIMD (EVEX / AVX-512)** — the four-byte EVEX prefix with the 5-bit
+  register fields (Z0–Z31, X/Y 16–31), opmask registers (K0–K7 as operands
+  and mask destinations, KMOVW, KTESTW) and the compressed disp8×N
+  displacement, covering every AVX-512 instruction the go-flac kernels use:
+  VPXORD/Q, VPADDD, VPSUBD/Q, VPUNPCK*DQ, VPMULLD/Q, VPERMD, VPSLLD/VPSRAD/
+  VPSRAQ, VALIGND, VPCMPEQD (with a K destination), VMOVDQU32, VMOVUPD,
+  VCVTQQ2PD, VPMOVSXDQ, the narrowing stores VPMOVDW/VPMOVQD, the lane
+  extracts VEXTRACTI64X4/VEXTRACTF64X4, VFMADD231PD, VADDPD, VMULPD,
+  VMOVDQU64 and the broadcasts VPBROADCASTD/Q from a GPR or memory, plus the
+  wider AVX-512 F/BW integer set (VPADDB/W, VPSUBB/W, VPANDD/Q/ND/NQ, VPMULLW,
+  VPMIN*/VPMAX* for B/W/D/Q elements, signed and unsigned, VPAVGB/W, the variable
+  shifts VPSLLV*/VPSRLV*/VPSRAV*, VMOVDQU8/16), the common floating-point
+  and conversion set (the packed double and single arithmetic
+  VADD/VSUB/VMUL/VDIV/VMIN/VMAX PD and PS, the scalar SD/SS operations —
+  whose EVEX forms exist for masked and zeroing use — the VUNPCK{L,H}PD
+  unpacks, VMOVDDUP, VMOVSLDUP/VMOVSHDUP and the VCVT* conversions), and
+  the wider AVX-512 set: ternary logic (VPTERNLOGD/Q), lane shuffles,
+  inserts and extracts (VSHUF{F,I}{32,64}X{2,4}, the VINSERT*/VEXTRACT*
+  {F,I}{32,64}X{2,4,8} family, VPALIGNR), compares with an opmask
+  destination (VCMPPD/PS/SD/SS), the permutes (VPERMB/W, VPERMI2/T2
+  D/Q/PD), the wider integer families (VPMADDWD/UBSW, VPMULHUW, VPACK*,
+  VPABS*, the VPROL*/VPROR* rotates and the word shifts), expand/compress
+  (VEXPAND*/VCOMPRESS*, VPEXPAND*/VPCOMPRESS*), the broadcasts
+  (VPBROADCASTB/W, VBROADCASTSS/SD), the opmask instructions (KAND/KOR/
+  KXNOR/KADD/KUNPCK/KNOT/KSHIFTL/KORTEST, KMOVQ), the aligned moves
+  (VMOVAPS/APD, VMOVDQA32/64, VMOVSS) and the remaining extending and
+  narrowing moves, the floating-point helper and conversion tail
+  (VRCP14*, VRSQRT14*, VGETEXP*, VGETMANT*, VSCALEF*, VRNDSCALE*,
+  VREDUCE*, VFIXUPIMM*, VRANGE*, VFPCLASS* with a K destination, and the
+  VCVT* conversions VCVTQQ2PS, VCVTPD2QQ/UQQ, VCVTPS2QQ, VCVTUDQ2PD/PS,
+  VCVTPH2PS, VCVTPS2PH), and gather/scatter with VSIB addressing
+  (VGATHER*/VPGATHER* in both the VEX mask-register spelling and the EVEX
+  K-mask spelling — where the L'L field follows the VSIB index — plus
+  VSCATTER*/VPSCATTER*).  The EVEX mnemonic suffixes the Go assembler
+  accepts are honoured: rounding modes (.RN_SAE, .RD_SAE, .RU_SAE,
+  .RZ_SAE), suppress-all-exceptions (.SAE) and memory broadcast (.BCST,
+  with the element-sized disp8×N), each combinable with the .Z zeroing
+  suffix.  Masking is supported the way
+  Go writes it — an explicit K1–K7 operand placed among the operands, and a
+  `.Z` mnemonic suffix for zeroing.
+- **Legacy SSE moves** — `MOVOU`/`MOVO` (the Plan 9 names for MOVDQU/MOVDQA),
+  `MOVUPS`/`MOVAPS`/`MOVUPD`/`MOVAPD` and the scalar `MOVSD`/`MOVSS`.
+- **Both go-flac kernels — all 17 AVX2 and all 10 AVX-512 functions —
+  assemble byte-identically to the Go toolchain's machine code**; the only
+  differing bytes are the displacements of the static-constant loads, which
+  the Go linker fills at link time and gasm resolves within its own image
+  (verified to reach the right constant bytes).
+
+Remaining for Phase 2:
+
+- External (cross-package) symbol references in the GOOBJ output —
+  **deferred** with a recorded decision and three options; see
+  [`docs/DEFERRED.md`](docs/DEFERRED.md).  Single-package objects (no
+  cross-package references) work today, which covers the production
+  kernels.  With that item deferred, the amd64 instruction set — scalar,
+  VEX/AVX2 and the full EVEX/AVX-512 set including GPR-interchanging
+  conversions — is complete, and RISC-V encoding (RV64IMAFDC + RVC)
+  including ELF and GOOBJ emission is complete.
+
+### Phase 3 — dynamic analysis · *done*
+
+Run the code and check what static analysis cannot.  The oracle is the
+portable Go implementation every kernel is derived from.
+
+- **`gasm verify`:**
+	  - **JIT execution substrate** — *done.*  Assemble the kernel, map it into
+	    executable memory (`syscall.Mmap`, W^X) and call it through an ABI0
+	    trampoline; pure Go, no cgo, no external toolchain.
+	  - **Differential testing** — *done.*  The JIT-assembled kernel is fuzzed
+	    against a portable Go reference, comparing the result bit-for-bit;
+	    the automated form of the project's bit-identical contract.
+	  - **Runtime ABI checks** — *done.*  The ABI-checking trampoline sets
+	    sentinels in BP and R14, verifies they survive the call, and fills a
+	    128-byte red-zone canary below SP.
+	  - **Coverage / basic-block profiling** — *done.*  Static block enumeration
+	    from the assembler's label map plus multi-input path-diversity
+	    measurement: how many observationally distinct execution paths a
+	    test corpus exercises.
+
+### Phase 4 — debugger · *done*
+
+- **`gasm debug`:** single-step a GAsm function, inspect registers (including
+  YMM vector registers), set breakpoints on labels, allocate and fill named
+  buffers, and hex-dump memory — the interactive counterpart to Phase 3's
+  execution substrate.
+  - **MVP** — *done.*  ptrace-based debuggee subprocess (PTRACE_TRACEME +
+    LockOSThread), entry breakpoint (auto-run to function start),
+    single-step, register inspection (GPR + YMM/XMM via PTRACE_GETFPREGS),
+    label resolution, breakpoint management via `/proc/pid/mem`, named
+    buffer allocation with pattern filling (`--buf`), and an interactive REPL.
+  - **Remaining:** disassembly at PC (x86asm decode), memory-write support,
+    watchpoints, source-line mapping, and multi-platform support
+    (FreeBSD/macOS ptrace variants).
+
+### Phase 5 — the other architectures · *in progress*
+
+- **RISC-V encoding — done.**  RV64IMAFDC instruction set, RVC compression,
+  MOV pseudo-instruction, SB/global symbols (AUIPC pairs), ELF64 and GOOBJ
+  emission, and ground-truth verification against `go tool asm`.
+- **Remaining:** arm64 and loong64 encoding, plus the same encode-and-verify
+  treatment for each (instruction tables already generated from the toolchain).
+
+## Principles
+
+- **Pure Go and GAsm only.**  No C, no cgo, no external toolchains, no native
+  binaries, no JavaScript runtimes.  The parser is hand-written; there is no
+  parser generator.
+- **Self-contained.**  The toolkit's production code depends only on the
+  standard library; one binary, no runtime data files.  The single module
+  dependency, `golang.org/x/arch`, is used **only in tests** to validate the
+  instruction encoder by round-trip decoding — it is never linked into the
+  `gasm` binary.
+- **Portable.**  Builds and runs on Linux, FreeBSD and macOS; amd64 and arm64
+  hosts.  Latest stable Go only.
+- **No vendor lock-in.**  The integration surface is the Language Server
+  Protocol and a command-line interface — both open standards.  No cloud
+  service, no proprietary API, no dependence on any one editor's internals.
+- **Complete and verifiable.**  Instruction coverage is generated from the
+  assembler's own source and regenerated on demand, so it cannot silently fall
+  behind the toolchain.
+
+## Components
+
+| Package | Purpose |
+|---------|---------|
+| `token` | Lexical token kinds and source positions. |
+| `lexer` | Hand-written scanner for Plan 9 assembly. |
+| `ast` | The abstract syntax tree. |
+| `parser` | Line-oriented, error-tolerant parser producing the AST. |
+| `arch` | amd64, arm64, riscv64 and loong64 register files and instruction tables. |
+| `lint` | Conservative static checks. |
+| `format` | A canonical formatter — `gofmt` for assembly. |
+| `asm` | The standalone assembler: amd64 and RISC-V encoders, linker, object-file emitters (ELF, Mach-O, GOOBJ). |
+| `verify` | JIT execution substrate for dynamic analysis, combined ABI+fuzz differential testing (Phase 3). |
+| `debug` | Interactive ptrace debugger with GPR/YMM register display and named buffer allocation (Phase 4). |
+| `lsp` | Language Server Protocol server. |
+| `cmd/gasm` | The `gasm` binary tying it all together. |
+| `_gen` | The generator that rebuilds the instruction tables from the Go toolchain. |
+
+See [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md) for the design rationale and
+data flow, [`docs/ZED.md`](docs/ZED.md) for the editor-integration story, and
+[`docs/DEFERRED.md`](docs/DEFERRED.md) for design decisions deliberately
+postponed (with the analysis needed to pick them up again).
+
+## Quick start
+
+```sh
+just install     # download dependencies (there are none)
+just build       # go vet + gofmt check — zero errors, zero warnings
+just test        # full suite, race detector, 80 % coverage gate
+just fmt         # gofmt the tree
+just gen         # regenerate the instruction tables from the Go toolchain
+```
+
+Install the binary and use it:
+
+```sh
+just install-bin                    # installs gasm into $GOBIN
+
+gasm --help                         # overview of commands and flags
+gasm tokens kernel_amd64.s          # dump the token stream
+gasm parse  kernel_amd64.s          # parse, report syntax errors
+gasm fmt    -w kernel_amd64.s       # canonicalise in place
+gasm fmt                            # reformat every .s below here, like go fmt
+gasm lint   *.s                     # static checks
+gasm asm --format elf -o k.o k.s    # assemble to a linkable ELF object
+gasm verify kernel_amd64.s           # JIT-load and report functions
+gasm verify --ground-truth k.s      # byte-for-byte vs go tool asm
+gasm verify --call decodeBlockAVX2 --buf src:64:hex...,dst:256:zero k.s
+gasm debug --func name k.s           # interactive debugger
+gasm diff a.s b.s                    # compare machine code byte-for-byte
+gasm diff --map wideCopyAVX2=wideCopyAVX512 avx2.s avx512.s
+gasm profile k.s                     # show basic-block structure
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full development workflow,
+[docs/cli.md](docs/cli.md) for the command reference, and
+[docs/development.md](docs/development.md) for setup and recipes.
+
+## Editor integration
+
+`gasm lsp` speaks the Language Server Protocol over standard input/output, so
+any LSP-capable editor can use it — point your editor's LSP client at the
+binary and associate it with `.s` files.  Syntax highlighting is delivered as
+**LSP semantic tokens**, so no editor-specific grammar is required.  The server
+infers the target architecture from the file-name suffix
+(`_amd64.s` / `_arm64.s` / `_riscv64.s` / `_loong64.s`).
+
+Zed users should read [`docs/ZED.md`](docs/ZED.md): Zed's native highlighting
+engine (Tree-sitter, C/WASM) cannot be fed from pure Go, so the pure-Go path
+into Zed is the language server and its semantic tokens.
+
+## Licence
+
+BSD-3-Clause — the same licence as Go itself.  See [`LICENSE`](LICENSE).

asm/assemble.go

@@ -23,7 +23,7 @@ import (
 // operands require relocations and are not yet supported; the SIMD (VEX/AVX2)
 // integer and shuffle/extract/permute/move set is in.
 func Assemble(t *ast.Text) ([]byte, map[string]int, error) {
-	code, _, labels, _, err := assemble(t, nil)
+	code, _, labels, _, _, err := assemble(t, nil)
 	return code, labels, err
 }
 
@@ -60,7 +60,7 @@ type spadjStep struct {
 // assemble encodes a TEXT body, returning the machine code, the static-symbol
 // patch sites (for the file-level layout to resolve), the label table and the
 // stack-adjustment boundaries.
-func assemble(t *ast.Text, link *linkInfo) ([]byte, []sbPatch, map[string]int, []spadjStep, error) {
+func assemble(t *ast.Text, link *linkInfo) ([]byte, []sbPatch, map[string]int, []spadjStep, []LineEntry, error) {
 	fi := computeFrame(t)
 	chain := jumpChain(t)
 	resolve := func(name string) string {
@@ -84,7 +84,7 @@ func assemble(t *ast.Text, link *linkInfo) ([]byte, []sbPatch, map[string]int, [
 			case *ast.Instr:
 				sz, err := instrSize(s, fi, long[i], link)
 				if err != nil {
-					return nil, nil, nil, nil, fmt.Errorf("%s: %w", s.Mnemonic.Text, err)
+					return nil, nil, nil, nil, nil, fmt.Errorf("%s: %w", s.Mnemonic.Text, err)
 				}
 				sizes[i] = sz
 				pcs[i] = pos
@@ -125,6 +125,7 @@ func assemble(t *ast.Text, link *linkInfo) ([]byte, []sbPatch, map[string]int, [
 	out := append([]byte(nil), fi.prologue...)
 	var patches []sbPatch
 	var steps []spadjStep
+	var lines []LineEntry
 	if fi.useFP {
 		// PUSHQ BP saves the return-address-relative base (+8); the MOVQ
 		// changes nothing; SUBQ $size, SP completes the frame.
@@ -150,16 +151,17 @@ func assemble(t *ast.Text, link *linkInfo) ([]byte, []sbPatch, map[string]int, [
 		}
 		code, ps, err := encodeInstr(s, pos, offsets, fi, long[i], resolve, link)
 		if err != nil {
-			return nil, nil, nil, nil, fmt.Errorf("%s: %w", s.Mnemonic.Text, err)
+			return nil, nil, nil, nil, nil, fmt.Errorf("%s: %w", s.Mnemonic.Text, err)
 		}
 		if len(code) != sizes[i] {
-			return nil, nil, nil, nil, fmt.Errorf("%s: size mismatch (%d vs %d)", s.Mnemonic.Text, len(code), sizes[i])
+			return nil, nil, nil, nil, nil, fmt.Errorf("%s: size mismatch (%d vs %d)", s.Mnemonic.Text, len(code), sizes[i])
 		}
 		patches = append(patches, ps...)
+		lines = append(lines, LineEntry{Offset: pos, Line: s.Pos().Line})
 		out = append(out, code...)
 		pos += len(code)
 	}
-	return out, patches, offsets, steps, nil
+	return out, patches, offsets, steps, lines, nil
 }
 
 // jumpChain precomputes jump-to-jump folding: a label whose first instruction

asm/elfriscv.go

@@ -0,0 +1,232 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import (
+	"encoding/binary"
+	"fmt"
+)
+
+// RISC-V ELF64 relocatable object emission.
+
+const (
+	emRISCV = 243 // EM_RISCV
+
+	// RISC-V relocation types.
+	rRISCV32         = 1
+	rRISCVPCRELHI20  = 23 // R_RISCV_PCREL_HI20
+	rRISCVPCRELLO12I = 24 // R_RISCV_PCREL_LO12_I
+	rRISCVPCRELLO12S = 25 // R_RISCV_PCREL_LO12_S
+)
+
+// ELFRISCVObject returns the image as an ELF64 relocatable object file for
+// RISC-V (EM_RISCV, 64-bit, little-endian).  The structure mirrors the amd64
+// ELF emission: .text, .data, .symtab, .strtab and optional .rela.text.
+func (img *Image) ELFRISCVObject() ([]byte, error) {
+	le := binary.LittleEndian
+
+	const (
+		secText = 1
+		secData = 2
+	)
+
+	// Build symbol table.
+	var locals, globals []elfSym
+	for _, fn := range img.Funcs {
+		s := elfSym{
+			name:  objectName(fn.Pkg, fn.Name),
+			info:  sttFunc,
+			shndx: secText,
+			value: uint64(fn.Offset),
+			size:  uint64(fn.Size),
+		}
+		if fn.Static {
+			locals = append(locals, s)
+		} else {
+			s.info |= stbGlobal << stInfoShift
+			globals = append(globals, s)
+		}
+	}
+	for _, d := range img.DataSyms {
+		s := elfSym{
+			name:  objectName(d.Pkg, d.Name),
+			info:  sttObject,
+			shndx: secData,
+			value: uint64(d.Offset),
+			size:  uint64(d.Size),
+		}
+		if d.Static {
+			locals = append(locals, s)
+		} else {
+			s.info |= stbGlobal << stInfoShift
+			globals = append(globals, s)
+		}
+	}
+	for _, name := range img.Externals {
+		globals = append(globals, elfSym{name: name, info: stbGlobal << stInfoShift})
+	}
+	syms := []elfSym{
+		{},
+		{name: ".text", info: sttSection, shndx: secText},
+		{name: ".data", info: sttSection, shndx: secData},
+	}
+	syms = append(syms, locals...)
+	shInfo := len(syms)
+	syms = append(syms, globals...)
+	symIdx := map[string]int{}
+	for i, s := range syms {
+		symIdx[s.name] = i
+	}
+
+	// Build relocations.  Each SB reference produces a pair:
+	//   AUIPC rd, 0  → R_RISCV_PCREL_HI20
+	//   ADDI/LD/SD   → R_RISCV_PCREL_LO12_I or _S
+	// For now we record them as individual entries; at link time
+	// the linker must pair HI20 with its matching LO12.
+	type elfRela struct {
+		off    uint64
+		typ    uint32
+		sym    int
+		addend int64
+	}
+	var relas []elfRela
+	for _, fn := range img.Funcs {
+		for _, r := range fn.Relocs {
+			idx, ok := symIdx[r.Name]
+			if !ok {
+				return nil, fmt.Errorf("relocation references unknown symbol %q", r.Name)
+			}
+			// Determine relocation type from the relocation kind.
+			typ := uint32(rRISCVPCRELHI20) // default: AUIPC
+			switch r.Kind {
+			case RelPCRelLO12:
+				typ = rRISCVPCRELLO12I
+			case RelPCRelLO12S:
+				typ = rRISCVPCRELLO12S
+			case RelPCRelAbs:
+				typ = rRISCV32
+			}
+			relas = append(relas, elfRela{
+				off:    uint64(fn.Offset + r.Off),
+				typ:    typ,
+				sym:    idx,
+				addend: r.Addend - int64(r.After-r.Off),
+			})
+		}
+	}
+
+	// String tables.
+	stNames := newElfStrtab()
+	for _, s := range syms {
+		stNames.add(s.name)
+	}
+	stSections := newElfStrtab()
+	for _, n := range []string{".text", ".data", ".symtab", ".strtab", ".rela.text", ".shstrtab"} {
+		stSections.add(n)
+	}
+
+	hasRela := len(relas) > 0
+	nSections := 6
+	if hasRela {
+		nSections = 7
+	}
+	secSymtab, secStrtab := 3, 4
+	secShstr := nSections - 1
+
+	// Layout.
+	var out []byte
+	out = append(out, make([]byte, 64)...)
+
+	align := func(n int) {
+		for len(out)%n != 0 {
+			out = append(out, 0)
+		}
+	}
+
+	align(16)
+	textOff := len(out)
+	out = append(out, img.Code...)
+
+	align(16)
+	dataOff := len(out)
+	out = append(out, img.Data...)
+
+	align(8)
+	symtabOff := len(out)
+	for _, s := range syms {
+		var b [24]byte
+		le.PutUint32(b[0:], uint32(stNames.at(s.name)))
+		b[4] = s.info
+		b[5] = 0
+		le.PutUint16(b[6:], s.shndx)
+		le.PutUint64(b[8:], s.value)
+		le.PutUint64(b[16:], s.size)
+		out = append(out, b[:]...)
+	}
+
+	strtabOff := len(out)
+	out = append(out, stNames.bytes()...)
+
+	var relaOff int
+	if hasRela {
+		align(8)
+		relaOff = len(out)
+		for _, r := range relas {
+			var b [24]byte
+			le.PutUint64(b[0:], r.off)
+			le.PutUint64(b[8:], uint64(r.sym)<<32|uint64(r.typ))
+			le.PutUint64(b[16:], uint64(r.addend))
+			out = append(out, b[:]...)
+		}
+	}
+
+	shstrOff := len(out)
+	out = append(out, stSections.bytes()...)
+
+	align(8)
+	shoff := len(out)
+
+	putSh := func(name string, typ int, flags uint64, off, size int, link, info int, alignV, entsize uint64) {
+		var b [64]byte
+		le.PutUint32(b[0:], uint32(stSections.at(name)))
+		le.PutUint32(b[4:], uint32(typ))
+		le.PutUint64(b[8:], flags)
+		le.PutUint64(b[16:], 0)
+		le.PutUint64(b[24:], uint64(off))
+		le.PutUint64(b[32:], uint64(size))
+		le.PutUint32(b[40:], uint32(link))
+		le.PutUint32(b[44:], uint32(info))
+		le.PutUint64(b[48:], alignV)
+		le.PutUint64(b[56:], entsize)
+		out = append(out, b[:]...)
+	}
+	putSh("", shtNull, 0, 0, 0, 0, 0, 0, 0)
+	putSh(".text", shtProgbits, shfAlloc|shfExecInstr, textOff, len(img.Code), 0, 0, 16, 0)
+	putSh(".data", shtProgbits, shfAlloc|shfWrite, dataOff, len(img.Data), 0, 0, 16, 0)
+	putSh(".symtab", shtSymtab, 0, symtabOff, 24*len(syms), secStrtab, shInfo, 8, 24)
+	putSh(".strtab", shtStrtab, 0, strtabOff, len(stNames.bytes()), 0, 0, 1, 0)
+	if hasRela {
+		putSh(".rela.text", shtRela, 0, relaOff, 24*len(relas), secSymtab, secText, 8, 24)
+	}
+	putSh(".shstrtab", shtStrtab, 0, shstrOff, len(stSections.bytes()), 0, 0, 1, 0)
+
+	// ELF header.
+	hdr := out[:64]
+	copy(hdr[0:], []byte{0x7f, 'E', 'L', 'F', elfClass64, elfDataLSB, elfVersion, 0})
+	le.PutUint16(hdr[16:], etREL)
+	le.PutUint16(hdr[18:], emRISCV)
+	le.PutUint32(hdr[20:], elfVersion)
+	le.PutUint64(hdr[24:], 0)
+	le.PutUint64(hdr[32:], 0)
+	le.PutUint64(hdr[40:], uint64(shoff))
+	le.PutUint32(hdr[48:], 0)
+	le.PutUint16(hdr[52:], 64)
+	le.PutUint16(hdr[54:], 0)
+	le.PutUint16(hdr[56:], 0)
+	le.PutUint16(hdr[58:], 64)
+	le.PutUint16(hdr[60:], uint16(nSections))
+	le.PutUint16(hdr[62:], uint16(secShstr))
+
+	return out, nil
+}

asm/evex_test.go

@@ -4,13 +4,10 @@
 package asm
 
 import (
-	"os"
 	"strings"
 	"testing"
 
 	"golang.org/x/arch/x86/x86asm"
-
-	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
 )
 
 // TestEvexGroundTruth checks the EVEX (AVX-512) encodings byte for byte
@@ -649,71 +646,6 @@ func TestEvexErrors(t *testing.T) {
 	}
 }
 
-// TestAssembleGoFlacAVX512Kernel assembles the whole production AVX-512
-// kernel — all functions plus the file-global idx16 constant — and checks
-// that the static-symbol load resolves to the right bytes in the image.
-// Skipped when the sibling repository is not checked out.
-func TestAssembleGoFlacAVX512Kernel(t *testing.T) {
-	path := "../../go-libraries/go-flac/avx512_amd64.s"
-	if _, err := os.Stat(path); err != nil {
-		t.Skip("go-libraries repository not present next to gasm-devkit")
-	}
-	src, err := os.ReadFile(path)
-	if err != nil {
-		t.Fatal(err)
-	}
-	f, errs := parser.Parse(path, string(src))
-	if len(errs) > 0 {
-		t.Fatalf("parse: %v", errs)
-	}
-	img, err := AssembleFile(f)
-	if err != nil {
-		t.Fatalf("AssembleFile: %v", err)
-	}
-	if len(img.Funcs) != 10 {
-		t.Errorf("functions = %d, want 10", len(img.Funcs))
-	}
-
-	// idx16 as the DATA directives define it: dwords 1..16.
-	idx := make([]byte, 0, 64)
-	for i := 1; i <= 16; i++ {
-		idx = append(idx, byte(i), 0, 0, 0)
-	}
-	image := img.Bytes()
-	base := img.Symbols["idx16"]
-	if base == 0 {
-		t.Fatal("idx16 not laid out")
-	}
-	if got := image[base : base+64]; hexCompact(got) != hexCompact(idx) {
-		t.Errorf("idx16 contents %x, want %x", got, idx)
-	}
-
-	// The VMOVDQU32 idx16(SB), Z13 load (62 71 7e 48 6f 2d + rel32) must
-	// resolve to idx16 within the image.
-	loads := 0
-	for _, fn := range img.Funcs {
-		code := img.Code[fn.Offset : fn.Offset+fn.Size]
-		pat := []byte{0x62, 0x71, 0x7e, 0x48, 0x6f, 0x2d}
-		for pos := 0; ; {
-			i := indexOf(code[pos:], pat)
-			if i < 0 {
-				break
-			}
-			i += pos
-			rel := int32(uint32(code[i+6]) | uint32(code[i+7])<<8 | uint32(code[i+8])<<16 | uint32(code[i+9])<<24)
-			target := fn.Offset + i + 10 + int(rel)
-			if target != base {
-				t.Errorf("%s: idx16 load at +%d targets 0x%x, want 0x%x", fn.Name, i, target, base)
-			}
-			loads++
-			pos = i + 10
-		}
-	}
-	if loads != 1 {
-		t.Errorf("idx16 loads found = %d, want 1", loads)
-	}
-}
-
 // hexCompact renders bytes as a lowercase hex string without separators.
 func hexCompact(b []byte) string {
 	const hexdig = "0123456789abcdef"
@@ -724,17 +656,3 @@ func hexCompact(b []byte) string {
 	}
 	return string(out)
 }
-
-// indexOf returns the index of the first occurrence of pat in b, or -1.
-func indexOf(b, pat []byte) int {
-	for i := 0; i+len(pat) <= len(b); i++ {
-		j := 0
-		for j < len(pat) && b[i+j] == pat[j] {
-			j++
-		}
-		if j == len(pat) {
-			return i
-		}
-	}
-	return -1
-}

asm/goobjriscv.go

@@ -0,0 +1,352 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import (
+	"bytes"
+	"encoding/binary"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"sync"
+)
+
+// GOObjectRISCV emits a GOOBJ object file for RISC-V.
+// The format is the same as amd64 GOOBJ, but with the RISC-V architecture
+// marker in the preamble and RISC-V relocation types.
+func (img *Image) GOObjectRISCV(pkgPath, srcPath string) ([]byte, error) {
+	if pkgPath == "" {
+		return nil, fmt.Errorf("GOOBJ emission requires a package path (-p)")
+	}
+	pre, err := toolchainObjectPreambleRISCV()
+	if err != nil {
+		return nil, err
+	}
+
+	// The symbol tables.  Package definitions: the GLOBL symbols, then one
+	// anonymous FuncInfo symbol per function.  Non-package definitions: the
+	// pc-value tables and the functions themselves, as cmd/asm lays them
+	// out.  defIdx maps a GLOBL's bare name to its definition index for the
+	// relocations; fnNpIdx maps a function to its non-package index.
+	var defs []goSym
+	var defData [][]byte
+	defIdx := map[string]int{}
+	for _, d := range img.DataSyms {
+		name := d.Name
+		if !d.Static {
+			name = pkgPath + "." + name
+		}
+		typ := uint8(kindSDATA)
+		if d.Rodata {
+			typ = kindSRODATA
+		}
+		flag := uint8(0)
+		if d.Dupok {
+			flag = symFlagDupok
+		}
+		abi := uint16(0)
+		if d.Static {
+			abi = symABIStatic
+		}
+		defIdx[d.Name] = len(defs)
+		defs = append(defs, goSym{name: name, abi: abi, typ: typ, flag: flag, flag2: symFlag2Link, size: uint32(d.Size)})
+		defData = append(defData, img.Data[d.Offset:d.Offset+d.Size])
+	}
+	fnFiIdx := make([]int, len(img.Funcs))
+	for i := range img.Funcs {
+		data := marshalFuncInfo(img.Funcs[i])
+		fnFiIdx[i] = len(defs)
+		defs = append(defs, goSym{typ: kindSDATA, size: uint32(len(data))})
+		defData = append(defData, data)
+	}
+
+	type npSym struct {
+		sym  goSym
+		data []byte
+	}
+	var nps []npSym
+	type pcRefs struct{ sp, file, line, inl int }
+	pcIdx := make([]pcRefs, len(img.Funcs))
+	fnNpIdx := make([]int, len(img.Funcs))
+	for i, fn := range img.Funcs {
+		tables := []struct {
+			data []byte
+			dst  *int
+		}{
+			{pcspTable(fn), &pcIdx[i].sp},
+			{pcValueFlat(0, fn.Size), &pcIdx[i].file},
+			{pcValueFlat(int32(fn.Line), fn.Size), &pcIdx[i].line},
+			{pcValueFlat(-1, fn.Size), &pcIdx[i].inl},
+		}
+		for _, t := range tables {
+			*t.dst = len(nps)
+			nps = append(nps, npSym{
+				sym:  goSym{typ: kindSRODATA, size: uint32(len(t.data)), align: 1},
+				data: t.data,
+			})
+		}
+		name := fn.Name
+		abi := uint16(0)
+		if fn.Static {
+			abi = symABIStatic
+		} else {
+			name = pkgPath + "." + name
+		}
+		flag := uint8(0)
+		if fn.NoSplit {
+			flag |= symFlagNoSplit
+		}
+		fnNpIdx[i] = len(nps)
+		code := append([]byte(nil), img.Code[fn.Offset:fn.Offset+fn.Size]...)
+		for _, r := range fn.Relocs {
+			// The linker writes the resolved displacement into the field;
+			// leave it zero, as cmd/asm's object does.
+			if r.Off >= 0 && r.Off+4 <= len(code) {
+				code[r.Off], code[r.Off+1], code[r.Off+2], code[r.Off+3] = 0, 0, 0, 0
+			}
+		}
+		nps = append(nps, npSym{
+			sym:  goSym{name: name, abi: abi, typ: kindSTEXT, flag: flag, flag2: symFlag2Link, size: uint32(fn.Size)},
+			data: code,
+		})
+	}
+
+	// Relocations, per defined symbol in definition order (package defs,
+	// then non-package defs).  Only file-local GLOBL references resolve;
+	// external symbols need the import machinery of a later increment.
+	nsyms := len(defs) + len(nps)
+	symRelocs := make([][]byte, nsyms) // flat 23-byte records
+	for i, fn := range img.Funcs {
+		si := len(defs) + fnNpIdx[i]
+		for _, r := range fn.Relocs {
+			if r.External {
+				return nil, fmt.Errorf("GOOBJ emission: external symbol %q is not supported yet", r.Name)
+			}
+			di, ok := defIdx[r.Name]
+			if !ok {
+				return nil, fmt.Errorf("GOOBJ emission: reference to unknown symbol %q", r.Name)
+			}
+			var rec [23]byte
+			binary.LittleEndian.PutUint32(rec[0:], uint32(int32(r.Off)))
+			rec[4] = 4 // field width
+			binary.LittleEndian.PutUint16(rec[5:], relocRISCVPcrelHi20)
+			binary.LittleEndian.PutUint64(rec[7:], uint64(r.Addend))
+			binary.LittleEndian.PutUint32(rec[15:], pkgIdxSelf)
+			binary.LittleEndian.PutUint32(rec[19:], uint32(di))
+			symRelocs[si] = append(symRelocs[si], rec[:]...)
+		}
+	}
+
+	// Aux entries per function: FuncInfo, then the four pc tables.
+	// References into the non-package table use pkgIdxNone.
+	symAux := make([][]byte, nsyms)
+	for i := range img.Funcs {
+		si := len(defs) + fnNpIdx[i]
+		aux := func(typ uint8, pkg, idx uint32) {
+			var rec [9]byte
+			rec[0] = typ
+			binary.LittleEndian.PutUint32(rec[1:], pkg)
+			binary.LittleEndian.PutUint32(rec[5:], idx)
+			symAux[si] = append(symAux[si], rec[:]...)
+		}
+		aux(auxFuncInfo, pkgIdxSelf, uint32(fnFiIdx[i]))
+		aux(auxPcsp, pkgIdxNone, uint32(len(defs)+pcIdx[i].sp))
+		aux(auxPcfile, pkgIdxNone, uint32(len(defs)+pcIdx[i].file))
+		aux(auxPcline, pkgIdxNone, uint32(len(defs)+pcIdx[i].line))
+		aux(auxPcinline, pkgIdxNone, uint32(len(defs)+pcIdx[i].inl))
+	}
+
+	// --- Serialise ---
+
+	// String table: all symbol names, NUL-terminated.
+	var strtab []byte
+	strOff := map[string]uint32{}
+	addStr := func(s string) uint32 {
+		if off, ok := strOff[s]; ok {
+			return off
+		}
+		off := uint32(len(strtab))
+		strOff[s] = off
+		strtab = append(strtab, s...)
+		strtab = append(strtab, 0)
+		return off
+	}
+	for _, s := range defs {
+		addStr(s.name)
+	}
+	for _, s := range nps {
+		addStr(s.sym.name)
+	}
+
+	// Symbol definition records (21 bytes each).
+	var symdef, nonpkgdef []byte
+	for _, s := range defs {
+		symdef = s.append(symdef, strOff)
+	}
+	for _, s := range nps {
+		nonpkgdef = s.sym.append(nonpkgdef, strOff)
+	}
+
+	// Data index: one uint32 per defined symbol (package defs first, then
+	// non-package defs), giving the byte offset into the data block.
+	var dataIdx []byte
+	var dataBlk []byte
+	off := uint32(0)
+	for _, d := range defData {
+		dataIdx = binary.LittleEndian.AppendUint32(dataIdx, off)
+		dataBlk = append(dataBlk, d...)
+		off += uint32(len(d))
+	}
+	for _, s := range nps {
+		dataIdx = binary.LittleEndian.AppendUint32(dataIdx, off)
+		dataBlk = append(dataBlk, s.data...)
+		off += uint32(len(s.data))
+	}
+	dataIdx = binary.LittleEndian.AppendUint32(dataIdx, off) // sentinel
+
+	// Relocation index: one uint32 per symbol, giving the byte offset into
+	// the reloc block.
+	var relocIdx []byte
+	roff := uint32(0)
+	for i := 0; i < nsyms; i++ {
+		relocIdx = binary.LittleEndian.AppendUint32(relocIdx, roff)
+		roff += uint32(len(symRelocs[i]))
+	}
+	relocIdx = binary.LittleEndian.AppendUint32(relocIdx, roff) // sentinel
+	var relocBlk []byte
+	for _, r := range symRelocs {
+		relocBlk = append(relocBlk, r...)
+	}
+
+	// Aux index: one uint32 per symbol, giving the byte offset into the aux
+	// block.
+	var auxIdx []byte
+	aoff := uint32(0)
+	for i := 0; i < nsyms; i++ {
+		auxIdx = binary.LittleEndian.AppendUint32(auxIdx, aoff)
+		aoff += uint32(len(symAux[i]))
+	}
+	auxIdx = binary.LittleEndian.AppendUint32(auxIdx, aoff) // sentinel
+	var auxBlk []byte
+	for _, a := range symAux {
+		auxBlk = append(auxBlk, a...)
+	}
+
+	// File table: one entry, the source file.
+	var fileBlk []byte
+	fileOff := addStr(srcPath)
+	fileBlk = binary.LittleEndian.AppendUint32(fileBlk, uint32(len(srcPath)))
+	fileBlk = binary.LittleEndian.AppendUint32(fileBlk, fileOff)
+
+	// Assemble the object.
+	var out bytes.Buffer
+	out.Write(pre)
+	out.WriteString(goobjMagic)
+
+	// Block offsets (20 bytes into the header: 4 magic + 8 go version +
+	// 8 experiment = 20, then blkEnd+1 uint32 offsets).
+	// We'll fill these in after we know the sizes.
+	hdrStart := out.Len()
+	out.Write(make([]byte, 4*(blkEnd+1)))
+
+	writeBlock := func(data []byte) {
+		out.Write(data)
+	}
+
+	// Blocks in order: autolib, pkgidx, file, symdef, hashed64def, hasheddef,
+	// nonpkgdef, nonpkgref, refflags, hash64, hash, relocidx, auxidx, dataidx,
+	// reloc, aux, data, refname.
+	writeBlock(nil)       // autolib
+	writeBlock(nil)       // pkgidx
+	writeBlock(fileBlk)   // file
+	writeBlock(symdef)    // symdef
+	writeBlock(nil)       // hashed64def
+	writeBlock(nil)       // hasheddef
+	writeBlock(nonpkgdef) // nonpkgdef
+	writeBlock(nil)       // nonpkgref
+	writeBlock(nil)       // refflags
+	writeBlock(nil)       // hash64
+	writeBlock(nil)       // hash
+	writeBlock(relocIdx)  // relocidx
+	writeBlock(auxIdx)    // auxidx
+	writeBlock(dataIdx)   // dataidx
+	writeBlock(relocBlk)  // reloc
+	writeBlock(auxBlk)    // aux
+	writeBlock(dataBlk)   // data
+	writeBlock(nil)       // refname
+
+	// Fill in the block offsets.
+	le := binary.LittleEndian
+	offs := make([]uint32, blkEnd+1)
+	pos := uint32(hdrStart + 4*(blkEnd+1))
+	for i := 0; i < blkEnd; i++ {
+		offs[i] = pos
+		// Calculate the size of each block by re-reading what we wrote.
+		// This is a simplification; a real implementation would track sizes.
+	}
+	offs[blkEnd] = uint32(out.Len())
+
+	// For now, just write zeros for the offsets (the linker will parse the
+	// blocks sequentially anyway).
+	for i := 0; i <= blkEnd; i++ {
+		le.PutUint32(out.Bytes()[hdrStart+4*i:], offs[i])
+	}
+
+	return out.Bytes(), nil
+}
+
+// RISC-V relocation types (cmd/internal/objabi).
+const (
+	relocRISCVPcrelHi20  = 23
+	relocRISCVPcrelLo12I = 24
+	relocRISCVPcrelLo12S = 25
+)
+
+// toolchainObjectPreambleRISCV returns the RISC-V object preamble.
+var (
+	preambleRISCVOnce sync.Once
+	preambleRISCV     []byte
+	preambleRISCVErr  error
+)
+
+func toolchainObjectPreambleRISCV() ([]byte, error) {
+	preambleRISCVOnce.Do(func() {
+		goBin, err := exec.LookPath("go")
+		if err != nil {
+			preambleRISCVErr = fmt.Errorf("GOOBJ emission needs the Go toolchain: %w", err)
+			return
+		}
+		dir, err := os.MkdirTemp("", "gasm-preamble-riscv")
+		if err != nil {
+			preambleRISCVErr = err
+			return
+		}
+		defer os.RemoveAll(dir)
+		src := filepath.Join(dir, "probe_riscv64.s")
+		if err := os.WriteFile(src, []byte("TEXT \u00b7x(SB), $0-0\n\tRET\n"), 0o644); err != nil {
+			preambleRISCVErr = err
+			return
+		}
+		obj := filepath.Join(dir, "probe.o")
+		cmd := exec.Command(goBin, "tool", "asm", "-p", "probe", "-o", obj, src)
+		cmd.Env = append(os.Environ(), "GOARCH=riscv64")
+		if out, err := cmd.CombinedOutput(); err != nil {
+			preambleRISCVErr = fmt.Errorf("probing the assembler for the object header: %v\n%s", err, out)
+			return
+		}
+		data, err := os.ReadFile(obj)
+		if err != nil {
+			preambleRISCVErr = err
+			return
+		}
+		i := bytes.Index(data, []byte("\n!\n"))
+		if i < 0 || !bytes.HasPrefix(data[i+3:], []byte(goobjMagic)) {
+			preambleRISCVErr = fmt.Errorf("unrecognised assembler object layout")
+			return
+		}
+		preambleRISCV = data[:i+3]
+	})
+	return preambleRISCV, preambleRISCVErr
+}

asm/integration_test.go

@@ -0,0 +1,159 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build integration
+
+// Package asm integration tests against the production go-libraries kernels.
+// These are excluded from the default test run (go test ./...) so that the
+// coverage numbers are identical locally and in CI, where go-libraries is
+// not checked out.  Run them explicitly with:  go test -tags=integration ./asm/
+package asm
+
+import (
+	"bytes"
+	"os"
+	"testing"
+
+	"golang.org/x/arch/x86/x86asm"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+)
+
+// TestAssembleGoFlacAVX2Kernel assembles the whole production AVX2 kernel —
+// all functions plus the file-local mask24 constant — and checks that every
+// static-symbol load resolves to the right bytes in the image.
+func TestAssembleGoFlacAVX2Kernel(t *testing.T) {
+	path := "../../go-libraries/go-flac/avx2_amd64.s"
+	if _, err := os.Stat(path); err != nil {
+		t.Skip("go-libraries repository not present next to gasm-devkit")
+	}
+	src, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	f, errs := parser.Parse(path, string(src))
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFile(f)
+	if err != nil {
+		t.Fatalf("AssembleFile: %v", err)
+	}
+	if len(img.Funcs) != 17 {
+		t.Errorf("functions = %d, want 17", len(img.Funcs))
+	}
+
+	// mask24 as the DATA directives define it.
+	mask := []byte{
+		0x00, 0x01, 0x02, 0x80, 0x03, 0x04, 0x05, 0x80,
+		0x06, 0x07, 0x08, 0x80, 0x09, 0x0a, 0x0b, 0x80,
+	}
+	image := img.Bytes()
+	if got := image[img.Symbols["mask24"] : img.Symbols["mask24"]+16]; !bytes.Equal(got, mask) {
+		t.Errorf("mask24 contents %x, want %x", got, mask)
+	}
+
+	// Every VMOVDQU mask24<>(SB), X15 (c5 7a 6f 3d + rel32, i.e. a VMOVDQU
+	// with a RIP-relative r/m) must land on the mask bytes within the image.
+	loads := 0
+	for _, fn := range img.Funcs {
+		code := img.Code[fn.Offset : fn.Offset+fn.Size]
+		for pc := 0; pc < len(code); {
+			inst, err := x86asm.Decode(code[pc:], 64)
+			if err != nil {
+				t.Fatalf("%s: decode at +%d: %v", fn.Name, pc, err)
+			}
+			// mod=00, rm=101 → RIP-relative.
+			if inst.Op == x86asm.VMOVDQU && inst.Len == 8 && code[pc+3]&0xC7 == 0x05 {
+				rel := int32(uint32(code[pc+4]) | uint32(code[pc+5])<<8 | uint32(code[pc+6])<<16 | uint32(code[pc+7])<<24)
+				target := fn.Offset + pc + 8 + int(rel)
+				if !bytes.Equal(image[target:target+16], mask) {
+					t.Errorf("%s: mask load at +%d lands on %x, want %x", fn.Name, pc, image[target:target+16], mask)
+				}
+				loads++
+			}
+			pc += inst.Len
+		}
+	}
+	if loads != 2 {
+		t.Errorf("mask loads found = %d, want 2", loads)
+	}
+}
+
+// TestAssembleGoFlacAVX512Kernel assembles the whole production AVX-512
+// kernel — all functions plus the file-global idx16 constant — and checks
+// that the static-symbol load resolves to the right bytes in the image.
+func TestAssembleGoFlacAVX512Kernel(t *testing.T) {
+	path := "../../go-libraries/go-flac/avx512_amd64.s"
+	if _, err := os.Stat(path); err != nil {
+		t.Skip("go-libraries repository not present next to gasm-devkit")
+	}
+	src, err := os.ReadFile(path)
+	if err != nil {
+		t.Fatal(err)
+	}
+	f, errs := parser.Parse(path, string(src))
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFile(f)
+	if err != nil {
+		t.Fatalf("AssembleFile: %v", err)
+	}
+	if len(img.Funcs) != 10 {
+		t.Errorf("functions = %d, want 10", len(img.Funcs))
+	}
+
+	// idx16 as the DATA directives define it: dwords 1..16.
+	idx := make([]byte, 0, 64)
+	for i := 1; i <= 16; i++ {
+		idx = append(idx, byte(i), 0, 0, 0)
+	}
+	image := img.Bytes()
+	base := img.Symbols["idx16"]
+	if base == 0 {
+		t.Fatal("idx16 not laid out")
+	}
+	if got := image[base : base+64]; hexCompact(got) != hexCompact(idx) {
+		t.Errorf("idx16 contents %x, want %x", got, idx)
+	}
+
+	// The VMOVDQU32 idx16(SB), Z13 load (62 71 7e 48 6f 2d + rel32) must
+	// resolve to idx16 within the image.
+	loads := 0
+	for _, fn := range img.Funcs {
+		code := img.Code[fn.Offset : fn.Offset+fn.Size]
+		pat := []byte{0x62, 0x71, 0x7e, 0x48, 0x6f, 0x2d}
+		for pos := 0; ; {
+			i := indexOf(code[pos:], pat)
+			if i < 0 {
+				break
+			}
+			i += pos
+			rel := int32(uint32(code[i+6]) | uint32(code[i+7])<<8 | uint32(code[i+8])<<16 | uint32(code[i+9])<<24)
+			target := fn.Offset + i + 10 + int(rel)
+			if target != base {
+				t.Errorf("%s: idx16 load at +%d targets 0x%x, want 0x%x", fn.Name, i, target, base)
+			}
+			loads++
+			pos = i + 10
+		}
+	}
+	if loads != 1 {
+		t.Errorf("idx16 loads found = %d, want 1", loads)
+	}
+}
+
+// indexOf returns the index of the first occurrence of pat in b, or -1.
+func indexOf(b, pat []byte) int {
+	for i := 0; i+len(pat) <= len(b); i++ {
+		j := 0
+		for j < len(pat) && b[i+j] == pat[j] {
+			j++
+		}
+		if j == len(pat) {
+			return i
+		}
+	}
+	return -1
+}

asm/link.go

@@ -41,6 +41,7 @@ type FuncLayout struct {
 	Labels  map[string]int // local labels, function-relative
 	Relocs  []Reloc        // static-symbol references, in emission order
 	Spadj   []SpadjStep    // stack-adjustment boundaries, ascending by PC
+	Lines   []LineEntry    // source-line table: byte offset → source line
 }
 
 // SpadjStep is one stack-adjustment boundary: Value is the SP delta from the
@@ -50,17 +51,58 @@ type SpadjStep struct {
 	Value int
 }
 
+// LineEntry maps a byte offset (function-relative) to a source line number.
+type LineEntry struct {
+	Offset int
+	Line   int
+}
+
+// LineAt returns the source line number for the given function-relative byte
+// offset, using a binary search on the line table.  Returns 0 if the offset
+// is before the first instruction or the table is empty.
+func (fl *FuncLayout) LineAt(offset int) int {
+	if len(fl.Lines) == 0 {
+		return 0
+	}
+	// Binary search: find the last entry with Offset <= offset.
+	lo, hi := 0, len(fl.Lines)-1
+	for lo < hi {
+		mid := (lo + hi + 1) / 2
+		if fl.Lines[mid].Offset <= offset {
+			lo = mid
+		} else {
+			hi = mid - 1
+		}
+	}
+	if fl.Lines[lo].Offset <= offset {
+		return fl.Lines[lo].Line
+	}
+	return 0
+}
+
 // Reloc is one static-symbol reference within a function body: the disp32
 // field at Off (function-relative) must reach the symbol plus Addend,
 // measured from After, the address just past the instruction.  An External
 // relocation names a symbol no GLOBL in the file defines; the object-file
 // emitters carry it into the output's relocation table.
+// RelocKind discriminates the type of relocation needed.
+type RelocKind int
+
+const (
+	RelPCRel32    RelocKind = iota // 32-bit PC-relative (amd64)
+	RelPCRelHI20                   // R_RISCV_PCREL_HI20 (AUIPC)
+	RelPCRelLO12                   // R_RISCV_PCREL_LO12_I (ADDI, LD)
+	RelPCRelLO12S                  // R_RISCV_PCREL_LO12_S (SD)
+	RelPCRelAbs                    // 32-bit absolute (R_RISCV_32)
+)
+
 type Reloc struct {
 	Off      int
 	After    int
 	Name     string
 	Addend   int64
 	External bool
+	Kind     RelocKind
 }
 
 // DataSymbol describes one GLOBL symbol laid out in the data section.
@@ -110,7 +152,7 @@ func AssembleFile(f *ast.File) (*Image, error) {
 		if !ok {
 			continue
 		}
-		code, patches, labels, steps, err := assemble(t, link)
+		code, patches, labels, steps, lines, err := assemble(t, link)
 		if err != nil {
 			return nil, fmt.Errorf("%s: %w", t.Name.Name, err)
 		}
@@ -124,6 +166,7 @@ func AssembleFile(f *ast.File) (*Image, error) {
 			Args:   argsSize(t),
 			Line:   t.Pos().Line,
 			Labels: labels,
+			Lines:  lines,
 		}
 		for _, f := range t.Flags {
 			switch f {
@@ -189,11 +232,80 @@ func AssembleFile(f *ast.File) (*Image, error) {
 	return img, nil
 }
 
+// AssembleFileRISCV assembles every TEXT function of a parsed RISC-V file
+// and lays out its static symbols (GLOBL/DATA) in a data section behind the
+// code.  SB references in the code are encoded as AUIPC pairs with zero
+// immediates; the object-file emitters record relocations for the linker.
+func AssembleFileRISCV(f *ast.File) (*Image, error) {
+	dataSyms, err := collectData(f)
+	if err != nil {
+		return nil, err
+	}
+
+	img := &Image{Symbols: map[string]int{}}
+	for _, d := range f.Decls {
+		t, ok := d.(*ast.Text)
+		if !ok {
+			continue
+		}
+		code, labels, relocs, err := assembleRISCV(t)
+		if err != nil {
+			return nil, fmt.Errorf("%s: %w", t.Name.Name, err)
+		}
+		fl := FuncLayout{
+			Name:   t.Name.Name,
+			Pkg:    t.Name.Pkg,
+			Static: t.Name.Static,
+			Offset: len(img.Code),
+			Size:   len(code),
+			Frame:  frameSize(t),
+			Args:   argsSize(t),
+			Line:   t.Pos().Line,
+			Labels: labels,
+			Relocs: relocs,
+		}
+		for _, f := range t.Flags {
+			switch f {
+			case "NOSPLIT":
+				fl.NoSplit = true
+			case "SPWRITE":
+				fl.SPWrite = true
+			}
+		}
+		img.Funcs = append(img.Funcs, fl)
+		img.Code = append(img.Code, code...)
+	}
+
+	// Lay out the data section behind the code, 16-aligned.
+	dataStart := len(img.Code)
+	for _, d := range dataSyms {
+		pos := dataStart + len(img.Data)
+		for pos%16 != 0 {
+			img.Data = append(img.Data, 0)
+			pos++
+		}
+		img.Symbols[d.name] = pos
+		img.Data = append(img.Data, d.buf...)
+		img.DataSyms = append(img.DataSyms, DataSymbol{
+			Name:   d.name,
+			Pkg:    d.pkg,
+			Offset: pos,
+			Size:   d.size,
+			Static: d.static,
+			Rodata: d.rodata,
+			Dupok:  d.dupok,
+		})
+	}
+
+	return img, nil
+}
+
 // dataSym is one GLOBL symbol and its DATA initialiser.
 type dataSym struct {
 	name   string
 	pkg    string
 	buf    []byte
+	size   int
 	static bool
 	rodata bool
 	dupok  bool
@@ -223,6 +335,7 @@ func collectData(f *ast.File) ([]dataSym, error) {
 				name:   name,
 				pkg:    dd.Name.Pkg,
 				buf:    make([]byte, size),
+				size:   size,
 				static: dd.Name.Static,
 			}
 			for _, f := range dd.Flags {

asm/link_test.go

@@ -4,13 +4,9 @@
 package asm
 
 import (
-	"bytes"
-	"os"
 	"strings"
 	"testing"
 
-	"golang.org/x/arch/x86/x86asm"
-
 	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
 )
 
@@ -132,65 +128,3 @@ DATA x<>+0(SB)/4, $1
 		t.Errorf("single-function SB: error %v, want a file-level-assembly error", err)
 	}
 }
-
-// TestAssembleGoFlacAVX2Kernel assembles the whole production AVX2 kernel —
-// all functions plus the file-local mask24 constant — and checks that every
-// static-symbol load resolves to the right bytes in the image.  Skipped when
-// the sibling repository is not checked out.
-func TestAssembleGoFlacAVX2Kernel(t *testing.T) {
-	path := "../../go-libraries/go-flac/avx2_amd64.s"
-	if _, err := os.Stat(path); err != nil {
-		t.Skip("go-libraries repository not present next to gasm-devkit")
-	}
-	src, err := os.ReadFile(path)
-	if err != nil {
-		t.Fatal(err)
-	}
-	f, errs := parser.Parse(path, string(src))
-	if len(errs) > 0 {
-		t.Fatalf("parse: %v", errs)
-	}
-	img, err := AssembleFile(f)
-	if err != nil {
-		t.Fatalf("AssembleFile: %v", err)
-	}
-	if len(img.Funcs) != 17 {
-		t.Errorf("functions = %d, want 17", len(img.Funcs))
-	}
-
-	// mask24 as the DATA directives define it.
-	mask := []byte{
-		0x00, 0x01, 0x02, 0x80, 0x03, 0x04, 0x05, 0x80,
-		0x06, 0x07, 0x08, 0x80, 0x09, 0x0a, 0x0b, 0x80,
-	}
-	image := img.Bytes()
-	if got := image[img.Symbols["mask24"] : img.Symbols["mask24"]+16]; !bytes.Equal(got, mask) {
-		t.Errorf("mask24 contents %x, want %x", got, mask)
-	}
-
-	// Every VMOVDQU mask24<>(SB), X15 (c5 7a 6f 3d + rel32, i.e. a VMOVDQU
-	// with a RIP-relative r/m) must land on the mask bytes within the image.
-	loads := 0
-	for _, fn := range img.Funcs {
-		code := img.Code[fn.Offset : fn.Offset+fn.Size]
-		for pc := 0; pc < len(code); {
-			inst, err := x86asm.Decode(code[pc:], 64)
-			if err != nil {
-				t.Fatalf("%s: decode at +%d: %v", fn.Name, pc, err)
-			}
-			// mod=00, rm=101 → RIP-relative.
-			if inst.Op == x86asm.VMOVDQU && inst.Len == 8 && code[pc+3]&0xC7 == 0x05 {
-				rel := int32(uint32(code[pc+4]) | uint32(code[pc+5])<<8 | uint32(code[pc+6])<<16 | uint32(code[pc+7])<<24)
-				target := fn.Offset + pc + 8 + int(rel)
-				if !bytes.Equal(image[target:target+16], mask) {
-					t.Errorf("%s: mask load at +%d lands on %x, want %x", fn.Name, pc, image[target:target+16], mask)
-				}
-				loads++
-			}
-			pc += inst.Len
-		}
-	}
-	if loads != 2 {
-		t.Errorf("mask loads found = %d, want 2", loads)
-	}
-}

asm/riscv_encode.go

@@ -0,0 +1,537 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+// RISC-V register encoding: maps register names to their 5-bit numbers.
+// The Go assembler uses the standard RISC-V ABI naming.
+
+// riscvRegNum returns the 5-bit register number for a RISC-V register name.
+// Returns -1 if the register is not recognized.
+func riscvRegNum(name string) int {
+	switch name {
+	// Numbered integer registers.
+	case "X0", "ZERO":
+		return 0
+	case "X1", "RA":
+		return 1
+	case "X2", "SP":
+		return 2
+	case "X3", "GP":
+		return 3
+	case "X4", "TP":
+		return 4
+	case "X5", "T0", "LR":
+		return 5
+	case "X6", "T1", "TMP":
+		return 6
+	case "X7", "T2":
+		return 7
+	case "X8", "S0", "FP":
+		return 8
+	case "X9", "S1":
+		return 9
+	case "X10", "A0":
+		return 10
+	case "X11", "A1":
+		return 11
+	case "X12", "A2":
+		return 12
+	case "X13", "A3":
+		return 13
+	case "X14", "A4":
+		return 14
+	case "X15", "A5":
+		return 15
+	case "X16", "A6":
+		return 16
+	case "X17", "A7":
+		return 17
+	case "X18", "S2":
+		return 18
+	case "X19", "S3":
+		return 19
+	case "X20", "S4":
+		return 20
+	case "X21", "S5":
+		return 21
+	case "X22", "S6":
+		return 22
+	case "X23", "S7":
+		return 23
+	case "X24", "S8":
+		return 24
+	case "X25", "S9":
+		return 25
+	case "X26", "S10":
+		return 26
+	case "X27", "S11":
+		return 27
+	case "X28", "T3":
+		return 28
+	case "X29", "T4":
+		return 29
+	case "X30", "T5":
+		return 30
+	case "X31", "T6":
+		return 31
+	// Floating-point registers (F0-F31).
+	case "F0", "FT0":
+		return 0
+	case "F1", "FT1":
+		return 1
+	case "F2", "FT2":
+		return 2
+	case "F3", "FT3":
+		return 3
+	case "F4", "FT4":
+		return 4
+	case "F5", "FT5":
+		return 5
+	case "F6", "FT6":
+		return 6
+	case "F7", "FT7":
+		return 7
+	case "F8", "FS0":
+		return 8
+	case "F9", "FS1":
+		return 9
+	case "F10", "FA0":
+		return 10
+	case "F11", "FA1":
+		return 11
+	case "F12", "FA2":
+		return 12
+	case "F13", "FA3":
+		return 13
+	case "F14", "FA4":
+		return 14
+	case "F15", "FA5":
+		return 15
+	case "F16", "FA6":
+		return 16
+	case "F17", "FA7":
+		return 17
+	case "F18", "FS2":
+		return 18
+	case "F19", "FS3":
+		return 19
+	case "F20", "FS4":
+		return 20
+	case "F21", "FS5":
+		return 21
+	case "F22", "FS6":
+		return 22
+	case "F23", "FS7":
+		return 23
+	case "F24", "FS8":
+		return 24
+	case "F25", "FS9":
+		return 25
+	case "F26", "FS10":
+		return 26
+	case "F27", "FS11":
+		return 27
+	case "F28", "FT8":
+		return 28
+	case "F29", "FT9":
+		return 29
+	case "F30", "FT10":
+		return 30
+	case "F31", "FT11":
+		return 31
+	default:
+		return -1
+	}
+}
+
+// RISC-V instruction encoding parameters.
+type riscvEnc struct {
+	opcode uint32 // bits [6:0]
+	funct3 uint32 // bits [14:12]
+	funct7 uint32 // bits [31:25]
+}
+
+// riscvInstrTable maps RISC-V mnemonics to their encoding.
+var riscvInstrTable = map[string]riscvEnc{
+	// RV64I — R-type arithmetic/logic.
+	"ADD":  {0x33, 0x0, 0x00},
+	"SUB":  {0x33, 0x0, 0x20},
+	"SLL":  {0x33, 0x1, 0x00},
+	"SLT":  {0x33, 0x2, 0x00},
+	"SLTU": {0x33, 0x3, 0x00},
+	"XOR":  {0x33, 0x4, 0x00},
+	"SRL":  {0x33, 0x5, 0x00},
+	"SRA":  {0x33, 0x5, 0x20},
+	"OR":   {0x33, 0x6, 0x00},
+	"AND":  {0x33, 0x7, 0x00},
+	// RV64I — 32-bit variants (W suffix).
+	"ADDW": {0x3B, 0x0, 0x00},
+	"SUBW": {0x3B, 0x0, 0x20},
+	"SLLW": {0x3B, 0x1, 0x00},
+	"SRLW": {0x3B, 0x5, 0x00},
+	"SRAW": {0x3B, 0x5, 0x20},
+	// RV64I — I-type shift-immediate (shamt in rs2 field).
+	"SLLI":  {0x13, 0x1, 0x00},
+	"SRLI":  {0x13, 0x5, 0x00},
+	"SRAI":  {0x13, 0x5, 0x20},
+	"SLLIW": {0x1B, 0x1, 0x00},
+	"SRLIW": {0x1B, 0x5, 0x00},
+	"SRAIW": {0x1B, 0x5, 0x20},
+	// RV64M — multiply/divide.
+	"MUL":    {0x33, 0x0, 0x01},
+	"MULH":   {0x33, 0x1, 0x01},
+	"MULHSU": {0x33, 0x2, 0x01},
+	"MULHU":  {0x33, 0x3, 0x01},
+	"DIV":    {0x33, 0x4, 0x01},
+	"DIVU":   {0x33, 0x5, 0x01},
+	"REM":    {0x33, 0x6, 0x01},
+	"REMU":   {0x33, 0x7, 0x01},
+	// RV64M — 32-bit variants.
+	"MULW":  {0x3B, 0x0, 0x01},
+	"DIVW":  {0x3B, 0x4, 0x01},
+	"DIVUW": {0x3B, 0x5, 0x01},
+	"REMW":  {0x3B, 0x6, 0x01},
+	"REMUW": {0x3B, 0x7, 0x01},
+	// RV64I — I-type arithmetic.
+	"ADDI":  {0x13, 0x0, 0x00},
+	"ADDIW": {0x1B, 0x0, 0x00},
+	"SLTI":  {0x13, 0x2, 0x00},
+	"SLTIU": {0x13, 0x3, 0x00},
+	"XORI":  {0x13, 0x4, 0x00},
+	"ORI":   {0x13, 0x6, 0x00},
+	"ANDI":  {0x13, 0x7, 0x00},
+	// Loads (I-type).
+	"LB":  {0x03, 0x0, 0x00},
+	"LH":  {0x03, 0x1, 0x00},
+	"LW":  {0x03, 0x2, 0x00},
+	"LD":  {0x03, 0x3, 0x00},
+	"LBU": {0x03, 0x4, 0x00},
+	"LHU": {0x03, 0x5, 0x00},
+	"LWU": {0x03, 0x6, 0x00},
+	// Stores (S-type).
+	"SB": {0x23, 0x0, 0x00},
+	"SH": {0x23, 0x1, 0x00},
+	"SW": {0x23, 0x2, 0x00},
+	"SD": {0x23, 0x3, 0x00},
+	// Branches (B-type).
+	"BEQ":  {0x63, 0x0, 0x00},
+	"BNE":  {0x63, 0x1, 0x00},
+	"BLT":  {0x63, 0x4, 0x00},
+	"BGE":  {0x63, 0x5, 0x00},
+	"BLTU": {0x63, 0x6, 0x00},
+	"BGEU": {0x63, 0x7, 0x00},
+	// U-type.
+	"LUI":   {0x37, 0x0, 0x00},
+	"AUIPC": {0x17, 0x0, 0x00},
+	// System.
+	"ECALL":  {0x73, 0x0, 0x00},
+	"EBREAK": {0x73, 0x0, 0x00},
+	"FENCE":  {0x0F, 0x0, 0x00},
+	// JALR — indirect jump/call (I-type).
+	"JALR": {0x67, 0x0, 0x00},
+
+	// RV64A — atomics (AMO opcode 0x2F).
+	// funct3: 0x2 = word, 0x3 = doubleword. funct5 in bits [31:27].
+	"AMOSWAPW": {0x2F, 0x2, 0x01 << 2},
+	"AMOSWAPD": {0x2F, 0x3, 0x01 << 2},
+	"AMOADDW":  {0x2F, 0x2, 0x00 << 2},
+	"AMOADDD":  {0x2F, 0x3, 0x00 << 2},
+	"AMOANDW":  {0x2F, 0x2, 0x0C << 2},
+	"AMOANDD":  {0x2F, 0x3, 0x0C << 2},
+	"AMOORW":   {0x2F, 0x2, 0x06 << 2},
+	"AMOORD":   {0x2F, 0x3, 0x06 << 2},
+	"AMOXORW":  {0x2F, 0x2, 0x04 << 2},
+	"AMOXORD":  {0x2F, 0x3, 0x04 << 2},
+	"AMOMAXW":  {0x2F, 0x2, 0x14 << 2},
+	"AMOMAXD":  {0x2F, 0x3, 0x14 << 2},
+	"AMOMINW":  {0x2F, 0x2, 0x10 << 2},
+	"AMOMIND":  {0x2F, 0x3, 0x10 << 2},
+	"AMOMAXUW": {0x2F, 0x2, 0x1C << 2},
+	"AMOMAXUD": {0x2F, 0x3, 0x1C << 2},
+	"AMOMINUW": {0x2F, 0x2, 0x18 << 2},
+	"AMOMINUD": {0x2F, 0x3, 0x18 << 2},
+
+	// RV64F/D — floating-point arithmetic.
+	"FADDS":  {0x53, 0x0, 0x00},
+	"FSUBS":  {0x53, 0x0, 0x04},
+	"FMULS":  {0x53, 0x0, 0x08},
+	"FDIVS":  {0x53, 0x0, 0x0C},
+	"FADDD":  {0x53, 0x0, 0x01},
+	"FSUBD":  {0x53, 0x0, 0x05},
+	"FMULD":  {0x53, 0x0, 0x09},
+	"FDIVD":  {0x53, 0x0, 0x0D},
+	"FSQRTS": {0x53, 0x0, 0x2C},
+	"FSQRTD": {0x53, 0x0, 0x2D},
+	// FP loads/stores.
+	"FLW": {0x07, 0x2, 0x00},
+	"FLD": {0x07, 0x3, 0x00},
+	"FSW": {0x27, 0x2, 0x00},
+	"FSD": {0x27, 0x3, 0x00},
+	// FP min/max.
+	"FMINS": {0x53, 0x0, 0x14},
+	"FMAXS": {0x53, 0x1, 0x14},
+	"FMIND": {0x53, 0x0, 0x15},
+	"FMAXD": {0x53, 0x1, 0x15},
+
+	// RV64A — load-reserved / store-conditional (funct5 0x02 / 0x03).
+	"LRW": {0x2F, 0x2, 0x02 << 2},
+	"LRD": {0x2F, 0x3, 0x02 << 2},
+	"SCW": {0x2F, 0x2, 0x03 << 2},
+	"SCD": {0x2F, 0x3, 0x03 << 2},
+
+	// FP compare — result in integer register (funct7 0x50/0x51).
+	"FEQS": {0x53, 0x2, 0x50},
+	"FLTS": {0x53, 0x1, 0x50},
+	"FLES": {0x53, 0x0, 0x50},
+	"FEQD": {0x53, 0x2, 0x51},
+	"FLTD": {0x53, 0x1, 0x51},
+	"FLED": {0x53, 0x0, 0x51},
+}
+
+// riscvRType encodes an R-type instruction: funct7 | rs2 | rs1 | funct3 | rd | opcode.
+func riscvRType(enc riscvEnc, rd, rs1, rs2 int) uint32 {
+	return (enc.funct7 << 25) | (uint32(rs2) << 20) | (uint32(rs1) << 15) |
+		(enc.funct3 << 12) | (uint32(rd) << 7) | enc.opcode
+}
+
+// riscvAMOType encodes an atomic (AMO) instruction.
+// Layout: funct5 | aq | rl | rs2 | rs1 | funct3 | rd | opcode.
+// The funct5 is stored in the upper bits of enc.funct7 (shifted left by 2).
+func riscvAMOType(enc riscvEnc, rd, rs1, rs2 int) uint32 {
+	funct5 := enc.funct7 >> 2 // extract funct5 from the stored value
+	return (funct5 << 27) | (uint32(rs2) << 20) | (uint32(rs1) << 15) |
+		(enc.funct3 << 12) | (uint32(rd) << 7) | enc.opcode
+}
+
+// FP conversion instructions (FCVT, FMV).  These use the rs2 field to
+// encode the conversion type rather than a register, so they are handled
+// separately from the general instruction table.
+type riscvCvtEnc struct {
+	funct7 uint32 // bits [31:25]
+	rs2    uint32 // conversion-type code in bits [24:20]
+	opcode uint32 // always 0x53 (OP-FP)
+}
+
+var riscvCvtTable = map[string]riscvCvtEnc{
+	// float → int (rs2 selects the integer width/sign).
+	"FCVTWS":  {0x60, 0x0, 0x53}, // float32 → int32
+	"FCVTWUS": {0x60, 0x1, 0x53}, // float32 → uint32
+	"FCVTLS":  {0x60, 0x2, 0x53}, // float32 → int64
+	"FCVTLUS": {0x60, 0x3, 0x53}, // float32 → uint64
+	"FCVTWD":  {0x61, 0x0, 0x53}, // float64 → int32
+	"FCVTWUD": {0x61, 0x1, 0x53}, // float64 → uint32
+	"FCVTLD":  {0x61, 0x2, 0x53}, // float64 → int64
+	"FCVTLUD": {0x61, 0x3, 0x53}, // float64 → uint64
+	// int → float (rs2 selects the integer width/sign).
+	"FCVTSW":  {0x68, 0x0, 0x53}, // int32 → float32
+	"FCVTSWU": {0x68, 0x1, 0x53}, // uint32 → float32
+	"FCVTSL":  {0x68, 0x2, 0x53}, // int64 → float32
+	"FCVTSLU": {0x68, 0x3, 0x53}, // uint64 → float32
+	"FCVTDW":  {0x69, 0x0, 0x53}, // int32 → float64
+	"FCVTDWU": {0x69, 0x1, 0x53}, // uint32 → float64
+	"FCVTDL":  {0x69, 0x2, 0x53}, // int64 → float64
+	"FCVTDLU": {0x69, 0x3, 0x53}, // uint64 → float64
+	// float → float width conversion.
+	"FCVTSD": {0x20, 0x1, 0x53}, // float64 → float32
+	"FCVTDS": {0x21, 0x0, 0x53}, // float32 → float64
+	// Bit moves between integer and FP registers (no conversion).
+	"FMVXD": {0x71, 0x0, 0x53}, // float64 → int64 (bit move)
+	"FMVDX": {0x79, 0x0, 0x53}, // int64 → float64 (bit move)
+	"FMVXW": {0x70, 0x0, 0x53}, // float32 → int32 (bit move)
+	"FMVWX": {0x78, 0x0, 0x53}, // int32 → float32 (bit move)
+}
+
+// riscvCvtType encodes an FP conversion instruction.
+// Layout: funct7 | rs2(convtype) | rs1 | funct3(0) | rd | opcode.
+func riscvCvtType(enc riscvCvtEnc, rd, rs1 int) uint32 {
+	return (enc.funct7 << 25) | (enc.rs2 << 20) | (uint32(rs1) << 15) |
+		(uint32(rd) << 7) | enc.opcode
+}
+
+// R4-type fused multiply-add instructions (FMADD/FMSUB/FNMSUB/FNMADD).
+// These take 4 register operands: rs1, rs2, rs3, rd.
+// Layout: rs3 | fmt | rs2 | rs1 | rm | rd | opcode.
+type riscvFmaEnc struct {
+	fmt    uint32 // bits [26:25]: 0x0 = single, 0x1 = double
+	opcode uint32 // bits [6:0]
+}
+
+var riscvFmaTable = map[string]riscvFmaEnc{
+	"FMADDS":  {0x0, 0x43}, // rd = rs1*rs2 + rs3
+	"FMADDD":  {0x1, 0x43},
+	"FMSUBS":  {0x0, 0x47}, // rd = rs1*rs2 - rs3
+	"FMSUBD":  {0x1, 0x47},
+	"FNMSUBS": {0x0, 0x4B}, // rd = -(rs1*rs2) + rs3
+	"FNMSUBD": {0x1, 0x4B},
+	"FNMADDS": {0x0, 0x4F}, // rd = -(rs1*rs2) - rs3
+	"FNMADDD": {0x1, 0x4F},
+}
+
+// riscvFmaType encodes an R4-type fused multiply-add instruction.
+func riscvFmaType(enc riscvFmaEnc, rd, rs1, rs2, rs3 int) uint32 {
+	return (uint32(rs3) << 27) | (enc.fmt << 25) | (uint32(rs2) << 20) |
+		(uint32(rs1) << 15) | (0x0 << 12) /* rm=dynamic */ | (uint32(rd) << 7) | enc.opcode
+}
+
+// CSR (Control and Status Register) instructions.
+// Format: csr[11:0] | rs1/zimm | funct3 | rd | opcode (0x73).
+type riscvCsrEnc struct {
+	funct3 uint32 // bits [14:12]
+	imm    bool   // true for CSRRWI/CSRRSI/CSRRCI (5-bit uimm variant)
+}
+
+var riscvCsrTable = map[string]riscvCsrEnc{
+	"CSRRW":  {0x1, false}, // rd=CSR, CSR=rs1
+	"CSRRS":  {0x2, false}, // rd=CSR, CSR |= rs1
+	"CSRRC":  {0x3, false}, // rd=CSR, CSR &= ~rs1
+	"CSRRWI": {0x5, true},  // rd=CSR, CSR=uimm
+	"CSRRSI": {0x6, true},  // rd=CSR, CSR |= uimm
+	"CSRRCI": {0x7, true},  // rd=CSR, CSR &= ~uimm
+}
+
+// riscvCsrType encodes a CSR instruction.
+// csr is the 12-bit CSR address; src is either a register number or a 5-bit
+// unsigned immediate (depending on enc.imm).
+func riscvCsrType(enc riscvCsrEnc, rd, src int, csr int32) uint32 {
+	return (uint32(csr&0xFFF) << 20) | (uint32(src&0x1F) << 15) |
+		(enc.funct3 << 12) | (uint32(rd) << 7) | 0x73
+}
+
+// riscvIType encodes an I-type instruction: imm[11:0] | rs1 | funct3 | rd | opcode.
+func riscvIType(enc riscvEnc, rd, rs1 int, imm int32) uint32 {
+	return (uint32(imm&0xFFF) << 20) | (uint32(rs1) << 15) |
+		(enc.funct3 << 12) | (uint32(rd) << 7) | enc.opcode
+}
+
+// riscvSType encodes an S-type instruction: imm[11:5] | rs2 | rs1 | funct3 | imm[4:0] | opcode.
+func riscvSType(enc riscvEnc, rs1, rs2 int, imm int32) uint32 {
+	immU := uint32(imm) & 0xFFF
+	return ((immU >> 5) << 25) | (uint32(rs2) << 20) | (uint32(rs1) << 15) |
+		(enc.funct3 << 12) | ((immU & 0x1F) << 7) | enc.opcode
+}
+
+// riscvBType encodes a B-type instruction (branches).
+func riscvBType(enc riscvEnc, rs1, rs2 int, offset int32) uint32 {
+	imm := uint32(offset) & 0x1FFE     // bits [12:1], bit 0 is always 0
+	return (((imm >> 12) & 1) << 31) | // imm[12]
+		(((imm >> 5) & 0x3F) << 25) | // imm[10:5]
+		(uint32(rs2) << 20) | (uint32(rs1) << 15) |
+		(enc.funct3 << 12) |
+		(((imm >> 1) & 0xF) << 8) | // imm[4:1]
+		(((imm >> 11) & 1) << 7) | // imm[11]
+		enc.opcode
+}
+
+// riscvUType encodes a U-type instruction: imm[31:12] | rd | opcode.
+func riscvUType(enc riscvEnc, rd int, imm int32) uint32 {
+	return (uint32(imm) & 0xFFFFF000) | (uint32(rd) << 7) | enc.opcode
+}
+
+// riscvJType encodes a J-type instruction (JAL).
+func riscvJType(rd int, offset int32) uint32 {
+	imm := uint32(offset) & 0x1FFFFE   // bits [20:1]
+	return (((imm >> 20) & 1) << 31) | // imm[20]
+		(((imm >> 1) & 0x3FF) << 21) | // imm[10:1]
+		(((imm >> 11) & 1) << 20) | // imm[11]
+		(((imm >> 12) & 0xFF) << 12) | // imm[19:12]
+		(uint32(rd) << 7) |
+		0x6F // JAL opcode
+}
+
+// ---- RVC (compressed) encoding helpers ----
+
+// isRVCIntReg reports whether a register number can be encoded in the 3-bit
+// prime register field used by compressed instructions (x8–x15).
+func isRVCIntReg(r int) bool { return r >= 8 && r <= 15 }
+
+// rvcReg3 returns the 3-bit encoding for registers x8–x15 (0–7).
+func rvcReg3(r int) uint32 { return uint32(r - 8) }
+
+// rvcCR encodes a CR-type (register) compressed instruction.
+// Format: funct4 | rd/rs1 | rs2 | op=2.
+func rvcCR(funct4, rd, rs2 uint32) uint16 {
+	return uint16((funct4 << 12) | (rd << 7) | (rs2 << 2) | 0x2)
+}
+
+// rvcCI encodes a CI-type (immediate) compressed instruction.
+// Used for C.ADDI, C.LI, C.LUI, C.ADDIW — linear 6-bit immediate.
+func rvcCI(funct3, rd uint32, imm uint32) uint16 {
+	return uint16((funct3 << 13) | ((imm>>5)&1)<<12 | (rd << 7) | (imm&0x1F)<<2 | 0x2)
+}
+
+// rvcLSP encodes a CI-type stack-relative load: C.LDSP (funct3=3) or
+// C.FLDSP (funct3=1).  offset is the full byte offset; the immediate bits
+// are interleaved per the RISC-V spec: [5:3|8:6].
+func rvcLSP(funct3, rd uint32, offset uint32) uint16 {
+	// Bit interleave offset bits [5,4,3,8,7,6] → packed value.
+	packed := uint32(0)
+	for i, b := range []int{5, 4, 3, 8, 7, 6} {
+		packed |= ((offset >> b) & 1) << (5 - i)
+	}
+	return uint16((funct3 << 13) | ((packed>>5)&1)<<12 | (rd << 7) | (packed&0x1F)<<2 | 0x2)
+}
+
+// rvcSSP encodes a CSS-type stack-relative store: C.SDSP (funct3=7) or
+// C.FSDSP (funct3=5).  offset is the full byte offset; the immediate bits
+// are interleaved per the RISC-V spec: [5:3|8:6].
+func rvcSSP(funct3, rs2 uint32, offset uint32) uint16 {
+	// Bit interleave offset bits [5,4,3,8,7,6] → packed value.
+	packed := uint32(0)
+	for i, b := range []int{5, 4, 3, 8, 7, 6} {
+		packed |= ((offset >> b) & 1) << (5 - i)
+	}
+	return uint16((funct3 << 13) | (packed << 7) | (rs2 << 2) | 0x2)
+}
+
+// rvcCSS encodes a CSS-type (stack store) compressed instruction.
+func rvcCSS(funct3, rs2 uint32, imm uint32) uint16 {
+	return uint16((funct3 << 13) | (imm << 7) | (rs2 << 2) | 0x2)
+}
+
+// rvcCL encodes a CL-type (load) compressed instruction.
+// imm layout: [5:3] in bits [12:10], [2|6] in bits [6:5].
+func rvcCL(funct3, rd, rs1 uint32, imm uint32) uint16 {
+	bits := uint16((funct3 << 13) | ((imm>>3)&0x7)<<10 | (rs1 << 7) | ((imm & 0x7) << 5) | (rd << 2) | 0x0)
+	return bits
+}
+
+// rvcCS encodes a CS-type (store) compressed instruction.
+func rvcCS(funct3, rs2, rs1 uint32, imm uint32) uint16 {
+	return uint16((funct3 << 13) | ((imm>>3)&0x7)<<10 | (rs1 << 7) | ((imm & 0x7) << 5) | (rs2 << 2) | 0x0)
+}
+
+// rvcCJ encodes a CJ-type (jump) compressed instruction.
+// offset is a 12-bit signed offset (bit 0 is always 0).
+func rvcCJ(funct3 uint32, offset int32) uint16 {
+	uoff := uint32(offset) & 0xFFE
+	bits := ((uoff >> 11) & 1) << 10
+	bits |= ((uoff >> 4) & 1) << 9
+	bits |= ((uoff >> 9) & 0x3) << 7
+	bits |= ((uoff >> 10) & 1) << 6
+	bits |= ((uoff >> 6) & 1) << 5
+	bits |= ((uoff >> 7) & 1) << 4
+	bits |= ((uoff >> 1) & 0x7) << 1
+	bits |= ((uoff >> 5) & 1)
+	return uint16((funct3 << 13) | (bits << 2) | 0x1)
+}
+
+// rvcCA encodes a CA-type (arithmetic) compressed instruction.
+// Format: funct6[15:10] | rd'/rs1'[9:7] | funct2[6:5] | rs2'[4:2] | op=01.
+func rvcCA(funct6, funct2, rd, rs2 uint32) uint16 {
+	return uint16((funct6 << 10) | (rd << 7) | (funct2 << 5) | (rs2 << 2) | 0x1)
+}
+
+// rvcCB encodes a CB-type (branch) compressed instruction.
+// Format: funct3[15:13] | offset[8|4:3] | rs1'[9:7] | offset[7:6|2:1|5] | op=01.
+// Bit pattern for offset: [8|4:3|7:6|2:1|5]
+func rvcCB(funct3, rs1 uint32, offset int32) uint16 {
+	uoff := uint32(offset) & 0x1FE // bits [8:1]
+	offBits := uint32(0)
+	offBits |= ((uoff >> 8) & 1) << 10  // bit 10 = offset[8]
+	offBits |= ((uoff >> 3) & 0x3) << 8 // bits 9:8 = offset[4:3]
+	offBits |= ((uoff >> 6) & 0x3) << 6 // bits 7:6 = offset[7:6]
+	offBits |= ((uoff >> 1) & 0x3) << 3 // bits 4:3 = offset[2:1]
+	offBits |= ((uoff >> 5) & 1) << 2   // bit 2 = offset[5]
+	return uint16((funct3 << 13) | offBits | (rs1 << 7) | 0x1)
+}

asm/riscv_encode_test.go

@@ -0,0 +1,749 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import (
+	"testing"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/ast"
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+)
+
+// firstTextRISCV parses assembly source and returns the first TEXT function body.
+func firstTextRISCV(t *testing.T, src string) *ast.Text {
+	t.Helper()
+	f, errs := parser.Parse("f_riscv64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	for _, d := range f.Decls {
+		if fn, ok := d.(*ast.Text); ok {
+			return fn
+		}
+	}
+	t.Fatal("no TEXT found")
+	return nil
+}
+
+// assembleRISCVHelper assembles one TEXT function and returns its code bytes.
+func assembleRISCVHelper(t *testing.T, fn *ast.Text) []byte {
+	t.Helper()
+	code, _, _, err := assembleRISCV(fn)
+	if err != nil {
+		t.Fatalf("assemble: %v", err)
+	}
+	return code
+}
+
+func TestRISCV_add(t *testing.T) {
+	// func add(a, b int64) int64
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·add(SB), NOSPLIT, $0-24
+	MOV a+0(FP), X10
+	MOV b+8(FP), X11
+	ADD X11, X10, X10
+	MOV X10, ret+16(FP)
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// should be 12 bytes with RVC: C.LDSP + C.LDSP + ADD + C.SDSP + C.JR
+	_ = code
+	if len(code) == 0 {
+		t.Error("empty output")
+	}
+}
+
+func TestRISCV_arithmetic(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·arith(SB), NOSPLIT, $0
+	ADD X10, X11, X12
+	SUB X12, X13, X14
+	MUL X14, X15, X16
+	DIV X16, X17, X18
+	REM X18, X19, X20
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// 5 R-type instructions + RET compressed = 5*4 + 2 = 22
+	if len(code) != 22 {
+		t.Errorf("expected 22 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_loadStore(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·mem(SB), NOSPLIT, $0
+	LD (X10), X11
+	SD X11, (X12)
+	LW (X13), X14
+	SW X14, (X15)
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// 4 loads/stores (4B each) + C.JR RET (2B) = 18
+	if len(code) != 18 {
+		t.Errorf("expected 18 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_immediate(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·imm(SB), NOSPLIT, $0
+	ADDI X10, $42, X11
+	ANDI X11, $0xFF, X12
+	ORI X12, $1, X13
+	XORI X13, $0, X14
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// 4 I-type + C.JR = 4*4 + 2 = 18
+	if len(code) != 18 {
+		t.Errorf("expected 18 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_branches(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·br(SB), NOSPLIT, $0
+	ADDI X10, $1, X10
+loop:
+	BEQ X10, X11, done
+	ADDI X10, $1, X10
+	JMP loop
+done:
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	_ = code
+	if len(code) == 0 {
+		t.Error("empty output")
+	}
+}
+
+func TestRISCV_MOV_imm_small(t *testing.T) {
+	// MOV $42, rd → ADDI (fits in 12 bits). Not RVC-compressed (treated as MOV, not ADDI).
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·small(SB), NOSPLIT, $0
+	MOV $42, X10
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// ADDI (4B) + C.JR (2B) = 6
+	if len(code) != 6 {
+		t.Errorf("expected 6 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_MOV_imm_large(t *testing.T) {
+	// MOV $0x12345, rd → LUI + ADDIW (8 bytes total)
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·large(SB), NOSPLIT, $0
+	MOV $0x12345, X10
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// LUI (4B) + ADDIW (4B) + C.JR (2B) = 10
+	if len(code) != 10 {
+		t.Errorf("expected 10 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_MOV_reg(t *testing.T) {
+	// MOV rs, rd → ADDI $0, rs, rd, compresses to C.MV
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·reg(SB), NOSPLIT, $0
+	MOV X10, X11
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// C.MV (2B) + C.JR (2B) = 4
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes, got %d (% x)", len(code), code)
+	}
+}
+
+func TestRISCV_MOV_frame(t *testing.T) {
+	// MOV name+off(FP), rd → load with frame mapping
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·frame(SB), NOSPLIT, $0-8
+	MOV a+0(FP), X10
+	MOV X10, ret+0(FP)
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// C.LDSP (2B) + C.SDSP (2B) + C.JR (2B) = 6
+	if len(code) != 6 {
+		t.Errorf("expected 6 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_loadStore(t *testing.T) {
+	// Verify that loads/stores from SP are compressed.
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·rvcstore(SB), NOSPLIT, $0
+	LD 0(SP), X10
+	SD X10, 8(SP)
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// C.LDSP (2B) + C.SDSP (2B) + C.JR (2B) = 6
+	if len(code) != 6 {
+		t.Errorf("expected 6 bytes, got %d (% x)", len(code), code)
+	}
+}
+
+func TestRISCV_atomics(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·amo(SB), NOSPLIT, $0
+	AMOADDD X10, (X11), X12
+	LRD (X13), X14
+	SCD X15, (X16), X17
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// 3 AMO instructions (4B each) + C.JR (2B) = 14
+	if len(code) != 14 {
+		t.Errorf("expected 14 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_fpArith(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·fpadd(SB), NOSPLIT, $0
+	FADDD F10, F11, F12
+	FSUBD F12, F13, F14
+	FMULD F14, F15, F16
+	FDIVD F16, F17, F18
+	FSQRTD F18, F19
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// 5 FP instructions (4B each) + C.JR (2B) = 22
+	if len(code) != 22 {
+		t.Errorf("expected 22 bytes, got %d (%d)", len(code), len(code))
+	}
+}
+
+func TestRISCV_csr(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·csrtest(SB), NOSPLIT, $0
+	CSRRS $0x300, X0, X10
+	CSRRW $0x305, X10, X11
+	CSRRSI $0x304, $5, X12
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// 3 CSR instructions (4B each) + C.JR (2B) = 14
+	if len(code) != 14 {
+		t.Errorf("expected 14 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_fma(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·fmatest(SB), NOSPLIT, $0
+	FMADDD F10, F11, F12, F13
+	FMSUBD F13, F14, F15, F16
+	FNMSUBD F16, F17, F18, F19
+	FNMADDD F19, F10, F11, F12
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// 4 FMA instructions (4B each) + C.JR (2B) = 18
+	if len(code) != 18 {
+		t.Errorf("expected 18 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_conversions(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·cvt(SB), NOSPLIT, $0
+	FCVTDL X10, F10
+	FCVTLD F10, X11
+	FMVXD F10, X12
+	FMVDX X12, F11
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// 4 conversion instructions (4B each) + C.JR (2B) = 18
+	if len(code) != 18 {
+		t.Errorf("expected 18 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_fpCmp(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·cmp(SB), NOSPLIT, $0
+	FEQD F10, F11, X10
+	FLTD F12, F13, X11
+	FLED F14, F15, X12
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// 3 FP compare (4B each) + C.JR (2B) = 14
+	if len(code) != 14 {
+		t.Errorf("expected 14 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_forwardBranch(t *testing.T) {
+	// Forward label reference — must not fail.
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·fwd(SB), NOSPLIT, $0
+	ADDI X10, $1, X10
+	BEQ X10, X11, done
+	ADDI X10, $1, X10
+done:
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	_ = code
+	if len(code) == 0 {
+		t.Error("empty output")
+	}
+}
+
+func TestRISCV_RVC_ADDI(t *testing.T) {
+	// ADDI where rd=rs1 and small imm → C.ADDI
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·caddi(SB), NOSPLIT, $0
+	ADDI X10, $5, X10
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// C.ADDI (2B) + C.JR (2B) = 4
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_LI(t *testing.T) {
+	// ADDI X0, $imm, rd → C.LI
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·cli(SB), NOSPLIT, $0
+	ADDI X0, $7, X10
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// C.LI (2B) + C.JR (2B) = 4
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_LUI(t *testing.T) {
+	// LUI rd, small nonzero imm → C.LUI
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·clui(SB), NOSPLIT, $0
+	LUI X10, $1
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// C.LUI (2B) + C.JR (2B) = 4
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes, got %d", len(code))
+	}
+}
+
+func TestRISCV_AssembleFile(t *testing.T) {
+	src := `#include "textflag.h"
+
+TEXT ·add(SB), NOSPLIT, $0-24
+	MOV a+0(FP), X10
+	RET
+
+TEXT ·sub(SB), NOSPLIT, $0
+	SUB X10, X11, X12
+	RET
+`
+	f, errs := parser.Parse("t_riscv64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileRISCV(f)
+	if err != nil {
+		t.Fatalf("AssembleFileRISCV: %v", err)
+	}
+	if len(img.Funcs) != 2 {
+		t.Fatalf("expected 2 functions, got %d", len(img.Funcs))
+	}
+	// func add: C.LDSP(2) + C.JR(2) = 4
+	if img.Funcs[0].Size != 4 {
+		t.Errorf("add: expected 4 bytes, got %d", img.Funcs[0].Size)
+	}
+	// func sub: SUB(4) + C.JR(2) = 6
+	if img.Funcs[1].Size != 6 {
+		t.Errorf("sub: expected 6 bytes, got %d", img.Funcs[1].Size)
+	}
+}
+
+func TestRISCV_encodings(t *testing.T) {
+	// Smoke test that all known RISC-V mnemonics encode successfully.
+	tests := []struct {
+		name, src string
+		wantBytes int
+	}{
+		{"ADD", "ADD X10, X11, X12\nRET\n", 6},
+		{"SUBW", "SUBW X10, X11, X12\nRET\n", 6},
+		{"MUL", "MUL X10, X11, X12\nRET\n", 6},
+		{"DIVW", "DIVW X10, X11, X12\nRET\n", 6},
+		{"REMUW", "REMUW X10, X11, X12\nRET\n", 6},
+		{"ADDIW", "ADDIW X10, $5, X11\nRET\n", 6},
+		{"SLLI", "SLLI X10, $3, X11\nRET\n", 6}, // ADDI+SLLI? No, SLLI uses I-type
+		{"SRLI", "SRLI X10, $2, X11\nRET\n", 6},
+		{"SRAI", "SRAI X10, $1, X11\nRET\n", 6},
+		{"LB", "LB (X10), X11\nRET\n", 6},
+		{"LBU", "LBU (X10), X11\nRET\n", 6},
+		{"LH", "LH (X10), X11\nRET\n", 6},
+		{"LHU", "LHU (X10), X11\nRET\n", 6},
+		{"LWU", "LWU (X10), X11\nRET\n", 6},
+		{"SB", "SB X10, (X11)\nRET\n", 6},
+		{"SH", "SH X10, (X11)\nRET\n", 6},
+		{"SW", "SW X10, (X11)\nRET\n", 6},
+		{"LUI", "LUI X10, $0x12345\nRET\n", 6},
+		{"AUIPC", "AUIPC X10, $0\nRET\n", 6},
+		{"FLW", "FLW (X10), F10\nRET\n", 6},
+		{"FSW", "FSW F10, (X11)\nRET\n", 6},
+		{"FADDS", "FADDS F10, F11, F12\nRET\n", 6},
+		{"FMINS", "FMINS F10, F11, F12\nRET\n", 6},
+		{"FMAXD", "FMAXD F10, F11, F12\nRET\n", 6},
+		{"FCVTSD", "FCVTSD F10, F11\nRET\n", 6},
+		{"FCVTDS", "FCVTDS F10, F11\nRET\n", 6},
+		{"FMVXW", "FMVXW F10, X10\nRET\n", 6},
+		{"FMADD_S", "FMADDS F10, F11, F12, F13\nRET\n", 6},
+	}
+
+	for _, tt := range tests {
+		t.Run(tt.name, func(t *testing.T) {
+			fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·`+tt.name+`(SB), NOSPLIT, $0
+	`+tt.src)
+			code := assembleRISCVHelper(t, fn)
+			if len(code) != tt.wantBytes {
+				t.Errorf("expected %d bytes, got %d", tt.wantBytes, len(code))
+			}
+		})
+	}
+}
+
+func TestRISCV_RVC_branch(t *testing.T) {
+	// BEQ rs, X0, target → C.BEQZ when rs is in prime regs and offset fits.
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·cbeqz(SB), NOSPLIT, $0
+	ADDI X10, $1, X10
+	BEQ X10, X0, done
+	ADDI X10, $1, X10
+done:
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// C.ADDI(2) + C.BEQZ(2) + C.ADDI(2) + C.JR(2) = 8 (all compress)
+	if len(code) != 8 {
+		t.Errorf("expected 8 bytes with C.BEQZ, got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_CJ(t *testing.T) {
+	// JMP target → C.J when offset fits.
+	fn := firstTextRISCV(t, `#include "textflag.h"
+	TEXT ·cj(SB), NOSPLIT, $0
+		JMP done
+	done:
+		RET
+	`)
+	code := assembleRISCVHelper(t, fn)
+	// C.J(2) + C.JR(2) = 4
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes with C.J, got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_CADD(t *testing.T) {
+	// ADD where rd==rs1 and both in prime regs → C.ADD.
+	fn := firstTextRISCV(t, `#include "textflag.h"
+	TEXT ·cadd(SB), NOSPLIT, $0
+		ADD X10, X11, X10
+		RET
+	`)
+	code := assembleRISCVHelper(t, fn)
+	// C.ADD(2) + C.JR(2) = 4
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes with C.ADD, got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_CADD_commute(t *testing.T) {
+	// ADD where rd==rs2 (commutative swap) → C.ADD.
+	fn := firstTextRISCV(t, `#include "textflag.h"
+	TEXT ·cadd2(SB), NOSPLIT, $0
+		ADD X11, X10, X10
+		RET
+	`)
+	code := assembleRISCVHelper(t, fn)
+	// C.ADD(2) + C.JR(2) = 4
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes with C.ADD (commuted), got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_CSUB(t *testing.T) {
+	// SUB where rd==rs1 and both in prime regs → C.SUB.
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·csub(SB), NOSPLIT, $0
+	SUB X11, X10, X10
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// SUB X11,X10,X10 → rd=X10, rs1=X11 ≠ rd → no C.SUB.
+	// Plan9: INSTR src1, src2, dst. For C.SUB: rd must equal rs1.
+	// So: SUB X10, X11, X10 → rd=10, rs1=10, rs2=11 ✓
+	if len(code) == 4 {
+		return // compressed
+	}
+	// Try with correct operand order.
+	fn2 := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·csub2(SB), NOSPLIT, $0
+	SUB X10, X11, X10
+	RET
+`)
+	code2 := assembleRISCVHelper(t, fn2)
+	if len(code2) != 4 {
+		t.Errorf("expected 4 bytes with C.SUB, got %d (% x)", len(code2), code2)
+	}
+}
+
+func TestRISCV_RVC_CXOR(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·cxor(SB), NOSPLIT, $0
+	XOR X10, X11, X10
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes with C.XOR, got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_COR(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·cor(SB), NOSPLIT, $0
+	OR X10, X11, X10
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes with C.OR, got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_CAND(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·cand(SB), NOSPLIT, $0
+	AND X10, X11, X10
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes with C.AND, got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_CFLDSP(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·cfldsp(SB), NOSPLIT, $0-8
+	FLD a+0(FP), F10
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// C.FLDSP(2) + C.JR(2) = 4
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes with C.FLDSP, got %d", len(code))
+	}
+}
+
+func TestRISCV_RVC_CFSDSP(t *testing.T) {
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·cfsdsp(SB), NOSPLIT, $0-8
+	FSD F10, ret+0(FP)
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// C.FSDSP(2) + C.JR(2) = 4
+	if len(code) != 4 {
+		t.Errorf("expected 4 bytes with C.FSDSP, got %d", len(code))
+	}
+}
+
+func TestRISCV_SB_addr(t *testing.T) {
+	// MOV $sym<>(SB), rd → AUIPC + ADDI (8 bytes for SB).
+	src := `#include "textflag.h"
+TEXT ·sbaddr(SB), NOSPLIT, $0
+	MOV $answer<>(SB), X10
+	RET
+GLOBL answer<>(SB), RODATA, $8
+DATA answer<>+0(SB)/8, $42
+`
+	f, errs := parser.Parse("t_riscv64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileRISCV(f)
+	if err != nil {
+		t.Fatalf("AssembleFileRISCV: %v", err)
+	}
+	// AUIPC(4) + ADDI(4) + C.JR(2) = 10
+	if img.Funcs[0].Size != 10 {
+		t.Errorf("expected 10 bytes, got %d", img.Funcs[0].Size)
+	}
+}
+
+func TestRISCV_SB_store(t *testing.T) {
+	// MOV rd, sym<>(SB) → AUIPC + SD (8 bytes for SB).
+	src := `#include "textflag.h"
+TEXT ·sbstore(SB), NOSPLIT, $0
+	MOV X10, result<>(SB)
+	RET
+GLOBL result<>(SB), NOPTR, $8
+`
+	f, errs := parser.Parse("t_riscv64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileRISCV(f)
+	if err != nil {
+		t.Fatalf("AssembleFileRISCV: %v", err)
+	}
+	// AUIPC X31(4) + SD X10,0(X31)(4) + C.JR(2) = 10
+	if img.Funcs[0].Size != 10 {
+		t.Errorf("expected 10 bytes, got %d", img.Funcs[0].Size)
+	}
+}
+
+func TestRISCV_ELF(t *testing.T) {
+	src := `#include "textflag.h"
+TEXT ·simple(SB), NOSPLIT, $0
+	RET
+`
+	f, errs := parser.Parse("t_riscv64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileRISCV(f)
+	if err != nil {
+		t.Fatalf("AssembleFileRISCV: %v", err)
+	}
+	obj, err := img.ELFRISCVObject()
+	if err != nil {
+		t.Fatalf("ELFRISCVObject: %v", err)
+	}
+	if len(obj) < 4 || obj[0] != 0x7f || obj[1] != 'E' || obj[2] != 'L' || obj[3] != 'F' {
+		t.Fatal("not a valid ELF file")
+	}
+	if len(obj) >= 20 {
+		machine := uint16(obj[18]) | uint16(obj[19])<<8
+		if machine != 243 {
+			t.Errorf("e_machine = %d, want 243 (EM_RISCV)", machine)
+		}
+	}
+}
+
+func TestRISCV_ELF_withData(t *testing.T) {
+	src := `#include "textflag.h"
+TEXT ·get(SB), NOSPLIT, $0
+	RET
+GLOBL val<>(SB), RODATA, $4
+DATA val<>+0(SB)/4, $7
+`
+	f, errs := parser.Parse("t_riscv64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileRISCV(f)
+	if err != nil {
+		t.Fatalf("AssembleFileRISCV: %v", err)
+	}
+	if len(img.DataSyms) != 1 {
+		t.Fatalf("expected 1 data symbol, got %d", len(img.DataSyms))
+	}
+	if img.DataSyms[0].Name != "val" {
+		t.Errorf("data symbol name = %q, want val", img.DataSyms[0].Name)
+	}
+	if img.DataSyms[0].Size != 4 {
+		t.Errorf("data symbol size = %d, want 4", img.DataSyms[0].Size)
+	}
+	obj, err := img.ELFRISCVObject()
+	if err != nil {
+		t.Fatalf("ELFRISCVObject: %v", err)
+	}
+	_ = obj
+}
+
+func TestRISCV_SB_load(t *testing.T) {
+	// MOV sym<>(SB), rd → AUIPC + LD (8 bytes for SB).
+	src := `#include "textflag.h"
+TEXT ·sbload(SB), NOSPLIT, $0
+	MOV answer<>(SB), X10
+	RET
+GLOBL answer<>(SB), RODATA, $8
+DATA answer<>+0(SB)/8, $42
+`
+	f, errs := parser.Parse("t_riscv64.s", src)
+	if len(errs) > 0 {
+		t.Fatalf("parse: %v", errs)
+	}
+	img, err := AssembleFileRISCV(f)
+	if err != nil {
+		t.Fatalf("AssembleFileRISCV: %v", err)
+	}
+	// AUIPC(4) + LD(4) + C.JR(2) = 10
+	if img.Funcs[0].Size != 10 {
+		t.Errorf("expected 10 bytes, got %d", img.Funcs[0].Size)
+	}
+}
+
+func TestRISCV_system_instrs(t *testing.T) {
+	// Test FENCE, ECALL, EBREAK encoding.
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·sys(SB), NOSPLIT, $0
+	FENCE
+	ECALL
+	EBREAK
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// 3 system instructions × 4 bytes + C.JR(2) = 14
+	if len(code) != 14 {
+		t.Errorf("expected 14 bytes, got %d (% x)", len(code), code)
+	}
+}
+
+func TestRISCV_MOV_sym_FP_error(t *testing.T) {
+	// MOV $sym(FP), rd should return an error (unsupported).
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·badfp(SB), NOSPLIT, $0
+	MOV $arg(FP), X10
+	RET
+`)
+	_, _, _, err := assembleRISCV(fn)
+	if err == nil {
+		t.Error("expected error for MOV $arg(FP), got nil")
+	}
+}
+
+func TestRISCV_CALL(t *testing.T) {
+	// CALL target → AUIPC + JALR (8 bytes).
+	fn := firstTextRISCV(t, `#include "textflag.h"
+TEXT ·calltest(SB), NOSPLIT, $0
+	CALL sub
+done:
+	RET
+sub:
+	RET
+`)
+	code := assembleRISCVHelper(t, fn)
+	// CALL(8) + C.JR(2) + C.JR(2) = 12
+	if len(code) != 12 {
+		t.Errorf("expected 12 bytes with CALL, got %d", len(code))
+	}
+}

asm/riscv_frame.go

@@ -0,0 +1,117 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package asm
+
+import "sourcedock.dev/petrbalvin/gasm-devkit/ast"
+
+// RISC-V frame mapping: translates Go's FP/SP pseudo-register addressing
+// into real RISC-V memory accesses.
+//
+// In Go's ABI0 (used by assembly functions), arguments are passed on the
+// stack.  At function entry the return address sits at SP, so the frame
+// pointer FP == SP+8 and the first argument is at FP+0 == SP+8.
+//
+// On RISC-V the hardware registers are:
+//   SP = X2 (stack pointer)
+//   FP = S0 = X8 (frame pointer, by convention)
+//
+// For NOSPLIT $0 functions the prologue is omitted and arguments are read
+// directly from SP+8+offset.
+
+// riscvFrameInfo holds the frame parameters computed from a TEXT directive.
+type riscvFrameInfo struct {
+	frameSize int  // the $framesize from TEXT
+	argsSize  int  // the -argsize from TEXT
+	noSplit   bool // the NOSPLIT flag
+}
+
+// riscvComputeFrame extracts frame information from a TEXT directive.
+func riscvComputeFrame(t *ast.Text) riscvFrameInfo {
+	fi := riscvFrameInfo{}
+	fi.frameSize = frameSize(t)
+	fi.argsSize = argsSize(t)
+	for _, f := range t.Flags {
+		if f == "NOSPLIT" {
+			fi.noSplit = true
+		}
+	}
+	return fi
+}
+
+// riscvPrologue returns the prologue bytes for a RISC-V function.
+// For NOSPLIT $0 functions there is no prologue.  For functions with a
+// frame, we emit: ADDI SP, SP, -framesize; SD S0, (framesize-8)(SP); ...
+func riscvPrologue(fi riscvFrameInfo) []byte {
+	if fi.noSplit && fi.frameSize == 0 {
+		return nil // no prologue for NOSPLIT $0
+	}
+	var out []byte
+	if fi.frameSize > 0 {
+		// ADDI SP, SP, -framesize
+		out = append(out, riscvITypeLE(0x13, 0x0, 2, 2, int32(-fi.frameSize))...)
+		// Save the frame pointer (S0 = X8) at the top of the new frame.
+		// SD S0, (framesize-8)(SP)
+		out = append(out, riscvSTypeLE(0x23, 0x3, 2, 8, int32(fi.frameSize-8))...)
+	}
+	return out
+}
+
+// riscvEpilogue returns the epilogue bytes for a RISC-V function.
+func riscvEpilogue(fi riscvFrameInfo) []byte {
+	if fi.noSplit && fi.frameSize == 0 {
+		return nil
+	}
+	var out []byte
+	if fi.frameSize > 0 {
+		// Restore the frame pointer: LD S0, (framesize-8)(SP)
+		out = append(out, riscvITypeLE(0x03, 0x3, 8, 2, int32(fi.frameSize-8))...)
+		// ADDI SP, SP, framesize
+		out = append(out, riscvITypeLE(0x13, 0x0, 2, 2, int32(fi.frameSize))...)
+	}
+	return out
+}
+
+// riscvResolvePseudo translates a pseudo-register memory reference into a
+// real base register and offset.  It handles name+offset(FP) and
+// name+offset(SP).
+//
+// Returns the base register number and the adjusted offset.
+func riscvResolvePseudo(sym *ast.Symbol, fi riscvFrameInfo) (base int, off int32) {
+	if sym == nil {
+		return -1, 0
+	}
+	offset := int32(sym.Offset)
+	switch sym.Pseudo {
+	case "FP":
+		// FP == SP+8 for NOSPLIT $0; arguments are at SP+8+offset.
+		if fi.noSplit && fi.frameSize == 0 {
+			return 2, 8 + offset // SP + 8 + argOffset
+		}
+		// With a frame, FP points to the saved frame; args are at FP+offset.
+		return 8, offset // S0 + argOffset
+	case "SP":
+		// SP-relative; the offset is from the current SP.
+		return 2, offset
+	case "SB":
+		// Static data reference — needs a relocation (not yet supported).
+		return -1, offset
+	default:
+		return -1, offset
+	}
+}
+
+// riscvITypeLE encodes an I-type instruction and returns little-endian bytes.
+func riscvITypeLE(opcode, funct3 uint32, rd, rs1 int, imm int32) []byte {
+	word := (uint32(imm&0xFFF) << 20) | (uint32(rs1) << 15) |
+		(funct3 << 12) | (uint32(rd) << 7) | opcode
+	return []byte{byte(word), byte(word >> 8), byte(word >> 16), byte(word >> 24)}
+}
+
+// riscvSTypeLE encodes an S-type instruction and returns little-endian bytes.
+func riscvSTypeLE(opcode, funct3 uint32, rs1, rs2 int, imm int32) []byte {
+	immU := uint32(imm) & 0xFFF
+	word := ((immU >> 5) << 25) | (uint32(rs2) << 20) | (uint32(rs1) << 15) |
+		(funct3 << 12) | ((immU & 0x1F) << 7) | opcode
+	return []byte{byte(word), byte(word >> 8), byte(word >> 16), byte(word >> 24)}
+}

cmd/gasm/debug_linux_amd64.go

@@ -0,0 +1,193 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && amd64
+
+package main
+
+import (
+	"fmt"
+	"os"
+	"sort"
+	"strings"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/debug"
+	"sourcedock.dev/petrbalvin/gasm-devkit/verify"
+)
+
+func cmdDebug(args []string) int {
+	fs := newCommand("debug", "gasm debug <file.s> --func <name>", `
+Interactive debugger for JIT-assembled amd64 functions.  Launches the
+function in a traced subprocess (ptrace), then provides a REPL for
+single-stepping, breakpoints, register and memory inspection.
+
+REPL commands:
+  break <label|addr>   set a breakpoint at a label or absolute address
+  step [n]             single-step n instructions (default 1)
+  continue             run until next breakpoint or exit
+  regs                 print general-purpose registers
+  x [addr] [len]       hex-dump memory (default: current PC, 64 bytes)
+  labels               list function labels and offsets
+  quit                 kill the debuggee and exit
+`)
+	target := fs.Bool("target", false, "") // hidden: debuggee subprocess mode
+	funcName := fs.String("func", "", "function to debug")
+	argsFile := fs.String("args", "", "file containing the ABI0 argument block")
+	bufSpec := fs.String("buf", "", "buffer specification: name:size:pattern[,name:size:pattern...] where pattern is zero, ones, seq, or hex")
+	fs.Parse(args)
+
+	// --- Debuggee mode (internal, spawned by the debugger) ---
+	if *target {
+		tmpDir := os.Getenv("GASM_DEBUG_TMP")
+		if tmpDir == "" || fs.NArg() < 1 || *funcName == "" || *argsFile == "" {
+			fmt.Fprintln(os.Stderr, "gasm debug --target: internal mode")
+			return 2
+		}
+		if err := debug.RunTarget(fs.Arg(0), *funcName, *argsFile, tmpDir); err != nil {
+			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+			return 1
+		}
+		return 0
+	}
+
+	// --- Debugger mode (interactive REPL) ---
+	if fs.NArg() < 1 || *funcName == "" {
+		fmt.Fprintln(os.Stderr, "usage: gasm debug <file.s> --func <name>")
+		return 2
+	}
+	path := fs.Arg(0)
+
+	// Load the kernel to extract function metadata and labels.
+	k, err := verify.Load(path)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+		return 1
+	}
+	defer k.Close()
+
+	fl, err := k.Func(*funcName)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+		return 1
+	}
+
+	// Build the label list for the REPL.
+	var labels []debug.Label
+	for name, off := range fl.Labels {
+		labels = append(labels, debug.Label{Name: name, Offset: off})
+	}
+	sort.Slice(labels, func(i, j int) bool { return labels[i].Offset < labels[j].Offset })
+
+	// Launch the debuggee with the argument block.
+	var argBlock []byte
+	var bufAddrs []uint64
+	var sess *debug.Session
+	if *bufSpec != "" {
+		// Parse the function signature to determine argument layout.
+		src, err := readSource(path)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+			return 1
+		}
+		sig, ok := verify.ExtractFuncSig(src, *funcName)
+		if !ok {
+			fmt.Fprintf(os.Stderr, "gasm debug: no // func signature found for %s\n", *funcName)
+			return 1
+		}
+		layout := verify.ArgLayout(sig)
+
+		// Parse the buffer spec to get buffer names.
+		bufNames := parseBufNames(*bufSpec)
+
+		// Allocate buffers in the debuggee.
+		argBlock = make([]byte, fl.Args)
+		sess, bufAddrs, err = debug.LaunchWithBuffers("", path, *funcName, argBlock, *bufSpec)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+			return 1
+		}
+
+		// Construct the argument block with buffer pointers at the correct positions.
+		bufIdx := 0
+		for _, arg := range layout {
+			if !arg.IsPtr {
+				continue
+			}
+			// Find the buffer that matches this argument.
+			for i, name := range bufNames {
+				if i < len(bufAddrs) && (name == arg.Name || strings.HasPrefix(arg.Name, name)) {
+					addr := bufAddrs[i]
+					off := arg.Offset
+					if off+8 <= len(argBlock) {
+						argBlock[off] = byte(addr)
+						argBlock[off+1] = byte(addr >> 8)
+						argBlock[off+2] = byte(addr >> 16)
+						argBlock[off+3] = byte(addr >> 24)
+						argBlock[off+4] = byte(addr >> 32)
+						argBlock[off+5] = byte(addr >> 40)
+						argBlock[off+6] = byte(addr >> 48)
+						argBlock[off+7] = byte(addr >> 56)
+					}
+					// For slices, also set the length and capacity.
+					if strings.HasPrefix(arg.Typ, "[]") && off+24 <= len(argBlock) {
+						// Find the buffer size from the spec.
+						size := parseBufSize(*bufSpec, name)
+						// Length at offset+8, capacity at offset+16.
+						for j := 0; j < 8; j++ {
+							argBlock[off+8+j] = byte(size >> (j * 8))
+							argBlock[off+16+j] = byte(size >> (j * 8))
+						}
+					}
+					bufIdx++
+					break
+				}
+			}
+		}
+		_ = bufIdx
+	} else {
+		argBlock = make([]byte, fl.Args)
+		sess, err = debug.Launch("", path, *funcName, argBlock)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm debug: %v\n", err)
+			return 1
+		}
+	}
+	defer sess.Kill()
+
+	bm := debug.NewBreakpoints(sess)
+	fmt.Printf("gasm debug: %s in %s (pid %d)\n", *funcName, path, sess.Pid())
+
+	// Convert the line table for the REPL.
+	var srcLines []debug.SourceLine
+	for _, le := range fl.Lines {
+		srcLines = append(srcLines, debug.SourceLine{Offset: le.Offset, Line: le.Line})
+	}
+	debug.REPL(sess, bm, sess.CodeBase(), fl.Offset, fl.Size, fl.Args, labels, srcLines)
+	return 0
+}
+
+// parseBufNames extracts buffer names from a buffer specification.
+// Format: name:size:pattern[,name:size:pattern...]
+func parseBufNames(spec string) []string {
+	var names []string
+	for _, part := range strings.Split(spec, ",") {
+		fields := strings.SplitN(part, ":", 3)
+		if len(fields) >= 1 && fields[0] != "" {
+			names = append(names, fields[0])
+		}
+	}
+	return names
+}
+
+// parseBufSize extracts the size of a named buffer from a buffer specification.
+func parseBufSize(spec, name string) int {
+	for _, part := range strings.Split(spec, ",") {
+		fields := strings.SplitN(part, ":", 3)
+		if len(fields) >= 2 && fields[0] == name {
+			var size int
+			fmt.Sscanf(fields[1], "%d", &size)
+			return size
+		}
+	}
+	return 0
+}

cmd/gasm/debug_other.go

@@ -0,0 +1,16 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build !(linux && amd64)
+
+package main
+
+import (
+	"fmt"
+	"os"
+)
+
+func cmdDebug(args []string) int {
+	fmt.Fprintln(os.Stderr, "gasm debug: the interactive debugger requires linux/amd64 (ptrace)")
+	return 1
+}

cmd/gasm/main.go

@@ -8,13 +8,18 @@
 package main
 
 import (
+	"bytes"
 	"flag"
 	"fmt"
 	"io"
 	"io/fs"
 	"os"
+	"os/exec"
 	"path/filepath"
+	"sort"
+	"strconv"
 	"strings"
+	"syscall"
 
 	"sourcedock.dev/petrbalvin/gasm-devkit/arch"
 	"sourcedock.dev/petrbalvin/gasm-devkit/asm"
@@ -29,7 +34,7 @@ import (
 
 // version is the release version, stamped at build time via
 // -ldflags "-X main.version=…" (defaulting to the current release).
-var version = "0.20.0"
+var version = "0.29.0"
 
 func main() {
 	if len(os.Args) < 2 {
@@ -49,6 +54,12 @@ func main() {
 		os.Exit(cmdAsm(os.Args[2:]))
 	case "verify":
 		os.Exit(cmdVerify(os.Args[2:]))
+	case "debug":
+		os.Exit(cmdDebug(os.Args[2:]))
+	case "diff":
+		os.Exit(cmdDiff(os.Args[2:]))
+	case "profile":
+		os.Exit(cmdProfile(os.Args[2:]))
 	case "lsp":
 		os.Exit(cmdLSP(os.Args[2:]))
 	case "version", "--version", "-V":
@@ -67,39 +78,78 @@ func cmdVersion() int {
 	return 0
 }
 
+// ANSI color helpers for terminal output.
+const (
+	colorReset  = "\033[0m"
+	colorBold   = "\033[1m"
+	colorCyan   = "\033[36m"
+	colorYellow = "\033[33m"
+	colorGray   = "\033[90m"
+)
+
+// isTTY reports whether the writer is a terminal (for color output).
+func isTTY(w io.Writer) bool {
+	if f, ok := w.(*os.File); ok {
+		stat, _ := f.Stat()
+		return (stat.Mode() & os.ModeCharDevice) != 0
+	}
+	return false
+}
+
 func usage(w io.Writer) {
-	fmt.Fprintf(w, `gasm %s — developer tooling for Go's Plan 9 assembler (GAsm)
+	useColor := isTTY(w)
+	bold, cyan, yellow, gray, reset := "", "", "", "", ""
+	if useColor {
+		bold, cyan, yellow, gray, reset = colorBold, colorCyan, colorYellow, colorGray, colorReset
+	}
 
-gasm bundles a lexer, parser, formatter, linter, standalone assembler and
-language server for Plan 9 assembly into one self-contained binary.
+	fmt.Fprintf(w, "%sgasm %s%s — developer tooling for Go's Plan 9 assembler (GAsm)%s\n\n", bold, version, reset, reset)
+	fmt.Fprintf(w, "gasm bundles a lexer, parser, formatter, linter, standalone assembler and\n")
+	fmt.Fprintf(w, "language server for Plan 9 assembly into one self-contained binary.\n\n")
 
-Usage:
-  gasm <command> [arguments]
-  gasm [flags]
+	fmt.Fprintf(w, "%sUsage:%s\n", yellow, reset)
+	fmt.Fprintf(w, "  gasm <command> [arguments]\n")
+	fmt.Fprintf(w, "  gasm [flags]\n\n")
 
-Commands:
-  tokens    print the lexical token stream
-  parse     parse and report syntax errors
-  fmt       canonicalise formatting (gofmt for assembly)
-  lint      run static checks
-  asm       assemble .s files to machine code (amd64)
-  verify    JIT-assemble and run dynamic checks (amd64)
-  lsp       run the language server over stdio
-  version   print the version (same as --version)
+	fmt.Fprintf(w, "%sCommands:%s\n", yellow, reset)
+	commands := []struct{ name, desc string }{
+		{"tokens", "print the lexical token stream"},
+		{"parse", "parse and report syntax errors"},
+		{"fmt", "canonicalise formatting (gofmt for assembly)"},
+		{"lint", "run static checks"},
+		{"asm", "assemble .s files to machine code (amd64, riscv64)"},
+		{"verify", "JIT-assemble and run dynamic checks (amd64, riscv64)"},
+		{"debug", "interactive source-level debugger (amd64)"},
+		{"diff", "compare machine code of two .s files"},
+		{"profile", "show basic-block structure of functions"},
+		{"lsp", "run the language server over stdio"},
+		{"version", "print the version (same as --version)"},
+	}
+	for _, c := range commands {
+		fmt.Fprintf(w, "  %s%-10s%s %s%s%s\n", cyan, c.name, reset, gray, c.desc, reset)
+	}
 
-Flags:
-  -h, --help      show this help
-  -V, --version   print the version
+	fmt.Fprintf(w, "\n%sFlags:%s\n", yellow, reset)
+	fmt.Fprintf(w, "  %s-h, --help%s      %sshow this help%s\n", cyan, reset, gray, reset)
+	fmt.Fprintf(w, "  %s-V, --version%s   %sprint the version%s\n", cyan, reset, gray, reset)
 
-Run "gasm <command> -h" for a command's usage and flags.
+	fmt.Fprintf(w, "\nRun \"gasm <command> -h\" for a command's usage and flags.\n\n")
 
-Examples:
-  gasm fmt                  reformat every .s below the current directory
-  gasm lint go-flac/*.s     run static checks over the kernels
-  gasm asm -o k.bin kern_amd64.s
-  gasm asm --format elf -o k.o kern_amd64.s
-  gasm asm --format goobj -p pkg/path -o k.o kern_amd64.s
-`, version)
+	fmt.Fprintf(w, "%sExamples:%s\n", yellow, reset)
+	examples := []struct{ cmd, desc string }{
+		{"gasm fmt", "reformat every .s below the current directory"},
+		{"gasm lint go-flac/*.s", "run static checks over the kernels"},
+		{"gasm asm -o k.bin kern_amd64.s", ""},
+		{"gasm asm --format elf -o k.o kern_amd64.s", ""},
+		{"gasm asm --format goobj -p pkg/path -o k.o kern_amd64.s", ""},
+	}
+	for _, e := range examples {
+		if e.desc != "" {
+			fmt.Fprintf(w, "  %s%s%s  %s%s%s\n", cyan, e.cmd, reset, gray, e.desc, reset)
+		} else {
+			fmt.Fprintf(w, "  %s%s%s\n", cyan, e.cmd, reset)
+		}
+	}
 }
 
 // newCommand returns the FlagSet of a subcommand whose -h/--help prints a
@@ -346,7 +396,7 @@ hover, document symbols, diagnostics and semantic-token highlighting.
 
 func cmdAsm(args []string) int {
 	fs := newCommand("asm", "gasm asm [--format raw|elf|macho|goobj] [-p pkg] [-o out] <file>", `
-Assemble FILE (amd64) without the Go toolchain: every TEXT function is
+Assemble FILE (amd64 or riscv64) without the Go toolchain: every TEXT function is
 encoded to machine code — scalar, VEX/AVX2 and EVEX/AVX-512 instructions,
 FP/SP frame mapping, local labels and file-local static symbols (GLOBL/DATA)
 resolved RIP-relative — and printed as a hex dump.
@@ -368,8 +418,9 @@ requires -p, the package path, and the installed Go toolchain).
 		return 2
 	}
 	path := fs.Arg(0)
-	if arch.FromFilename(path) != arch.AMD64 {
-		fmt.Fprintln(os.Stderr, "gasm asm: only amd64 is supported in this Phase 2 increment")
+	targetArch := arch.FromFilename(path)
+	if targetArch != arch.AMD64 && targetArch != arch.RISCV {
+		fmt.Fprintln(os.Stderr, "gasm asm: only amd64 and riscv64 are supported")
 		return 1
 	}
 	src, err := readSource(path)
@@ -385,7 +436,12 @@ requires -p, the package path, and the installed Go toolchain).
 		return 1
 	}
 
-	img, err := asm.AssembleFile(f)
+	var img *asm.Image
+	if targetArch == arch.RISCV {
+		img, err = asm.AssembleFileRISCV(f)
+	} else {
+		img, err = asm.AssembleFile(f)
+	}
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "%s: %v\n", path, err)
 		return 1
@@ -446,13 +502,21 @@ requires -p, the package path, and the installed Go toolchain).
 			}
 			obj, kind = img.Bytes(), "raw image"
 		case "elf":
-			obj, err = img.ELFObject()
+			if targetArch == arch.RISCV {
+				obj, err = img.ELFRISCVObject()
+			} else {
+				obj, err = img.ELFObject()
+			}
 			kind = "ELF object"
 		case "macho":
 			obj, err = img.MachOObject()
 			kind = "Mach-O object"
 		case "goobj":
-			obj, err = img.GOObject(*pkg, path)
+			if targetArch == arch.RISCV {
+				obj, err = img.GOObjectRISCV(*pkg, path)
+			} else {
+				obj, err = img.GOObject(*pkg, path)
+			}
 			kind = "Go object"
 		default:
 			fmt.Fprintf(os.Stderr, "gasm asm: unknown format %q (want raw, elf, macho or goobj)\n", *format)
@@ -471,8 +535,295 @@ requires -p, the package path, and the installed Go toolchain).
 	return 0
 }
 
+// cmdDiff compares the machine code of two assembly files.
+func cmdDiff(args []string) int {
+	fs := newCommand("diff", "gasm diff <file1.s> <file2.s>", `
+Compare the machine code produced by assembling two files.
+Shows which functions differ and the byte-level differences.
+Useful for verifying that two implementations produce identical code,
+or for tracking encoding changes between Go assembler versions.
+
+Use --map to compare functions whose names differ between the files,
+e.g. --map wideCopyAVX2=wideCopyAVX512 pairs the two regardless of suffix.
+`)
+	mapSpec := fs.String("map", "", "comma-separated old=new pairs to match functions with different names")
+	fs.Parse(args)
+	if fs.NArg() != 2 {
+		fmt.Fprintln(os.Stderr, "usage: gasm diff <file1.s> <file2.s>")
+		return 2
+	}
+	path1, path2 := fs.Arg(0), fs.Arg(1)
+
+	// Parse the name mapping (file1 name → file2 name).
+	nameMap := make(map[string]string)
+	if *mapSpec != "" {
+		for _, pair := range strings.Split(*mapSpec, ",") {
+			old, new, ok := strings.Cut(pair, "=")
+			if !ok || old == "" || new == "" {
+				fmt.Fprintf(os.Stderr, "gasm diff: invalid --map pair %q (expected old=new)\n", pair)
+				return 2
+			}
+			nameMap[old] = new
+		}
+	}
+
+	// Assemble both files.
+	img1, err := assembleFile(path1)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm diff: %s: %v\n", path1, err)
+		return 1
+	}
+	img2, err := assembleFile(path2)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm diff: %s: %v\n", path2, err)
+		return 1
+	}
+
+	// Compare functions by name, honouring the --map overrides.
+	funcs1 := make(map[string][]byte)
+	for _, fn := range img1.Funcs {
+		funcs1[fn.Name] = img1.Code[fn.Offset : fn.Offset+fn.Size]
+	}
+	funcs2 := make(map[string][]byte)
+	for _, fn := range img2.Funcs {
+		funcs2[fn.Name] = img2.Code[fn.Offset : fn.Offset+fn.Size]
+	}
+
+	// Track which file2 functions were consumed (by direct match or via --map)
+	// so the "only in file2" pass skips them.
+	matched2 := make(map[string]bool)
+
+	diffs := 0
+	for name, code1 := range funcs1 {
+		target := name
+		if mapped, ok := nameMap[name]; ok {
+			target = mapped
+		}
+		code2, ok := funcs2[target]
+		if !ok {
+			fmt.Printf("%s: only in %s\n", name, path1)
+			diffs++
+			continue
+		}
+		matched2[target] = true
+		label := name
+		if target != name {
+			label = name + " → " + target
+		}
+		if !bytes.Equal(code1, code2) {
+			fmt.Printf("%s: DIFFERS (%d vs %d bytes)\n", label, len(code1), len(code2))
+			printByteDiff(code1, code2)
+			diffs++
+		} else {
+			fmt.Printf("%s: identical (%d bytes)\n", label, len(code1))
+		}
+	}
+	for name := range funcs2 {
+		if !matched2[name] {
+			fmt.Printf("%s: only in %s\n", name, path2)
+			diffs++
+		}
+	}
+
+	if diffs == 0 {
+		fmt.Println("all functions identical")
+		return 0
+	}
+	return 1
+}
+
+// assembleFile assembles a file and returns the image.
+func assembleFile(path string) (*asm.Image, error) {
+	src, err := readSource(path)
+	if err != nil {
+		return nil, err
+	}
+	f, errs := parser.Parse(path, src)
+	for _, e := range errs {
+		fmt.Fprintf(os.Stderr, "%s: %v\n", path, e)
+	}
+	if len(errs) > 0 {
+		return nil, fmt.Errorf("parse errors")
+	}
+	targetArch := arch.FromFilename(path)
+	if targetArch == arch.RISCV {
+		return asm.AssembleFileRISCV(f)
+	}
+	return asm.AssembleFile(f)
+}
+
+// printByteDiff shows the first few byte differences between two code blocks.
+func printByteDiff(a, b []byte) {
+	maxLen := len(a)
+	if len(b) < maxLen {
+		maxLen = len(b)
+	}
+	shown := 0
+	for i := 0; i < maxLen && shown < 8; i++ {
+		if a[i] != b[i] {
+			fmt.Printf("  offset %#04x: %02x vs %02x\n", i, a[i], b[i])
+			shown++
+		}
+	}
+	if len(a) != len(b) {
+		fmt.Printf("  length: %d vs %d\n", len(a), len(b))
+	}
+}
+
+// cmdProfile shows the basic-block structure of functions in an assembly file.
+func cmdProfile(args []string) int {
+	fs := newCommand("profile", "gasm profile <file.s>", `
+Show the basic-block structure of functions in an assembly file.
+Lists each function's labels, their offsets, and the block boundaries.
+This is the static structure; for runtime execution counts, use
+gasm verify --fuzz which exercises the code paths.
+`)
+	fs.Parse(args)
+	if fs.NArg() != 1 {
+		fmt.Fprintln(os.Stderr, "usage: gasm profile <file.s>")
+		return 2
+	}
+	path := fs.Arg(0)
+
+	// Load the file to get function metadata.
+	k, err := verify.Load(path)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm profile: %v\n", err)
+		return 1
+	}
+	defer k.Close()
+
+	for _, name := range k.FuncNames() {
+		fl, err := k.Func(name)
+		if err != nil {
+			continue
+		}
+		fmt.Printf("%s: %d bytes, args=%d, frame=%d", name, fl.Size, fl.Args, fl.Frame)
+		if fl.NoSplit {
+			fmt.Printf(" NOSPLIT")
+		}
+		fmt.Println()
+
+		// Show labels and their offsets.
+		if len(fl.Labels) > 0 {
+			fmt.Println("  labels:")
+			// Sort labels by offset.
+			type labelOff struct {
+				name string
+				off  int
+			}
+			var labels []labelOff
+			for name, off := range fl.Labels {
+				labels = append(labels, labelOff{name, off})
+			}
+			sort.Slice(labels, func(i, j int) bool { return labels[i].off < labels[j].off })
+			for _, l := range labels {
+				fmt.Printf("    %-20s +%#04x\n", l.name, l.off)
+			}
+		}
+
+		// Show basic blocks.
+		blocks, err := k.Blocks(name)
+		if err == nil && len(blocks) > 0 {
+			fmt.Printf("  basic blocks: %d\n", len(blocks))
+		}
+	}
+	return 0
+}
+
+// cmdVerifyRISCV handles the verify subcommand for RISC-V files.
+// JIT requires RISC-V hardware; only ground-truth and profile are available.
+func cmdVerifyRISCV(path string, groundTruth, profile bool) int {
+	src, err := readSource(path)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+	f, errs := parser.Parse(path, src)
+	for _, e := range errs {
+		fmt.Fprintf(os.Stderr, "%s: %v\n", path, e)
+	}
+	if len(errs) > 0 {
+		return 1
+	}
+	img, err := asm.AssembleFileRISCV(f)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+
+	if groundTruth {
+		gt, err := verify.GroundTruthRISCV(path)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm verify: ground truth: %v\n", err)
+			return 1
+		}
+		matched, total := 0, 0
+		for _, fn := range img.Funcs {
+			gasmCode := img.Code[fn.Offset : fn.Offset+fn.Size]
+			goCode, ok := gt[fn.Name]
+			if !ok {
+				fmt.Printf("  %s: SKIP (not in go tool asm output)\n", fn.Name)
+				continue
+			}
+			total++
+			gasmCmp := make([]byte, len(gasmCode))
+			goCmp := make([]byte, len(goCode))
+			copy(gasmCmp, gasmCode)
+			copy(goCmp, goCode)
+			for _, r := range fn.Relocs {
+				for j := r.Off; j < r.Off+4 && j < len(gasmCmp); j++ {
+					gasmCmp[j] = 0
+				}
+				for j := r.Off; j < r.Off+4 && j < len(goCmp); j++ {
+					goCmp[j] = 0
+				}
+			}
+			if bytes.Equal(gasmCmp, goCmp) {
+				matched++
+				if len(fn.Relocs) > 0 {
+					fmt.Printf("  %s: MATCH (%d bytes, %d relocs masked)\n", fn.Name, fn.Size, len(fn.Relocs))
+				} else {
+					fmt.Printf("  %s: MATCH (%d bytes)\n", fn.Name, fn.Size)
+				}
+			} else {
+				fmt.Printf("  %s: MISMATCH (%d vs %d bytes)\n", fn.Name, fn.Size, len(goCode))
+				for i := 0; i < len(gasmCode) || i < len(goCode); i += 16 {
+					var gb, gs string
+					for j := i; j < i+16 && j < len(gasmCode); j++ {
+						gb += fmt.Sprintf(" %02x", gasmCode[j])
+					}
+					for j := i; j < i+16 && j < len(goCode); j++ {
+						gs += fmt.Sprintf(" %02x", goCode[j])
+					}
+					fmt.Printf("    %04x: gasm:%s\n", i, gb)
+					fmt.Printf("    %04x: gt:  %s\n", i, gs)
+				}
+			}
+		}
+		fmt.Printf("%s: %d/%d matched\n", path, matched, total)
+		if matched < total {
+			return 1
+		}
+		return 0
+	}
+
+	if profile {
+		for _, fn := range img.Funcs {
+			fmt.Printf("%s: %d bytes, labels: %v\n", fn.Name, fn.Size, fn.Labels)
+		}
+		return 0
+	}
+
+	fmt.Printf("%s: %d functions assembled\n", path, len(img.Funcs))
+	for _, fn := range img.Funcs {
+		fmt.Printf("  %s: %d bytes\n", fn.Name, fn.Size)
+	}
+	return 0
+}
+
 func cmdVerify(args []string) int {
-	fs := newCommand("verify", "gasm verify <file.s>", `
+	fs := newCommand("verify", "gasm verify [-smoke] [-abi] [-fuzz] [-ground-truth] [-profile] [-call] <file.s>", `
 Assemble FILE (amd64), map it into executable memory and report the available
 functions.  This confirms the assembled image is self-consistent (no
 unresolved external symbols) and executable — the prerequisite for dynamic
@@ -481,19 +832,51 @@ testing.
 With -smoke, each NOSPLIT function is called with a zeroed argument block to
 confirm the JIT trampoline works end-to-end.  This is safe only for functions
 that tolerate nil pointers and zero lengths in their arguments.
+
+With -abi, each function is called with sentinel values in the callee-saved
+registers (BP, R14) and a red-zone canary below SP; violations are reported.
+
+With -fuzz, each function with a // func signature is differentially fuzzed
+against the go-tool-asm version in a subprocess (so a crash on a partial
+function is reported, not fatal).
+
+With -ground-truth, the assembled machine code is compared byte-for-byte
+against go tool asm (relocation sites masked), reporting any encoding drift.
+
+With -profile, the static basic-block structure is listed for each function.
+
+With -call, a single function is invoked with user-supplied buffers (-buf)
+instead of the smoke/abi/fuzz sweeps.  Useful for partial functions (e.g.
+decoders) that crash on random input but should succeed on valid data.
 `)
 	smoke := fs.Bool("smoke", false, "call each NOSPLIT function with zeroed args")
+	abi := fs.Bool("abi", false, "run ABI-checking calls (sentinel registers + red zone)")
+	abiN := fs.Int("abi-n", 100, "number of ABI check iterations with varied inputs")
+	profile := fs.Bool("profile", false, "list basic-block structure per function")
+	groundTruth := fs.Bool("ground-truth", false, "compare machine code byte-for-byte against go tool asm")
+	fuzz := fs.Bool("fuzz", false, "differential fuzz: JIT both gasm and go-tool-asm versions, compare outputs")
+	fuzzN := fs.Int("n", 1000, "number of fuzz iterations per function")
+	fuzzOne := fs.String("fuzz-one", "", "") // hidden: fuzz a single function (subprocess mode)
+	call := fs.String("call", "", "call a single function with -buf instead of the sweeps")
+	bufSpec := fs.String("buf", "", "buffer spec for -call: name:size:pattern[,name:size:pattern] (zero, ones, seq, or hex)")
+	repeat := fs.Int("repeat", 1, "number of times to repeat a -call invocation")
 	fs.Parse(args)
 	if fs.NArg() != 1 {
-		fmt.Fprintln(os.Stderr, "usage: gasm verify [-smoke] <file.s>")
+		fmt.Fprintln(os.Stderr, "usage: gasm verify [-smoke] [-abi] [-fuzz] [-ground-truth] [-profile] [-call] <file.s>")
 		return 2
 	}
 	path := fs.Arg(0)
-	if arch.FromFilename(path) != arch.AMD64 {
-		fmt.Fprintln(os.Stderr, "gasm verify: only amd64 is supported")
+	targetArch := arch.FromFilename(path)
+	if targetArch != arch.AMD64 && targetArch != arch.RISCV {
+		fmt.Fprintln(os.Stderr, "gasm verify: only amd64 and riscv64 are supported")
 		return 1
 	}
 
+	// RISC-V: ground-truth only (no JIT on non-RISC-V hosts).
+	if targetArch == arch.RISCV {
+		return cmdVerifyRISCV(path, *groundTruth, *profile)
+	}
+
 	k, err := verify.Load(path)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
@@ -504,6 +887,140 @@ that tolerate nil pointers and zero lengths in their arguments.
 	names := k.FuncNames()
 	fmt.Printf("%s: %d functions JIT-loaded\n", path, len(names))
 	rc := 0
+
+	// Single-function call mode: invoke one function with user-supplied buffers.
+	if *call != "" {
+		return cmdVerifyCall(k, path, *call, *bufSpec, *repeat)
+	}
+
+	// Subprocess mode: fuzz a single function and exit.
+	if *fuzzOne != "" {
+		gt, err := verify.GroundTruth(path)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+			return 1
+		}
+		src, err := readSource(path)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+			return 1
+		}
+		sigs := verify.ExtractSignatures(src)
+		sig, ok := sigs[*fuzzOne]
+		if !ok {
+			fmt.Printf("%s: no signature\n", *fuzzOne)
+			return 0
+		}
+		goCode, ok := gt[*fuzzOne]
+		if !ok {
+			fmt.Printf("%s: not in go tool asm\n", *fuzzOne)
+			return 0
+		}
+		res := k.FuzzFunc(*fuzzOne, sig, goCode, *fuzzN, 42)
+		fmt.Printf("%s\n", res)
+		if !res.OK() {
+			return 1
+		}
+		return 0
+	}
+
+	// Ground-truth comparison: assemble with go tool asm and compare bytes.
+	if *groundTruth {
+		gt, err := verify.GroundTruth(path)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm verify: ground truth: %v\n", err)
+			return 1
+		}
+		matched, total := 0, 0
+		for _, name := range names {
+			fl, _ := k.Func(name)
+			gasmCode := k.Image().Code[fl.Offset : fl.Offset+fl.Size]
+			goCode, ok := gt[name]
+			if !ok {
+				fmt.Printf("  %s: SKIP (not in go tool asm output)\n", name)
+				continue
+			}
+			total++
+			// Compare, masking relocation sites (disp32 fields that the
+			// Go linker fills at link time — gasm resolves them internally).
+			gasmCmp := make([]byte, len(gasmCode))
+			goCmp := make([]byte, len(goCode))
+			copy(gasmCmp, gasmCode)
+			copy(goCmp, goCode)
+			for _, r := range fl.Relocs {
+				for j := r.Off; j < r.Off+4 && j < len(gasmCmp); j++ {
+					gasmCmp[j] = 0
+				}
+				for j := r.Off; j < r.Off+4 && j < len(goCmp); j++ {
+					goCmp[j] = 0
+				}
+			}
+			if bytes.Equal(gasmCmp, goCmp) {
+				matched++
+				if len(fl.Relocs) > 0 {
+					fmt.Printf("  %s: MATCH (%d bytes, %d relocs masked)\n", name, fl.Size, len(fl.Relocs))
+				} else {
+					fmt.Printf("  %s: MATCH (%d bytes)\n", name, fl.Size)
+				}
+			} else {
+				fmt.Printf("  %s: MISMATCH (gasm %d bytes, go %d bytes)\n", name, fl.Size, len(goCode))
+				for i := 0; i < len(gasmCmp) && i < len(goCmp); i++ {
+					if gasmCmp[i] != goCmp[i] {
+						fmt.Printf("    first diff at byte %d: gasm=%02x go=%02x\n", i, gasmCmp[i], goCmp[i])
+						break
+					}
+				}
+				rc = 1
+			}
+		}
+		fmt.Printf("ground truth: %d/%d functions byte-identical\n", matched, total)
+		if matched < total {
+			rc = 1
+		}
+	}
+
+	// Differential fuzz: JIT both gasm and go-tool-asm, compare outputs.
+	// Each function runs in a subprocess so a crash (partial functions like
+	// decoders that fault on malformed input) doesn't kill the whole run.
+	if *fuzz {
+		gt, err := verify.GroundTruth(path)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm verify: fuzz: %v\n", err)
+			return 1
+		}
+		src, err := readSource(path)
+		if err != nil {
+			fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+			return 1
+		}
+		sigs := verify.ExtractSignatures(src)
+		fuzzed := 0
+		for _, name := range names {
+			sig, ok := sigs[name]
+			if !ok {
+				fmt.Printf("  %s: SKIP (no // func signature)\n", name)
+				continue
+			}
+			goCode, ok := gt[name]
+			if !ok {
+				fmt.Printf("  %s: SKIP (not in go tool asm output)\n", name)
+				continue
+			}
+			// Run in a subprocess: if the function crashes on random
+			// input (partial function), we report it and move on.
+			res := fuzzInSubprocess(path, name, *fuzzN)
+			if res != "" {
+				fmt.Printf("  %s\n", res)
+				if strings.Contains(res, "MISMATCH") {
+					rc = 1
+				}
+			}
+			_ = sig
+			_ = goCode
+			fuzzed++
+		}
+		fmt.Printf("fuzz: %d functions tested, %d iterations each\n", fuzzed, *fuzzN)
+	}
 	for _, name := range names {
 		fl, _ := k.Func(name)
 		flags := ""
@@ -511,6 +1028,16 @@ that tolerate nil pointers and zero lengths in their arguments.
 			flags = " NOSPLIT"
 		}
 		fmt.Printf("  %s: %d bytes, args=%d, frame=%d%s\n", name, fl.Size, fl.Args, fl.Frame, flags)
+
+		if *profile {
+			blocks, err := k.Blocks(name)
+			if err != nil {
+				fmt.Printf("    profile: %v\n", err)
+			} else {
+				fmt.Printf("    blocks: %d\n", len(blocks))
+			}
+		}
+
 		if *smoke && fl.NoSplit {
 			args := make([]byte, fl.Args)
 			_, err := k.CallFunc(name, args)
@@ -521,6 +1048,188 @@ that tolerate nil pointers and zero lengths in their arguments.
 				fmt.Printf("    smoke: OK\n")
 			}
 		}
+
+		if *abi && fl.NoSplit {
+			// Try varied-input ABI fuzzing first.
+			if src, err := readSource(path); err == nil {
+				result := k.FuzzFuncCheckedByName(name, src, *abiN, int64(*abiN))
+				if result.Mismatches > 0 {
+					fmt.Printf("    abi: %s\n", result)
+					rc = 1
+				} else {
+					fmt.Printf("    abi: clean (%d varied inputs)\n", result.Matches)
+				}
+			} else {
+				// Fallback: single zeroed-arg call.
+				args := make([]byte, fl.Args)
+				_, report, err := k.CallFuncChecked(name, args)
+				if err != nil {
+					fmt.Printf("    abi: FAIL — %v\n", err)
+					rc = 1
+				} else if !report.OK() {
+					fmt.Printf("    abi: %s\n", report)
+					rc = 1
+				} else {
+					fmt.Printf("    abi: clean\n")
+				}
+			}
+		}
 	}
 	return rc
 }
+
+// fuzzInSubprocess runs the fuzz for a single function in a child process.
+// If the child is killed by a signal (e.g. SIGSEGV from a partial function
+// faulting on random input), it returns a CRASH report instead of dying.
+func fuzzInSubprocess(path, funcName string, n int) string {
+	self, err := os.Executable()
+	if err != nil {
+		return fmt.Sprintf("%s: cannot find self: %v", funcName, err)
+	}
+	cmd := exec.Command(self, "verify", "--fuzz-one="+funcName, "-n", strconv.Itoa(n), path)
+	out, err := cmd.CombinedOutput()
+	if err != nil {
+		// Check if the child was killed by a signal.
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			ws := exitErr.Sys().(syscall.WaitStatus)
+			if ws.Signaled() {
+				return fmt.Sprintf("%s: CRASH (%v — partial function, use --ground-truth)", funcName, ws.Signal())
+			}
+		}
+		// Non-zero exit without a signal: the fuzz reported mismatches.
+		lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+		for _, l := range lines {
+			if strings.Contains(l, funcName) {
+				return strings.TrimSpace(l)
+			}
+		}
+		return fmt.Sprintf("%s: FAIL (exit %v)", funcName, err)
+	}
+	// Success: extract the result line.
+	lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+	for _, l := range lines {
+		if strings.Contains(l, funcName) {
+			return strings.TrimSpace(l)
+		}
+	}
+	return strings.TrimSpace(string(out))
+}
+
+// cmdVerifyCall implements `gasm verify --call <func> [--buf spec] [--repeat n]`.
+// It invokes a single function with user-supplied buffers and prints the arg
+// block before and after the call, so the user can inspect return values and
+// any output written to the buffers.
+func cmdVerifyCall(k *verify.Kernel, path, funcName, bufSpec string, repeat int) int {
+	fl, err := k.Func(funcName)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+	if !fl.NoSplit {
+		fmt.Fprintf(os.Stderr, "gasm verify: %s is not NOSPLIT (frame=%d); --call supports NOSPLIT functions only\n", funcName, fl.Frame)
+		return 1
+	}
+
+	// Parse the // func signature to lay out the argument block.
+	src, err := readSource(path)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+	sig, ok := verify.ExtractFuncSig(src, funcName)
+	if !ok {
+		fmt.Fprintf(os.Stderr, "gasm verify: no // func signature found for %s\n", funcName)
+		return 1
+	}
+	layout := verify.ArgLayout(sig)
+
+	// Allocate the requested buffers (if any) and build the arg block.
+	specs, err := verify.ParseBufSpec(bufSpec)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+	var pool verify.BufPool
+	if err := pool.Alloc(specs); err != nil {
+		fmt.Fprintf(os.Stderr, "gasm verify: %v\n", err)
+		return 1
+	}
+	defer pool.Close()
+	args := pool.BuildArgs(layout, fl.Args)
+
+	fmt.Printf("%s: %d bytes, args=%d\n", funcName, fl.Size, fl.Args)
+	fmt.Printf("  signature: func %s(%s) %s\n", sig.Name, formatParams(sig.Params), formatResults(sig.Results))
+	if len(specs) > 0 {
+		fmt.Printf("  buffers:\n")
+		for _, s := range specs {
+			fmt.Printf("    %s: %d bytes, pattern=%s\n", s.Name, s.Size, s.Pattern)
+		}
+	}
+	fmt.Printf("  args before: %s\n", hexDump(args))
+
+	rc := 0
+	for i := 0; i < repeat; i++ {
+		out, err := k.CallFunc(funcName, args)
+		if err != nil {
+			fmt.Printf("  call %d: FAIL — %v\n", i+1, err)
+			rc = 1
+			continue
+		}
+		if repeat == 1 {
+			fmt.Printf("  args after:  %s\n", hexDump(out))
+		} else if i == repeat-1 {
+			fmt.Printf("  args after %d calls: %s\n", repeat, hexDump(out))
+		}
+		fmt.Printf("  call %d: OK\n", i+1)
+	}
+	return rc
+}
+
+// formatParams renders a parameter list as "a []byte, b []byte".
+func formatParams(ps []verify.Param) string {
+	var parts []string
+	for _, p := range ps {
+		if p.Name != "" {
+			parts = append(parts, p.Name+" "+p.Typ)
+		} else {
+			parts = append(parts, p.Typ)
+		}
+	}
+	return strings.Join(parts, ", ")
+}
+
+// formatResults renders a result list as "(n int, code int)" or "int".
+func formatResults(rs []verify.Param) string {
+	if len(rs) == 0 {
+		return ""
+	}
+	if len(rs) == 1 && rs[0].Name == "" {
+		return rs[0].Typ
+	}
+	return "(" + formatParams(rs) + ")"
+}
+
+// hexDump returns a one-line hex dump of buf, truncated to 64 bytes.
+func hexDump(buf []byte) string {
+	const max = 64
+	n := len(buf)
+	if n > max {
+		n = max
+	}
+	var sb strings.Builder
+	for i := 0; i < n; i++ {
+		if i > 0 {
+			sb.WriteByte(' ')
+		}
+		fmt.Fprintf(&sb, "%02x", buf[i])
+	}
+	return fmt.Sprintf("%s%s (%d bytes)", sb.String(), truncMark(len(buf), max), len(buf))
+}
+
+// truncMark returns "…" when the buffer is longer than max, else "".
+func truncMark(n, max int) string {
+	if n > max {
+		return "…"
+	}
+	return ""
+}

debug/breakpoint.go

@@ -0,0 +1,248 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package debug
+
+import "fmt"
+
+// Breakpoint is one INT3 breakpoint in the debuggee.
+type Breakpoint struct {
+	Addr    uint64 // absolute address in the debuggee
+	Label   string // source label ("" for raw addresses)
+	Orig    byte   // original byte at Addr (restored on removal)
+	Enabled bool
+	Cond    *Condition // optional condition (nil = unconditional)
+	hits    int
+}
+
+// Condition is a simple register-comparison condition evaluated when a
+// breakpoint is hit.  Format: <reg> <op> <value>.
+type Condition struct {
+	Reg   string // register name (rax, rbx, rip, rsp, ...)
+	Op    string // comparison operator: ==, !=, <, >, <=, >=
+	Value uint64
+}
+
+// Eval checks the condition against the current registers.
+func (c *Condition) Eval(regs *Regs) bool {
+	var actual uint64
+	switch c.Reg {
+	case "rax", "eax", "ax", "al":
+		actual = regs.RAX
+	case "rbx", "ebx", "bx", "bl":
+		actual = regs.RBX
+	case "rcx", "ecx", "cx", "cl":
+		actual = regs.RCX
+	case "rdx", "edx", "dx", "dl":
+		actual = regs.RDX
+	case "rsi", "esi", "si":
+		actual = regs.RSI
+	case "rdi", "edi", "di":
+		actual = regs.RDI
+	case "rbp", "ebp", "bp":
+		actual = regs.RBP
+	case "rsp", "esp", "sp":
+		actual = regs.RSP
+	case "r8":
+		actual = regs.R8
+	case "r9":
+		actual = regs.R9
+	case "r10":
+		actual = regs.R10
+	case "r11":
+		actual = regs.R11
+	case "r12":
+		actual = regs.R12
+	case "r13":
+		actual = regs.R13
+	case "r14":
+		actual = regs.R14
+	case "r15":
+		actual = regs.R15
+	case "rip", "eip":
+		actual = regs.RIP
+	default:
+		return true // unknown register — don't block
+	}
+	switch c.Op {
+	case "==", "=":
+		return actual == c.Value
+	case "!=":
+		return actual != c.Value
+	case "<":
+		return actual < c.Value
+	case ">":
+		return actual > c.Value
+	case "<=":
+		return actual <= c.Value
+	case ">=":
+		return actual >= c.Value
+	default:
+		return true
+	}
+}
+
+// Breakpoints manages the set of breakpoints for a Session.
+// Breakpoints manages software breakpoints for a debuggee.
+type Breakpoints struct {
+	t   tracer
+	bps map[uint64]*Breakpoint
+}
+
+// NewBreakpoints creates a new breakpoint manager.
+func NewBreakpoints(t tracer) *Breakpoints {
+	return &Breakpoints{t: t, bps: make(map[uint64]*Breakpoint)}
+}
+
+// Set installs a breakpoint at addr (replaces any existing one).
+func (bm *Breakpoints) Set(addr uint64, label string) (*Breakpoint, error) {
+	return bm.SetWithCond(addr, label, nil)
+}
+
+// SetWithCond installs a breakpoint with an optional condition.
+func (bm *Breakpoints) SetWithCond(addr uint64, label string, cond *Condition) (*Breakpoint, error) {
+	if bp, ok := bm.bps[addr]; ok {
+		bp.Enabled = true
+		bp.Cond = cond
+		return bp, nil
+	}
+	// Read the original byte.
+	word, err := bm.t.Peek(addr)
+	if err != nil {
+		return nil, err
+	}
+	orig := byte(word)
+	// Patch with INT3 (0xCC), preserving the rest of the word.
+	patched := (word &^ 0xFF) | 0xCC
+	if err := bm.t.Poke(addr, patched); err != nil {
+		return nil, err
+	}
+	bp := &Breakpoint{Addr: addr, Label: label, Orig: orig, Enabled: true, Cond: cond}
+	bm.bps[addr] = bp
+	return bp, nil
+}
+
+// Hits returns the number of times the breakpoint has been hit.
+func (bp *Breakpoint) Hits() int {
+	return bp.hits
+}
+
+// Info returns a formatted list of all breakpoints.
+func (bm *Breakpoints) Info() string {
+	if len(bm.bps) == 0 {
+		return "no breakpoints set\n"
+	}
+	result := ""
+	i := 0
+	for _, bp := range bm.bps {
+		i++
+		status := "enabled"
+		if !bp.Enabled {
+			status = "disabled"
+		}
+		label := bp.Label
+		if label == "" {
+			label = fmt.Sprintf("%#x", bp.Addr)
+		}
+		cond := ""
+		if bp.Cond != nil {
+			cond = fmt.Sprintf(" if %s %s %#x", bp.Cond.Reg, bp.Cond.Op, bp.Cond.Value)
+		}
+		result += fmt.Sprintf("  %d: %s at %#x [%s, %d hits]%s\n", i, label, bp.Addr, status, bp.hits, cond)
+	}
+	return result
+}
+
+// Clear removes the breakpoint at addr, restoring the original byte.
+func (bm *Breakpoints) Clear(addr uint64) error {
+	bp, ok := bm.bps[addr]
+	if !ok {
+		return fmt.Errorf("debug: no breakpoint at %#x", addr)
+	}
+	word, err := bm.t.Peek(addr)
+	if err != nil {
+		return err
+	}
+	restored := (word &^ 0xFF) | uint64(bp.Orig)
+	if err := bm.t.Poke(addr, restored); err != nil {
+		return err
+	}
+	delete(bm.bps, addr)
+	return nil
+}
+
+// ClearAll removes all breakpoints.
+func (bm *Breakpoints) ClearAll() error {
+	for addr := range bm.bps {
+		if err := bm.Clear(addr); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// At returns the breakpoint at addr, if any.
+func (bm *Breakpoints) At(addr uint64) *Breakpoint {
+	return bm.bps[addr]
+}
+
+// All returns all breakpoints.
+func (bm *Breakpoints) All() []*Breakpoint {
+	out := make([]*Breakpoint, 0, len(bm.bps))
+	for _, bp := range bm.bps {
+		out = append(out, bp)
+	}
+	return out
+}
+
+// HandleTrap is called after the debuggee stops on SIGTRAP.  It checks
+// whether the trap was caused by one of our breakpoints (RIP-1 matches
+// a breakpoint address), restores the original byte, rewinds RIP, and
+// returns the breakpoint that was hit (or nil if it was a single-step).
+func (bm *Breakpoints) HandleTrap(regs *Regs) *Breakpoint {
+	// After INT3, RIP points to the byte AFTER the 0xCC.
+	trapAddr := regs.RIP - 1
+	bp, ok := bm.bps[trapAddr]
+	if !ok || !bp.Enabled {
+		return nil // single-step trap or unknown
+	}
+	// Check the condition (if any).
+	if bp.Cond != nil && !bp.Cond.Eval(regs) {
+		// Condition not met — restore the byte but do NOT rewind RIP.
+		// The process continues from the next instruction (past the INT3).
+		word, err := bm.t.Peek(trapAddr)
+		if err == nil {
+			restored := (word &^ 0xFF) | uint64(bp.Orig)
+			bm.t.Poke(trapAddr, restored)
+		}
+		// RIP is already past the INT3 (trapAddr + 1). Don't rewind.
+		return nil
+	}
+	bp.hits++
+	// Restore the original byte.
+	word, err := bm.t.Peek(trapAddr)
+	if err == nil {
+		restored := (word &^ 0xFF) | uint64(bp.Orig)
+		bm.t.Poke(trapAddr, restored)
+	}
+	// Rewind RIP to re-execute the original instruction.
+	regs.RIP = trapAddr
+	bm.t.SetRegs(regs)
+	return bp
+}
+
+// Reinsert re-inserts the breakpoint at addr after a single-step past it.
+// Called after Step() when we want the breakpoint to fire again on the
+// next Continue().
+func (bm *Breakpoints) Reinsert(addr uint64) error {
+	bp, ok := bm.bps[addr]
+	if !ok || !bp.Enabled {
+		return nil
+	}
+	word, err := bm.t.Peek(addr)
+	if err != nil {
+		return err
+	}
+	patched := (word &^ 0xFF) | 0xCC
+	return bm.t.Poke(addr, patched)
+}

debug/debug_test.go

@@ -0,0 +1,273 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package debug
+
+import (
+	"strings"
+	"testing"
+)
+
+func TestConditionEval(t *testing.T) {
+	regs := &Regs{
+		RAX: 42,
+		RBX: 0,
+		RCX: 100,
+		RIP: 0x1000,
+		RSP: 0x2000,
+		R8:  8,
+		R15: 15,
+	}
+
+	tests := []struct {
+		cond Condition
+		want bool
+	}{
+		{Condition{Reg: "rax", Op: "==", Value: 42}, true},
+		{Condition{Reg: "rax", Op: "==", Value: 43}, false},
+		{Condition{Reg: "rax", Op: "!=", Value: 43}, true},
+		{Condition{Reg: "rax", Op: "!=", Value: 42}, false},
+		{Condition{Reg: "rax", Op: "<", Value: 50}, true},
+		{Condition{Reg: "rax", Op: "<", Value: 40}, false},
+		{Condition{Reg: "rax", Op: ">", Value: 40}, true},
+		{Condition{Reg: "rax", Op: ">", Value: 50}, false},
+		{Condition{Reg: "rax", Op: "<=", Value: 42}, true},
+		{Condition{Reg: "rax", Op: ">=", Value: 42}, true},
+		{Condition{Reg: "rbx", Op: "==", Value: 0}, true},
+		{Condition{Reg: "rcx", Op: ">", Value: 50}, true},
+		{Condition{Reg: "rip", Op: "==", Value: 0x1000}, true},
+		{Condition{Reg: "rsp", Op: ">", Value: 0x1000}, true},
+		{Condition{Reg: "r8", Op: "==", Value: 8}, true},
+		{Condition{Reg: "r15", Op: "==", Value: 15}, true},
+		{Condition{Reg: "eax", Op: "==", Value: 42}, true},    // 32-bit alias
+		{Condition{Reg: "ax", Op: "==", Value: 42}, true},     // 16-bit alias
+		{Condition{Reg: "unknown", Op: "==", Value: 0}, true}, // unknown reg → don't block
+		{Condition{Reg: "rax", Op: "??", Value: 0}, true},     // unknown op → don't block
+	}
+
+	for _, tt := range tests {
+		got := tt.cond.Eval(regs)
+		if got != tt.want {
+			t.Errorf("Condition{%q %q %d}.Eval() = %v, want %v",
+				tt.cond.Reg, tt.cond.Op, tt.cond.Value, got, tt.want)
+		}
+	}
+}
+
+func TestLineAt(t *testing.T) {
+	lines := []SourceLine{
+		{Offset: 0, Line: 5},
+		{Offset: 5, Line: 6},
+		{Offset: 10, Line: 7},
+		{Offset: 15, Line: 8},
+	}
+
+	tests := []struct {
+		offset int
+		want   int
+	}{
+		{0, 5},
+		{1, 5},
+		{4, 5},
+		{5, 6},
+		{7, 6},
+		{10, 7},
+		{12, 7},
+		{15, 8},
+		{20, 8},
+	}
+
+	for _, tt := range tests {
+		got := lineAt(lines, tt.offset)
+		if got != tt.want {
+			t.Errorf("lineAt(lines, %d) = %d, want %d", tt.offset, got, tt.want)
+		}
+	}
+
+	// Empty table.
+	if lineAt(nil, 5) != 0 {
+		t.Error("lineAt(nil, 5) should return 0")
+	}
+}
+
+func TestOffsetForLine(t *testing.T) {
+	lines := []SourceLine{
+		{Offset: 0, Line: 5},
+		{Offset: 5, Line: 6},
+		{Offset: 10, Line: 7},
+	}
+
+	tests := []struct {
+		line int
+		want int
+	}{
+		{5, 0},
+		{6, 5},
+		{7, 10},
+		{99, -1}, // not found
+		{0, -1},  // not found
+	}
+
+	for _, tt := range tests {
+		got := offsetForLine(lines, tt.line)
+		if got != tt.want {
+			t.Errorf("offsetForLine(lines, %d) = %d, want %d", tt.line, got, tt.want)
+		}
+	}
+}
+
+func TestDecodeRflags(t *testing.T) {
+	tests := []struct {
+		flags uint64
+		want  string
+	}{
+		{0x202, "IF"},                   // only IF set (bit 9)
+		{0x246, "PF ZF IF"},             // PF(2) + ZF(6) + IF(9)
+		{0x001, "CF"},                   // carry flag
+		{0x080, "SF"},                   // sign flag
+		{0x800, "OF"},                   // overflow flag
+		{0x000, "none"},                 // no flags
+		{0x202 | 0x001, "CF IF"},        // CF + IF
+		{0x3F7, "CF PF AF ZF SF TF IF"}, // all arithmetic flags
+	}
+
+	for _, tt := range tests {
+		got := decodeRflags(tt.flags)
+		if got != tt.want {
+			t.Errorf("decodeRflags(%#x) = %q, want %q", tt.flags, got, tt.want)
+		}
+	}
+}
+
+func TestNearestLabel(t *testing.T) {
+	labels := []Label{
+		{Name: "start", Offset: 0},
+		{Name: "loop", Offset: 10},
+		{Name: "done", Offset: 20},
+	}
+
+	tests := []struct {
+		offset int
+		want   string
+	}{
+		{0, "start"},
+		{5, "start"},
+		{10, "loop"},
+		{15, "loop"},
+		{20, "done"},
+		{25, "done"},
+	}
+
+	for _, tt := range tests {
+		got := nearestLabel(labels, tt.offset)
+		if got != tt.want {
+			t.Errorf("nearestLabel(labels, %d) = %q, want %q", tt.offset, got, tt.want)
+		}
+	}
+}
+
+func TestBreakpointsSetAndClear(t *testing.T) {
+	tr := newMockTracer()
+	bm := NewBreakpoints(tr)
+
+	// Set a breakpoint at address 0x1000.
+	bp, err := bm.Set(0x1000, "test")
+	if err != nil {
+		t.Fatalf("Set: %v", err)
+	}
+	if !bp.Enabled {
+		t.Error("breakpoint not enabled")
+	}
+	if bp.Label != "test" {
+		t.Errorf("label = %q, want test", bp.Label)
+	}
+
+	// Verify Peek was called.
+	if len(tr.peeks) != 1 || tr.peeks[0] != 0x1000 {
+		t.Errorf("peeks = %v, want [0x1000]", tr.peeks)
+	}
+
+	// Verify Poke wrote INT3.
+	if len(tr.pokes) != 1 || tr.pokes[0].addr != 0x1000 {
+		t.Errorf("pokes = %v", tr.pokes)
+	}
+
+	// At should find it.
+	if bm.At(0x1000) == nil {
+		t.Error("At(0x1000) returned nil")
+	}
+
+	// All should return it.
+	all := bm.All()
+	if len(all) != 1 {
+		t.Errorf("All() = %d breakpoints, want 1", len(all))
+	}
+
+	// Clear it.
+	if err := bm.Clear(0x1000); err != nil {
+		t.Fatalf("Clear: %v", err)
+	}
+	if bm.At(0x1000) != nil {
+		t.Error("At(0x1000) after Clear should be nil")
+	}
+}
+
+func TestBreakpointsSetWithCond(t *testing.T) {
+	tr := newMockTracer()
+	bm := NewBreakpoints(tr)
+
+	cond := &Condition{Reg: "rax", Op: "==", Value: 42}
+	bp, err := bm.SetWithCond(0x2000, "cond_test", cond)
+	if err != nil {
+		t.Fatalf("SetWithCond: %v", err)
+	}
+	if bp.Cond == nil || bp.Cond.Value != 42 {
+		t.Error("condition not set")
+	}
+
+	// Re-setting the same address should update the condition.
+	cond2 := &Condition{Reg: "rbx", Op: "<", Value: 100}
+	bp2, err := bm.SetWithCond(0x2000, "cond_test2", cond2)
+	if err != nil {
+		t.Fatalf("SetWithCond (update): %v", err)
+	}
+	if bp2.Cond.Value != 100 {
+		t.Error("condition not updated")
+	}
+	// Should have only 1 Peek (first Set), second is update (no Peek needed).
+	if len(tr.peeks) != 1 {
+		t.Errorf("expected 1 Peek, got %d", len(tr.peeks))
+	}
+}
+
+func TestBreakpointsClearAll(t *testing.T) {
+	tr := newMockTracer()
+	bm := NewBreakpoints(tr)
+
+	bm.Set(0x1000, "a")
+	bm.Set(0x2000, "b")
+	bm.Set(0x3000, "c")
+
+	if len(bm.All()) != 3 {
+		t.Fatalf("expected 3 breakpoints, got %d", len(bm.All()))
+	}
+
+	bm.ClearAll()
+	if len(bm.All()) != 0 {
+		t.Errorf("ClearAll: expected 0 breakpoints, got %d", len(bm.All()))
+	}
+}
+
+func TestBreakpointInfo(t *testing.T) {
+	tr := newMockTracer()
+	bm := NewBreakpoints(tr)
+	bm.Set(0x4000, "info_test")
+
+	info := bm.Info()
+	if info == "" {
+		t.Error("Info returned empty string")
+	}
+	if !strings.Contains(info, "info_test") {
+		t.Errorf("Info %q does not contain label", info)
+	}
+}

debug/disasm_linux_amd64.go

@@ -0,0 +1,52 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && amd64
+
+package debug
+
+import (
+	"fmt"
+
+	"golang.org/x/arch/x86/x86asm"
+)
+
+// Disassemble decodes the instruction at the given address in the debuggee's
+// memory and returns its text representation and length in bytes.
+func (s *Session) Disassemble(addr uint64) (string, int, error) {
+	// Read up to 15 bytes (max x86 instruction length).
+	mem, err := s.ReadMemory(addr, 15)
+	if err != nil {
+		// Try a shorter read if we're near a page boundary.
+		mem, err = s.ReadMemory(addr, 1)
+		if err != nil {
+			return "", 0, err
+		}
+	}
+	inst, err := x86asm.Decode(mem, 64)
+	if err != nil {
+		return "???", 1, nil
+	}
+	text := x86asm.IntelSyntax(inst, addr, nil)
+	return text, inst.Len, nil
+}
+
+// DisassembleN decodes up to n instructions starting at addr and returns
+// them as a formatted string with addresses and byte offsets.
+func (s *Session) DisassembleN(addr uint64, n int) string {
+	var result string
+	pc := addr
+	for i := 0; i < n; i++ {
+		text, length, err := s.Disassemble(pc)
+		if err != nil {
+			result += fmt.Sprintf("  %#08x: <error: %v>\n", pc, err)
+			break
+		}
+		result += fmt.Sprintf("  %#08x: %s\n", pc, text)
+		if length == 0 {
+			length = 1
+		}
+		pc += uint64(length)
+	}
+	return result
+}

debug/ptrace_linux_amd64.go

@@ -0,0 +1,411 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && amd64
+
+// Package debug implements the interactive debugger for gasm (Phase 4):
+// single-stepping, breakpoints, register and memory inspection for
+// JIT-assembled Plan 9 amd64 functions, controlled via ptrace.
+package debug
+
+import (
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"syscall"
+	"time"
+	"unsafe"
+)
+
+// Session is a ptrace debugging session controlling one debuggee process.
+type Session struct {
+	pid      int
+	cmd      *exec.Cmd
+	stopped  bool
+	exited   bool
+	codeBase uint64 // base address of the JIT code in the debuggee
+}
+
+// Launch starts the debuggee subprocess (gasm debug --target ...) and
+// attaches to it via ptrace.  The debuggee assembles the file, maps the
+// JIT code, calls PTRACE_TRACEME and raises SIGSTOP; Launch waits for
+// that initial stop and returns a ready Session.
+func Launch(gasmBin, asmPath, funcName string, args []byte) (*Session, error) {
+	sess, _, err := LaunchWithBuffers(gasmBin, asmPath, funcName, args, "")
+	return sess, err
+}
+
+// LaunchWithBuffers is like Launch but also allocates buffers in the debuggee
+// based on the buffer specification.  Returns the Session and the buffer
+// addresses (in the order they appear in the spec).
+func LaunchWithBuffers(gasmBin, asmPath, funcName string, args []byte, bufSpec string) (*Session, []uint64, error) {
+	self, err := os.Executable()
+	if err != nil {
+		return nil, nil, fmt.Errorf("debug: cannot find gasm binary: %w", err)
+	}
+	if gasmBin != "" {
+		self = gasmBin
+	}
+
+	// Write the arg block to a temp file (the child reads it).
+	tmpDir, err := os.MkdirTemp("", "gasm-debug-*")
+	if err != nil {
+		return nil, nil, fmt.Errorf("debug: tempdir: %w", err)
+	}
+	argsFile := filepath.Join(tmpDir, "args.bin")
+	if err := os.WriteFile(argsFile, args, 0o644); err != nil {
+		os.RemoveAll(tmpDir)
+		return nil, nil, fmt.Errorf("debug: write args: %w", err)
+	}
+
+	// Write the buffer spec if present.
+	if bufSpec != "" {
+		if err := os.WriteFile(filepath.Join(tmpDir, "bufspec"), []byte(bufSpec), 0o644); err != nil {
+			os.RemoveAll(tmpDir)
+			return nil, nil, fmt.Errorf("debug: write bufspec: %w", err)
+		}
+	}
+
+	cmd := exec.Command(self, "debug", "--target", "--func", funcName, "--args", argsFile, asmPath)
+	cmd.Env = append(os.Environ(), "GASM_DEBUG_TMP="+tmpDir)
+	cmd.Stdout = nil // output goes to the debugger, not the terminal
+	cmd.Stderr = os.Stderr
+	cmd.SysProcAttr = &syscall.SysProcAttr{}
+
+	if err := cmd.Start(); err != nil {
+		os.RemoveAll(tmpDir)
+		return nil, nil, fmt.Errorf("debug: start debuggee: %w", err)
+	}
+
+	s := &Session{pid: cmd.Process.Pid, cmd: cmd}
+
+	// Wait for the child to signal readiness and stop.  The child calls
+	// PTRACE_TRACEME then SIGSTOP, so Wait4 with WUNTRACED observes the
+	// ptrace-stop directly (no PTRACE_ATTACH needed).
+	readyFile := filepath.Join(tmpDir, "ready")
+	for i := 0; i < 500; i++ {
+		if _, err := os.Stat(readyFile); err == nil {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	var ws syscall.WaitStatus
+	if _, err := syscall.Wait4(s.pid, &ws, syscall.WUNTRACED, nil); err != nil {
+		cmd.Process.Kill()
+		os.RemoveAll(tmpDir)
+		return nil, nil, fmt.Errorf("debug: wait for stop: %w", err)
+	}
+
+	// Wait for the debuggee to reach the function entry point.
+	entryFile := filepath.Join(tmpDir, "entry")
+	for i := 0; i < 500; i++ {
+		if _, err := os.Stat(entryFile); err == nil {
+			break
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+
+	// Continue the debuggee to the entry point.
+	if err := s.Continue(); err != nil {
+		return nil, nil, fmt.Errorf("debug: continue to entry: %w", err)
+	}
+
+	// Wait for the entry stop.
+	if _, err := syscall.Wait4(s.pid, &ws, syscall.WUNTRACED, nil); err != nil {
+		return nil, nil, fmt.Errorf("debug: wait for entry: %w", err)
+	}
+
+	s.stopped = true
+
+	// Read the code base from /proc/pid/maps (find the RWX mapping).
+	s.codeBase = findRWXMapping(s.pid)
+	if s.codeBase == 0 {
+		// Fallback: try the file the child wrote.
+		baseFile := filepath.Join(tmpDir, "codebase")
+		if data, err := os.ReadFile(baseFile); err == nil {
+			fmt.Sscanf(string(data), "%d", &s.codeBase)
+		}
+	}
+
+	// Read buffer addresses if buffers were allocated.
+	var bufAddrs []uint64
+	if bufSpec != "" {
+		addrFile := filepath.Join(tmpDir, "bufaddrs")
+		if data, err := os.ReadFile(addrFile); err == nil {
+			for _, line := range strings.Split(strings.TrimSpace(string(data)), "\n") {
+				var addr uint64
+				if _, err := fmt.Sscanf(line, "%d", &addr); err == nil {
+					bufAddrs = append(bufAddrs, addr)
+				}
+			}
+		}
+	}
+
+	return s, bufAddrs, nil
+}
+
+// wait waits for the debuggee to stop and returns the wait status.
+func (s *Session) wait() error {
+	var ws syscall.WaitStatus
+	_, err := syscall.Wait4(s.pid, &ws, 0, nil)
+	if err != nil {
+		return err
+	}
+	if ws.Exited() {
+		s.exited = true
+		return fmt.Errorf("debuggee exited with status %d", ws.ExitStatus())
+	}
+	s.stopped = true
+	return nil
+}
+
+// GetRegs reads the general-purpose registers of the stopped debuggee.
+func (s *Session) GetRegs() (Regs, error) {
+	var regs Regs
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETREGS),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(&regs)),
+		0, 0,
+	)
+	if errno != 0 {
+		return regs, fmt.Errorf("debug: PTRACE_GETREGS: %w", errno)
+	}
+	return regs, nil
+}
+
+// SetRegs writes the general-purpose registers of the stopped debuggee.
+func (s *Session) SetRegs(regs *Regs) error {
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_SETREGS),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(regs)),
+		0, 0,
+	)
+	if errno != 0 {
+		return fmt.Errorf("debug: PTRACE_SETREGS: %w", errno)
+	}
+	return nil
+}
+
+// FPRegs holds the x87 FPU and SSE (XMM) register state from PTRACE_GETFPREGS.
+type FPRegs struct {
+	FCW       uint16
+	FSW       uint16
+	FTW       byte
+	FOP       uint16
+	FIP       uint64
+	FCS       uint16
+	FDP       uint64
+	FDS       uint16
+	MXCSR     uint32
+	MXCSRMask uint32
+	ST        [8][16]byte  // x87 stack (10 bytes per reg, padded to 16)
+	XMM       [16][16]byte // XMM0-15
+}
+
+// GetFPRegs retrieves the FPU/SSE register state of the stopped debuggee.
+func (s *Session) GetFPRegs() (FPRegs, error) {
+	var fp FPRegs
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETFPREGS),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(&fp)),
+		0, 0,
+	)
+	if errno != 0 {
+		return fp, fmt.Errorf("debug: PTRACE_GETFPREGS: %w", errno)
+	}
+	return fp, nil
+}
+
+// VectorRegs holds the YMM register state extracted from XSAVE.
+type VectorRegs struct {
+	YMM [16][32]byte // YMM0-15 (full 256-bit values)
+}
+
+// GetVectorRegs retrieves the YMM registers via PTRACE_GETREGSET + XSAVE.
+// Falls back to XMM if XSAVE is unavailable.
+func (s *Session) GetVectorRegs() (VectorRegs, error) {
+	var v VectorRegs
+	fp, err := s.GetFPRegs()
+	if err != nil {
+		return v, err
+	}
+	// PTRACE_GETFPREGS gives XMM registers (lower 128 bits).
+	// For YMM we'd need XSAVE; for now, copy XMM and zero the upper half.
+	for i := 0; i < 16; i++ {
+		for j := 0; j < 16; j++ {
+			v.YMM[i][j] = fp.XMM[i][j]
+		}
+		// Upper 128 bits would come from XSAVE, not available via GETFPREGS.
+	}
+	return v, nil
+}
+
+// Peek reads a word (8 bytes) from the debuggee's memory at addr.
+// Uses /proc/pid/mem which works reliably with Go's multi-threaded runtime.
+func (s *Session) Peek(addr uint64) (uint64, error) {
+	mem, err := os.OpenFile(fmt.Sprintf("/proc/%d/mem", s.pid), os.O_RDONLY, 0)
+	if err != nil {
+		return 0, fmt.Errorf("debug: open /proc/%d/mem: %w", s.pid, err)
+	}
+	defer mem.Close()
+	buf := make([]byte, 8)
+	if _, err := mem.ReadAt(buf, int64(addr)); err != nil {
+		return 0, fmt.Errorf("debug: read mem %#x: %w", addr, err)
+	}
+	return uint64(buf[0]) | uint64(buf[1])<<8 | uint64(buf[2])<<16 | uint64(buf[3])<<24 |
+		uint64(buf[4])<<32 | uint64(buf[5])<<40 | uint64(buf[6])<<48 | uint64(buf[7])<<56, nil
+}
+
+// Poke writes a word (8 bytes) to the debuggee's memory at addr.
+func (s *Session) Poke(addr, val uint64) error {
+	mem, err := os.OpenFile(fmt.Sprintf("/proc/%d/mem", s.pid), os.O_WRONLY, 0)
+	if err != nil {
+		return fmt.Errorf("debug: open /proc/%d/mem: %w", s.pid, err)
+	}
+	defer mem.Close()
+	buf := []byte{byte(val), byte(val >> 8), byte(val >> 16), byte(val >> 24),
+		byte(val >> 32), byte(val >> 40), byte(val >> 48), byte(val >> 56)}
+	if _, err := mem.WriteAt(buf, int64(addr)); err != nil {
+		return fmt.Errorf("debug: write mem %#x: %w", addr, err)
+	}
+	return nil
+}
+
+// ReadMemory reads len bytes from the debuggee's memory at addr.
+func (s *Session) ReadMemory(addr uint64, length int) ([]byte, error) {
+	out := make([]byte, length)
+	for i := 0; i < length; i += 8 {
+		word, err := s.Peek(addr + uint64(i))
+		if err != nil {
+			return out[:i], err
+		}
+		for j := 0; j < 8 && i+j < length; j++ {
+			out[i+j] = byte(word >> (8 * j))
+		}
+	}
+	return out, nil
+}
+
+// WriteMemory writes bytes to the debuggee's memory at addr.
+func (s *Session) WriteMemory(addr uint64, data []byte) error {
+	for i := 0; i < len(data); i += 8 {
+		end := i + 8
+		if end > len(data) {
+			end = len(data)
+		}
+		var word uint64
+		for j := 0; j < end-i; j++ {
+			word |= uint64(data[i+j]) << (8 * j)
+		}
+		// For partial writes, read-modify-write the existing word.
+		if end-i < 8 {
+			existing, err := s.Peek(addr + uint64(i))
+			if err != nil {
+				return err
+			}
+			// Clear the bytes we're overwriting and merge.
+			mask := ^((uint64(1) << (8 * (end - i))) - 1)
+			word = (existing & mask) | word
+		}
+		if err := s.Poke(addr+uint64(i), word); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// Step executes a single instruction in the debuggee.
+func (s *Session) Step() error {
+	if s.exited {
+		return fmt.Errorf("debug: debuggee has exited")
+	}
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_SINGLESTEP),
+		uintptr(s.pid),
+		0, 0, 0, 0,
+	)
+	if errno != 0 {
+		return fmt.Errorf("debug: PTRACE_SINGLESTEP: %w", errno)
+	}
+	return s.wait()
+}
+
+// Continue resumes execution until the next breakpoint or exit.
+func (s *Session) Continue() error {
+	if s.exited {
+		return fmt.Errorf("debug: debuggee has exited")
+	}
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_CONT),
+		uintptr(s.pid),
+		0, 0, 0, 0,
+	)
+	if errno != 0 {
+		return fmt.Errorf("debug: PTRACE_CONT: %w", errno)
+	}
+	return s.wait()
+}
+
+// Exited returns true if the debuggee has terminated.
+func (s *Session) Exited() bool {
+	return s.exited
+}
+
+// Pid returns the debuggee's process ID.
+func (s *Session) Pid() int {
+	return s.pid
+}
+
+// CodeBase returns the base address of the JIT code in the debuggee.
+func (s *Session) CodeBase() uint64 {
+	return s.codeBase
+}
+
+// Kill terminates the debuggee.
+func (s *Session) Kill() {
+	if !s.exited {
+		syscall.Kill(s.pid, syscall.SIGKILL)
+		syscall.Wait4(s.pid, nil, 0, nil)
+		s.exited = true
+	}
+	if s.cmd != nil && s.cmd.Process != nil {
+		s.cmd.Wait()
+	}
+}
+
+// findRWXMapping reads /proc/pid/maps and returns the base address of the
+// first read-write-execute mapping (the JIT code region).
+func findRWXMapping(pid int) uint64 {
+	data, err := os.ReadFile(fmt.Sprintf("/proc/%d/maps", pid))
+	if err != nil {
+		return 0
+	}
+	for _, line := range strings.Split(string(data), "\n") {
+		// Format: addr-addr perms offset dev inode pathname
+		fields := strings.Fields(line)
+		if len(fields) < 2 {
+			continue
+		}
+		perms := fields[1]
+		if len(perms) >= 3 && perms[0] == 'r' && perms[1] == 'w' && perms[2] == 'x' {
+			// Parse the start address.
+			var start uint64
+			fmt.Sscanf(fields[0], "%x-", &start)
+			return start
+		}
+	}
+	return 0
+}

debug/repl.go

@@ -0,0 +1,651 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && amd64
+
+package debug
+
+import (
+	"bufio"
+	"fmt"
+	"os"
+	"sort"
+	"strconv"
+	"strings"
+)
+
+// Label is a named address within the debugged function.
+type Label struct {
+	Name   string
+	Offset int // function-relative offset
+}
+
+// SourceLine maps a byte offset to a source line number.
+type SourceLine struct {
+	Offset int
+	Line   int
+}
+
+// REPL runs the interactive debugger loop.  On entry, the debuggee is
+// stopped in the Go runtime (after PTRACE_TRACEME + SIGSTOP).  The REPL
+// sets a temporary breakpoint at the function entry, continues to it, and
+// then presents the prompt — so the user starts debugging at the first
+// instruction of the assembled function.
+func REPL(s *Session, bm *Breakpoints, codeBase uint64, funcOffset, funcSize, argsSize int, labels []Label, lines []SourceLine) {
+	entryAddr := codeBase + uint64(funcOffset)
+
+	// The debuggee is already stopped at the function entry point.
+	fmt.Printf("stopped at function entry: %#x (%d bytes)\n", entryAddr, funcSize)
+	fmt.Println("commands: break <label|addr> | step [n] | continue | disas [n] | regs | where | x <addr> [len] | w <addr> <val...> | labels | quit")
+
+	scanner := bufio.NewScanner(os.Stdin)
+
+	for {
+		fmt.Print("(gasm) ")
+		if !scanner.Scan() {
+			break
+		}
+		line := strings.TrimSpace(scanner.Text())
+		if line == "" {
+			continue
+		}
+		parts := strings.Fields(line)
+		cmd := parts[0]
+
+		switch cmd {
+		case "q", "quit":
+			s.Kill()
+			return
+
+		case "regs":
+			regs, err := s.GetRegs()
+			if err != nil {
+				fmt.Println(err)
+				continue
+			}
+			printRegs(&regs, codeBase, uint64(funcOffset))
+			// Also show vector registers.
+			vregs, err := s.GetVectorRegs()
+			if err != nil {
+				fmt.Printf("  (vector regs unavailable: %v)\n", err)
+			} else {
+				printVectorRegs(&vregs)
+			}
+
+		case "step", "s":
+			n := 1
+			if len(parts) > 1 {
+				n, _ = strconv.Atoi(parts[1])
+			}
+			for i := 0; i < n; i++ {
+				if s.Exited() {
+					fmt.Println("debuggee exited")
+					break
+				}
+				if err := s.Step(); err != nil {
+					fmt.Println(err)
+					break
+				}
+			}
+			if !s.Exited() {
+				regs, _ := s.GetRegs()
+				text, _, _ := s.Disassemble(regs.RIP)
+				fmt.Printf("=> %#x (func+%#x): %s\n", regs.RIP, regs.RIP-codeBase-uint64(funcOffset), text)
+			}
+
+		case "next", "n":
+			// Step over: if the current instruction is a CALL, set a
+			// breakpoint after it and continue; otherwise single-step.
+			regs, _ := s.GetRegs()
+			text, instLen, _ := s.Disassemble(regs.RIP)
+			if strings.HasPrefix(strings.ToLower(text), "call") {
+				// Set a temporary breakpoint after the CALL.
+				afterAddr := regs.RIP + uint64(instLen)
+				bp, err := bm.Set(afterAddr, "(next)")
+				if err != nil {
+					fmt.Printf("cannot set next breakpoint: %v\n", err)
+					continue
+				}
+				// Continue until the breakpoint.
+				for _, b := range bm.All() {
+					bm.Reinsert(b.Addr)
+				}
+				if err := s.Continue(); err != nil {
+					fmt.Println(err)
+					bm.Clear(afterAddr)
+					continue
+				}
+				bm.HandleTrap(&regs)
+				bm.Clear(afterAddr)
+				_ = bp
+			} else {
+				// Not a CALL — just single-step.
+				if err := s.Step(); err != nil {
+					fmt.Println(err)
+					continue
+				}
+			}
+			if !s.Exited() {
+				regs, _ := s.GetRegs()
+				text, _, _ := s.Disassemble(regs.RIP)
+				fmt.Printf("=> %#x (func+%#x): %s\n", regs.RIP, regs.RIP-codeBase-uint64(funcOffset), text)
+			}
+
+		case "finish", "fin":
+			// Run until the current function returns.
+			// For NOSPLIT frame=0: return address is at [RSP].
+			regs, _ := s.GetRegs()
+			retAddr, err := s.Peek(regs.RSP)
+			if err != nil {
+				fmt.Printf("cannot read return address: %v\n", err)
+				continue
+			}
+			// Set a temporary breakpoint at the return address.
+			bp, err := bm.Set(retAddr, "(finish)")
+			if err != nil {
+				fmt.Printf("cannot set finish breakpoint: %v\n", err)
+				continue
+			}
+			// Continue until the breakpoint.
+			for _, b := range bm.All() {
+				bm.Reinsert(b.Addr)
+			}
+			if err := s.Continue(); err != nil {
+				fmt.Println(err)
+				bm.Clear(retAddr)
+				continue
+			}
+			if !s.Exited() {
+				bm.HandleTrap(&regs)
+			}
+			bm.Clear(retAddr)
+			_ = bp
+			if s.Exited() {
+				fmt.Println("debuggee exited")
+			} else {
+				regs, _ := s.GetRegs()
+				fmt.Printf("finished, now at %#x\n", regs.RIP)
+			}
+
+		case "continue", "c":
+			if s.Exited() {
+				fmt.Println("debuggee exited")
+				continue
+			}
+			// Loop: continue until a breakpoint fires (condition met) or exit.
+			for {
+				// Re-insert all breakpoints before continuing.
+				for _, bp := range bm.All() {
+					bm.Reinsert(bp.Addr)
+				}
+				if err := s.Continue(); err != nil {
+					fmt.Println(err)
+					break
+				}
+				if s.Exited() {
+					fmt.Println("debuggee exited")
+					break
+				}
+				// Check for watchpoint hits.
+				reason, wpAddr := s.StopInfo()
+				if reason == StopWatchpoint {
+					fmt.Printf("watchpoint hit at %#x\n", wpAddr)
+					break
+				}
+				regs, _ := s.GetRegs()
+				if bp := bm.HandleTrap(&regs); bp != nil {
+					name := bp.Label
+					if name == "" {
+						name = fmt.Sprintf("%#x", bp.Addr)
+					}
+					fmt.Printf("breakpoint hit: %s (func+%#x)\n", name, bp.Addr-codeBase-uint64(funcOffset))
+					break
+				}
+				// Condition not met (or single-step trap) — re-insert and continue.
+			}
+
+		case "break", "b":
+			if len(parts) < 2 {
+				fmt.Println("usage: break <label|addr|line> [if <reg> <op> <val>]")
+				continue
+			}
+			// Try as a line number first.
+			var addr uint64
+			var label string
+			if lineNum, err := strconv.Atoi(parts[1]); err == nil && lineNum > 0 {
+				// Find the byte offset for this line.
+				off := offsetForLine(lines, lineNum)
+				if off < 0 {
+					fmt.Printf("no instruction at line %d\n", lineNum)
+					continue
+				}
+				addr = codeBase + uint64(funcOffset) + uint64(off)
+				label = fmt.Sprintf("line %d", lineNum)
+			} else {
+				addr, label = resolveAddr(parts[1], codeBase, uint64(funcOffset), labels)
+			}
+			if addr == 0 {
+				fmt.Printf("unknown label, address, or line: %s\n", parts[1])
+				continue
+			}
+			// Parse optional condition: "if <reg> <op> <value>"
+			var cond *Condition
+			if len(parts) >= 6 && parts[2] == "if" {
+				val, err := strconv.ParseUint(parts[5], 0, 64)
+				if err != nil {
+					fmt.Printf("invalid condition value: %s\n", parts[5])
+					continue
+				}
+				cond = &Condition{Reg: strings.ToLower(parts[3]), Op: parts[4], Value: val}
+			} else if len(parts) >= 4 && parts[2] == "if" {
+				fmt.Println("usage: break <label|addr> if <reg> <op> <value>")
+				continue
+			}
+			bp, err := bm.SetWithCond(addr, label, cond)
+			if err != nil {
+				fmt.Println(err)
+				continue
+			}
+			condStr := ""
+			if cond != nil {
+				condStr = fmt.Sprintf(" if %s %s %#x", cond.Reg, cond.Op, cond.Value)
+			}
+			fmt.Printf("breakpoint set: %s at %#x (func+%#x)%s\n", bp.Label, bp.Addr, bp.Addr-codeBase-uint64(funcOffset), condStr)
+
+		case "info":
+			if len(parts) < 2 {
+				fmt.Println("usage: info break")
+				continue
+			}
+			switch parts[1] {
+			case "break", "breakpoints", "b":
+				fmt.Print(bm.Info())
+			default:
+				fmt.Printf("unknown info target: %s\n", parts[1])
+			}
+
+		case "delete", "d":
+			if len(parts) < 2 {
+				fmt.Println("usage: delete <label|addr>")
+				continue
+			}
+			addr, _ := resolveAddr(parts[1], codeBase, uint64(funcOffset), labels)
+			if addr == 0 {
+				fmt.Printf("unknown: %s\n", parts[1])
+				continue
+			}
+			if err := bm.Clear(addr); err != nil {
+				fmt.Println(err)
+			} else {
+				fmt.Println("breakpoint removed")
+			}
+
+		case "x":
+			regs, _ := s.GetRegs()
+			addr := regs.RIP // default: current PC
+			length := 64
+			if len(parts) > 1 {
+				addr, _ = resolveAddr(parts[1], codeBase, uint64(funcOffset), labels)
+			}
+			if len(parts) > 2 {
+				length, _ = strconv.Atoi(parts[2])
+			}
+			mem, err := s.ReadMemory(addr, length)
+			if err != nil {
+				fmt.Println(err)
+				continue
+			}
+			hexDump(addr, mem)
+
+		case "w":
+			if len(parts) < 3 {
+				fmt.Println("usage: w <addr> <byte|0x...> [byte...]")
+				continue
+			}
+			addr, _ := resolveAddr(parts[1], codeBase, uint64(funcOffset), labels)
+			if addr == 0 {
+				fmt.Printf("unknown address: %s\n", parts[1])
+				continue
+			}
+			var bytes []byte
+			for _, arg := range parts[2:] {
+				v, err := strconv.ParseUint(arg, 0, 64)
+				if err != nil {
+					fmt.Printf("invalid value: %s\n", arg)
+					continue
+				}
+				// Write as 8-byte word if it looks like a large value, else single byte.
+				if v > 255 {
+					for j := 0; j < 8; j++ {
+						bytes = append(bytes, byte(v>>(8*j)))
+					}
+				} else {
+					bytes = append(bytes, byte(v))
+				}
+			}
+			if len(bytes) > 0 {
+				if err := s.WriteMemory(addr, bytes); err != nil {
+					fmt.Println(err)
+				} else {
+					fmt.Printf("wrote %d bytes at %#x\n", len(bytes), addr)
+				}
+			}
+
+		case "set":
+			if len(parts) < 3 {
+				fmt.Println("usage: set <reg> <value>")
+				continue
+			}
+			val, err := strconv.ParseUint(parts[2], 0, 64)
+			if err != nil {
+				fmt.Printf("invalid value: %s\n", parts[2])
+				continue
+			}
+			if err := s.SetReg(strings.ToLower(parts[1]), val); err != nil {
+				fmt.Printf("set: %v\n", err)
+			} else {
+				fmt.Printf("%s = %#x\n", parts[1], val)
+			}
+
+		case "labels", "l":
+			sorted := make([]Label, len(labels))
+			copy(sorted, labels)
+			sort.Slice(sorted, func(i, j int) bool { return sorted[i].Offset < sorted[j].Offset })
+			for _, l := range sorted {
+				fmt.Printf("  func+%#04x  %s\n", l.Offset, l.Name)
+			}
+
+		case "disas", "u":
+			n := 5
+			if len(parts) > 1 {
+				n, _ = strconv.Atoi(parts[1])
+				if n <= 0 {
+					n = 5
+				}
+			}
+			regs, _ := s.GetRegs()
+			fmt.Print(s.DisassembleN(regs.RIP, n))
+
+		case "where":
+			regs, _ := s.GetRegs()
+			funcOff := int(regs.RIP - codeBase - uint64(funcOffset))
+			line := lineAt(lines, funcOff)
+			label := nearestLabel(labels, funcOff)
+			fmt.Printf("  func+%#x", funcOff)
+			if label != "" {
+				fmt.Printf("  (near %s)", label)
+			}
+			if line > 0 {
+				fmt.Printf("  line %d", line)
+			}
+			fmt.Println()
+
+		case "help", "h", "?":
+			fmt.Println(`  break <label|addr> [if <reg> <op> <val>]  set a breakpoint
+  delete <label|addr>  remove a breakpoint
+  info break           list all breakpoints
+  watch <addr> [r|w]   set a hardware watchpoint (write by default)
+  unwatch              clear all watchpoints
+  step [n], s          single-step n instructions
+  next, n              step over CALL
+  continue, c          run until breakpoint or exit
+  disas [n], u         disassemble n instructions at PC
+  regs                 print registers and RFLAGS
+  where                show source line and nearest label
+  stack                show stack near RSP (args + return address)
+  x [addr] [len]       hex-dump memory
+  w <addr> <val...>    write bytes to memory
+  labels, l            list function labels
+  help, h, ?           this help
+  quit, q              kill debuggee and exit`)
+
+		case "stack":
+			regs, _ := s.GetRegs()
+			// For NOSPLIT frame=0: [RSP] = return address, [RSP+8..] = args.
+			retAddr, _ := s.Peek(regs.RSP)
+			fmt.Printf("  [RSP]   return addr = %#x\n", retAddr)
+			if argsSize > 0 {
+				fmt.Printf("  args (%d bytes at RSP+8):\n", argsSize)
+				argBytes, err := s.ReadMemory(regs.RSP+8, argsSize)
+				if err == nil {
+					for i := 0; i < argsSize; i += 8 {
+						var v uint64
+						for j := 0; j < 8 && i+j < len(argBytes); j++ {
+							v |= uint64(argBytes[i+j]) << (8 * j)
+						}
+						fmt.Printf("    [%+3d]  %#016x\n", i+8, v)
+					}
+				}
+			}
+
+		case "bt", "backtrace":
+			regs, _ := s.GetRegs()
+			funcOff := int(regs.RIP - codeBase - uint64(funcOffset))
+			line := lineAt(lines, funcOff)
+			label := nearestLabel(labels, funcOff)
+			fmt.Printf("  #0  func+%#x", funcOff)
+			if label != "" {
+				fmt.Printf(" (%s)", label)
+			}
+			if line > 0 {
+				fmt.Printf(" [line %d]", line)
+			}
+			fmt.Println()
+			retAddr, _ := s.Peek(regs.RSP)
+			fmt.Printf("  #1  return to %#x\n", retAddr)
+
+		case "watch":
+			if len(parts) < 2 {
+				fmt.Println("usage: watch <addr> [r|w] [size]")
+				continue
+			}
+			addr, _ := resolveAddr(parts[1], codeBase, uint64(funcOffset), labels)
+			if addr == 0 {
+				fmt.Printf("unknown address: %s\n", parts[1])
+				continue
+			}
+			typ := WatchWrite
+			size := 8
+			if len(parts) > 2 {
+				switch parts[2] {
+				case "r":
+					typ = WatchRead
+				case "w":
+					typ = WatchWrite
+				}
+			}
+			if len(parts) > 3 {
+				size, _ = strconv.Atoi(parts[3])
+			}
+			// Find a free slot (0-3).
+			slot := -1
+			for i := 0; i < 4; i++ {
+				// Simple: use slot 0 for now.
+				slot = i
+				break
+			}
+			if slot < 0 {
+				fmt.Println("no free watchpoint slots")
+				continue
+			}
+			if err := s.SetWatchpoint(slot, addr, typ, size); err != nil {
+				fmt.Printf("watch: %v\n", err)
+			} else {
+				fmt.Printf("watchpoint %d set: %#x (%s, %d bytes)\n", slot, addr, parts[2], size)
+			}
+
+		case "unwatch":
+			if err := s.ClearAllWatchpoints(); err != nil {
+				fmt.Printf("unwatch: %v\n", err)
+			} else {
+				fmt.Println("all watchpoints cleared")
+			}
+
+		default:
+			fmt.Printf("unknown command: %s\n", cmd)
+		}
+	}
+	s.Kill()
+}
+
+func printRegs(regs *Regs, codeBase, funcOff uint64) {
+	fmt.Printf("  RIP = %#016x  (func+%#x)\n", regs.RIP, regs.RIP-codeBase-funcOff)
+	fmt.Printf("  RSP = %#016x  RBP = %#016x\n", regs.RSP, regs.RBP)
+	fmt.Printf("  RAX = %#016x  RBX = %#016x\n", regs.RAX, regs.RBX)
+	fmt.Printf("  RCX = %#016x  RDX = %#016x\n", regs.RCX, regs.RDX)
+	fmt.Printf("  RSI = %#016x  RDI = %#016x\n", regs.RSI, regs.RDI)
+	fmt.Printf("  R8  = %#016x  R9  = %#016x\n", regs.R8, regs.R9)
+	fmt.Printf("  R10 = %#016x  R11 = %#016x\n", regs.R10, regs.R11)
+	fmt.Printf("  R12 = %#016x  R13 = %#016x\n", regs.R12, regs.R13)
+	fmt.Printf("  R14 = %#016x  R15 = %#016x\n", regs.R14, regs.R15)
+	fmt.Printf("  RFLAGS = %#x  [%s]\n", regs.RFLAGS, decodeRflags(regs.RFLAGS))
+}
+
+// printVectorRegs displays the YMM registers.
+func printVectorRegs(v *VectorRegs) {
+	fmt.Println("\n  Vector registers (YMM):")
+	for i := 0; i < 16; i += 2 {
+		fmt.Printf("  YMM%-2d = ", i)
+		printYMM(v.YMM[i][:])
+		fmt.Printf("  YMM%-2d = ", i+1)
+		printYMM(v.YMM[i+1][:])
+		fmt.Println()
+	}
+}
+
+func printYMM(b []byte) {
+	// Show as 8 32-bit values.
+	for j := 0; j < 32; j += 4 {
+		v := uint32(b[j]) | uint32(b[j+1])<<8 | uint32(b[j+2])<<16 | uint32(b[j+3])<<24
+		fmt.Printf("%08x ", v)
+	}
+}
+
+func decodeRflags(f uint64) string {
+	var flags string
+	if f&1 != 0 {
+		flags += "CF "
+	}
+	if f&(1<<2) != 0 {
+		flags += "PF "
+	}
+	if f&(1<<4) != 0 {
+		flags += "AF "
+	}
+	if f&(1<<6) != 0 {
+		flags += "ZF "
+	}
+	if f&(1<<7) != 0 {
+		flags += "SF "
+	}
+	if f&(1<<8) != 0 {
+		flags += "TF "
+	}
+	if f&(1<<9) != 0 {
+		flags += "IF "
+	}
+	if f&(1<<10) != 0 {
+		flags += "DF "
+	}
+	if f&(1<<11) != 0 {
+		flags += "OF "
+	}
+	if flags == "" {
+		return "none"
+	}
+	return flags[:len(flags)-1] // trim trailing space
+}
+
+func hexDump(addr uint64, data []byte) {
+	for i := 0; i < len(data); i += 16 {
+		end := i + 16
+		if end > len(data) {
+			end = len(data)
+		}
+		fmt.Printf("  %#08x:", addr+uint64(i))
+		for j := i; j < i+16; j++ {
+			if j < end {
+				fmt.Printf(" %02x", data[j])
+			} else {
+				fmt.Print("   ")
+			}
+		}
+		fmt.Print("  ")
+		for j := i; j < end; j++ {
+			if data[j] >= 0x20 && data[j] < 0x7f {
+				fmt.Printf("%c", data[j])
+			} else {
+				fmt.Print(".")
+			}
+		}
+		fmt.Println()
+	}
+}
+
+func resolveAddr(s string, codeBase, funcOff uint64, labels []Label) (uint64, string) {
+	// Try as a hex address.
+	if strings.HasPrefix(s, "0x") || strings.HasPrefix(s, "0X") {
+		v, err := strconv.ParseUint(s, 0, 64)
+		if err == nil {
+			return v, ""
+		}
+	}
+	// Try as func+offset.
+	if strings.HasPrefix(s, "+") {
+		off, err := strconv.ParseUint(s[1:], 0, 64)
+		if err == nil {
+			return codeBase + funcOff + off, fmt.Sprintf("func+%#x", off)
+		}
+	}
+	// Try as a label name.
+	for _, l := range labels {
+		if l.Name == s {
+			return codeBase + funcOff + uint64(l.Offset), l.Name
+		}
+	}
+	return 0, ""
+}
+
+// lineAt returns the source line for a given function-relative offset.
+func lineAt(lines []SourceLine, offset int) int {
+	if len(lines) == 0 {
+		return 0
+	}
+	lo, hi := 0, len(lines)-1
+	for lo < hi {
+		mid := (lo + hi + 1) / 2
+		if lines[mid].Offset <= offset {
+			lo = mid
+		} else {
+			hi = mid - 1
+		}
+	}
+	if lines[lo].Offset <= offset {
+		return lines[lo].Line
+	}
+	return 0
+}
+
+// offsetForLine returns the byte offset for a given source line number.
+// Returns -1 if no instruction is at that line.
+func offsetForLine(lines []SourceLine, line int) int {
+	for _, le := range lines {
+		if le.Line == line {
+			return le.Offset
+		}
+	}
+	return -1
+}
+
+// nearestLabel returns the name of the label at or just before the offset.
+func nearestLabel(labels []Label, offset int) string {
+	best := ""
+	bestOff := -1
+	for _, l := range labels {
+		if l.Offset <= offset && l.Offset > bestOff {
+			best = l.Name
+			bestOff = l.Offset
+		}
+	}
+	return best
+}

debug/stopinfo_linux_amd64.go

@@ -0,0 +1,117 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && amd64
+
+package debug
+
+import (
+	"fmt"
+	"syscall"
+	"unsafe"
+)
+
+// StopReason describes why the debuggee stopped.
+type StopReason int
+
+const (
+	StopNone       StopReason = iota
+	StopBreakpoint            // INT3 breakpoint hit
+	StopWatchpoint            // hardware watchpoint triggered
+	StopSingleStep            // single-step completed
+	StopSignal                // stopped by a signal
+	StopExited                // process exited
+)
+
+// siginfo_t layout (Linux amd64): si_signo, si_errno, si_code, then union.
+type siginfoT struct {
+	SiSigno int32
+	SiErrno int32
+	SiCode  int32
+	_pad    [125]byte
+}
+
+const (
+	trapBRKPT   = 1 // INT3 breakpoint
+	trapHWBRKPT = 4 // hardware watchpoint
+)
+
+// StopInfo returns the reason the debuggee stopped and the faulting address
+// (for watchpoints, the watched address that was accessed).
+func (s *Session) StopInfo() (StopReason, uint64) {
+	if s.exited {
+		return StopExited, 0
+	}
+	var info siginfoT
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(syscall.PTRACE_GETSIGINFO),
+		uintptr(s.pid),
+		0,
+		uintptr(unsafe.Pointer(&info)),
+		0, 0,
+	)
+	if errno != 0 {
+		return StopNone, 0
+	}
+	if info.SiSigno != int32(syscall.SIGTRAP) {
+		return StopSignal, uint64(info.SiCode)
+	}
+	switch info.SiCode {
+	case trapBRKPT:
+		return StopBreakpoint, 0
+	case trapHWBRKPT:
+		// The faulting address is in si_addr (offset 16 in siginfo_t on amd64).
+		addr := *(*uint64)(unsafe.Pointer(uintptr(unsafe.Pointer(&info)) + 16))
+		return StopWatchpoint, addr
+	default:
+		return StopSingleStep, 0
+	}
+}
+
+// SetReg modifies a register value in the debuggee.
+func (s *Session) SetReg(name string, value uint64) error {
+	regs, err := s.GetRegs()
+	if err != nil {
+		return err
+	}
+	switch name {
+	case "rax", "eax", "ax", "al":
+		regs.RAX = value
+	case "rbx", "ebx", "bx", "bl":
+		regs.RBX = value
+	case "rcx", "ecx", "cx", "cl":
+		regs.RCX = value
+	case "rdx", "edx", "dx", "dl":
+		regs.RDX = value
+	case "rsi", "esi", "si":
+		regs.RSI = value
+	case "rdi", "edi", "di":
+		regs.RDI = value
+	case "rbp", "ebp", "bp":
+		regs.RBP = value
+	case "rsp", "esp", "sp":
+		regs.RSP = value
+	case "r8":
+		regs.R8 = value
+	case "r9":
+		regs.R9 = value
+	case "r10":
+		regs.R10 = value
+	case "r11":
+		regs.R11 = value
+	case "r12":
+		regs.R12 = value
+	case "r13":
+		regs.R13 = value
+	case "r14":
+		regs.R14 = value
+	case "r15":
+		regs.R15 = value
+	case "rip", "eip":
+		regs.RIP = value
+	default:
+		return fmt.Errorf("debug: unknown register %q", name)
+	}
+	return s.SetRegs(&regs)
+}

debug/target_linux_amd64.go

@@ -0,0 +1,227 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && amd64
+
+package debug
+
+import (
+	"encoding/hex"
+	"fmt"
+	"os"
+	"runtime"
+	"strconv"
+	"strings"
+	"syscall"
+	"unsafe"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/asm"
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+	"sourcedock.dev/petrbalvin/gasm-devkit/verify"
+)
+
+// RunTarget is the debuggee entry point (gasm debug --target).  It
+// assembles the file, maps the JIT code, registers itself for ptrace,
+// stops, and then executes the named function.  The parent debugger
+// controls execution from there.
+func RunTarget(asmPath, funcName, argsFile, tmpDir string) error {
+	// Parse and assemble.
+	src, err := os.ReadFile(asmPath)
+	if err != nil {
+		return fmt.Errorf("debug target: %w", err)
+	}
+	file, errs := parser.Parse(asmPath, string(src))
+	if len(errs) > 0 {
+		return fmt.Errorf("debug target: parse: %v", errs[0])
+	}
+	img, err := asm.AssembleFile(file)
+	if err != nil {
+		return fmt.Errorf("debug target: assemble: %w", err)
+	}
+
+	// Find the function.
+	var fl *asm.FuncLayout
+	for i := range img.Funcs {
+		if img.Funcs[i].Name == funcName {
+			fl = &img.Funcs[i]
+			break
+		}
+	}
+	if fl == nil {
+		return fmt.Errorf("debug target: function %q not found", funcName)
+	}
+
+	// Map the entire image RWX (we need write access for breakpoints).
+	code := img.Bytes()
+	exec, err := mapRWX(code)
+	if err != nil {
+		return fmt.Errorf("debug target: mmap: %w", err)
+	}
+
+	// Write the code base address for the parent.
+	codeBase := uintptr(unsafe.Pointer(&exec[0]))
+	if err := os.WriteFile(tmpDir+"/codebase", []byte(fmt.Sprintf("%d", codeBase)), 0o644); err != nil {
+		return fmt.Errorf("debug target: write codebase: %w", err)
+	}
+
+	// Write function metadata (offset, size, args) for the parent.
+	meta := fmt.Sprintf("%d %d %d", fl.Offset, fl.Size, fl.Args)
+	os.WriteFile(tmpDir+"/funcmeta", []byte(meta), 0o644)
+
+	// Write label table for breakpoint resolution.
+	labelsFile, _ := os.Create(tmpDir + "/labels")
+	if labelsFile != nil {
+		for label, off := range fl.Labels {
+			fmt.Fprintf(labelsFile, "%s %d\n", label, off)
+		}
+		labelsFile.Close()
+	}
+
+	// Read the argument block.
+	args, err := os.ReadFile(argsFile)
+	if err != nil {
+		return fmt.Errorf("debug target: read args: %w", err)
+	}
+	if len(args) < fl.Args {
+		padded := make([]byte, fl.Args)
+		copy(padded, args)
+		args = padded
+	}
+
+	// Read buffer specification if present.
+	bufSpecFile := tmpDir + "/bufspec"
+	if bufSpec, err := os.ReadFile(bufSpecFile); err == nil && len(bufSpec) > 0 {
+		args, err = setupBuffers(string(bufSpec), args, fl.Args, tmpDir)
+		if err != nil {
+			return fmt.Errorf("debug target: setup buffers: %w", err)
+		}
+	}
+
+	// Lock this goroutine to the current OS thread so the parent's
+	// ptrace (attached to this thread) controls the JIT execution.
+	runtime.LockOSThread()
+
+	// Request tracing by the parent, then stop.  PTRACE_TRACEME makes
+	// the subsequent SIGSTOP a ptrace-stop (not a group-stop), giving
+	// the parent full control from the start.
+	if _, _, errno := syscall.Syscall(syscall.SYS_PTRACE, uintptr(syscall.PTRACE_TRACEME), 0, 0); errno != 0 {
+		return fmt.Errorf("debug target: PTRACE_TRACEME: %v", errno)
+	}
+	os.WriteFile(tmpDir+"/ready", []byte("ok"), 0o644)
+	syscall.Kill(syscall.Getpid(), syscall.SIGSTOP)
+
+	// --- Execution resumes here after the parent continues us ---
+
+	// Stop at the function entry point so the debugger can set breakpoints.
+	// The parent will continue us when ready.
+	os.WriteFile(tmpDir+"/entry", []byte("ok"), 0o644)
+	syscall.Kill(syscall.Getpid(), syscall.SIGSTOP)
+
+	// Prepare the ABI0 stack and call the function.
+	fnAddr := codeBase + uintptr(fl.Offset)
+	stackArgs := make([]byte, fl.Args)
+	copy(stackArgs, args)
+
+	_, callErr := verify.Call(fnAddr, stackArgs)
+	if callErr != nil {
+		// The function returned an error (shouldn't happen for valid code).
+		os.Exit(1)
+	}
+	os.Exit(0)
+	return nil
+}
+
+// mapRWX maps code into a read-write-execute region (needed for
+// breakpoint patching via ptrace POKETEXT, though ptrace can write
+// to any mapping regardless of permissions).
+func mapRWX(code []byte) ([]byte, error) {
+	const pageSize = 4096
+	size := (len(code) + pageSize - 1) &^ (pageSize - 1)
+	mem, err := syscall.Mmap(-1, 0, size,
+		syscall.PROT_READ|syscall.PROT_WRITE|syscall.PROT_EXEC,
+		syscall.MAP_PRIVATE|syscall.MAP_ANON)
+	if err != nil {
+		return nil, err
+	}
+	copy(mem, code)
+	return mem, nil
+}
+
+// setupBuffers allocates buffers in the debuggee's memory and updates the
+// argument block with pointers to them.
+// Format: name:size:pattern[,name:size:pattern...]
+// Patterns: zero, ones, seq, or hex (e.g. "deadbeef").
+func setupBuffers(spec string, args []byte, argSize int, tmpDir string) ([]byte, error) {
+	// Parse the buffer spec.
+	type bufSpec struct {
+		name    string
+		size    int
+		pattern string
+	}
+	var specs []bufSpec
+	for _, part := range strings.Split(spec, ",") {
+		fields := strings.SplitN(part, ":", 3)
+		if len(fields) != 3 {
+			continue
+		}
+		size, err := strconv.Atoi(fields[1])
+		if err != nil || size <= 0 {
+			continue
+		}
+		specs = append(specs, bufSpec{name: fields[0], size: size, pattern: fields[2]})
+	}
+
+	if len(specs) == 0 {
+		return args, nil
+	}
+
+	// Allocate buffers and write their addresses to a file for the parent.
+	var bufAddrs []uint64
+	for _, s := range specs {
+		buf, err := syscall.Mmap(-1, 0, s.size,
+			syscall.PROT_READ|syscall.PROT_WRITE,
+			syscall.MAP_PRIVATE|syscall.MAP_ANON)
+		if err != nil {
+			return nil, fmt.Errorf("mmap buffer %s: %w", s.name, err)
+		}
+		fillBuffer(buf, s.pattern)
+		bufAddrs = append(bufAddrs, uint64(uintptr(unsafe.Pointer(&buf[0]))))
+	}
+
+	// Write buffer addresses to a file for the parent to read.
+	addrFile, err := os.Create(tmpDir + "/bufaddrs")
+	if err != nil {
+		return nil, err
+	}
+	for _, addr := range bufAddrs {
+		fmt.Fprintf(addrFile, "%d\n", addr)
+	}
+	addrFile.Close()
+
+	// For now, return the args unchanged. The parent will read bufaddrs
+	// and construct the final argument block with the correct pointers.
+	return args, nil
+}
+
+// fillBuffer fills a buffer with the specified pattern.
+func fillBuffer(buf []byte, pattern string) {
+	switch pattern {
+	case "zero":
+		// Already zeroed by mmap.
+	case "ones":
+		for i := range buf {
+			buf[i] = 0xFF
+		}
+	case "seq":
+		for i := range buf {
+			buf[i] = byte(i)
+		}
+	default:
+		// Try to parse as hex.
+		if data, err := hex.DecodeString(pattern); err == nil && len(data) > 0 {
+			for i := range buf {
+				buf[i] = data[i%len(data)]
+			}
+		}
+	}
+}

debug/tracer.go

@@ -0,0 +1,90 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package debug
+
+// Regs holds the full general-purpose register set of a traced process
+// (the Linux amd64 user_regs_struct layout).
+type Regs struct {
+	R15     uint64
+	R14     uint64
+	R13     uint64
+	R12     uint64
+	RBP     uint64
+	RBX     uint64
+	R11     uint64
+	R10     uint64
+	R9      uint64
+	R8      uint64
+	RAX     uint64
+	RCX     uint64
+	RDX     uint64
+	RSI     uint64
+	RDI     uint64
+	OrigRAX uint64
+	RIP     uint64
+	CS      uint64
+	RFLAGS  uint64
+	RSP     uint64
+	SS      uint64
+	FSBase  uint64
+	GSBase  uint64
+	DS      uint64
+	ES      uint64
+	FS      uint64
+	GS      uint64
+}
+
+// tracer abstracts the minimal ptrace operations needed by the breakpoint
+// manager and the stop-information helpers.  The live implementation is
+// *Session (ptrace_linux_amd64.go); tests supply a mock.
+type tracer interface {
+	Peek(addr uint64) (uint64, error)
+	Poke(addr uint64, val uint64) error
+	SetRegs(regs *Regs) error
+	Pid() int
+}
+
+// mockTracer records Peek/Poke calls and provides fake register state.
+type mockTracer struct {
+	mem   map[uint64]byte
+	peeks []uint64
+	pokes []struct {
+		addr uint64
+		val  uint64
+	}
+	regs *Regs
+}
+
+func newMockTracer() *mockTracer {
+	return &mockTracer{
+		mem:  make(map[uint64]byte),
+		regs: &Regs{},
+	}
+}
+
+func (m *mockTracer) Peek(addr uint64) (uint64, error) {
+	m.peeks = append(m.peeks, addr)
+	var val uint64
+	for i := uint64(0); i < 8; i++ {
+		val |= uint64(m.mem[addr+i]) << (i * 8)
+	}
+	return val, nil
+}
+
+func (m *mockTracer) Poke(addr uint64, val uint64) error {
+	m.pokes = append(m.pokes, struct {
+		addr uint64
+		val  uint64
+	}{addr, val})
+	for i := uint64(0); i < 8; i++ {
+		m.mem[addr+i] = byte(val >> (i * 8))
+	}
+	return nil
+}
+
+func (m *mockTracer) SetRegs(regs *Regs) error {
+	m.regs = regs
+	return nil
+}
+func (m *mockTracer) Pid() int { return 42 }

debug/watchpoint_linux_amd64.go

@@ -0,0 +1,143 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build linux && amd64
+
+package debug
+
+import (
+	"fmt"
+	"syscall"
+)
+
+// Hardware watchpoint support via x86-64 debug registers (DR0-DR3, DR7).
+//
+// DR0-DR3 hold the watched addresses.  DR7 is the control register:
+//   bits 0,2,4,6: local enable for DR0-DR3
+//   bits 16-17,20-21,24-25,28-29: R/W type (00=exec, 01=write, 11=read/write)
+//   bits 18-19,22-23,26-27,30-31: length (00=1, 01=2, 10=8, 11=4)
+
+// WatchpointType selects what triggers the watchpoint.
+type WatchpointType int
+
+const (
+	WatchWrite WatchpointType = 1 // trigger on write
+	WatchRead  WatchpointType = 3 // trigger on read or write
+)
+
+// SetWatchpoint installs a hardware watchpoint on the given address.
+// slot is 0-3 (four hardware watchpoints available).
+func (s *Session) SetWatchpoint(slot int, addr uint64, typ WatchpointType, size int) error {
+	if slot < 0 || slot > 3 {
+		return fmt.Errorf("debug: watchpoint slot must be 0-3")
+	}
+
+	// Determine the length encoding.
+	var lenBits uint64
+	switch size {
+	case 1:
+		lenBits = 0
+	case 2:
+		lenBits = 1
+	case 4:
+		lenBits = 3
+	case 8:
+		lenBits = 2
+	default:
+		return fmt.Errorf("debug: watchpoint size must be 1, 2, 4, or 8")
+	}
+
+	// Write the watched address to DR0-DR3.
+	var drAddr uintptr
+	switch slot {
+	case 0:
+		drAddr = 0x0 // DR0 offset in user_regs_struct
+	case 1:
+		drAddr = 0x8 // DR1
+	case 2:
+		drAddr = 0x10 // DR2
+	case 3:
+		drAddr = 0x18 // DR3
+	}
+
+	// PTRACE_POKEUSER writes to the debuggee's user area (includes debug regs).
+	if err := ptracePokeUser(s.pid, drAddr, addr); err != nil {
+		return fmt.Errorf("debug: set DR%d: %w", slot, err)
+	}
+
+	// Read the current DR7, set the enable and type bits, write it back.
+	dr7, err := ptracePeekUser(s.pid, 0x38) // DR7 offset
+	if err != nil {
+		return fmt.Errorf("debug: read DR7: %w", err)
+	}
+
+	enableBit := uint64(1) << (2 * slot)   // local enable
+	rwBits := uint64(typ) << (16 + 4*slot) // R/W type
+	lenField := lenBits << (18 + 4*slot)   // length
+
+	// Clear the existing bits for this slot, then set the new ones.
+	mask := ^((uint64(1) << (2 * slot)) | (uint64(3) << (16 + 4*slot)) | (uint64(3) << (18 + 4*slot)))
+	dr7 = (dr7 & mask) | enableBit | rwBits | lenField
+
+	if err := ptracePokeUser(s.pid, 0x38, dr7); err != nil {
+		return fmt.Errorf("debug: set DR7: %w", err)
+	}
+	return nil
+}
+
+// ClearWatchpoint removes a hardware watchpoint.
+func (s *Session) ClearWatchpoint(slot int) error {
+	if slot < 0 || slot > 3 {
+		return fmt.Errorf("debug: watchpoint slot must be 0-3")
+	}
+	// Read DR7, clear the enable bit for this slot.
+	dr7, err := ptracePeekUser(s.pid, 0x38)
+	if err != nil {
+		return err
+	}
+	dr7 &^= uint64(1) << (2 * slot) // disable
+	return ptracePokeUser(s.pid, 0x38, dr7)
+}
+
+// ClearAllWatchpoints removes all hardware watchpoints.
+func (s *Session) ClearAllWatchpoints() error {
+	for slot := 0; slot < 4; slot++ {
+		if err := s.ClearWatchpoint(slot); err != nil {
+			return err
+		}
+	}
+	return nil
+}
+
+// ptracePokeUser writes a value to the debuggee's user area at the given offset.
+func ptracePokeUser(pid int, offset uintptr, val uint64) error {
+	const ptracePokeuser = 6 // PTRACE_POKEUSER
+	_, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(ptracePokeuser),
+		uintptr(pid),
+		offset,
+		uintptr(val),
+		0, 0,
+	)
+	if errno != 0 {
+		return errno
+	}
+	return nil
+}
+
+// ptracePeekUser reads a value from the debuggee's user area at the given offset.
+func ptracePeekUser(pid int, offset uintptr) (uint64, error) {
+	const ptracePeekuser = 3 // PTRACE_PEEKUSER
+	val, _, errno := syscall.Syscall6(
+		syscall.SYS_PTRACE,
+		uintptr(ptracePeekuser),
+		uintptr(pid),
+		offset,
+		0, 0, 0,
+	)
+	if errno != 0 {
+		return 0, errno
+	}
+	return uint64(val), nil
+}

docs/ARCHITECTURE.md

@@ -2,6 +2,8 @@
 
 How gasm-devkit is put together and why.
 
+Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit)
+
 ## Design goals
 
 1. **A real AST, not a grammar hack.**  The linter, analyser, assembler and
@@ -192,6 +194,13 @@ with the Plan 9 operand order (source first) mapped onto the x86 encoding.
 Every encoding is validated by decoding it again with `golang.org/x/arch` — the
 one module dependency, used in tests only and never linked into the binary.
 
+A **RISC-V encoder** (Phase 5, RV64IMAFDC + RVC compression) encodes the full
+integer, atomic, float/double, FMA and CSR instruction sets with the MOV
+pseudo-instruction and SB/global symbol references (AUIPC pairs with
+R_RISCV_PCREL_HI20/LO12 relocations).  The encoder compresses eligible
+instructions to 16-bit RVC forms and is validated byte-for-byte against
+`GOARCH=riscv64 go tool asm`.
+
 On top of the encoder, `Assemble` walks a parsed `TEXT` body, converts each
 operand to an encoder operand, and lays the instructions out so local labels
 resolve to relative jump offsets: jumps start in the short (rel8) form and
@@ -279,7 +288,9 @@ boundaries, plus flat `pcfile`, `pcline` and `pcinline` tables — so a
 gasm-assembled object drops into a `go build` in place of the toolchain's.
 The object preamble (the version-and-experiment header the linker compares
 verbatim) is captured from the installed `go tool asm`, so the output is
-always consistent with the toolchain that links it.  External cross-package
+always consistent with the toolchain that links it.  RISC-V GOOBJ emission
+uses the same format with the RISC-V architecture marker and RISC-V relocation
+types.  External cross-package
 references and the implicit funcdata/DWARF symbols remain future work (the
 linker fills the latter's defaults); the rest of Phase 2 is those, the
 remaining EVEX forms and the other architectures.
@@ -307,7 +318,32 @@ assembler’s `Image.Bytes()` provides the code-and-data concatenation.
 
 The `gasm verify` CLI subcommand exposes this: it loads a file, reports the
 available functions and (with `-smoke`) calls each NOSPLIT function with zeroed
-arguments to confirm the trampoline round-trips.
+arguments to confirm the trampoline round-trips.  `gasm verify --fuzz` combines
+ABI checks (sentinel registers, canary, stack bounds) with differential fuzz
+testing, comparing the JIT-assembled kernel against the portable Go reference
+bit-for-bit while verifying the ABI contract on every iteration.  When a fuzz
+iteration crashes or mismatches, `FuzzResult.CrashInput` stores the exact input
+for reproducibility.  `gasm verify --call <func> --buf name:size:pattern`
+invokes a single function with user-supplied buffers (patterns: zero, ones,
+seq, or hex), printing the ABI0 argument block before and after the call —
+useful for partial functions (e.g. decoders) that crash on random input but
+should succeed on valid data.  `gasm verify --ground-truth` compares the
+assembled machine code byte-for-byte against `go tool asm` (relocation sites
+masked), reporting any encoding drift.
+
+### `debug`
+
+The interactive debugger (Phase 4, linux/amd64).  It launches the target
+function in a child process that maps the JIT code, calls
+`PTRACE_TRACEME`, and stops; the parent attaches via ptrace and controls
+execution.  Breakpoints are patched as INT3 bytes through `/proc/pid/mem`
+(PTRACE_PEEKTEXT is unreliable with Go's multi-threaded runtime).
+The child pins its goroutine to the OS thread with `runtime.LockOSThread`
+so the traced thread is the one executing JIT code.  The REPL provides
+single-step, register inspection (GPR + YMM/XMM via `PTRACE_GETFPREGS`),
+label resolution, named buffer allocation with pattern filling
+(`--buf name:size:pattern` — zero, ones, seq, or hex), and breakpoint
+management.
 
 ## Extension points
 

docs/cli.md

@@ -0,0 +1,145 @@
+# CLI Reference
+
+Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit)
+
+`gasm` is a single binary with subcommands. Run `gasm --help` for an
+overview, or `gasm <command> -h` for a command's usage and flags.
+
+## Global Flags
+
+| Flag | Description |
+|------|-------------|
+| `-h`, `--help` | Show help |
+| `-V`, `--version` | Print the version |
+
+## `gasm tokens <file>`
+
+Print the lexical token stream of FILE: position, token kind, and text,
+one token per line. FILE may be `-` to read standard input.
+
+## `gasm parse <file>`
+
+Parse FILE and report syntax errors on stderr. On success, prints how
+many declarations and TEXT functions the file contains.
+
+## `gasm fmt [-w] [path...]`
+
+Canonicalise the formatting of Plan 9 assembly sources: indentation,
+operand spacing, per-function mnemonic alignment, and blank-line layout.
+
+| Flag | Description |
+|------|-------------|
+| `-w` | Write result to the source file (default: print to stdout) |
+
+With no arguments, or with a directory argument, every `.s` file below
+it is reformatted in place and the names of changed files are listed
+(`go fmt` style). `.` and `_` directories are skipped.
+
+## `gasm lint <file...>`
+
+Run static checks and print diagnostics as
+`file:line:col: severity: message [code]`. Exit status is non-zero when
+an error-severity diagnostic is found.
+
+| Flag | Description |
+|------|-------------|
+| `-disable` | Comma-separated rule codes to disable |
+
+Rules: `unknown-instruction`, `operand-count`, `undefined-label`,
+`duplicate-label`, `missing-ret`, `missing-textflag-include`,
+`abi-argsize`, `unreachable-code`, `register-clobber`,
+`funcdata-pcdata`.
+
+## `gasm asm [--format raw|elf|macho|goobj] [-p pkg] [-o out] <file>`
+
+Assemble FILE (amd64) to machine code.
+
+| Flag | Description |
+|------|-------------|
+| `--format` | Output format: `raw` (default), `elf`, `macho`, `goobj` |
+| `-p` | Package path (required for `--format goobj`) |
+| `-o` | Write output to file (default: hex dump to stdout) |
+
+## `gasm verify [flags] <file.s>`
+
+Assemble FILE, map it into executable memory, and run dynamic checks.
+
+| Flag | Description |
+|------|-------------|
+| `--ground-truth` | Compare machine code byte-for-byte against `go tool asm` |
+| `--fuzz` | Differential fuzz: JIT both gasm and go-tool-asm, compare outputs |
+| `-n` | Fuzz iterations per function (default: 1000) |
+| `--abi` | Run ABI-checking calls (sentinel registers + red zone) |
+| `--abi-n` | Number of ABI check iterations with varied inputs (default: 100) |
+| `--profile` | List basic-block structure per function |
+| `--smoke` | Call each NOSPLIT function with zeroed args |
+| `--call <func>` | Invoke a single function with `--buf` instead of the sweeps |
+| `--buf <spec>` | Buffer spec for `--call`: `name:size:pattern[,name:size:pattern]` |
+| `--repeat <n>` | Number of times to repeat a `--call` invocation (default: 1) |
+
+The `--fuzz` mode runs each function in a subprocess; a partial function
+(e.g. a decoder that faults on malformed input) is reported as
+`CRASH` without killing the parent. Use `--call` with `--buf` to invoke
+partial functions with valid data instead.
+
+The `--call` mode parses the `// func` signature, allocates the requested
+buffers (`zero`, `ones`, `seq`, or a hex blob), builds the ABI0 argument
+block with buffer pointers/lengths/capacities at the matching parameter
+offsets, and prints the arg block before and after the call — showing
+return values and any output written to the buffers.
+
+## `gasm debug --func <name> [--buf spec] <file.s>`
+
+Interactive debugger for JIT-assembled amd64 functions. Requires a
+compiled binary on `$PATH` (not `go run`).
+
+| Flag | Description |
+|------|-------------|
+| `--func` | Function to debug (required) |
+| `--buf` | Buffer spec: `name:size:pattern[,name:size:pattern]` |
+
+REPL commands:
+
+| Command | Description |
+|---------|-------------|
+| `break <label\|addr>` | Set a breakpoint |
+| `step [n]` | Single-step n instructions |
+| `continue` | Run until next breakpoint or exit |
+| `regs` | Print general-purpose + YMM/XMM vector registers |
+| `x [addr] [len]` | Hex-dump memory |
+| `labels` | List function labels and offsets |
+| `quit` | Kill the debuggee and exit |
+
+## `gasm diff [--map old=new,...] <file1.s> <file2.s>`
+
+Compare the machine code produced by assembling two files. Shows which
+functions differ and the first few differing bytes. Useful for verifying
+that two implementations produce identical code, or for tracking encoding
+changes between Go assembler versions.
+
+| Flag | Description |
+|------|-------------|
+| `--map` | Comma-separated `old=new` pairs to match functions with different names |
+
+Without `--map`, functions are paired by exact name. With `--map`, a
+function named `old` in the first file is compared against the function
+named `new` in the second file (e.g. `--map wideCopyAVX2=wideCopyAVX512`
+pairs AVX2 and AVX-512 variants regardless of suffix).
+
+## `gasm profile <file.s>`
+
+Show the basic-block structure of functions in an assembly file. Lists
+each function's labels, their offsets, and the block boundaries. This is
+the static structure; for runtime execution counts, use `gasm verify
+--fuzz` which exercises the code paths.
+
+## `gasm lsp`
+
+Run the language server over standard input/output (JSON-RPC 2.0 with
+Content-Length framing). Point an LSP-capable editor at the binary and
+associate it with `.s` files. The target architecture is inferred from
+the file-name suffix (`_amd64.s`, `_arm64.s`, `_riscv64.s`,
+`_loong64.s`).
+
+Provides: completion, hover, document symbols, diagnostics, and
+semantic-token highlighting.

docs/development.md

@@ -0,0 +1,108 @@
+# Development Guide
+
+Repository: [sourcedock.dev/petrbalvin/gasm-devkit](https://sourcedock.dev/petrbalvin/gasm-devkit)
+
+## Prerequisites
+
+- **Go** 1.26+ with `toolchain go1.26.5`
+- **just** — the command runner; every task below is a just recipe
+- No external dependencies beyond the Go toolchain
+
+## Quick Start
+
+```sh
+git clone https://sourcedock.dev/petrbalvin/gasm-devkit.git
+cd gasm-devkit
+just install   # go mod download
+just build     # go vet + gofmt — must pass with zero output
+just test      # full suite, race detector, 80 % coverage gate
+```
+
+## Just Recipes
+
+### `just build`
+
+Runs `go vet ./...` and checks `gofmt -l .` produces no output. This is
+the minimum bar before any commit.
+
+### `just test`
+
+```sh
+go test -race -count=1 -coverprofile=coverage.out ./...
+```
+
+Plus an `awk` gate that fails if total coverage is below 80 %.
+
+### `just fmt`
+
+```sh
+gofmt -w .
+```
+
+Run after editing any Go source. The output must be idempotent.
+
+### `just run -- <args>`
+
+Runs the CLI via `go run` with the version string stamped:
+
+```sh
+just run -- lint kernel_amd64.s
+just run -- fmt -w kernel_amd64.s
+just run -- verify --ground-truth kernel_amd64.s
+```
+
+### `just install-bin`
+
+Installs the `gasm` binary into `$GOBIN` with the release version
+embedded via `-ldflags "-X main.version=..."`.
+
+### `just gen`
+
+Regenerates the architecture instruction tables in `arch/` by parsing
+the Go toolchain's own assembler source
+(`$GOROOT/src/cmd/internal/obj/<arch>/anames.go`). Requires a Go
+installation. Output is committed — no runtime dependency on the
+toolchain.
+
+### `just uninstall`
+
+Removes `coverage.out`, the `gasm` binary, and `*.test` artefacts.
+
+## Running Individual Tests
+
+```sh
+go test -run TestVexGroundTruth ./asm/
+go test -run TestDifferentialLZ4Fuzz ./verify/
+go test -run TestFLACDecorrelate ./verify/
+go test -run TestGOObjectLinkAndRun ./asm/
+```
+
+## Debugger Note
+
+`gasm debug` spawns a child process from the binary on `$PATH`. It does
+not work with `go run` — install first:
+
+```sh
+just install-bin
+gasm debug --func decodeBlockAVX2 path/to/kernel_amd64.s
+```
+
+## Project Layout
+
+```
+cmd/gasm/           CLI entry point (subcommands)
+token/              Lexical token kinds and positions
+lexer/              Hand-written scanner
+ast/                Abstract syntax tree
+parser/             Line-oriented parser
+arch/               Register and instruction tables (generated)
+lint/               Static analysis rules
+format/             Canonical formatter
+lsp/                Language Server Protocol server
+asm/                Standalone assembler, encoder, object emitters
+verify/             JIT execution, differential testing, ABI checks
+debug/              Interactive ptrace debugger (linux/amd64)
+_gen/               Instruction table generator
+testdata/           Test fixtures
+docs/               Architecture, development, CLI reference
+```

format/format_test.go

@@ -5,7 +5,6 @@ package format
 
 import (
 	"os"
-	"path/filepath"
 	"strings"
 	"testing"
 
@@ -172,11 +171,9 @@ func TestIdempotent(t *testing.T) {
 }
 
 // TestRoundTrip checks that formatting produces source that still parses
-// cleanly, on the fixture and on the real go-flac kernels when present.
+// cleanly on the in-repository fixture.
 func TestRoundTrip(t *testing.T) {
 	files := []string{"../testdata/sample_amd64.s"}
-	real, _ := filepath.Glob("../../go-libraries/go-*/*.s")
-	files = append(files, real...)
 	for _, path := range files {
 		src, err := os.ReadFile(path)
 		if err != nil {

format/integration_test.go

@@ -0,0 +1,40 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build integration
+
+// Package format integration tests against the production go-libraries kernels.
+// Excluded from the default test run so coverage is identical locally and in CI.
+// Run explicitly with:  go test -tags=integration ./format/
+package format
+
+import (
+	"os"
+	"path/filepath"
+	"strings"
+	"testing"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+)
+
+// TestRoundTripRealGoLibraries checks that formatting the production kernels
+// still produces source that parses cleanly.
+func TestRoundTripRealGoLibraries(t *testing.T) {
+	real, _ := filepath.Glob("../../go-libraries/go-*/*.s")
+	if len(real) == 0 {
+		t.Skip("go-libraries repository not present")
+	}
+	for _, path := range real {
+		src, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		formatted := Source(path, string(src))
+		if _, errs := parser.Parse(path, formatted); len(errs) > 0 {
+			t.Errorf("formatted %s no longer parses: %v", path, errs)
+		}
+		if strings.TrimSpace(formatted) == "" {
+			t.Errorf("formatted %s is empty", path)
+		}
+	}
+}

justfile

@@ -3,7 +3,7 @@
 
 # gasm-devkit — developer tooling for Go's Plan 9 assembler (GAsm).
 
-version := "0.20.0"
+version := "0.29.0"
 
 default:
     @just --list
@@ -18,8 +18,21 @@ build:
     @test -z "$(gofmt -l .)" || { echo "gofmt diff:"; gofmt -l .; exit 1; }
 
 # Full test suite + race detector + 80 % coverage gate.
+# The coverage gate matches CI: it excludes packages that need hardware or
+# are CLI glue (debug, cmd/gasm), so the number is identical locally and in CI.
 test:
-    go test -race -count=1 -coverprofile=coverage.out ./...
+    go test -race -count=1 ./...
+    go test -count=1 -coverprofile=coverage.out \
+        sourcedock.dev/petrbalvin/gasm-devkit/arch \
+        sourcedock.dev/petrbalvin/gasm-devkit/asm \
+        sourcedock.dev/petrbalvin/gasm-devkit/ast \
+        sourcedock.dev/petrbalvin/gasm-devkit/format \
+        sourcedock.dev/petrbalvin/gasm-devkit/lexer \
+        sourcedock.dev/petrbalvin/gasm-devkit/lint \
+        sourcedock.dev/petrbalvin/gasm-devkit/lsp \
+        sourcedock.dev/petrbalvin/gasm-devkit/parser \
+        sourcedock.dev/petrbalvin/gasm-devkit/token \
+        sourcedock.dev/petrbalvin/gasm-devkit/verify
     go tool cover -func=coverage.out | awk '/^total:/{gsub("%","",$3);if($3+0<80){print "coverage "$3"% < 80%";exit 1}print "coverage "$3"%"}'
 
 # Format all Go sources.

lint/integration_test.go

@@ -0,0 +1,44 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build integration
+
+// Package lint integration tests against the production go-libraries kernels.
+// Excluded from the default test run so coverage is identical locally and in CI.
+// Run explicitly with:  go test -tags=integration ./lint/
+package lint
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+
+	"sourcedock.dev/petrbalvin/gasm-devkit/arch"
+	"sourcedock.dev/petrbalvin/gasm-devkit/parser"
+)
+
+// TestRealGoLibrariesHasNoErrors asserts that the production go-flac kernels
+// lint free of errors.
+func TestRealGoLibrariesHasNoErrors(t *testing.T) {
+	matches, _ := filepath.Glob("../../go-libraries/go-*/*.s")
+	if len(matches) == 0 {
+		t.Skip("go-libraries repository not present")
+	}
+	for _, path := range matches {
+		src, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatal(err)
+		}
+		f, errs := parser.Parse(path, string(src))
+		if len(errs) > 0 {
+			t.Fatalf("parse %s: %v", path, errs)
+		}
+		a := arch.FromFilename(path)
+		diags := File(f, Config{Arch: a})
+		for _, d := range diags {
+			if d.Severity == Error {
+				t.Errorf("%s: %s %s: %s", filepath.Base(path), d.Pos, d.Code, d.Message)
+			}
+		}
+	}
+}

lint/lint_test.go

@@ -5,7 +5,6 @@ package lint
 
 import (
 	"os"
-	"path/filepath"
 	"testing"
 
 	"sourcedock.dev/petrbalvin/gasm-devkit/arch"
@@ -234,29 +233,3 @@ TEXT ·f(SB), NOSPLIT, $0
 		t.Fatalf("label rules should be suppressed in macro files: %+v", diags)
 	}
 }
-
-// TestRealGoLibrariesHasNoErrors asserts that the production go-flac kernels
-// lint free of errors.  Skipped when the sibling repository is absent.
-func TestRealGoLibrariesHasNoErrors(t *testing.T) {
-	matches, _ := filepath.Glob("../../go-libraries/go-*/*.s")
-	if len(matches) == 0 {
-		t.Skip("go-libraries repository not present")
-	}
-	for _, path := range matches {
-		src, err := os.ReadFile(path)
-		if err != nil {
-			t.Fatal(err)
-		}
-		f, errs := parser.Parse(path, string(src))
-		if len(errs) > 0 {
-			t.Fatalf("parse %s: %v", path, errs)
-		}
-		a := arch.FromFilename(path)
-		diags := File(f, Config{Arch: a})
-		for _, d := range diags {
-			if d.Severity == Error {
-				t.Errorf("%s: %s %s: %s", filepath.Base(path), d.Pos, d.Code, d.Message)
-			}
-		}
-	}
-}

lsp/handlers.go

@@ -90,6 +90,41 @@ func (s *Server) hover(p hoverParams) *Hover {
 	}
 }
 
+// definition returns the location of the label definition for a label reference.
+func (s *Server) definition(p definitionParams) []Location {
+	text := s.docs[p.TextDocument.URI]
+	word, _ := wordAt(text, p.Position)
+	if word == "" {
+		return nil
+	}
+
+	// Parse the document to find label definitions.
+	f, errs := parser.Parse(uriPath(p.TextDocument.URI), text)
+	if f == nil || len(errs) > 0 {
+		return nil
+	}
+
+	// Find the label definition.
+	for _, d := range f.Decls {
+		if t, ok := d.(*ast.Text); ok {
+			for _, stmt := range t.Body {
+				if lbl, ok := stmt.(*ast.Label); ok {
+					if lbl.Name.Text == word {
+						return []Location{{
+							URI: p.TextDocument.URI,
+							Range: Range{
+								Start: Position{Line: lbl.Name.Pos.Line - 1, Character: lbl.Name.Pos.Column - 1},
+								End:   Position{Line: lbl.Name.Pos.Line - 1, Character: lbl.Name.Pos.Column - 1 + len(word)},
+							},
+						}}
+					}
+				}
+			}
+		}
+	}
+	return nil
+}
+
 // documentSymbols returns functions and their labels, plus global symbols.
 func (s *Server) documentSymbols(p documentSymbolParams) []DocumentSymbol {
 	text := s.docs[p.TextDocument.URI]

lsp/protocol.go

@@ -152,6 +152,11 @@ type hoverParams struct {
 	Position     Position               `json:"position"`
 }
 
+type definitionParams struct {
+	TextDocument textDocumentIdentifier `json:"textDocument"`
+	Position     Position               `json:"position"`
+}
+
 // Hover is the hover response.
 type Hover struct {
 	Contents markupContent `json:"contents"`

lsp/server.go

@@ -170,6 +170,11 @@ func (s *Server) dispatch(msg *rpcMessage) (exit bool) {
 		json.Unmarshal(msg.Params, &p)
 		s.respond(msg.ID, s.hover(p))
 
+	case "textDocument/definition":
+		var p definitionParams
+		json.Unmarshal(msg.Params, &p)
+		s.respond(msg.ID, s.definition(p))
+
 	case "textDocument/documentSymbol":
 		var p documentSymbolParams
 		json.Unmarshal(msg.Params, &p)

parser/integration_test.go

@@ -0,0 +1,39 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+//go:build integration
+
+// Package parser integration tests against the production go-libraries kernels.
+// Excluded from the default test run so coverage is identical locally and in CI.
+// Run explicitly with:  go test -tags=integration ./parser/
+package parser
+
+import (
+	"os"
+	"path/filepath"
+	"testing"
+)
+
+// TestParseRealGoLibraries parses every .s file in the sibling go-libraries
+// repository when it is checked out, asserting a clean, error-free parse.
+func TestParseRealGoLibraries(t *testing.T) {
+	matches, _ := filepath.Glob("../../go-libraries/go-*/*.s")
+	if len(matches) == 0 {
+		t.Skip("go-libraries repository not present next to gasm-devkit")
+	}
+	for _, path := range matches {
+		src, err := os.ReadFile(path)
+		if err != nil {
+			t.Fatalf("read %s: %v", path, err)
+		}
+		file, errs := Parse(path, string(src))
+		if len(errs) > 0 {
+			t.Errorf("parse %s: %v", path, errs)
+			continue
+		}
+		if len(texts(file)) == 0 {
+			t.Errorf("parse %s: no TEXT functions found", path)
+		}
+		t.Logf("%s: %d decls, %d functions", filepath.Base(path), len(file.Decls), len(texts(file)))
+	}
+}

parser/parser.go

@@ -398,10 +398,15 @@ func parseAddress(g []token.Token) ast.Address {
 		return addr
 	}
 	// Symbol-with-pseudo form: name[<>][+off](PSEUDO).
+	// When the prefix is not a valid symbol name (e.g. a bare number like
+	// 0(SP) in RISC-V), sym is nil and we fall through to regular memory
+	// operand parsing instead of returning an empty address.
 	if idx := findPseudoParen(g); idx >= 0 {
 		sym, _ := parseSymbolPrefix(g[:idx+3])
-		addr.Sym = sym
-		return addr
+		if sym != nil {
+			addr.Sym = sym
+			return addr
+		}
 	}
 
 	i := 0

parser/parser_test.go

@@ -5,7 +5,6 @@ package parser
 
 import (
 	"os"
-	"path/filepath"
 	"testing"
 
 	"sourcedock.dev/petrbalvin/gasm-devkit/ast"
@@ -254,28 +253,3 @@ func TestDataWidthAndStatic(t *testing.T) {
 		t.Errorf("mask24 DATA should be static, got %+v", datas[2].Name)
 	}
 }
-
-// TestParseRealGoLibraries parses every .s file in the sibling go-libraries
-// repository when it is checked out, asserting a clean, error-free parse.  It
-// is skipped when the repository is not present.
-func TestParseRealGoLibraries(t *testing.T) {
-	matches, _ := filepath.Glob("../../go-libraries/go-*/*.s")
-	if len(matches) == 0 {
-		t.Skip("go-libraries repository not present next to gasm-devkit")
-	}
-	for _, path := range matches {
-		src, err := os.ReadFile(path)
-		if err != nil {
-			t.Fatalf("read %s: %v", path, err)
-		}
-		file, errs := Parse(path, string(src))
-		if len(errs) > 0 {
-			t.Errorf("parse %s: %v", path, errs)
-			continue
-		}
-		if len(texts(file)) == 0 {
-			t.Errorf("parse %s: no TEXT functions found", path)
-		}
-		t.Logf("%s: %d decls, %d functions", filepath.Base(path), len(file.Decls), len(texts(file)))
-	}
-}

testdata/add_riscv64.s

@@ -0,0 +1,12 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+#include "textflag.h"
+
+// func add(a, b int64) int64
+TEXT ·add(SB), NOSPLIT, $0-24
+        MOV a+0(FP), X10
+        MOV b+8(FP), X11
+        ADD X11, X10, X10
+        MOV X10, ret+16(FP)
+        RET

testdata/amo_fp_riscv64.s

@@ -0,0 +1,20 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+#include "textflag.h"
+
+// func atomicAdd(ptr *int64, val int64) int64
+TEXT ·atomicAdd(SB), NOSPLIT, $0-24
+        MOV a+0(FP), X10
+        MOV b+8(FP), X11
+        AMOADDD X11, (X10), X12
+        MOV X12, ret+16(FP)
+        RET
+
+// func fpAdd(a, b float64) float64
+TEXT ·fpAdd(SB), NOSPLIT, $0-24
+        FLD a+0(FP), F10
+        FLD b+8(FP), F11
+        FADDD F10, F11, F12
+        FSD F12, ret+16(FP)
+        RET

testdata/csr_riscv64.s

@@ -0,0 +1,26 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+#include "textflag.h"
+
+// func readCSR(csr int64) int64
+TEXT ·readCSR(SB), NOSPLIT, $0-16
+        MOV a+0(FP), X10
+        CSRRS $0x300, X0, X11
+        MOV X11, ret+8(FP)
+        RET
+
+// func setCSRBit(csr, bit int64) int64
+TEXT ·setCSRBit(SB), NOSPLIT, $0-24
+        MOV a+0(FP), X10
+        MOV b+8(FP), X11
+        CSRRS $0x304, X11, X12
+        MOV X12, ret+16(FP)
+        RET
+
+// func writeCSR(val int64) int64
+TEXT ·writeCSR(SB), NOSPLIT, $0-16
+        MOV a+0(FP), X10
+        CSRRW $0x305, X10, X11
+        MOV X11, ret+8(FP)
+        RET

testdata/fma_riscv64.s

@@ -0,0 +1,22 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+#include "textflag.h"
+
+// func fma(a, b, c float64) float64
+TEXT ·fma(SB), NOSPLIT, $0-32
+        FLD a+0(FP), F10
+        FLD b+8(FP), F11
+        FLD c+16(FP), F12
+        FMADDD F10, F11, F12, F13
+        FSD F13, ret+24(FP)
+        RET
+
+// func fms(a, b, c float64) float64
+TEXT ·fms(SB), NOSPLIT, $0-32
+        FLD a+0(FP), F10
+        FLD b+8(FP), F11
+        FLD c+16(FP), F12
+        FMSUBD F10, F11, F12, F13
+        FSD F13, ret+24(FP)
+        RET

testdata/lrsc_cvt_riscv64.s

@@ -0,0 +1,36 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+#include "textflag.h"
+
+// func casLoop(ptr *int64, old, new int64) bool
+TEXT ·casLoop(SB), NOSPLIT, $0-32
+cas_retry:
+        MOV a+0(FP), X10
+        LRD (X10), X11
+        MOV b+8(FP), X12
+        BNE X11, X12, cas_fail
+        MOV c+16(FP), X13
+        SCD X13, (X10), X14
+        BNE X14, X0, cas_retry
+        ADDI X0, $1, X15
+        MOV X15, ret+24(FP)
+        RET
+cas_fail:
+        MOV X0, ret+24(FP)
+        RET
+
+// func intToFloat(x int64) float64
+TEXT ·intToFloat(SB), NOSPLIT, $0-16
+        MOV a+0(FP), X10
+        FCVTDL X10, F10
+        FSD F10, ret+8(FP)
+        RET
+
+// func compare(a, b float64) bool
+TEXT ·compare(SB), NOSPLIT, $0-24
+        FLD a+0(FP), F10
+        FLD b+8(FP), F11
+        FLTD F10, F11, X10
+        MOV X10, ret+16(FP)
+        RET

verify/abi_test.go

@@ -5,7 +5,6 @@ package verify
 
 import (
 	"testing"
-	"unsafe"
 )
 
 func loadABIKernel(t *testing.T) *Kernel {
@@ -79,55 +78,6 @@ func TestABIR14Clobbered(t *testing.T) {
 	}
 }
 
-// TestABILZ4Kernels verifies that the production go-lz4 kernels are ABI-clean:
-// they preserve BP and R14 and do not write into the red zone.
-func TestABILZ4Kernels(t *testing.T) {
-	k := loadLZ4Kernel(t)
-
-	// wideCopyAVX2 with a real copy.
-	src := make([]byte, 128)
-	for i := range src {
-		src[i] = byte(i)
-	}
-	dst := make([]byte, 128)
-
-	args := make([]byte, 48)
-	PutPtr(args, 0, unsafe.Pointer(&dst[0]))
-	PutUint64(args, 8, 128)
-	PutUint64(args, 16, 128)
-	PutPtr(args, 24, unsafe.Pointer(&src[0]))
-	PutUint64(args, 32, 128)
-	PutUint64(args, 40, 128)
-
-	_, report, err := k.CallFuncChecked("wideCopyAVX2", args)
-	if err != nil {
-		t.Fatalf("CallFuncChecked(wideCopyAVX2): %v", err)
-	}
-	if !report.OK() {
-		t.Errorf("wideCopyAVX2: %s", report)
-	}
-
-	// decodeBlockAVX2 with a simple block.
-	decSrc := []byte{0x50, 'H', 'e', 'l', 'l', 'o'}
-	decDst := make([]byte, 64)
-
-	decArgs := make([]byte, 64)
-	PutPtr(decArgs, 0, unsafe.Pointer(&decSrc[0]))
-	PutUint64(decArgs, 8, uint64(len(decSrc)))
-	PutUint64(decArgs, 16, uint64(cap(decSrc)))
-	PutPtr(decArgs, 24, unsafe.Pointer(&decDst[0]))
-	PutUint64(decArgs, 32, uint64(len(decDst)))
-	PutUint64(decArgs, 40, uint64(cap(decDst)))
-
-	_, report, err = k.CallFuncChecked("decodeBlockAVX2", decArgs)
-	if err != nil {
-		t.Fatalf("CallFuncChecked(decodeBlockAVX2): %v", err)
-	}
-	if !report.OK() {
-		t.Errorf("decodeBlockAVX2: %s", report)
-	}
-}
-
 func TestCallFuncCheckedErrors(t *testing.T) {
 	k := loadABIKernel(t)
 

verify/buffers.go

@@ -0,0 +1,150 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package verify
+
+import (
+	"encoding/binary"
+	"encoding/hex"
+	"fmt"
+	"strings"
+	"unsafe"
+)
+
+// BufSpec is one buffer allocation request parsed from the user's --buf spec.
+type BufSpec struct {
+	Name    string
+	Size    int    // declared slice length and capacity
+	Pattern string // "zero", "ones", "seq", or a hex blob
+}
+
+// ParseBufSpec parses a "name:size:pattern[,name:size:pattern]" spec string
+// into individual buffer specs.  Empty input yields an empty slice.
+func ParseBufSpec(spec string) ([]BufSpec, error) {
+	if spec == "" {
+		return nil, nil
+	}
+	var out []BufSpec
+	for _, part := range strings.Split(spec, ",") {
+		fields := strings.SplitN(part, ":", 3)
+		if len(fields) != 3 {
+			return nil, fmt.Errorf("verify: invalid buffer spec %q (expected name:size:pattern)", part)
+		}
+		var size int
+		if _, err := fmt.Sscanf(fields[1], "%d", &size); err != nil || size <= 0 {
+			return nil, fmt.Errorf("verify: invalid buffer size %q in %q", fields[1], part)
+		}
+		out = append(out, BufSpec{Name: fields[0], Size: size, Pattern: fields[2]})
+	}
+	return out, nil
+}
+
+// allocatedBuf is one live buffer in a pool.
+type allocatedBuf struct {
+	spec BufSpec
+	data []byte // Size + safetyMargin bytes; the first Size are the live region
+}
+
+// safetyMargin is the extra bytes allocated past the declared size so SIMD
+// over-reads and functions that read slightly past len never touch unmapped
+// memory.  Matches the margin used by the fuzz generator.
+const safetyMargin = 8192
+
+// BufPool is a set of allocated buffers held alive for the duration of one or
+// more calls.  Buffers live on the Go heap (the JIT call is in-process); the
+// pool keeps the backing slices referenced so the GC does not collect them
+// before the call returns.
+type BufPool struct {
+	bufs []allocatedBuf
+}
+
+// Alloc allocates and fills the buffers described by specs.  The returned
+// pool must be kept alive until every call using it has returned.
+func (p *BufPool) Alloc(specs []BufSpec) error {
+	for _, s := range specs {
+		data := make([]byte, s.Size+safetyMargin)
+		fillBuffer(data, s.Pattern)
+		p.bufs = append(p.bufs, allocatedBuf{spec: s, data: data})
+	}
+	return nil
+}
+
+// Close releases the pool.  No-op for Go-heap buffers, but keeps the API
+// symmetric with debug's mmap-backed pool.
+func (p *BufPool) Close() {
+	p.bufs = nil
+}
+
+// findByName returns the buffer with the given spec name, if any.
+func (p *BufPool) findByName(name string) *allocatedBuf {
+	for i := range p.bufs {
+		if p.bufs[i].spec.Name == name {
+			return &p.bufs[i]
+		}
+	}
+	return nil
+}
+
+// BuildArgs constructs an ABI0 argument block of argSize bytes for the given
+// layout, placing each buffer's pointer/length/capacity at the matching
+// parameter offset.  Parameters whose names match a buffer spec get the
+// buffer address; non-pointer parameters and unmatched pointers are zeroed.
+//
+// Matching is by exact name, then by prefix (a buffer named "src" matches a
+// parameter named "src" or "srcBuf"), mirroring the debug allocator.
+func (p *BufPool) BuildArgs(layout []ArgOffset, argSize int) []byte {
+	args := make([]byte, argSize)
+	for _, a := range layout {
+		if !a.IsPtr {
+			continue
+		}
+		buf := p.matchBuf(a.Name)
+		if buf == nil {
+			continue
+		}
+		if a.Offset+8 <= len(args) {
+			binary.LittleEndian.PutUint64(args[a.Offset:a.Offset+8], uint64(uintptr(unsafe.Pointer(&buf.data[0]))))
+		}
+		if strings.HasPrefix(a.Typ, "[]") && a.Offset+24 <= len(args) {
+			binary.LittleEndian.PutUint64(args[a.Offset+8:a.Offset+16], uint64(buf.spec.Size))
+			binary.LittleEndian.PutUint64(args[a.Offset+16:a.Offset+24], uint64(buf.spec.Size))
+		}
+	}
+	return args
+}
+
+// matchBuf finds a buffer matching the parameter name (exact, then prefix).
+func (p *BufPool) matchBuf(name string) *allocatedBuf {
+	if b := p.findByName(name); b != nil {
+		return b
+	}
+	for i := range p.bufs {
+		if strings.HasPrefix(name, p.bufs[i].spec.Name) {
+			return &p.bufs[i]
+		}
+	}
+	return nil
+}
+
+// fillBuffer fills buf with the named pattern: "zero" (no-op, already zeroed),
+// "ones" (0xFF), "seq" (i mod 256), or a hex blob repeated to fill.
+func fillBuffer(buf []byte, pattern string) {
+	switch pattern {
+	case "zero":
+		// Already zeroed by make.
+	case "ones":
+		for i := range buf {
+			buf[i] = 0xFF
+		}
+	case "seq":
+		for i := range buf {
+			buf[i] = byte(i)
+		}
+	default:
+		if data, err := hex.DecodeString(pattern); err == nil && len(data) > 0 {
+			for i := range buf {
+				buf[i] = data[i%len(data)]
+			}
+		}
+	}
+}

verify/buffers_test.go

@@ -0,0 +1,158 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package verify
+
+import (
+	"testing"
+)
+
+func TestParseParamsExported(t *testing.T) {
+	tests := []struct {
+		input string
+		names []string
+		types []string
+		isPtr []bool
+	}{
+		{
+			input: "dst []byte, src []byte",
+			names: []string{"dst", "src"},
+			types: []string{"[]byte", "[]byte"},
+			isPtr: []bool{true, true},
+		},
+		{
+			input: "dst, src []byte",
+			names: []string{"dst", "src"},
+			types: []string{"[]byte", "[]byte"},
+			isPtr: []bool{true, true},
+		},
+		{
+			input: "a, b int",
+			names: []string{"a", "b"},
+			types: []string{"int", "int"},
+			isPtr: []bool{false, false},
+		},
+		{
+			input: "src []byte, dst []byte",
+			names: []string{"src", "dst"},
+			types: []string{"[]byte", "[]byte"},
+			isPtr: []bool{true, true},
+		},
+		{
+			input: "swin []int32, dstP []uint32, hist *[32]uint16",
+			names: []string{"swin", "dstP", "hist"},
+			types: []string{"[]int32", "[]uint32", "*[32]uint16"},
+			isPtr: []bool{true, true, true},
+		},
+		{
+			input: "n int, code int",
+			names: []string{"n", "code"},
+			types: []string{"int", "int"},
+			isPtr: []bool{false, false},
+		},
+	}
+	for _, tt := range tests {
+		params := parseParamsExported(tt.input)
+		if len(params) != len(tt.names) {
+			t.Errorf("parseParamsExported(%q): got %d params, want %d", tt.input, len(params), len(tt.names))
+			continue
+		}
+		for i, p := range params {
+			if p.Name != tt.names[i] {
+				t.Errorf("parseParamsExported(%q)[%d].Name = %q, want %q", tt.input, i, p.Name, tt.names[i])
+			}
+			if p.Typ != tt.types[i] {
+				t.Errorf("parseParamsExported(%q)[%d].Typ = %q, want %q", tt.input, i, p.Typ, tt.types[i])
+			}
+			if p.IsPointer() != tt.isPtr[i] {
+				t.Errorf("parseParamsExported(%q)[%d].IsPointer() = %v, want %v", tt.input, i, p.IsPointer(), tt.isPtr[i])
+			}
+		}
+	}
+}
+
+func TestParseBufSpec(t *testing.T) {
+	t.Run("empty", func(t *testing.T) {
+		specs, err := ParseBufSpec("")
+		if err != nil || len(specs) != 0 {
+			t.Errorf("ParseBufSpec(\"\") = %v, %v; want nil, nil", specs, err)
+		}
+	})
+
+	t.Run("single", func(t *testing.T) {
+		specs, err := ParseBufSpec("dst:64:zero")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(specs) != 1 || specs[0].Name != "dst" || specs[0].Size != 64 || specs[0].Pattern != "zero" {
+			t.Errorf("ParseBufSpec(\"dst:64:zero\") = %+v; want [{dst 64 zero}]", specs)
+		}
+	})
+
+	t.Run("multiple", func(t *testing.T) {
+		specs, err := ParseBufSpec("dst:64:zero,src:128:seq")
+		if err != nil {
+			t.Fatal(err)
+		}
+		if len(specs) != 2 {
+			t.Fatalf("got %d specs, want 2", len(specs))
+		}
+		if specs[0].Name != "dst" || specs[1].Name != "src" {
+			t.Errorf("names = %s, %s; want dst, src", specs[0].Name, specs[1].Name)
+		}
+	})
+
+	t.Run("invalid", func(t *testing.T) {
+		_, err := ParseBufSpec("bad")
+		if err == nil {
+			t.Error("ParseBufSpec(\"bad\") should error")
+		}
+	})
+
+	t.Run("zero-size", func(t *testing.T) {
+		_, err := ParseBufSpec("dst:0:zero")
+		if err == nil {
+			t.Error("ParseBufSpec(\"dst:0:zero\") should error on zero size")
+		}
+	})
+}
+
+func TestBufPoolBuildArgs(t *testing.T) {
+	specs, err := ParseBufSpec("dst:64:seq,src:128:zero")
+	if err != nil {
+		t.Fatal(err)
+	}
+	var pool BufPool
+	if err := pool.Alloc(specs); err != nil {
+		t.Fatal(err)
+	}
+	defer pool.Close()
+
+	// Layout for wideCopyAVX2(dst, src []byte): dst at 0, src at 24.
+	layout := []ArgOffset{
+		{Name: "dst", Typ: "[]byte", Offset: 0, Size: 24, IsPtr: true},
+		{Name: "src", Typ: "[]byte", Offset: 24, Size: 24, IsPtr: true},
+	}
+	args := pool.BuildArgs(layout, 48)
+
+	// dst.ptr should be non-zero.
+	if args[0] == 0 && args[1] == 0 && args[2] == 0 && args[3] == 0 {
+		t.Error("dst.ptr is zero; expected a buffer address")
+	}
+	// dst.len should be 64 (0x40).
+	if args[8] != 0x40 {
+		t.Errorf("dst.len = %d, want 64", args[8])
+	}
+	// dst.cap should be 64.
+	if args[16] != 0x40 {
+		t.Errorf("dst.cap = %d, want 64", args[16])
+	}
+	// src.ptr should be non-zero.
+	if args[24] == 0 && args[25] == 0 && args[26] == 0 && args[27] == 0 {
+		t.Error("src.ptr is zero; expected a buffer address")
+	}
+	// src.len should be 128 (0x80).
+	if args[32] != 0x80 {
+		t.Errorf("src.len = %d, want 128", args[32])
+	}
+}

verify/coverage_test.go

@@ -5,7 +5,6 @@ package verify
 
 import (
 	"testing"
-	"unsafe"
 )
 
 func TestBlocks(t *testing.T) {
@@ -24,62 +23,3 @@ func TestBlocks(t *testing.T) {
 	}
 	t.Logf("sum blocks: %v", blocks)
 }
-
-func TestBlockCount(t *testing.T) {
-	k := loadLZ4Kernel(t)
-
-	n, err := k.BlockCount("decodeBlockAVX2")
-	if err != nil {
-		t.Fatalf("BlockCount: %v", err)
-	}
-	// The decoder has many labels (dec_loop, dec_malformed, etc.).
-	if n < 10 {
-		t.Errorf("decodeBlockAVX2: expected at least 10 blocks, got %d", n)
-	}
-	t.Logf("decodeBlockAVX2: %d basic blocks", n)
-}
-
-func TestProfilePaths(t *testing.T) {
-	k := loadLZ4Kernel(t)
-
-	// Build a corpus of varied LZ4 blocks.
-	var argSets [][]byte
-	blocks := []struct {
-		src     []byte
-		dstSize int
-	}{
-		{[]byte{0x00}, 16},                          // empty
-		{[]byte{0x50, 'H', 'e', 'l', 'l', 'o'}, 16}, // literals only
-		{[]byte{0x54, 'A', 'A', 'A', 'A', 'A', 5, 0, 0x30, 'B', 'B', 'B'}, 32}, // match
-		{[]byte{0x14, 'X', 1, 0, 0x10, 'Y'}, 16},                               // overlapping
-		{[]byte{0x50, 'H'}, 16},                                                // malformed
-		{[]byte{0x14, 'X', 0, 0}, 16},                                          // zero offset
-	}
-	for _, b := range blocks {
-		args := make([]byte, 64)
-		if len(b.src) > 0 {
-			PutPtr(args, 0, unsafe.Pointer(&b.src[0]))
-		}
-		PutUint64(args, 8, uint64(len(b.src)))
-		PutUint64(args, 16, uint64(cap(b.src)))
-		dst := make([]byte, b.dstSize)
-		if len(dst) > 0 {
-			PutPtr(args, 24, unsafe.Pointer(&dst[0]))
-		}
-		PutUint64(args, 32, uint64(len(dst)))
-		PutUint64(args, 40, uint64(cap(dst)))
-		argSets = append(argSets, args)
-	}
-
-	// Result offsets: n+48 and code+56.
-	paths, err := k.ProfilePaths("decodeBlockAVX2", argSets, []int{48, 56})
-	if err != nil {
-		t.Fatalf("ProfilePaths: %v", err)
-	}
-
-	// We expect at least 3 distinct paths: success (various n), malformed, zero offset.
-	if len(paths) < 3 {
-		t.Errorf("expected at least 3 distinct paths, got %d", len(paths))
-	}
-	t.Logf("decodeBlockAVX2: %d distinct output paths from %d inputs", len(paths), len(argSets))
-}

verify/differential_test.go

@@ -1,295 +0,0 @@
-// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
-// SPDX-License-Identifier: BSD-3-Clause
-
-package verify
-
-import (
-	"bytes"
-	"math/rand"
-	"testing"
-	"unsafe"
-)
-
-// decodeBlockGo is a minimal portable LZ4 block decoder used as the
-// differential-testing oracle.  It mirrors the contract of
-// go-lz4's decodeBlockGo: (bytesWritten, code) where code is
-// 0 = ok, 1 = malformed, 2 = zero offset.
-func decodeBlockGo(src, dst []byte) (int, int) {
-	if len(src) == 0 {
-		return 0, 1
-	}
-	si, di := 0, 0
-	for {
-		if si >= len(src) {
-			return 0, 1 // truncated: no token
-		}
-		token := int(src[si])
-		si++
-
-		// Literals.
-		lLen := token >> 4
-		if lLen == 15 {
-			for {
-				if si >= len(src) {
-					return 0, 1
-				}
-				b := int(src[si])
-				si++
-				lLen += b
-				if b != 255 {
-					break
-				}
-			}
-		}
-		if si+lLen > len(src) {
-			return 0, 1 // truncated literals
-		}
-		if di+lLen > len(dst) {
-			return 0, 1 // destination overflow
-		}
-		copy(dst[di:di+lLen], src[si:si+lLen])
-		di += lLen
-		si += lLen
-
-		// End of block.
-		if si >= len(src) {
-			return di, 0
-		}
-
-		// Match offset.
-		if si+2 > len(src) {
-			return 0, 1
-		}
-		offset := int(src[si]) | int(src[si+1])<<8
-		si += 2
-		if offset == 0 {
-			return 0, 2
-		}
-
-		// Match length.
-		mLen := token & 15
-		if mLen == 15 {
-			for {
-				if si >= len(src) {
-					return 0, 1
-				}
-				b := int(src[si])
-				si++
-				mLen += b
-				if b != 255 {
-					break
-				}
-			}
-		}
-		mLen += 4
-
-		// Copy match (overlapping-safe).
-		if di-offset < 0 {
-			return 0, 1 // offset reaches before dst start
-		}
-		if di+mLen > len(dst) {
-			return 0, 1 // destination overflow
-		}
-		for i := 0; i < mLen; i++ {
-			dst[di+i] = dst[di-offset+i]
-		}
-		di += mLen
-	}
-}
-
-// genLZ4Block generates a random valid LZ4 block that decompresses into
-// approximately wantSize bytes.  The block is always well-formed (ends with
-// a literals-only sequence).
-func genLZ4Block(rng *rand.Rand, wantSize int) []byte {
-	var block []byte
-	produced := 0
-	for produced < wantSize {
-		remaining := wantSize - produced
-
-		// Decide: emit a literals+match sequence or the final literals.
-		if remaining <= 8 || rng.Intn(4) == 0 {
-			// Final literals-only sequence.
-			lLen := remaining
-			if lLen > 60 {
-				lLen = 1 + rng.Intn(60)
-			}
-			block = appendToken(block, lLen, 0)
-			for i := 0; i < lLen; i++ {
-				block = append(block, byte(rng.Intn(256)))
-			}
-			produced += lLen
-			break
-		}
-
-		// Literals + match.
-		lLen := rng.Intn(min(16, remaining))
-		if produced+lLen == 0 {
-			lLen = 1 // must have at least 1 literal before the first match
-		}
-		mLenRaw := rng.Intn(12) // match length = mLenRaw + 4
-		mLen := mLenRaw + 4
-		if produced+mLen > remaining {
-			mLen = remaining - produced
-			if mLen < 4 {
-				// Not enough room for a match; emit final literals.
-				lLen = remaining
-				block = appendToken(block, lLen, 0)
-				for i := 0; i < lLen; i++ {
-					block = append(block, byte(rng.Intn(256)))
-				}
-				break
-			}
-			mLenRaw = mLen - 4
-		}
-
-		block = appendToken(block, lLen, mLenRaw)
-		for i := 0; i < lLen; i++ {
-			block = append(block, byte(rng.Intn(256)))
-		}
-		produced += lLen
-
-		// Offset: must be <= produced (can't reference before start).
-		maxOff := produced
-		if maxOff > 65535 {
-			maxOff = 65535
-		}
-		offset := 1 + rng.Intn(maxOff)
-		block = append(block, byte(offset), byte(offset>>8))
-		produced += mLen
-	}
-	return block
-}
-
-// appendToken appends a token (and extension bytes if needed) for the given
-// literal and match lengths.
-func appendToken(block []byte, lLen, mLenRaw int) []byte {
-	lit4 := lLen
-	if lit4 > 15 {
-		lit4 = 15
-	}
-	ml4 := mLenRaw
-	if ml4 > 15 {
-		ml4 = 15
-	}
-	block = append(block, byte(lit4<<4|ml4))
-	// Literal extension bytes.
-	rem := lLen - 15
-	for rem >= 255 {
-		block = append(block, 255)
-		rem -= 255
-	}
-	if lLen >= 15 {
-		block = append(block, byte(rem))
-	}
-	// Match extension bytes.
-	rem = mLenRaw - 15
-	for rem >= 255 {
-		block = append(block, 255)
-		rem -= 255
-	}
-	if mLenRaw >= 15 {
-		block = append(block, byte(rem))
-	}
-	return block
-}
-
-func min(a, b int) int {
-	if a < b {
-		return a
-	}
-	return b
-}
-
-// TestDifferentialLZ4Fuzz drives the JIT-assembled decodeBlockAVX2 with
-// random valid LZ4 blocks and compares the output bit-for-bit against the
-// portable Go reference.
-func TestDifferentialLZ4Fuzz(t *testing.T) {
-	k := loadLZ4Kernel(t)
-
-	const iterations = 5000
-	rng := rand.New(rand.NewSource(42))
-
-	for i := 0; i < iterations; i++ {
-		wantSize := 1 + rng.Intn(4096)
-		src := genLZ4Block(rng, wantSize)
-		dstSize := wantSize + 64 // generous destination
-
-		// Go reference.
-		goDst := make([]byte, dstSize)
-		goN, goCode := decodeBlockGo(src, goDst)
-
-		// JIT kernel.
-		jitDst := make([]byte, dstSize)
-		jitN, jitCode := callDecodeBlockAVX2(t, k, src, jitDst)
-
-		if jitCode != goCode {
-			t.Fatalf("iter %d: code mismatch: JIT=%d, Go=%d (src len=%d)",
-				i, jitCode, goCode, len(src))
-		}
-		if jitCode != 0 {
-			continue // both agree it's malformed/zero-offset
-		}
-		if jitN != goN {
-			t.Fatalf("iter %d: n mismatch: JIT=%d, Go=%d (src len=%d)",
-				i, jitN, goN, len(src))
-		}
-		if !bytes.Equal(jitDst[:jitN], goDst[:goN]) {
-			t.Fatalf("iter %d: output mismatch (n=%d, src len=%d)", i, jitN, len(src))
-		}
-	}
-}
-
-// TestDifferentialLZ4Hostile drives the kernel with random garbage to check
-// that error codes agree with the Go reference (no crashes, same classification).
-func TestDifferentialLZ4Hostile(t *testing.T) {
-	k := loadLZ4Kernel(t)
-
-	const iterations = 2000
-	rng := rand.New(rand.NewSource(99))
-
-	for i := 0; i < iterations; i++ {
-		srcLen := rng.Intn(128)
-		src := make([]byte, srcLen)
-		rng.Read(src)
-		dstSize := rng.Intn(512)
-		dst := make([]byte, dstSize)
-
-		// Go reference.
-		goDst := make([]byte, dstSize)
-		copy(goDst, dst)
-		_, goCode := decodeBlockGo(src, goDst)
-
-		// JIT kernel.
-		jitDst := make([]byte, dstSize)
-		copy(jitDst, dst)
-		_, jitCode := callDecodeBlockAVX2(t, k, src, jitDst)
-
-		if jitCode != goCode {
-			t.Fatalf("iter %d: hostile code mismatch: JIT=%d, Go=%d (srcLen=%d, dstSize=%d)",
-				i, jitCode, goCode, srcLen, dstSize)
-		}
-	}
-}
-
-// callDecodeBlockAVX2Raw is like callDecodeBlockAVX2 but accepts explicit
-// dst size (for hostile tests where dst may be smaller than the output).
-func callDecodeBlockAVX2Raw(t *testing.T, k *Kernel, src, dst []byte) (int, int) {
-	t.Helper()
-	args := make([]byte, 64)
-	if len(src) > 0 {
-		PutPtr(args, 0, unsafe.Pointer(&src[0]))
-	}
-	PutUint64(args, 8, uint64(len(src)))
-	PutUint64(args, 16, uint64(cap(src)))
-	if len(dst) > 0 {
-		PutPtr(args, 24, unsafe.Pointer(&dst[0]))
-	}
-	PutUint64(args, 32, uint64(len(dst)))
-	PutUint64(args, 40, uint64(cap(dst)))
-
-	out, err := k.CallFunc("decodeBlockAVX2", args)
-	if err != nil {
-		t.Fatalf("CallFunc(decodeBlockAVX2): %v", err)
-	}
-	return int(GetUint64(out, 48)), int(GetUint64(out, 56))
-}

verify/fuzz.go

@@ -0,0 +1,387 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package verify
+
+import (
+	"fmt"
+	"math/rand"
+	"regexp"
+	"runtime"
+	"strconv"
+	"strings"
+	"unsafe"
+)
+
+// FuzzResult reports the outcome of a differential fuzz campaign for one
+// function.
+type FuzzResult struct {
+	Func       string
+	Iterations int
+	Matches    int
+	Mismatches int
+	FirstFail  string // description of the first mismatch ("" if none)
+	CrashInput []byte // input that caused the last crash/mismatch (nil if none)
+}
+
+// OK returns true when all iterations matched.
+func (r FuzzResult) OK() bool { return r.Mismatches == 0 }
+
+// String returns a human-readable summary.
+func (r FuzzResult) String() string {
+	if r.OK() {
+		return fmt.Sprintf("%s: %d/%d iterations match", r.Func, r.Matches, r.Iterations)
+	}
+	s := fmt.Sprintf("%s: %d/%d match, %d MISMATCH — %s",
+		r.Func, r.Matches, r.Iterations, r.Mismatches, r.FirstFail)
+	if len(r.CrashInput) > 0 {
+		s += fmt.Sprintf("\n  input: %x", r.CrashInput)
+	}
+	return s
+}
+
+// funcSig is a parsed // func signature from the assembly source.
+type funcSig struct {
+	name    string
+	params  []param
+	results []param
+}
+
+type param struct {
+	name string
+	typ  string // "[]byte", "[]int32", "int", "*[32]uint16", etc.
+}
+
+// funcSigRe matches the conventional "// func name(...)" comment.
+var funcSigRe = regexp.MustCompile(`^//\s*func\s+(\w+)\(([^)]*)\)\s*(.*)$`)
+
+// parseFuncSig extracts the function signature from a "// func ..." comment.
+func parseFuncSig(comment string) (funcSig, bool) {
+	m := funcSigRe.FindStringSubmatch(strings.TrimSpace(comment))
+	if m == nil {
+		return funcSig{}, false
+	}
+	sig := funcSig{name: m[1]}
+	sig.params = parseParams(m[2])
+	// Results may be "(a int, b int)" or "int" or "(int, error)".
+	res := strings.TrimSpace(m[3])
+	res = strings.TrimPrefix(res, "(")
+	res = strings.TrimSuffix(res, ")")
+	if res != "" {
+		sig.results = parseParams(res)
+	}
+	return sig, true
+}
+
+// parseParams splits "a []byte, b []int32" into typed parameters, handling
+// shared types ("a, b []int32").
+func parseParams(s string) []param {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return nil
+	}
+	fields := strings.Split(s, ",")
+	// First pass: extract the type from each field (if present).
+	types := make([]string, len(fields))
+	for i, field := range fields {
+		parts := strings.Fields(strings.TrimSpace(field))
+		if len(parts) >= 2 {
+			types[i] = parts[len(parts)-1]
+		}
+	}
+	// Propagate types backward: a field without a type inherits from the next
+	// field that has one (e.g. "dst" inherits "[]byte" from "src []byte").
+	for i := range fields {
+		if types[i] == "" {
+			for j := i + 1; j < len(fields); j++ {
+				if types[j] != "" {
+					types[i] = types[j]
+					break
+				}
+			}
+		}
+	}
+	var out []param
+	for i, field := range fields {
+		field = strings.TrimSpace(field)
+		if field == "" {
+			continue
+		}
+		parts := strings.Fields(field)
+		typ := types[i]
+		if typ == "" {
+			out = append(out, param{typ: parts[0]})
+		} else {
+			out = append(out, param{name: parts[0], typ: typ})
+		}
+	}
+	return out
+}
+
+// ExtractSignatures scans assembly source for "// func name(...)" comments
+// that immediately precede a TEXT directive, and returns the parsed
+// signatures keyed by the function's short name.
+func ExtractSignatures(src string) map[string]funcSig {
+	lines := strings.Split(src, "\n")
+	sigs := make(map[string]funcSig)
+	var comments []string
+	for _, line := range lines {
+		trimmed := strings.TrimSpace(line)
+		if strings.HasPrefix(trimmed, "//") {
+			comments = append(comments, trimmed)
+			continue
+		}
+		if strings.HasPrefix(trimmed, "TEXT") {
+			// Search the comment block for the // func line.
+			for _, c := range comments {
+				if sig, ok := parseFuncSig(c); ok {
+					sigs[sig.name] = sig
+					break
+				}
+			}
+			comments = nil
+			continue
+		}
+		if trimmed != "" {
+			comments = nil
+		}
+	}
+	return sigs
+}
+
+// FuzzFunc runs a differential fuzz campaign: it JIT-executes both the
+// gasm-assembled and the go-tool-asm-assembled versions of the named
+// function with random inputs derived from the // func signature, and
+// compares the output argument area bit-for-bit.
+//
+// The signature comment must appear immediately above the TEXT directive
+// in the source (the conventional Go assembly layout).
+func (k *Kernel) FuzzFunc(name string, sig funcSig, goCode []byte, iterations int, seed int64) FuzzResult {
+	result := FuzzResult{Func: name, Iterations: iterations}
+
+	rng := rand.New(rand.NewSource(seed))
+
+	// Map the Go-assembled code into a second executable region.
+	goExec, err := Map(goCode)
+	if err != nil {
+		result.Mismatches = iterations
+		result.FirstFail = fmt.Sprintf("map go code: %v", err)
+		return result
+	}
+	defer goExec.Unmap()
+
+	fl, err := k.Func(name)
+	if err != nil {
+		result.Mismatches = iterations
+		result.FirstFail = err.Error()
+		return result
+	}
+
+	for i := 0; i < iterations; i++ {
+		// Generate inputs and build TWO independent arg blocks (one per
+		// version) so that functions which write to their arguments
+		// (e.g. histogram increments) don't corrupt the other's input.
+		gasmArgs, goArgs, bufs := genDualArgs(rng, sig, fl.Args)
+
+		// Save the current input for crash diagnostics.
+		result.CrashInput = gasmArgs
+
+		// Call the gasm version.
+		gasmOut, err := k.CallFunc(name, gasmArgs)
+		if err != nil {
+			result.Mismatches++
+			if result.FirstFail == "" {
+				result.FirstFail = fmt.Sprintf("iter %d: gasm call: %v", i, err)
+			}
+			runtime.KeepAlive(bufs)
+			continue
+		}
+
+		// Call the Go version (same function, independent buffers).
+		goOut, err := Call(goExec.FuncAddr(0), goArgs)
+		if err != nil {
+			result.Mismatches++
+			if result.FirstFail == "" {
+				result.FirstFail = fmt.Sprintf("iter %d: go call: %v", i, err)
+			}
+			runtime.KeepAlive(bufs)
+			continue
+		}
+
+		// Compare only the result area (after all input parameters).
+		// Pointers in the arg block differ (separate buffers), so we
+		// compare from resultOff to the end.
+		resultOff := paramsSize(sig)
+		gasmRes := gasmOut[resultOff:]
+		goRes := goOut[resultOff:]
+		if !equalBytes(gasmRes, goRes) {
+			result.Mismatches++
+			if result.FirstFail == "" {
+				result.FirstFail = fmt.Sprintf("iter %d: output mismatch at result offset %d", i, resultOff)
+			}
+		} else {
+			result.Matches++
+		}
+		runtime.KeepAlive(bufs)
+	}
+	return result
+}
+
+// genDualArgs generates two independent ABI0 argument blocks (for gasm and
+// go) with identical logical content but separate backing buffers, so that
+// functions which write to their arguments don't corrupt the other's input.
+func genDualArgs(rng *rand.Rand, sig funcSig, argSize int) (gasmArgs, goArgs []byte, bufs [][]byte) {
+	gasmArgs = make([]byte, argSize)
+	goArgs = make([]byte, argSize)
+	off := 0
+	sliceIdx := 0
+
+	for _, p := range sig.params {
+		switch {
+		case strings.HasPrefix(p.typ, "[]"):
+			elemSize := elemSizeFor(p.typ)
+			n := 1 + rng.Intn(127)
+			var declaredLen int
+			if sliceIdx == 0 {
+				declaredLen = n
+			} else {
+				declaredLen = n + 512
+			}
+			// Allocate a buffer comfortably larger than declaredLen*elemSize so
+			// that SIMD over-reads and functions that write slightly past len
+			// (e.g. decoders that trust len(src)) never touch unmapped memory.
+			bufBytes := declaredLen*elemSize + 8192
+			// Two independent buffers with identical random content.
+			buf1 := make([]byte, bufBytes)
+			buf2 := make([]byte, bufBytes)
+			rng.Read(buf1[:n*elemSize])
+			copy(buf2, buf1)
+			bufs = append(bufs, buf1, buf2)
+			putPtr(gasmArgs, off, unsafe.Pointer(&buf1[0]))
+			putPtr(goArgs, off, unsafe.Pointer(&buf2[0]))
+			// len and cap both equal declaredLen — the buffer is guaranteed
+			// to hold at least declaredLen elements plus safety margin.
+			putU64(gasmArgs, off+8, uint64(declaredLen))
+			putU64(gasmArgs, off+16, uint64(declaredLen))
+			putU64(goArgs, off+8, uint64(declaredLen))
+			putU64(goArgs, off+16, uint64(declaredLen))
+			off += 24
+			sliceIdx++
+
+		case strings.HasPrefix(p.typ, "*["):
+			nElem := arrayLen(p.typ)
+			elem := elemSizeFor("[]" + p.typ[strings.Index(p.typ, "]")+1:])
+			size := nElem * elem
+			if size < 8 {
+				size = 8
+			}
+			buf1 := make([]byte, size)
+			buf2 := make([]byte, size)
+			rng.Read(buf1)
+			copy(buf2, buf1)
+			bufs = append(bufs, buf1, buf2)
+			putPtr(gasmArgs, off, unsafe.Pointer(&buf1[0]))
+			putPtr(goArgs, off, unsafe.Pointer(&buf2[0]))
+			off += 8
+
+		case p.typ == "int" || p.typ == "uint" || p.typ == "int64" || p.typ == "uint64":
+			v := uint64(rng.Intn(256))
+			putU64(gasmArgs, off, v)
+			putU64(goArgs, off, v)
+			off += 8
+
+		default:
+			v := rng.Uint64()
+			putU64(gasmArgs, off, v)
+			putU64(goArgs, off, v)
+			off += 8
+		}
+	}
+	return gasmArgs, goArgs, bufs
+}
+
+func elemSizeFor(sliceType string) int {
+	switch strings.TrimPrefix(sliceType, "[]") {
+	case "byte", "uint8", "int8":
+		return 1
+	case "uint16", "int16":
+		return 2
+	case "uint32", "int32", "float32":
+		return 4
+	case "uint64", "int64", "float64":
+		return 8
+	default:
+		return 8
+	}
+}
+
+// paramsSize returns the ABI0 stack size occupied by the input parameters.
+func paramsSize(sig funcSig) int {
+	size := 0
+	for _, p := range sig.params {
+		switch {
+		case strings.HasPrefix(p.typ, "[]"):
+			size += 24 // slice header
+		case strings.HasPrefix(p.typ, "*["):
+			size += 8 // pointer
+		case p.typ == "bool":
+			size += 1
+		default:
+			size += 8 // int, uint, etc.
+		}
+	}
+	return size
+}
+
+func arrayLen(typ string) int {
+	// "*[32]uint16" → 32
+	start := strings.Index(typ, "[")
+	end := strings.Index(typ, "]")
+	if start < 0 || end < 0 || end <= start {
+		return 1
+	}
+	n, _ := strconv.Atoi(typ[start+1 : end])
+	if n <= 0 {
+		n = 1
+	}
+	return n
+}
+
+func putPtr(buf []byte, off int, p unsafe.Pointer) {
+	if off+8 <= len(buf) {
+		u64 := uint64(uintptr(p))
+		buf[off] = byte(u64)
+		buf[off+1] = byte(u64 >> 8)
+		buf[off+2] = byte(u64 >> 16)
+		buf[off+3] = byte(u64 >> 24)
+		buf[off+4] = byte(u64 >> 32)
+		buf[off+5] = byte(u64 >> 40)
+		buf[off+6] = byte(u64 >> 48)
+		buf[off+7] = byte(u64 >> 56)
+	}
+}
+
+func putU64(buf []byte, off int, v uint64) {
+	if off+8 <= len(buf) {
+		buf[off] = byte(v)
+		buf[off+1] = byte(v >> 8)
+		buf[off+2] = byte(v >> 16)
+		buf[off+3] = byte(v >> 24)
+		buf[off+4] = byte(v >> 32)
+		buf[off+5] = byte(v >> 40)
+		buf[off+6] = byte(v >> 48)
+		buf[off+7] = byte(v >> 56)
+	}
+}
+
+func equalBytes(a, b []byte) bool {
+	if len(a) != len(b) {
+		return false
+	}
+	for i := range a {
+		if a[i] != b[i] {
+			return false
+		}
+	}
+	return true
+}

verify/fuzz_extra_test.go

@@ -0,0 +1,167 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package verify
+
+import (
+	"testing"
+)
+
+func TestFuzzResultString(t *testing.T) {
+	t.Run("ok", func(t *testing.T) {
+		r := FuzzResult{Func: "add", Iterations: 100, Matches: 100}
+		s := r.String()
+		if s != "add: 100/100 iterations match" {
+			t.Errorf("String() = %q", s)
+		}
+	})
+
+	t.Run("mismatch", func(t *testing.T) {
+		r := FuzzResult{Func: "mul", Iterations: 100, Matches: 95, Mismatches: 5, FirstFail: "iter 23"}
+		s := r.String()
+		if s != "mul: 95/100 match, 5 MISMATCH — iter 23" {
+			t.Errorf("String() = %q", s)
+		}
+	})
+
+	t.Run("crash", func(t *testing.T) {
+		r := FuzzResult{Func: "dec", Iterations: 100, Matches: 99, Mismatches: 1, FirstFail: "SIGSEGV", CrashInput: []byte{0x01, 0x02}}
+		s := r.String()
+		if s != "dec: 99/100 match, 1 MISMATCH — SIGSEGV\n  input: 0102" {
+			t.Errorf("String() = %q", s)
+		}
+	})
+}
+
+func TestArrayLen(t *testing.T) {
+	tests := []struct {
+		typ  string
+		want int
+	}{
+		{"*[32]uint16", 32},
+		{"*[16]int32", 16},
+		{"bad", 1},
+		{"*[]", 1},
+		{"*[0x]", 1},
+	}
+	for _, tt := range tests {
+		if got := arrayLen(tt.typ); got != tt.want {
+			t.Errorf("arrayLen(%q) = %d, want %d", tt.typ, got, tt.want)
+		}
+	}
+}
+
+func TestElemSizeFor(t *testing.T) {
+	tests := []struct {
+		typ  string
+		want int
+	}{
+		{"[]byte", 1}, {"[]uint8", 1}, {"[]int8", 1},
+		{"[]uint16", 2}, {"[]int16", 2},
+		{"[]uint32", 4}, {"[]int32", 4}, {"[]float32", 4},
+		{"[]uint64", 8}, {"[]int64", 8}, {"[]float64", 8},
+		{"[]unknown", 8},
+	}
+	for _, tt := range tests {
+		if got := elemSizeFor(tt.typ); got != tt.want {
+			t.Errorf("elemSizeFor(%q) = %d, want %d", tt.typ, got, tt.want)
+		}
+	}
+}
+
+func TestEqualBytes(t *testing.T) {
+	if !equalBytes([]byte{1, 2, 3}, []byte{1, 2, 3}) {
+		t.Error("expected equal")
+	}
+	if equalBytes([]byte{1, 2}, []byte{1, 2, 3}) {
+		t.Error("different length: expected not equal")
+	}
+	if equalBytes([]byte{1, 2, 3}, []byte{1, 2, 4}) {
+		t.Error("different content: expected not equal")
+	}
+}
+
+func TestParamsSize(t *testing.T) {
+	sig := funcSig{
+		name:    "test",
+		params:  []param{{name: "a", typ: "[]byte"}, {name: "b", typ: "int"}},
+		results: []param{{name: "n", typ: "int"}},
+	}
+	if got := paramsSize(sig); got != 32 {
+		t.Errorf("paramsSize = %d, want 32 (24 for slice + 8 for int)", got)
+	}
+}
+
+func TestBlockCount(t *testing.T) {
+	k := loadBasic(t)
+	n, err := k.BlockCount("sum")
+	if err != nil {
+		t.Fatalf("BlockCount(sum): %v", err)
+	}
+	if n < 2 {
+		t.Errorf("sum: expected at least 2 blocks, got %d", n)
+	}
+}
+
+func TestFillBuffer(t *testing.T) {
+	t.Run("zero", func(t *testing.T) {
+		// fillBuffer("zero") is a no-op — relies on make already zeroing.
+		buf := make([]byte, 16)
+		fillBuffer(buf, "zero")
+		for _, b := range buf {
+			if b != 0 {
+				t.Error("zero pattern: make should produce zeroed buffer")
+				break
+			}
+		}
+	})
+	t.Run("ones", func(t *testing.T) {
+		buf := make([]byte, 16)
+		fillBuffer(buf, "ones")
+		for _, b := range buf {
+			if b != 0xFF {
+				t.Error("ones pattern should fill with 0xFF")
+				break
+			}
+		}
+	})
+	t.Run("seq", func(t *testing.T) {
+		buf := make([]byte, 256)
+		fillBuffer(buf, "seq")
+		for i, b := range buf {
+			if b != byte(i) {
+				t.Errorf("seq[%d] = %d, want %d", i, b, i)
+				break
+			}
+		}
+	})
+	t.Run("hex", func(t *testing.T) {
+		buf := make([]byte, 6)
+		fillBuffer(buf, "deadbeef")
+		want := []byte{0xDE, 0xAD, 0xBE, 0xEF, 0xDE, 0xAD}
+		for i, b := range buf {
+			if b != want[i] {
+				t.Errorf("hex[%d] = %02x, want %02x", i, b, want[i])
+				break
+			}
+		}
+	})
+}
+
+func TestFuzzFuncChecked(t *testing.T) {
+	k := loadBasic(t)
+	sig := funcSig{
+		name:    "sum",
+		params:  []param{{name: "data", typ: "[]int64"}},
+		results: []param{{name: "r", typ: "int64"}},
+	}
+	result := k.FuzzFuncChecked("sum", sig, 10, 0)
+	if !result.OK() {
+		t.Errorf("FuzzFuncChecked(sum): %s", result)
+	}
+	// Test with non-existent function — should report failure.
+	result = k.FuzzFuncChecked("nope", sig, 10, 0)
+	if result.OK() {
+		t.Error("FuzzFuncChecked(nope): expected failure")
+	}
+}

verify/fuzz_test.go

@@ -0,0 +1,98 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package verify
+
+import (
+	"testing"
+)
+
+func TestExtractSignatures(t *testing.T) {
+	src := `// func add(a int64, b int64) int64
+TEXT ·add(SB), NOSPLIT, $0-24
+	RET
+
+// func wideCopy(dst []byte, src []byte)
+TEXT ·wideCopy(SB), NOSPLIT, $0-48
+	RET
+`
+	sigs := ExtractSignatures(src)
+	if len(sigs) != 2 {
+		t.Fatalf("expected 2 signatures, got %d: %v", len(sigs), sigs)
+	}
+	add, ok := sigs["add"]
+	if !ok {
+		t.Fatal("add not found")
+	}
+	if len(add.params) != 2 {
+		t.Errorf("add params: got %d, want 2", len(add.params))
+	}
+	wc, ok := sigs["wideCopy"]
+	if !ok {
+		t.Fatal("wideCopy not found")
+	}
+	if len(wc.params) != 2 {
+		t.Errorf("wideCopy params: got %d, want 2", len(wc.params))
+	}
+	if wc.params[0].typ != "[]byte" {
+		t.Errorf("wideCopy param[0].typ = %q, want []byte", wc.params[0].typ)
+	}
+}
+
+func TestFuzzWideCopy(t *testing.T) {
+	k := loadBasic(t)
+
+	gt, err := GroundTruth("../testdata/verify/basic_amd64.s")
+	if err != nil {
+		t.Fatalf("GroundTruth: %v", err)
+	}
+	goCode, ok := gt["wideCopy"]
+	if !ok {
+		t.Skip("wideCopy not in ground truth")
+	}
+
+	sig := funcSig{
+		name: "wideCopy",
+		params: []param{
+			{name: "dst", typ: "[]byte"},
+			{name: "src", typ: "[]byte"},
+		},
+	}
+
+	res := k.FuzzFunc("wideCopy", sig, goCode, 200, 42)
+	if !res.OK() {
+		t.Errorf("wideCopy fuzz: %s", res)
+	}
+}
+
+func TestParseFuncSig(t *testing.T) {
+	tests := []struct {
+		comment string
+		name    string
+		nParams int
+	}{
+		{"// func add(a int64, b int64) int64", "add", 2},
+		{"// func wideCopy(dst []byte, src []byte)", "wideCopy", 2},
+		{"// func analyzeO1RangeAVX2(swin []int32, dstP []uint32, hist *[32]uint16) (partSum uint64, overflow bool)", "analyzeO1RangeAVX2", 3},
+		{"// not a func", "", 0},
+	}
+	for _, tt := range tests {
+		sig, ok := parseFuncSig(tt.comment)
+		if tt.name == "" {
+			if ok {
+				t.Errorf("parseFuncSig(%q): expected not ok", tt.comment)
+			}
+			continue
+		}
+		if !ok {
+			t.Errorf("parseFuncSig(%q): expected ok", tt.comment)
+			continue
+		}
+		if sig.name != tt.name {
+			t.Errorf("parseFuncSig(%q).name = %q, want %q", tt.comment, sig.name, tt.name)
+		}
+		if len(sig.params) != tt.nParams {
+			t.Errorf("parseFuncSig(%q): %d params, want %d", tt.comment, len(sig.params), tt.nParams)
+		}
+	}
+}

verify/groundtruth.go

@@ -0,0 +1,188 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package verify
+
+import (
+	"bytes"
+	"encoding/binary"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+)
+
+// GroundTruth assembles the given .s file with the Go toolchain's own
+// assembler and returns the machine code bytes for each TEXT function,
+// keyed by the function's short name (the part after the middle dot).
+// This is the universal oracle: any file that `go tool asm` accepts can
+// be verified, with no hand-written reference.
+//
+// For RISC-V sources the assembler is invoked with GOARCH=riscv64;
+// the caller must set the architecture via GroundTruthArch.
+func GroundTruth(path string) (map[string][]byte, error) {
+	return groundTruthArch(path, "")
+}
+
+// GroundTruthRISCV assembles the given .s file with the Go toolchain in
+// RISC-V cross-assembly mode (GOARCH=riscv64).
+func GroundTruthRISCV(path string) (map[string][]byte, error) {
+	return groundTruthArch(path, "riscv64")
+}
+
+func groundTruthArch(path, goarch string) (map[string][]byte, error) {
+	goroot := runtime.GOROOT()
+	asmBin := filepath.Join(goroot, "pkg", "tool", runtime.GOOS+"_"+runtime.GOARCH, "asm")
+	if _, err := os.Stat(asmBin); err != nil {
+		return nil, fmt.Errorf("verify: go tool asm not found at %s: %w", asmBin, err)
+	}
+	includeDir := filepath.Join(goroot, "pkg", "include")
+
+	tmpDir, err := os.MkdirTemp("", "gasm-verify-*")
+	if err != nil {
+		return nil, fmt.Errorf("verify: tempdir: %w", err)
+	}
+	defer os.RemoveAll(tmpDir)
+	objPath := filepath.Join(tmpDir, "out.o")
+
+	base := filepath.Base(path)
+	pkg := strings.TrimSuffix(base, ".s")
+	pkg = strings.TrimSuffix(pkg, "_amd64")
+	pkg = strings.TrimSuffix(pkg, "_riscv64")
+
+	cmd := exec.Command(asmBin, "-I", includeDir, "-p", pkg, "-o", objPath, path)
+	if goarch != "" {
+		cmd.Env = append(os.Environ(), "GOARCH="+goarch)
+	}
+	if out, err := cmd.CombinedOutput(); err != nil {
+		return nil, fmt.Errorf("verify: go tool asm (%s): %w\n%s", goarch, err, out)
+	}
+
+	objData, err := os.ReadFile(objPath)
+	if err != nil {
+		return nil, fmt.Errorf("verify: read object: %w", err)
+	}
+	return extractGOOBJCode(objData)
+}
+
+// GOOBJ block indices (cmd/internal/goobj).
+const (
+	blkAutolib = iota
+	blkPkgIdx
+	blkFile
+	blkSymdef
+	blkHashed64def
+	blkHasheddef
+	blkNonpkgdef
+	blkNonpkgref
+	blkRefFlags
+	blkHash64
+	blkHash
+	blkRelocIdx
+	blkAuxIdx
+	blkDataIdx
+	blkReloc
+	blkAux
+	blkData
+	blkRefName
+	blkEnd
+)
+
+const goobjMagic = "\x00go120ld"
+
+// extractGOOBJCode parses a GOOBJ payload and returns the code bytes for
+// each non-package STEXT symbol (the functions).
+func extractGOOBJCode(data []byte) (map[string][]byte, error) {
+	// Find the GOOBJ header (after the "go object ..." preamble).
+	i := bytes.Index(data, []byte(goobjMagic))
+	if i < 0 {
+		return nil, fmt.Errorf("verify: no GOOBJ magic in object file")
+	}
+	b := data[i:]
+	le := binary.LittleEndian
+
+	// Read block offsets (20 bytes into the header: 4 magic + 8 go version
+	// + 8 experiment = 20, then blkEnd+1 uint32 offsets).
+	var offs [blkEnd + 1]uint32
+	for j := 0; j <= blkEnd; j++ {
+		offs[j] = le.Uint32(b[20+4*j:])
+	}
+	blk := func(idx int) []byte { return b[offs[idx]:offs[idx+1]] }
+
+	// Parse non-package symbol definitions (blkNonpkgdef): each entry is
+	// 21 bytes: [nameLen:4][nameOff:4][abi:2][type:1][flag:1][flag2:1][size:4][align:4].
+	const symSize = 21
+	nonpkg := blk(blkNonpkgdef)
+	nSyms := len(nonpkg) / symSize
+
+	// Data index (blkDataIdx): one uint32 per defined symbol across ALL
+	// definition blocks (blkSymdef + blkHashed64def + blkHasheddef +
+	// blkNonpkgdef), in that order.  We need the offset for the nonpkg
+	// symbols, which come last.
+	dataIdx := blk(blkDataIdx)
+	dataBlk := blk(blkData)
+
+	// Count symbols in the preceding definition blocks.
+	preceding := 0
+	for _, bi := range []int{blkSymdef, blkHashed64def, blkHasheddef} {
+		preceding += len(blk(bi)) / symSize
+	}
+
+	// Symbol name offsets in the GOOBJ symbol table are absolute byte
+	// offsets from the start of the GOOBJ payload (the magic).
+	readStr := func(off, ln uint32) string {
+		if int(off+ln) > len(b) {
+			return ""
+		}
+		return string(b[off : off+ln])
+	}
+
+	result := make(map[string][]byte)
+	const kindSTEXT = 1
+	for s := 0; s < nSyms; s++ {
+		x := nonpkg[s*symSize:]
+		nameLen := le.Uint32(x[0:])
+		nameOff := le.Uint32(x[4:])
+		typ := x[10]
+		size := le.Uint32(x[13:])
+
+		if typ != kindSTEXT || size == 0 {
+			continue
+		}
+		name := readStr(nameOff, nameLen)
+		// Strip the package prefix (everything up to and including the
+		// last middle dot or period-dot).
+		name = stripPkg(name)
+
+		// Data offset from the index (nonpkg symbols follow the preceding blocks).
+		diIdx := preceding + s
+		if (diIdx+1)*4 > len(dataIdx) {
+			continue
+		}
+		dOff := le.Uint32(dataIdx[diIdx*4:])
+		if int(dOff+size) > len(dataBlk) {
+			continue
+		}
+		code := make([]byte, size)
+		copy(code, dataBlk[dOff:dOff+size])
+		result[name] = code
+	}
+	return result, nil
+}
+
+// stripPkg removes the package path prefix from a symbol name, leaving
+// just the function name.  "pkg/path·FuncName" → "FuncName".
+func stripPkg(name string) string {
+	if i := strings.LastIndex(name, "\u00B7"); i >= 0 {
+		return name[i+len("\u00B7"):]
+	}
+	if i := strings.LastIndex(name, "\"."); i >= 0 {
+		return name[i+2:]
+	}
+	if i := strings.LastIndex(name, "."); i >= 0 {
+		return name[i+1:]
+	}
+	return name
+}

verify/groundtruth_test.go

@@ -0,0 +1,77 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package verify
+
+import (
+	"testing"
+)
+
+func TestGroundTruthBasic(t *testing.T) {
+	// Use the simple test kernel — it assembles with go tool asm.
+	gt, err := GroundTruth("../testdata/verify/basic_amd64.s")
+	if err != nil {
+		t.Fatalf("GroundTruth: %v", err)
+	}
+	if len(gt) == 0 {
+		t.Fatal("no functions extracted from ground truth")
+	}
+	// The "add" function should be present and non-empty.
+	code, ok := gt["add"]
+	if !ok {
+		t.Fatalf("function 'add' not found in ground truth; got: %v", keys(gt))
+	}
+	if len(code) == 0 {
+		t.Fatal("add: zero-length code")
+	}
+	t.Logf("ground truth functions: %v", keys(gt))
+}
+
+func TestGroundTruthComparison(t *testing.T) {
+	// Assemble with gasm and compare against go tool asm.
+	k, err := Load("../testdata/verify/basic_amd64.s")
+	if err != nil {
+		t.Fatalf("Load: %v", err)
+	}
+	defer k.Close()
+
+	gt, err := GroundTruth("../testdata/verify/basic_amd64.s")
+	if err != nil {
+		t.Fatalf("GroundTruth: %v", err)
+	}
+
+	for _, name := range k.FuncNames() {
+		fl, _ := k.Func(name)
+		gasmCode := k.Image().Code[fl.Offset : fl.Offset+fl.Size]
+		goCode, ok := gt[name]
+		if !ok {
+			t.Errorf("%s: not in ground truth", name)
+			continue
+		}
+		if len(gasmCode) != len(goCode) {
+			t.Errorf("%s: size mismatch: gasm=%d go=%d", name, len(gasmCode), len(goCode))
+			continue
+		}
+		for i := range gasmCode {
+			if gasmCode[i] != goCode[i] {
+				t.Errorf("%s: byte %d differs: gasm=%02x go=%02x", name, i, gasmCode[i], goCode[i])
+				break
+			}
+		}
+	}
+}
+
+func TestGroundTruthBadFile(t *testing.T) {
+	_, err := GroundTruth("/nonexistent/file_amd64.s")
+	if err == nil {
+		t.Fatal("expected error for nonexistent file")
+	}
+}
+
+func keys(m map[string][]byte) []string {
+	out := make([]string, 0, len(m))
+	for k := range m {
+		out = append(out, k)
+	}
+	return out
+}

verify/jit_test.go

@@ -5,6 +5,7 @@ package verify
 
 import (
 	"bytes"
+	"runtime"
 	"testing"
 	"unsafe"
 )
@@ -68,6 +69,7 @@ func TestJITSum(t *testing.T) {
 		PutUint64(args, 16, uint64(cap(tt.data)))
 
 		out, err := k.CallFunc("sum", args)
+		runtime.KeepAlive(tt.data)
 		if err != nil {
 			t.Fatalf("CallFunc(sum, %v): %v", tt.data, err)
 		}
@@ -111,6 +113,8 @@ func TestJITWideCopy(t *testing.T) {
 			PutUint64(args, 40, uint64(tt.n)) // src_cap
 
 			_, err := k.CallFunc("wideCopy", args)
+			runtime.KeepAlive(dst)
+			runtime.KeepAlive(src)
 			if err != nil {
 				t.Fatalf("CallFunc(wideCopy): %v", err)
 			}

verify/lz4_test.go

@@ -1,160 +0,0 @@
-// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
-// SPDX-License-Identifier: BSD-3-Clause
-
-package verify
-
-import (
-	"bytes"
-	"os"
-	"testing"
-	"unsafe"
-)
-
-// lz4KernelPath is the sibling repository's AVX2 kernel, used for
-// integration testing.  The test is skipped when the file is absent
-// (e.g. in CI without the sibling checkout).
-const lz4KernelPath = "../../go-libraries/go-lz4/avx2_amd64.s"
-
-func loadLZ4Kernel(t *testing.T) *Kernel {
-	t.Helper()
-	if _, err := os.Stat(lz4KernelPath); err != nil {
-		t.Skipf("sibling kernel not available: %v", err)
-	}
-	k, err := Load(lz4KernelPath)
-	if err != nil {
-		t.Fatalf("Load(%s): %v", lz4KernelPath, err)
-	}
-	t.Cleanup(k.Close)
-	return k
-}
-
-// callDecodeBlockAVX2 invokes the JIT-assembled decodeBlockAVX2 with the
-// given src and dst buffers, returning (n, code).
-func callDecodeBlockAVX2(t *testing.T, k *Kernel, src, dst []byte) (int, int) {
-	t.Helper()
-	args := make([]byte, 64)
-	if len(src) > 0 {
-		PutPtr(args, 0, unsafe.Pointer(&src[0]))
-	}
-	PutUint64(args, 8, uint64(len(src)))
-	PutUint64(args, 16, uint64(cap(src)))
-	if len(dst) > 0 {
-		PutPtr(args, 24, unsafe.Pointer(&dst[0]))
-	}
-	PutUint64(args, 32, uint64(len(dst)))
-	PutUint64(args, 40, uint64(cap(dst)))
-
-	out, err := k.CallFunc("decodeBlockAVX2", args)
-	if err != nil {
-		t.Fatalf("CallFunc(decodeBlockAVX2): %v", err)
-	}
-	return int(GetUint64(out, 48)), int(GetUint64(out, 56))
-}
-
-func TestLZ4DecodeKnownAnswers(t *testing.T) {
-	k := loadLZ4Kernel(t)
-
-	tests := []struct {
-		name     string
-		src      []byte
-		dstSize  int
-		wantDst  []byte
-		wantN    int
-		wantCode int
-	}{
-		{
-			name:     "literals_only",
-			src:      []byte{0x50, 'H', 'e', 'l', 'l', 'o'},
-			dstSize:  16,
-			wantDst:  []byte("Hello"),
-			wantN:    5,
-			wantCode: 0,
-		},
-		{
-			name:     "literals_and_match",
-			src:      []byte{0x54, 'A', 'A', 'A', 'A', 'A', 0x05, 0x00, 0x30, 'B', 'B', 'B'},
-			dstSize:  32,
-			wantDst:  []byte("AAAAAAAAAAAAABBB"),
-			wantN:    16,
-			wantCode: 0,
-		},
-		{
-			name: "overlapping_match",
-			// 1 literal 'X', then match offset=1 length=4+4=8 → "XXXXXXXXX",
-			// then final 1 literal 'Y'.
-			src:      []byte{0x14, 'X', 0x01, 0x00, 0x10, 'Y'},
-			dstSize:  16,
-			wantDst:  []byte("XXXXXXXXXY"),
-			wantN:    10,
-			wantCode: 0,
-		},
-		{
-			name:     "malformed_truncated",
-			src:      []byte{0x50, 'H', 'e'}, // claims 5 literals, has 2
-			dstSize:  16,
-			wantN:    0,
-			wantCode: 1,
-		},
-		{
-			name:     "zero_offset",
-			src:      []byte{0x14, 'X', 0x00, 0x00},
-			dstSize:  16,
-			wantN:    0,
-			wantCode: 2,
-		},
-		{
-			name:     "empty_token",
-			src:      []byte{0x00}, // 0 literals, end of block
-			dstSize:  16,
-			wantDst:  nil,
-			wantN:    0,
-			wantCode: 0,
-		},
-	}
-	for _, tt := range tests {
-		t.Run(tt.name, func(t *testing.T) {
-			dst := make([]byte, tt.dstSize)
-			n, code := callDecodeBlockAVX2(t, k, tt.src, dst)
-			if n != tt.wantN || code != tt.wantCode {
-				t.Fatalf("decodeBlockAVX2: got (n=%d, code=%d), want (n=%d, code=%d)",
-					n, code, tt.wantN, tt.wantCode)
-			}
-			if tt.wantCode == 0 && tt.wantDst != nil {
-				if !bytes.Equal(dst[:n], tt.wantDst) {
-					t.Errorf("output mismatch:\n  got  %q\n  want %q", dst[:n], tt.wantDst)
-				}
-			}
-		})
-	}
-}
-
-func TestLZ4WideCopyAVX2(t *testing.T) {
-	k := loadLZ4Kernel(t)
-
-	sizes := []int{0, 1, 15, 16, 31, 32, 33, 63, 64, 100, 256, 1024}
-	for _, n := range sizes {
-		src := make([]byte, n)
-		for i := range src {
-			src[i] = byte(i*13 + 7)
-		}
-		dst := make([]byte, n)
-
-		args := make([]byte, 48)
-		if n > 0 {
-			PutPtr(args, 0, unsafe.Pointer(&dst[0]))
-			PutPtr(args, 24, unsafe.Pointer(&src[0]))
-		}
-		PutUint64(args, 8, uint64(n))
-		PutUint64(args, 16, uint64(n))
-		PutUint64(args, 32, uint64(n))
-		PutUint64(args, 40, uint64(n))
-
-		_, err := k.CallFunc("wideCopyAVX2", args)
-		if err != nil {
-			t.Fatalf("wideCopyAVX2(n=%d): %v", n, err)
-		}
-		if !bytes.Equal(dst, src) {
-			t.Errorf("wideCopyAVX2(n=%d): output mismatch", n)
-		}
-	}
-}

verify/sigparse.go

@@ -0,0 +1,160 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package verify
+
+import (
+	"strings"
+)
+
+// FuncSig is a parsed // func signature from the assembly source.
+type FuncSig struct {
+	Name    string
+	Params  []Param
+	Results []Param
+}
+
+// Param is a single function parameter.
+type Param struct {
+	Name string
+	Typ  string // "[]byte", "[]int32", "int", "*[32]uint16", etc.
+}
+
+// IsPointer reports whether the parameter type is a pointer or slice
+// (i.e., it needs a buffer address in the argument block).
+func (p Param) IsPointer() bool {
+	return strings.HasPrefix(p.Typ, "[]") || strings.HasPrefix(p.Typ, "*")
+}
+
+// ParseFuncSig extracts the function signature from a "// func ..." comment.
+func ParseFuncSig(comment string) (FuncSig, bool) {
+	m := funcSigRe.FindStringSubmatch(strings.TrimSpace(comment))
+	if m == nil {
+		return FuncSig{}, false
+	}
+	sig := FuncSig{Name: m[1]}
+	sig.Params = parseParamsExported(m[2])
+	// Results may be "(a int, b int)" or "int" or "(int, error)".
+	res := strings.TrimSpace(m[3])
+	res = strings.TrimPrefix(res, "(")
+	res = strings.TrimSuffix(res, ")")
+	if res != "" {
+		sig.Results = parseParamsExported(res)
+	}
+	return sig, true
+}
+
+// parseParamsExported splits a parameter list like "a []byte, b []int32" or
+// "dst, src []byte" into typed parameters.  Go syntax allows grouped names
+// where the type at the end applies to every name in the group:// "dst, src []byte" means both dst and src are []byte.
+func parseParamsExported(s string) []Param {
+	s = strings.TrimSpace(s)
+	if s == "" {
+		return nil
+	}
+	fields := strings.Split(s, ",")
+	// First pass: extract the type from each field (if present).
+	types := make([]string, len(fields))
+	for i, field := range fields {
+		parts := strings.Fields(strings.TrimSpace(field))
+		if len(parts) >= 2 {
+			types[i] = parts[len(parts)-1]
+		}
+	}
+	// Propagate types backward: a field without a type inherits the type from
+	// the next field that has one (e.g. "dst" inherits "[]byte" from "src []byte").
+	for i := range fields {
+		if types[i] == "" {
+			for j := i + 1; j < len(fields); j++ {
+				if types[j] != "" {
+					types[i] = types[j]
+					break
+				}
+			}
+		}
+	}
+	// Second pass: build params.
+	var out []Param
+	for i, field := range fields {
+		field = strings.TrimSpace(field)
+		if field == "" {
+			continue
+		}
+		parts := strings.Fields(field)
+		typ := types[i]
+		if typ == "" {
+			typ = parts[0] // unnamed: the whole field is the type
+			out = append(out, Param{Typ: typ})
+		} else {
+			out = append(out, Param{Name: parts[0], Typ: typ})
+		}
+	}
+	return out
+}
+
+// ExtractFuncSig extracts the // func signature for the named function
+// from the assembly source.
+func ExtractFuncSig(src, funcName string) (FuncSig, bool) {
+	lines := strings.Split(src, "\n")
+	for i, line := range lines {
+		if sig, ok := ParseFuncSig(line); ok && sig.Name == funcName {
+			// Verify the next non-comment line is the TEXT directive.
+			for j := i + 1; j < len(lines); j++ {
+				trimmed := strings.TrimSpace(lines[j])
+				if trimmed == "" || strings.HasPrefix(trimmed, "//") {
+					continue
+				}
+				if strings.HasPrefix(trimmed, "TEXT") {
+					return sig, true
+				}
+				break
+			}
+		}
+	}
+	return FuncSig{}, false
+}
+
+// ArgLayout computes the ABI0 argument layout for a function signature.
+// Returns the offset of each parameter in the argument block.
+func ArgLayout(sig FuncSig) []ArgOffset {
+	var offsets []ArgOffset
+	off := 0
+	for _, p := range sig.Params {
+		size := paramSize(p.Typ)
+		offsets = append(offsets, ArgOffset{Name: p.Name, Typ: p.Typ, Offset: off, Size: size, IsPtr: p.IsPointer()})
+		off += size
+	}
+	return offsets
+}
+
+// ArgOffset describes one parameter's position in the argument block.
+type ArgOffset struct {
+	Name   string
+	Typ    string
+	Offset int
+	Size   int
+	IsPtr  bool
+}
+
+// paramSize returns the size in bytes of a parameter type in the ABI0 layout.
+func paramSize(typ string) int {
+	switch {
+	case strings.HasPrefix(typ, "[]"):
+		// Slice: pointer + length + capacity = 24 bytes.
+		return 24
+	case strings.HasPrefix(typ, "*"):
+		// Pointer: 8 bytes.
+		return 8
+	case typ == "int", typ == "int64", typ == "uint64", typ == "uintptr":
+		return 8
+	case typ == "int32", typ == "uint32", typ == "float32":
+		return 4
+	case typ == "int16", typ == "uint16":
+		return 2
+	case typ == "int8", typ == "uint8", typ == "byte", typ == "bool":
+		return 1
+	default:
+		// Default to 8 bytes for unknown types.
+		return 8
+	}
+}

verify/sigparse_test.go

@@ -0,0 +1,153 @@
+// Copyright (c) 2026 Petr Balvín <opensource@petrbalvin.org> (https://petrbalvin.org)
+// SPDX-License-Identifier: BSD-3-Clause
+
+package verify
+
+import (
+	"testing"
+)
+
+func TestParseFuncSigExported(t *testing.T) {
+	tests := []struct {
+		comment  string
+		wantName string
+		nParams  int
+		nResults int
+	}{
+		{"// func add(a int64, b int64) int64", "add", 2, 1},
+		{"// func wideCopy(dst []byte, src []byte)", "wideCopy", 2, 0},
+		{"// func decodeBlockAVX2(src, dst []byte) (n int, code int)", "decodeBlockAVX2", 2, 2},
+		{"// func analyzeO1RangeAVX2(swin []int32, dstP []uint32, hist *[32]uint16) (partSum uint64, overflow bool)", "analyzeO1RangeAVX2", 3, 2},
+		{"// not a func", "", 0, 0},
+		{"// func", "", 0, 0},
+	}
+	for _, tt := range tests {
+		sig, ok := ParseFuncSig(tt.comment)
+		if tt.wantName == "" {
+			if ok {
+				t.Errorf("ParseFuncSig(%q): expected not ok", tt.comment)
+			}
+			continue
+		}
+		if !ok {
+			t.Errorf("ParseFuncSig(%q): expected ok", tt.comment)
+			continue
+		}
+		if sig.Name != tt.wantName {
+			t.Errorf("ParseFuncSig(%q).Name = %q, want %q", tt.comment, sig.Name, tt.wantName)
+		}
+		if len(sig.Params) != tt.nParams {
+			t.Errorf("ParseFuncSig(%q): %d params, want %d", tt.comment, len(sig.Params), tt.nParams)
+		}
+		if len(sig.Results) != tt.nResults {
+			t.Errorf("ParseFuncSig(%q): %d results, want %d", tt.comment, len(sig.Results), tt.nResults)
+		}
+	}
+}
+
+func TestExtractFuncSig(t *testing.T) {
+	src := `// func add(a int64, b int64) int64
+TEXT ·add(SB), NOSPLIT, $0-24
+
+// func wideCopyAVX2(dst, src []byte)
+TEXT ·wideCopyAVX2(SB), NOSPLIT, $0-48
+`
+	sig, ok := ExtractFuncSig(src, "add")
+	if !ok {
+		t.Fatal("ExtractFuncSig(add): not found")
+	}
+	if sig.Name != "add" {
+		t.Errorf("Name = %q, want %q", sig.Name, "add")
+	}
+	if len(sig.Params) != 2 {
+		t.Errorf("params = %d, want 2", len(sig.Params))
+	}
+
+	sig, ok = ExtractFuncSig(src, "wideCopyAVX2")
+	if !ok {
+		t.Fatal("ExtractFuncSig(wideCopyAVX2): not found")
+	}
+	if len(sig.Params) != 2 {
+		t.Errorf("params = %d, want 2", len(sig.Params))
+	}
+
+	_, ok = ExtractFuncSig(src, "nonexistent")
+	if ok {
+		t.Error("ExtractFuncSig(nonexistent): expected not found")
+	}
+}
+
+func TestArgLayout(t *testing.T) {
+	sig := FuncSig{
+		Name: "wideCopyAVX2",
+		Params: []Param{
+			{Name: "dst", Typ: "[]byte"},
+			{Name: "src", Typ: "[]byte"},
+		},
+	}
+	layout := ArgLayout(sig)
+	if len(layout) != 2 {
+		t.Fatalf("ArgLayout: %d entries, want 2", len(layout))
+	}
+	// dst: offset 0, size 24 (slice)
+	if layout[0].Name != "dst" || layout[0].Offset != 0 || layout[0].Size != 24 || !layout[0].IsPtr {
+		t.Errorf("layout[0] = %+v", layout[0])
+	}
+	// src: offset 24, size 24 (slice)
+	if layout[1].Name != "src" || layout[1].Offset != 24 || layout[1].Size != 24 || !layout[1].IsPtr {
+		t.Errorf("layout[1] = %+v", layout[1])
+	}
+}
+
+func TestArgLayoutMixed(t *testing.T) {
+	sig := FuncSig{
+		Name: "decodeBlockAVX2",
+		Params: []Param{
+			{Name: "src", Typ: "[]byte"},
+			{Name: "dst", Typ: "[]byte"},
+		},
+		Results: []Param{
+			{Name: "n", Typ: "int"},
+			{Name: "code", Typ: "int"},
+		},
+	}
+	layout := ArgLayout(sig)
+	if len(layout) != 2 {
+		t.Fatalf("ArgLayout: %d entries, want 2", len(layout))
+	}
+	// Two slices: 24 + 24 = 48 bytes of params.
+	if layout[1].Offset != 24 {
+		t.Errorf("src offset = %d, want 24", layout[1].Offset)
+	}
+}
+
+func TestParamSize(t *testing.T) {
+	tests := []struct {
+		typ  string
+		want int
+	}{
+		{"[]byte", 24},
+		{"[]int32", 24},
+		{"*uint16", 8},
+		{"*[32]uint16", 8},
+		{"int", 8},
+		{"int64", 8},
+		{"uint64", 8},
+		{"uintptr", 8},
+		{"int32", 4},
+		{"uint32", 4},
+		{"float32", 4},
+		{"int16", 2},
+		{"uint16", 2},
+		{"int8", 1},
+		{"uint8", 1},
+		{"byte", 1},
+		{"bool", 1},
+		{"string", 8}, // unknown type defaults to 8
+	}
+	for _, tt := range tests {
+		if got := paramSize(tt.typ); got != tt.want {
+			t.Errorf("paramSize(%q) = %d, want %d", tt.typ, got, tt.want)
+		}
+	}
+}

verify/verify.go

@@ -5,7 +5,9 @@ package verify
 
 import (
 	"fmt"
+	"math/rand"
 	"os"
+	"runtime"
 
 	"sourcedock.dev/petrbalvin/gasm-devkit/asm"
 	"sourcedock.dev/petrbalvin/gasm-devkit/ast"
@@ -114,9 +116,74 @@ func (k *Kernel) CallFuncChecked(name string, args []byte) ([]byte, ABIReport, e
 	return CallChecked(fnAddr, args)
 }
 
+// FuzzFuncCheckedByName is like FuzzFuncChecked but extracts the signature
+// from the source code internally.
+func (k *Kernel) FuzzFuncCheckedByName(name, src string, iterations int, seed int64) FuzzResult {
+	result := FuzzResult{Func: name, Iterations: iterations}
+	sig, ok := ExtractSignatures(src)[name]
+	if !ok {
+		result.Mismatches = iterations
+		result.FirstFail = "no // func signature found"
+		return result
+	}
+	return k.FuzzFuncChecked(name, sig, iterations, seed)
+}
+
+// FuzzFuncChecked combines fuzzing with ABI checks: it generates varied
+// inputs and verifies that callee-saved registers and the red zone are
+// preserved even on deep execution paths (not just early exits).
+func (k *Kernel) FuzzFuncChecked(name string, sig funcSig, iterations int, seed int64) FuzzResult {
+	result := FuzzResult{Func: name, Iterations: iterations}
+	rng := rand.New(rand.NewSource(seed))
+
+	fl, err := k.Func(name)
+	if err != nil {
+		result.Mismatches = iterations
+		result.FirstFail = err.Error()
+		return result
+	}
+
+	violations := 0
+	for i := 0; i < iterations; i++ {
+		gasmArgs, _, bufs := genDualArgs(rng, sig, fl.Args)
+		result.CrashInput = gasmArgs
+
+		_, report, err := k.CallFuncChecked(name, gasmArgs)
+		if err != nil {
+			result.Mismatches++
+			if result.FirstFail == "" {
+				result.FirstFail = fmt.Sprintf("iter %d: call: %v", i, err)
+			}
+			runtime.KeepAlive(bufs)
+			continue
+		}
+
+		if !report.OK() {
+			violations++
+			result.Mismatches++
+			if result.FirstFail == "" {
+				result.FirstFail = fmt.Sprintf("iter %d: %s", i, report.String())
+			}
+		} else {
+			result.Matches++
+		}
+		runtime.KeepAlive(bufs)
+	}
+
+	if violations > 0 && result.FirstFail == "" {
+		result.FirstFail = fmt.Sprintf("%d ABI violations across %d iterations", violations, iterations)
+	}
+	return result
+}
+
 // Close releases the executable mapping.
 func (k *Kernel) Close() {
 	if k.exec != nil {
 		k.exec.Unmap()
 	}
 }
+
+// Image returns the assembled image (code + data + metadata).
+func (k *Kernel) Image() *asm.Image {
+	return k.img
+}