Layered profiles and write targets¶
How canair finds a profile, how a read-only base and the capture layer of a user combine, and how canair keeps a write from landing where the next reinstall deletes it. Read this page before you change profile discovery, a capture reader or writer, or any command that edits a profile. The user-facing view is Profiles and its layering section.
Finding a profile¶
Because more than one profile ships, canair selects none for you. The precedence is:
--profile NAME|PATH(a global flag, before or after the subcommand)CANAIR_PROFILEdefault_profilein the user config- a single discovered profile
profile/discovery.py::profiles_roots lists where to look, highest precedence first:
--profiles-dir$CANAIR_PROFILES_DIRprofiles_dirin the config~/.config/canair/profiles/(user profiles, uncommitted)- the
profiles/directory of the repo
A user profile shadows a bundled one of the same name, unless it declares extends:. Then it
layers.
Names follow make-model-code-drivetrain, never a year (profile/names.py). A renamed profile
keeps its old names under aliases:.
resolve_profilemaps an old name to the new profile (alias_index). A real directory of the old name always wins.- An overlay that is still filed under the old name layers onto the renamed profile
(
profile_layers(..., old_names)). - Nothing rewrites the config or the directories of a user, because a config is often shared with older checkouts that only know the old name.
selectable_profilesis discovery minus such old-named overlays. Use it, notdiscover_profiles, for anything that canair offers to a user.also_known_as:names are labels for people. They resolve nothing and have one reader:profile/names.py::also_known_as.
The member list of the bundle is not hand-written anywhere else. It is the BUNDLE_MEMBERS
registry in profile/bundle.py. The registry also decides what contribute ships and what the
blind-test strip withholds. A new bundle member is therefore one edit there.
Adopt or overlay¶
Two commands make a profile writable. Both live in profile/scaffold.py and carry no argparse.
-
profile adopt NAMEcopies a read-only profile into~/.config/canair/profiles/. The copy shadows the original. Choose it when you want to change definitions.- It skips members with
role: generated(out/is regenerated, not inherited). - It refuses when a higher-precedence discovery root would keep winning (an explicit
--profiles-diror$CANAIR_PROFILES_DIR), because canair would never read the copy. The message names the blocking root.
- It skips members with
-
profile overlay NAME(overlay_profile) writes only aprofile.yamlwithextends: NAMEand an emptycaptures/. The base keeps tracking upstream while every recording lands in the layer. Choose it when you only want to record.
profile_layers walks the roots and stops at the first bundle without extends:. _from_layers
assembles the Profile. It raises an error in two cases:
- a dangling overlay (nothing underneath)
extends:that names a different profile. Today an overlay must extend the profile that has its own name (or an old name of that profile), and it layers onlycaptures/. A profile that inherits the definitions of another profile with a different name is not built.plans/2026-07-30-profile-variant-inheritance.mdis the design for that definition merge. It is not started, and it keeps theextends:key for this case.
What a layered Profile looks like¶
Profile has overlays: tuple[Path, ...] (least specific first) with layered, write_root
and capture_layers.
- Definitions (
ecus_dir,states_file,signals_dir,can_buses_file,groups_file,meta_file) stay onroot, the base. captures_dirandout_dirderive fromwrite_root, the layer of the user.- Definitions do not overlay.
profile/writable.py::require_writable_definitions()refuses an edit of a layered profile. The one edit funnel that every authoring command shares calls it (cli/commands/_edit.py::edit_scope). It raisesProfileError.cli/__init__.pyreports that error aserror: …with exit code 2, so no command handles it.
Reads span layers, writes do not¶
-
captures/io.py::resolve_capture_layersis the read seam.captures/store.py::load_all_capturesiterates it.load_all_capturesdedupes sessions across layers bycaptures/merge.py::session_key. The base wins, and a session that was contributed and then pulled stays read-only.- It lets an overlay copy supersede the base when the copy shares the
session_anchorof a base session but not its content. canair never counts an edited copy twice. - It sorts chronologically only when layered, so single-layer results stay byte-identical.
-
A reader that bypasses
load_all_capturesneeds a decision per call site.validation/captures.pyandcli/commands/coverage/walk both layers, because a schema break or a payload in the base still matters.contribute/pii.pyandmigrations/captures.pyintentionally stay oncaptures_dir(the overlay). The overlay is exactly whatcontributeships, and the only layer that a migration may rewrite. - Base captures are read-only.
captures/layers.py::refusalenforces it for--delete, the--set-*editors,--backfill-statesand thecaptures uds --steptext user interface.--dry-runstill previews.read_only_filesreturns[]when fewer than two layers resolve, so an ordinary profile is unchanged.layers.py::owning_profilejudges an explicit--dir. - A session has no id. Its identity is its content, plus an anchor
(
captures/merge.py::session_anchor: the date, the label, the version, and the time,rxand parameter identifier (PID) of the first capture). The anchor holds the fields that no editor or repair rewrites. It pairs an edited copy with its original in the merge driver, the contribute overlay and the layered read. A new editor must keep the anchor fields intact. The design rejected tombstones and copy-on-write (plans/2026-08-05-profile-write-targets-and-workspace-hygiene.md).
Never write into the install snapshot¶
A profile that resolves from site-packages (a bare canair from uv tool install, pipx or
pip) accepts writes that the next reinstall deletes. This cost two sessions' captures.
- Detection and the user-facing remedy:
install/context.py::installed_snapshot_kindandsnapshot_write_note. -
Every write path emits that note.
captures/save.py::saved_bannerdoes it for captures.yaml_edit/echo.py::echo_editdoes it for every definition edit.pids,signals,states,groupsandecu addall route their✓ …confirmation through it. That also guarantees that the confirmation names a full path, not a barebms.yaml.
-
canair updaterefuses to be the thing that erases the data.snapshot_profile_risksdiffs the profiles of the snapshot against the profiles of the clone. It lists what a reinstall would delete before it asks to proceed. cli/first_run.pyoffers to adopt a profile, instead of recording adefault_profilethat cannot work.- To fix an existing setup, run
canair config set profiles_dir <clone>/profiles(preferred: git tracks it and you can contribute it) orcanair profile adopt <name>.
A new write path must emit the same note. Plan:
plans/2026-08-05-profile-write-targets-and-workspace-hygiene.md.