Compfuzor Toolkit

Filters and helpers built during the subsystem-model refactor. Each lives in library/filter_plugins/ and is tested in a co-located <name>.test.py.

Filter plugins

merge_with_strategy — merge_strategy.py

Strategy-driven record merger. The core synthesis engine.

# inline strategy map
records | merge_with_strategy(
  {"BINS": "append", "ENV": "dict_overlay"},
  payload_path="contrib"
)

# named profile
records | merge_with_strategy("subsystem_contrib", payload_path="contrib")

String strategies: append, append_unique, dict_overlay, replace

Operation strategies (dict with op key):

op	purpose
merge_keyed	merge lists of dicts by key, with concat_fields for string/list field joining
append_unique_by	append + deduplicate by a dict key (last wins, first-seen position)

Nested strategies: any dict without op is recursed as a sub-field map.

Named profiles:

Profile	Fields
subsystem_contrib	ETC_FILES append, BINS append, ENV dict_overlay, ENV_LIST append_unique, PKGS append_unique
subsystem_artifacts	ETC_FILES append, LINKS append

payload_path walks a dot-separated path (e.g. "contrib.artifacts") to extract the working payload from each record.

Used in: mergeKeyed.py (compat shim)

---

subsystem_record — subsystem_record.py

Builds a subsystem runtime record with computed status/active/reasons from context vars or explicit overrides. Attaches spec and contrib only when appropriate.

"kernel_sysctl" | subsystem_record(
  sysctl_requested, sysctl_bypassed, valid, errors, sysctl_spec, sysctl_contrib
)

Used in: fn_kernel.tasks

---

build_install_bins — build_install_bins.py

Returns standard build_bins / install_bins entries for a stem name.

"sysctl" | build_install_bins
# => {build_bins: [{name: "build-sysctl.sh", ...}], install_bins: [{name: "install-sysctl.sh", ...}]}

Used in: fn_kernel.tasks

---

mergeKeyed — mergeKeyed.py

Compatibility shim over merge_with_strategy's merge_keyed operation. Merges two lists of dicts by key, with optional concat_fields.

enhancedBins | mergeKeyed(bins, key="name", concat_fields=["generated"])

Used in: gen_kernel.tasks, gen_get_urls.tasks, vars_python.tasks, vars_go.tasks

Architecture contract

See doc/arch.md for the full subsystem model, phase lifecycle, prefix conventions (fn_/gen_/fs_), and worked examples.

Task file prefixes

Prefix	Phase	Purpose
fn_*	compile.transform	Normalize input, build subsystem contracts and state
gen_*	compile.synthesis	Aggregate contribs into shared globals
fs_*	fs-apply	Materialize files, links, downloads

Migrated task files

File	Former name	Status
fn_get_urls.tasks	vars_get_urls.tasks	Complete
gen_get_urls.tasks	—	Complete
fn_kernel.tasks	vars_kernel.tasks	Complete
gen_kernel.tasks	—	Complete
gen_tool_versions.tasks	vars_tool_versions.tasks	Complete

Test suite

python tests/filter_plugins/merge_strategy.test.py   # 42 tests
python tests/filter_plugins/mergeKeyed.test.py       # 11 tests
python tests/filter_plugins/merge.test.py             # 25 tests
python tests/filter_plugins/subsystem_record.test.py  # 27 tests
python tests/filter_plugins/get.test.py                #  9 tests
python tests/filter_plugins/cmdline.test.py            # 12 tests
python tests/lookup_plugins/subsys.test.py             #  8 tests