Beagle SCM

JAB-020 JS: narrow the pack bindings to one repack call — the per-object surface exists so JS can drive the record loop, and KEEP-006 moves that loop into libdog

jab/pack.hpp exposes fourteen per-object primitives (_pack_next, _pack_type, _pack_size, _pack_baseoff, _pack_ref, _pack_inflate, _pack_resolve, _pack_scan, _pack_feed, _pack_feed_emit, _delt_apply, _delt_encode, plus _pack_header/_pack_count) for one reason: the ingest record loop runs in JS. KEEP-006 rules that loop into libdog as "repack a git pack", with JS keeping only routing (URL classify, capability/want-have negotiation, pkt-line preamble, refs, shard resolution, rotate policy). So the clone path stops calling any of them and the binding surface becomes roughly one call. This is a NARROWING, not a deletion — _pack_scan still backs the PACK-003 salvage-index rebuild over existing logs, and the primitives remain the test/diagnostic surface. Prototype and measurements are in KEEP-006; method Issues.

Input

Context

• jab/pack.hpp:388-403 registers the fourteen primitives; jab/pack.hpp:246 JABCpackScan marshals PIDXScan into a caller region.
• be/shared/wire.js currently returns { packFile, packLen, verified } and stages a tmp pack via drainToFile/spillToFile — KEEP-006 retires that shape for the clone path (never stored).
• be/shared/wire.js:250 curlRun buffers the whole https response in the JS heap; the fd is what should be handed over, not the bytes.
• Verified in work/KEEP-006: the libdog loop repacks the 6.33 GB linux pack from a PIPE with all 11,690,992 shas matching git, output byte-identical to the mapped run. JS sees no object bytes at any point.
• jab/io.cpp JABC_MAP_MAX (2^31-1, added 2026-07-27) stops being load-bearing for clones once no multi-GB buffer reaches JS — it stays as the backstop for every other caller.

Goals

The clone path crosses the JS/C boundary once per fetch instead of ~11.7M times, and no pack bytes are ever materialised in the JS heap.

• One binding, RULED 2026-07-27: git.pack(fd, buf, shard, opts) -> stats — one call per fetch, no session handle, no step protocol.
• buf (was head) is a JS Buf: PAST|DATA|IDLE over a JS-owned Uint8Array (jab/buf.cpp), already carrying whatever the pkt-line NAK/ACK reader ate off the wire.
• The binding reconstitutes a u8b over bytes/_data/_idle, drains DATA, read()s straight into IDLE, and writes the advanced _data/_idle back onto the JS object.
• buf is REQUIRED (its DATA may be empty): without it the leading records are silently lost — the reason drainToFile(fd, head, destDir) carries one today.
• NO growth: JS sizes buf at the log cap via io._ram (anonymous MAP_NORESERVE, lazily faulted, RSS follows the working set); the binding never remaps and never allocates the input buffer.
• A record that outgrows buf cannot fit a capped log either, so it is a plain-words error ("object at N exceeds the 2 GiB log cap"), not a growth case.
• stats carries objects/raw/ofs/ref counts, bytes in+out, the logs written, and a plain-words error; refs is STRUCK from the shape — refs stay JS routing per KEEP-006.
• The call OWNS the pack log and the index file and keeps BOTH OPEN for its duration, rotating the pair at the cap; map, scratch and fds die with the call.
• curlRun hands over child.stdout rather than returning bytes; spillToFile and the {packFile, packLen} result shape go away for clone.
• The retained primitives keep working for salvage/diagnosis — PACK-003's rebuild must not regress.

Constraints

• Errors cross the boundary in plain words, never as ok64 codes: no PACKBADOBJ, ZINFMORE, PIDXFAIL reaching a user. See the standing ruling.
• libdog knows nothing of curl, HTTP or pkt-line (KEEP-006 ruling) — the binding passes an fd and a shard, nothing protocol-shaped.
• No new buffer primitive: abc/Bx.h PAST|DATA|IDLE + u8bShift/u8bUsed/u8bFed/u8bReMap already cover the reader.

WIP

Design decisions

Both open questions are RULED 2026-07-27; the signature above is settled.

