From f91e51162f9a2522d9890bc87e807024721b98bf Mon Sep 17 00:00:00 2001
From: Bryan Helmkamp <bryan@brynary.com>
Date: Tue, 28 Jul 2026 18:05:24 -0400
Subject: [PATCH] Describe the parallel branch fields in generated clients
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`parallel_group_id` used `oneOf: [$ref StageId, null]`, and the generator
drops a sibling description in that position, so the TypeScript client
documented the field as "Canonical stage execution identifier in
`node_id@visit` form" — the shared StageId text, which says nothing about
what this field means. Switching to `allOf` lets the field's own
description through.

Dropping `type: "null"` also makes the contract match the server, which
omits both fields rather than sending null (`skip_serializing_if` on
`Option`, pinned by list_run_stages_exposes_parallel_branch_identity).
The Rust types are unchanged — still `Option<StageId>` and `Option<u32>`,
which accept an explicit null on input either way — so this only narrows
what clients are told to expect on the wire. Wording updated to match,
and reworded to avoid an apostrophe the generator escapes into the
JSDoc.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 docs/public/api-reference/fabro-api.yaml              | 11 +++++------
 lib/packages/fabro-api-client/src/models/run-stage.ts |  8 ++++----
 2 files changed, 9 insertions(+), 10 deletions(-)

diff --git a/docs/public/api-reference/fabro-api.yaml b/docs/public/api-reference/fabro-api.yaml
index 3ace82a9f..f434dd6ab 100644
--- a/docs/public/api-reference/fabro-api.yaml
+++ b/docs/public/api-reference/fabro-api.yaml
@@ -12794,21 +12794,20 @@ components:
             replay after the run was resumed.
           example: verify@1
         parallel_group_id:
-          oneOf:
+          allOf:
             - $ref: "#/components/schemas/StageId"
-            - type: "null"
           description: >-
             Exact StageId of the parent parallel execution. Clients can compare
-            this directly with a parallel stage's `id`. Null for stages that
-            are not parallel branches.
+            this directly with the `id` of a parallel stage. Omitted for stages
+            that are not parallel branches.
           example: review_fork@1
         parallel_branch_index:
-          type: ["integer", "null"]
+          type: integer
           format: uint32
           minimum: 0
           description: >-
             Zero-based outgoing-edge index within the parent parallel
-            execution. Null for stages that are not parallel branches.
+            execution. Omitted for stages that are not parallel branches.
           example: 1
         provider_used:
           oneOf:
diff --git a/lib/packages/fabro-api-client/src/models/run-stage.ts b/lib/packages/fabro-api-client/src/models/run-stage.ts
index 41caa58c0..442753331 100644
--- a/lib/packages/fabro-api-client/src/models/run-stage.ts
+++ b/lib/packages/fabro-api-client/src/models/run-stage.ts
@@ -61,13 +61,13 @@ export interface RunStage {
      */
     'resumed_from_stage_id'?: string | null;
     /**
-     * Canonical stage execution identifier in `node_id@visit` form.
+     * Exact StageId of the parent parallel execution. Clients can compare this directly with the `id` of a parallel stage. Omitted for stages that are not parallel branches.
      */
-    'parallel_group_id'?: string | null;
+    'parallel_group_id'?: string;
     /**
-     * Zero-based outgoing-edge index within the parent parallel execution. Null for stages that are not parallel branches.
+     * Zero-based outgoing-edge index within the parent parallel execution. Omitted for stages that are not parallel branches.
      */
-    'parallel_branch_index'?: number | null;
+    'parallel_branch_index'?: number;
     'provider_used'?: StageModelUsage | null;
     /**
      * Wall-clock time the latest attempt of this stage started, if known.