perf(artifact-delivery): answer Resolution polls when the build moves (#497)

* perf(artifact-delivery): answer Resolution polls when the build moves

A run waited for its build in one second steps, so the CLI saw a
finished build up to a second after it landed. A read of a building
Resolution now waits up to 8 seconds for its next state, checking every
250 ms, and the poll interval drops to 250 ms.

The queue send took 446 to 500 ms of each Resolution request in three
production traces. The CLI polls for the result anyway, so the send now
runs after the response. A send that fails settles the Resolution as a
retryable SERVICE_UNAVAILABLE, so the CLI requests a new one.

* fix(artifact-delivery): schedule the resolution queue send past the response

---------

Co-authored-by: Harlan GitHub Agent <harlan-github-agent[bot]@users.noreply.github.com>

Author: harlan-zw

layers/artifact-delivery/server/api/v1/resolutions/[id].get.ts

@@ -10,6 +10,7 @@ import {
 } from '../../../utils/github-app'
 import { canReadPrivateResolution } from '../../../utils/private-access'
 import { privateArtifactAccessEnabled } from '../../../utils/private-feature'
+import { waitForResolutionChange } from '../../../utils/resolution-wait'
 import { setSkillPageUrlHeader } from '../../../utils/skill-page'
 import { getResolution } from '../../../utils/state'
 
@@ -50,8 +51,15 @@ export default withArtifactProblems(defineApiHandler({
         throw createError({ statusCode: 404, message: 'Resolution not found' })
       }
     }
-    await setSkillPageUrlHeader(event, row)
-    return row
+    // A building Resolution answers when its state changes, so the CLI sees
+    // each stage, and the finished build, within one check of it landing.
+    const current = await waitForResolutionChange({
+      load: () => getResolution(platform.db, row.id),
+      sleep: milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
+      now: Date.now,
+    }, row)
+    await setSkillPageUrlHeader(event, current)
+    return current
   },
   presenter: presentArtifactResolution,
 }))

layers/artifact-delivery/server/api/v1/resolutions/index.post.ts

@@ -1,3 +1,4 @@
+import type { H3Event } from 'h3'
 import { getHeader, setHeader, setResponseStatus } from 'h3'
 import { defineApiHandler } from '#shared/server/handler'
 import { presentArtifactResolution } from '../../../presenters/resolution'
@@ -7,11 +8,13 @@ import {
   problemCodeSchema,
 } from '../../../schemas/contracts'
 import { withArtifactProblems } from '../../../utils/artifact-problem'
+import { failResolution } from '../../../utils/build'
 import { findPrivateRepositoryAccess } from '../../../utils/private-access'
 import { privateArtifactAccessEnabled } from '../../../utils/private-feature'
 import { enqueueArtifactBuild } from '../../../utils/queue'
-import { fetchAdmittedSkillIdentity, requestResolution } from '../../../utils/request-resolution'
+import { enqueueAfterResponse, fetchAdmittedSkillIdentity, requestResolution } from '../../../utils/request-resolution'
 import { setSkillPageUrlHeader } from '../../../utils/skill-page'
