Add graymatter fuzz source workflow

[tomusdrw]

Summary

• Adds a reusable graymatter-fuzz-source.yml workflow that runs the graymatter fuzz-m1-source against any target implementation
• Adds typeberry-fuzz.yml as the first caller workflow
• Adds TypeScript test infrastructure (tests/fuzz-source/, fuzzSource() in tests/common.ts) following the existing picofuzz/minifuzz pattern
• On failure, the workflow creates a deduplicated GitHub issue @-mentioning a configured user
• Documents the new workflow type and review checklist in agents.md

Test plan

• Trigger Fuzz: typeberry workflow manually from Actions tab
• Verify graymatter fuzzer source starts and communicates with typeberry over the shared socket
• Verify failure notification creates an issue with correct labels and @-mention

🤖 Generated with Claude Code

Summary by CodeRabbit

• Tests

  • Added a fuzz-source test harness, helpers, and an entry test to run end-to-end fuzz-source scenarios with per-test lifecycle, shared-volume management, and target/source orchestration.

• CI/CD

  • Added a reusable, parameterized fuzz-source workflow and a TypeBerry-specific workflow to run fuzz tests, support concurrency by target, and optionally create failure notifications when configured.

• Documentation

  • Expanded agent docs with fuzz workflow guidance, examples, and a checklist for reviewing fuzz workflow PRs.

[coderabbitai]

Note

Reviews paused

It looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the reviews.auto_review.auto_pause_after_reviewed_commits setting.

Use the following commands to manage reviews:

• @coderabbitai resume to resume automatic reviews.
• @coderabbitai review to trigger a single review.

Use the checkboxes below for quick actions:

• ▶️ Resume reviews
• 🔍 Trigger review

📝 Walkthrough

Walkthrough

Adds a reusable GitHub Actions fuzz-source workflow, a TypeBerry caller, Docker-based test helpers and end-to-end fuzz-source tests, and documentation updates describing workflow usage and a review checklist.

Changes

Cohort / File(s)	Summary
Workflows .github/workflows/graymatter-fuzz-source.yml, .github/workflows/typeberry-fuzz.yml	Introduce a reusable "graymatter-fuzz-source" workflow (inputs, concurrency, jobs: init, fuzz, notify) and a workflow that calls it for TypeBerry with target-specific parameters (docker image, cmd, env, memory, readiness, mention). Notify job conditionally deduplicates/creates an issue on failures when a mention is provided.
Test helpers & tests tests/common.ts, tests/fuzz-source/common.ts, tests/fuzz-source/fuzz.test.ts	Add SourceConfig and getSourceConfig(), chmodSocket(), and fuzzSource() to run source containers; add runFuzzSourceTest() harness that manages per-test shared volumes and lifecycle; add fuzz.test.ts entry invoking the harness.
Documentation agents.md	Document the fuzz-source workflow, example workflow template, optional inputs (readiness, timeout, memory, mention), deduplicated issue creation behavior, a checklist for reviewing fuzz workflow PRs, and update the key files table to reference new workflows and tests.

Sequence Diagram

sequenceDiagram
    participant Caller as Workflow Caller
    participant Init as Init Job
    participant Fuzz as Fuzz Job
    participant Docker as Docker Engine
    participant Notify as Notify Job
    participant GHAPI as GitHub API

    Caller->>Init: workflow_call with inputs
    Init->>Docker: pull target & conformance-fuzzer images
    Init-->>Caller: init complete
    Caller->>Fuzz: start fuzz job (depends on init)
    Fuzz->>Docker: start target container (shared volume)
    Fuzz->>Docker: start fuzz source container (env, cmd, memory)
    Docker-->>Fuzz: run/monitor, enforce timeouts
    Fuzz-->>Caller: success/failure
    alt failure and mention provided
        Caller->>Notify: run notify job
        Notify->>GHAPI: search for existing issue with labels
        alt no existing issue
            Notify->>GHAPI: create issue with details and mention
        end
    end

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Poem

🐰 I nudged the Docker, set the tests to glide,
I paired the source and target side by side.
If chaos blooms, an issue gets a mention,
Volumes shared, I hop through each contention.
Hop, fuzz, report — a rabbit's CI invention!

🚥 Pre-merge checks | ✅ 2 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding a new GitHub Actions workflow for graymatter fuzz source testing, which is the primary objective of this PR.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch graymatter-fuzz-source

