crucible-gen¶

Standalone tool for generating synthetic GGUF seed corpus files.

Usage¶

crucible-gen [flags]

Flags¶

Flag	Default	Description
`--output`	`./corpus/generated`	Output directory
`--count`	`50`	Number of mutated files to generate
`--seed`	`0`	Random seed (`0` = time-based random)
`--mutate`	`true`	Also generate mutated variants
`--talos`	`false`	Generate Talos CVE-targeted seeds into `corpus/reconstructed/`
`--arch`	`false`	Generate architecture-targeted seeds for model-loader fuzzing
`--clip`	`false`	Generate clip/vision-model-targeted seeds

What It Generates¶

Structural Seeds¶

These are valid GGUF files designed to exercise different parser code paths:

Seed Type	Purpose
Minimal valid file	0 tensors, 0 metadata — baseline
Single tensor + metadata	Minimal non-trivial file
Many tensors (100+)	Stress-test iteration loops
Per-value-type seeds	One seed for each of the 14 metadata value types
Per-tensor-type seeds	One seed for each common ggml type (F32, F16, Q4_0, Q4_1, Q8_0)
Nested array metadata	Array-of-arrays to test recursive parsing
Various alignments	1, 8, 16, 32, 64, 128 byte alignments
Edge-case dimensions	1x1, 1x1x1x1, 4096 single dimension
Mixed tensor types	Multiple tensors with different quantization types

Mutated Variants¶

When --mutate is enabled (default), also generates files with 1-3 structure-aware mutations applied to each structural seed.

Examples¶

# Generate default corpus
crucible-gen

# Generate 200 mutated files with deterministic seed
crucible-gen --count 200 --seed 42

# Structural seeds only (no mutations)
crucible-gen --mutate=false

# Output to custom directory
crucible-gen --output /path/to/corpus

# Generate CVE-reconstruction seeds for regression testing
crucible-gen --talos

# Generate architecture-targeted seeds for model-loader fuzzing
crucible-gen --arch

# Generate clip/vision-model seeds
crucible-gen --clip

Output¶

Generating GGUF seed corpus to ./corpus/generated
  Wrote 25 structural seeds
  Generated 25/50 mutants (last: metadata.alignment_poison, tensorinfo.offset)
  Generated 50/50 mutants (last: header.version, consistency.tensor_count)
  Wrote 50 mutated variants
Done. Total files in ./corpus/generated

Files are named seed_000.gguf, seed_001.gguf, ... for structural seeds and mutated_0000.gguf, mutated_0001.gguf, ... for mutated variants.