@elaraai/e3-rack 0.0.0-stage → 1.0.95

package/dist/src/hub/infrastructure.spec.js

@@ -0,0 +1,211 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { afterEach, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { setTimeout as delay } from 'node:timers/promises';
+import { Hono } from 'hono';
+import { BooleanType, StringType, decodeBeast2For, encodeBeast2For, some, variant } from '@elaraai/east';
+import { processOwner } from '@elaraai/e3-core';
+import { decodeBody, sendError, sendSuccess } from '../server/beast2.js';
+import { acquireHubLock, HubLockType, readHubLock } from './lock.js';
+import { defaultHubConfig, listenerProblem, loadHubConfig, saveHubConfig, validateHubConfig, wildcardHost } from './config.js';
+import { FairLeaseStore } from './fair-lease-store.js';
+import { SessionLeaseCoordinator, SessionProxyStorageBridge } from './session-bridge.js';
+import { InMemoryRackLeaseStore } from '../lease/in-memory-lease-store.js';
+import { makeLeaseId } from '../lease/lease-store.js';
+import { closeSocketServer, RackHubError, REQUEST_BODY_TIMEOUT_MS, serveOnSocket, socketRequest, socketStream } from '../client/local-http.js';
+import { SessionLogsType } from '../protocol/session-data.js';
+import { HUB_CONFIG_FILE, HUB_LOCK_FILE, sessionSocketPath } from '../paths.js';
+const cleanup = [];
+afterEach(async () => { for (const close of cleanup.splice(0).reverse())
+    await close(); });
+async function home() {
+    const path = await mkdtemp(join(tmpdir(), 'e3r-'));
+    cleanup.push(() => rm(path, { recursive: true, force: true }));
+    return path;
+}
+it('persists hub configuration atomically and refuses invalid or corrupt state', async () => {
+    const path = await home();
+    assert.deepEqual(await loadHubConfig(path), defaultHubConfig());
+    const config = { ...defaultHubConfig(), listen: some({ host: '127.0.0.1', port: 7331n }) };
+    await saveHubConfig(config, path);
+    assert.deepEqual(await loadHubConfig(path), config);
+    await assert.rejects(saveHubConfig({ ...config, idleExitMinutes: -1n }, path), /timeout/);
+    assert.deepEqual(await loadHubConfig(path), config);
+    await writeFile(join(path, HUB_CONFIG_FILE), new Uint8Array([1, 2, 3]));
+    await assert.rejects(loadHubConfig(path));
+});
+it('serves plain HTTP only on the loopback or a private address it names, and TLS on any address', () => {
+    const listen = (host) => some({ host, port: 7331n });
+    const plain = (host, allow = ['127.0.0.1']) => ({ ...defaultHubConfig(), listen: listen(host), allow, tls: false });
+    assert.equal(defaultHubConfig().tls, true);
+    assert.equal(listenerProblem(defaultHubConfig()), undefined);
+    for (const host of ['127.0.0.1', '::1', 'localhost', '10.1.2.3', '172.16.0.9', '192.168.1.2', '100.64.0.10', '169.254.3.4', 'fd00::5', 'fe80::1']) {
+        assert.equal(listenerProblem(plain(host)), undefined, host);
+    }
+    assert.match(listenerProblem(plain('127.0.0.1', [])), /must name the addresses it admits/);
+    for (const host of ['0.0.0.0', '::'])
+        assert.match(listenerProblem(plain(host)), /every address/);
+    for (const host of ['8.8.8.8', '172.32.0.1', '2001:db8::1', 'hub.example.com'])
+        assert.match(listenerProblem(plain(host)), /loopback or a private address/, host);
+    for (const host of ['0.0.0.0', '8.8.8.8', 'hub.example.com'])
+        assert.equal(listenerProblem({ ...defaultHubConfig(), listen: listen(host) }), undefined, host);
+    assert.match(listenerProblem({ ...defaultHubConfig(), listen: listen('127.0.0.1'), advertiseUrl: some('http://relay.example') }), /https:\/\//);
+    assert.equal(listenerProblem({ ...plain('127.0.0.1'), advertiseUrl: some('https://terminator.example') }), undefined);
+    assert.throws(() => validateHubConfig(plain('127.0.0.1', [])), /must name the addresses/);
+    assert.throws(() => validateHubConfig({ ...defaultHubConfig(), allow: ['not-an-ip'] }), /not an IP address/);
+    assert.deepEqual(['0.0.0.0', '::', '0:0:0:0:0:0:0:0', '127.0.0.1', 'localhost'].map(wildcardHost), [true, true, true, false, false]);
+});
+it('publishes one whole hub lock and recovers a stale owner under simultaneous contenders', async () => {
+    const path = await home();
+    for (let round = 0; round < 3; round++) {
+        const acquired = await Promise.all(Array.from({ length: 12 }, () => acquireHubLock(path)));
+        const winners = acquired.filter((lock) => lock !== null);
+        assert.equal(winners.length, 1);
+        const winner = winners[0];
+        cleanup.push(() => winner.release());
+        assert.deepEqual(decodeBeast2For(HubLockType)(await readFile(join(path, HUB_LOCK_FILE))), winner.record);
+        assert.equal(await acquireHubLock(path), null);
+        await winner.release();
+        assert.equal(await readHubLock(path), null);
+        // A complete record left by a dead process: all contenders see the same stale owner.
+        await writeFile(join(path, HUB_LOCK_FILE), encodeBeast2For(HubLockType)({ ...winner.record, pid: -1n }));
+    }
+});
+it('asks after a contender\'s liveness once in a while during an election, never once per claim per poll', async () => {
+    const path = await home();
+    const self = await processOwner();
+    // Twelve contenders of distinct identities, each liveness answer costing
+    // about what a macOS answer does, which spawns sysctl and ps.
+    const contenders = Array.from({ length: 12 }, (_, n) => ({ ...self, pid: 100000n + BigInt(n) }));
+    let probes = 0;
+    const alive = async () => { probes++; await delay(15); return true; };
+    const started = Date.now();
+    const acquired = await Promise.all(contenders.map((owner) => acquireHubLock(path, { owner, alive })));
+    const elapsed = Date.now() - started;
+    const winners = acquired.filter((lock) => lock !== null);
+    assert.equal(winners.length, 1);
+    cleanup.push(() => winners[0].release());
+    assert(probes <= contenders.length * contenders.length, `${probes} liveness answers for ${contenders.length} contenders`);
+    assert(elapsed < 3000, `the election took ${elapsed} ms`);
+});
+it('elects one hub across processes and recovers its lock after an ungraceful exit', async () => {
+    const path = await home();
+    const module = new URL('./lock.js', import.meta.url).href;
+    const launch = async () => {
+        const script = `import { acquireHubLock } from ${JSON.stringify(module)};
+      const lock = await acquireHubLock(process.argv[1]);
+      console.log(lock ? 'held' : 'busy');
+      if (lock) setInterval(() => {}, 1000);`;
+        const child = spawn(process.execPath, ['--input-type=module', '-e', script, path], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+        cleanup.push(async () => {
+            if (child.exitCode === null && child.signalCode === null) {
+                const exit = once(child, 'exit');
+                child.kill('SIGKILL');
+                await exit;
+            }
+        });
+        const [bytes] = await once(child.stdout, 'data', { signal: AbortSignal.timeout(10_000) });
+        return { child, held: String(bytes).trim() === 'held' };
+    };
+    const contenders = await Promise.all([launch(), launch(), launch()]);
+    const winners = contenders.filter((c) => c.held);
+    assert.equal(winners.length, 1);
+    const winner = winners[0].child;
+    const exit = once(winner, 'exit');
+    winner.kill('SIGKILL');
+    await exit;
+    const reclaimed = await Promise.all([launch(), launch(), launch()]);
+    assert.equal(reclaimed.filter((c) => c.held).length, 1);
+});
+it('serves typed and raw data over a private socket with deadlines and cancellation', async () => {
+    const path = sessionSocketPath(await home());
+    const app = new Hono();
+    app.post('/echo', async (c) => sendSuccess(StringType, await decodeBody(c, StringType)));
+    app.get('/error', () => sendError(StringType, variant('internal', { message: 'test error' })));
+    app.get('/slow', async () => { await delay(150); return sendSuccess(StringType, 'late'); });
+    app.get('/bytes', () => new Response(new Uint8Array([1, 2, 3])));
+    const server = await serveOnSocket(app, path);
+    cleanup.push(() => closeSocketServer(server, path));
+    assert.equal(server.requestTimeout, REQUEST_BODY_TIMEOUT_MS, "a request body may take a data URL's whole lifetime to arrive");
+    if (process.platform !== 'win32')
+        assert.equal((await stat(path)).mode & 0o777, 0o600);
+    assert.equal(await socketRequest(path, 'POST', '/echo', { requestType: StringType, body: 'hello', responseType: StringType }), 'hello');
+    await assert.rejects(socketRequest(path, 'GET', '/error', { responseType: StringType }), /test error/);
+    await assert.rejects(socketRequest(path, 'GET', '/slow', { responseType: StringType, timeoutMs: 20 }), (err) => err instanceof RackHubError && err.code === 'timeout');
+    const abort = new AbortController();
+    const pending = socketRequest(path, 'GET', '/slow', { responseType: StringType, signal: abort.signal });
+    abort.abort();
+    await assert.rejects(pending, (err) => err instanceof RackHubError && err.code === 'aborted');
+    const response = await socketStream(path, 'GET', '/bytes');
+    const chunks = [];
+    for await (const chunk of response)
+        chunks.push(Buffer.from(chunk));
+    assert.deepEqual(Buffer.concat(chunks), Buffer.from([1, 2, 3]));
+});
+it('drops a log batch whose flush the session refused, so the rack\'s re-post is written once', async () => {
+    const path = sessionSocketPath(await home());
+    const app = new Hono();
+    const batches = [];
+    let refusals = 1;
+    app.post('/v1/logs', async (c) => {
+        const request = await decodeBody(c, SessionLogsType);
+        if (refusals-- > 0)
+            return c.text('session busy', 503);
+        batches.push(request.chunks.map((chunk) => chunk.data));
+        return sendSuccess(BooleanType, true);
+    });
+    const server = await serveOnSocket(app, path);
+    cleanup.push(() => closeSocketServer(server, path));
+    const leases = new InMemoryRackLeaseStore();
+    const taskHash = 'a'.repeat(64);
+    const inputsHash = 'b'.repeat(64);
+    await leases.put({
+        leaseId: makeLeaseId(taskHash, inputsHash), repo: 'repo', workspace: 'dev', taskHash, inputsHash, tier: 'node', status: 'claimed',
+        claimedBy: 'rack', createdAtMs: 0, attempt: { executionId: 'run', startedAtMs: 0 },
+        event: { version: 2, workspace: 'dev', taskName: 'task', closure: { hashes: [] }, runnerEvent: { mode: 'task', repo: 'repo', launchId: 'launch', taskHash, inputHashes: [], timeoutMs: 1000 } },
+    });
+    const coordinator = new SessionLeaseCoordinator();
+    const bridge = new SessionProxyStorageBridge({ leases, coordinator, session: () => ({ dataSocket: path, dataToken: 'token' }), owner: await processOwner(), advertiseOrigin: () => undefined });
+    const post = (line) => coordinator.run('repo', 'lease', async () => {
+        await bridge.attempts.logs.append('repo', taskHash, inputsHash, 'run', 'stdout', line);
+        await bridge.attempts.logs.flush('repo', taskHash, inputsHash, 'run');
+    });
+    await assert.rejects(post('first\n'), /session busy/);
+    await post('first\n'); // the rack, told its lines were not stored, posts them again
+    await post('second\n');
+    assert.deepEqual(batches, [['first\n'], ['second\n']]);
+});
+it('rotates claims across owners even when one session fills the oldest queue positions', async () => {
+    const backend = new InMemoryRackLeaseStore();
+    const store = new FairLeaseStore(backend, (lease) => lease.workspace);
+    const taskHash = 'a'.repeat(64);
+    const inputsHash = 'b'.repeat(64);
+    for (const workspace of ['first', 'second'])
+        for (let n = 0; n < 6; n++) {
+            const lease = {
+                leaseId: makeLeaseId(taskHash, inputsHash), repo: 'repo', workspace, taskHash, inputsHash,
+                tier: 'node', status: 'pending', createdAtMs: workspace === 'first' ? n : n + 10,
+                event: { version: 2, workspace, taskName: 'task', closure: { hashes: [] }, runnerEvent: {
+                        mode: 'task', repo: 'repo', launchId: 'launch', taskHash, inputHashes: [], timeoutMs: 1000,
+                    } },
+            };
+            await store.put(lease);
+        }
+    const owners = [];
+    for (let n = 0; n < 12; n++) {
+        const [lease] = await store.listClaimable(['node'], Date.now(), 1);
+        assert(lease);
+        assert(await store.claim('repo', lease.leaseId, 'rack', Date.now() + 60_000));
+        owners.push(lease.workspace);
+    }
+    assert.deepEqual(owners, Array.from({ length: 12 }, (_, n) => n % 2 ? 'second' : 'first'));
+});
+//# sourceMappingURL=infrastructure.spec.js.map

package/dist/src/hub/infrastructure.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"infrastructure.spec.js","sourceRoot":"","sources":["../../../src/hub/infrastructure.spec.ts"],"names":[],"mappings":"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"}

package/dist/src/hub/lock.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { DateTimeType, IntegerType, StringType, StructType, type ValueTypeOf } from '@elaraai/east';
+import { type ExecutionOwner } from '@elaraai/e3-types';
+/** Records the one hub's process identity and the control protocol it serves. */
+export declare const HubLockType: StructType<{
+    readonly ownerId: StringType;
+    readonly pid: IntegerType;
+    readonly pidStartTime: IntegerType;
+    readonly bootId: StringType;
+    readonly version: StringType;
+    readonly protocol: IntegerType;
+    readonly controlSocket: StringType;
+    readonly startedAt: DateTimeType;
+}>;
+/** The process holding this user's hub. */
+export type HubLock = ValueTypeOf<typeof HubLockType>;
+/** Test seams of {@link acquireHubLock}: a contender's identity and its liveness probe. */
+export interface AcquireHubLockOptions {
+    /** The contender's process identity; this process's unless given, as a test racing contenders of distinct identities gives it. */
+    owner?: ExecutionOwner;
+    /** Whether a claimant's process is alive; e3-core's process liveness unless given. */
+    alive?: (claimant: ExecutionOwner) => Promise<boolean>;
+}
+/** A held hub lock; its release removes only files belonging to this holder. */
+export interface HeldHubLock {
+    /** Process identity used by sessions for execution ownership. */
+    readonly record: HubLock;
+    /** Releases ownership once the listeners have closed. */
+    release(): Promise<void>;
+}
+/**
+ * Reads the hub's ownership record, without deleting an in-progress publication.
+ * @param home - Private rack home
+ * @returns The complete lock, or null if absent
+ * @throws {Error} When a present lock is corrupt
+ */
+export declare function readHubLock(home?: string): Promise<HubLock | null>;
+/**
+ * Claims the single hub, including concurrent recovery of a crashed holder.
+ *
+ * @remarks
+ * A shared lock name cannot safely be unlinked after an asynchronous liveness
+ * check: another contender may already have replaced it. A bakery election
+ * uses unique, atomically published claim files instead. Each contender first
+ * announces that it is choosing (ticket zero), then publishes max(ticket)+1.
+ * A live lower (ticket, UUID) wins. Only dead, uniquely named claims are
+ * reclaimed, so no recovery deletes a new holder's lock. `hub.lock` is
+ * published whole once the election is won, and is never observed empty.
+ *
+ * @param home - Private rack home
+ * @param options - Test seams: the contender's identity and its liveness probe
+ * @returns Ownership, or null when another live contender/holder wins
+ * @throws {Error} When a claim cannot be read or startup exceeds ten seconds
+ * @example
+ * const lock = await acquireHubLock();
+ * if (lock !== null) await lock.release();
+ */
+export declare function acquireHubLock(home?: string, options?: AcquireHubLockOptions): Promise<HeldHubLock | null>;
+//# sourceMappingURL=lock.d.ts.map

package/dist/src/hub/lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.d.ts","sourceRoot":"","sources":["../../../src/hub/lock.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,UAAU,EAAE,UAAU,EAAoE,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AACtK,OAAO,EAAsB,KAAK,cAAc,EAAE,MAAM,mBAAmB,CAAC;AAK5E,iFAAiF;AACjF,eAAO,MAAM,WAAW;;;;;;;;;EAGtB,CAAC;AACH,2CAA2C;AAC3C,MAAM,MAAM,OAAO,GAAG,WAAW,CAAC,OAAO,WAAW,CAAC,CAAC;AAmBtD,2FAA2F;AAC3F,MAAM,WAAW,qBAAqB;IACpC,kIAAkI;IAClI,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,sFAAsF;IACtF,KAAK,CAAC,EAAE,CAAC,QAAQ,EAAE,cAAc,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxD;AAED,gFAAgF;AAChF,MAAM,WAAW,WAAW;IAC1B,iEAAiE;IACjE,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,yDAAyD;IACzD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAMD;;;;;GAKG;AACH,wBAAsB,WAAW,CAAC,IAAI,SAAa,GAAG,OAAO,CAAC,OAAO,GAAG,IAAI,CAAC,CAK5E;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,cAAc,CAAC,IAAI,SAAa,EAAE,OAAO,GAAE,qBAA0B,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAsExH"}

package/dist/src/hub/lock.js

@@ -0,0 +1,165 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { randomUUID } from 'node:crypto';
+import { readdir, readFile, unlink } from 'node:fs/promises';
+import { join } from 'node:path';
+import { setTimeout as delay } from 'node:timers/promises';
+import { DateTimeType, IntegerType, StringType, StructType, compareFor, decodeBeast2For, encodeBeast2For, equalFor, printFor } from '@elaraai/east';
+import { ExecutionOwnerType } from '@elaraai/e3-types';
+import { atomicWriteFile, isProcessAlive, processOwner } from '@elaraai/e3-core';
+import { ensureRackHome, HUB_LOCK_FILE, hubSocketPath, rackHome } from '../paths.js';
+import { E3_RACK_VERSION, HUB_PROTOCOL } from '../version.js';
+/** Records the one hub's process identity and the control protocol it serves. */
+export const HubLockType = StructType({
+    ownerId: StringType, pid: IntegerType, pidStartTime: IntegerType, bootId: StringType,
+    version: StringType, protocol: IntegerType, controlSocket: StringType, startedAt: DateTimeType,
+});
+const ClaimType = StructType({ owner: HubLockType, ticket: IntegerType });
+const encodeClaim = encodeBeast2For(ClaimType);
+const decodeClaim = decodeBeast2For(ClaimType);
+const encodeLock = encodeBeast2For(HubLockType);
+const decodeLock = decodeBeast2For(HubLockType);
+const compareTicket = compareFor(IntegerType);
+const compareOwner = compareFor(StringType);
+const sameProcess = equalFor(ExecutionOwnerType);
+const printProcess = printFor(ExecutionOwnerType);
+const PREFIX = '.hub-claim-';
+/**
+ * How long one election trusts an answer about a claimant's liveness. On
+ * macOS each answer spawns `sysctl` and `ps`, and every contender reads every
+ * claim on every 20 ms poll: a dozen contenders asking afresh each time outran
+ * the election's own deadline there.
+ */
+const LIVENESS_TTL_MS = 1000;
+async function remove(file) {
+    await unlink(file).catch((err) => { if (err.code !== 'ENOENT')
+        throw err; });
+}
+/**
+ * Reads the hub's ownership record, without deleting an in-progress publication.
+ * @param home - Private rack home
+ * @returns The complete lock, or null if absent
+ * @throws {Error} When a present lock is corrupt
+ */
+export async function readHubLock(home = rackHome()) {
+    try {
+        return decodeLock(await readFile(join(home, HUB_LOCK_FILE)));
+    }
+    catch (err) {
+        if (err.code === 'ENOENT')
+            return null;
+        throw err;
+    }
+}
+/**
+ * Claims the single hub, including concurrent recovery of a crashed holder.
+ *
+ * @remarks
+ * A shared lock name cannot safely be unlinked after an asynchronous liveness
+ * check: another contender may already have replaced it. A bakery election
+ * uses unique, atomically published claim files instead. Each contender first
+ * announces that it is choosing (ticket zero), then publishes max(ticket)+1.
+ * A live lower (ticket, UUID) wins. Only dead, uniquely named claims are
+ * reclaimed, so no recovery deletes a new holder's lock. `hub.lock` is
+ * published whole once the election is won, and is never observed empty.
+ *
+ * @param home - Private rack home
+ * @param options - Test seams: the contender's identity and its liveness probe
+ * @returns Ownership, or null when another live contender/holder wins
+ * @throws {Error} When a claim cannot be read or startup exceeds ten seconds
+ * @example
+ * const lock = await acquireHubLock();
+ * if (lock !== null) await lock.release();
+ */
+export async function acquireHubLock(home = rackHome(), options = {}) {
+    ensureRackHome(home);
+    const owner = options.owner ?? await processOwner();
+    const probe = options.alive ?? ((claimant) => isProcessAlive(Number(claimant.pid), Number(claimant.pidStartTime), claimant.bootId));
+    // A claim of this process needs no asking; another claimant's answer holds
+    // for LIVENESS_TTL_MS, so an election asks after each once in a while, not
+    // once per claim per poll.
+    const answered = new Map();
+    const alive = async (lock) => {
+        const claimant = { pid: lock.pid, pidStartTime: lock.pidStartTime, bootId: lock.bootId };
+        if (sameProcess(claimant, owner))
+            return true;
+        const key = printProcess(claimant);
+        const known = answered.get(key);
+        if (known !== undefined && Date.now() - known.at < LIVENESS_TTL_MS)
+            return known.alive;
+        const result = await probe(claimant);
+        answered.set(key, { at: Date.now(), alive: result });
+        return result;
+    };
+    const existing = await readHubLock(home);
+    if (existing !== null && await alive(existing))
+        return null;
+    const record = {
+        ...owner, ownerId: randomUUID(), version: E3_RACK_VERSION, protocol: BigInt(HUB_PROTOCOL),
+        controlSocket: hubSocketPath(home), startedAt: new Date(),
+    };
+    const file = join(home, `${PREFIX}${record.ownerId}.beast2`);
+    const deadline = Date.now() + 10_000;
+    let held = false;
+    const claims = async () => {
+        const result = [];
+        for (const name of await readdir(home)) {
+            if (!name.startsWith(PREFIX) || !name.endsWith('.beast2'))
+                continue;
+            const path = join(home, name);
+            let claim;
+            try {
+                claim = decodeClaim(await readFile(path));
+            }
+            catch (err) {
+                if (err.code === 'ENOENT')
+                    continue;
+                throw err; // Whole atomic publications: corrupt is never evidence of death.
+            }
+            if (await alive(claim.owner))
+                result.push(claim);
+            else
+                await remove(path);
+        }
+        return result;
+    };
+    try {
+        await atomicWriteFile(file, encodeClaim({ owner: record, ticket: 0n }));
+        let ticket = 1n;
+        for (const claim of await claims())
+            if (compareTicket(claim.ticket, ticket) >= 0)
+                ticket = claim.ticket + 1n;
+        await atomicWriteFile(file, encodeClaim({ owner: record, ticket }));
+        for (;;) {
+            const others = (await claims()).filter((claim) => compareOwner(claim.owner.ownerId, record.ownerId) !== 0);
+            if (others.some((claim) => compareTicket(claim.ticket, 0n) === 0)) {
+                if (Date.now() >= deadline)
+                    throw new Error('Rack hub startup is waiting for another live contender');
+                await delay(20);
+                continue;
+            }
+            if (others.some((claim) => compareTicket(claim.ticket, ticket) < 0 ||
+                (compareTicket(claim.ticket, ticket) === 0 && compareOwner(claim.owner.ownerId, record.ownerId) < 0)))
+                return null;
+            await atomicWriteFile(join(home, HUB_LOCK_FILE), encodeLock(record));
+            held = true;
+            let released = false;
+            return { record, async release() {
+                    if (released)
+                        return;
+                    released = true;
+                    const current = await readHubLock(home);
+                    if (current !== null && compareOwner(current.ownerId, record.ownerId) === 0)
+                        await remove(join(home, HUB_LOCK_FILE));
+                    await remove(file);
+                } };
+        }
+    }
+    finally {
+        if (!held)
+            await remove(file);
+    }
+}
+//# sourceMappingURL=lock.js.map

package/dist/src/hub/lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock.js","sourceRoot":"","sources":["../../../src/hub/lock.ts"],"names":[],"mappings":"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"}

package/dist/src/hub/main.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Runs the shared hub until it is stopped, drained or idle.
+ * Background callers redirect stdout/stderr to the private hub log; a
+ * foreground invocation prints the same timestamped diagnostics directly.
+ * @param argv - --foreground or --background, and optional --idle-exit minutes
+ * @returns Once the owned listeners and lock are released
+ * @throws {Error} When arguments, state or startup are invalid
+ * @example
+ * await runHub(['--foreground']);
+ */
+export declare function runHub(argv: string[]): Promise<void>;
+//# sourceMappingURL=main.d.ts.map

package/dist/src/hub/main.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.d.ts","sourceRoot":"","sources":["../../../src/hub/main.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH;;;;;;;;;GASG;AACH,wBAAsB,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAqB1D"}

package/dist/src/hub/main.js

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { pathToFileURL } from 'node:url';
+import { RackHub } from './hub.js';
+/**
+ * Runs the shared hub until it is stopped, drained or idle.
+ * Background callers redirect stdout/stderr to the private hub log; a
+ * foreground invocation prints the same timestamped diagnostics directly.
+ * @param argv - --foreground or --background, and optional --idle-exit minutes
+ * @returns Once the owned listeners and lock are released
+ * @throws {Error} When arguments, state or startup are invalid
+ * @example
+ * await runHub(['--foreground']);
+ */
+export async function runHub(argv) {
+    let foreground = true;
+    let idleExitMinutes;
+    for (let index = 0; index < argv.length; index++) {
+        switch (argv[index]) {
+            case '--foreground':
+                foreground = true;
+                break;
+            case '--background':
+                foreground = false;
+                break;
+            case '--idle-exit': {
+                idleExitMinutes = Number(argv[++index]);
+                if (!Number.isFinite(idleExitMinutes) || idleExitMinutes < 0 || idleExitMinutes > 35000)
+                    throw new Error('--idle-exit requires 0–35000 minutes');
+                break;
+            }
+            default: throw new Error(`Unknown rack hub option: ${argv[index]}`);
+        }
+    }
+    if (!foreground)
+        process.title = 'e3-rack-hub';
+    const log = (line) => { process.stdout.write(`${new Date().toISOString()} ${line}\n`); };
+    const hub = new RackHub({ foreground, idleExitMinutes, log });
+    const stop = () => { void hub.stop().catch((err) => { console.error(err); process.exitCode = 1; }); };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+    try {
+        if (await hub.start())
+            await hub.closed;
+    }
+    finally {
+        process.off('SIGINT', stop);
+        process.off('SIGTERM', stop);
+    }
+}
+if (process.argv[1] !== undefined && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    void runHub(process.argv.slice(2)).catch((err) => { console.error(err); process.exitCode = 1; });
+}
+//# sourceMappingURL=main.js.map

package/dist/src/hub/main.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../../../src/hub/main.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AACzC,OAAO,EAAE,OAAO,EAAE,MAAM,UAAU,CAAC;AAEnC;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,MAAM,CAAC,IAAc;IACzC,IAAI,UAAU,GAAG,IAAI,CAAC;IACtB,IAAI,eAAmC,CAAC;IACxC,KAAK,IAAI,KAAK,GAAG,CAAC,EAAE,KAAK,GAAG,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,EAAE,CAAC;QACjD,QAAQ,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YACpB,KAAK,cAAc;gBAAE,UAAU,GAAG,IAAI,CAAC;gBAAC,MAAM;YAC9C,KAAK,cAAc;gBAAE,UAAU,GAAG,KAAK,CAAC;gBAAC,MAAM;YAC/C,KAAK,aAAa,CAAC,CAAC,CAAC;gBACnB,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,EAAE,KAAK,CAAC,CAAC,CAAC;gBACxC,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,eAAe,CAAC,IAAI,eAAe,GAAG,CAAC,IAAI,eAAe,GAAG,KAAK;oBAAE,MAAM,IAAI,KAAK,CAAC,sCAAsC,CAAC,CAAC;gBACjJ,MAAM;YACR,CAAC;YACD,OAAO,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,4BAA4B,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;IACD,IAAI,CAAC,UAAU;QAAE,OAAO,CAAC,KAAK,GAAG,aAAa,CAAC;IAC/C,MAAM,GAAG,GAAG,CAAC,IAAY,EAAE,EAAE,GAAG,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,IAAI,IAAI,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC;IACjG,MAAM,GAAG,GAAG,IAAI,OAAO,CAAC,EAAE,UAAU,EAAE,eAAe,EAAE,GAAG,EAAE,CAAC,CAAC;IAC9D,MAAM,IAAI,GAAG,GAAG,EAAE,GAAG,KAAK,GAAG,CAAC,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/G,OAAO,CAAC,IAAI,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAAC,OAAO,CAAC,IAAI,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAC5D,IAAI,CAAC;QAAC,IAAI,MAAM,GAAG,CAAC,KAAK,EAAE;YAAE,MAAM,GAAG,CAAC,MAAM,CAAC;IAAC,CAAC;YAAS,CAAC;QAAC,OAAO,CAAC,GAAG,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;QAAC,OAAO,CAAC,GAAG,CAAC,SAAS,EAAE,IAAI,CAAC,CAAC;IAAC,CAAC;AACzH,CAAC;AAED,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,SAAS,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,aAAa,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;IAC7F,KAAK,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,GAAY,EAAE,EAAE,GAAG,OAAO,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AAC5G,CAAC"}