📝 Coding Plan

• Generate coding plan for human review comments

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/graymatter-fuzz-source.yml:
- Around line 28-32: The workflow currently only uses docker_platform for init
pulls so container runs can use the host arch; propagate the selected platform
by adding platform fields to the TargetConfig and SourceConfig interfaces, read
them from TARGET_PLATFORM and SOURCE_PLATFORM environment vars, and then pass
the platform into the docker run commands in tests/common.ts by inserting
--platform <value> immediately before config.image in startTarget() and
fuzzSource(); ensure the env vars are set from the workflow inputs and default
to the existing docker_platform value when missing.

In `@tests/fuzz-source/common.ts`:
- Around line 1-2: The test reuses a fixed shared-volume name which allows stale
sockets to bypass readiness; update createSharedVolume to generate a unique
per-run name (e.g., include timestamp/PID or crypto.randomUUID) and have
tests/fuzz-source/common.ts call it so each fuzz run gets its own volume; also
stop silently swallowing docker volume rm errors in createSharedVolume
(propagate or log the failure) and harden waitForSocket to verify the socket is
actually connectable (reference createSharedVolume, waitForSocket, and the
/shared/jam_target.sock path) rather than only testing file existence.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: e79cacdf-cb30-45e1-8d74-b321ea903151

📥 Commits

Reviewing files that changed from the base of the PR and between 1124ba8 and c55671b.

📒 Files selected for processing (6)

• .github/workflows/graymatter-fuzz-source.yml
• .github/workflows/typeberry-fuzz.yml
• agents.md
• tests/common.ts
• tests/fuzz-source/common.ts
• tests/fuzz-source/fuzz.test.ts

[coderabbitai]

🧹 Nitpick comments (3)

.github/workflows/graymatter-fuzz-source.yml (3)

56-56: Actionlint "perf" label warning is a false positive.

The static analysis tool flagged the perf label as unknown, but this is expected for custom self-hosted runner labels. Consider adding an actionlint.yaml config file to silence this warning:

self-hosted-runner:
  labels:
    - perf

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/graymatter-fuzz-source.yml at line 56, Actionlint is
reporting the custom self-hosted runner label "perf" as unknown; add an
actionlint config to whitelist that label by creating an actionlint.yaml that
defines a self-hosted-runner.labels list containing "perf" (so actionlint
recognizes the custom label used in the workflow file where runs-on:
[self-hosted, perf] is declared).

---

108-108: Consider parameterizing --num-blocks for flexibility.

The fuzz source command hardcodes --num-blocks 100. For different test scenarios (quick smoke tests vs. thorough fuzzing), exposing this as a workflow input would add flexibility.

🔧 Suggested change

Add a new input:

      fuzz_iterations:
        required: false
        type: number
        default: 100
        description: "Number of blocks to fuzz"

Then reference it:

-          SOURCE_CMD: 'fuzz-m1-source --num-blocks 100 --target {TARGET_SOCK}'
+          SOURCE_CMD: 'fuzz-m1-source --num-blocks ${{ inputs.fuzz_iterations }} --target {TARGET_SOCK}'

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/graymatter-fuzz-source.yml at line 108, The workflow
hardcodes "--num-blocks 100" in the SOURCE_CMD which reduces flexibility; add a
new workflow input (e.g., fuzz_iterations) with a default (100) and use that
input in SOURCE_CMD so the command becomes "fuzz-m1-source --num-blocks ${ {
inputs.fuzz_iterations } } --target {TARGET_SOCK}" (reference the SOURCE_CMD
variable and the fuzz-m1-source invocation) to allow configurable iteration
counts for smoke vs thorough runs.

---

54-80: Init image pulls may not benefit fuzz job on different runners.

The init and fuzz jobs both target [self-hosted, perf] runners but may land on different machines. The Docker images pulled during init won't be cached for fuzz if they run on separate hosts.

Consider either:

