Method createCheckpoint

packages/ai-sandbox-sprites/src/client.ts:328–367

* Create a checkpoint and return its new version id (e.g. `v3`). The create * endpoint streams NDJSON progress; we drain it to completion, then resolve * the new id as the highest sequential `vN` checkpoint (autos and the live * `Current` pointer are ignored).

(
    name: string,
    options: { comment?: string; signal?: AbortSignal } = {},
  )

   * `Current` pointer are ignored).
   */
  async createCheckpoint(
    name: string,
    options: { comment?: string; signal?: AbortSignal } = {},
  ): Promise<string> {
    // Snapshot the existing versions first so we can identify the one THIS call
    // creates, rather than blindly returning the current max (which a concurrent
    // create — e.g. handle.snapshot() racing an after-run snapshot — would make
    // ambiguous, or an eventually-consistent list would make stale).
    const before = new Set(await this.checkpointVersions(name, options.signal))

    const url = this.spritePath(name, '/checkpoint')
    const response = await fetch(url, {
      method: 'POST',
      headers: this.headers({ 'content-type': 'application/json' }),
      body: JSON.stringify(
        options.comment !== undefined ? { comment: options.comment } : {},
      ),
      ...(options.signal ? { signal: options.signal } : {}),
    })
    if (!response.ok) await this.fail('POST', url, response)
    // The create stream closes promptly; drain it so the checkpoint is committed
    // before we read the list back, and mine it for the new version id.
    const streamText = await response.text()
    const streamVersions = [...streamText.matchAll(/\bv(\d+)\b/g)].map((m) =>
      Number(m[1]),
    )

    const after = await this.checkpointVersions(name, options.signal)
    const fresh = after.filter((v) => !before.has(v))
    // Prefer a version that did not exist before this call; fall back to the
    // stream-reported version, then to the overall max.
    const candidates = fresh.length > 0 ? fresh : streamVersions
    const pool = candidates.length > 0 ? candidates : after
    if (pool.length === 0) {
      throw new Error(
        `Sprites: checkpoint created for "${name}" but no versioned checkpoint was found.`,
      )
    }
    return `v${Math.max(...pool)}`
  }

  /** Numeric ids of the Sprite's non-auto `vN` checkpoints. */
  private async checkpointVersions(