Beagle SCM

SUBS-050: one parsed-branch type for all branch paths

REBASE 2026-07-15: the shape inventory shrinks — ?/libdog/.jab/JS-101 (absolute dot-chain) and ?.libdog/.jab/JS-101 (relative) both die with the dot-branch (URI-016 d5, SUBS-054); the replacement shapes are the wtlog pin rows ///path/to/sub?proj_branch#pin and ///path/to/sub/?branch#base. The unify-on-one-parsed-type goal stands and gets easier.

Branch paths in be/ JS are handled by ad-hoc string surgery at every call site; three recorded shapes leak verbatim into display, so status labels the same branch three ways at three depths: plain ?JS-101 (primary wt), absolute ?/libdog/.jab/JS-101 (mounted sub), relative ?.libdog/.jab/JS-101 (sub-of-sub, title-stripped rows). Unify on ONE parsed type { title, branch: [segments] } and ONE helper module; no string concat or manual parsing at call sites.

Input

Context

shared/branch.js (SUBS-048) is an ORPHANED string codec — nothing requires it; every call site grew its own indexOf/slice surgery. Composers: submount.js:114 syntheticBranch (manual slice surgery; writes the absolute sub-anchor shape at :233/:283/:325), store.js:626 keyURI/refKey, relate.js:29 resolveRef (refs/heads/X KEEPS the title — disagrees with serve.js:45 which advertises the title-STRIPPED branch), status.js:365 "?"+rawQuery verbatim, refs.js:34, head.js report, get.js ?<branch>#<tip> wtlog rows. Parsers: wtlog.js:36 stripProject + refOf (&-chain), store.js:588 stripProj (byte-identical duplicate of stripProject) + resolveRef's 3-way fuzzy match + shaOf's /proj/branch/<sha> split, get.js:92 query.slice(1).split("/"), wire.js:135 refs/heads/ strip, post.js resolveTarget, delete.js:330, patch/fetchleg.js. Related: SUBS-040 dot-branch tracking, SUBS-023 synthetic-name get (wontfix), Submodules wiki, BE-011 segment-array path law.

Goals

• ONE value type: sub { title: "abc", branch: [".libdog", ".jab", "JS-101"] }; plain { title: "proj", branch: ["feature"] }; trunk branch: []. Dots stay ON the segments.
• ONE module (rewrite shared/branch.js) owning parse / format / key / sub / wireRef / fromWireRef / isTrunk / display, built over util/path.js split/merge segment arrays.
• status shows ONE branch label shape at every depth.
• Every composer/parser site above routes through the module.

Constraints

• Read-compat FOREVER: parse() accepts all three recorded shapes (absolute / relative-dotted / plain) — old wtlog/refs rows.
• refs-log KEY bytes unchanged (title-stripped rel) so existing refs rows still resolve; NO store migration.
• Wire refs title-stripped (refs/heads/<rel>, the serve.js form); relate.js adopts it.
• test/submount.js:121-129 pins syntheticBranch output — KEEP the expected strings, retarget the calls to the new helper; no other test edits without explicit permission.

WIP

Design decisions

• Display rule = format(br): plain ?feature for a primary wt, absolute ?/<title>/.<parent>.../<branch> for a mounted sub.
• Branch objects are INTERNAL; text only at IO edges (ulog rows, wire refs, display labels), parsed once on entry.

TODOs

• rewrite shared/branch.js: parse/format/key/sub/wireRef/

  fromWireRef/isTrunk/display + 3-shape round-trip unit test

• repro FIRST: 3-level status label test (one shape expected)
• wtlog.js: tip/attachedBranch/refOf yield parsed branch;

  kill stripProject

• store.js: refs r/w keyed on key(br); kill stripProj, the

  fuzzy resolveRef match, shaOf's split

• submount.js: syntheticBranch → branch.sub()
• verbs: get.js remote parse, post.js resolveTarget,

  delete.js, head.js, patch/fetchleg.js

• wire refs: relate.js + serve.js + wire.js via wireRef()
• views: status.js + refs.js labels via display()

Blockers and bummers

• relate.js resolveRef NOT converted: test/put/wire-refguard pins the old title-KEEPING push ref (/project → refs/heads/project) + raw-segment POSTREF guard; the codec's split/merge collapses those. Push/advertise wire refs still disagree; amending that test needs an explicit user ruling.

Outcome