@elaraai/e3-rack 0.0.0-bootstrap.0 → 1.0.94

package/dist/src/client/session-data-server.spec.js

@@ -0,0 +1,192 @@
+/**
+ * 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 { createHash, randomUUID } from 'node:crypto';
+import { mkdtemp, readdir, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { PassThrough, Readable } from 'node:stream';
+import { setTimeout as delay } from 'node:timers/promises';
+import { BooleanType, IntegerType, StringType, encodeBeast2For, variant } from '@elaraai/east';
+import { LocalStorage, inputsHash, processOwner, repoInit, uuidv7 } from '@elaraai/e3-core';
+import { startSessionDataServer } from './session-data-server.js';
+import { RackHubError, socketRequest, socketStream } from './local-http.js';
+import { LeaseOutcomeType, LeaseRunningType, SessionLogsType, SessionUploadType, VerifyOutputType } from '../protocol/session-data.js';
+import { makeLeaseId } from '../lease/lease-store.js';
+const cleanup = [];
+afterEach(async () => { for (const close of cleanup.splice(0).reverse())
+    await close(); });
+async function setup() {
+    const home = await mkdtemp(join(tmpdir(), 'e3d-'));
+    cleanup.push(() => rm(home, { recursive: true, force: true }));
+    const repo = join(home, 'repo');
+    assert.equal(repoInit(repo).success, true);
+    const storage = new LocalStorage();
+    const logs = [];
+    const options = { storage, repoPath: repo, home, dataToken: randomUUID(), onLog: (_id, _stream, data) => { logs.push(data); } };
+    const data = await startSessionDataServer(options);
+    cleanup.push(() => data.close());
+    return { home, repo, storage, options, logs, data, auth: { bearer: options.dataToken } };
+}
+const digest = (bytes) => createHash('sha256').update(bytes).digest('hex');
+function uploadUrl(id, info) {
+    return `/v1/uploads/${id}?${new URLSearchParams({ lease: info.leaseId, hash: info.hash, size: `${info.size}`, receipt: info.receipt })}`;
+}
+it('rejects an already-cancelled streamed upload without crashing the process', async () => {
+    const { data, auth } = await setup();
+    const bytes = Buffer.from('cancelled upload');
+    const body = Readable.from([bytes]);
+    const info = { leaseId: 'lease', hash: digest(bytes), size: BigInt(bytes.length), receipt: randomUUID() };
+    await assert.rejects(socketStream(data.socketPath, 'PUT', uploadUrl(randomUUID(), info), {
+        ...auth, rawBody: body, signal: AbortSignal.abort(),
+    }), { code: 'aborted' });
+    await delay(0); // Allow asynchronous stream errors to reach the test runner.
+    assert.equal(body.destroyed, true);
+    const response = await socketStream(data.socketPath, 'HEAD', `/v1/objects/${info.hash}`, auth);
+    response.resume();
+    assert.equal(response.statusCode, 404);
+});
+it('streams large objects, verifies bytes before adoption and preserves an adopted inode on retries', async () => {
+    const { data, auth, repo, storage } = await setup();
+    const bytes = Buffer.alloc(9 * 1024 * 1024, 42);
+    const hash = digest(bytes);
+    const id = randomUUID();
+    const info = { leaseId: 'lease', hash, size: BigInt(bytes.length), receipt: randomUUID() };
+    const upload = async (body, path = uploadUrl(id, info)) => {
+        const response = await socketStream(data.socketPath, 'PUT', path, { ...auth, rawBody: Readable.from((function* () {
+                for (let at = 0; at < body.length; at += 65536)
+                    yield body.subarray(at, at + 65536);
+            })()) });
+        response.resume();
+        return response;
+    };
+    const denied = await socketStream(data.socketPath, 'HEAD', `/v1/objects/${hash}`);
+    denied.resume();
+    assert.equal(denied.statusCode, 401);
+    const wrong = Buffer.from(bytes);
+    wrong[0] = 1;
+    assert.equal((await upload(wrong)).statusCode, 400);
+    const commit = (declaration = info) => socketRequest(data.socketPath, 'POST', `/v1/uploads/${id}/commit`, {
+        ...auth, requestType: SessionUploadType, body: declaration, responseType: BooleanType,
+    });
+    assert.equal(await commit(), false);
+    assert.equal(await storage.objects.exists(repo, hash), false);
+    const accepted = await upload(bytes);
+    assert.equal(accepted.statusCode, 200);
+    assert.equal(accepted.headers['x-amz-version-id'], info.receipt);
+    assert.equal(await commit({ ...info, receipt: randomUUID() }), false);
+    assert.equal(await commit({ ...info, leaseId: 'another' }), false);
+    assert.equal(await commit({ ...info, size: info.size + 1n }), false);
+    assert.equal(await commit(), true);
+    assert.equal(await commit(), true);
+    // A retry with a lost acknowledgment must not reopen the committed inode.
+    assert.equal((await upload(wrong)).statusCode, 200);
+    assert.equal(digest(await storage.objects.read(repo, hash)), hash);
+    const response = await socketStream(data.socketPath, 'GET', `/v1/objects/${hash}`, auth);
+    assert.equal(Number(response.headers['content-length']), bytes.length);
+    const received = createHash('sha256');
+    let size = 0;
+    for await (const chunk of response) {
+        received.update(chunk);
+        size += chunk.length;
+    }
+    assert.equal(size, bytes.length);
+    assert.equal(received.digest('hex'), hash);
+    assert.equal(await socketRequest(data.socketPath, 'DELETE', `/v1/uploads/${id}`, { ...auth, responseType: BooleanType }), true);
+    assert.equal(await storage.objects.exists(repo, hash), true);
+});
+it('recovers an acknowledged upload in a successor session and refuses inline and size overflows', async () => {
+    const { data, auth, options, storage, repo } = await setup();
+    const bytes = encodeBeast2For(IntegerType)(42n);
+    const id = randomUUID();
+    const info = { leaseId: 'lease', hash: digest(bytes), size: BigInt(bytes.length), receipt: randomUUID() };
+    const response = await socketStream(data.socketPath, 'PUT', uploadUrl(id, info), { ...auth, rawBody: bytes });
+    response.resume();
+    assert.equal(response.statusCode, 200);
+    await data.close();
+    const successor = await startSessionDataServer(options);
+    cleanup.push(() => successor.close());
+    assert.equal(await socketRequest(successor.socketPath, 'POST', `/v1/uploads/${id}/commit`, {
+        ...auth, requestType: SessionUploadType, body: info, responseType: BooleanType,
+    }), true);
+    assert.equal(await storage.objects.exists(repo, info.hash), true);
+    await assert.rejects(socketRequest(successor.socketPath, 'POST', '/v1/objects', {
+        ...auth, rawBody: new Uint8Array(4097), responseType: StringType,
+    }), (error) => error instanceof RackHubError && error.code === 'http_413' && /exceeds 4096 bytes/.test(error.message));
+    const bad = await socketStream(successor.socketPath, 'PUT', uploadUrl(randomUUID(), { ...info, size: 1n << 100n }), { ...auth, rawBody: new Uint8Array() });
+    bad.resume();
+    assert.equal(bad.statusCode, 400);
+    const oversized = await socketStream(successor.socketPath, 'PUT', uploadUrl(randomUUID(), { ...info, size: 1n }), { ...auth, rawBody: bytes });
+    oversized.resume();
+    assert.equal(oversized.statusCode, 400);
+});
+it('writes a claim-time attempt and flushes ordered logs before recording a verified outcome', async () => {
+    const { data, auth, storage, repo, logs } = await setup();
+    const taskHash = 'a'.repeat(64);
+    const outputHash = await storage.objects.write(repo, encodeBeast2For(IntegerType)(42n));
+    const executionId = uuidv7();
+    const lease = {
+        leaseId: makeLeaseId(taskHash, inputsHash([])), repo: 'opaque-alias', workspace: 'dev', taskHash, inputsHash: inputsHash([]),
+        tier: 'node', status: 'claimed', createdAtMs: Date.now(), attempt: { executionId, startedAtMs: Date.now() },
+        event: { version: 2, workspace: 'dev', taskName: 'task', closure: { hashes: [] }, runnerEvent: {
+                mode: 'task', repo: 'opaque-alias', taskHash, launchId: 'launch', inputHashes: [], timeoutMs: 1000,
+            } },
+    };
+    await socketRequest(data.socketPath, 'POST', '/v1/attempts/running', {
+        ...auth, requestType: LeaseRunningType, body: { leaseJson: JSON.stringify(lease), owner: await processOwner() }, responseType: BooleanType,
+    });
+    assert.equal((await storage.refs.executionGet(repo, taskHash, lease.inputsHash, executionId))?.type, 'running');
+    await socketRequest(data.socketPath, 'POST', '/v1/logs', { ...auth, requestType: SessionLogsType, responseType: BooleanType, body: {
+            taskHash, inputsHash: lease.inputsHash, executionId, chunks: [{ stream: variant('stdout', null), data: 'one\n' }, { stream: variant('stdout', null), data: 'two\n' }],
+        } });
+    assert.deepEqual(logs, ['one\n', 'two\n']);
+    assert.equal(await socketRequest(data.socketPath, 'POST', '/v1/verify', {
+        ...auth, requestType: VerifyOutputType, body: { hash: 'b'.repeat(64) }, responseType: BooleanType,
+    }), false);
+    await socketRequest(data.socketPath, 'POST', '/v1/attempts/outcome', { ...auth, requestType: LeaseOutcomeType, responseType: BooleanType,
+        body: { leaseJson: JSON.stringify(lease), resultJson: JSON.stringify({ taskName: 'task', status: 'success', outputHash }) },
+    });
+    assert.equal((await storage.refs.executionGet(repo, taskHash, lease.inputsHash, executionId))?.type, 'success');
+    assert.equal((await storage.logs.read(repo, taskHash, lease.inputsHash, executionId, 'stdout')).data, 'one\ntwo\n');
+});
+it('keeps a successor upload when a predecessor PUT fails after takeover', async () => {
+    const { data, auth, options, storage, repo } = await setup();
+    const bytes = Buffer.alloc(1024, 42);
+    const id = randomUUID();
+    const info = { leaseId: 'lease', hash: digest(bytes), size: BigInt(bytes.length), receipt: randomUUID() };
+    const stream = new PassThrough();
+    cleanup.push(async () => { stream.destroy(); });
+    const predecessor = socketStream(data.socketPath, 'PUT', uploadUrl(id, info), { ...auth, rawBody: stream });
+    stream.write(bytes.subarray(0, 512));
+    // Wait until the first listener has opened its real staging file. Keep
+    // that PUT in progress while another session takes the same upload over.
+    const staging = join(repo, 'tmp', 'transfers');
+    const deadline = Date.now() + 5000;
+    for (;;) {
+        const files = await readdir(staging).catch((error) => { if (error.code === 'ENOENT')
+            return []; throw error; });
+        if (files.some((name) => name.startsWith('rack-')))
+            break;
+        assert(Date.now() < deadline, 'predecessor never opened its staging file');
+        await delay(10);
+    }
+    const successor = await startSessionDataServer(options);
+    cleanup.push(() => successor.close());
+    const response = await socketStream(successor.socketPath, 'PUT', uploadUrl(id, info), { ...auth, rawBody: bytes });
+    response.resume();
+    assert.equal(response.statusCode, 200);
+    // Its checksum failure must clean only its own file, not the successor's.
+    stream.end(Buffer.alloc(512, 43));
+    const failed = await predecessor;
+    failed.resume();
+    assert.equal(failed.statusCode, 400);
+    await data.close();
+    assert.equal(await socketRequest(successor.socketPath, 'POST', `/v1/uploads/${id}/commit`, {
+        ...auth, requestType: SessionUploadType, body: info, responseType: BooleanType,
+    }), true);
+    assert.deepEqual(new Uint8Array(await storage.objects.read(repo, info.hash)), new Uint8Array(bytes));
+});
+//# sourceMappingURL=session-data-server.spec.js.map

package/dist/src/client/session-data-server.spec.js.map

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

package/dist/src/client/session.d.ts

@@ -0,0 +1,119 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { type ValueTypeOf } from '@elaraai/east';
+import { type StorageBackend } from '@elaraai/e3-core';
+import { HubAttemptType, type CapacitySnapshot, type CreateLease } from '../protocol/control.js';
+import type { RackLeaseResult } from '../protocol/task-envelope.js';
+import type { HubClient } from './hub-client.js';
+/** Names the claim-time attempt; absent until an agent claims the lease. */
+export type LeaseAttempt = ValueTypeOf<typeof HubAttemptType>;
+/** Reports one lease transition after its repository effects have completed. */
+export type LeaseUpdate = {
+    kind: 'claimed';
+    rackId: string;
+    rackLabel: string;
+    attempt: LeaseAttempt;
+} | {
+    kind: 'completed';
+    result: RackLeaseResult;
+    attempt: LeaseAttempt | null;
+    at: Date;
+} | {
+    kind: 'lost';
+    reason: string;
+} | {
+    kind: 'cancelled';
+};
+/** A task/unit lease requested through the current control protocol. */
+export type LeaseRequest = CreateLease;
+/** One subscriber's ordered view of shared work. */
+export interface LeaseHandle {
+    /** Queue identity shared by all subscribers of identical work. */
+    readonly leaseId: string;
+    /** Whether the hub attached this request to work already queued. */
+    readonly attached: boolean;
+    /** Latest claim-time identity, including a fresh identity after reclaim. */
+    readonly attempt: LeaseAttempt | null;
+    /** Resolves with the next transition; terminal updates remain repeatable. */
+    next(): Promise<LeaseUpdate>;
+    /** Leaves this subscription; other subscribers continue to own shared work. */
+    cancel(): Promise<void>;
+}
+/** Configures one run's attachment and repository data endpoint. */
+export interface RackSessionOptions {
+    /** Backend belonging to the run's e3 release. */
+    storage: StorageBackend;
+    /** Repository path; canonicalized before registration. */
+    repoPath: string;
+    /** Workspace shown in rack status. */
+    workspace: string;
+    /** Description shown in rack status, usually the command and PID. */
+    label: string;
+    /** The run's exact e3 release, defaulting to the package release. */
+    e3Version?: string;
+}
+/**
+ * Keeps a run attached to the hub and serves its repository through a private
+ * socket. A lost hub ends every pending wait; this session never reconnects
+ * to a replacement whose in-memory leases cannot be the old ones.
+ * @example
+ * const session = await RackSession.open(client, { storage, repoPath, workspace: 'dev', label: 'run dev' });
+ * try { const lease = await session.createLease(request); await lease.next(); }
+ * finally { await session.close(); }
+ */
+export declare class RackSession {
+    private readonly client;
+    readonly sessionId: string;
+    readonly repoAlias: string;
+    private readonly data;
+    private lost;
+    private closing?;
+    private readonly abort;
+    private readonly handles;
+    private readonly early;
+    private creating;
+    private snapshot;
+    private readonly tee;
+    private loop?;
+    private constructor();
+    /**
+     * Starts a private data server, registers the live process and starts polling.
+     * @param client - A connected, compatible hub
+     * @param options - Repository backend, workspace, label and exact release
+     * @returns The live session
+     * @throws {Error} On registration failure, after removing the data socket
+     */
+    static open(client: HubClient, options: RackSessionOptions): Promise<RackSession>;
+    /** Whether the original hub has been lost; later creates refuse immediately. */
+    get hubLost(): boolean;
+    /** Returns the latest capacity snapshot without a network round trip. */
+    capacity(): CapacitySnapshot;
+    /** Refreshes fleet capacity without disturbing the ordered event cursor. */
+    refreshCapacity(): Promise<CapacitySnapshot>;
+    /**
+     * Submits work or attaches to an existing lease, handling events that race
+     * the create response. Attempt identity is assigned at claim, never locally.
+     * @param request - Current task/unit event and rack shape
+     * @returns An ordered subscription to the lease
+     */
+    createLease(request: LeaseRequest): Promise<LeaseHandle>;
+    /**
+     * Attaches to identical work already queued or held, which costs the racks
+     * no further capacity, and queues nothing otherwise: how a run spills work
+     * locally when the racks are full, without first offering it to them.
+     * @param request - Current task/unit event and rack shape
+     * @returns An ordered subscription, or null when no such work is queued
+     */
+    attachLease(request: LeaseRequest): Promise<LeaseHandle | null>;
+    private subscribe;
+    private unsubscribe;
+    /** Registers a live log tee; persistence remains the data server's job. */
+    onLog(executionId: string, sink: (stream: 'stdout' | 'stderr', data: string) => void): () => void;
+    private update;
+    private poll;
+    /** Unregisters first, stops polling and removes the private data endpoint once. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=session.d.ts.map

package/dist/src/client/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../../src/client/session.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,EAA2B,KAAK,WAAW,EAAE,MAAM,eAAe,CAAC;AAC1E,OAAO,EAAgB,KAAK,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAErE,OAAO,EAAyB,cAAc,EAAE,KAAK,gBAAgB,EAAE,KAAK,WAAW,EAAqB,MAAM,wBAAwB,CAAC;AAC3I,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAGpE,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,4EAA4E;AAC5E,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC,OAAO,cAAc,CAAC,CAAC;AAC9D,gFAAgF;AAChF,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,YAAY,CAAA;CAAE,GAC7E;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,MAAM,EAAE,eAAe,CAAC;IAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IAAC,EAAE,EAAE,IAAI,CAAA;CAAE,GACtF;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAC1B,wEAAwE;AACxE,MAAM,MAAM,YAAY,GAAG,WAAW,CAAC;AACvC,oDAAoD;AACpD,MAAM,WAAW,WAAW;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,oEAAoE;IACpE,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,YAAY,GAAG,IAAI,CAAC;IACtC,6EAA6E;IAC7E,IAAI,IAAI,OAAO,CAAC,WAAW,CAAC,CAAC;IAC7B,+EAA+E;IAC/E,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACzB;AA+BD,oEAAoE;AACpE,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,OAAO,EAAE,cAAc,CAAC;IACxB,0DAA0D;IAC1D,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,qEAAqE;IACrE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAOD;;;;;;;;GAQG;AACH,qBAAa,WAAW;IAWF,OAAO,CAAC,QAAQ,CAAC,MAAM;IAAa,QAAQ,CAAC,SAAS,EAAE,MAAM;IAAE,QAAQ,CAAC,SAAS,EAAE,MAAM;IAC5G,OAAO,CAAC,QAAQ,CAAC,IAAI;IAXvB,OAAO,CAAC,IAAI,CAAS;IACrB,OAAO,CAAC,OAAO,CAAC,CAAgB;IAChC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAyB;IAC/C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAkC;IAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAoC;IAC1D,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,QAAQ,CAAmF;IACnG,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA+E;IACnG,OAAO,CAAC,IAAI,CAAC,CAAgB;IAE7B,OAAO;IAGP;;;;;;OAMG;WACU,IAAI,CAAC,MAAM,EAAE,SAAS,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,WAAW,CAAC;IAsBvF,gFAAgF;IAChF,IAAI,OAAO,IAAI,OAAO,CAAsB;IAC5C,yEAAyE;IACzE,QAAQ,IAAI,gBAAgB;IAE5B,4EAA4E;IACtE,eAAe,IAAI,OAAO,CAAC,gBAAgB,CAAC;IAOlD;;;;;OAKG;IACG,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,CAAC;IAI9D;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC;YAOjD,SAAS;YAkBT,WAAW;IAoBzB,2EAA2E;IAC3E,KAAK,CAAC,WAAW,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,MAAM,EAAE,QAAQ,GAAG,QAAQ,EAAE,IAAI,EAAE,MAAM,KAAK,IAAI,GAAG,MAAM,IAAI;IAKjG,OAAO,CAAC,MAAM;YAUA,IAAI;IAgClB,mFAAmF;IACnF,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAYvB"}

package/dist/src/client/session.js

@@ -0,0 +1,290 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { randomBytes } from 'node:crypto';
+import { realpath } from 'node:fs/promises';
+import { setTimeout as delay } from 'node:timers/promises';
+import { IntegerType, compareFor } from '@elaraai/east';
+import { processOwner } from '@elaraai/e3-core';
+import { E3_RACK_VERSION, HUB_PROTOCOL } from '../version.js';
+import { startSessionDataServer } from './session-data-server.js';
+import { RackHubUnavailableError } from './connect.js';
+class Handle {
+    leaseId;
+    attached;
+    unsubscribe;
+    attempt;
+    queue = [];
+    waiters = [];
+    terminal;
+    lastClaim;
+    cancelling;
+    constructor(leaseId, attached, attempt, unsubscribe) {
+        this.leaseId = leaseId;
+        this.attached = attached;
+        this.unsubscribe = unsubscribe;
+        this.attempt = attempt;
+    }
+    push(update) {
+        if (this.terminal !== undefined)
+            return;
+        if (update.kind === 'claimed') {
+            if (this.lastClaim === update.attempt.executionId)
+                return;
+            this.lastClaim = update.attempt.executionId;
+            this.attempt = update.attempt;
+        }
+        else
+            this.terminal = update;
+        const waiter = this.waiters.shift();
+        if (waiter === undefined)
+            this.queue.push(update);
+        else
+            waiter(update);
+        if (this.terminal !== undefined)
+            for (const waiting of this.waiters.splice(0))
+                waiting(this.terminal);
+    }
+    next() {
+        const queued = this.queue.shift();
+        if (queued !== undefined)
+            return Promise.resolve(queued);
+        if (this.terminal !== undefined)
+            return Promise.resolve(this.terminal);
+        return new Promise((resolve) => { this.waiters.push(resolve); });
+    }
+    cancel() { return this.cancelling ??= this.unsubscribe(this); }
+}
+// One listener for every open session of this process, however many runs an
+// API server keeps attached: the sessions it closes as the process ends.
+const openSessions = new Set();
+const closeOpenSessions = () => { for (const session of openSessions)
+    void session.close(); };
+/**
+ * Keeps a run attached to the hub and serves its repository through a private
+ * socket. A lost hub ends every pending wait; this session never reconnects
+ * to a replacement whose in-memory leases cannot be the old ones.
+ * @example
+ * const session = await RackSession.open(client, { storage, repoPath, workspace: 'dev', label: 'run dev' });
+ * try { const lease = await session.createLease(request); await lease.next(); }
+ * finally { await session.close(); }
+ */
+export class RackSession {
+    client;
+    sessionId;
+    repoAlias;
+    data;
+    lost = false;
+    closing;
+    abort = new AbortController();
+    handles = new Map();
+    early = new Map();
+    creating = 0;
+    snapshot = { racks: [], queued: 0n, mine: { pending: 0n, claimed: 0n } };
+    tee = new Map();
+    loop;
+    constructor(client, sessionId, repoAlias, data) {
+        this.client = client;
+        this.sessionId = sessionId;
+        this.repoAlias = repoAlias;
+        this.data = data;
+    }
+    /**
+     * Starts a private data server, registers the live process and starts polling.
+     * @param client - A connected, compatible hub
+     * @param options - Repository backend, workspace, label and exact release
+     * @returns The live session
+     * @throws {Error} On registration failure, after removing the data socket
+     */
+    static async open(client, options) {
+        const dataToken = randomBytes(32).toString('hex');
+        let session;
+        const data = await startSessionDataServer({ storage: options.storage, repoPath: await realpath(options.repoPath), home: client.home, dataToken,
+            onLog: (id, stream, text) => { for (const sink of session?.tee.get(id) ?? [])
+                sink(stream, text); } });
+        try {
+            const opened = await client.openSession({ protocol: BigInt(HUB_PROTOCOL), e3Version: options.e3Version ?? E3_RACK_VERSION,
+                owner: await processOwner(), repoPath: await realpath(options.repoPath), workspace: options.workspace, label: options.label,
+                dataSocket: data.socketPath, dataToken });
+            session = new RackSession(client, opened.sessionId, opened.repoAlias, data);
+            const initial = await client.events(opened.sessionId, 0n, 0);
+            session.snapshot = initial.capacity;
+            session.loop = session.poll();
+            if (openSessions.size === 0)
+                process.on('beforeExit', closeOpenSessions);
+            openSessions.add(session);
+            return session;
+        }
+        catch (err) {
+            if (session !== undefined)
+                await client.closeSession(session.sessionId).catch(() => { });
+            await data.close();
+            throw err;
+        }
+    }
+    /** Whether the original hub has been lost; later creates refuse immediately. */
+    get hubLost() { return this.lost; }
+    /** Returns the latest capacity snapshot without a network round trip. */
+    capacity() { return this.snapshot; }
+    /** Refreshes fleet capacity without disturbing the ordered event cursor. */
+    async refreshCapacity() {
+        if (this.lost || this.closing !== undefined)
+            return this.snapshot;
+        const status = await this.client.status();
+        this.snapshot = { ...status.capacity, mine: this.snapshot.mine };
+        return this.snapshot;
+    }
+    /**
+     * Submits work or attaches to an existing lease, handling events that race
+     * the create response. Attempt identity is assigned at claim, never locally.
+     * @param request - Current task/unit event and rack shape
+     * @returns An ordered subscription to the lease
+     */
+    async createLease(request) {
+        return (await this.subscribe((sessionId) => this.client.createLease(sessionId, request)));
+    }
+    /**
+     * Attaches to identical work already queued or held, which costs the racks
+     * no further capacity, and queues nothing otherwise: how a run spills work
+     * locally when the racks are full, without first offering it to them.
+     * @param request - Current task/unit event and rack shape
+     * @returns An ordered subscription, or null when no such work is queued
+     */
+    attachLease(request) {
+        return this.subscribe(async (sessionId) => {
+            const attached = await this.client.attachLease(sessionId, request);
+            return attached.type === 'some' ? attached.value : null;
+        });
+    }
+    async subscribe(ask) {
+        if (this.lost || this.closing !== undefined)
+            throw new RackHubUnavailableError('Rack session is closed or its hub is unreachable');
+        this.creating++;
+        try {
+            const created = await ask(this.sessionId);
+            if (created === null)
+                return null;
+            const handle = new Handle(created.leaseId, created.attached, created.attempt.type === 'some' ? created.attempt.value : null, (handle) => this.unsubscribe(handle));
+            const handles = this.handles.get(created.leaseId) ?? new Set();
+            handles.add(handle);
+            this.handles.set(created.leaseId, handles);
+            for (const update of this.early.get(created.leaseId) ?? [])
+                handle.push(update);
+            if (this.lost || this.closing !== undefined)
+                handle.push({ kind: 'lost', reason: 'rack hub unreachable' });
+            return handle;
+        }
+        finally {
+            this.creating--;
+            if (this.creating === 0)
+                this.early.clear();
+        }
+    }
+    async unsubscribe(handle) {
+        const handles = this.handles.get(handle.leaseId);
+        if (handles === undefined || !handles.has(handle))
+            return;
+        if (handles.size > 1) {
+            handles.delete(handle);
+            handle.push({ kind: 'cancelled' });
+            return;
+        }
+        try {
+            if (!this.lost && this.closing === undefined) {
+                const response = await this.client.cancelLease(this.sessionId, handle.leaseId);
+                // Completion won the hub's fence. Its event remains authoritative and
+                // may still be in the events response racing this cancellation reply.
+                if (response.status === 'completed')
+                    return;
+            }
+            handle.push(this.lost ? { kind: 'lost', reason: 'rack hub unreachable' } : { kind: 'cancelled' });
+            handles.delete(handle);
+            if (handles.size === 0)
+                this.handles.delete(handle.leaseId);
+        }
+        finally {
+            // A completed handle can still receive the in-flight completion event.
+            if (this.lost || this.closing !== undefined)
+                this.handles.delete(handle.leaseId);
+        }
+    }
+    /** Registers a live log tee; persistence remains the data server's job. */
+    onLog(executionId, sink) {
+        const sinks = this.tee.get(executionId) ?? new Set();
+        sinks.add(sink);
+        this.tee.set(executionId, sinks);
+        return () => { sinks.delete(sink); if (sinks.size === 0)
+            this.tee.delete(executionId); };
+    }
+    update(event) {
+        switch (event.type) {
+            case 'claimed': return { kind: 'claimed', rackId: event.value.rackId, rackLabel: event.value.rackLabel, attempt: event.value.attempt };
+            case 'completed': return { kind: 'completed', result: JSON.parse(event.value.resultJson),
+                attempt: event.value.attempt.type === 'some' ? event.value.attempt.value : null, at: event.value.at };
+            case 'lost': return { kind: 'lost', reason: event.value.reason };
+            case 'cancelled': return { kind: 'cancelled' };
+        }
+    }
+    async poll() {
+        let after = 0n;
+        let failures = 0;
+        while (!this.abort.signal.aborted && !this.lost) {
+            try {
+                const response = await this.client.events(this.sessionId, after, 20000, this.abort.signal);
+                failures = 0;
+                this.snapshot = response.capacity;
+                for (const event of response.events) {
+                    if (compareFor(IntegerType)(event.seq, after) <= 0)
+                        continue;
+                    after = event.seq;
+                    const update = this.update(event.event);
+                    const id = event.event.value.leaseId;
+                    const handles = this.handles.get(id);
+                    if (handles !== undefined)
+                        for (const handle of handles)
+                            handle.push(update);
+                    if (update.kind !== 'claimed')
+                        this.handles.delete(id);
+                    if (this.creating > 0) {
+                        const early = this.early.get(id) ?? [];
+                        early.push(update);
+                        this.early.set(id, early);
+                    }
+                }
+            }
+            catch {
+                if (this.abort.signal.aborted)
+                    break;
+                if (++failures >= 2) {
+                    this.lost = true;
+                    this.snapshot = { racks: [], queued: 0n, mine: { pending: 0n, claimed: 0n } };
+                    for (const handles of this.handles.values())
+                        for (const handle of handles)
+                            handle.push({ kind: 'lost', reason: 'rack hub unreachable' });
+                    break;
+                }
+                await delay(100, undefined, { signal: this.abort.signal }).catch(() => { });
+            }
+        }
+    }
+    /** Unregisters first, stops polling and removes the private data endpoint once. */
+    close() {
+        return this.closing ??= (async () => {
+            openSessions.delete(this);
+            if (openSessions.size === 0)
+                process.off('beforeExit', closeOpenSessions);
+            await this.client.closeSession(this.sessionId).catch(() => { });
+            this.abort.abort();
+            await this.loop;
+            for (const handles of this.handles.values())
+                for (const handle of handles)
+                    handle.push({ kind: 'cancelled' });
+            this.handles.clear();
+            this.early.clear();
+            this.tee.clear();
+            await this.data.close();
+        })();
+    }
+}
+//# sourceMappingURL=session.js.map