Beagle SCM

JAB-034: the ULOG handle is a bare pointer-as-Number — no finalizer, no ownership, no guard

_ulog_open heap-boxes a booked mmap plus its wh128 sidecar and hands the raw pointer to JS as a *Number*. A Number owns nothing: drop it and the mapping, its fd and the sidecar leak for the life of the process — GC cannot reclaim what it was never told about. The reverse cast is unguarded too, so any JS number reaches raw memory. Found while measuring JAB-033; today's two callers happen to close correctly, so this is a LATENT defect of the binding contract, not a live leak.

Input

Context

Read-only inspection of ///jab#8335085b on 2026-08-05, out of the JAB-033 measurement pass; the mmap side of the same question is ABC-020.

• ulog.hpp:251 — the box is typedef struct { u8bp data; wh128bp idx; } jabc_ulog: a booked file mapping AND a sidecar index, both real OS resources.
• ulog.hpp:274-278 — calloc the box, ULOGOpen into it, return JSValueMakeNumber(ctx, (double)(size_t)h). No JSClassRef, no private data, no finalizer callback.
• Contrast io.cpp:632, where a mapping goes out as a typed array WITH a JABCMapFree deallocator — there GC is at least an idempotent backstop. The ULOG handle has none at all.
• ulog.hpp:281-286 — JABCulogHandle runs JSValueToNumber and casts the result straight to jabc_ulog*, guarded only by d <= 0. A stale, wrong or already-closed number is dereferenced: use-after-free or a wild pointer.
• ulog.hpp:250 says close "frees the box (idempotent — nulls handle)", but nothing nulls the JS-side Number, so a double close passes the SAME value in twice.
• Consumers today are exception-proof by hand: be/shared/ulog.js:169-188 closes on a catch arm, :205-220 in a finally. Correctness rests entirely on every future caller repeating that.
• The pointer round-trips through a double — exact only under 2^53, fine now, silently wrong the day it is not.

Goals

The handle OWNS its resources: dropping it on the floor is reclaimable, and a bogus value never reaches raw memory.

• Red-first probe: N x _ulog_open with the handle dropped, no close — count /proc/self/maps lines and fds; unbounded today, must plateau.
• A second red probe: pass a stale (closed) and a garbage handle to _ulog_append — must refuse in plain words, never dereference.
• Explicit _ulog_close stays THE deterministic release; GC is only the backstop, never the plan.

Constraints

• Reuse the object shape the map bindings already use (a real JS object with a finalizer, io.cpp:632) — no third handle convention invented for ULOG.
• ABC idioms per abc; PRO.h in .c files only; errors in plain words, never bare codes.
• Do not change the _ulog_open/_append/_close CALL SHAPE that be/shared/ulog.js writes through without landing the JS side in the same pass — a half-migration breaks every put.
• Keep the pin accounting JAB-033 adds: a ULOG handle pins a mapping and an fd and must be counted like one.
• Clone ///jab/ from the main tree per work; stop and report on any clone failure, no improvised fallback.

WIP

Design decisions

TODOs

• red probe: dropped handles leak maps + fds; red today
• red probe: stale / garbage handle must refuse, not dereference
• give the handle a JSClassRef with private data + a finalizer that closes idempotently
• validate the handle on every entry point (_ulog_append/_count/_rowTime/_close)
• count the handle's mapping + fd in the JAB-033 pin counters
• full suite green, jab/test/ulog_book.js included

Blockers and bummers

Outcome