unfazed 0.8.0 → 0.9.0

package/dist/unfazed.d.ts

@@ -1,4 +1,5 @@
 import { UnfazedClient, type ClientOptions, type RequestOptions } from "./client.js";
+import { UnfazedOIDC } from "./oidc.js";
 import type { AppErrorGroupFieldsFragment, CreateDeploymentInput, DeploymentEventType, DeploymentFieldsFragment, FileCommitFieldsFragment, ListDeploymentsInput, RunFieldsFragment, RunStatus, ServiceMode, ServiceRuntime, SdkAppCommitQuery, SdkAppCommitsQuery, SdkAppErrorGroupQuery, SdkAppErrorsQuery, SdkCreateWorkspaceMutation, SdkDeleteAppMutation, SdkDeploymentEventsQuery, SdkEventTypesQuery, SdkPollEventsQuery, SdkRestoreVersionMutation, SdkRunHarnessesQuery, SdkWorkspaceLiveAppsQuery } from "./generated/graphql.js";
 import { type WaitOptions } from "./wait.js";
 /** A deployment as the workflow layer returns it. */
@@ -171,9 +172,12 @@ export interface RestoreVersionOptions {
     commitMessage?: string;
     /**
      * When the restore deploys (`deploys: true`, an app that deploys every
-     * push), wait for that deploy: resolve once the import of the new commit
-     * finished with every deployment it made, throw {@link UnfazedDeployError}
-     * when it failed.
+     * push), wait for that deploy: the platform's wait by commit
+     * ({@link Unfazed.waitForDeployment} with `gitCommit`, `alias` and `after`
+     * from the answer) resolves once it is READY; {@link UnfazedDeployError}
+     * when it or the import of the new commit failed. A link with unfazed.json
+     * `apps[]` (no `deployAlias`) deploys once per app: then the wait follows
+     * the import until every deployment it made is done.
      */
     wait?: boolean;
     /** Timeout/backoff for `wait`; default 10 minutes. */
@@ -185,10 +189,29 @@ export type RestoreVersionResult = SdkRestoreVersionMutation["restoreAppVersion"
     /**
      * With `wait` and `deploys`: the deployments the restore's import made (one
      * per alias it deploys), READY. Absent without `wait` or when nothing
-     * deploys.
+     * deploys. Without `wait`, wait later with `waitForDeployment({ workspaceId:
+     * workspaceID, gitCommit: sha, alias: deployAlias, after: waitAfter })`.
      */
     deployments?: Deployment[];
 };
+/**
+ * The deploy a git import makes of a commit, for
+ * {@link Unfazed.waitForDeployment}: a restore, a push or a sync deploys
+ * before any deployment id exists, so the commit names it.
+ */
+export interface CommitDeploymentTarget {
+    workspaceId: string;
+    /** Full 40-character sha. */
+    gitCommit: string;
+    /** The app that deploys it; required when several apps (unfazed.json `apps[]`) deployed the commit. */
+    alias?: string | null;
+    /**
+     * Count only deployments begun after this point of the platform's
+     * deployment order (a restore's `waitAfter`), so an earlier deploy of the
+     * same commit never answers.
+     */
+    after?: number | null;
+}
 /** A service app's error group (MCP `list_errors`). Title, type, culprit and level are untrusted app text. */
 export type ErrorGroup = AppErrorGroupFieldsFragment;
 /** One page of error groups ({@link Unfazed.listErrors}). */
@@ -246,8 +269,14 @@ export interface DeploymentEvent {
     severity: SdkDeploymentEventsQuery["deploymentEvents"][number]["severity"];
     message: string;
     vmID: string | null;
-    /** The event's fields; timing events carry their phases as `*_ms` strings ({@link parseDeploymentTimings}). */
+    /** The event's fields; timing events carry their phases as `*_ms` strings. */
     metadata: Record<string, string> | null;
+    /**
+     * What a timing event (`deployment.build_finished`, `deployment.phases`)
+     * measured, as the platform parsed it; null for any other event.
+     * {@link parseDeploymentTimings} prefers it to `metadata`.
+     */
+    timings: PlatformTimings | null;
     createdAt: string;
 }
 /**
@@ -549,9 +578,19 @@ export interface UnfazedOptions extends ClientOptions {
  */
 export declare class Unfazed {
     #private;
-    /** The underlying typed GraphQL client. Use it for un-wrapped operations. */
-    readonly client: UnfazedClient;
+    /**
+     * Workload identity tokens for the app this code runs in
+     * (`oidc.token(audience)`, `oidc.fetchWithToken(audience)`). They need only
+     * the app's `UNFZ_STATE_TOKEN`, so they work in an `Unfazed` made without
+     * an API token or a login.
+     */
+    readonly oidc: UnfazedOIDC;
     constructor(options?: UnfazedOptions);
+    /**
+     * The underlying typed GraphQL client. Use it for un-wrapped operations.
+     * Throws {@link UnfazedAuthError} when there is no token and no login.
+     */
+    get client(): UnfazedClient;
     /** Who this token authenticates as, plus usage and resource limits. */
     whoami(options?: RequestOptions): Promise<{
         kind: import("./index.js").CurrentActorKind;
@@ -862,12 +901,27 @@ export declare class Unfazed {
      * the account already holds its cap of waits in progress (16), it polls
      * instead (`waitOptions.mode: "poll"` forces that), every 0.5 s backing
      * off to 3 s by default.
+     *
+     * Pass a {@link CommitDeploymentTarget} instead of an id to wait for the
+     * deploy a git import makes of a commit — a restore, a push or a sync
+     * deploys before any id exists. The wait covers the import too, and
+     * {@link UnfazedDeployError} carries the import's error when it failed on
+     * the commit.
+     *
+     * ```ts
+     * const back = await unfazed.restoreVersion({ workspaceId: ws.id, sha });
+     * await unfazed.waitForDeployment({
+     *   workspaceId: back.workspaceID, gitCommit: back.sha, alias: back.deployAlias, after: back.waitAfter,
+     * });
+     * ```
      */
-    waitForDeployment(deploymentId: string, waitOptions?: WaitOptions): Promise<Deployment>;
+    waitForDeployment(target: string | CommitDeploymentTarget, waitOptions?: WaitOptions): Promise<Deployment>;
     /**
-     * The platform's measured phases of a deploy ({@link PlatformTimings}),
-     * from its timing events. Null when it recorded none (a deploy that is
-     * still building, or one from before timings existed).
+     * The platform's measured phases of a deploy ({@link PlatformTimings}), as
+     * it parses them from all of the deployment's timing events
+     * (`Deployment.timings`). Null when it recorded none (a deploy that is
+     * still building, or one from before timings existed), or for a deployment
+     * you cannot see.
      */
     getDeploymentTimings(deploymentId: string, options?: RequestOptions): Promise<PlatformTimings | null>;
     /** Reads one deployment by id. Null when absent. */
@@ -1162,9 +1216,12 @@ export declare class Unfazed {
      * When the app deploys every push (`deploys: true`), the new commit is
      * imported and deployed like a push. That deploy is queued behind the
      * restore, so the platform answers before it exists; with `wait: true` the
-     * SDK waits for the import of the new commit and resolves with the
-     * deployments it made (READY), or throws {@link UnfazedDeployError} with
-     * the import's error.
+     * SDK waits for it by commit on the platform ({@link Unfazed.waitForDeployment}
+     * with `gitCommit: sha`, `alias: deployAlias`, `after: waitAfter`) and
+     * resolves with it READY, or throws {@link UnfazedDeployError} with its
+     * build error or the import's. A link with unfazed.json `apps[]` names no
+     * `deployAlias` and deploys once per app: then it follows the import until
+     * every deployment it made is done.
      *
      * ```ts
      * const page = await unfazed.listCommits(ws.id);
@@ -1406,10 +1463,18 @@ export declare class Unfazed {
         truncated: boolean;
     }>;
 }
+/** An event {@link parseDeploymentTimings} reads: `timings` when the platform parsed it, else `metadata`. */
+export type TimingEvent = Pick<DeploymentEvent, "type" | "metadata"> & {
+    timings?: PlatformTimings | null;
+};
 /**
- * A deploy's phases from its events: `deployment.phases` (written when it went
- * READY: build, promotion and its split, total) over `deployment.build_finished`
- * (the build VM's own phases). Every `*_ms` field becomes a number. Null when
- * neither event is there.
+ * A deploy's phases from its events, as the platform reads them: the latest
+ * `deployment.phases` (written when it went READY: build, promotion and its
+ * split, total) over the latest `deployment.build_finished` (the build VM's
+ * own phases). It prefers the `timings` the platform parsed into each event
+ * ({@link Unfazed.getEvents} reads them); events without them (an older
+ * platform, events built by hand) are parsed from their `*_ms` metadata the
+ * same way. Durations are whole, non-negative milliseconds: anything else is
+ * dropped, as the platform drops it. Null when neither event is there.
  */
-export declare function parseDeploymentTimings(events: readonly Pick<DeploymentEvent, "type" | "metadata">[]): PlatformTimings | null;
+export declare function parseDeploymentTimings(events: readonly TimingEvent[]): PlatformTimings | null;

package/dist/unfazed.js

@@ -1,5 +1,6 @@
 import { UnfazedClient } from "./client.js";
-import { DEPLOYMENT_NOT_FOUND, UnfazedConflictError, UnfazedDeployError, UnfazedError, UnfazedGraphQLError, UnfazedNotFoundError, UnfazedRunError, UnfazedTimeoutError, UnfazedUnconfirmedAppsError, UnfazedWriteError, WORKSPACE_NOT_FOUND, isAppNotFound, isDuplicateWorkspaceName, isNotFoundSentinel as isNotFound, isUnconfirmedAppsRefusal, isTooManyWaits, isUnsupportedField, looksLikeCASConflict, } from "./errors.js";
+import { DEPLOYMENT_NOT_FOUND, UnfazedAuthError, UnfazedConflictError, UnfazedDeployError, UnfazedError, UnfazedGraphQLError, UnfazedNotFoundError, UnfazedRunError, UnfazedTimeoutError, UnfazedUnconfirmedAppsError, UnfazedWriteError, WORKSPACE_NOT_FOUND, isAppNotFound, isDuplicateWorkspaceName, isNotFoundSentinel as isNotFound, isUnconfirmedAppsRefusal, isTooManyWaits, isUnsupportedField, looksLikeCASConflict, } from "./errors.js";
+import { UnfazedOIDC } from "./oidc.js";
 import * as ops from "./operations.js";
 import { pollWithBackoff, resolveWaitOptions } from "./wait.js";
 /**
@@ -20,11 +21,51 @@ import { pollWithBackoff, resolveWaitOptions } from "./wait.js";
  * ```
  */
 export class Unfazed {
-    /** The underlying typed GraphQL client. Use it for un-wrapped operations. */
-    client;
+    #client;
+    /** Why there is no client: no token and no stored login. */
+    #noClient;
+    /**
+     * Workload identity tokens for the app this code runs in
+     * (`oidc.token(audience)`, `oidc.fetchWithToken(audience)`). They need only
+     * the app's `UNFZ_STATE_TOKEN`, so they work in an `Unfazed` made without
+     * an API token or a login.
+     */
+    oidc;
     constructor(options = {}) {
         const { client, ...clientOptions } = options;
-        this.client = client ?? new UnfazedClient(clientOptions);
+        let made = client;
+        if (!made) {
+            try {
+                made = new UnfazedClient(clientOptions);
+            }
+            catch (error) {
+                // An app has its state token but no API token: `oidc` still works,
+                // and the first call that needs the API says how to sign in.
+                if (!(error instanceof UnfazedAuthError))
+                    throw error;
+                this.#noClient = error;
+            }
+        }
+        this.#client = made;
+        // Tokens come from the platform the client talks to: its endpoint already
+        // resolved `endpoint`, `baseUrl`, `UNFZ_API_URL` and the stored login.
+        const endpoint = made?.endpoint ?? options.endpoint;
+        this.oidc = new UnfazedOIDC({
+            ...(endpoint ? { endpoint } : {}),
+            ...(!made && options.baseUrl ? { baseUrl: options.baseUrl } : {}),
+            ...(options.env ? { env: options.env } : {}),
+            ...(options.fetch ? { fetch: options.fetch } : {}),
+            ...(options.userAgent !== undefined ? { userAgent: options.userAgent } : {}),
+        });
+    }
+    /**
+     * The underlying typed GraphQL client. Use it for un-wrapped operations.
+     * Throws {@link UnfazedAuthError} when there is no token and no login.
+     */
+    get client() {
+        if (this.#client)
+            return this.#client;
+        throw new UnfazedAuthError(this.#noClient?.message ?? "unfazed: no API client", { cause: this.#noClient });
     }
     /* ---------------------------------------------------------------- identity */
     /** Who this token authenticates as, plus usage and resource limits. */
@@ -464,9 +505,24 @@ export class Unfazed {
      * the account already holds its cap of waits in progress (16), it polls
      * instead (`waitOptions.mode: "poll"` forces that), every 0.5 s backing
      * off to 3 s by default.
+     *
+     * Pass a {@link CommitDeploymentTarget} instead of an id to wait for the
+     * deploy a git import makes of a commit — a restore, a push or a sync
+     * deploys before any id exists. The wait covers the import too, and
+     * {@link UnfazedDeployError} carries the import's error when it failed on
+     * the commit.
+     *
+     * ```ts
+     * const back = await unfazed.restoreVersion({ workspaceId: ws.id, sha });
+     * await unfazed.waitForDeployment({
+     *   workspaceId: back.workspaceID, gitCommit: back.sha, alias: back.deployAlias, after: back.waitAfter,
+     * });
+     * ```
      */
-    async waitForDeployment(deploymentId, waitOptions = {}) {
-        return (await this.#waitTerminal(deploymentId, waitOptions)).deployment;
+    async waitForDeployment(target, waitOptions = {}) {
+        if (typeof target !== "string")
+            return (await this.#commitWait(target, waitOptions)).deployment;
+        return (await this.#waitTerminal(target, waitOptions)).deployment;
     }
     async #waitTerminal(deploymentId, waitOptions) {
         const now = waitOptions.now ?? (() => Date.now());
@@ -518,7 +574,11 @@ export class Unfazed {
                 }
                 throw e;
             }
+            // By id the platform always answers the deployment; null is only for a
+            // wait by commit before the import made it.
             const d = answer.deployment;
+            if (!d)
+                throw new UnfazedNotFoundError(`unfazed: deployment ${deploymentId} not found`);
             last = d;
             if (answer.timedOut) {
                 landing = d.status === "READY";
@@ -529,6 +589,61 @@ export class Unfazed {
             throw new UnfazedDeployError("FAILED", deploymentId, d, `unfazed: deployment ${deploymentId} ${d.status}${d.error ? `: ${d.error}` : ""}`);
         }
     }
+    /**
+     * The server-side wait by commit: for the import to make the commit's
+     * deployment, then for it, one budget for both. There is nothing cheaper to
+     * poll, so a refusal past the platform's cap on waits in progress backs off
+     * (0.5 s up to 3 s) and asks again.
+     */
+    async #commitWait(target, waitOptions) {
+        const resolved = resolveWaitOptions(waitOptions);
+        const deadline = resolved.now() + resolved.timeoutMs;
+        const commit = target.gitCommit.slice(0, 7);
+        const what = `the deploy of ${commit}${target.alias ? ` to ${target.alias}` : ""}`;
+        let last = null;
+        let status = "IMPORTING";
+        let backoff = 500;
+        for (let requests = 1;; requests++) {
+            if (resolved.signal?.aborted)
+                throw new UnfazedTimeoutError("unfazed: wait aborted");
+            const remaining = deadline - resolved.now();
+            if (requests > 1 && remaining <= 0) {
+                throw new UnfazedDeployError("TIMEOUT", last?.id ?? "", last, `unfazed: ${what} still ${status} after ${resolved.timeoutMs}ms`);
+            }
+            const seconds = Math.max(1, Math.min(SERVER_WAIT_SECONDS, Math.ceil(remaining / 1000)));
+            let answer;
+            try {
+                answer = (await this.client.query(ops.WaitForCommitDeploymentDocument, {
+                    workspaceID: target.workspaceId,
+                    gitCommit: target.gitCommit,
+                    alias: target.alias ?? null,
+                    after: target.after ?? null,
+                    timeoutSeconds: seconds,
+                }, { ...(resolved.signal ? { signal: resolved.signal } : {}), timeoutMs: (seconds + 30) * 1000 })).waitForDeployment;
+            }
+            catch (e) {
+                if (!isTooManyWaits(e))
+                    throw e;
+                await resolved.sleep(Math.max(0, Math.min(backoff, deadline - resolved.now())), resolved.signal);
+                backoff = Math.min(backoff * 1.5, 3_000);
+                continue;
+            }
+            const d = answer.deployment;
+            status = answer.status;
+            if (d)
+                last = d;
+            if (answer.timedOut)
+                continue;
+            if (!d) {
+                // Not timed out and no deployment: the import failed on the commit
+                // and nothing imports any more, so no deployment of it is coming.
+                throw new UnfazedDeployError("FAILED", "", null, `unfazed: the import of ${commit} failed${answer.importError ? `: ${answer.importError}` : ""}`);
+            }
+            if (d.status === "READY")
+                return { deployment: d, requests };
+            throw new UnfazedDeployError("FAILED", d.id, d, `unfazed: deployment ${d.id} (${what}) ${d.status}${d.error ? `: ${d.error}` : ""}`);
+        }
+    }
     async #pollWait(deploymentId, waitOptions) {
         const resolved = resolveWaitOptions({ initialIntervalMs: 500, maxIntervalMs: 3_000, ...waitOptions });
         const requestOptions = resolved.signal ? { signal: resolved.signal } : {};
@@ -557,12 +672,16 @@ export class Unfazed {
         return { deployment: full, requests: requests + 1, mode: "poll" };
     }
     /**
-     * The platform's measured phases of a deploy ({@link PlatformTimings}),
-     * from its timing events. Null when it recorded none (a deploy that is
-     * still building, or one from before timings existed).
+     * The platform's measured phases of a deploy ({@link PlatformTimings}), as
+     * it parses them from all of the deployment's timing events
+     * (`Deployment.timings`). Null when it recorded none (a deploy that is
+     * still building, or one from before timings existed), or for a deployment
+     * you cannot see.
      */
     async getDeploymentTimings(deploymentId, options) {
-        return parseDeploymentTimings(await this.getEvents(deploymentId, 100, options));
+        const data = await this.client.query(ops.DeploymentTimingsDocument, { id: deploymentId }, options);
+        const timings = data.deployment?.timings;
+        return timings ? toPlatformTimings(timings) : null;
     }
     /**
      * The timings of a deploy that just went READY. `deployment.phases` is
@@ -964,9 +1083,12 @@ export class Unfazed {
      * When the app deploys every push (`deploys: true`), the new commit is
      * imported and deployed like a push. That deploy is queued behind the
      * restore, so the platform answers before it exists; with `wait: true` the
-     * SDK waits for the import of the new commit and resolves with the
-     * deployments it made (READY), or throws {@link UnfazedDeployError} with
-     * the import's error.
+     * SDK waits for it by commit on the platform ({@link Unfazed.waitForDeployment}
+     * with `gitCommit: sha`, `alias: deployAlias`, `after: waitAfter`) and
+     * resolves with it READY, or throws {@link UnfazedDeployError} with its
+     * build error or the import's. A link with unfazed.json `apps[]` names no
+     * `deployAlias` and deploys once per app: then it follows the import until
+     * every deployment it made is done.
      *
      * ```ts
      * const page = await unfazed.listCommits(ws.id);
@@ -985,18 +1107,19 @@ export class Unfazed {
         const restored = data.restoreAppVersion;
         if (!options.wait || !restored.deploys)
             return restored;
-        return {
-            ...restored,
-            deployments: await this.#waitForImport(options.workspaceId, restored.sha, {
-                ...options.waitOptions,
-                ...(options.signal ? { signal: options.signal } : {}),
-            }),
-        };
+        const waitOptions = { ...options.waitOptions, ...(options.signal ? { signal: options.signal } : {}) };
+        if (restored.deployAlias) {
+            const { deployment } = await this.#commitWait({ workspaceId: restored.workspaceID, gitCommit: restored.sha, alias: restored.deployAlias, after: restored.waitAfter }, waitOptions);
+            return { ...restored, deployments: [deployment] };
+        }
+        return { ...restored, deployments: await this.#waitForImport(restored.workspaceID, restored.sha, waitOptions) };
     }
     /**
      * Waits until the app's git link has imported `sha` (READY: its deploys
      * are done) and returns the deployments of that commit; throws on a FAILED
-     * import of it.
+     * import of it. Only for a restore whose link names no alias (unfazed.json
+     * `apps[]`): the wait by commit waits for one app's deploy, and which apps
+     * a commit deploys is known only once its import is done.
      */
     async #waitForImport(workspaceId, sha, waitOptions) {
         const resolved = resolveWaitOptions({ initialIntervalMs: 500, maxIntervalMs: 3_000, ...waitOptions });
@@ -1443,51 +1566,123 @@ function toDeploymentEvent(event) {
         message: event.message,
         vmID: event.vmID ?? null,
         metadata: event.metadata ?? null,
+        timings: event.timings ? toPlatformTimings(event.timings) : null,
         createdAt: event.createdAt,
     };
 }
+const BUILD_FINISHED_EVENT = "deployment.build_finished";
+const DEPLOY_PHASES_EVENT = "deployment.phases";
 /**
- * A deploy's phases from its events: `deployment.phases` (written when it went
- * READY: build, promotion and its split, total) over `deployment.build_finished`
- * (the build VM's own phases). Every `*_ms` field becomes a number. Null when
- * neither event is there.
+ * A duration as the platform accepts one: a whole, non-negative number of
+ * milliseconds (a number, or a string of digits as metadata carries it). A
+ * fraction or anything else is not a duration; a negative one is a clock gone
+ * backwards. Both are dropped, as the platform drops them.
  */
-export function parseDeploymentTimings(events) {
-    const latest = (type) => [...events].reverse().find((e) => e.type === type)?.metadata ?? null;
-    const build = latest("deployment.build_finished");
-    const ready = latest("deployment.phases");
-    if (!build && !ready)
+function durationMs(value) {
+    let n;
+    if (typeof value === "number")
+        n = value;
+    else if (typeof value === "string" && /^[+-]?\d+$/.test(value.trim()))
+        n = Number(value.trim());
+    else
         return null;
-    const merged = { ...build, ...ready };
-    const ms = (name) => {
-        const value = merged[`${name}_ms`];
-        if (value === undefined)
-            return null;
-        const n = Number(value);
-        return Number.isFinite(n) ? n : null;
-    };
+    return Number.isSafeInteger(n) && n >= 0 ? n + 0 : null; // + 0: -0 is 0
+}
+/** The platform's structured timings, with every duration checked like the metadata's. */
+function toPlatformTimings(t) {
     const phases = {};
-    for (const [key, value] of Object.entries(merged)) {
-        if (!key.endsWith("_ms"))
-            continue;
-        const name = key.slice(0, -3);
-        if (name === "total" || name === "build" || name === "promote")
-            continue;
-        const n = Number(value);
-        if (Number.isFinite(n))
-            phases[name] = n;
+    if (t.phases && typeof t.phases === "object") {
+        for (const [name, value] of Object.entries(t.phases)) {
+            const ms = durationMs(value);
+            if (ms !== null)
+                phases[name] = ms;
+        }
     }
-    const memory = Number(merged["build_memory_mib"]);
+    const memory = durationMs(t.buildMemoryMiB);
     return {
-        totalMs: ready ? ms("total") : null,
-        buildMs: ms("build"),
-        promoteMs: ms("promote"),
+        totalMs: durationMs(t.totalMs),
+        buildMs: durationMs(t.buildMs),
+        promoteMs: durationMs(t.promoteMs),
         phases,
-        buildMode: merged["build_mode"] ?? null,
-        artifactTransport: merged["artifact_transport"] ?? null,
-        buildMemoryMiB: Number.isFinite(memory) && merged["build_memory_mib"] !== undefined ? memory : null,
+        buildMode: t.buildMode || null,
+        artifactTransport: t.artifactTransport || null,
+        buildMemoryMiB: memory ? memory : null,
     };
 }
+/**
+ * Timing-event metadata read exactly as the platform reads it
+ * (internal/usecases/deploy_timings.go): every `<name>_ms` that is a whole,
+ * non-negative number; `total` only from the READY summary.
+ */
+function timingsFromMetadata(metadata, ready) {
+    const out = {
+        totalMs: null,
+        buildMs: null,
+        promoteMs: null,
+        phases: {},
+        buildMode: metadata["build_mode"] || null,
+        artifactTransport: metadata["artifact_transport"] || null,
+        buildMemoryMiB: null,
+    };
+    for (const [key, raw] of Object.entries(metadata)) {
+        if (!key.endsWith("_ms") || key === "_ms")
+            continue;
+        const ms = durationMs(raw);
+        if (ms === null)
+            continue;
+        const name = key.slice(0, -3);
+        if (name === "total") {
+            if (ready)
+                out.totalMs = ms;
+        }
+        else if (name === "build")
+            out.buildMs = ms;
+        else if (name === "promote")
+            out.promoteMs = ms;
+        else
+            out.phases[name] = ms;
+    }
+    const memory = durationMs(metadata["build_memory_mib"]);
+    if (memory)
+        out.buildMemoryMiB = memory;
+    return out;
+}
+/**
+ * A deploy's phases from its events, as the platform reads them: the latest
+ * `deployment.phases` (written when it went READY: build, promotion and its
+ * split, total) over the latest `deployment.build_finished` (the build VM's
+ * own phases). It prefers the `timings` the platform parsed into each event
+ * ({@link Unfazed.getEvents} reads them); events without them (an older
+ * platform, events built by hand) are parsed from their `*_ms` metadata the
+ * same way. Durations are whole, non-negative milliseconds: anything else is
+ * dropped, as the platform drops it. Null when neither event is there.
+ */
+export function parseDeploymentTimings(events) {
+    const latest = (type) => {
+        const event = [...events].reverse().find((e) => e.type === type);
+        return event && (event.timings || event.metadata) ? event : null;
+    };
+    const build = latest(BUILD_FINISHED_EVENT);
+    const ready = latest(DEPLOY_PHASES_EVENT);
+    if (!build && !ready)
+        return null;
+    if ((!build || build.timings) && (!ready || ready.timings)) {
+        const b = build?.timings ? toPlatformTimings(build.timings) : null;
+        const r = ready?.timings ? toPlatformTimings(ready.timings) : null;
+        return {
+            totalMs: r?.totalMs ?? null,
+            buildMs: r?.buildMs ?? b?.buildMs ?? null,
+            promoteMs: r?.promoteMs ?? b?.promoteMs ?? null,
+            phases: { ...b?.phases, ...r?.phases },
+            buildMode: r?.buildMode ?? b?.buildMode ?? null,
+            artifactTransport: r?.artifactTransport ?? b?.artifactTransport ?? null,
+            buildMemoryMiB: r?.buildMemoryMiB ?? b?.buildMemoryMiB ?? null,
+        };
+    }
+    // The platform merges the two events' metadata, the READY summary's values
+    // over the build's, and parses the result.
+    return timingsFromMetadata({ ...build?.metadata, ...ready?.metadata }, ready !== null);
+}
 function errorGroupInput(ref) {
     return { workspaceID: ref.workspaceId, alias: ref.alias, groupID: ref.groupId };
 }