Beagle SCM

BEE-016: bee mint <file>... — the verb that reaches refs no hook can see

A pre-commit hook only ever sees a commit IN FLIGHT, so a ref that landed transient — committed before BEE-014, with --no-verify, or on a commit the hook could not resolve at the time — is unreachable by any hook whatever, and BEE-015 proved --amend cannot rescue it either: it mints against the amended commit as baseline and there is no amend signal in pre-commit to fix that. This is route (3) of BEE-015's Blockers, taken. bee mint <file>... upgrades EVERY transient file:line(:col) ref in the files it is given, in the WORKING copy alone, and the author then commits the result as an ordinary commit — after which the hook finds nothing fresh and does nothing. About 60 such refs sit in ///bee, 15 in ///bee-journal.

Input

Context

The backlog is history the hook can never revisit, and the one move a reader reaches for does not work.

• BEE-015 Outcome: the routes left were D-only (a hook fix that still cannot reach half the cases), an install-contract change, or this verb.
• A verb subsumes route (1) of that ticket: a verb may mint what a hook may not, because the author asked for it by name and can read the report first.
• bee mint views/*.js is the calling shape gritzko specified: the shell globs, the verb takes the LIST — not a repo argument like bee hook [<repo>].

Goals

Transient refs in the named files become permalinks, and nothing else moves.

• The file list names the CARRIERS, not the targets: bee mint doc/page.mkd mints refs WRITTEN IN that file, pointing anywhere the door can reach.
• The WORKING file is the only thing written — no hash-object -w, no update-index, so nothing joins a commit behind the author's back.
• Everything the hook refuses to guess through, the verb refuses too: an unresolved path, an ambiguous one, a line past the end, a link cycle.
• It SAYS what it left alone and why, one line per ref — a verb can afford the conversation a hook cannot.
• --dry-run reports without writing a byte, so the ~75 can be vetted before anything moves.
• Idempotent: a second run over the same files rewrites nothing, because a minted ref carries a hashlet and is no longer transient.

Constraints

• REUSE the hook's minter — targetOf, rewrite, components, mintRef/mintForeign — never a second copy of it (abc "reuse before you add").
• No new link recognizer: the DOG-034 lexer's F tokens through index/hook.js fTokens, as LITE-033 ruled.
• ninja && ninja -j20 test in quickjab/build green; the test/hook and test/perma legs unmoved.

WIP

Design decisions

The verb is the hook's pass with two ends changed: what it scans and where it writes.

• THE SCAN drops the freshness gate. The hook's freshRefs folds HEAD against the staged blob and keeps ADDED tokens; nothing here is fresh, so mint reads every F token of the working bytes and keeps those with a line >= 1 and no hashlet.
• THE RESOLUTION passes an EMPTY staged map to targetOf, so targets come from the LITE-011 descent at HEAD plus the BEE-014 fan-out. A file no commit carries has no blob for a hashlet to name, so it correctly answers nothing.
• THE WRITE-BACK is writeFile only. stageBytes is the hook's half and stays there.
• A DIRTY UNLISTED TARGET IS REFUSED, and this is the one rule the hook has no analogue for: the author's line:col counts lines in the working copy while the only hashable bytes are HEAD's, so minting would anchor to bytes the reader never sees. Listed files may anchor to each other — naming a file is the statement that it is going into the commit.
• A HASHLET INTO A LISTED FILE only resolves ONCE COMMITTED: it names pm.blobIdOf of the post-mint image, an object git writes when the commit lands. Said in the report rather than left as a surprise.
• BARE bee mint IS USAGE, not a whole-tree sweep — 75 files rewritten by a bare word is not a thing a verb should be able to do by accident.

TODOs

• test/mint/run.sh + test/mint/mint.js, RED first (no verb yet)
• index/mint.js: the scan, the resolution, the write-back
• index/hook.js: export targetOf/rewrite/components/readFile/writeFile, and let rewrite return the refs it LEFT so the verb can say why
• main.js: mint: runMint in SIDE, the path LIST unfused
• README.mkd: the verb line
• RUN it over the backlog — ///bee is dry-run clean at 61 refs, ///bee-journal not yet looked at; gritzko's call, and gritzko's commit

Blockers and bummers

• A FOREIGN target is not dirt-checked, matching the hook's existing stance: mintForeign reads the target repo's HEAD blob and the sibling's worktree is not this repo's business. A dirty sibling can therefore anchor a ref the same way BEE-015 describes; noted, not fixed here.
• targetOf answers null for BOTH "nothing spells that" and "several files do", so the report cannot tell the two apart without changing it. The wording says "no one file answers", which is true of both.

Outcome

BUILT AND GREEN, uncommitted: ///bee carries the change in its working tree, no VC op run. ninja && ctest -j20 in quickjab/build is 147/147 — 146 before, plus the new JSRCmint, and JSRChook/JSRCperma unmoved.

• index/mint.js is new and is the whole verb; the minter itself was not copied — targetOf, components and rewrite come from index/hook.js through its exports.
• index/hook.js gained the exports and one behaviour: rewrite returns left, the refs that HAD a target and still did not mint. The hook drops it, the verb reports each one with its cause.
• test/mint/ is 11 shell checks plus 13 in mint.js; it registers itself as JSRCmint through the test/*/run.sh glob in quickjab/CMakeLists.txt. It was RED before the verb existed, on exactly the checks the verb makes green.
• Two things came out of driving it for real, neither in the plan: the report is sorted by file and line rather than by the phase that found it, and --dry-run SPELLS OUT each upgrade (LITE-045:27:t2 -> LITE-045:Nf:t2ME) instead of only counting — a count cannot be vetted.
• bee mint --dry-run over every tracked *.js *.mkd *.sh in ///bee: 61 refs would mint in door.js, index/hook.js, index/index.js, test/hook/cross.js; 15 are refused, all of them "no one file answers" — fixture paths in test docs (src/A.c, TKT-123) and dog/tok/LINK.rl, which lives in a repo that is not registered.
• The cross-repo half works unchanged: ticket codes like LITE-045:27:t2 mint against ///bee-journal through the BEE-014 fan-out, which is most of the 61.