• *Re-entrant REJECTED.* A session handle plus a MORE/DONE step protocol leaks the loop's state (input buffer, map, log+index fds) into the API and ruins encapsulation. One blocking call, everything owned inside.
• *Blocking is fine.* Clone is a foreground operation, and the C loop pumps pol itself between records — pol is in-process C, so keeping the pager and signals alive never has to go through JS.
• *Progress* is an optional callback invoked every N objects, restricted to printing (no re-entry into git.*) — it replaces the quota/step protocol that chunking would have needed.
• *No promises.* be/ contains zero async/await/Promise: io._read blocks and pol._watch/_more is a callback poller, so the JS side is a plain synchronous call.
• *Allocation stays at the top of the chain* (JS io._ram), per CLAUDE.md §5, and the binding keeps pack.hpp's pure-marshalling character — its only mutation of JS state is the _data/_idle write-back.

TODOs

• Settle blocking vs chunked; write the signature — ruled above: one blocking git.pack(fd, buf, shard, opts).
• dog/git/REPACK.c+.h library entry (REPACKRun); REPACK.cli.c is now a thin dogrepack driver over it.
• Statics and the never-freed scratch are gone: one call-owned repack context, released on every exit path.
• git.pack(fd, buf, shard, opts) -> stats binding (abc._pack_repack, jab/pack.hpp); plain-words errors, Buf marshalling with _data/_idle write-back; test/repack.js (JABCrepack).
• ZINFMORE PROPAGATES, never collapsed to PACKBADOBJ: "truncated here" outlives "damaged bytes" and is what PACK-003 salvage needs to tell a torn log from a corrupt one.
• On the three mapped-pack PACKInflate callers (PACK.c:200,238,275) ZINFMORE means truncated-and-unrefillable — document it there, do not rename it.
• Check no JS or test keys on PACKBADOBJ for a truncated tail (the code changed under them), and give ZINFMORE its own plain-words string at the boundary.
• curlRun hands over the fd; drop spillToFile and the {packFile, packLen} clone shape.
• dog/INDEX.md entry for git/REPACK.h (+ PACKResolve, PIDXScanRef, the dogrepack/dogscan pair).
• Give _pack_scan/_pack_resolve a finder so the binding reads rotated logs too: the js store already maps every log and holds the sha→(file,offset) index, so the question is how C++ asks it — not a new structure.
• Verify end-to-end through a real jab get of a large repo — the ingest still calls the OLD path; only dogrepack/git.pack exercise the new one.
• Confirm PACK-003's salvage path still builds indexes over existing logs (the retained _pack_scan).
• Audit which of the fourteen primitives have no remaining caller; report, do not delete in this ticket.

Blockers and bummers

• Everything (the KEEP-006 prototype, ZINFMORE, and now REPACK.c/.h + the binding) is UNCOMMITTED in the main tree, so a worker cloning ///jab or ///jab/dog still gets none of it.
• CLEARED in libdog 2026-07-27: a re-anchored REF record reads back via PACKResolve/PIDXScanRef + a caller finder (KEEP-006 §Outcome; dogscan proves it on git.git at a 128 MB cap). The BINDING still runs the OFS-only pair, so pack.scan: ref-delta stands there until _pack_scan/_pack_resolve get a finder — which needs the js store's index reachable from C++, its own design step.

Outcome

Library entry + binding landed in the main tree (uncommitted), 2026-07-27; the JS ingest still runs the old path, so nothing is switched over yet.

• dog/git/REPACK.h/.c — REPACKRun(fd, buf, shard, conf, idx, st), one call per fetch; dog/CMakeLists.txt builds it into libdog, dogrepack is the CLI driver.
• jab/pack.hpp — _pack_repack + plain-words error map; jab/cont.cpp makes git.pack callable while keeping git.pack.ram/over/mmap/book; JABCPath exported from io.cpp via JABC.hpp.
• Verified: git.git's 315 MB pack, 417,182/417,182 shas + types identical to git verify-pack (single log, 45 s); at a 128 MB cap it streams from a PIPE into 3 logs and emits *57,609* REF records — the exact crossing count KEEP-006's prototype measured.
• Verified through the binding: jab test/repack.js — index entries written into the caller's wh128 region equal the native scanner's keys+offsets, the Buf cursor comes back advanced, a small cap rotates without losing an object; full jab suite 108/108.
• KNOWN, pre-existing: a log holding a re-anchored REF record cannot be scanned back (pack.scan: ref-delta) — KEEP-006 §TODO "Restore REF_DELTA resolution" is the prerequisite, not a regression of this work.