feat(foundation): type the canonical base-artifact directory of an instance

[nilsonfh]

Summary

Phase (b) of bd 6ns.1: the canonical base-artifact directory of an instance gets its own type, BaseArtifactDir (a NewType over Path, identity at run time).

base_dir named two unrelated things: StudyProject.base_dir is the directory stage commands run in, and the twin's base_dir is <workspace>/instances/<instance>/digital_twin/base. 19 of the 25 functions taking a base_dir documented neither.

What changes

• Producer: ArtifactLayout.base returns BaseArtifactDir. Named for its role in the layout, since the layout is a general mechanism over named instances and the twin is its main reader, not its owner.
• Store: NetworkModelRepository.base_dir — the field. from_parquet keeps accepting any path-like, so the guarantee is about the field, not that constructor. Review raised this, and narrowing was measured rather than assumed: it makes 3 call sites fail, because generate_ev_scenarios, generate_flexibility_provider_artifacts and generate_semantic_graph still declare base_dir: Path. Typing those three signatures, none of which has a docstring yet, is the next phase.
• Readers: twin/network/metadata.py (3 signatures), twin/adapters/validation.py (2), assets/modeling/artifacts.py::load_base_inputs, projects/dashboard_catalog.py::_load_network_metadata.
• Adapters wrap at the call: cim.py (2) and network.py (4) pass BaseArtifactDir(out_dir), with the reason in a comment. The claim "this export writes the canonical base" is the caller's; export(out_dir=...) stays Path, because _validation_report_path already falls back when an export does not land there.
• The 9 --base-dir boundaries convert at add_argument. Their defaults all come from the layout (8 DEFAULT_LAYOUT.base, 1 WORKSPACE.layout.base — measured, none built with Path(...)), so both paths into the parameter carry the type.
• Six base_dir parameters gain their docstring line.

The limit, stated rather than implied. This types the value; it does not prove the directory is canonical (--base-dir /tmp/whatever still type-checks). And it holds where the type is required — the layout, the field, the readers, the argparse boundaries — not at NetworkModelRepository.from_parquet, which still accepts any path-like, so from_parquet(script.root) type-checks today. That gap is named rather than implied away, and closing it is the next phase.

Verification

• Simulated first on a throwaway worktree, mypy A/B per (file, message): typing the producer and store with no call site touched surfaced exactly 6 errors, all in the two adapters. A positive control confirmed a plain Path into build_base_metadata is rejected, so mypy was reading the patched tree. Runtime imports: 0 failures.
• Predicted before measuring: with the wraps in, the three ratchets must read 116 / 846 / 12, identical to main, not merely "no rise". Measured: 116 / 846 / 12.
• On this branch: pinned black/isort/flake8 clean; 18/18 touched modules import at run time; targeted tests 102 passed (workspace layout, repository, base metadata, network adapters, twin workflows and verifiers, project catalog, import hygiene, layer direction, verb prefixes, workspace roots); full suite 2254 passed.

The suite's 2 failures are not from this branch

test_flagship_baselines_value_identical and test_project_workflow.py's regression CLI test fail in this checkout, and would fail without this PR:

• The flagship outputs present here are from a 2026-09-07 run whose manifest records git_commit f6a35e47, which predates the topology re-base (chore(rebase): the Quebec-grounded topology re-base, and the 42 pins it moves #52).
• Control: with those same outputs symlinked into a pristine worktree of main 3c80b88c, with none of this PR's changes, both tests fail identically — "42 of 94 pinned metrics FAILED value-identity", and 42 is exactly what chore(rebase): the Quebec-grounded topology re-base, and the 42 pins it moves #52 re-based.
• CI is unaffected: it has no flagship outputs, so both tests skip there.

Not in this phase

The generate_* / verify_* workflow functions keep base_dir: Path. Closing the argparse boundary was enough to type the value end to end; annotating those signatures is the next step, and several have no docstring to extend yet.

🤖 Generated with Claude Code