+import { getResolution } from '../../../utils/state'
 
 export default withArtifactProblems(defineApiHandler({
   schema: createResolutionRequestSchema,
@@ -36,7 +39,21 @@ export default withArtifactProblems(defineApiHandler({
     const result = await requestResolution({
       db: platform.db,
       lookupAdmitted: fetchAdmittedSkillIdentity(event.context),
-      enqueue: resolutionId => enqueueArtifactBuild(platform.env, resolutionId),
+      enqueue: enqueueAfterResponse({
+        schedule: work => runAfterResponse(event, work),
+        enqueue: resolutionId => enqueueArtifactBuild(platform.env, resolutionId),
+        failUnqueued: async (resolutionId, error) => {
+          console.error(JSON.stringify({
+            operation: 'artifact-build',
+            outcome: 'enqueue-failed',
+            resolutionId,
+            error: error instanceof Error ? error.message : String(error),
+          }))
+          const row = await getResolution(platform.db, resolutionId)
+          if (row)
+            await failResolution({ db: platform.db, now: () => Math.floor(Date.now() / 1000) }, row, 'SERVICE_UNAVAILABLE', true)
+        },
+      }),
       now: () => Math.floor(Date.now() / 1000),
     }, {
       source: body.source,
@@ -89,3 +106,20 @@ export default withArtifactProblems(defineApiHandler({
   },
   presenter: presentArtifactResolution,
 }))
+
+/**
+ * Keep the queue send alive past the response on Workers.
+ *
+ * H3Event has no `waitUntil` on h3 1.15, so the send goes through the
+ * Cloudflare context Nitro mounts. Off Workers (local dev, tests) it does not
+ * block the response. The registry layer keeps the same helper, and ADR-0001
+ * keeps utilities out of other layers, so this route holds its own copy.
+ */
+function runAfterResponse(event: H3Event, promise: Promise<unknown>): void {
+  const ctx = (event.context as { cloudflare?: { context?: { waitUntil?: (p: Promise<unknown>) => void } } }).cloudflare?.context
+  if (ctx?.waitUntil) {
+    ctx.waitUntil(promise)
+    return
+  }
+  void promise
+}

layers/artifact-delivery/server/utils/request-resolution.ts

@@ -77,3 +77,31 @@ export async function requestResolution(
     await dependencies.enqueue(result.row.id)
   return result
 }
+
+export interface AfterResponseEnqueueDependencies {
+  /** Keep work alive after the response, such as the Worker's `waitUntil`. */
+  schedule: (work: Promise<unknown>) => void
+  enqueue: (resolutionId: string) => Promise<void>
+  /** Settle a Resolution whose build never reached the queue. */
+  failUnqueued: (resolutionId: string, error: unknown) => Promise<void>
+}
+
+/**
+ * An `enqueue` that sends the build message after the response.
+ *
+ * The queue send took 446 to 500 ms of a 590 to 650 ms request in three
+ * production traces from Sydney and Bangkok on 2026-10-07. The CLI polls
+ * for the result anyway, so the send need not hold the first answer. A send
+ * that fails settles the Resolution as a retryable failure, so the polling
+ * CLI requests a new Resolution instead of waiting out its deadline.
+ */
+export function enqueueAfterResponse(
+  dependencies: AfterResponseEnqueueDependencies,
+): (resolutionId: string) => Promise<void> {
+  return async (resolutionId) => {
+    dependencies.schedule(
+      dependencies.enqueue(resolutionId)
+        .catch(error => dependencies.failUnqueued(resolutionId, error)),
+    )
+  }
+}

layers/artifact-delivery/server/utils/resolution-wait.ts

@@ -0,0 +1,51 @@
+import type { ResolutionRow } from './state'
+import { ACTIVE_BUILD_STATES } from './state'
+
+/** The longest one Resolution read waits for its build to move. */
+export const RESOLUTION_WAIT_MS = 8_000
+
+/** How often a waiting read loads the Resolution again. */
+export const RESOLUTION_CHECK_MS = 250
+
+export interface ResolutionWaitDependencies {
+  /** Load the Resolution as D1 holds it now. */
+  load: () => Promise<ResolutionRow | null>
+  sleep: (milliseconds: number) => Promise<void>
+  /** Milliseconds since the epoch. */
+  now: () => number
+}
+
+/**
+ * The Resolution once its build leaves the state it had, or as it stands
+ * when the wait runs out.
+ *
+ * A read used to answer at once, and the CLI came back a second later. A
+ * build that finished just after a read cost the run up to that second, and a
+ * Resolution passes through seven states. A held read answers within one
+ * check of each change, so the CLI sees `ready` about 250 ms after it lands.
+ * A settled Resolution answers at once.
+ */
+export async function waitForResolutionChange(
+  dependencies: ResolutionWaitDependencies,
+  row: ResolutionRow,
+  budgetMs: number = RESOLUTION_WAIT_MS,
+): Promise<ResolutionRow> {
+  if (!isBuilding(row))
+    return row
+  const deadline = dependencies.now() + budgetMs
+  let current = row
+  while (dependencies.now() + RESOLUTION_CHECK_MS <= deadline) {
+    await dependencies.sleep(RESOLUTION_CHECK_MS)
+    const next = await dependencies.load()
+    if (!next)
+      return current
+    current = next
+    if (current.state !== row.state)
+      return current
+  }
+  return current
+}
+
+function isBuilding(row: ResolutionRow): boolean {
+  return (ACTIVE_BUILD_STATES as readonly string[]).includes(row.state)
+}

layers/artifact-delivery/server/utils/state.ts

@@ -461,7 +461,9 @@ export function presentResolution(row: ResolutionRow): ResolutionResponse {
       state: 'pending',
       resolutionId: row.id,
       stage: row.state as ActiveBuildState,
-      pollAfterMs: 1000,
+      // A read of a building Resolution waits for its next state, so the
+      // CLI may come back at once. See `waitForResolutionChange`.
+      pollAfterMs: 250,
     }
   }
   if (row.state === 'blocked') {