feat(processing): pack labelmap inputs by multiplicity and label count

backend-contract/README.md

@@ -109,9 +109,28 @@ Two versions on separate clocks:
 - **Artifact version**: `package.json` `version` and the OpenAPI
   `info.version`, kept in lockstep by `processing/__tests__/openapi.spec.ts`.
   Versions this package as a published thing.
-- **Shape versions**: `INTENT_VOCABULARY_VERSION` (`processing/wire.ts`) and
-  the task-spec `specVersion`. These version the wire vocabulary for additive
-  compatibility negotiation.
+- **Shape versions**: `INTENT_VOCABULARY_VERSION` (`processing/wire.ts`) names
+  the shape of the result intent vocabulary in the generated OpenAPI
+  description and in release notes. It never travels on the wire, so adding an
+  intent rests on both sides failing open on a name they do not know. The
+  task-spec `specVersion` does travel: every task spec carries it, and a client
+  rejects a spec whose version it does not know. Bump it only on a shape
+  change, never for a new optional field.
+
+### Result instruction rollout
+
+Contract artifact 0.3.0 uses intent vocabulary 3 and names segmentation import
+`import-segmentation`. A current client still reads the earlier name,
+`add-segment-group`, as the same instruction (`LEGACY_RESULT_INTENT_NAMES` in
+`processing/wire.ts`), so a producer may move to the new name after the client.
+The reverse order does not hold: an older client treats `import-segmentation`
+as an ordinary result and will not apply its segmentation automatically.
+Update Girder's pinned VolView package before the producer emits the new name.
+
+This vocabulary change does not change task-spec versions or saved-session
+schemas. Girder projects stored job outputs into current instructions when
+results are requested; stored output references and mask provenance keep their
+identities.
 
 ## Regenerating
 

backend-contract/fixtures/negative/wrong-length-color.json

