Add the segment model and segmentation workflows

.github/workflows/checks.yml

@@ -9,6 +9,10 @@ jobs:
     name: Code check and tests
     steps:
       - uses: actions/checkout@v4
+        with:
+          # The ratchets diff against the merge base with the target branch, so
+          # the checkout needs history rather than a single commit.
+          fetch-depth: 0
       - name: Setup node
         uses: actions/setup-node@v4
         with:
@@ -19,6 +23,16 @@ jobs:
         run: npx prettier --list-different "src/**/*.[jt]s" "tests/**/*.[jt]s" "src/**/*.vue"
       - name: Lint
         run: npm run lint
+      - name: Quality ratchets
+        # On a pull request the checkout is the merge commit, so the merge base
+        # with the target branch is what the change is measured against. The
+        # merge queue has no pull request to read a base from.
+        env:
+          BASE_REF: ${{ github.event.pull_request.base.ref || 'main' }}
+        run: |
+          git fetch --no-tags origin \
+            "+refs/heads/$BASE_REF:refs/remotes/origin/$BASE_REF"
+          node scripts/checks/check.mjs --base "origin/$BASE_REF"
       - name: Tests
         run: npm test
 

backend-contract/README.md

@@ -60,7 +60,11 @@ validate `annotations-file.schema.json`, then enforce
 `validateAnnotationsFileSemantics` — every nonempty `labelName` must be declared
 in its own tool-kind label namespace, which JSON Schema cannot express either.
 Backend conformance tests must also assert that every payload under
-`fixtures/negative/` is rejected by the combined validation path.
+`fixtures/negative/` is rejected by the combined validation path. The one
+exception is `negative/wrong-length-color.json`, which only the strict
+known-intent union rejects: `result-intent.schema.json` is deliberately open,
+so it accepts the row and demotes it to an ordinary result carrying no state
+action.
 
 ## The neutral REST surface (OpenAPI)
 
