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

package/dist/src/lease/lease-store.d.ts

@@ -0,0 +1,169 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import type { RackLeaseStatus } from './rack-dispatch.js';
+import type { RackLeaseAttempt, RackLeaseEvent, RackLeaseResult } from '../protocol/task-envelope.js';
+/**
+ * The most object keys a lease may be issued write targets for (#214): its
+ * row records each, and a failed or expired lease deletes the uncatalogued
+ * versions of each. A unit that writes more new objects than this falls back
+ * to the cloud.
+ */
+export declare const MAX_LEASE_TARGETS = 4096;
+/** A stored lease — the persistent shape behind the RackDispatch seam. */
+export interface RackLeaseRecord {
+    /** `{taskHash}#{inputsHash}#{uuidv7}` — see {@link makeLeaseId}. */
+    leaseId: string;
+    repo: string;
+    workspace: string;
+    taskHash: string;
+    inputsHash: string;
+    /** The rack tier the task needs (node | py | c | ...). */
+    tier: string;
+    /** The task's compute size tag — the agent's VM shape (default serverless). */
+    computeSize?: string;
+    status: RackLeaseStatus;
+    /** The rack that claimed it (set on claim and preserved after). */
+    claimedBy?: string;
+    /** Epoch ms of the (latest) claim — the rack-activity timeline (D12 UI). */
+    claimedAtMs?: number;
+    /** Epoch ms of completion. */
+    completedAtMs?: number;
+    /** Epoch ms; while `claimed`, past-deadline means reclaimable. */
+    visibilityDeadlineMs?: number;
+    /** The task envelope the agent executes. */
+    event: RackLeaseEvent;
+    /** The attempt the latest claim runs: minted by the claim, for a task or
+     *  unit lease (#214) */
+    attempt?: RackLeaseAttempt;
+    /** The object hashes the lease was issued write targets for (#214): what
+     *  its end deletes the uncatalogued versions of */
+    targets?: readonly string[];
+    /** Terminal result (set on `completed`). */
+    result?: RackLeaseResult;
+    createdAtMs: number;
+}
+/** Disposition of a completion attempt (accepted-and-discarded semantics). */
+export type CompleteDisposition = 'recorded' | 'idempotent' | 'discarded';
+/**
+ * Build a lease id embedding the re-attachment key.
+ *
+ * @param taskHash - The task's content hash
+ * @param inputsHash - Hash of the resolved input set
+ * @returns `{taskHash}#{inputsHash}#{uuidv7}`: a fresh id, which sorts after every earlier lease of the task
+ * @example
+ * const leaseId = makeLeaseId(taskHash, inputsHash);
+ */
+export declare function makeLeaseId(taskHash: string, inputsHash: string): string;
+/**
+ * The key prefix all leases for a task identity share.
+ *
+ * @param taskHash - The task's content hash
+ * @param inputsHash - Hash of the resolved input set
+ * @returns `{taskHash}#{inputsHash}#`
+ * @example
+ * const ofTask = ids.filter((id) => id.startsWith(leaseIdPrefix(taskHash, inputsHash)));
+ */
+export declare function leaseIdPrefix(taskHash: string, inputsHash: string): string;
+/**
+ * Whether a lease can be claimed right now: pending, or claimed with an
+ * expired visibility deadline (the claimant went quiet).
+ *
+ * @param record - The stored lease
+ * @param nowMs - Current epoch ms
+ * @returns Whether a claim would take it
+ * @example
+ * const candidates = records.filter((record) => isClaimable(record, Date.now()));
+ */
+export declare function isClaimable(record: RackLeaseRecord, nowMs: number): boolean;
+/**
+ * Whether a rack lease is still held: claimed within its visibility deadline,
+ * which the claimant's heartbeat extends, or pending a claim. A rack
+ * attempt's liveness (#206, `launchLiveness`): the attempt can still finish
+ * while its lease is held.
+ *
+ * @param leases - The lease store
+ * @param now - The time, in ms since the epoch (default `Date.now`)
+ * @returns Whether a repository's lease is held
+ */
+export declare function rackLeaseHeld(leases: Pick<RackLeaseStore, 'get'>, now?: () => number): (repo: string, leaseId: string) => Promise<boolean>;
+/**
+ * Rack lease persistence seam. Implementations: `InMemoryRackLeaseStore`
+ * (testing) and `DynamoRackLeaseStore` (e3-aws; lease rows under
+ * `PK=RACKLEASE/{repo}` plus a small `PK=RACKQUEUE` discovery partition).
+ */
+export interface RackLeaseStore {
+    /** Persist a new pending lease (and its queue-discovery entry). */
+    put(record: RackLeaseRecord): Promise<void>;
+    /** Read one lease. */
+    get(repo: string, leaseId: string): Promise<RackLeaseRecord | null>;
+    /**
+     * Latest lease for a task identity that is not superseded/cancelled —
+     * the yield re-attachment lookup (prefix query on the lease id).
+     */
+    findByTask(repo: string, taskHash: string, inputsHash: string): Promise<RackLeaseRecord | null>;
+    /**
+     * Leases an agent with the given tiers could claim right now (pending or
+     * visibility-expired), oldest first.
+     *
+     * @param tiers - The tiers the agent has rootfs for
+     * @param nowMs - Current epoch ms
+     * @param limit - Max candidates to return
+     */
+    listClaimable(tiers: string[], nowMs: number, limit: number): Promise<RackLeaseRecord[]>;
+    /**
+     * Conditionally claim a lease: succeeds only while {@link isClaimable}.
+     * Exactly one racing claimant wins.
+     *
+     * @param attempt - The attempt the claim runs, for a task or unit lease
+     *   (#214): it replaces the one an earlier claim ran
+     * @returns The claimed record, or null when the condition lost
+     */
+    claim(repo: string, leaseId: string, rackId: string, visibilityDeadlineMs: number, attempt?: RackLeaseAttempt): Promise<RackLeaseRecord | null>;
+    /**
+     * Record object hashes a lease was issued write targets for (#214), only
+     * by its claimant while it holds the lease. The lease keeps each once.
+     *
+     * @returns Whether they were recorded: false when the lease is not held by
+     *   the rack
+     */
+    recordTargets(repo: string, leaseId: string, rackId: string, hashes: readonly string[]): Promise<boolean>;
+    /**
+     * Recent leases claimed by a rack, newest first — the fleet-table
+     * activity view ("what has this rack done"). A lease reclaimed by
+     * ANOTHER rack after visibility expiry leaves this rack's list (the
+     * record tracks its latest claimant only).
+     *
+     * @param rackId - The rack whose activity is listed
+     * @param limit - Max records
+     */
+    listRecentByRack(rackId: string, limit: number): Promise<RackLeaseRecord[]>;
+    /**
+     * Extend a claimed lease's visibility — only by its claimant.
+     *
+     * @returns Whether the extension applied
+     */
+    extend(repo: string, leaseId: string, rackId: string, visibilityDeadlineMs: number): Promise<boolean>;
+    /**
+     * Record a terminal result — only transitions `claimed → completed` by
+     * the claimant. Anything else is 'idempotent' (already completed) or
+     * 'discarded' (superseded/cancelled/expired-and-reclaimed/unknown).
+     */
+    complete(repo: string, leaseId: string, rackId: string, result: RackLeaseResult): Promise<CompleteDisposition>;
+    /**
+     * CAS supersede (runner falling back to cloud): `pending|claimed →
+     * superseded`; a completed lease stays completed.
+     *
+     * @returns The lease's state after the attempt
+     */
+    supersede(repo: string, leaseId: string): Promise<RackLeaseRecord | null>;
+    /**
+     * CAS cancel: `pending|claimed → cancelled`; a completed lease stays
+     * completed. Heartbeats deliver the signal to the running agent.
+     *
+     * @returns The lease's state after the attempt
+     */
+    cancel(repo: string, leaseId: string): Promise<RackLeaseRecord | null>;
+}
+//# sourceMappingURL=lease-store.d.ts.map