@@ -1,6 +1,6 @@
 {
   "id": "6600000000000000000000e1",
-  "intent": "add-segment-group",
+  "intent": "import-segmentation",
   "url": "/api/v1/file/6600000000000000000000e1/proxiable/otsu.nii.gz",
   "name": "otsu.nii.gz",
   "segments": [

backend-contract/fixtures/wire/intent.add-segment-group.embedded.json → backend-contract/fixtures/wire/intent.import-segmentation.embedded.json

@@ -1,6 +1,6 @@
 {
   "id": "6600000000000000000000e2",
-  "intent": "add-segment-group",
+  "intent": "import-segmentation",
   "url": "/api/v1/file/6600000000000000000000e2/proxiable/threshold.seg.nrrd",
   "name": "threshold.seg.nrrd",
   "source": {

backend-contract/fixtures/wire/intent.add-segment-group.with-segments.json → backend-contract/fixtures/wire/intent.import-segmentation.with-segments.json

@@ -1,6 +1,6 @@
 {
   "id": "6600000000000000000000e1",
-  "intent": "add-segment-group",
+  "intent": "import-segmentation",
   "url": "/api/v1/file/6600000000000000000000e1/proxiable/otsu.nii.gz",
   "name": "otsu.nii.gz",
   "segments": [

backend-contract/generated/job-results.schema.json

@@ -114,7 +114,7 @@
                 "properties": {
                   "intent": {
                     "type": "string",
-                    "const": "add-segment-group"
+                    "const": "import-segmentation"
                   },
                   "id": {
                     "type": "string",
@@ -155,10 +155,12 @@
                         "value": {
                           "type": "integer",
                           "minimum": 1,
-                          "maximum": 9007199254740991
+                          "maximum": 9007199254740991,
+                          "description": "The label value, from 1 to 65535; 0 is background. The client stores labels in at most 16 bits: voxels holding a larger value import as background with a warning, and a segment declared with one arrives empty."
                         },
                         "name": {
-                          "type": "string"
+                          "type": "string",
+                          "description": "Binds the segment by exact name. A segment the client already holds under this name, with no mask on the target image yet, takes these voxels and keeps its own color and visibility. Otherwise the client creates a segment from this descriptor, with a numbered name when the existing one already has a mask on that image."
                         },
                         "color": {
                           "minItems": 4,

backend-contract/generated/openapi.json

@@ -3,8 +3,8 @@
   "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
   "info": {
     "title": "VolView neutral backend contract",
-    "version": "0.2.0",
-    "description": "DRAFT 0.x — shapes may change until a second backend passes the conformance kit (the pinned 1.0 criterion). The neutral REST surface the VolView client calls to run processing tasks against a backend. A conforming server-side BACKEND implements these endpoints and the referenced wire schemas — no VolView client change is needed to bring a new backend online. Everything here is neutral: no backend routes, ids, status enums, or URL shapes leak. The artifact version is the draft artifact version, distinct from the shape versions: the result-intent vocabulary is at version 2 (INTENT_VOCABULARY_VERSION); the task-spec shape at version 1 (specVersion)."
+    "version": "0.3.0",
+    "description": "DRAFT 0.x — shapes may change until a second backend passes the conformance kit (the pinned 1.0 criterion). The neutral REST surface the VolView client calls to run processing tasks against a backend. A conforming server-side BACKEND implements these endpoints and the referenced wire schemas — no VolView client change is needed to bring a new backend online. Everything here is neutral: no backend routes, ids, status enums, or URL shapes leak. The artifact version is the draft artifact version, distinct from the shape versions: the result-intent vocabulary is at version 3 (INTENT_VOCABULARY_VERSION); the task-spec shape at version 1 (specVersion)."
   },
   "servers": [
     {
@@ -347,7 +347,7 @@
         ],
         "responses": {
           "200": {
-            "description": "The resolved results as the { resultState, intents, missing } envelope (JobResults). Each entry of `intents` is a ResultIntent — a result row carrying a required `id` display key and required `name`/`url`, plus optional/null `mimeType`/`size` file metadata. `missing` counts declared outputs that never arrived plus recorded outputs that cannot be read. Total loss is a valid incomplete response with an empty intents array.",
+            "description": "The resolved results as the { resultState, intents, missing } envelope (JobResults). Each entry of `intents` is a ResultIntent — a result row carrying a required `id` display key, unique within the job, and required `name`/`url`, plus optional/null `mimeType`/`size` file metadata. `missing` counts declared outputs that never arrived plus recorded outputs that cannot be read. Total loss is a valid incomplete response with an empty intents array.",
             "content": {
               "application/json": {
                 "schema": {
@@ -896,7 +896,8 @@
               "name",
               "referenceImage"
             ],
-            "additionalProperties": false
+            "additionalProperties": false,
+            "description": "The staged bytes are a `.seg.nrrd` labelmap on the reference image's voxel grid. Label values run from 1 to N within each file, in the client's segment order, with 0 as background. Voxels are unsigned 8-bit for up to 255 labels and unsigned 16-bit beyond. Segment names and colors ride in the header."
           },
           {
             "type": "object",
@@ -1203,7 +1204,7 @@
                 "properties": {
                   "intent": {
                     "type": "string",
-                    "const": "add-segment-group"
+                    "const": "import-segmentation"
                   },
                   "id": {
                     "type": "string",
@@ -1244,10 +1245,12 @@
                         "value": {
                           "type": "integer",
                           "minimum": 1,
-                          "maximum": 9007199254740991
+                          "maximum": 9007199254740991,
+                          "description": "The label value, from 1 to 65535; 0 is background. The client stores labels in at most 16 bits: voxels holding a larger value import as background with a warning, and a segment declared with one arrives empty."
                         },
                         "name": {
-                          "type": "string"
+                          "type": "string",
+                          "description": "Binds the segment by exact name. A segment the client already holds under this name, with no mask on the target image yet, takes these voxels and keeps its own color and visibility. Otherwise the client creates a segment from this descriptor, with a numbered name when the existing one already has a mask on that image."
                         },
                         "color": {
                           "minItems": 4,

backend-contract/generated/result-intent.schema.json

@@ -102,7 +102,7 @@
           "properties": {
             "intent": {
               "type": "string",
-              "const": "add-segment-group"
+              "const": "import-segmentation"
             },
             "id": {
               "type": "string",
@@ -143,10 +143,12 @@
                   "value": {
                     "type": "integer",
                     "minimum": 1,
-                    "maximum": 9007199254740991
+                    "maximum": 9007199254740991,
+                    "description": "The label value, from 1 to 65535; 0 is background. The client stores labels in at most 16 bits: voxels holding a larger value import as background with a warning, and a segment declared with one arrives empty."
                   },
                   "name": {
-                    "type": "string"
+                    "type": "string",
+                    "description": "Binds the segment by exact name. A segment the client already holds under this name, with no mask on the target image yet, takes these voxels and keeps its own color and visibility. Otherwise the client creates a segment from this descriptor, with a numbered name when the existing one already has a mask on that image."
                   },
                   "color": {
                     "minItems": 4,

backend-contract/generated/stage-input-descriptor.schema.json

@@ -42,7 +42,8 @@
         "name",
         "referenceImage"
       ],
-      "additionalProperties": false
+      "additionalProperties": false,
+      "description": "The staged bytes are a `.seg.nrrd` labelmap on the reference image's voxel grid. Label values run from 1 to N within each file, in the client's segment order, with 0 as background. Voxels are unsigned 8-bit for up to 255 labels and unsigned 16-bit beyond. Segment names and colors ride in the header."
     },
     {
       "type": "object",

backend-contract/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@volview/backend-contract",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "private": true
 }

backend-contract/processing/__tests__/wire.spec.ts

@@ -15,6 +15,7 @@ import {
   jobHistoryDetailSchema,
   jobResultsSchema,
   jobResultsErrorSchema,
+  currentResultIntentName,
 } from '../wire';
 import { loadFixture, loadFixtureDir } from './loadFixtures';
 
@@ -193,13 +194,28 @@ describe('neutral job status fixtures', () => {
 // Result intents
 // ---------------------------------------------------------------------------
 
+describe('currentResultIntentName', () => {
+  it('reads the earlier segmentation import name as the current one', () => {
+    expect(currentResultIntentName('add-segment-group')).toBe(
+      'import-segmentation'
+    );
+  });
+
+  it.each(['toString', 'constructor', '__proto__', 'add-mesh'])(
+    'passes %s through unchanged',
+    (intent) => {
+      expect(currentResultIntentName(intent)).toBe(intent);
+    }
+  );
+});
+
 describe('result intent fixtures', () => {
-  it('exports vocabulary version 2 and the exactly-four state intents', () => {
-    expect(INTENT_VOCABULARY_VERSION).toBe(2);
+  it('exports vocabulary version 3 and the exactly-four state intents', () => {
+    expect(INTENT_VOCABULARY_VERSION).toBe(3);
     expect([...RESULT_INTENTS]).toEqual([
       'add-base-image',
       'add-layer',
-      'add-segment-group',
+      'import-segmentation',
       'add-annotations',
     ]);
     expect(wire).not.toHaveProperty('intent.download');
@@ -208,8 +224,8 @@ describe('result intent fixtures', () => {
   it.each([
     'intent.add-base-image',
     'intent.add-layer',
-    'intent.add-segment-group.with-segments',
-    'intent.add-segment-group.embedded',
+    'intent.import-segmentation.with-segments',
+    'intent.import-segmentation.embedded',
     'intent.add-annotations',
     'intent.unknown',
   ])('validates %s', (name) => {
@@ -253,11 +269,11 @@ describe('result intent fixtures', () => {
     ).toBe(false);
   });
 
-  it('parses add-segment-group WITH segments and a source provenance tag', () => {
+  it('parses import-segmentation WITH segments and a source provenance tag', () => {
     const parsed = resultIntentSchema.parse(
-      wire['intent.add-segment-group.with-segments']
+      wire['intent.import-segmentation.with-segments']
     ) as Record<string, unknown>;
-    expect(parsed.intent).toBe('add-segment-group');
+    expect(parsed.intent).toBe('import-segmentation');
     expect(Array.isArray(parsed.segments)).toBe(true);
     expect(parsed.source).toEqual({
       providerId: 'analysis-provider',
@@ -266,18 +282,18 @@ describe('result intent fixtures', () => {
     });
   });
 
-  it('parses add-segment-group WITHOUT segments (embedded metadata) but with source', () => {
+  it('parses import-segmentation WITHOUT segments (embedded metadata) but with source', () => {
     const parsed = resultIntentSchema.parse(
-      wire['intent.add-segment-group.embedded']
+      wire['intent.import-segmentation.embedded']
     ) as Record<string, unknown>;
-    expect(parsed.intent).toBe('add-segment-group');
+    expect(parsed.intent).toBe('import-segmentation');
     expect(parsed.segments).toBeUndefined();
     expect(parsed.source).toMatchObject({ outputId: 'outputLabelmap' });
   });
 
-  it('rejects a segment-group source without provider identity', () => {
+  it('rejects a segmentation source without provider identity', () => {
     const value = structuredClone(
-      wire['intent.add-segment-group.with-segments']
+      wire['intent.import-segmentation.with-segments']
     ) as { source: { providerId?: string } };
     delete value.source.providerId;
     expect(knownResultIntentSchema.safeParse(value).success).toBe(false);
@@ -364,16 +380,14 @@ describe('result intent fixtures', () => {
   });
 
   it('rejects a wrong-length segment color (the tuple-length parity pin)', () => {
-    // The negative fixture carries a 3-element color. The STRICT union must
-    // reject it — and the generated JSON Schema must agree (backend side:
-    // test_contract_fixtures.py), so both validators close fixed-length
-    // tuples identically. The full union still accepts the row, demoted to an
-    // ordinary result with no state action (the designed fail-open).
+    // Only the strict known-intent union rejects the 3-element color; the
+    // published result-intent schema accepts the row and demotes it to an
+    // ordinary result with no state action.
     const short = loadFixture('negative/wrong-length-color.json');
     expect(knownResultIntentSchema.safeParse(short).success).toBe(false);
     expect(resultIntentSchema.safeParse(short).success).toBe(true);
 
-    const good = wire['intent.add-segment-group.with-segments'] as {
+    const good = wire['intent.import-segmentation.with-segments'] as {
       segments: { color: number[] }[];
     };
     const long = structuredClone(good);

backend-contract/processing/annotations.ts

@@ -1,6 +1,9 @@
 // Vector annotations staged into a task or returned as a result. Coordinates
-// are world LPS millimeters. Tool records exclude session identity and state;
-// labels are namespaced by tool kind because the client stores are independent.
+// are world LPS millimeters. Tool records exclude session identity and state.
+// Labels are namespaced by tool kind on the wire, but the client binds every
+// kind into one segment registry by name: a name repeated across kinds is one
+// segment, the first kind to bind a new name (rulers, rectangles, polygons)
+// sets its style, and a label no tool references creates nothing.
 // Unknown envelope fields survive round-trip without gaining behavior.
 
 import { z } from 'zod';

backend-contract/processing/openapi.ts

@@ -429,11 +429,11 @@ const paths = (): Record<string, unknown> => ({
           description:
             'The resolved results as the { resultState, intents, missing } envelope ' +
             '(JobResults). Each entry of `intents` is a ResultIntent — a result ' +
-            'row carrying a required `id` display key and required `name`/`url`, ' +
-            'plus optional/null `mimeType`/`size` file metadata. `missing` counts ' +
-            'declared outputs that never arrived plus recorded outputs that cannot ' +
-            'be read. Total loss is a valid incomplete response with an empty ' +
-            'intents array.',
+            'row carrying a required `id` display key, unique within the job, and ' +
+            'required `name`/`url`, plus optional/null `mimeType`/`size` file ' +
+            'metadata. `missing` counts declared outputs that never arrived plus ' +
+            'recorded outputs that cannot be read. Total loss is a valid ' +
+            'incomplete response with an empty intents array.',
           content: json(ref('JobResults')),
         },
         '409': resultReadErrorResponse,
@@ -474,7 +474,7 @@ export const buildOpenApiDocument = (): Record<string, unknown> => ({
     // VERSION / specVersion) below. It is deliberately literal, not derived from
     // the shape-version constants — the artifact and the shapes version on
     // separate clocks.
-    version: '0.2.0',
+    version: '0.3.0',
     description:
       'DRAFT 0.x — shapes may change until a second backend passes the ' +
       'conformance kit (the pinned 1.0 criterion). ' +