@toloka-platform/sdk 0.1.0-preview.6 → 0.1.0-preview.8

package/docs/testing.md

@@ -0,0 +1,115 @@
+# Test pipelines locally
+
+The `@toloka-platform/sdk/testing` entry point provides typed Vitest wrappers for executable Python `code` nodes, Chromium Task UI scenarios, and complete pipeline flows. `toloka check` runs those tests together with project TypeScript and automatic Task UI typechecking without creating or modifying a platform project.
+
+## Install test dependencies
+
+```sh
+bun add --dev vitest playwright
+bunx playwright install chromium
+```
+
+Code-node tests also require `python3` on the test machine. See [testing examples](./testing-examples.md) for parameterization, validation failures, hardware coverage, and cleanup patterns.
+
+## Test a code node
+
+`test.code(pipeline, node, name, callback)` binds one test to one authored code node. Its `run(inputs, options?)` helper executes the Python source with the same async `main(inputs)` entry contract. The test counts as node coverage only after `run` executes, at least one assertion runs, and the callback passes.
+
+```ts
+import { expect, test } from "@toloka-platform/sdk/testing";
+import pipeline from "../../pipeline";
+import { normalize } from "./node";
+
+test.code(pipeline, normalize, "normalizes whitespace", async ({ run }) => {
+  await expect(run({ text: "  hello  " })).resolves.toEqual({
+    normalized_text: "hello",
+  });
+});
+```
+
+Failures from the bound executor throw `CodeNodeExecutionError` with the Python exit code and stderr. Authored static environment values are included; pass secret or test-specific values through the optional `run` options. Third-party imports must be available to the selected Python executable.
+
+`test.code` defaults to 30 seconds, which exceeds the code runner's 10-second default. Pass `{ timeout: milliseconds }` after the callback when the scenario also raises the runner timeout.
+
+## Test a complete pipeline flow
+
+Register the representative connected scenario with `test.pipeline(pipeline, name, callback)`. Its callback provides `runCode(node, inputs, options?)` and `renderUi(node, options?)` bound to that pipeline.
+
+Use the first row from the same local dataset file intended for upload when one is available. If it contains sensitive values, keep a redacted fixture that preserves field names, nesting, optionality, and media/value shapes. Use synthetic input only when no local row exists. `test.pipeline` does not fetch a live dataset: the local gate remains deterministic, credential-free, and usable before apply. Treat the fixture as `root.started` item state, execute connected nodes in order, merge only each node's declared outputs, and assert the fields accepted by `root.completed`. A linear happy path can stay in one test; use separate scenarios for materially different match branches, optional paths, and failures.
+
+## Test a Task UI
+
+Create a file ending in `.ui.spec.ts` next to the human-work node. `test.ui` binds the test to the pipeline and node, and its callback receives `render(options?)` for that target. The test counts as coverage only after a successful submission, at least one assertion, and a passing callback.
+
+Browser-backed `test.ui` scenarios default to 60 seconds, which exceeds the launcher's 45-second setup budget. `test.pipeline` scenarios default to 120 seconds for connected flows with multiple UI steps. Pass `{ timeout: milliseconds }` after the callback to tune either wrapper without weakening its inner launcher deadlines.
+
+```ts
+import { expect, test } from "@toloka-platform/sdk/testing";
+import pipeline from "../../pipeline";
+import { annotate } from "./node";
+
+test.ui(pipeline, annotate, "submits a valid answer", async ({ render }) => {
+  const task = await render({
+    data: { prompt: "What is two plus two?" },
+  });
+
+  await task.setValue("raw_answer", "four");
+
+  expect(await task.validationErrors()).toEqual([]);
+  expect(await task.submit()).toMatchObject({
+    answer: "four",
+  });
+  await task.screenshot("test-results/answer.png");
+});
+```
+
+Run the complete gate rather than invoking Vitest separately:
+
+```sh
+toloka check
+```
+
+Use an ordinary TypeScript loop to register several `test.code` or `test.ui` scenarios. There is no separate JSON scenario format.
+
+## Fixture API
+
+The low-level `ui` fixture remains available inside ordinary Vitest tests for component discovery and exploratory work, but plain tests do not satisfy required node coverage. Use typed wrappers for committed gate evidence. Importing `@toloka-platform/sdk/testing` from a plain Bun script executes Vitest fixture setup and fails.
+
+- `ui.componentDocumentation(names?)` returns the current launcher's supported component contracts. Call it before choosing component names or props.
+- `ui.render(pipeline, node, options)` creates a fresh browser context and returns a Task UI session for exactly that authored node. `test.ui` supplies the equivalent bound `render(options?)` helper.
+
+The returned Task UI session supports:
+
+- `componentTree()` returns the rendered component hierarchy.
+- `componentDocumentation(names?)` returns component props, value shapes, capabilities, and limitations.
+- `setValue(path, value)` and `getValue(path)` address Fields by their stable `path`, not generated component ids.
+- `validationErrors()` returns browser-level required-field and component-rule failures with Field paths.
+- `submit()` executes preprocess/postprocess, removes the launcher's `_context`, and validates declared output entities. The returned form data can also contain echoed inputs; assert output-entity keys and values without treating those inputs as output entities.
+- `screenshot(path)` writes a full-page PNG to the local filesystem.
+- `coverage` states whether hardware-backed fields were exercised completely.
+
+One Chromium process is shared per Vitest worker. Every scenario gets a fresh context and page and is cleaned up automatically.
+
+For a structured or array-valued Field, derive the dataset field schema from the component's documented `valueType`. In its typed UI scenario, adapt only semantic values such as labels, then pass the documented example value through `setValue`, `getValue`, and `submit`. This catches component-shape drift before a postprocess can read absent keys and silently write fallback data.
+
+## Runtime rules
+
+`ui.code` must parse as one JSX root. Every identifier must be a component returned by `componentDocumentation()` or a documented `actions` API. `toloka check` applies full TypeScript semantic checking with declarations bundled in the SDK; the real launcher then renders the same JSX in browser scenarios. Treat a component's `propsType` and `example` together as its contract.
+
+`preprocess` and `postprocess` are JavaScript function bodies, not TypeScript:
+
+Valid JavaScript: `items.map((item) => item.value)`
+
+Invalid runtime JavaScript: `items.map((item: unknown) => item.value)`
+
+`preprocess` can run again after form state changes. Use it to shape input data; if it prefills a bound field, return that key only while it is absent so later edits are not overwritten. A `Field`-bound top-level key already enters the submission. `postprocess` must return only new top-level keys: bind a component to a draft key when postprocess must derive a different entity key.
+
+The fixture loads the hosted TBX launcher in a fresh local Chromium context, so tests require network access but do not use Azure Playwright or Potato application services. The context has no platform cookies or credentials. Use synthetic or redacted fixtures because the hosted launcher executes with access to the supplied test data.
+
+## Hardware-backed fields
+
+File pickers, video upload/recording, and other hardware-backed fields cannot be completed reliably in headless Chromium. `task.coverage.complete` is `false` when these components are present. Render with `allowPartialCoverage: true`, inject one value matching the component's documented `valueType` through `setValue`, and assert the postprocessed output shape yourself: entity validation skips hardware-backed paths, and `getValue` may not serialize their launcher state. This checks browser validation and mapping only, not capture, upload, link generation, or record-time constraints. A partial result must not be described as complete coverage.
+
+## Final gate
+
+`toloka check` loads every authored pipeline, runs the project TypeScript compiler, typechecks every Task UI against declarations bundled with the installed SDK, runs Vitest, and requires passing `test.code`, `test.ui`, and `test.pipeline` evidence. `missing`, `failed`, `partial`, and `infrastructure_error` are distinct blocking outcomes. `toloka apply` reruns this complete gate before resolving credentials or writing platform state. Platform source/spec errors from `toloka validate` remain separate; `not_ran_node_check` describes a Remote Node Check and does not replace local evidence.