1. Combining into a single job if image caching is the primary goal
2. Accepting the potential re-pull overhead (current approach is still valid, just slightly less efficient)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/graymatter-fuzz-source.yml around lines 54 - 80, The init
job pulls Docker images that the fuzz job expects but since 'init' and 'fuzz'
are separate jobs both targeting [self-hosted, perf] they may land on different
hosts and the pulled images won't be available to 'fuzz'; fix by merging the
'init' steps (checkout, setup-node, npm ci, docker pull lines for ${{
inputs.docker_image }} and the graymatter fuzzer) into the 'fuzz' job so image
pulls and preparation run on the same runner as the fuzz step (i.e., move the
docker pull commands and installation steps from the 'init' job into the 'fuzz'
job) or explicitly accept the current design and remove the unnecessary separate
'init' job if re-pulls are acceptable.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.github/workflows/graymatter-fuzz-source.yml:
- Line 56: Actionlint is reporting the custom self-hosted runner label "perf" as
unknown; add an actionlint config to whitelist that label by creating an
actionlint.yaml that defines a self-hosted-runner.labels list containing "perf"
(so actionlint recognizes the custom label used in the workflow file where
runs-on: [self-hosted, perf] is declared).
- Line 108: The workflow hardcodes "--num-blocks 100" in the SOURCE_CMD which
reduces flexibility; add a new workflow input (e.g., fuzz_iterations) with a
default (100) and use that input in SOURCE_CMD so the command becomes
"fuzz-m1-source --num-blocks ${ { inputs.fuzz_iterations } } --target
{TARGET_SOCK}" (reference the SOURCE_CMD variable and the fuzz-m1-source
invocation) to allow configurable iteration counts for smoke vs thorough runs.
- Around line 54-80: The init job pulls Docker images that the fuzz job expects
but since 'init' and 'fuzz' are separate jobs both targeting [self-hosted, perf]
they may land on different hosts and the pulled images won't be available to
'fuzz'; fix by merging the 'init' steps (checkout, setup-node, npm ci, docker
pull lines for ${{ inputs.docker_image }} and the graymatter fuzzer) into the
'fuzz' job so image pulls and preparation run on the same runner as the fuzz
step (i.e., move the docker pull commands and installation steps from the 'init'
job into the 'fuzz' job) or explicitly accept the current design and remove the
unnecessary separate 'init' job if re-pulls are acceptable.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 13d503db-3554-45ee-aa7a-a257d997cd47

📥 Commits

Reviewing files that changed from the base of the PR and between c55671b and fdde44d.

📒 Files selected for processing (4)

• .github/workflows/graymatter-fuzz-source.yml
• .github/workflows/typeberry-fuzz.yml
• tests/common.ts
• tests/fuzz-source/common.ts

🚧 Files skipped from review as they are similar to previous changes (3)

• tests/fuzz-source/common.ts
• .github/workflows/typeberry-fuzz.yml
• tests/common.ts

[coderabbitai]

🧹 Nitpick comments (1)

.github/workflows/graymatter-fuzz-source.yml (1)

54-56: Consider adding actionlint configuration for custom runner labels.

The static analysis tool flags perf as an unknown label, but this is a valid custom label for your self-hosted runners. To silence these warnings and document your custom labels, consider adding an actionlint.yaml config file:

self-hosted-runner:
  labels:
    - perf

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/graymatter-fuzz-source.yml around lines 54 - 56, The
actionlint warning is caused by the custom runner label "perf" used in the init
job's runs-on declaration; add an actionlint configuration that declares your
self-hosted runner labels so actionlint recognizes "perf". Create an
actionlint.yaml containing a self-hosted-runner section with a labels array that
includes "perf" (so the analyzer accepts the runs-on: [self-hosted, perf] usage
in the init job). Ensure the file is committed to the repo root or the location
actionlint expects so the linter picks it up.

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Nitpick comments:
In @.github/workflows/graymatter-fuzz-source.yml:
- Around line 54-56: The actionlint warning is caused by the custom runner label
"perf" used in the init job's runs-on declaration; add an actionlint
configuration that declares your self-hosted runner labels so actionlint
recognizes "perf". Create an actionlint.yaml containing a self-hosted-runner
section with a labels array that includes "perf" (so the analyzer accepts the
runs-on: [self-hosted, perf] usage in the init job). Ensure the file is
committed to the repo root or the location actionlint expects so the linter
picks it up.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 28e344d2-cba0-4a90-a29a-25775e8fd904

📥 Commits

Reviewing files that changed from the base of the PR and between fdde44d and 0ff3c0f.

📒 Files selected for processing (1)

• .github/workflows/graymatter-fuzz-source.yml