package/dist/src/lease/lease-store.d.ts.map

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

package/dist/src/lease/lease-store.js

@@ -0,0 +1,94 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Rack lease persistence (#73, epic #67 design §9.2–9.3) — the DynamoDB-
+ * layered pull queue behind {@link StoreRackDispatch} and the /rack
+ * dispatch routes.
+ *
+ * Lease state machine (review F3), every transition a conditional write:
+ *
+ *   pending ──claim──▶ claimed ──complete──▶ completed
+ *      │                 │  ▲
+ *      │                 │  └─ extend (visibility)
+ *      │           visibility expires (lazily observed: the lease becomes
+ *      │           claimable again; a claim retakes it)
+ *      ├──supersede──▶ superseded   (runner fell back to cloud)
+ *      └──cancel─────▶ cancelled    (heartbeat delivers; agent kills the VM)
+ *
+ * `complete` against superseded/cancelled (or by a non-claimant) is
+ * **accepted-and-discarded** — never an error, the response just tells the
+ * agent to drop local state. `complete` on completed is idempotent-success.
+ * Supersede/cancel are CAS: an already-completed lease stays completed and
+ * the caller receives it (completed-wins).
+ *
+ * The lease id embeds the task identity (`{taskHash}#{inputsHash}#{uuid}`)
+ * so the store can find re-attachable leases with a key-prefix query — no
+ * scans, no extra index.
+ */
+import { uuidv7 } from '@elaraai/e3-core';
+/**
+ * The most object keys a lease may be issued write targets for (#214): its
+ * row records each, and a failed or expired lease deletes the uncatalogued
+ * versions of each. A unit that writes more new objects than this falls back
+ * to the cloud.
+ */
+export const MAX_LEASE_TARGETS = 4096;
+/**
+ * Build a lease id embedding the re-attachment key.
+ *
+ * @param taskHash - The task's content hash
+ * @param inputsHash - Hash of the resolved input set
+ * @returns `{taskHash}#{inputsHash}#{uuidv7}`: a fresh id, which sorts after every earlier lease of the task
+ * @example
+ * const leaseId = makeLeaseId(taskHash, inputsHash);
+ */
+export function makeLeaseId(taskHash, inputsHash) {
+    return `${taskHash}#${inputsHash}#${uuidv7()}`;
+}
+/**
+ * The key prefix all leases for a task identity share.
+ *
+ * @param taskHash - The task's content hash
+ * @param inputsHash - Hash of the resolved input set
+ * @returns `{taskHash}#{inputsHash}#`
+ * @example
+ * const ofTask = ids.filter((id) => id.startsWith(leaseIdPrefix(taskHash, inputsHash)));
+ */
+export function leaseIdPrefix(taskHash, inputsHash) {
+    return `${taskHash}#${inputsHash}#`;
+}
+/**
+ * Whether a lease can be claimed right now: pending, or claimed with an
+ * expired visibility deadline (the claimant went quiet).
+ *
+ * @param record - The stored lease
+ * @param nowMs - Current epoch ms
+ * @returns Whether a claim would take it
+ * @example
+ * const candidates = records.filter((record) => isClaimable(record, Date.now()));
+ */
+export function isClaimable(record, nowMs) {
+    return (record.status === 'pending' ||
+        (record.status === 'claimed' && (record.visibilityDeadlineMs ?? 0) < nowMs));
+}
+/**
+ * Whether a rack lease is still held: claimed within its visibility deadline,
+ * which the claimant's heartbeat extends, or pending a claim. A rack
+ * attempt's liveness (#206, `launchLiveness`): the attempt can still finish
+ * while its lease is held.
+ *
+ * @param leases - The lease store
+ * @param now - The time, in ms since the epoch (default `Date.now`)
+ * @returns Whether a repository's lease is held
+ */
+export function rackLeaseHeld(leases, now = Date.now) {
+    return async (repo, leaseId) => {
+        const record = await leases.get(repo, leaseId);
+        if (record === null)
+            return false;
+        return record.status === 'pending' || (record.status === 'claimed' && (record.visibilityDeadlineMs ?? 0) >= now());
+    };
+}
+//# sourceMappingURL=lease-store.js.map

package/dist/src/lease/lease-store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-store.js","sourceRoot":"","sources":["../../../src/lease/lease-store.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAI1C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,IAAI,CAAC;AAuCtC;;;;;;;;GAQG;AACH,MAAM,UAAU,WAAW,CAAC,QAAgB,EAAE,UAAkB;IAC9D,OAAO,GAAG,QAAQ,IAAI,UAAU,IAAI,MAAM,EAAE,EAAE,CAAC;AACjD,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB,EAAE,UAAkB;IAChE,OAAO,GAAG,QAAQ,IAAI,UAAU,GAAG,CAAC;AACtC,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,WAAW,CAAC,MAAuB,EAAE,KAAa;IAChE,OAAO,CACL,MAAM,CAAC,MAAM,KAAK,SAAS;QAC3B,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,oBAAoB,IAAI,CAAC,CAAC,GAAG,KAAK,CAAC,CAC5E,CAAC;AACJ,CAAC;AAED;;;;;;;;;GASG;AACH,MAAM,UAAU,aAAa,CAC3B,MAAmC,EACnC,MAAoB,IAAI,CAAC,GAAG;IAE5B,OAAO,KAAK,EAAE,IAAI,EAAE,OAAO,EAAE,EAAE;QAC7B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,GAAG,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC;QAC/C,IAAI,MAAM,KAAK,IAAI;YAAE,OAAO,KAAK,CAAC;QAClC,OAAO,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,CAAC,MAAM,CAAC,oBAAoB,IAAI,CAAC,CAAC,IAAI,GAAG,EAAE,CAAC,CAAC;IACrH,CAAC,CAAC;AACJ,CAAC"}

package/dist/src/lease/lease-store.spec.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=lease-store.spec.d.ts.map

package/dist/src/lease/lease-store.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-store.spec.d.ts","sourceRoot":"","sources":["../../../src/lease/lease-store.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/lease/lease-store.spec.js

@@ -0,0 +1,8 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { InMemoryRackLeaseStore } from './in-memory-lease-store.js';
+import { leaseStoreContract } from '../testing/lease-store-contract.js';
+leaseStoreContract('memory', () => new InMemoryRackLeaseStore());
+//# sourceMappingURL=lease-store.spec.js.map

package/dist/src/lease/lease-store.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"lease-store.spec.js","sourceRoot":"","sources":["../../../src/lease/lease-store.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,sBAAsB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,EAAE,kBAAkB,EAAE,MAAM,oCAAoC,CAAC;AAExE,kBAAkB,CAAC,QAAQ,EAAE,GAAG,EAAE,CAAC,IAAI,sBAAsB,EAAE,CAAC,CAAC"}

package/dist/src/lease/rack-dispatch.d.ts

@@ -0,0 +1,105 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * The rack dispatch seam DelegatingTaskRunner drives (epic #67 design §7.3,
+ * §9.2 rev. 2026-07-11). #73 implements it over the RackLease store +
+ * registry; FakeRackDispatch (testing) lets #70 land and test independently.
+ *
+ * Lease lifecycle (every transition a conditional write):
+ * `pending → claimed → completed | superseded | cancelled`, with visibility
+ * expiry making a claimed lease reclaimable. A completion against a
+ * superseded/cancelled lease is accepted-and-discarded by the store. The
+ * cloud records a task or unit lease's attempt itself (#214): `running` when
+ * a rack claims it, its outcome when the rack completes it, and `interrupted`
+ * or `cancelled` when it is superseded or cancelled while claimed.
+ */
+import type { RackLeaseAttempt, RackLeaseEvent, RackLeaseResult } from '../protocol/task-envelope.js';
+/** A lease's lifecycle state. */
+export type RackLeaseStatus = 'pending' | 'claimed' | 'completed' | 'superseded' | 'cancelled';
+/** One delegated task hand-off. */
+export interface RackLease {
+    leaseId: string;
+    repo: string;
+    workspace: string;
+    /** Task identity — the re-attachment key across orchestrator yields. */
+    taskHash: string;
+    inputsHash: string;
+    /** The dataflow run this lease belongs to, a UUIDv7: re-attach is scoped
+     *  to it (a lease from a prior run is never a cache; #67) */
+    runId?: string;
+    /** The rack tier it runs on */
+    tier: string;
+    /** The compute size tag its VM is shaped by */
+    computeSize: string;
+    status: RackLeaseStatus;
+    /** The rack that claimed it (set on `claimed` and beyond). */
+    claimedBy?: string;
+    /** The attempt its latest claim runs, for a task or unit lease (#214) */
+    attempt?: RackLeaseAttempt;
+    /** Terminal result (set on `completed`). */
+    result?: RackLeaseResult;
+}
+/**
+ * What DelegatingTaskRunner needs from the rack control plane. Implemented
+ * over the lease store + rack registry (#73); faked in tests.
+ */
+export interface RackDispatch {
+    /**
+     * Whether any healthy enrolled rack advertises the tier and runs an agent
+     * that runs a v2 lease (0.5.0 and later, #214): the prefer-rack
+     * availability check. NOT per-rack targeting: the v1 lease pool is
+     * repo-global and any matching agent claims.
+     *
+     * @param tier - The work's rack tier (node | py | c | full | env base)
+     */
+    anyHealthyRackWithTier(tier: string): Promise<boolean>;
+    /**
+     * The rack tier (base image) a PUBLISHED environment was built on, or
+     * null when the env is not published for rack execution (#94 Slice D).
+     * Also the delegability gate for env/custom tasks: null ⇒ cloud.
+     *
+     * @param envHash - The task's declared environment hash
+     */
+    envBaseTier(envHash: string): Promise<string | null>;
+    /**
+     * Find a live (pending/claimed) or completed lease for a task — the
+     * re-attachment path a resumed orchestrator cycle takes instead of
+     * creating a duplicate.
+     */
+    findLease(repo: string, taskHash: string, inputsHash: string): Promise<RackLease | null>;
+    /**
+     * Create a pending lease carrying the work's event.
+     *
+     * @param event - The v2 lease event the agent will run
+     * @param tier - The rack tier the work requires
+     * @param computeSize - The work's resolved compute size tag (VM shape)
+     */
+    createLease(event: RackLeaseEvent, tier: string, computeSize?: string): Promise<RackLease>;
+    /** Re-read a lease's current state. */
+    getLease(repo: string, leaseId: string): Promise<RackLease | null>;
+    /**
+     * Terminally supersede a lease (runner falling back to cloud). A CAS —
+     * a lease already `completed` stays completed (the store returns the
+     * final state so the caller can still use a result that won the race).
+     * A claimed lease's attempt is recorded `interrupted` (#214).
+     *
+     * @returns The lease's state after the attempt
+     */
+    supersede(repo: string, leaseId: string): Promise<RackLease | null>;
+    /**
+     * Terminally cancel a lease: its run was cancelled. A CAS, as
+     * {@link supersede}; the rack's next heartbeat stops it, and a claimed
+     * lease's attempt is recorded `cancelled` (#214).
+     *
+     * @returns The lease's state after the attempt
+     */
+    cancel(repo: string, leaseId: string): Promise<RackLease | null>;
+    /**
+     * Whether a lease is still held: pending a claim, or claimed within its
+     * visibility deadline. A rack attempt's liveness (#206, #214).
+     */
+    leaseHeld(repo: string, leaseId: string): Promise<boolean>;
+}
+//# sourceMappingURL=rack-dispatch.d.ts.map

package/dist/src/lease/rack-dispatch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rack-dispatch.d.ts","sourceRoot":"","sources":["../../../src/lease/rack-dispatch.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;;;;;;;GAYG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAC;AAEtG,iCAAiC;AACjC,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,SAAS,GAAG,WAAW,GAAG,YAAY,GAAG,WAAW,CAAC;AAE/F,mCAAmC;AACnC,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB;iEAC6D;IAC7D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,+CAA+C;IAC/C,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,eAAe,CAAC;IACxB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,yEAAyE;IACzE,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,4CAA4C;IAC5C,MAAM,CAAC,EAAE,eAAe,CAAC;CAC1B;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;;;;OAOG;IACH,sBAAsB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAEvD;;;;;;OAMG;IACH,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAErD;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEzF;;;;;;OAMG;IACH,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;IAE3F,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEnE;;;;;;;OAOG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEpE;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC,CAAC;IAEjE;;;OAGG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5D"}

package/dist/src/lease/rack-dispatch.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+export {};
+//# sourceMappingURL=rack-dispatch.js.map

package/dist/src/lease/rack-dispatch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rack-dispatch.js","sourceRoot":"","sources":["../../../src/lease/rack-dispatch.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/src/mutation-queue.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/** Serializes a store's mutations; failed mutations do not poison the queue. @internal */
+export declare class MutationQueue {
+    private tail;
+    /** Runs the operation after every preceding operation has settled. */
+    run<T>(operation: () => Promise<T>): Promise<T>;
+    /** Waits for all operations already queued. */
+    idle(): Promise<void>;
+}
+//# sourceMappingURL=mutation-queue.d.ts.map

package/dist/src/mutation-queue.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-queue.d.ts","sourceRoot":"","sources":["../../src/mutation-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,0FAA0F;AAC1F,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAAuC;IAEnD,sEAAsE;IACtE,GAAG,CAAC,CAAC,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAM/C,+CAA+C;IACzC,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;CAC5B"}

package/dist/src/mutation-queue.js

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/** Serializes a store's mutations; failed mutations do not poison the queue. @internal */
+export class MutationQueue {
+    tail = Promise.resolve();
+    /** Runs the operation after every preceding operation has settled. */
+    run(operation) {
+        const result = this.tail.then(operation);
+        this.tail = result.catch(() => undefined);
+        return result;
+    }
+    /** Waits for all operations already queued. */
+    async idle() { await this.tail; }
+}
+//# sourceMappingURL=mutation-queue.js.map

package/dist/src/mutation-queue.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mutation-queue.js","sourceRoot":"","sources":["../../src/mutation-queue.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,0FAA0F;AAC1F,MAAM,OAAO,aAAa;IAChB,IAAI,GAAqB,OAAO,CAAC,OAAO,EAAE,CAAC;IAEnD,sEAAsE;IACtE,GAAG,CAAI,SAA2B;QAChC,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QACzC,IAAI,CAAC,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,SAAS,CAAC,CAAC;QAC1C,OAAO,MAAM,CAAC;IAChB,CAAC;IAED,+CAA+C;IAC/C,KAAK,CAAC,IAAI,KAAoB,MAAM,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;CACjD"}

package/dist/src/paths.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/** The hashed machine credentials, under the rack home. */
+export declare const IDENTITY_FILE = "identity.beast2";
+/** The enrolled machines and their security policy. */
+export declare const RACKS_FILE = "racks.beast2";
+/** The hub's listening address and advertised origin. */
+export declare const HUB_CONFIG_FILE = "hub-config.beast2";
+/** The hub's TLS certificate and private key, created when its listener first serves TLS. */
+export declare const HUB_TLS_FILE = "hub-tls.beast2";
+/** The single hub's ownership record. */
+export declare const HUB_LOCK_FILE = "hub.lock";
+/** The hub process's diagnostic log. */
+export declare const HUB_LOG_FILE = "hub.log";
+/**
+ * Resolves this user's rack home, respecting `E3_RACK_HOME`.
+ * @returns An absolute path
+ * @example
+ * const home = rackHome();
+ */
+export declare function rackHome(): string;
+/**
+ * Creates the private rack home, tightening its existing permissions too.
+ * @param home - The rack home (default: this user's)
+ * @returns Its path
+ * @example
+ * const home = ensureRackHome();
+ */
+export declare function ensureRackHome(home?: string): string;
+/**
+ * Checks a socket path against the shortest supported Unix socket limit.
+ * @param path - The socket's path
+ * @throws {Error} When it exceeds 100 bytes on POSIX
+ * @example
+ * socketPathOk('/tmp/e3r/hub.sock');
+ */
+export declare function socketPathOk(path: string): void;
+/**
+ * Names this rack home's hub socket or Windows named pipe.
+ * @param home - The rack home
+ * @returns Its socket path
+ * @example
+ * const socket = hubSocketPath(rackHome());
+ */
+export declare function hubSocketPath(home?: string): string;
+/**
+ * Names a fresh session socket or Windows named pipe.
+ * @param home - The rack home
+ * @returns Its socket path
+ * @example
+ * const socket = sessionSocketPath(rackHome());
+ */
+export declare function sessionSocketPath(home?: string): string;
+//# sourceMappingURL=paths.d.ts.map

package/dist/src/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../../src/paths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,2DAA2D;AAC3D,eAAO,MAAM,aAAa,oBAAoB,CAAC;AAC/C,uDAAuD;AACvD,eAAO,MAAM,UAAU,iBAAiB,CAAC;AACzC,yDAAyD;AACzD,eAAO,MAAM,eAAe,sBAAsB,CAAC;AACnD,6FAA6F;AAC7F,eAAO,MAAM,YAAY,mBAAmB,CAAC;AAC7C,yCAAyC;AACzC,eAAO,MAAM,aAAa,aAAa,CAAC;AACxC,wCAAwC;AACxC,eAAO,MAAM,YAAY,YAAY,CAAC;AAEtC;;;;;GAKG;AACH,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,SAAa,GAAG,MAAM,CAIxD;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAI/C;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,IAAI,SAAa,GAAG,MAAM,CAMvD;AAED;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,SAAa,GAAG,MAAM,CAK3D"}

package/dist/src/paths.js

@@ -0,0 +1,82 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { chmodSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+/** The hashed machine credentials, under the rack home. */
+export const IDENTITY_FILE = 'identity.beast2';
+/** The enrolled machines and their security policy. */
+export const RACKS_FILE = 'racks.beast2';
+/** The hub's listening address and advertised origin. */
+export const HUB_CONFIG_FILE = 'hub-config.beast2';
+/** The hub's TLS certificate and private key, created when its listener first serves TLS. */
+export const HUB_TLS_FILE = 'hub-tls.beast2';
+/** The single hub's ownership record. */
+export const HUB_LOCK_FILE = 'hub.lock';
+/** The hub process's diagnostic log. */
+export const HUB_LOG_FILE = 'hub.log';
+/**
+ * Resolves this user's rack home, respecting `E3_RACK_HOME`.
+ * @returns An absolute path
+ * @example
+ * const home = rackHome();
+ */
+export function rackHome() {
+    return resolve(process.env.E3_RACK_HOME ?? join(homedir(), '.e3', 'rack'));
+}
+/**
+ * Creates the private rack home, tightening its existing permissions too.
+ * @param home - The rack home (default: this user's)
+ * @returns Its path
+ * @example
+ * const home = ensureRackHome();
+ */
+export function ensureRackHome(home = rackHome()) {
+    mkdirSync(home, { recursive: true, mode: 0o700 });
+    if (process.platform !== 'win32')
+        chmodSync(home, 0o700);
+    return home;
+}
+/**
+ * Checks a socket path against the shortest supported Unix socket limit.
+ * @param path - The socket's path
+ * @throws {Error} When it exceeds 100 bytes on POSIX
+ * @example
+ * socketPathOk('/tmp/e3r/hub.sock');
+ */
+export function socketPathOk(path) {
+    if (process.platform !== 'win32' && Buffer.byteLength(path) > 100) {
+        throw new Error('Rack socket path exceeds 100 bytes; set E3_RACK_HOME to a shorter path');
+    }
+}
+/**
+ * Names this rack home's hub socket or Windows named pipe.
+ * @param home - The rack home
+ * @returns Its socket path
+ * @example
+ * const socket = hubSocketPath(rackHome());
+ */
+export function hubSocketPath(home = rackHome()) {
+    const path = process.platform === 'win32'
+        ? `\\\\.\\pipe\\e3-rack-hub-${createHash('sha256').update(resolve(home)).digest('hex').slice(0, 12)}`
+        : join(home, 'hub.sock');
+    socketPathOk(path);
+    return path;
+}
+/**
+ * Names a fresh session socket or Windows named pipe.
+ * @param home - The rack home
+ * @returns Its socket path
+ * @example
+ * const socket = sessionSocketPath(rackHome());
+ */
+export function sessionSocketPath(home = rackHome()) {
+    const id = randomBytes(6).toString('hex');
+    const path = process.platform === 'win32' ? `\\\\.\\pipe\\e3-rack-s-${id}` : join(home, `s-${id}.sock`);
+    socketPathOk(path);
+    return path;
+}
+//# sourceMappingURL=paths.js.map

package/dist/src/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../../src/paths.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AACtD,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AAC/C,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAE1C,2DAA2D;AAC3D,MAAM,CAAC,MAAM,aAAa,GAAG,iBAAiB,CAAC;AAC/C,uDAAuD;AACvD,MAAM,CAAC,MAAM,UAAU,GAAG,cAAc,CAAC;AACzC,yDAAyD;AACzD,MAAM,CAAC,MAAM,eAAe,GAAG,mBAAmB,CAAC;AACnD,6FAA6F;AAC7F,MAAM,CAAC,MAAM,YAAY,GAAG,gBAAgB,CAAC;AAC7C,yCAAyC;AACzC,MAAM,CAAC,MAAM,aAAa,GAAG,UAAU,CAAC;AACxC,wCAAwC;AACxC,MAAM,CAAC,MAAM,YAAY,GAAG,SAAS,CAAC;AAEtC;;;;;GAKG;AACH,MAAM,UAAU,QAAQ;IACtB,OAAO,OAAO,CAAC,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,CAAC,CAAC;AAC7E,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,cAAc,CAAC,IAAI,GAAG,QAAQ,EAAE;IAC9C,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;IAClD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,IAAI,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC;QAClE,MAAM,IAAI,KAAK,CAAC,wEAAwE,CAAC,CAAC;IAC5F,CAAC;AACH,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,aAAa,CAAC,IAAI,GAAG,QAAQ,EAAE;IAC7C,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO;QACvC,CAAC,CAAC,4BAA4B,UAAU,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE;QACrG,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC;IAC3B,YAAY,CAAC,IAAI,CAAC,CAAC;IACnB,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,iBAAiB,CAAC,IAAI,GAAG,QAAQ,EAAE;IACjD,MAAM,EAAE,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,OAAO,CAAC,QAAQ,KAAK,OAAO,CAAC,CAAC,CAAC,0BAA0B,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,KAAK,EAAE,OAAO,CAAC,CAAC;IACxG,YAAY,CAAC,IAAI,CAAC,CAAC;IACnB,OAAO,IAAI,CAAC;AACd,CAAC"}