FEMIC extension boundary
Brushline extends FEMIC’s instance, rebuild-spec, FreshForge, catalogue, DataLad, and preflight surfaces. It does not import FEMIC internals, fork the provider, or build a second instance-builder package. This page is the pinned boundary.
Exact pins
Component |
Pin |
|---|---|
FEMIC |
|
FreshForge |
|
Boundary schema |
|
FEMIC is an alpha package and its provider API can change between releases. The pin is exact on purpose. A new FEMIC or FreshForge release is a deliberate boundary review with a new pin, a compatible test run, and a changelog entry. It is not a silent dependency upgrade.
Install the optional extra only when the instance builder is needed:
python -m pip install -e ".[femic]"
Brushline core, the contracts, the fixture, and the prototype install and run without FEMIC.
Provider ids
femicfemic.materialization
FEMIC nodes
validate_case, geospatial_preflight, compile_upstream, accepted_btc_handoff,
btc_post_tipsy, export_patchworks, patchworks_preflight, matrix_build,
export_woodstock, ws3_bridge, and ws4_quality.
Materialization nodes
check_toolchain, check_python_environment, install_packages, init_submodules,
init_annex, enable_special_remote, materialize_paths, audit_annex_availability, and
write_materialization_report.
FEMIC CLI commands
femic instance initfemic instance rebuildfemic instance validate-specfemic instance config showfemic freshforge workflows listfemic data bcdc-resolvefemic data bcdc-fetchfemic data bcdc-orderfemic prep validate-casefemic prep geospatial-preflight
FreshForge CLI commands
freshforge validatefreshforge inspectfreshforge planfreshforge runfreshforge providers
Data contracts
femic.lidar.product.v1femic.lidar.bundle.v1femic.inventory.als.v1femic.inventory.als.model.v1femic.climate.v1femic.disturbance.v1femic.efi.model.v1
What Brushline may call
Only the commands and provider nodes above, plus the data contracts as read-only inputs. The
instance-builder extension adds brushline.* provider nodes that call the existing Brushline CLI.
The extension does not call FEMIC Python internals, private functions, or an unlisted command.
What Brushline may not call
FEMIC’s internal modules or private helpers.
A FEMIC provider node that is not in the pinned list.
A data contract that is not in the pinned list without a boundary review.
A second data-acquisition or instance-builder package.
Compatibility check
from brushline.integrations.femic import check_femic_compatibility
report = check_femic_compatibility("0.2.0a1", "0.1.0a5")
if not report.is_compatible:
raise SystemExit("\n".join(report.errors))
The check rejects a different FEMIC version, a different FreshForge version, and an invalid version string. A missing FreshForge version is a warning, not a pass.
The committed pin is notes/reference/femic-provider-api.v1.json. It records the versions, the
provider ids, the node ids, the CLI commands, and the data contracts. The validator compares the pin
with the canonical manifest and fails if a provider, node, command, or contract is missing or extra.
Regenerate the pin
After a deliberate boundary review:
python - <<'PY'
from pathlib import Path
from brushline.integrations.femic import write_boundary_pin
write_boundary_pin(Path("notes/reference/femic-provider-api.v1.json"))
PY
Then update the version constants, the compatibility tests, the changelog, and this page in the same change set.
Drift policy
The pinned surface is the contract.
A drift test fails when the pin and the canonical manifest disagree.
A FEMIC upgrade requires a new pin, a review of the provider nodes, a compatibility run, and a changelog entry.
A Brushline provider node may call only a declared FEMIC command or data contract.
A missing provider or node is a blocker, not a warning to ignore.