Beagle SCM

BEE-002: cross-repo backlinks — LINK keys on the target's segment hashlets

The wiki, the tickets and the code are separate git repos that link to each other, so "who links to this page" is a question no single lane can answer today: LITE-033's LINK row keys on pathHl(dst text), which is a full repo-relative path, and its dst is resolved through the LOCAL FSEG descent — so a cross-repo target keys differently depending on which repo was indexed first. This ticket re-keys LINK on the TARGET's own segment hashlets, mints from TEXT alone, and answers a query by fanning out over the BEE-001 registry. Indexing ORDER then cannot change a key, and no lane ever reads another lane.

Input

Context

index/lindex.js scans the tip blobs of ONE repo, reads the F tokens of each moved blob (index/hook.js fTokens), resolves each ref through index/resolve.js against the local tip tree, and puts key = dst_hl:40|0:20|7, val = src path_hl:40|0:20|vnib:4.

• The dst is minted from the RESOLVED repo-relative path when exactly one local file answers, from the ref's verbatim text otherwise (the ticket-code case); an ambiguity mints nothing.
• That resolution reads the lane's own FSEG rows, so the key a link gets depends on the state of an index — the ordering hazard this ticket removes.
• suspects() answers from ONE lane and names its rows back to text by descending the local tip tree (namePaths); a foreign repo is invisible.
• BEE-001 landed the registry $HOME/.config/bee/repos, one absolute worktree path per line — the list a query now fans out over.

Goals

bee lindex <target> names the files that MAY link to it in EVERY registered repo, and the answer does not depend on the order the repos were indexed in.

• LINK re-keyed: key = fn_hl:40 | par:20 | 7, val = src path_hl:40 | gpar:20 | vnib:4.
• Mint is a pure function of the ref TEXT: no resolution, no lane read, no repo id.
• Query fans out read-only over the registry: two exact-key seeks per lane, gpar filters.
• A suspect prints repo-qualified, so a hit in another repo is actionable.

Constraints

• Implement in the MAIN TREE /home/gritzko/src/bee — gritzko's explicit permission, 2026-08-15, overriding work; no VC ops there.
• Repro FIRST: two fixture repos, one linking the other, zero suspects today.
• LITE-033's contract holds: suspects not proof, rows never deleted, re-puts idempotent, tip blobs only, the mark row written LAST.
• No new runtime binding (io git abc ron hex utf8 sha1 only); the ONE link recognizer stays hook.js fTokens.
• Local lindex behaviour — ticket codes, self-links, binary/oversize skips — must survive the re-key.

WIP

Design decisions

Ruled by gritzko 2026-08-15 in chat, before any code.

1. LAYOUT. key = fn_hl:40 | par:20 | 7, val = src path_hl:40 | gpar:20 | vnib:4. Every slot is a truncated TEXT hashlet — the filename's top 40, the immediate parent dir's top 20, the grandparent dir's top 20 — under the LITE-011 FSEG rule: 0 spells absent, a genuine 0 bumps to 1.
2. TEXT-ONLY MINT. The scan keys on the ref's own segments and resolves nothing, so no lane reads another lane and the indexing ORDER cannot change a key. dstText's FSEG descent retires for LINK; a ticket code (LITE-029) keys as its own text in the fn_hl slot with both ancestors absent, which is exactly today's behaviour.
3. NO REPO ID, anywhere. The SOURCE repo is the lane that was scanned; the DESTINATION repo is not recorded, so two repos carrying a same-named file produce FALSE SUSPECTS — licensed by the suspects contract, and far cheaper than a dst repo id, which would make REGISTERING a repo invalidate every other repo's lindex mark.
4. QUERY = FAN-OUT. The target's full path gives two exact keys per lane — fn|0 (a bare-filename ref) and fn|par (a ref naming the parent) — and rows carrying a gpar are kept only when it matches the target's. Anything spelled deeper than the grandparent keys the same as a 3-segment ref, so depth costs false suspects, never a wider probe.
5. Every lane is opened READ-ONLY during a query and none is brought up: a stale foreign lane answers with fewer suspects, never with a wrong one. Bare bee lindex still scans the LOCAL repo's tip blobs only.
6. Suspects are named back to TEXT the LITE-033 way, per repo: one descent of THAT repo's tip tree. Output is repo-qualified (the registry path joined to the repo-relative path), local repo first, sorted.
7. FORMAT BUMP. The new LINK keys share the key space with the old ones, so an old row would answer wrongly: the lane extension bumps and openIndex sweeps the outdated files, as LITE-044 ruled. Cost: one re-derive.

TODOs

• repro test: two fixture repos, A links a file in B; bee lindex in B finds nothing today
• LINK re-keyed to fn_hl:40|par:20 / path_hl:40|gpar:20, text-only mint
• self-link and ticket-code cases pinned under the new key
• query fan-out over $HOME/.config/bee/repos, two seeks per lane, gpar filter
• per-repo tip-tree naming, repo-qualified output, local repo first
• lane format bump + sweep of the outdated files
• docs: INDEXES.mkd LINK entry + the suspects section, README.mkd lindex line, index/lindex.js header
• suites test/lindex test/index test/list test/first green

Blockers and bummers

• LITE-044's format bump and sweep were never in the landed tree (the commit 327581a carries the dir revs alone, IDX_EXT stayed .lite.idx), so this ticket wrote the mechanism rather than following one: .lite2.idx plus an openIndex sweep that unlinks every file of the dir that is not of the current format. The sweep NEVER runs on a read-only open, so a fan-out cannot touch another repo's lane.
• The re-key changes LOCAL answers too, and three test/lindex checks were amended to the ruled behaviour: an ambiguous ref now MINTS (nothing resolves at mint time, so there is no ambiguity to skip), a bare TCP.c ref makes every same-named file a suspect (decision 3's licensed false suspect), and every suspect line is repo-qualified.
• test/first (2 of 34), test/merge (2 of 46), test/http (2 of 91) and test/pager (2 of 33) fail identically on a git archive HEAD build — pre-existing (the lite→bee rename in the goldens, one ansi colour golden, the pty frames), not touched here.

Outcome

Landed in the main tree, uncommitted. bee lindex <target> now answers from every registered repo, and the answer no longer depends on indexing order.

• index/lindex.js: linkKey(fn, par) / linkVal(srcPhl, gpar) / linkGpar, the new slots(text) (the three ruled TEXT hashlets via index.js's fnHl and segHl), dstText and its resolver call GONE from the mint, carriers (two exact-key seeks + the gpar filter), nameIn, foreign (one registered repo, READ-ONLY, never brought up, skipped in silence when it cannot be opened), and suspects fanning out over idx.repos(opts.home).
• index/index.js: IDX_EXT .lite.idx -> .lite2.idx with sweep(dir) called from openIndex (skipped on the new read-only third arg), and repos(home) — the registry reader track() now shares.
• Docs: INDEXES.mkd (lane extension, the LINK entry, the "who links" bullet, three new suspects-contract bullets), README.mkd lindex line, index/lindex.js header.
• Tests: test/lindex/run.sh leg 6 (the two-repo repro: cross-repo hit, bare-filename ref, gpar filter, ticket code, self-link, idempotence) plus L4b (the sweep) and the amended local checks; test/lindex/rows.js re-keyed; the extension assertion in test/index/run.sh and test/first/run.sh.
• Green: lindex 40 (31 before), index 135, list 83, plus blob 13, cat 35, chat 148, click 24, commit 45, commitnav 32, cursor 43, diff 34, hook 14+7, land 40, logspine 41, mark 66, now 42, perma 51, refline 38, render 59, rst 92, tree 47.