Beagle SCM

BEE-006: a submodule is an ordinary repo — install and index recurse into it

index/index.js readTree DROPS gitlinks (mode 0o160000) — a submodule's blobs live in another ODB, so rows about them in the parent's lane could never be rebuilt by rm -rf .git/be there. Submodules are therefore invisible to bee today: html/ in the journal lists blank and its pages are unreachable. The ruling is uniformity, not a special case: bee install and bee index RECURSE into every initialised submodule, so a sub is an ordinary registered repo with its own lane and every link crossing the boundary is an ordinary cross-repo link (BEE-002).

Input

Context

BEE-001 made install the registration point ($HOME/.config/bee/repos, one absolute worktree path per line) and gave it the index + lindex bring-up; nothing walks into a submodule.

• A submodule's .git is a GITFILE into <parent gitdir>/modules/<name>, and it carries no commondir — so BEE-001's linked-worktree refusal does not trip on it.
• An UNINITIALISED submodule has an empty dir and no gitdir at all: there is nothing to index and nothing to register.
• The parent's own commits that BUMP a gitlink are the only record of when the sub moved — the sub's own history knows nothing of it.
• LITE-044 already mints one REV-CMMT row per changed DIR, which is exactly the shape a gitlink bump needs.

Goals

Installing or indexing a parent leaves every initialised submodule installed and indexed too, and no code anywhere carries a submodule case.

• bee install <parent> registers and brings up the parent AND each initialised submodule, depth-first, and says how many it took.
• bee index <parent> brings up the submodule lanes the same way; opts.track === false still writes no registry line, for any of them.
• An uninitialised or unreadable submodule is SKIPPED in words, never a failure of the parent's run.
• The parent keeps the gitlink's own history: one REV-CMMT row on the submodule's path per commit that moved the pointer, so bee list attributes the row.

Constraints

• Worktree /home/gritzko/src/bee2 (branch worktree2), gritzko's call; no VC writes in it or in the main tree.
• Repro first, as a test: a fixture parent with one real submodule.
• The gitlink DROP in readTree stays — the parent's lane must never carry a foreign blob's row.
• Enumeration comes from the tip tree's gitlinks or .gitmodules, not from a shelled-out git submodule walk if the ODB already answers.
• Recursion must terminate on a cycle (a sub pointing at an ancestor path) and must not follow a sub that lies outside the parent's worktree.

WIP

Design decisions

1. UNIFORMITY IS THE POINT: a submodule is registered, indexed and linked exactly like any other repo, so the only new code is the WALK, not a case.
2. The parent-side exception is attribution only: a gitlink bump mints ONE REV-CMMT row on the submodule's path (LITE-044 dir-rev shape), never a REV-BLOB — a commit sha is no blob of the parent's.
3. RULED (agent, 2026-08-15): bee index <parent> DOES recurse by default, because the N-gitdir fear is not the hot path — the views (list, log, diff, lindex, door) all ride bringUp on ONE open repo and never recurse, so only the explicit index verb and install walk subs, and a repo whose tip carries no .gitmodules pays one cached Map hit. index takes opts.subs === false for a caller that must not.
4. The parent's ATTRIBUTION cannot ride descend: dog/git's GITTreeDiff drops gitlinks in C (git_td_next), so no diff ever hands one back. The gitlink revs are minted beside it, from the tip's sub paths compared over the commit's tree and its parents' — readTree's drop stands untouched.

TODOs

• repro test: a fixture parent + submodule — html/ no row at all, the sub unregistered
• gitlink enumeration off the tip tree, gated on .gitmodules, uninitialised ones skipped in words
• install recurses: register + index + lindex per sub, counted in the report line
• index recursion, under the ruling taken above; track: false still writes nothing
• parent-side gitlink dir revs so bee list attributes the submodule row
• cycle and out-of-tree guards
• docs: README.mkd install/index lines, INDEXES.mkd gitlink sentence + dir-rev entry, index/index.js header
• suites test/index test/list test/lindex test/first green

Blockers and bummers

• The repro was WORSE than the ticket said: html/ had no row at all in bee list (a dropped gitlink is no entry), not a blank one. view/list.js now adds the sub rows off subTree and sorts them git's way.
• CLICKING a sub row still goes nowhere: the target is list <abs>/, which the parent's own repo cannot answer. Crossing the boundary is BEE-002.
• Pre-existing at 2fbda56, verified against a git archive build: test/first (2, the non-repo bare run), test/http (2), test/merge (2), test/pager (2, the pty goldens). Everything else green.

Outcome

Landed in the worktree /home/gritzko/src/bee2, uncommitted.

• index/index.js: subTree/subPaths/submodulePaths/subAt (the gitlink reader, memoized per tree, gated on .gitmodules at the tip), subRevs (one DIR rev per pointer bump, emitDir's shape), submodules (the initialised ones, skips in words), indexSubs (depth-first recursion, flat rec.subs, _seen cycle guard), subsSaid (the report tail).
• merge.js install: the recursion's subs are tracked and lindexed, and the one line says "took N submodules" plus every skip.
• view/list.js: the sub's row, attributed off the gitlink dir revs.
• Tests: test/index/run.sh leg 5 (7 shell checks) + test/index/subs.js (6 checks: the walk, track: false writing nothing, REV-CMMT and no REV-BLOB, no row keyed by the sub's commit). index 148, list 83, lindex 31, plus 16 more suites green.