package/examples/face-image-collection/README.md

@@ -17,7 +17,13 @@ toloka import pp.0190abcd-abcd-7abc-8abc-abcdefabcdef
 # Imported project pp.0190abcd-abcd-7abc-8abc-abcdefabcdef with 1 pipeline and 1 dataset into ...
 ```
 
-Edit a node under `pipelines/face-image-collection/nodes/`, then inspect and apply the project-wide reconciliation:
+Edit a node under `pipelines/face-image-collection/nodes/`, then run the shipped typed code, UI, and connected-flow scenarios before inspecting any platform changes:
+
+```sh
+toloka check face-image-collection
+```
+
+After the local gate passes, inspect and apply the project-wide reconciliation:
 
 ```sh
 toloka plan

package/examples/face-image-collection/fields.ts

@@ -5,19 +5,31 @@ const faceAnnotationsSchema: Parameters<typeof field>[1] = {
   items: {
     type: "object",
     properties: {
-      boundingBox: {
+      id: { type: "string" },
+      type: { type: "string" },
+      geometry: {
         type: "object",
         properties: {
-          x: { type: "number" },
-          y: { type: "number" },
-          width: { type: "number" },
-          height: { type: "number" },
+          bounds: {
+            type: "object",
+            properties: {
+              minX: { type: "number" },
+              minY: { type: "number" },
+              maxX: { type: "number" },
+              maxY: { type: "number" },
+            },
+            required: ["minX", "minY", "maxX", "maxY"],
+          },
         },
-        required: ["x", "y", "width", "height"],
+        required: ["bounds"],
+      },
+      properties: {
+        type: "object",
+        properties: { value: { type: "string", const: "face" } },
+        required: ["value"],
       },
-      label: { type: "string", const: "face" },
     },
-    required: ["boundingBox", "label"],
+    required: ["id", "type", "geometry", "properties"],
   },
 };
 

package/examples/face-image-collection/nodes/annotate-faces/node.ts

@@ -55,7 +55,7 @@ export const annotateFaces = generation("annotate_faces", {
   instruction:
     "Draw one tight rectangular bounding box around every visible human face. Do not annotate faces shown only in photographs, posters, or reflections.",
   ui: {
-    code: "<Field.ImageAnnotation path={'draft_faces'} image={actions.get('image_url', '')} tools={['rectangle']} labels={[{ label: 'Face', value: 'face' }]} />",
+    code: "<Field.ImageAnnotation path={'draft_faces'} image={actions.get('image_url')} tools={['rectangle']} labels={[{ label: 'Face', value: 'face', color: 'blue' }]} navigator={true} />",
     data: '{"image_url":"https://example.com/face.jpg"}',
     preprocess: "return {}",
     postprocess: "return {};",
@@ -131,12 +131,4 @@ export const annotateFaces = generation("annotate_faces", {
       successCriteria: "Every face has one tight bounding box",
     },
   },
-  exam: {
-    enabled: false,
-    gradedEntities: [],
-    tasksPerExpert: 1,
-    passThreshold: 1,
-  },
-  reuseAudienceWithNodeId: null,
-  smartSearch: null,
 });

package/examples/face-image-collection/nodes/order-faces/node.ts

@@ -9,17 +9,15 @@ export const orderFaces = code("order_faces", {
       "Order face annotations from top left to bottom right for deterministic downstream data.",
   },
   envVars: [],
-  fieldProxies: {
-    input: [{ field: draftFaces, optional: false }],
-    output: [{ field: faces, optional: false }],
-  },
+  input: [{ field: draftFaces, optional: false }],
+  output: [{ field: faces, optional: false }],
   code: {
     code: `from main_types import Inputs, Outputs
 
 async def main(inputs: Inputs) -> Outputs:
     ordered_faces = sorted(
         inputs["draft_faces"],
-        key=lambda face: (face["boundingBox"]["y"], face["boundingBox"]["x"]),
+        key=lambda face: (face["geometry"]["bounds"]["minY"], face["geometry"]["bounds"]["minX"]),
     )
     return {"faces": ordered_faces}`,
   },

package/examples/face-image-collection/pipeline.browser.integration.spec.ts

@@ -0,0 +1,78 @@
+import { expect, test } from "@toloka-platform/sdk/testing";
+import { describe } from "vitest";
+import { assert } from "es-toolkit";
+import type { TaskUiSession } from "@toloka-platform/sdk/testing";
+
+import pipeline from "./pipeline";
+import { annotateFaces } from "./nodes/annotate-faces/node";
+import { orderFaces } from "./nodes/order-faces/node";
+const upperFace = {
+  id: "upper-face",
+  type: "RECTANGLE",
+  geometry: { x: 40, y: 10, w: 20, h: 20, bounds: { minX: 40, minY: 10, maxX: 60, maxY: 30 } },
+  properties: { value: "face" },
+};
+const lowerFace = {
+  id: "lower-face",
+  type: "RECTANGLE",
+  geometry: { x: 10, y: 60, w: 30, h: 30, bounds: { minX: 10, minY: 60, maxX: 40, maxY: 90 } },
+  properties: { value: "face" },
+};
+const imageUrl =
+  "https://tlkfrontprod.azureedge.net/frontend-testing/static/gzarip/cats/cat_001.jpg";
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value);
+
+const documentedFaceAnnotations = async (
+  session: TaskUiSession,
+): Promise<Record<string, unknown>[]> => {
+  const documentation = await session.componentDocumentation(["Field.ImageAnnotation"]);
+  const output = documentation["Field.ImageAnnotation"]?.example?.output;
+  assert(output, "Field.ImageAnnotation has no documented example output");
+  const example: unknown = JSON.parse(output);
+  assert(isRecord(example), "Field.ImageAnnotation example output is not an object");
+  const annotations = example.roi;
+  assert(Array.isArray(annotations), "Field.ImageAnnotation example output has no roi array");
+  return annotations.map((annotation) => {
+    assert(isRecord(annotation), "Field.ImageAnnotation example contains a non-object value");
+    assert(
+      isRecord(annotation.properties),
+      "Field.ImageAnnotation example annotation has no properties",
+    );
+    return {
+      ...annotation,
+      properties: { ...annotation.properties, value: "face" },
+    };
+  });
+};
+
+describe("face image collection example", () => {
+  test.code(pipeline, orderFaces, "orders faces from top to bottom", async ({ run }) => {
+    await expect(run({ draft_faces: [lowerFace, upperFace] })).resolves.toEqual({
+      faces: [upperFace, lowerFace],
+    });
+  });
+
+  test.ui(pipeline, annotateFaces, "submits face annotations", async ({ render }) => {
+    const session = await render({ data: { image_url: imageUrl, draft_faces: [] } });
+    const annotations = await documentedFaceAnnotations(session);
+    await session.setValue("draft_faces", annotations);
+
+    expect(await session.getValue("draft_faces")).toEqual(annotations);
+    await expect(session.submit()).resolves.toMatchObject({ draft_faces: annotations });
+    await session.close();
+  });
+
+  test.pipeline(pipeline, "collects and orders face annotations", async ({ renderUi, runCode }) => {
+    const session = await renderUi(annotateFaces, {
+      data: { image_url: imageUrl, draft_faces: [] },
+    });
+    await session.setValue("draft_faces", [lowerFace, upperFace]);
+    const annotation = await session.submit();
+    const result = await runCode(orderFaces, { draft_faces: annotation.draft_faces });
+
+    expect(result).toEqual({ faces: [upperFace, lowerFace] });
+    await session.close();
+  });
+});

package/examples/video-pair-rating/README.md

@@ -33,12 +33,12 @@ Sixteen nodes: one root, eight `code`, three `match`, two `generation`, two `quo
 
 ## What to read first
 
-| file | why |
-|---|---|
-| `pipeline.ts` | the whole topology on one screen — every edge is explicit |
-| `nodes/cascade/node.ts` | the deterministic core that resolves every metric from rater arrays |
-| `nodes/rate_pair/node.ts` | a quorum node with real quality criteria and a Training course |
-| `nodes/route_overall/node.ts` | predicate routing, and what the `default` branch is for |
+| file                          | why                                                                 |
+| ----------------------------- | ------------------------------------------------------------------- |
+| `pipeline.ts`                 | the whole topology on one screen — every edge is explicit           |
+| `nodes/cascade/node.ts`       | the deterministic core that resolves every metric from rater arrays |
+| `nodes/rate_pair/node.ts`     | a quorum node with real quality criteria and a Training course      |
+| `nodes/route_overall/node.ts` | predicate routing, and what the `default` branch is for             |
 
 ## Conventions this example demonstrates
 
@@ -52,6 +52,14 @@ Sixteen nodes: one root, eight `code`, three `match`, two `generation`, two `quo
 
 **Adjudication is a branch, not a loop.** The graph stays acyclic. Redo, appeal, and payment retry live inside the human-work nodes; only the tie-breaking hand-off is a graph edge.
 
+## Check locally
+
+The shipped typed scenarios cover all eight code nodes, all four Task UIs, and an agreed-pair connected flow:
+
+```sh
+toloka check video-pair-rating
+```
+
 ## Provenance
 
 The topology, the resolution cascade, and the per-node layout are adapted from a design spike by @hexode. Media URLs, sample payloads, prompts, and prose here are synthetic: no customer data, project identifiers, or asset URLs from the original are carried over.

package/examples/video-pair-rating/nodes/adjudicate/node.ts

@@ -64,7 +64,7 @@ export const adjudicate = generation("adjudicate", {
     },
   ],
   ui: {
-    code: "<View.Group><If condition={actions.get('disagreed_metrics', []).includes('image_text_alignment')}><Field.SelectGroup path={'adjudicated_metrics.image_text_alignment'} label={'Imagery matches the prompt'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If><If condition={actions.get('disagreed_metrics', []).includes('motion_text_alignment')}><Field.SelectGroup path={'adjudicated_metrics.motion_text_alignment'} label={'Motion matches the prompt'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If><If condition={actions.get('disagreed_metrics', []).includes('image_quality')}><Field.SelectGroup path={'adjudicated_metrics.image_quality'} label={'Image quality'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If><If condition={actions.get('disagreed_metrics', []).includes('motion_quality')}><Field.SelectGroup path={'adjudicated_metrics.motion_quality'} label={'Motion quality'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If><If condition={actions.get('disagreed_metrics', []).includes('subject_background_consistency')}><Field.SelectGroup path={'adjudicated_metrics.subject_background_consistency'} label={'Subject and background consistency'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If><If condition={actions.get('disagreed_metrics', []).includes('video_realism')}><Field.SelectGroup path={'adjudicated_metrics.video_realism'} label={'Realism'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} /></If></View.Group>",
+    code: "<View.Card>{actions.get('disagreed_metrics', []).includes('image_text_alignment') && <Field.RadioGroup path={'adjudicated_metrics.image_text_alignment'} label={'Imagery matches the prompt'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} />}{actions.get('disagreed_metrics', []).includes('motion_text_alignment') && <Field.RadioGroup path={'adjudicated_metrics.motion_text_alignment'} label={'Motion matches the prompt'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} />}{actions.get('disagreed_metrics', []).includes('image_quality') && <Field.RadioGroup path={'adjudicated_metrics.image_quality'} label={'Image quality'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} />}{actions.get('disagreed_metrics', []).includes('motion_quality') && <Field.RadioGroup path={'adjudicated_metrics.motion_quality'} label={'Motion quality'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} />}{actions.get('disagreed_metrics', []).includes('subject_background_consistency') && <Field.RadioGroup path={'adjudicated_metrics.subject_background_consistency'} label={'Subject and background consistency'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} />}{actions.get('disagreed_metrics', []).includes('video_realism') && <Field.RadioGroup path={'adjudicated_metrics.video_realism'} label={'Realism'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} />}</View.Card>",
     data: '{"prompt":"a red fox crossing a snowy field at dawn","video_a":"https://example.com/video-a.mp4","video_b":"https://example.com/video-b.mp4","disagreed_metrics":["image_quality","motion_quality"]}',
     preprocess: "return {}",
     postprocess: "return {};",
@@ -157,6 +157,4 @@ export const adjudicate = generation("adjudicate", {
     perExpertCapEnabled: false,
     perExpertCapValue: 1,
   },
-  reuseAudienceWithNodeId: null,
-  smartSearch: null,
 });

package/examples/video-pair-rating/nodes/adjudicate_op/node.ts

@@ -50,7 +50,7 @@ export const adjudicateOp = generation("adjudicate_op", {
     },
   ],
   ui: {
-    code: "<Field.SelectGroup path={'op_adjudicated_value'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} />",
+    code: "<Field.RadioGroup path={'op_adjudicated_value'} options={[{ label: 'First video', value: 'video_a' }, { label: 'Second video', value: 'video_b' }, { label: 'Tie', value: 'tie' }]} />",
     data: '{"prompt":"a red fox crossing a snowy field at dawn","video_a":"https://example.com/video-a.mp4","video_b":"https://example.com/video-b.mp4"}',
     preprocess: "return {}",
     postprocess: "return {};",
@@ -147,6 +147,4 @@ export const adjudicateOp = generation("adjudicate_op", {
     perExpertCapEnabled: false,
     perExpertCapValue: 1,
   },
-  reuseAudienceWithNodeId: null,
-  smartSearch: null,
 });

package/examples/video-pair-rating/nodes/adjudication_match/node.ts

@@ -20,23 +20,21 @@ export const adjudicationMatch = code("adjudication_match", {
       "Computes per-rater matches_adjudication booleans for image_text_alignment, image_quality, and overall preference. Only populated when adjudication actually ran; otherwise null.",
   },
   envVars: [],
-  fieldProxies: {
-    input: [
-      { field: raterItaVotes, optional: false },
-      { field: raterIqVotes, optional: false },
-      { field: raterOpVotes, optional: true },
-      { field: disagreedMetrics, optional: false },
-      { field: finalMetrics, optional: false },
-      { field: needsOverallManual, optional: false },
-      { field: opNeedsAdjudication, optional: true },
-      { field: finalOpValue, optional: true },
-    ],
-    output: [
-      { field: raterItaMatchesAdjudication, optional: false },
-      { field: raterIqMatchesAdjudication, optional: false },
-      { field: raterOpMatchesAdjudication, optional: false },
-    ],
-  },
+  input: [
+    { field: raterItaVotes, optional: false },
+    { field: raterIqVotes, optional: false },
+    { field: raterOpVotes, optional: true },
+    { field: disagreedMetrics, optional: false },
+    { field: finalMetrics, optional: false },
+    { field: needsOverallManual, optional: false },
+    { field: opNeedsAdjudication, optional: true },
+    { field: finalOpValue, optional: true },
+  ],
+  output: [
+    { field: raterItaMatchesAdjudication, optional: false },
+    { field: raterIqMatchesAdjudication, optional: false },
+    { field: raterOpMatchesAdjudication, optional: false },
+  ],
   code: {
     code: `from main_types import Inputs, Outputs
 

package/examples/video-pair-rating/nodes/assemble/node.ts

@@ -8,32 +8,30 @@ export const assemble = code("assemble", {
       "Assembles the final JSONL delivery record containing all evaluation results: video identifiers, text prompt, per-metric scores, overall preference, annotator metadata, resolution method, rater vote history, and a UTC timestamp.",
   },
   envVars: [],
-  fieldProxies: {
-    input: [
-      { field: f.recordId, optional: false },
-      { field: f.prompt, optional: false },
-      { field: f.videoA, optional: false },
-      { field: f.videoB, optional: false },
-      { field: f.finalMetrics, optional: false },
-      { field: f.overallPreference, optional: false },
-      { field: f.overallPreferenceSource, optional: false },
-      { field: f.resolutionMethod, optional: false },
-      { field: f.annotatorIdAdjudicator, optional: false },
-      { field: f.raterItaVotes, optional: false },
-      { field: f.raterMtaVotes, optional: false },
-      { field: f.raterIqVotes, optional: false },
-      { field: f.raterMqVotes, optional: false },
-      { field: f.raterSbcVotes, optional: false },
-      { field: f.raterVrVotes, optional: false },
-      { field: f.raterOpVotes, optional: true },
-      { field: f.raterDurationSeconds, optional: true },
-      { field: f.raterBothPlayed, optional: true },
-      { field: f.raterItaMatchesAdjudication, optional: false },
-      { field: f.raterIqMatchesAdjudication, optional: false },
-      { field: f.raterOpMatchesAdjudication, optional: false },
-    ],
-    output: [{ field: f.deliveryRecord, optional: false }],
-  },
+  input: [
+    { field: f.recordId, optional: false },
+    { field: f.prompt, optional: false },
+    { field: f.videoA, optional: false },
+    { field: f.videoB, optional: false },
+    { field: f.finalMetrics, optional: false },
+    { field: f.overallPreference, optional: false },
+    { field: f.overallPreferenceSource, optional: false },
+    { field: f.resolutionMethod, optional: false },
+    { field: f.annotatorIdAdjudicator, optional: false },
+    { field: f.raterItaVotes, optional: false },
+    { field: f.raterMtaVotes, optional: false },
+    { field: f.raterIqVotes, optional: false },
+    { field: f.raterMqVotes, optional: false },
+    { field: f.raterSbcVotes, optional: false },
+    { field: f.raterVrVotes, optional: false },
+    { field: f.raterOpVotes, optional: true },
+    { field: f.raterDurationSeconds, optional: true },
+    { field: f.raterBothPlayed, optional: true },
+    { field: f.raterItaMatchesAdjudication, optional: false },
+    { field: f.raterIqMatchesAdjudication, optional: false },
+    { field: f.raterOpMatchesAdjudication, optional: false },
+  ],
+  output: [{ field: f.deliveryRecord, optional: false }],
   code: {
     code: `from datetime import datetime, timezone
 from main_types import Inputs, Outputs
@@ -60,7 +58,7 @@ async def main(inputs: Inputs) -> Outputs:
         "video_realism": final_metrics.get("video_realism"),
         "video_image_text_alignment": final_metrics.get("image_text_alignment"),
         "video_motion_text_alignment": final_metrics.get("motion_text_alignment"),
-        # Platform limitation: rater ids are not surfaced as field proxies
+        # Platform limitation: rater ids are not surfaced as output fields
         # from the quorum node in this pilot. Stubs preserve schema conformance.
         "annotator_id_1": None,
         "annotator_id_2": None,

package/examples/video-pair-rating/nodes/cascade/node.ts

@@ -8,32 +8,30 @@ export const cascade = code("cascade", {
       "Un-swaps each rater per-metric vote back to canonical video_a/video_b/tie labels using the swap flag. Computes per-metric majority agreement and flags metrics requiring adjudication. Applies a deterministic Overall Preference cascade: image-text alignment decides first, then image quality, falling back to manual review.",
   },
   envVars: [],
-  fieldProxies: {
-    input: [
-      { field: f.swap, optional: false },
-      { field: f.imageTextAlignment, optional: false },
-      { field: f.motionTextAlignment, optional: false },
-      { field: f.imageQuality, optional: false },
-      { field: f.motionQuality, optional: false },
-      { field: f.subjectBackgroundConsistency, optional: false },
-      { field: f.videoRealism, optional: false },
-    ],
-    output: [
-      { field: f.perMetricResolved, optional: false },
-      { field: f.needsAdjudication, optional: false },
-      { field: f.disagreedTask, optional: false },
-      { field: f.disagreedMetrics, optional: false },
-      { field: f.opValueOrNull, optional: false },
-      { field: f.opSource, optional: false },
-      { field: f.needsOverallManual, optional: false },
-      { field: f.raterItaVotes, optional: false },
-      { field: f.raterMtaVotes, optional: false },
-      { field: f.raterIqVotes, optional: false },
-      { field: f.raterMqVotes, optional: false },
-      { field: f.raterSbcVotes, optional: false },
-      { field: f.raterVrVotes, optional: false },
-    ],
-  },
+  input: [
+    { field: f.swap, optional: false },
+    { field: f.imageTextAlignment, optional: false },
+    { field: f.motionTextAlignment, optional: false },
+    { field: f.imageQuality, optional: false },
+    { field: f.motionQuality, optional: false },
+    { field: f.subjectBackgroundConsistency, optional: false },
+    { field: f.videoRealism, optional: false },
+  ],
+  output: [
+    { field: f.perMetricResolved, optional: false },
+    { field: f.needsAdjudication, optional: false },
+    { field: f.disagreedTask, optional: false },
+    { field: f.disagreedMetrics, optional: false },
+    { field: f.opValueOrNull, optional: false },
+    { field: f.opSource, optional: false },
+    { field: f.needsOverallManual, optional: false },
+    { field: f.raterItaVotes, optional: false },
+    { field: f.raterMtaVotes, optional: false },
+    { field: f.raterIqVotes, optional: false },
+    { field: f.raterMqVotes, optional: false },
+    { field: f.raterSbcVotes, optional: false },
+    { field: f.raterVrVotes, optional: false },
+  ],
   code: {
     code: `from main_types import Inputs, Outputs
 

package/examples/video-pair-rating/nodes/finalize_overall/node.ts

@@ -8,25 +8,23 @@ export const finalizeOverall = code("finalize_overall", {
       "Combines cascade-derived and manually adjudicated Overall Preference into the final output. Re-runs the cascade against post-adjudication metrics and falls back to the manual quorum majority vote when both cascade tiers are tied.",
   },
   envVars: [],
-  fieldProxies: {
-    input: [
-      { field: f.opValueOrNull, optional: true },
-      { field: f.opSource, optional: false },
-      { field: f.needsOverallManual, optional: false },
-      { field: f.finalMetrics, optional: false },
-      { field: f.finalOpValue, optional: true },
-      { field: f.finalOpResolutionMethod, optional: true },
-      { field: f.finalOpAdjudicatorId, optional: true },
-      { field: f.resolutionMethod, optional: false },
-      { field: f.annotatorIdAdjudicator, optional: true },
-    ],
-    output: [
-      { field: f.overallPreference, optional: false },
-      { field: f.overallPreferenceSource, optional: false },
-      { field: f.resolutionMethod, optional: false },
-      { field: f.annotatorIdAdjudicator, optional: false },
-    ],
-  },
+  input: [
+    { field: f.opValueOrNull, optional: true },
+    { field: f.opSource, optional: false },
+    { field: f.needsOverallManual, optional: false },
+    { field: f.finalMetrics, optional: false },
+    { field: f.finalOpValue, optional: true },
+    { field: f.finalOpResolutionMethod, optional: true },
+    { field: f.finalOpAdjudicatorId, optional: true },
+    { field: f.resolutionMethod, optional: false },
+    { field: f.annotatorIdAdjudicator, optional: true },
+  ],
+  output: [
+    { field: f.overallPreference, optional: false },
+    { field: f.overallPreferenceSource, optional: false },
+    { field: f.resolutionMethod, optional: false },
+    { field: f.annotatorIdAdjudicator, optional: false },
+  ],
   code: {
     code: `from main_types import Inputs, Outputs
 

package/examples/video-pair-rating/nodes/merge_adjudication/node.ts

@@ -18,21 +18,19 @@ export const mergeAdjudication = code("merge_adjudication", {
       "Merges majority-vote per-metric resolutions from the cascade with adjudicator overrides on disagreed metrics into final_metrics. Also stamps annotator_id_adjudicator and resolution_method.",
   },
   envVars: [],
-  fieldProxies: {
-    input: [
-      { field: perMetricResolved, optional: false },
-      { field: adjudicatedMetrics, optional: true },
-      { field: disagreedMetrics, optional: true },
-    ],
-    output: [
-      { field: finalMetrics, optional: false },
-      { field: resolutionMethod, optional: false },
-      { field: annotatorIdAdjudicator, optional: false },
-      { field: opValueOrNull, optional: false },
-      { field: opSource, optional: false },
-      { field: needsOverallManual, optional: false },
-    ],
-  },
+  input: [
+    { field: perMetricResolved, optional: false },
+    { field: adjudicatedMetrics, optional: true },
+    { field: disagreedMetrics, optional: true },
+  ],
+  output: [
+    { field: finalMetrics, optional: false },
+    { field: resolutionMethod, optional: false },
+    { field: annotatorIdAdjudicator, optional: false },
+    { field: opValueOrNull, optional: false },
+    { field: opSource, optional: false },
+    { field: needsOverallManual, optional: false },
+  ],
   code: {
     code: `from main_types import Inputs, Outputs