Beagle SCM

DIS-072: a submodule must track the parent's pin URI //WT/path/to/sub; kill the synthetic pin-branches

RULED 2026-07-15 (gritzko, law #4 of DIS-071): a submodule tracks the parent's PIN, addressed by the child worktree's own local URI //WT/path/to/sub — the same syntax a worktree tracks — set by the parent's first get and refreshed by any later parent update; the sub's own commit leaves the pin behind and DETACHES it (bare-hash post records, DIS-075), and ONLY the parent's get/post re-attaches it by writing a fresh //WT/path/to/sub#<hash> record. be/ JS instead mints a synthetic branch /child/.parent/.grandparent/gp_branch (submount.js:109-116 syntheticBranch over branch.js:64-68 sub()), records it as an ordinary ATTACHED branch (submount.js:287), and lets the child's own commit advance that ref (post.js:720-721) — so a sub never detaches and the parent never refreshes anything. Submodules:7-8,28,49 specs the synthetic branch and is rewritten here. Carries the pin half of the stale DIS-061 (whose 2026-07-13 pin-reflection ruling — materialized pin refs the parent maintains — is overruled by the URI model).

Input

Context

The sub is mounted on an invented branch nobody owns; the pin relation it should track exists only as a comparison in subs.js.

• syntheticBranch composes /<title>/.<parent>[/<parent_branch>] (submount.js:109-116) via branch.js:64-68 sub(); the mount records it as get ?<synthetic>#<pin> (submount.js:287).
• The child's own commit advances the child's ref — att.detached is false for a mount, so post.js:720-721 fires.
• Nothing anywhere refreshes a pin-branch ref on a parent base move: the only ref writers are post.js:225-231 advanceRef and put.js:96,110.
• subs.enumerate already compares the sub's curTip against the parent's gitlink for the adv/ok/stale buckets (subs.js:84-122) — that comparison IS the pin relation the track URI should name.
• Nested subs are FLAT under the owning wt (RULED 2026-07-15): //ABC-123/lib/abc/dog, so the .parent/.grandparent chain (Submodules:49) has no successor.
• DIS-063 wants a fork to INHERIT the source's pin-branch — under this model it inherits the source's track URI instead; reconcile at land time.

Goals

The pin is a URI the parent writes, not a branch the child owns.

• The mount records get //WT/path/to/sub#<pin>: the pin resolves through the parent's gitlink — no refs entry, no synthetic branch, no .parent chain.
• A sub's own commit records a bare-hash post row (detached, DIS-075) and moves NO ref; status keeps reporting it "adv" off the same pin comparison.
• The parent's get/post re-attaches each immediate child by writing a fresh //WT/path/to/sub#<newpin> record into the child's wtlog.
• Delete branch.js:sub() + submount.js:syntheticBranch; rewrite Submodules:7-8,28,33,49 and its Store-layout section to the pin-URI model.

Constraints

Old mounts must survive the flip, and the orphaned refs are somebody else's problem.

• Read-compat: existing sub wtlogs carry ?/child/.parent/br#pin rows and must still parse, re-anchoring on the next parent move (DIS-071 law).
• Synthetic-branch refs already written into shards become orphans; a tombstone sweep is OUT of scope — file a follow-up if they hurt.
• Depends on DIS-071 (row grammar) and DIS-075 (detach shape); the commit/advance split rides DIS-076.
• Repro-first; a fixture seeds with jab get file:<path> (the working wt-clone form), 2 levels deep.

WIP

Design decisions

• (none yet — the pin-URI shape is RULED, the resolution path through the parent's gitlink is not designed)

TODOs

• repro: mount, commit in the sub → sub detached, NO ref moved; parent post → sub re-attached at the new pin
• repro: sub-of-sub tracks //WT/lib/abc/dog flat, not a .parent/.grandparent chain
• submount: record the pin URI; delete syntheticBranch + branch.js:sub()
• post/get: the parent refreshes each immediate child's track record on ANY base move
• Submodules rewrite (:7-8,28,33,49 + Store layout)
• test inventory: SUBS legs pinning synthetic branches; request the user

Blockers and bummers

• SUBS-040 I2 and DIS-058 both carry the synthetic-branch model as settled — each needs a ruling note pointing here.

Outcome

• FILED 2026-07-15 (track/base audit); nothing landed yet.