@@ -106,8 +110,23 @@ Two versions on separate clocks:
   `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.
+  the task-spec `specVersion`. These name the shape of the wire vocabulary in
+  the generated OpenAPI description and in release notes. Neither travels on
+  the wire, so neither is negotiated: additive compatibility rests on both
+  sides failing open on a value they do not know.
+
+### Result instruction rollout
+
+Contract artifact 0.3.0 uses intent vocabulary 3 and names segmentation import
+`import-segmentation`. Deploy the updated producer and VolView client together.
+An older client treats the unfamiliar instruction as an ordinary result and
+will not apply its segmentation automatically. Update Girder's pinned VolView
+package when releasing the paired change.
+
+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/annotations-file.schema.json

@@ -24,6 +24,7 @@
             "type": "object",
             "properties": {
               "color": {
+                "description": "A hex colour such as `#d60000` or a CSS colour keyword such as `lime`. Any other syntax, including functional forms such as `rgb()` and `hsl()`, is ignored: the label keeps the colour the client already holds for it, and the client tells the user the value was rejected.",
                 "type": "string"
               },
               "strokeWidth": {
@@ -46,6 +47,7 @@
             "type": "object",
             "properties": {
               "color": {
+                "description": "A hex colour such as `#d60000` or a CSS colour keyword such as `lime`. Any other syntax, including functional forms such as `rgb()` and `hsl()`, is ignored: the label keeps the colour the client already holds for it, and the client tells the user the value was rejected.",
                 "type": "string"
               },
               "strokeWidth": {
@@ -68,6 +70,7 @@
             "type": "object",
             "properties": {
               "color": {
+                "description": "A hex colour such as `#d60000` or a CSS colour keyword such as `lime`. Any other syntax, including functional forms such as `rgb()` and `hsl()`, is ignored: the label keeps the colour the client already holds for it, and the client tells the user the value was rejected.",
                 "type": "string"
               },
               "strokeWidth": {

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",

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": [
     {
@@ -717,7 +717,7 @@
                       }
                     },
                     "multiple": {
-                      "description": "When true, the parameter takes more than one value: the client sends one staged file per value, listed in `uris` in selection order. When absent or false, it takes a single value. Only labelmap source refs bind plurally today — every group whose parent is the active dataset, in store order; on other type tags the flag has no effect yet.",
+                      "description": "When true, the parameter takes more than one value: the client sends one staged file per value, listed in `uris` in selection order. When absent or false, it takes a single value. For a labelmap input the client stages the active image's segmentation as overlap-free parts: when true, every mask, spread across as many files as it takes for no two masks to share a voxel; when absent or false, only the non-conflicting subset that fits one file, with the remaining masks omitted whole and reported to the user. No mask is ever clipped to fit.",
                       "type": "boolean"
                     }
                   },
@@ -1203,7 +1203,7 @@
                 "properties": {
                   "intent": {
                     "type": "string",
-                    "const": "add-segment-group"
+                    "const": "import-segmentation"
                   },
                   "id": {
                     "type": "string",
@@ -1701,6 +1701,7 @@
                   "type": "object",
                   "properties": {
                     "color": {
+                      "description": "A hex colour such as `#d60000` or a CSS colour keyword such as `lime`. Any other syntax, including functional forms such as `rgb()` and `hsl()`, is ignored: the label keeps the colour the client already holds for it, and the client tells the user the value was rejected.",
                       "type": "string"
                     },
                     "strokeWidth": {
@@ -1723,6 +1724,7 @@
                   "type": "object",
                   "properties": {
                     "color": {
+                      "description": "A hex colour such as `#d60000` or a CSS colour keyword such as `lime`. Any other syntax, including functional forms such as `rgb()` and `hsl()`, is ignored: the label keeps the colour the client already holds for it, and the client tells the user the value was rejected.",
                       "type": "string"
                     },
                     "strokeWidth": {
@@ -1745,6 +1747,7 @@
                   "type": "object",
                   "properties": {
                     "color": {
+                      "description": "A hex colour such as `#d60000` or a CSS colour keyword such as `lime`. Any other syntax, including functional forms such as `rgb()` and `hsl()`, is ignored: the label keeps the colour the client already holds for it, and the client tells the user the value was rejected.",
                       "type": "string"
                     },
                     "strokeWidth": {

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",

backend-contract/generated/task-spec.schema.json

@@ -310,7 +310,7 @@
                 }
               },
               "multiple": {
-                "description": "When true, the parameter takes more than one value: the client sends one staged file per value, listed in `uris` in selection order. When absent or false, it takes a single value. Only labelmap source refs bind plurally today — every group whose parent is the active dataset, in store order; on other type tags the flag has no effect yet.",
+                "description": "When true, the parameter takes more than one value: the client sends one staged file per value, listed in `uris` in selection order. When absent or false, it takes a single value. For a labelmap input the client stages the active image's segmentation as overlap-free parts: when true, every mask, spread across as many files as it takes for no two masks to share a voxel; when absent or false, only the non-conflicting subset that fits one file, with the remaining masks omitted whole and reported to the user. No mask is ever clipped to fit.",
                 "type": "boolean"
               }
             },

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

@@ -194,12 +194,12 @@ describe('neutral job status fixtures', () => {
 // ---------------------------------------------------------------------------
 
 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 +208,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 +253,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 +266,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', () => {
     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);
@@ -373,7 +373,7 @@ describe('result intent fixtures', () => {
     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

@@ -89,7 +89,12 @@ export type WirePolygon = z.infer<typeof wirePolygonSchema>;
 
 // A label's style. Every field is optional: a label may exist purely as a name.
 export const annotationLabelSchema = z.strictObject({
-  color: z.string().optional(),
+  color: z
+    .string()
+    .optional()
+    .describe(
+      'A hex colour such as `#d60000` or a CSS colour keyword such as `lime`. Any other syntax, including functional forms such as `rgb()` and `hsl()`, is ignored: the label keeps the colour the client already holds for it, and the client tells the user the value was rejected.'
+    ),
   strokeWidth: z.number().optional(),
   fillColor: z.string().optional(),
 });

backend-contract/processing/openapi.ts

@@ -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). ' +

backend-contract/processing/task-spec.ts

@@ -136,7 +136,7 @@ const sourceRefParam = z.object({
     .boolean()
     .optional()
     .describe(
-      'When true, the parameter takes more than one value: the client sends one staged file per value, listed in `uris` in selection order. When absent or false, it takes a single value. Only labelmap source refs bind plurally today — every group whose parent is the active dataset, in store order; on other type tags the flag has no effect yet.'
+      "When true, the parameter takes more than one value: the client sends one staged file per value, listed in `uris` in selection order. When absent or false, it takes a single value. For a labelmap input the client stages the active image's segmentation as overlap-free parts: when true, every mask, spread across as many files as it takes for no two masks to share a voxel; when absent or false, only the non-conflicting subset that fits one file, with the remaining masks omitted whole and reported to the user. No mask is ever clipped to fit."
     ),
 });
 

backend-contract/processing/wire.ts

@@ -18,10 +18,14 @@ import {
 } from './task-spec';
 import { pathSegmentIdSchema } from './ids';
 
-// Bump when the intent vocabulary's shape changes so producers and the applier
-// can negotiate compatibility. Adding an intent is a compatible bump: an older
-// client demotes the unknown intent through the fail-open branch above.
-export const INTENT_VOCABULARY_VERSION = 2;
+// A client-side marker for the shape of the intent vocabulary below, bumped
+// when that shape changes. It never travels on the wire: no request header,
+// response field, or schema property carries it, so the two sides never see
+// each other's value and cannot negotiate on it. It names the vocabulary in
+// the generated OpenAPI description and in this package's release notes.
+// Adding an intent stays compatible without it: an older client demotes the
+// unknown intent through the fail-open branch above.
+export const INTENT_VOCABULARY_VERSION = 3;
 
 // ---------------------------------------------------------------------------
 // Input value: what the client sends at submit
@@ -158,7 +162,7 @@ export type NeutralJobStatus = z.infer<typeof neutralJobStatusSchema>;
 export const RESULT_INTENTS = [
   'add-base-image',
   'add-layer',
-  'add-segment-group',
+  'import-segmentation',
   'add-annotations',
 ] as const;
 export type ResultIntentName = (typeof RESULT_INTENTS)[number];
@@ -212,13 +216,13 @@ const addLayer = z
   .object({ intent: z.literal('add-layer'), ...resultListItemSchema.shape })
   .passthrough();
 
-// `add-segment-group` carries OPTIONAL `segments` (the bare-labelmap +
+// `import-segmentation` carries OPTIONAL `segments` (the bare-labelmap +
 // labels-sidecar case; a `seg.nrrd` with embedded metadata carries none — the
 // client uses `segments` when present, else the file's own metadata) and an
 // optional `source` provenance tag (the idempotency key).
 const addSegmentGroup = z
   .object({
-    intent: z.literal('add-segment-group'),
+    intent: z.literal('import-segmentation'),
     ...resultListItemSchema.shape,
     segments: z.array(segmentDescriptorSchema).optional(),
     source: resultSourceSchema.optional(),