hbengine 0.2.3 → 0.4.0

package/engine-cli/hbengine.mjs

@@ -6,13 +6,16 @@
  *   hbengine verify  [dir]    the math, by the engine's own verifier: RTP per bet, the hash
  *   hbengine lint    [dir]    the bundle: budgets, staged loading, forbidden code
  *   hbengine dev     [dir]    play the bundle inside the real shell against the sandbox
- *   hbengine test    [dir]    offline: the upload's checks on desktop and phone sizes (Chrome)
+ *   hbengine test    [dir]    offline: the upload's checks on desktop and phone sizes (Chrome);
+ *                             --time-travel: the fake-clock matrix the upload plays too
+ *                             --clock <variant>=<instant>,<zone>,<language>: one variant at the
+ *                             clock an upload's report names
  *   hbengine pack    [dir]    verify + lint, then the .tgz an upload takes (math/, bundle/) to hand over
  *   hbengine upload  [dir]    verify + lint, then the version goes to the portal, which
  *                             registers it with the sandbox and plays the conformance run
  *   hbengine status  [dir]    every version of the game and its state
  *   hbengine stats   [dir]    rounds, turnover, GGR and RTP by coin, last 30 days, and the shell's counts
- *   hbengine store   [dir]    the store page from store.json (and tile.png/.webp, 3:4) to the dashboard
+ *   hbengine store   [dir]    the store page from store.json to the dashboard (Housebets makes the tile)
  *   hbengine submit  [dir]    the newest version that passed every check, to review
  *   hbengine live    [dir]    the newest approved version, live (an owner's key)
  *   hbengine preflight [dir]  the review checklist items a machine can check, on the newest version
@@ -39,19 +42,24 @@
  * Offline (the kit), verify and dev start the kit's engine-dev: the
  * engine's own maths and round rules on this machine, play money.
  */
+import { fileURLToPath } from 'node:url';
 import { execFileSync, spawn, spawnSync } from 'node:child_process';
-import { chmodSync, cpSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, cpSync, createReadStream, existsSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
-import { homedir } from 'node:os';
+import { homedir, tmpdir } from 'node:os';
 import { dirname, join, resolve } from 'node:path';
 import { createInterface } from 'node:readline/promises';
 import { handshake } from './connect.mjs';
+import { MAX_MATH_BYTES, mathBytes, mathTooLarge } from '../engine-math/pack.mjs';
+import { outageArgs } from './outage.mjs';
 import { TEMPLATES } from './templates.mjs';
+import { uploadArchive } from './upload.mjs';
+import { uploadFailure } from './upload-errors.mjs';
 
-const PKG = new URL('..', import.meta.url).pathname;
+const PKG = fileURLToPath(new URL('..', import.meta.url));
 const [cmd, ...rest] = process.argv.slice(2);
 // Flags that stand alone; every other --flag takes the word after it as its value.
-const BOOLEAN = new Set(['--fixed', '--close']);
+const BOOLEAN = new Set(['--fixed', '--close', '--time-travel']);
 const takesValue = (i) => i >= 0 && rest[i].startsWith('--') && !BOOLEAN.has(rest[i]);
 const opt = (k, d) => { const i = rest.findIndex((a, j) => a === '--' + k && !takesValue(j - 1)); return i >= 0 ? rest[i + 1] : d; };
 const flag = (k) => rest.some((a, j) => a === '--' + k && !takesValue(j - 1));
@@ -136,17 +144,21 @@ const get = async (url, auth = {}) => {
 };
 // A 429 or 503 with Retry-After is the studio saying its pipeline is busy
 // (another pack in the verifier, the play-tests full), not that the pack is
-// bad: the call is made again after that wait, three times at most.
-const post = async (url, body, type = 'application/json', auth = {}, tries = 3) => {
+// bad: the call is made again after that wait, three times at most. A caller
+// that can do without the call takes a size refusal itself (tooLarge), with
+// the reason given, whatever the body.
+const post = async (url, body, type = 'application/json', auth = {}, { tries = 3, tooLarge } = {}) => {
     const r = await fetch(url, { method: 'POST', headers: { 'Content-Type': type, ...UA, ...auth }, body }).catch((e) => fail(`${url}: ${e.message} — is it running?`));
     const text = await r.text();
     let j;
-    try { j = JSON.parse(text); } catch { fail(`${url}: HTTP ${r.status} ${text.slice(0, 120)}`); }
+    try { j = JSON.parse(text); } catch { j = null; }
+    if (tooLarge && !r.ok && (r.status === 413 || /size limit/.test(j?.error || ''))) return tooLarge(j?.error || `HTTP ${r.status}`);
+    if (!j) fail(`${url}: HTTP ${r.status} ${text.slice(0, 120)}`);
     const after = Number(r.headers.get('retry-after'));
     if ((r.status === 429 || r.status === 503) && after > 0 && tries > 1) {
         console.error(`${j.error || `${url}: HTTP ${r.status}`} — trying again in ${after} s`);
         await new Promise((resolve) => setTimeout(resolve, Math.min(after, 60) * 1000));
-        return post(url, body, type, auth, tries - 1);
+        return post(url, body, type, auth, { tries: tries - 1, tooLarge });
     }
     if (!r.ok) fail(j.error || `${url}: HTTP ${r.status}`);
     return j;
@@ -186,6 +198,7 @@ async function init() {
             mode.table = rename(mode.table);
             for (const step of mode.steps || []) step.table = rename(step.table);
         }
+        for (const meter of m.meters || []) meter.table = rename(meter.table);
         writeFileSync(manifest, JSON.stringify(m, null, 2) + '\n');
     }
     console.log(`${dir}: a ${template} game as "${slug}".\nNext: edit math/ and bundle/, then hbengine verify and hbengine dev; hbengine pack makes the file to hand over (or hbengine upload with a studio key).`);
@@ -208,20 +221,48 @@ async function sandbox(rgs) {
     return { offline: true, child };
 }
 
-async function verify() {
+// The studio's pre-check refused the pack for its size (the hosted verifier
+// takes about 32 MiB of request). The maths are within Housebets' limit by
+// then (verify refuses more before sending), so that is no verdict on them,
+// and an upload verifies the whole pack in its own check: before one (upload,
+// pack) it is a warning, alone (verify) a failure that says so.
+// The most the hosted pre-check takes in one request: Cloud Run's HTTP/1
+// request limit (32 MiB), below the portal's own 64 MB (studio/rgs.go verifyMax).
+const PRECHECK_MAX = 32 * 1024 * 1024;
+const preCheckTooLarge = (beforeUpload) => (said) => {
+    const why = `the hosted pre-check could not take a maths pack this large (the studio said: ${said.replace(/\.$/, '')}). That is not a verdict on the maths`;
+    if (!beforeUpload) fail(`math not verified: ${why}. An upload verifies the whole pack in its own check: hbengine upload, or hbengine pack and upload the .tgz in the dashboard.`);
+    console.error(`warning: math not checked before the upload: ${why}: the upload's own check will verify it.`);
+    return null;
+};
+
+async function verify({ beforeUpload = false } = {}) {
     const { rgs } = project();
+    const mathDir = join(dir, 'math');
+    // Housebets' limit on a pack's maths, before a byte is sent: the upload refuses more too.
+    const held = mathBytes(mathDir);
+    if (held > MAX_MATH_BYTES) fail(mathTooLarge(held));
     const box = login() ? {} : await sandbox(rgs);
     process.on('exit', () => box.child?.kill());
-    const mathDir = join(dir, 'math');
     const files = Object.fromEntries(readdirSync(mathDir, { withFileTypes: true }).filter((e) => e.isFile()).map((e) => [e.name, readFileSync(join(mathDir, e.name), 'utf8')]));
     // With a key the studio platform asks the engine (CI has no sandbox); without, the local sandbox.
     const l = login();
-    const r = l ? await post(`${l.portal.replace(/\/$/, '')}/engine/portal/v1/verify`, JSON.stringify({ files }), 'application/json', { Authorization: 'Bearer ' + l.key })
-        : await post(`${rgs}/engine/v1/verify`, JSON.stringify({ files }));
+    const body = JSON.stringify({ files });
+    // A pack bigger than the hosted pre-check takes is not sent: the front end
+    // drops a request that size before House Studio can answer its 413, which
+    // would read as a network failure. It is left to the upload's own check.
+    if (l && Buffer.byteLength(body) > PRECHECK_MAX) {
+        if (preCheckTooLarge(beforeUpload)(`the maths are ${Math.ceil(Buffer.byteLength(body) / 1048576)} MB as JSON, and it takes ${PRECHECK_MAX / 1048576} MB at most`) === null) return;
+    }
+    const r = l ? await post(`${l.portal.replace(/\/$/, '')}/engine/portal/v1/verify`, body, 'application/json', { Authorization: 'Bearer ' + l.key }, { tooLarge: preCheckTooLarge(beforeUpload) })
+        : await post(`${rgs}/engine/v1/verify`, body);
+    if (!r) return;
     if (!r.ok) fail('math does not verify:\n  ' + r.errors.join('\n  '));
     console.log(`math ok  hash ${r.hash}`);
     const pct = (bp) => (Number(bp) / 100).toFixed(4) + '%';
-    for (const m of r.report.modes) for (const b of m.bets) console.log(`  ${m.id}/${b.id}: RTP ${pct(b.rtp)}  hit ${pct(b.hitRate)}  max ${b.maxMult}×${b.stops ? '  stops ' + b.stops.map(pct).join(' ') : ''}`);
+    for (const m of r.report.modes) for (const b of m.bets) console.log(`  ${m.id}/${b.id}: RTP ${pct(b.rtp)}${b.baseRtp ? ` (base ${pct(b.baseRtp)} + meter ${m.meter})` : ''}  hit ${pct(b.hitRate)}  max ${b.maxMult}×${b.stops ? '  stops ' + b.stops.map(pct).join(' ') : ''}`);
+    // Meters (GUIDE §2.2): what each adds to every bet of its modes, exactly.
+    for (const mt of r.report.meters || []) console.log(`  meter ${mt.id}: fill ${mt.fill}  award ${mt.awardEv}× the reference on average, up to ${mt.awardMax}×  adds ${pct(mt.rtp)}`);
     for (const w of r.report.warnings || []) console.log('  warning: ' + w);
     box.child?.kill();
 }
@@ -249,17 +290,40 @@ async function dev() {
 }
 
 async function upload() {
-    await verify();
+    await verify({ beforeUpload: true });
     lint();
     const p = project();
     const { slug, site } = p;
     const { base, auth } = games(p);
     const g = await post(base, JSON.stringify({ slug, title: p.title || slug }), 'application/json', auth);
-    const tgz = execFileSync('tar', ['-czf', '-', 'math', 'bundle'], { cwd: dir, env: TAR_ENV, maxBuffer: 200 * 1024 * 1024 });
-    let v = await post(`${base}/${slug}/uploads`, tgz, 'application/gzip', auth);
+    const tempDir = mkdtempSync(join(tmpdir(), 'hbengine-upload-'));
+    const archive = join(tempDir, 'archive.tgz');
+    let v;
+    try {
+        execFileSync('tar', ['-czf', archive, 'math', 'bundle'], { cwd: dir, env: TAR_ENV });
+        const { size } = statSync(archive);
+        const hash = createHash('sha256');
+        for await (const chunk of createReadStream(archive)) hash.update(chunk);
+        process.stdout.write('upload ');
+        try { v = await uploadArchive({
+            file: archive,
+            size,
+            sha256: hash.digest('hex'),
+            base,
+            slug,
+            auth,
+            headers: UA,
+            onProgress: () => process.stdout.write('.')
+        }); } catch (error) {
+            throw new Error(await uploadFailure(error, { base, slug, auth, headers: UA }));
+        }
+        console.log();
+    } finally {
+        rmSync(tempDir, { recursive: true, force: true });
+    }
     console.log(`version ${v.n} ${v.state}${v.hash ? '  math ' + v.hash.slice(0, 12) : ''}`);
     if (v.state === 'failed') fail(report(v));
-    console.log('the sandbox plays it now on desktop and phone (about two minutes; hbengine status shows the state meanwhile)');
+    console.log('the sandbox checks desktop and phone, then the date/endurance matrix (usually two to ten minutes; hbengine status shows progress)');
     process.stdout.write('conformance run ');
     for (let waited = 0; v.run && v.run.detail === 'running'; waited += 2) {
         if (waited > 600) fail('\nthe run is still going after ten minutes: hbengine status');
@@ -389,18 +453,10 @@ async function storeCmd() {
     const j = await r.json().catch(() => ({}));
     if (r.status === 404) fail(`${p.slug} is not on the studio platform yet: hbengine upload creates it`);
     if (!r.ok) fail(j.error || `HTTP ${r.status}`);
-    const tile = ['tile.png', 'tile.webp'].map((t) => join(dir, t)).find(existsSync);
-    let kept = ''; // why the tile stayed as it was
-    if (tile) {
-        const t = await fetch(`${base}/${p.slug}/tile`, { method: 'PUT', headers: { ...UA, ...auth }, body: readFileSync(tile) });
-        const why = t.ok ? '' : (await t.json().catch(() => ({}))).error || `HTTP ${t.status}`;
-        // 409: the game is live and its tile is the one review saw (until Housebets reset it).
-        // The page is saved; the tile staying is said, not an error, or every store of a live game fails.
-        if (t.status === 409) kept = why;
-        else if (!t.ok) fail('tile: ' + why);
-    }
-    const missing = tile ? (j.missing || []).filter((m) => m !== 'a tile') : j.missing || [];
-    console.log(`store page saved${tile && !kept ? ' with the tile' : ''}.${kept ? ' Tile unchanged: ' + kept : ''}${missing.length ? ' Before review it needs: ' + missing.join(', ') + '.' : ' Ready for review: hbengine submit.'}`);
+    // The tile is ours: Housebets makes it from the game's art when a version goes live.
+    const tile = ['tile.png', 'tile.webp'].find((t) => existsSync(join(dir, t)));
+    const missing = j.missing || [];
+    console.log(`store page saved.${missing.length ? ' Before review it needs: ' + missing.join(', ') + '.' : ' Ready for review: hbengine submit.'}${tile ? ` ${tile} was not sent: Housebets makes the tile from your game's art when a version goes live.` : ''}`);
 }
 
 async function submit() {
@@ -515,6 +571,7 @@ async function feedback() {
     console.log(`ticket #${r.id} sent to Housebets${game ? ` (about ${game})` : ''}. The answer comes by email and in hbengine tickets.\n  ${r.url}`);
 }
 
+
 async function tickets() {
     const { base, auth } = support();
     const r = await get(base, auth);
@@ -529,13 +586,26 @@ async function tickets() {
 }
 
 // The upload's conformance run, offline against engine-dev (needs Chrome
-// and playwright-core: npm install playwright-core).
+// and playwright-core: npm install playwright-core). With --time-travel, the
+// fake-clock matrix the upload plays after it too (every variant, the clock
+// jumps and the long session: several minutes), so a version that passes here
+// meets the same checks there. An engine-dev with no wallet fault stub has
+// the outage check skipped, as the hosted upload does (outage.mjs).
 async function test() {
     const { slug, rgs } = project();
     const box = await sandbox(rgs);
     if (!box.offline) fail(`${rgs} is not engine-dev: with a sandbox, hbengine upload runs these checks`);
     process.on('exit', () => box.child?.kill());
-    const r = spawnSync('node', [join(PKG, 'engine-conformance', 'run.mjs'), join(dir, 'bundle'), '--slug', slug, '--game-id', '0', '--rgs', rgs], { stdio: 'inherit' });
+    const travel = flag('time-travel') ? ['--time-travel', 'all', '--manifest', join(dir, 'math', 'manifest.json')] : [];
+    // `--clock plus7d=2026-11-05T14:00:00.000Z,Asia/Tokyo,ja`: one variant at the clock an
+    // upload's report names (the upload draws its own), replayed against the baseline.
+    const clock = opt('clock', '');
+    if (clock) {
+        const m = /^([a-z0-9]+)=([^,]+),([^,]+),([^,]+)$/.exec(clock) || fail('--clock <variant>=<instant>,<zone>,<language>, as the report line names it');
+        if (!travel.length) fail('--clock replays a time-travel variant: add --time-travel');
+        travel.push('--travel-clocks', JSON.stringify({ [m[1]]: { at: m[2], tz: m[3], locale: m[4] } }), '--variants', `base,${m[1]}`);
+    }
+    const r = spawnSync('node', [join(PKG, 'engine-conformance', 'run.mjs'), join(dir, 'bundle'), '--slug', slug, '--game-id', '0', '--rgs', rgs, ...(await outageArgs(rgs)), ...travel], { stdio: 'inherit' });
     process.exit(r.status ?? 1);
 }
 
@@ -544,13 +614,13 @@ async function test() {
 // check it. The store page travels on its own (hbengine store, or by hand).
 async function pack() {
     const p = project();
-    await verify();
+    await verify({ beforeUpload: true });
     lint();
     mkdirSync(join(dir, 'dist'), { recursive: true });
     const out = join(dir, 'dist', `${p.slug}-${new Date().toISOString().slice(0, 10)}.tgz`);
     execFileSync('tar', ['-czf', out, '-C', dir, 'math', 'bundle'], { env: TAR_ENV });
     const sum = createHash('sha256').update(readFileSync(out)).digest('hex');
-    const store = ['store.json', 'tile.png', 'tile.webp'].filter((f) => existsSync(join(dir, f)));
+    const store = ['store.json'].filter((f) => existsSync(join(dir, f)));
     console.log(`${out}\nsha256 ${sum}\nsend both; the receiver uploads the .tgz in the dashboard (the game's page, New version).` + (store.length ? `\nthe store page is not in it: send ${store.join(' and ')} too.` : ''));
 }
 
@@ -561,5 +631,5 @@ function templates() {
 const mcp = async () => (await import('../engine-mcp/server.mjs')).serve();
 const version = () => console.log(VERSION);
 const commands = { init, verify, lint, dev, test, pack, upload, status, stats, store: storeCmd, submit, live, preflight, review, reply, feedback, tickets, login: loginCmd, connect, mcp, templates, version };
-if (!commands[cmd]) fail('usage: hbengine init|verify|lint|dev|test|pack|upload|status|stats|store|submit|live|preflight|review|reply|feedback|tickets|connect|login|mcp|templates|version [dir]');
+if (!commands[cmd]) fail('usage: hbengine init|verify|lint|dev|test|pack|upload|status|stats|store|submit|live|preflight|review|reply|feedback|tickets|support|admin|connect|login|mcp|templates|version [dir]');
 await commands[cmd]();

package/engine-cli/outage.mjs

@@ -0,0 +1,9 @@
+// The upload's outage check arms engine-dev's wallet fault stub (POST /dev/fault). A kit
+// whose engine-dev has none failed every game on it, for the sandbox and not the game: an
+// engine-dev that answers 404 there gets the run's --skip-outage, and the check reads as
+// skipped, as on the hosted upload. Asked with HEAD, so asking never arms a fault; any
+// answer but a clear 404 leaves the run to arm it and judge.
+export async function outageArgs(rgs, fetch = globalThis.fetch) {
+    const status = await fetch(`${rgs}/dev/fault`, { method: 'HEAD' }).then((r) => r.status).catch(() => 0);
+    return status === 404 ? ['--skip-outage'] : [];
+}

package/engine-cli/templates.mjs

@@ -6,6 +6,7 @@ export const TEMPLATES = {
     lines: 'five reels, paylines, scatters and free spins, built by the maths kit',
     tumble: 'a 6 × 5 scatter-pays grid with tumbles, free spins with multipliers (the maths kit)',
     plinko: 'rows and risk levels, each bucket weighted by the binomial',
+    'plinko-jar': 'plinko with a jar that fills with every stake and pays a bonus when full (a meter)',
     keno: '40 numbers, 10 drawn, 1–10 picks; exact hypergeometric weights',
     crash: 'a ladder that climbs by itself: cash out before it busts, 99% at every level',
     mines: 'a 5 × 5 grid, 1–24 mines: reveal tiles, cash out; exact weights per reveal',

package/engine-cli/upload-errors.mjs

@@ -0,0 +1,18 @@
+// A failed upload is not permission to upload the same archive again: the
+// server may have accepted it before the response was lost. Read status once
+// for context, with a short deadline, and leave any retry to the studio.
+export async function uploadFailure(error, { base, slug, auth = {}, headers = {}, fetchImpl = fetch }) {
+    let checking = [];
+    try {
+        const r = await fetchImpl(`${base}/${slug}`, { headers: { ...headers, ...auth }, signal: AbortSignal.timeout(3000) });
+        if (r.ok) {
+            const game = await r.json();
+            checking = (Array.isArray(game.uploads) ? game.uploads : []).filter(v =>
+                Number.isInteger(v.n) && v.n > 0 && ['uploaded', 'verified'].includes(v.state)).map(v => v.n).slice(-10);
+        }
+    } catch { /* status is optional; retain the original failure */ }
+    const message = String(error.message || 'Upload failed').replace(/https?:\/\/[^\s?#]+[?#][^\s]*/g, '[upload URL redacted]');
+    const running = checking.length ? ` Version${checking.length > 1 ? 's' : ''} ${checking.map(n => `v${n}`).join(', ')} still have checks running.` : '';
+    const kind = error.status === 429 || error.status === 503 ? ' The service is busy; follow any retry guidance above.' : '';
+    return `${message}.${running}${kind} Run hbengine status for this project before retrying: an upload may have been accepted even if its response was lost. Do not repeatedly upload the same version.`;
+}

package/engine-cli/upload.mjs

@@ -0,0 +1,172 @@
+import { createReadStream } from 'node:fs';
+
+const RETRIES = 5;
+
+const json = async (response) => {
+    const text = await response.text();
+    let body;
+    try { body = text ? JSON.parse(text) : {}; } catch { body = {}; }
+    return { response, body };
+};
+
+const errorMessage = (url, response, body) => body.error || `${url}: HTTP ${response.status}`;
+
+const responseError = (url, response, body) => {
+    const error = new Error(errorMessage(url, response, body));
+    error.status = response.status;
+    return error;
+};
+
+const sessionExpiredError = () => {
+    const error = new Error('Upload session expired or was cancelled; run hbengine upload again.');
+    error.sessionExpired = true;
+    return error;
+};
+
+const isSessionExpired = (status) => status === 404 || status === 410;
+
+const requestJson = async (url, options = {}) => {
+    const { response, body } = await json(await fetch(url, options));
+    if (!response.ok) throw responseError(url, response, body);
+    return body;
+};
+
+const readChunk = async (file, start, end) => {
+    const parts = [];
+    for await (const part of createReadStream(file, { start, end })) parts.push(part);
+    return Buffer.concat(parts);
+};
+
+const rangeEnd = (range) => {
+    const match = /^bytes=(?:\d+)-(\d+)$/.exec(range || '');
+    return match ? Number(match[1]) : -1;
+};
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function committed(fileUrl, size) {
+    const response = await fetch(fileUrl, {
+        method: 'PUT',
+        headers: { 'Content-Length': '0', 'Content-Range': `bytes */${size}` },
+        body: ''
+    });
+    if (response.status === 200 || response.status === 201) return size;
+    if (response.status === 308) return rangeEnd(response.headers.get('range')) + 1;
+    const { body } = await json(response);
+    if (isSessionExpired(response.status)) throw sessionExpiredError();
+    throw responseError(fileUrl, response, body);
+}
+
+const retryDelay = (attempt) => Math.min(1000, 100 * 2 ** attempt);
+
+const retryableError = (error) => !error.sessionExpired && (error.status === undefined || (error.status >= 500 && error.status <= 599));
+
+const recoverOffset = async (uploadUrl, size, attempt) => {
+    let lastError;
+    while (attempt < RETRIES) {
+        await sleep(retryDelay(attempt++));
+        try {
+            return { next: await committed(uploadUrl, size), attempt };
+        } catch (error) {
+            if (!retryableError(error)) throw error;
+            lastError = error;
+        }
+    }
+    throw lastError;
+};
+
+async function putChunks(file, size, session, onProgress = () => {}) {
+    const { uploadUrl, chunkBytes } = session;
+    if (typeof uploadUrl !== 'string' || !uploadUrl || !Number.isInteger(chunkBytes) || chunkBytes <= 0) {
+        throw new Error('upload session returned an invalid uploadUrl or chunkBytes');
+    }
+    let offset = 0;
+    // 308s in a row that kept nothing: storage that takes a chunk without
+    // keeping it would otherwise be sent the same bytes forever.
+    let stalls = 0;
+    while (offset < size) {
+        const end = Math.min(offset + chunkBytes, size) - 1;
+        let attempt = 0;
+        while (true) {
+            let response;
+            try {
+                const body = await readChunk(file, offset, end);
+                response = await fetch(uploadUrl, {
+                    method: 'PUT',
+                    headers: {
+                        'Content-Length': String(body.length),
+                        'Content-Range': `bytes ${offset}-${end}/${size}`
+                    },
+                    body
+                });
+            } catch (error) {
+                if (attempt >= RETRIES) throw error;
+                const recovery = await recoverOffset(uploadUrl, size, attempt);
+                attempt = recovery.attempt;
+                const next = recovery.next;
+                if (next >= size) { offset = size; onProgress(size, size); break; }
+                if (next > end) { offset = next; onProgress(offset, size); break; }
+                offset = next;
+                continue;
+            }
+            if (response.status === 200 || response.status === 201) {
+                offset = size;
+                onProgress(offset, size);
+                break;
+            }
+            if (response.status === 308) {
+                const next = rangeEnd(response.headers.get('range')) + 1;
+                if (next > offset) stalls = 0;
+                else if (++stalls > RETRIES) throw new Error(`${uploadUrl}: storage is not keeping the upload; run hbengine upload again`);
+                offset = Math.min(next, size);
+                onProgress(offset, size);
+                break;
+            }
+            if (response.status < 500 || response.status > 599) {
+                const { body } = await json(response);
+                if (isSessionExpired(response.status)) throw sessionExpiredError();
+                throw responseError(uploadUrl, response, body);
+            }
+            await response.text().catch(() => {});
+            if (attempt >= RETRIES) throw new Error(`${uploadUrl}: HTTP ${response.status}`);
+            const recovery = await recoverOffset(uploadUrl, size, attempt);
+            attempt = recovery.attempt;
+            const next = recovery.next;
+            if (next >= size) { offset = size; onProgress(size, size); break; }
+            if (next > end) { offset = next; onProgress(offset, size); break; }
+            offset = next;
+        }
+    }
+}
+
+/** Upload an archive using the direct-storage contract, with legacy fallback. */
+export async function uploadArchive({ file, size, sha256, base, slug, auth = {}, headers = {}, onProgress }) {
+    const sessionUrl = `${base}/${slug}/upload-sessions`;
+    let session;
+    try {
+        session = await requestJson(sessionUrl, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json', ...headers, ...auth },
+            body: JSON.stringify({ size, sha256 })
+        });
+    } catch (error) {
+        if (error.status !== 404 && error.status !== 405) throw error;
+        const response = await fetch(`${base}/${slug}/uploads`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/gzip', 'Content-Length': String(size), ...headers, ...auth },
+            body: createReadStream(file),
+            duplex: 'half'
+        });
+        const result = await json(response);
+        if (!response.ok) throw new Error(errorMessage(`${base}/${slug}/uploads`, response, result.body));
+        onProgress?.(size, size);
+        return result.body;
+    }
+
+    await putChunks(file, size, session, onProgress);
+    return requestJson(`${sessionUrl}/${session.id}/complete`, {
+        method: 'POST',
+        headers: { ...headers, ...auth }
+    });
+}
+