@bedrock-rbx/ocale 0.1.0-beta.2 → 0.1.0-beta.20

package/dist/polling-helpers-Cb4j4cq7.mjs

@@ -0,0 +1,787 @@
+import { n as NetworkError, r as ApiError } from "./rate-limit-Co9i28qi.mjs";
+import { c as findErrorCode, n as IDEMPOTENT_METHOD_DEFAULTS, r as TRANSIENT_TRANSPORT_CODES, t as CREATE_METHOD_DEFAULTS } from "./retry-CbHBw60o.mjs";
+import { n as PollAbortedError, t as PollTimeoutError } from "./poll-timeout-C0nmJzOd.mjs";
+import { t as ValidationError } from "./validation-9oU6qNNQ.mjs";
+import { a as isDateTimeString, i as isRecord, n as okRequest } from "./resource-client-lE7Tg3BK.mjs";
+//#region src/domains/cloud-v2/luau-execution-task-logs/builders.ts
+/**
+* Builds a `GET` request for the Open Cloud "list Luau execution session
+* task logs" endpoint. The endpoint requires the maximal x-aep-resource
+* path shape (universe, place, version, session, task), so the supplied
+* ref must include `versionId` and `sessionId`; refs extracted from the
+* narrower path formats are rejected with a {@link ValidationError}.
+*
+* The `view` query parameter is hard-coded to `STRUCTURED` so callers
+* always receive typed structured messages. No public `view` parameter
+* is exposed.
+*
+* @param parameters - Task ref, and optional `pageSize` and `pageToken`
+*   pagination controls.
+* @returns A success result wrapping the request, or a
+*   {@link ValidationError} when the ref is missing `versionId` or
+*   `sessionId`.
+*/
+function buildListLogsRequest(parameters) {
+	const { pageSize, pageToken, ref } = parameters;
+	const { placeId, sessionId, taskId, universeId, versionId } = ref;
+	if (versionId === void 0) return {
+		err: new ValidationError("Task ref is missing versionId; cannot list logs", { code: "incomplete_ref" }),
+		success: false
+	};
+	if (sessionId === void 0) return {
+		err: new ValidationError("Task ref is missing sessionId; cannot list logs", { code: "incomplete_ref" }),
+		success: false
+	};
+	return {
+		data: {
+			method: "GET",
+			url: `${`/cloud/v2/universes/${universeId}/places/${placeId}/versions/${versionId}/luau-execution-sessions/${sessionId}/tasks/${taskId}/logs`}?${buildQuery(pageSize, pageToken).toString()}`
+		},
+		success: true
+	};
+}
+function buildQuery(pageSize, pageToken) {
+	const query = new URLSearchParams({ view: "STRUCTURED" });
+	if (pageSize !== void 0) query.append("maxPageSize", String(pageSize));
+	if (pageToken !== void 0) query.append("pageToken", pageToken);
+	return query;
+}
+/**
+* Per-second request ceiling for listing Luau execution task logs,
+* sourced from `x-roblox-rate-limits.perApiKeyOwner` on the
+* `Cloud_ListLuauExecutionSessionTaskLogs` operation (45 requests per
+* minute per API key owner).
+*/
+const LIST_LOGS_OPERATION_LIMIT = Object.freeze({
+	maxPerSecond: 45 / 60,
+	operationKey: "luau-execution-task-logs.list"
+});
+/**
+* Scopes required to list Luau execution task logs, sourced from
+* `x-roblox-scopes` on the list-logs operation in the vendored OpenAPI
+* schema. Surfaced via the `requiredScopes` field of the per-method
+* spec so a 401 or 403 ApiError is upgraded to a `PermissionError`
+* naming the missing scope. Only `:read` is required as the
+* minimum-privilege scope for this read-only operation.
+*/
+const LIST_LOGS_REQUIRED_SCOPES = Object.freeze(["universe.place.luau-execution-session:read"]);
+//#endregion
+//#region src/domains/cloud-v2/luau-execution-task-logs/parsers.ts
+const MALFORMED_LOGS_MESSAGE = "Malformed list-luau-execution-task-logs response";
+/**
+* Parses a successful Open Cloud list-luau-execution-task-logs response
+* body into the public {@link LogPage} shape. Chunks are flattened into
+* a single ordered array of {@link LogMessage} values. The
+* `MESSAGE_TYPE_UNSPECIFIED` sentinel is rejected.
+*
+* @param response - The full {@link HttpResponse} from the Open Cloud API.
+* @returns A success result wrapping the parsed {@link LogPage}, or an
+*   {@link ApiError} when the body does not match a supported shape.
+*/
+function parseListLogsResponse(response) {
+	const { body, status: statusCode } = response;
+	if (!isRecord(body)) return malformed$1(statusCode);
+	const rawChunks = body["luauExecutionSessionTaskLogs"] ?? void 0;
+	if (!isOptionalLogChunks(rawChunks)) return malformed$1(statusCode);
+	const rawToken = body["nextPageToken"] ?? void 0;
+	if (rawToken !== void 0 && typeof rawToken !== "string") return malformed$1(statusCode);
+	const messages = [];
+	for (const chunk of rawChunks ?? []) for (const wireMessage of chunk.structuredMessages ?? []) messages.push({
+		createTime: wireMessage.createTime,
+		message: wireMessage.message,
+		messageType: wireMessage.messageType
+	});
+	return {
+		data: {
+			messages,
+			nextPageToken: rawToken
+		},
+		success: true
+	};
+}
+function isAcceptedMessageType(value) {
+	return value === "OUTPUT" || value === "INFO" || value === "WARNING" || value === "ERROR";
+}
+function isLogMessageWire(value) {
+	return isRecord(value) && typeof value["createTime"] === "string" && typeof value["message"] === "string" && isAcceptedMessageType(value["messageType"]);
+}
+function isOptionalStructuredMessages(value) {
+	return value === void 0 || Array.isArray(value) && value.every((item) => isLogMessageWire(item));
+}
+function isLogChunkWire(value) {
+	return isRecord(value) && isOptionalStructuredMessages(value["structuredMessages"]);
+}
+function isOptionalLogChunks(value) {
+	return value === void 0 || Array.isArray(value) && value.every((item) => isLogChunkWire(item));
+}
+function malformed$1(statusCode) {
+	return {
+		err: new ApiError(MALFORMED_LOGS_MESSAGE, { statusCode }),
+		success: false
+	};
+}
+//#endregion
+//#region src/domains/cloud-v2/luau-execution-task-logs/specs.ts
+function makeSpec$1(spec) {
+	return Object.freeze(spec);
+}
+/**
+* Per-method dispatch spec for listing the structured log messages
+* produced by a Luau execution task. Frozen at module scope so both
+* the top-level `LuauExecutionClient` and the `luauExecution` Operation
+* Group on `PlacesClient` share the same instance reference.
+*/
+const LIST_LOGS_SPEC = makeSpec$1({
+	buildRequest: buildListLogsRequest,
+	methodDefaults: IDEMPOTENT_METHOD_DEFAULTS,
+	methodKind: "idempotent",
+	operationLimit: LIST_LOGS_OPERATION_LIMIT,
+	parse: parseListLogsResponse,
+	requiredScopes: LIST_LOGS_REQUIRED_SCOPES
+});
+//#endregion
+//#region src/domains/cloud-v2/luau-execution-tasks/builders.ts
+const JSON_HEADERS = { "content-type": "application/json" };
+/**
+* Builds a `POST` request for the Open Cloud "create Luau execution
+* session task" endpoint, targeting the place's head version. Serializes
+* `timeoutSeconds` into the wire's duration string format (`"<n>s"`)
+* when supplied.
+*
+* @param parameters - Universe and place identifiers, the script body,
+*   and an optional `timeoutSeconds`.
+* @returns A pure {@link HttpRequest} describing the submit call.
+*/
+function buildSubmitAtHeadRequest(parameters) {
+	const { placeId, universeId } = parameters;
+	return {
+		body: buildSubmitBody(parameters),
+		headers: JSON_HEADERS,
+		method: "POST",
+		url: `/cloud/v2/universes/${universeId}/places/${placeId}/luau-execution-session-tasks`
+	};
+}
+/**
+* Builds a `POST` request for the Open Cloud "create Luau execution
+* session task" endpoint, targeting a specific place version. Differs
+* from {@link buildSubmitAtHeadRequest} only in URL shape: the path
+* includes the `versions/{versionId}` segment so the script runs
+* against that exact place version instead of the live head.
+*
+* @param parameters - Universe, place, and version identifiers, the
+*   script body, and an optional `timeoutSeconds`.
+* @returns A pure {@link HttpRequest} describing the submit call.
+*/
+function buildSubmitAtVersionRequest(parameters) {
+	const { placeId, universeId, versionId } = parameters;
+	return {
+		body: buildSubmitBody(parameters),
+		headers: JSON_HEADERS,
+		method: "POST",
+		url: `/cloud/v2/universes/${universeId}/places/${placeId}/versions/${versionId}/luau-execution-session-tasks`
+	};
+}
+/**
+* Builds a `GET` request for the Open Cloud "read Luau execution session
+* task" endpoint. The endpoint accepts only the maximal x-aep-resource
+* path shape (universe, place, version, session, task), so the supplied
+* ref must include `versionId` and `sessionId`; refs extracted from the
+* narrower path formats are rejected with a {@link ValidationError}.
+*
+* @param parameters - Task ref and optional view selector. When `view`
+*   is omitted, no `?view=` query is sent and the server applies its
+*   own default (`BASIC`).
+* @returns A success result wrapping the request, or a
+*   {@link ValidationError} when the ref is missing `versionId` or
+*   `sessionId`.
+*/
+function buildGetRequest(parameters) {
+	const { ref, view } = parameters;
+	const { placeId, sessionId, taskId, universeId, versionId } = ref;
+	if (versionId === void 0) return {
+		err: new ValidationError("Task ref is missing versionId; cannot GET", { code: "incomplete_ref" }),
+		success: false
+	};
+	if (sessionId === void 0) return {
+		err: new ValidationError("Task ref is missing sessionId; cannot GET", { code: "incomplete_ref" }),
+		success: false
+	};
+	const base = `/cloud/v2/universes/${universeId}/places/${placeId}/versions/${versionId}/luau-execution-sessions/${sessionId}/tasks/${taskId}`;
+	return {
+		data: {
+			method: "GET",
+			url: view === void 0 ? base : `${base}?view=${view}`
+		},
+		success: true
+	};
+}
+function buildSubmitBody(parameters) {
+	const { binaryInput, enableBinaryOutput: shouldEnableBinaryOutput, script, timeoutSeconds } = parameters;
+	const body = { script };
+	if (timeoutSeconds !== void 0) body["timeout"] = `${timeoutSeconds}s`;
+	if (binaryInput !== void 0) body["binaryInput"] = binaryInput;
+	if (shouldEnableBinaryOutput !== void 0) body["enableBinaryOutput"] = shouldEnableBinaryOutput;
+	return body;
+}
+//#endregion
+//#region src/domains/cloud-v2/luau-execution-tasks/operations.ts
+const SUBMIT_PER_MINUTE = 40;
+const GET_PER_MINUTE = 200;
+const SECONDS_PER_MINUTE = 60;
+/**
+* Per-second request ceiling for submitting a Luau execution task,
+* sourced from `x-roblox-rate-limits.perApiKeyOwner` on the
+* `Cloud_CreateLuauExecutionSessionTask__Using_Universes` operation
+* (40 requests per minute per API key owner). The two URL shapes
+* (head and version) share this queue because Roblox attributes both
+* to the same per-minute quota.
+*/
+const SUBMIT_OPERATION_LIMIT = Object.freeze({
+	maxPerSecond: SUBMIT_PER_MINUTE / SECONDS_PER_MINUTE,
+	operationKey: "luau-execution-tasks.submit"
+});
+/**
+* Per-second request ceiling for fetching a Luau execution task,
+* sourced from `x-roblox-rate-limits.perApiKeyOwner` on the
+* `Cloud_GetLuauExecutionSessionTask` operation (200 requests per
+* minute per API key owner).
+*/
+const GET_OPERATION_LIMIT = Object.freeze({
+	maxPerSecond: GET_PER_MINUTE / SECONDS_PER_MINUTE,
+	operationKey: "luau-execution-tasks.get"
+});
+/**
+* Scopes required to submit a Luau execution task, sourced from
+* `x-roblox-scopes` on the create operation in the vendored OpenAPI
+* schema. Surfaced via the `requiredScopes` field of the per-method
+* spec so a 401 or 403 ApiError is upgraded to a `PermissionError`
+* naming the missing scope.
+*/
+const SUBMIT_REQUIRED_SCOPES = Object.freeze(["universe.place.luau-execution-session:write"]);
+/**
+* Scopes required to fetch a Luau execution task, sourced from
+* `x-roblox-scopes` on the get operation. The `:write` scope also
+* grants read in upstream auth, but we surface only `:read` here as
+* the minimum-privilege requirement for this method.
+*/
+const GET_REQUIRED_SCOPES = Object.freeze(["universe.place.luau-execution-session:read"]);
+//#endregion
+//#region src/domains/cloud-v2/luau-execution-tasks/parsers.ts
+const MALFORMED_TASK_MESSAGE = "Malformed luau-execution-session-task response";
+const PATH_PATTERN = /^universes\/(\d+)\/places\/(\d+)(?:\/versions\/(\d+))?(?:\/luau-execution-sessions\/([^/]+)\/tasks\/([^/]+)|\/luau-execution-session-tasks\/([^/]+))$/;
+/**
+* Parses a successful Open Cloud `LuauExecutionSessionTask` response
+* body into the public {@link LuauExecutionTask} discriminated union.
+* Handles every supported task state (in-progress, COMPLETE, FAILED)
+* across all four x-aep-resource path shapes the server returns.
+*
+* @param response - The full {@link HttpResponse} from the Open Cloud
+*   API.
+* @returns A success result wrapping the parsed task, or an
+*   {@link ApiError} when the body or path do not match a supported
+*   shape.
+*/
+function parseLuauExecutionTaskResponse(response) {
+	const { body, status: statusCode } = response;
+	if (!isLuauExecutionTaskWire(body)) return malformed(statusCode);
+	const ref = parseTaskRef(body.path);
+	if (ref === void 0) return malformed(statusCode);
+	const timeoutSeconds = parseTimeoutSeconds(body.timeout);
+	const createdAt = parseOptionalDate(body.createTime);
+	const updatedAt = parseOptionalDate(body.updateTime);
+	if (body.state === "COMPLETE") return parseCompleteTask({
+		body,
+		createdAt,
+		ref,
+		statusCode,
+		timeoutSeconds,
+		updatedAt
+	});
+	if (body.state === "FAILED") return parseFailedTask({
+		body,
+		createdAt,
+		ref,
+		statusCode,
+		timeoutSeconds,
+		updatedAt
+	});
+	return parseInProgressTask({
+		body,
+		createdAt,
+		ref,
+		state: body.state,
+		statusCode,
+		timeoutSeconds,
+		updatedAt
+	});
+}
+function isAcceptedWireState(state) {
+	return state === "QUEUED" || state === "PROCESSING" || state === "CANCELLED" || state === "COMPLETE" || state === "FAILED";
+}
+function isErrorWireCode(code) {
+	return code === "SCRIPT_ERROR" || code === "DEADLINE_EXCEEDED" || code === "OUTPUT_SIZE_LIMIT_EXCEEDED" || code === "INTERNAL_ERROR";
+}
+function isErrorWire(value) {
+	return isRecord(value) && isErrorWireCode(value["code"]) && typeof value["message"] === "string";
+}
+function isOptionalErrorWire(value) {
+	return value === void 0 || isErrorWire(value);
+}
+function isOutputWire(value) {
+	return isRecord(value) && Array.isArray(value["results"]);
+}
+function isOptionalOutputWire(value) {
+	return value === void 0 || isOutputWire(value);
+}
+function isOptionalString(value) {
+	return value === void 0 || typeof value === "string";
+}
+function isOptionalBoolean(value) {
+	return value === void 0 || typeof value === "boolean";
+}
+function isOptionalDateTimeString(value) {
+	return value === void 0 || isDateTimeString(value);
+}
+function isLuauExecutionTaskWire(body) {
+	return isRecord(body) && typeof body["path"] === "string" && isOptionalDateTimeString(body["createTime"]) && isOptionalDateTimeString(body["updateTime"]) && isAcceptedWireState(body["state"]) && typeof body["user"] === "string" && isOptionalOutputWire(body["output"]) && isOptionalErrorWire(body["error"]) && isOptionalDurationWire(body["timeout"]) && isOptionalString(body["binaryInput"]) && isOptionalBoolean(body["enableBinaryOutput"]) && isOptionalString(body["binaryOutputUri"]);
+}
+function parseOptionalDate(value) {
+	return value === void 0 ? void 0 : new Date(value);
+}
+const DURATION_PATTERN = /^(\d+)s$/;
+function isOptionalDurationWire(value) {
+	return value === void 0 || typeof value === "string" && DURATION_PATTERN.test(value);
+}
+function parseTimeoutSeconds(value) {
+	if (value === void 0) return;
+	const seconds = DURATION_PATTERN.exec(value)?.[1];
+	if (seconds === void 0) return;
+	return Number.parseInt(seconds, 10);
+}
+function malformed(statusCode) {
+	return {
+		err: new ApiError(MALFORMED_TASK_MESSAGE, { statusCode }),
+		success: false
+	};
+}
+function parseInProgressTask(args) {
+	const { body, createdAt, ref, state, timeoutSeconds, updatedAt } = args;
+	return {
+		data: {
+			binaryInput: body.binaryInput,
+			binaryOutputUri: body.binaryOutputUri,
+			createdAt,
+			enableBinaryOutput: body.enableBinaryOutput,
+			ref,
+			state,
+			timeoutSeconds,
+			updatedAt,
+			user: body.user
+		},
+		success: true
+	};
+}
+function parseCompleteTask(args) {
+	const { body, createdAt, ref, statusCode, timeoutSeconds, updatedAt } = args;
+	if (body.output === void 0) return malformed(statusCode);
+	return {
+		data: {
+			binaryInput: body.binaryInput,
+			binaryOutputUri: body.binaryOutputUri,
+			createdAt,
+			enableBinaryOutput: body.enableBinaryOutput,
+			output: { results: body.output.results },
+			ref,
+			state: "COMPLETE",
+			timeoutSeconds,
+			updatedAt,
+			user: body.user
+		},
+		success: true
+	};
+}
+function parseFailedTask(args) {
+	const { body, createdAt, ref, statusCode, timeoutSeconds, updatedAt } = args;
+	if (body.error === void 0) return malformed(statusCode);
+	return {
+		data: {
+			binaryInput: body.binaryInput,
+			binaryOutputUri: body.binaryOutputUri,
+			createdAt,
+			enableBinaryOutput: body.enableBinaryOutput,
+			error: {
+				code: body.error.code,
+				message: body.error.message
+			},
+			ref,
+			state: "FAILED",
+			timeoutSeconds,
+			updatedAt,
+			user: body.user
+		},
+		success: true
+	};
+}
+function parseTaskRef(path) {
+	const match = PATH_PATTERN.exec(path);
+	if (match === null) return;
+	const [, universeId, placeId, versionId, sessionId, sessionTaskId, plainTaskId] = match;
+	const taskId = sessionTaskId ?? plainTaskId;
+	if (universeId === void 0 || placeId === void 0 || taskId === void 0) return;
+	return {
+		placeId,
+		sessionId,
+		taskId,
+		universeId,
+		versionId
+	};
+}
+//#endregion
+//#region src/domains/cloud-v2/luau-execution-tasks/specs.ts
+function makeSpec(spec) {
+	return Object.freeze(spec);
+}
+/**
+* Per-method dispatch spec for submitting a Luau execution task at a
+* place's head version. Frozen at module scope so both the top-level
+* `LuauExecutionClient` and the `luauExecution` Operation Group on
+* `PlacesClient` share the same instance reference.
+*/
+const SUBMIT_HEAD_SPEC = makeSpec({
+	buildRequest: (parameters) => okRequest(buildSubmitAtHeadRequest(parameters)),
+	methodDefaults: CREATE_METHOD_DEFAULTS,
+	methodKind: "create",
+	operationLimit: SUBMIT_OPERATION_LIMIT,
+	parse: parseLuauExecutionTaskResponse,
+	requiredScopes: SUBMIT_REQUIRED_SCOPES
+});
+/**
+* Per-method dispatch spec for submitting a Luau execution task at a
+* specific place version. Shares the rate-limit queue and required
+* scope set with {@link SUBMIT_HEAD_SPEC} because Roblox attributes
+* both URL shapes to one per-minute quota.
+*/
+const SUBMIT_VERSION_SPEC = makeSpec({
+	buildRequest: (parameters) => okRequest(buildSubmitAtVersionRequest(parameters)),
+	methodDefaults: CREATE_METHOD_DEFAULTS,
+	methodKind: "create",
+	operationLimit: SUBMIT_OPERATION_LIMIT,
+	parse: parseLuauExecutionTaskResponse,
+	requiredScopes: SUBMIT_REQUIRED_SCOPES
+});
+/**
+* Per-method dispatch spec for fetching a Luau execution task. Uses
+* idempotent retry semantics (429 and 5xx both retried) so reads
+* recover transparently from transient server errors.
+*/
+const GET_SPEC = makeSpec({
+	buildRequest: buildGetRequest,
+	methodDefaults: IDEMPOTENT_METHOD_DEFAULTS,
+	methodKind: "idempotent",
+	operationLimit: GET_OPERATION_LIMIT,
+	parse: parseLuauExecutionTaskResponse,
+	requiredScopes: GET_REQUIRED_SCOPES
+});
+/** Steady-state delay once elapsed time reaches the final tier bound. */
+const STEADY_POLL_DELAY_MS = 5e3;
+/**
+* Fast-to-slow poll-cadence tiers keyed on elapsed wall-clock time. Elapsed
+* times at or beyond the last `untilMs` fall through to
+* {@link STEADY_POLL_DELAY_MS}.
+*/
+const DEFAULT_POLL_TIERS = [{
+	delayMs: 500,
+	untilMs: 2e4
+}, {
+	delayMs: 1e3,
+	untilMs: 6e4
+}];
+/**
+* Default poll cadence as a function of elapsed wall-clock time since
+* polling began. Polls quickly while a task is young so short runs resolve
+* snappily, then eases off so a long run leaves rate-limit headroom for
+* newer tasks: 0-20s is 500ms, 20-60s is 1000ms, 60s+ is 5000ms.
+*
+* @since 0.1.0
+*
+* @example
+* ```ts
+* import { defaultPollDelay } from "@bedrock-rbx/ocale/luau-execution";
+*
+* expect(defaultPollDelay(0)).toBe(500);
+* expect(defaultPollDelay(30_000)).toBe(1000);
+* expect(defaultPollDelay(120_000)).toBe(5000);
+* ```
+*
+* @param elapsedMs - Milliseconds elapsed since polling started.
+* @returns The delay in milliseconds to wait before the next poll.
+*/
+function defaultPollDelay(elapsedMs) {
+	return DEFAULT_POLL_TIERS.find((candidate) => elapsedMs < candidate.untilMs)?.delayMs ?? STEADY_POLL_DELAY_MS;
+}
+/**
+* Defaults the per-request `timeout` to the effective poll budget when the
+* caller has not set one. A luau-execution submit and each poll `get` normally
+* answer in well under a second (the submit endpoint enqueues the task without
+* waiting for it to run), so the only job of a per-request deadline here is to
+* bound a black-hole connection. Leaving these requests on the client-wide 30s
+* default (tuned for snappy CRUD) turns a slow-but-alive backend into a
+* self-abort, an error the retry layer never retries by construction, before
+* the loop's wall-clock budget is ever consulted. Deriving the deadline from
+* `timeoutMs` keeps a single request alive exactly as long as the caller
+* already agreed to wait for the whole operation, so the backend can answer or
+* surface a retryable status instead.
+*
+* @param options - The caller's poll and per-request options.
+* @returns The options with `timeout` filled from the budget when it was unset.
+*/
+function withBudgetRequestTimeout(options) {
+	if (options.timeout !== void 0) return options;
+	return {
+		...options,
+		timeout: options.timeoutMs ?? 3e5
+	};
+}
+const ABORTED = Symbol("poll-aborted");
+/**
+* Core polling loop. Calls `deps.fetch()` repeatedly, sleeping
+* `pollDelay(elapsedMs)` ms between iterations, until a terminal state
+* is observed, the wall-clock budget is exhausted, or an `AbortSignal`
+* fires. A transient transport failure ({@link NetworkError}) is tolerated
+* and the loop continues, giving up only after `maxConsecutivePollFailures`
+* consecutive failures; any other failure aborts immediately, since an API
+* response (a 404 for a vanished task, a 403) means there is nothing left to
+* poll. A successful poll resets the failure count.
+*
+* @param deps - Injected fetch, now, and sleep callbacks.
+* @param options - Optional poll delay, timeout, failure cap, and abort signal.
+* @returns The terminal task, or an error if aborted, timed out, or the transport keeps failing.
+*/
+async function pollUntilDoneCore(deps, options = {}) {
+	const timeoutMs = options.timeoutMs ?? 3e5;
+	const pollDelay = options.pollDelay ?? defaultPollDelay;
+	const maxFailures = options.maxConsecutivePollFailures ?? 3;
+	const sig = options.signal;
+	const startedAt = deps.now();
+	if (sig?.aborted === true) return abortedResult(sig);
+	let state = {
+		consecutiveFailures: 0,
+		lastTask: void 0
+	};
+	for (;;) {
+		const elapsedMs = deps.now() - startedAt;
+		if (elapsedMs >= timeoutMs) return {
+			err: makeTimeout(state.lastTask, timeoutMs),
+			success: false
+		};
+		const action = applyOutcome(await fetchOnce(deps, sig), {
+			maxFailures,
+			signal: sig,
+			state
+		});
+		if (action.kind === "return") return action.result;
+		({state} = action);
+		if (await sleepWithAbort({
+			ms: pollDelay(elapsedMs),
+			signal: sig,
+			sleep: deps.sleep
+		})) return abortedResult(sig);
+	}
+}
+function makeAborted(signal) {
+	return new PollAbortedError("Polling was aborted", { reason: signal?.reason });
+}
+function abortedResult(signal) {
+	return {
+		err: makeAborted(signal),
+		success: false
+	};
+}
+/**
+* Maps a single fetch outcome to the next loop action. Terminal, failed, and
+* aborted outcomes return immediately; a transient transport failure advances
+* the consecutive-failure count and returns once it reaches `maxFailures`; a
+* pending task resets the count and continues.
+*
+* @param outcome - The classified result of one poll fetch.
+* @param context - The loop state, failure cap, and abort signal.
+* @returns Whether to return a final Result or continue with updated state.
+*/
+function applyOutcome(outcome, context) {
+	const { maxFailures, signal, state } = context;
+	switch (outcome.kind) {
+		case "aborted": return {
+			kind: "return",
+			result: abortedResult(signal)
+		};
+		case "failed": return {
+			kind: "return",
+			result: {
+				err: outcome.error,
+				success: false
+			}
+		};
+		case "pending": return {
+			kind: "continue",
+			state: {
+				consecutiveFailures: 0,
+				lastTask: outcome.task
+			}
+		};
+		case "terminal": return {
+			kind: "return",
+			result: {
+				data: outcome.task,
+				success: true
+			}
+		};
+		case "transient": {
+			const consecutiveFailures = state.consecutiveFailures + 1;
+			if (consecutiveFailures >= maxFailures) return {
+				kind: "return",
+				result: {
+					err: outcome.error,
+					success: false
+				}
+			};
+			return {
+				kind: "continue",
+				state: {
+					consecutiveFailures,
+					lastTask: state.lastTask
+				}
+			};
+		}
+	}
+}
+function abortObserver(signal) {
+	const { promise, resolve } = Promise.withResolvers();
+	function onAbort() {
+		resolve(ABORTED);
+	}
+	signal.addEventListener("abort", onAbort);
+	function cleanup() {
+		signal.removeEventListener("abort", onAbort);
+	}
+	return {
+		cleanup,
+		promise
+	};
+}
+async function raceWithAbort(promise, signal) {
+	if (signal === void 0) return promise;
+	if (signal.aborted) return ABORTED;
+	const observer = abortObserver(signal);
+	try {
+		return await Promise.race([promise, observer.promise]);
+	} finally {
+		observer.cleanup();
+	}
+}
+async function sleepWithAbort(options) {
+	const { ms, signal, sleep } = options;
+	return await raceWithAbort(sleep(ms), signal) === ABORTED;
+}
+function makeTimeout(task, timeoutMs) {
+	return new PollTimeoutError(`Polling timed out after ${timeoutMs} ms`, {
+		lastObservedTask: task,
+		timeoutMs
+	});
+}
+function isTerminal(task) {
+	return task.state === "COMPLETE" || task.state === "FAILED" || task.state === "CANCELLED";
+}
+/**
+* A failed poll is worth re-polling only when it is a `NetworkError` carrying a
+* known transient transport code. A self-aborted request timeout has no
+* `code`, and an API response (4xx/5xx) is authoritative, so both abort the
+* loop rather than being re-polled. Transient-ness is classified against the
+* canonical `TRANSIENT_TRANSPORT_CODES` set; this is the loop's own tolerance
+* dimension, distinct from the per-request `retryableTransportCodes` override
+* (which governs request-level retries inside each poll). Loop tolerance is
+* bounded separately by `maxConsecutivePollFailures`.
+*
+* @param error - The error returned by a failed poll.
+* @returns `true` when the loop should tolerate and re-poll.
+*/
+function isTransientTransport(error) {
+	if (!(error instanceof NetworkError)) return false;
+	const code = findErrorCode(error);
+	return code !== void 0 && TRANSIENT_TRANSPORT_CODES.includes(code);
+}
+async function fetchOnce(deps, signal) {
+	const fetchResult = await raceWithAbort(deps.fetch(), signal);
+	if (fetchResult === ABORTED) return { kind: "aborted" };
+	if (!fetchResult.success) return isTransientTransport(fetchResult.err) ? {
+		error: fetchResult.err,
+		kind: "transient"
+	} : {
+		error: fetchResult.err,
+		kind: "failed"
+	};
+	return isTerminal(fetchResult.data) ? {
+		kind: "terminal",
+		task: fetchResult.data
+	} : {
+		kind: "pending",
+		task: fetchResult.data
+	};
+}
+//#endregion
+//#region src/resources/luau-execution/polling-helpers.ts
+/**
+* Builds the {@link PollDeps} bundle used by {@link pollUntilDoneCore},
+* closing over the supplied {@link ResourceClient}, task ref, and
+* per-request options so the core loop stays narrow.
+*
+* @param inner - The {@link ResourceClient} that issues each `tasks.get` call.
+* @param args - The polling options and the task ref to fetch on every iteration.
+* @returns A {@link PollDeps} bundle wiring `fetch`, `now`, and `sleep`.
+*/
+function buildPollDeps(inner, args) {
+	return {
+		fetch: async () => {
+			return inner.execute({
+				options: args.options,
+				parameters: {
+					ref: args.ref,
+					view: "BASIC"
+				},
+				spec: GET_SPEC
+			});
+		},
+		now: Date.now,
+		sleep: inner.sleep
+	};
+}
+/**
+* Submits a Luau execution task and polls it to a terminal state.
+* Dispatches to the head-version or specific-version submit spec based on
+* the presence of `versionId`, then delegates to {@link pollUntilDoneCore}.
+*
+* @param inner - The {@link ResourceClient} that issues submit and poll calls.
+* @param args - The polling options and submit parameters.
+* @returns A {@link Result} wrapping the terminal {@link LuauExecutionTask}, or
+*   the {@link OpenCloudError} that caused submit or polling to fail.
+*/
+async function submitAndPoll(inner, args) {
+	const { options, parameters } = args;
+	const submitResult = await ("versionId" in parameters ? inner.execute({
+		options,
+		parameters,
+		spec: SUBMIT_VERSION_SPEC
+	}) : inner.execute({
+		options,
+		parameters,
+		spec: SUBMIT_HEAD_SPEC
+	}));
+	if (!submitResult.success) return submitResult;
+	return pollUntilDoneCore(buildPollDeps(inner, {
+		options,
+		ref: submitResult.data.ref
+	}), options);
+}
+//#endregion
+export { withBudgetRequestTimeout as a, SUBMIT_VERSION_SPEC as c, pollUntilDoneCore as i, LIST_LOGS_SPEC as l, submitAndPoll as n, GET_SPEC as o, defaultPollDelay as r, SUBMIT_HEAD_SPEC as s, buildPollDeps as t };
+
+//# sourceMappingURL=polling-helpers-Cb4j4cq7.mjs.map