Module substrate 

§12 substrate — prime’s bootstrap-on-miss, the retired init.

Founding is not a separate verb: it is the local-miss branch of idempotent prime (§12). The two-branch substrate (§2) is founded in TWO steps, on two different schedules:

• found_landing lays the landing (balls/config, holding config/) as the repo’s first worktree EAGERLY — prime needs its config/ to know the plugin chain and the configured tasks_branch before it can do anything.
• materialize lays the store (tasks_branch, holding tasks/) LAZILY, between prime’s pre and post phases (bl-0a23): it checks out the branch if a ref already exists — a remote one the prime/pre tracker just cloned in (§12) — and founds a fresh orphan ONLY when no such ref exists (the genuine no-remote bootstrap). Founding eagerly would create a divergent orphan that an established remote could not fast-forward onto, the unrelated-histories bug bl-fa00 had to reset away; materializing after the tracker’s clone-in means that divergence is never CREATED.

One repo, two branches, two real checkouts — no symlink indirection, no chain to resolve (§1). Core knows nothing of remotes here (§0); it only ensures the two checkouts exist and seeds the landing’s config/ from the app default-config (crate::seed). Re-running prime skips both steps (the landing is already a landing, the store checkout already sits on the configured tasks_branch — the §12 predicate, not “a store dir exists”, bl-eb52), so the whole verb converges to a no-op — there is no --reinit.

Functions

found_landing

Found the landing half of the substrate (§2 bootstrap-on-miss): the balls/config branch at landing, its config/ SEEDED from the app default-config (the balls.toml + the plugins.toml hook schedule, with each named plugin found beside bl in exe_dir bound and every absent-binary entry pruned, §12). Returns the seed’s rendered prune notes (a pruned name with a [source] hint, bl-5b09) for prime to emit through the op log once it has one — founding necessarily precedes the log’s threshold read. The caller guarantees is_landing is false, so this never clobbers an established checkout.

is_landing

Is the landing already founded? A founded landing has a COMMIT on the balls/config branch (§12) — founding’s ONE commit point, not the config/ folder found_landing creates on its way there (bl-ffbf).

materialize

Ensure the configured tasks_branch name IS the store checkout at store — the lazy “a branch is a disk path” primitive prime drives between its phases (bl-0a23). Two invariants, each established only when missing, so a re-prime converges to a no-op:

warn_founded_ancestor

The bl-b915 founding advisory: report-only scrutiny, zero mechanism added to resolution — never a refusal, never a redirect. Call only on the miss branch of prime, right before found_landing: the caller is ABOUT to found a brand-new store at invocation_path, so if a founded store already sits at some ANCESTOR directory (balls’ own record — Xdg::nearest_founded_ancestor stats the ancestor’s own clone dir, git never consulted), that is almost always the bl-0bd8 invisible-sibling-substrate footgun rather than a deliberate nested/sibling store: warn on stderr, naming the -C escape hatch (bl-c620), and let founding proceed regardless.