Beagle SCM

LITE-011 DONE: FSEG records — resolve a partial path against a commit

Ruling (gritzko 2026-08-13): a user names a file as a PARTIAL path (abc/TCP.c), and the index must turn that into the full repo-relative path it stands for. The LITE-006 lane is hash-only and hands back no text, so the index cannot answer alone: it narrows, a real tree object answers. A new record keyed by the filename hash carries the ancestor segment hashes, which prune a descent of the commit's tree down to (almost always) one line; the tree entries carry the real names, so the recovered path is TEXT, and path_hl falls out of hashing it. Resolution is always RELATIVE TO A COMMIT, most often HEAD.

Input

Context

lite log <path> / lite diff <path> take a path today only because the caller spells it in full: INDEXES.mkd states the gap outright — "NO name or suffix lookup: dog/git/ZINF.h, git/ZINF.h and ZINF.h hash to three unrelated keys". path_hl is a one-way 40-bit hash of the WHOLE path, so a partial spelling hashes to nothing the lane holds.

• Nibble 6 is free: LITE-006 spends 1..5 and F (index/index.js:60).
• Matching a partial path to path_hl is USELESS (it hashes the whole path); the record's job is to prune a tree descent, not to name a key.
• The value's bits are better spent on the ANCESTOR CHAIN: with a tree object in hand, per-segment hashes filter the entries at each level.
• The indexer already sees full path text while descending trees, so the row costs it no second pass.

Goals

resolve(commit, "abc/TCP.c") returns the full repo-relative path(s) that partial names in that commit, or none, in plain words.

• RECORD FSEG (kind 6), one row per distinct path ever seen:
  1. key = fn_hl:40 | prnt_hl:20 | 6 — fn_hl = the top 40 bits of the LAST segment's hashlet, prnt_hl = the top 20 of the immediate parent DIR SEGMENT's hashlet (not of the parent path), 0 = no parent (a repo-root file), a genuine 0 hash bumps to 1.
  2. val = seg0:10 | seg1:10 | seg2:10 | seg3:10 | seg4:10 | seg5:10 | vnib:4 — the ancestor dir segments ROOT-FIRST (seg0 = the topmost dir under the repo root), each the top 10 bits of that segment's hashlet, 0 = no such level, a genuine 0 bumps to 1.
  3. vnib = the TRUE depth (count of dir segments, 0..15), so a path deeper than 6 is self-declaring instead of looking 6-deep; the chain then holds the TOP 6 and the near tail is missing.
• The value is a pure function of the path TEXT — no rev, no commit, no blob — so a row is minted once, re-puts are byte-identical, and it needs no top guard, no watermark and no invalidation. Deletions and rebases never touch it: the row describes a NAME, not a content state.
• ROOT-FIRST is load-bearing: it anchors the descent at the root tree. Nearest-first would leave the walk with nothing to match at level 0.
• index.js emits one FSEG row per path it first sees during its existing tree descent; a rerun over an indexed repo puts nothing new.
• A resolve routine (index/resolve.js) exported for log/diff/any future verb, plus the wiring so a partial path arg is accepted where a full one is today.
• INDEXES.mkd updated: the new kind, and the "NO name or suffix lookup" gap replaced by what actually holds after this.

Constraints

Work in lite/ only; be/ and jab/ are READ-ONLY precedent, never imported; never read beagle/. Zero quickjab edits are the expectation (LITE-006 managed it) — a missing binding is a REPORT, not an improvisation.

• No new lane, no new file: FSEG rows go in the SAME <gitdir>/be/*.lite.idx family, so rm -rf .git/be still rebuilds everything.
• DOG-027 write discipline (<=200 rows per batch) and the LITE-006 seal order stand — FSEG rows are rev rows for ordering purposes (before that commit's CPAR).
• Scratch and dev builds in ~/tmp; no VC ops (put + report only).
• Existing test/index/ checks must stay green; the row count in their assertions will move — adjust the counts, not the semantics.

WIP

Design decisions

Ruled in chat 2026-08-13, before any code:

• RESOLUTION IS PER-COMMIT: resolve(commit, partial) -> 0..n paths, the commit defaulting to the HEAD tip; each verb already has one (diff <hex> that commit, log/diff <path> the tip). A row that does not descend in THAT commit is simply not a hit — "no such path at <sha8>" is the answer, never a widening to other commits.
• THE DESCENT, given candidate rows and a root tree:
  1. scan the lane for the key prefix: fn_hl|prnt_hl (60 bits) when the partial has a parent, fn_hl alone (40 bits) for a bare filename;
  2. at level i keep only the entries whose name's top-10 hashlet equals seg_i, recursing into those trees, accumulating the real segment names;
  3. below the chain (depth > 6, per vnib) the walk goes wide for those levels;
  4. at the bottom verify the parent dir name at 20 bits against prnt_hl and the entry name at 40 against fn_hl;
  5. survivors carry their full TEXT — that is the answer; path_hl = hlOfText(path) >> 20 re-enters the LITE-006 scans unchanged.
• ITERATIVE, NOT RECURSIVE: at 10 bits a 100-entry dir yields ~0.1 false branches per level, so the descent is a LINE almost always. Write it as a loop with a small fixed pending stack that is empty in the common case — cost is depth tree reads, no blob is ever opened, so resolution results need no cache and no record of their own.
• BATCH THE CANDIDATES: several rows (a bare TCP.c) descend in ONE pass — union their seg0 at the root, seg1 at the next level, carrying the still-live row set down each branch — so a bare filename costs about what a qualified one does.
• AMBIGUITY IS THE ANSWER, NOT AN ERROR: two real TCP.c under different dirs come back as two paths and get printed as two paths. A hash collision costs one wasted tree read and never a wrong answer, because the bottom verifies against real names.

TODOs

• FSEG kind + pack/unpack in index/index.js (mirror the existing key/val helpers)
• emit one row per first-seen path in the tree descent; batch/seal order unchanged
• index/resolve.js — prefix scan, batched iterative descent, bottom verify
• wire partial paths into log and diff path args; ambiguous = list the paths
• test/index/ — fixture repo cases: qualified, bare filename, ambiguous, root-level file, depth > 6, absent-in-this-commit, deleted-before-HEAD-but-present-in-<hex>
• rerun-emits-nothing check; existing test row counts adjusted
• INDEXES.mkd — the kind, the descent, the corrected "what is NOT indexed"

Blockers and bummers

• (none yet)

Outcome

• (open)