Repo and Runtime Invariants

Purpose

This page is the compact source of truth for the invariants that should be assumed before running or extending FEMIC from this checkout.

Quick Contract

Seam

Contract

Canonical repo root

Use the active checkout root as the canonical repository root for commands, patches, and file references. Prefer repo-relative examples in published docs rather than machine-specific absolute paths.

Stale path mentions

Treat unexpected stale workspace paths in session or editor metadata as stale context only. Do not use them for execution; use the active checkout root instead.

Python environment

Use a repo-local .venv and install requirements-dev.txt before FEMIC development or docs work.

Submodules

Initialize submodules before relying on bundled example instances or the public-data mirror.

Annex-backed public data

external/femic-public-data is not usable until git annex works, the arbutus-s3 remote is enabled, and datalad get has materialized real payloads. For Windows-specific Arbutus bootstrap or publication work, the canonical maintainer runbook is Public Data Mirror Runbook.

External data root

Export FEMIC_EXTERNAL_DATA_ROOT before case preflight and pipeline runs when using the linked public-data mirror.

Preflight

Run femic prep validate-case and femic prep geospatial-preflight before long workflows. On Windows, validate-case is also the intended low-noise place to catch Arbutus auth-format and bucket-visibility failures before users fall into noisy git-annex diagnostics, and to catch canonical FADM_TSA.gdb materialization/readability failures before users misdiagnose them as generic GDAL/FileGDB incompatibility.

External runtime boundaries

BatchTIPSY and Patchworks remain external/proprietary runtime seams; FEMIC documents and validates those boundaries but does not replace those tools.

Fresh-Clone Baseline

Linux/macOS:

python -m venv .venv
. .venv/bin/activate
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements-dev.txt
git submodule update --init --recursive
git annex version
datalad --version
git -C external/femic-public-data annex enableremote arbutus-s3
datalad get -r external/femic-public-data/data
export FEMIC_EXTERNAL_DATA_ROOT=$PWD/external/femic-public-data/data
femic prep validate-case --instance-root external/femic-k3z-instance --run-config config/run_profile.k3z.yaml
femic prep geospatial-preflight

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip setuptools wheel
python -m pip install -r requirements-dev.txt
git submodule update --init --recursive
git annex version
.venv\Scripts\datalad.exe --version
git -C external/femic-public-data annex enableremote arbutus-s3
.venv\Scripts\datalad.exe get -r external/femic-public-data/data
$env:FEMIC_EXTERNAL_DATA_ROOT="$PWD\external\femic-public-data\data"
femic prep validate-case --instance-root external/femic-k3z-instance --run-config config/run_profile.k3z.yaml
femic prep geospatial-preflight

Do Not Assume

  • Do not treat symlinked annex pointers as usable data files before datalad get completes.

  • Do not assume a passing femic prep geospatial-preflight result proves the active annex-backed FADM_TSA.gdb checkout is readable on Windows; femic prep validate-case is the case-aware check for that seam.

  • Do not assume quoted values in a local Arbutus env file are harmless; for the documented Windows auth-file workflow, quoted KEY=VALUE lines are an input bug, not an accepted variant.

  • Do not assume proprietary runtimes are vendored into the repo.

  • Do not assume a Windows-only helper is available on Linux, or vice versa.

  • Do not assume the current working directory is the intended instance root if --instance-root or FEMIC_INSTANCE_ROOT has been supplied.

See Also