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

package/dist/src/protocol/rack-wire.d.ts

@@ -0,0 +1,357 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Rack machine-protocol wire types (epic #67 design §9) — the BEAST2 bodies
+ * exchanged between a rack agent and the deployment's /api/rack endpoints.
+ * Shared by the server routes (e3-cloud-core), the HTTP client, and the
+ * rack agent, so the shapes live here beside the delegation types.
+ */
+import { ArrayType, BlobType, BooleanType, DateTimeType, DictType, IntegerType, NullType, OptionType, StringType, StructType, VariantType, type ValueTypeOf } from '@elaraai/east';
+/**
+ * What an enrolling agent declares about its host: the operator-facing
+ * label, the runner tiers it has rootfs images for (node | py |
+ * py-datascience | c | full — the #57 vocabulary), its max concurrent
+ * microVMs, and the agent build it runs.
+ */
+export declare const RackHostInfoType: StructType<{
+    readonly label: StringType;
+    readonly tiers: ArrayType<StringType>;
+    readonly capacity: IntegerType;
+    readonly agentVersion: StringType;
+}>;
+export type RackHostInfo = ValueTypeOf<typeof RackHostInfoType>;
+/**
+ * POST /rack/enroll request — exchanges a single-use enrollment token
+ * (minted by an admin in the UI) for a long-lived rack credential.
+ */
+export declare const RackEnrollRequestType: StructType<{
+    readonly enrollmentToken: StringType;
+    readonly hostInfo: StructType<{
+        readonly label: StringType;
+        readonly tiers: ArrayType<StringType>;
+        readonly capacity: IntegerType;
+        readonly agentVersion: StringType;
+    }>;
+}>;
+export type RackEnrollRequest = ValueTypeOf<typeof RackEnrollRequestType>;
+/**
+ * POST /rack/enroll response — the generated rack identity and its
+ * bearer credential. The token is shown exactly once and stored hashed
+ * at rest server-side; the agent persists it mode 0600.
+ */
+export declare const RackEnrollResponseType: StructType<{
+    readonly rackId: StringType;
+    readonly rackToken: StringType;
+}>;
+export type RackEnrollResponse = ValueTypeOf<typeof RackEnrollResponseType>;
+/** A (repo, leaseId) reference — leases are partitioned per repo. */
+export declare const RackLeaseRefType: StructType<{
+    readonly repo: StringType;
+    readonly leaseId: StringType;
+}>;
+export type RackLeaseRef = ValueTypeOf<typeof RackLeaseRefType>;
+/**
+ * POST /rack/lease request — long-poll for the next claimable task
+ * matching any of the agent's tiers. `bootId` declares WHICH process
+ * lifetime is asking: under `requireStartApproval` only the approved boot
+ * receives grants, checked against the request itself so no heartbeat
+ * ordering can leak a lease to an unapproved restart (D12, #90).
+ */
+export declare const RackLeaseRequestType: StructType<{
+    readonly tiers: ArrayType<StringType>;
+    readonly bootId: StringType;
+}>;
+export type RackLeaseRequest = ValueTypeOf<typeof RackLeaseRequestType>;
+/**
+ * A granted lease. `eventJson` carries the lease's event (e3-cloud-core's
+ * `RackLeaseEvent`, v2 since elaraai/e3-cloud#214) as JSON: the runner
+ * containers' v2 event (#205) the guest runs, the runtime version, and the
+ * lease's closure. The agent must extend visibility before
+ * `visibilityDeadline` or the lease becomes reclaimable.
+ */
+export declare const RackLeaseGrantType: StructType<{
+    readonly repo: StringType;
+    readonly workspace: StringType;
+    readonly leaseId: StringType;
+    readonly tier: StringType;
+    /** Compute size tag -> the agent's VM shape (serverless when unset upstream). */
+    readonly computeSize: StringType;
+    readonly eventJson: StringType;
+    readonly visibilityDeadline: DateTimeType;
+}>;
+export type RackLeaseGrant = ValueTypeOf<typeof RackLeaseGrantType>;
+/**
+ * POST /rack/heartbeat request — liveness + running work, every ~15 s.
+ * `bootId` (D12, #90) is a fresh uuid per agent process lifetime, the unit
+ * of start-approval quarantine. `cacheBytes` (RCK-D1, elaraai/e3-cloud#214)
+ * is what the agent's object cache holds after its last collection, which
+ * it runs after every lease and every 10 minutes; the cloud keeps none of
+ * it yet (a registration is a stored value: its shape grows only with a
+ * migration).
+ *
+ * The machine protocol evolves IN PLACE (pre-GA): a deployment and its
+ * racks update together. #80's drift check is the planned skew answer —
+ * a too-old binary gets "update required", never shape negotiation.
+ */
+export declare const RackHeartbeatRequestType: StructType<{
+    readonly healthy: BooleanType;
+    readonly freeCapacity: IntegerType;
+    readonly runningLeases: ArrayType<StructType<{
+        readonly repo: StringType;
+        readonly leaseId: StringType;
+    }>>;
+    readonly agentVersion: StringType;
+    readonly bootId: StringType;
+    readonly cacheBytes: IntegerType;
+}>;
+export type RackHeartbeatRequest = ValueTypeOf<typeof RackHeartbeatRequestType>;
+/**
+ * POST /rack/heartbeat response —
+ * - `stop`: leases the agent should stop working on (cancelled by an
+ *   operator, or superseded because the runner fell back to cloud).
+ *   This remains a backstop; /rack/lease/watch delivers prompt cancellation.
+ * - `rotatedToken` (D12, #90): a successor rack token (shown once, hashed
+ *   at rest server-side). The agent persists it and switches; the old
+ *   token stays valid until the successor's first use, then for a short
+ *   grace window — a lost response never strands the agent, and a leaked
+ *   token ages out with rotation.
+ * - `pendingApproval` (D12, #90): this boot is quarantined awaiting the
+ *   fleet-table Approve (`requireStartApproval`); the agent keeps
+ *   heartbeating but receives no leases.
+ */
+export declare const RackHeartbeatResponseType: StructType<{
+    readonly stop: ArrayType<StructType<{
+        readonly repo: StringType;
+        readonly leaseId: StringType;
+    }>>;
+    readonly rotatedToken: OptionType<StringType>;
+    readonly pendingApproval: BooleanType;
+}>;
+export type RackHeartbeatResponse = ValueTypeOf<typeof RackHeartbeatResponseType>;
+/** The most running leases one cancellation watch may name. */
+export declare const RACK_WATCH_MAX_LEASES = 128;
+/** POST /rack/lease/watch: hold a read-only request until named work must stop. */
+export declare const RackWatchRequestType: StructType<{
+    readonly runningLeases: ArrayType<StructType<{
+        readonly repo: StringType;
+        readonly leaseId: StringType;
+    }>>;
+}>;
+export type RackWatchRequest = ValueTypeOf<typeof RackWatchRequestType>;
+/** Cancellation notifications contain only references supplied by this caller. */
+export declare const RackWatchResponseType: StructType<{
+    readonly stop: ArrayType<StructType<{
+        readonly repo: StringType;
+        readonly leaseId: StringType;
+    }>>;
+}>;
+export type RackWatchResponse = ValueTypeOf<typeof RackWatchResponseType>;
+/** POST /rack/lease/extend request — refresh a running lease's visibility. */
+export declare const RackExtendRequestType: StructType<{
+    readonly repo: StringType;
+    readonly leaseId: StringType;
+}>;
+export type RackExtendRequest = ValueTypeOf<typeof RackExtendRequestType>;
+/**
+ * POST /rack/complete request — terminal result for a lease. `resultJson`
+ * carries the lease's result (e3-cloud-core's `RackLeaseResult`) as JSON.
+ *
+ * Output delivery (#74): a large output was already PUT via the presigned
+ * target — `outputUploadId` makes the server verify-and-commit it (SHA-256
+ * checked server-side; a tampered upload rejects the completion). A small
+ * (≤4 KB) output rides `inlineOutput` instead and the server writes it
+ * through the normal object-store normalization, computing the hash itself.
+ */
+export declare const RackCompleteRequestType: StructType<{
+    readonly repo: StringType;
+    readonly leaseId: StringType;
+    readonly resultJson: StringType;
+    readonly outputUploadId: OptionType<StringType>;
+    readonly inlineOutput: OptionType<BlobType>;
+}>;
+export type RackCompleteRequest = ValueTypeOf<typeof RackCompleteRequestType>;
+/** An object an agent declares or commits: its hash and size. */
+export declare const RackObjectSizeType: StructType<{
+    readonly hash: StringType;
+    readonly size: IntegerType;
+}>;
+export type RackObjectSize = ValueTypeOf<typeof RackObjectSizeType>;
+/** An object an agent PUT through a write target, and the version its PUT made. */
+export declare const RackObjectCommitType: StructType<{
+    readonly hash: StringType;
+    readonly size: IntegerType;
+    readonly version: StringType;
+}>;
+export type RackObjectCommit = ValueTypeOf<typeof RackObjectCommitType>;
+/**
+ * POST /rack/storage request — storage descriptors for a claimed lease
+ * (#74, #214):
+ * - `need` lists the object hashes the agent's content-addressed cache
+ *   lacks; every one must be in the lease's closure (server-validated —
+ *   review F5);
+ * - `output` declares a whole output for a staged PUT target (#210);
+ * - `outputs` declares objects the lease's guest wrote, each for a PUT target
+ *   at its content address bound to its SHA-256 (#214);
+ * - `commits` names objects the agent PUT through those targets, and the
+ *   versions its PUTs made, for the cloud to take in.
+ */
+export declare const RackStorageRequestType: StructType<{
+    readonly repo: StringType;
+    readonly leaseId: StringType;
+    readonly need: ArrayType<StringType>;
+    readonly output: OptionType<StructType<{
+        readonly hash: StringType;
+        readonly size: IntegerType;
+    }>>;
+    /** #94 Slice B: environment hash to resolve published layers for. Must
+     *  equal the lease's own declared environment (F5). */
+    readonly envManifest: OptionType<StringType>;
+    readonly outputs: ArrayType<StructType<{
+        readonly hash: StringType;
+        readonly size: IntegerType;
+    }>>;
+    readonly commits: ArrayType<StructType<{
+        readonly hash: StringType;
+        readonly size: IntegerType;
+        readonly version: StringType;
+    }>>;
+}>;
+export type RackStorageRequest = ValueTypeOf<typeof RackStorageRequestType>;
+/**
+ * One object descriptor: small (≤4 KB) objects live in DynamoDB and are
+ * carried inline; large objects get a presigned S3 GET.
+ */
+export declare const RackObjectDescriptorType: VariantType<{
+    readonly inline: StructType<{
+        readonly hash: StringType;
+        readonly data: BlobType;
+    }>;
+    readonly url: StructType<{
+        readonly hash: StringType;
+        readonly url: StringType;
+    }>;
+}>;
+export type RackObjectDescriptor = ValueTypeOf<typeof RackObjectDescriptorType>;
+/** One published env layer: content digest + presigned GET (#94). */
+export declare const RackEnvLayerType: StructType<{
+    readonly digest: StringType;
+    readonly url: StringType;
+    readonly sizeBytes: IntegerType;
+}>;
+/**
+ * Where an object a lease's guest wrote goes (#214): nowhere, when the store
+ * holds it already (`held`), or a PUT at its content address, whose headers
+ * the agent sends as given: they are signed into its URL.
+ */
+export declare const RackWriteTargetType: VariantType<{
+    readonly held: NullType;
+    readonly put: StructType<{
+        readonly url: StringType;
+        readonly headers: DictType<StringType, StringType>;
+    }>;
+}>;
+export type RackWriteTarget = ValueTypeOf<typeof RackWriteTargetType>;
+/** POST /rack/storage response. */
+export declare const RackStorageResponseType: StructType<{
+    readonly objects: ArrayType<VariantType<{
+        readonly inline: StructType<{
+            readonly hash: StringType;
+            readonly data: BlobType;
+        }>;
+        readonly url: StructType<{
+            readonly hash: StringType;
+            readonly url: StringType;
+        }>;
+    }>>;
+    readonly output: OptionType<StructType<{
+        readonly url: StringType;
+        readonly uploadId: StringType;
+    }>>;
+    /** #94 Slice B: the env's published manifest (small JSON, inline) plus a
+     *  presigned GET per delta layer — set iff `envManifest` was requested
+     *  and the env is published. */
+    readonly env: OptionType<StructType<{
+        readonly manifestJson: StringType;
+        readonly layers: ArrayType<StructType<{
+            readonly digest: StringType;
+            readonly url: StringType;
+            readonly sizeBytes: IntegerType;
+        }>>;
+    }>>;
+    /** Each declared output's target, in the order declared */
+    readonly targets: ArrayType<StructType<{
+        readonly hash: StringType;
+        readonly target: VariantType<{
+            readonly held: NullType;
+            readonly put: StructType<{
+                readonly url: StringType;
+                readonly headers: DictType<StringType, StringType>;
+            }>;
+        }>;
+    }>>;
+    /** Whether each commit was taken in, in the order named */
+    readonly committed: ArrayType<StructType<{
+        readonly hash: StringType;
+        readonly committed: BooleanType;
+    }>>;
+}>;
+export type RackStorageResponse = ValueTypeOf<typeof RackStorageResponseType>;
+export type RackEnvLayer = ValueTypeOf<typeof RackEnvLayerType>;
+/** One streamed log chunk (agent batches ≥1 s or ≥32 KB per POST). */
+export declare const RackLogChunkType: StructType<{
+    readonly stream: VariantType<{
+        readonly stdout: NullType;
+        readonly stderr: NullType;
+    }>;
+    readonly data: StringType;
+}>;
+export type RackLogChunk = ValueTypeOf<typeof RackLogChunkType>;
+/** POST /rack/logs request — batched stdout/stderr for a claimed lease. */
+export declare const RackLogsRequestType: StructType<{
+    readonly repo: StringType;
+    readonly leaseId: StringType;
+    readonly chunks: ArrayType<StructType<{
+        readonly stream: VariantType<{
+            readonly stdout: NullType;
+            readonly stderr: NullType;
+        }>;
+        readonly data: StringType;
+    }>>;
+}>;
+export type RackLogsRequest = ValueTypeOf<typeof RackLogsRequestType>;
+/**
+ * POST /rack/complete response — accepted-and-discarded semantics:
+ * - recorded: the result landed; the runner will pick it up
+ * - idempotent: the lease was already completed (retry) — all good
+ * - discarded: the lease was superseded/cancelled/reclaimed; the agent
+ *   drops local state and moves on (never an error)
+ */
+export declare const RackCompleteResponseType: StructType<{
+    readonly disposition: VariantType<{
+        readonly recorded: NullType;
+        readonly idempotent: NullType;
+        readonly discarded: NullType;
+    }>;
+}>;
+export type RackCompleteResponse = ValueTypeOf<typeof RackCompleteResponseType>;
+/**
+ * The oldest rack agent the cloud leases work to (elaraai/e3-cloud#214): one
+ * whose guest runs e3-core's own execution over its lease's staged closure,
+ * and reads the v2 lease event, which names the runtime its work was built
+ * with (#189). It subsumes the environment (0.3.0) and function (0.4.0)
+ * capability gates. An older agent is refused at lease time and told to
+ * upgrade; its work runs in the cloud.
+ */
+export declare const LEASE_MIN_AGENT = "0.5.0";
+/**
+ * Whether an agent version is at least another, under dotted-numeric semver:
+ * pre-release and build suffixes are ignored, only the numeric core compared.
+ *
+ * @param version - The agent's version, as its registration reports it
+ * @param min - The least version
+ * @returns Whether `version` is `min` or later
+ */
+export declare function agentVersionAtLeast(version: string, min: string): boolean;
+//# sourceMappingURL=rack-wire.d.ts.map

package/dist/src/protocol/rack-wire.d.ts.map

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

package/dist/src/protocol/rack-wire.js

@@ -0,0 +1,262 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+/**
+ * Rack machine-protocol wire types (epic #67 design §9) — the BEAST2 bodies
+ * exchanged between a rack agent and the deployment's /api/rack endpoints.
+ * Shared by the server routes (e3-cloud-core), the HTTP client, and the
+ * rack agent, so the shapes live here beside the delegation types.
+ */
+import { ArrayType, BlobType, BooleanType, DateTimeType, DictType, IntegerType, NullType, OptionType, StringType, StructType, VariantType, } from '@elaraai/east';
+/**
+ * What an enrolling agent declares about its host: the operator-facing
+ * label, the runner tiers it has rootfs images for (node | py |
+ * py-datascience | c | full — the #57 vocabulary), its max concurrent
+ * microVMs, and the agent build it runs.
+ */
+export const RackHostInfoType = StructType({
+    label: StringType,
+    tiers: ArrayType(StringType),
+    capacity: IntegerType,
+    agentVersion: StringType,
+});
+/**
+ * POST /rack/enroll request — exchanges a single-use enrollment token
+ * (minted by an admin in the UI) for a long-lived rack credential.
+ */
+export const RackEnrollRequestType = StructType({
+    enrollmentToken: StringType,
+    hostInfo: RackHostInfoType,
+});
+/**
+ * POST /rack/enroll response — the generated rack identity and its
+ * bearer credential. The token is shown exactly once and stored hashed
+ * at rest server-side; the agent persists it mode 0600.
+ */
+export const RackEnrollResponseType = StructType({
+    rackId: StringType,
+    rackToken: StringType,
+});
+/** A (repo, leaseId) reference — leases are partitioned per repo. */
+export const RackLeaseRefType = StructType({
+    repo: StringType,
+    leaseId: StringType,
+});
+/**
+ * POST /rack/lease request — long-poll for the next claimable task
+ * matching any of the agent's tiers. `bootId` declares WHICH process
+ * lifetime is asking: under `requireStartApproval` only the approved boot
+ * receives grants, checked against the request itself so no heartbeat
+ * ordering can leak a lease to an unapproved restart (D12, #90).
+ */
+export const RackLeaseRequestType = StructType({
+    tiers: ArrayType(StringType),
+    bootId: StringType,
+});
+/**
+ * A granted lease. `eventJson` carries the lease's event (e3-cloud-core's
+ * `RackLeaseEvent`, v2 since elaraai/e3-cloud#214) as JSON: the runner
+ * containers' v2 event (#205) the guest runs, the runtime version, and the
+ * lease's closure. The agent must extend visibility before
+ * `visibilityDeadline` or the lease becomes reclaimable.
+ */
+export const RackLeaseGrantType = StructType({
+    repo: StringType,
+    workspace: StringType,
+    leaseId: StringType,
+    tier: StringType,
+    /** Compute size tag -> the agent's VM shape (serverless when unset upstream). */
+    computeSize: StringType,
+    eventJson: StringType,
+    visibilityDeadline: DateTimeType,
+});
+/**
+ * POST /rack/heartbeat request — liveness + running work, every ~15 s.
+ * `bootId` (D12, #90) is a fresh uuid per agent process lifetime, the unit
+ * of start-approval quarantine. `cacheBytes` (RCK-D1, elaraai/e3-cloud#214)
+ * is what the agent's object cache holds after its last collection, which
+ * it runs after every lease and every 10 minutes; the cloud keeps none of
+ * it yet (a registration is a stored value: its shape grows only with a
+ * migration).
+ *
+ * The machine protocol evolves IN PLACE (pre-GA): a deployment and its
+ * racks update together. #80's drift check is the planned skew answer —
+ * a too-old binary gets "update required", never shape negotiation.
+ */
+export const RackHeartbeatRequestType = StructType({
+    healthy: BooleanType,
+    freeCapacity: IntegerType,
+    runningLeases: ArrayType(RackLeaseRefType),
+    agentVersion: StringType,
+    bootId: StringType,
+    cacheBytes: IntegerType,
+});
+/**
+ * POST /rack/heartbeat response —
+ * - `stop`: leases the agent should stop working on (cancelled by an
+ *   operator, or superseded because the runner fell back to cloud).
+ *   This remains a backstop; /rack/lease/watch delivers prompt cancellation.
+ * - `rotatedToken` (D12, #90): a successor rack token (shown once, hashed
+ *   at rest server-side). The agent persists it and switches; the old
+ *   token stays valid until the successor's first use, then for a short
+ *   grace window — a lost response never strands the agent, and a leaked
+ *   token ages out with rotation.
+ * - `pendingApproval` (D12, #90): this boot is quarantined awaiting the
+ *   fleet-table Approve (`requireStartApproval`); the agent keeps
+ *   heartbeating but receives no leases.
+ */
+export const RackHeartbeatResponseType = StructType({
+    stop: ArrayType(RackLeaseRefType),
+    rotatedToken: OptionType(StringType),
+    pendingApproval: BooleanType,
+});
+/** The most running leases one cancellation watch may name. */
+export const RACK_WATCH_MAX_LEASES = 128;
+/** POST /rack/lease/watch: hold a read-only request until named work must stop. */
+export const RackWatchRequestType = StructType({
+    runningLeases: ArrayType(RackLeaseRefType),
+});
+/** Cancellation notifications contain only references supplied by this caller. */
+export const RackWatchResponseType = StructType({
+    stop: ArrayType(RackLeaseRefType),
+});
+/** POST /rack/lease/extend request — refresh a running lease's visibility. */
+export const RackExtendRequestType = StructType({
+    repo: StringType,
+    leaseId: StringType,
+});
+/**
+ * POST /rack/complete request — terminal result for a lease. `resultJson`
+ * carries the lease's result (e3-cloud-core's `RackLeaseResult`) as JSON.
+ *
+ * Output delivery (#74): a large output was already PUT via the presigned
+ * target — `outputUploadId` makes the server verify-and-commit it (SHA-256
+ * checked server-side; a tampered upload rejects the completion). A small
+ * (≤4 KB) output rides `inlineOutput` instead and the server writes it
+ * through the normal object-store normalization, computing the hash itself.
+ */
+export const RackCompleteRequestType = StructType({
+    repo: StringType,
+    leaseId: StringType,
+    resultJson: StringType,
+    outputUploadId: OptionType(StringType),
+    inlineOutput: OptionType(BlobType),
+});
+/** An object an agent declares or commits: its hash and size. */
+export const RackObjectSizeType = StructType({ hash: StringType, size: IntegerType });
+/** An object an agent PUT through a write target, and the version its PUT made. */
+export const RackObjectCommitType = StructType({ hash: StringType, size: IntegerType, version: StringType });
+/**
+ * POST /rack/storage request — storage descriptors for a claimed lease
+ * (#74, #214):
+ * - `need` lists the object hashes the agent's content-addressed cache
+ *   lacks; every one must be in the lease's closure (server-validated —
+ *   review F5);
+ * - `output` declares a whole output for a staged PUT target (#210);
+ * - `outputs` declares objects the lease's guest wrote, each for a PUT target
+ *   at its content address bound to its SHA-256 (#214);
+ * - `commits` names objects the agent PUT through those targets, and the
+ *   versions its PUTs made, for the cloud to take in.
+ */
+export const RackStorageRequestType = StructType({
+    repo: StringType,
+    leaseId: StringType,
+    need: ArrayType(StringType),
+    output: OptionType(RackObjectSizeType),
+    /** #94 Slice B: environment hash to resolve published layers for. Must
+     *  equal the lease's own declared environment (F5). */
+    envManifest: OptionType(StringType),
+    outputs: ArrayType(RackObjectSizeType),
+    commits: ArrayType(RackObjectCommitType),
+});
+/**
+ * One object descriptor: small (≤4 KB) objects live in DynamoDB and are
+ * carried inline; large objects get a presigned S3 GET.
+ */
+export const RackObjectDescriptorType = VariantType({
+    inline: StructType({ hash: StringType, data: BlobType }),
+    url: StructType({ hash: StringType, url: StringType }),
+});
+/** One published env layer: content digest + presigned GET (#94). */
+export const RackEnvLayerType = StructType({
+    digest: StringType,
+    url: StringType,
+    sizeBytes: IntegerType,
+});
+/**
+ * Where an object a lease's guest wrote goes (#214): nowhere, when the store
+ * holds it already (`held`), or a PUT at its content address, whose headers
+ * the agent sends as given: they are signed into its URL.
+ */
+export const RackWriteTargetType = VariantType({
+    held: NullType,
+    put: StructType({ url: StringType, headers: DictType(StringType, StringType) }),
+});
+/** POST /rack/storage response. */
+export const RackStorageResponseType = StructType({
+    objects: ArrayType(RackObjectDescriptorType),
+    output: OptionType(StructType({ url: StringType, uploadId: StringType })),
+    /** #94 Slice B: the env's published manifest (small JSON, inline) plus a
+     *  presigned GET per delta layer — set iff `envManifest` was requested
+     *  and the env is published. */
+    env: OptionType(StructType({ manifestJson: StringType, layers: ArrayType(RackEnvLayerType) })),
+    /** Each declared output's target, in the order declared */
+    targets: ArrayType(StructType({ hash: StringType, target: RackWriteTargetType })),
+    /** Whether each commit was taken in, in the order named */
+    committed: ArrayType(StructType({ hash: StringType, committed: BooleanType })),
+});
+/** One streamed log chunk (agent batches ≥1 s or ≥32 KB per POST). */
+export const RackLogChunkType = StructType({
+    stream: VariantType({ stdout: NullType, stderr: NullType }),
+    data: StringType,
+});
+/** POST /rack/logs request — batched stdout/stderr for a claimed lease. */
+export const RackLogsRequestType = StructType({
+    repo: StringType,
+    leaseId: StringType,
+    chunks: ArrayType(RackLogChunkType),
+});
+/**
+ * POST /rack/complete response — accepted-and-discarded semantics:
+ * - recorded: the result landed; the runner will pick it up
+ * - idempotent: the lease was already completed (retry) — all good
+ * - discarded: the lease was superseded/cancelled/reclaimed; the agent
+ *   drops local state and moves on (never an error)
+ */
+export const RackCompleteResponseType = StructType({
+    disposition: VariantType({
+        recorded: NullType,
+        idempotent: NullType,
+        discarded: NullType,
+    }),
+});
+/**
+ * The oldest rack agent the cloud leases work to (elaraai/e3-cloud#214): one
+ * whose guest runs e3-core's own execution over its lease's staged closure,
+ * and reads the v2 lease event, which names the runtime its work was built
+ * with (#189). It subsumes the environment (0.3.0) and function (0.4.0)
+ * capability gates. An older agent is refused at lease time and told to
+ * upgrade; its work runs in the cloud.
+ */
+export const LEASE_MIN_AGENT = '0.5.0';
+/**
+ * Whether an agent version is at least another, under dotted-numeric semver:
+ * pre-release and build suffixes are ignored, only the numeric core compared.
+ *
+ * @param version - The agent's version, as its registration reports it
+ * @param min - The least version
+ * @returns Whether `version` is `min` or later
+ */
+export function agentVersionAtLeast(version, min) {
+    const core = (v) => (v.split(/[-+]/)[0] ?? '').split('.').map((n) => parseInt(n, 10) || 0);
+    const a = core(version);
+    const b = core(min);
+    for (let i = 0; i < Math.max(a.length, b.length); i++) {
+        const d = (a[i] ?? 0) - (b[i] ?? 0);
+        if (d !== 0)
+            return d > 0;
+    }
+    return true; // equal
+}
+//# sourceMappingURL=rack-wire.js.map

package/dist/src/protocol/rack-wire.js.map

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

package/dist/src/protocol/rack-wire.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=rack-wire.spec.d.ts.map

package/dist/src/protocol/rack-wire.spec.d.ts.map

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

package/dist/src/protocol/rack-wire.spec.js

@@ -0,0 +1,14 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Licensed under BSL 1.1. See LICENSE for details.
+ */
+import { it } from 'node:test';
+import assert from 'node:assert/strict';
+import { wireSamples } from './wire-samples.js';
+import { wireGolden } from './wire-golden.js';
+for (const sample of wireSamples) {
+    it(`encodes ${sample.name} identically to its e3-cloud protocol fixture`, () => {
+        assert.equal(Buffer.from(sample.encode()).toString('hex'), wireGolden[sample.name]);
+    });
+}
+//# sourceMappingURL=rack-wire.spec.js.map

package/dist/src/protocol/rack-wire.spec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rack-wire.spec.js","sourceRoot":"","sources":["../../../src/protocol/rack-wire.spec.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,EAAE,EAAE,MAAM,WAAW,CAAC;AAC/B,OAAO,MAAM,MAAM,oBAAoB,CAAC;AACxC,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAChD,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAE9C,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;IACjC,EAAE,CAAC,WAAW,MAAM,CAAC,IAAI,+CAA+C,EAAE,GAAG,EAAE;QAC7E,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;IACtF,CAAC,CAAC,CAAC;AACL,CAAC"}