Let a catalog target run each example on its own Worker

An authoring target can now declare grouping: 'per-example'. The generated
registration then registers one target for each example, with its own task
queue, workflow bundle, and activities. The default, 'shared', keeps the
current output unchanged.

Author: rossnelson

src/lib/catalog/README.md

@@ -68,6 +68,19 @@ An API key cannot be combined with any TLS variable. The CA certificate and serv
 
 A target is a worker specification: a namespace, a task queue, a workflow bundle, and its activities. The catalog runs **one worker per target**, all in a single process sharing one connection. Starting the worker with two targets registered starts two workers.
 
+### Grouping examples into targets
+
+An authoring target declares how its examples map to workers with `grouping`:
+
+| Grouping                | Workers                 | Task queue                    | Workflow bundle             | Same activity name in two examples |
+| ----------------------- | ----------------------- | ----------------------------- | --------------------------- | ---------------------------------- |
+| `shared` (the default)  | One for all examples    | `defaultTaskQueue`            | The generated workflows module | An error                        |
+| `per-example`           | One for each example    | `<defaultTaskQueue>-<example>` | The example's own `workflow.ts` | Allowed                       |
+
+Use `shared` for many small examples that exercise primitives. Use `per-example` when each example must have clear boundaries: its own task queue, bundle, and activities. Both groupings run in the same process. The generated catalog lists each example's task queue, so the browser does not need to know which grouping produced it.
+
+A `per-example` target registers targets named `<target id>-<example id>`. Validation fails when a derived target ID or task queue collides with another target. Moving an example to a target with a different grouping changes its task queue.
+
 The worker waits for the server rather than exiting if it starts first, printing progress while it retries. Non-connection failures, such as an invalid API key, still fail immediately.
 
 On a plaintext local connection, the worker creates any Nexus endpoints its examples declare. When it lacks the authority to do so — any credentialed connection, including Temporal Cloud — it prints the exact `temporal operator nexus endpoint create` command instead, and the catalog page shows the same command as copyable text.

src/lib/catalog/authoring.test.ts

@@ -23,6 +23,8 @@ import {
   createCatalogAuthoring as createCatalogAuthoringSdk,
   createCatalogLocalArtifactVitePlugin,
   defineCatalogArtifact,
+  perExampleTargetId,
+  perExampleTaskQueue,
   renderCatalogSourceAssembly,
   runCatalogCli,
   validateCatalogAuthoringGraph,
@@ -1630,3 +1632,185 @@ try {
     ).toThrow('browser boundary must declare a browser consumer');
   });
 });
+
+describe('per-example catalog targets', () => {
+  const source = {
+    examplesPath: 'demos/examples',
+    id: 'demos',
+    label: 'Demos',
+    registrationOutputPath: 'demos/registration.ts',
+    registrationTypePath: 'demos/registration-source.ts',
+  };
+  const target = {
+    defaultNamespace: 'default',
+    defaultTaskQueue: 'demos',
+    grouping: 'per-example' as const,
+    id: 'demos',
+    sourceId: 'demos',
+    workflowsModulePath: 'demos/workflows.ts',
+  };
+  const workflowExample = (id: string, workflowType: string) => ({
+    definitionImportPath: `demos/examples/${id}/example.ts`,
+    id,
+    sourceFiles: [
+      `demos/examples/${id}/example.ts`,
+      `demos/examples/${id}/workflow.ts`,
+    ],
+    sourceId: 'demos',
+    targetId: 'demos',
+    workflowExport: workflowType,
+    workflowImportPath: `demos/examples/${id}/workflow.ts`,
+    workflowType,
+  });
+  const graph = {
+    boundaries: {
+      browserPaths: ['demos/catalog.json'],
+      packageJsonPath: 'package.json',
+      workerPaths: ['demos/registration.ts', 'demos/workflows.ts'],
+    },
+    outputs: [
+      { consumers: ['browser'] as const, path: 'demos/catalog.json' },
+      { consumers: ['worker'] as const, path: 'demos/registration.ts' },
+      { consumers: ['worker'] as const, path: 'demos/workflows.ts' },
+    ],
+    sources: [source],
+    targets: [target],
+  };
+
+  it('derives a target id and task queue for each example', () => {
+    expect(perExampleTargetId(target, 'money-transfer')).toBe(
+      'demos-money-transfer',
+    );
+    expect(perExampleTaskQueue(target, 'money-transfer')).toBe(
+      'demos-money-transfer',
+    );
+  });
+
+  it('registers one target, task queue, and workflow bundle for each example', () => {
+    const [registration] = renderCatalogSourceAssembly({
+      examples: [
+        workflowExample('order-saga', 'orderSaga'),
+        workflowExample('money-transfer', 'moneyTransfer'),
+      ],
+      source,
+      target,
+    });
+    const content = String(registration.content);
+
+    expect(content).not.toContain('import * as workflows');
+    expect(content).toContain(
+      "import { moneyTransfer as workflow0 } from './examples/money-transfer/workflow.js';",
+    );
+    expect(content).toContain(
+      [
+        '    registry.registerTarget({',
+        "      id: 'demos-money-transfer',",
+        "      namespace: 'default',",
+        "      taskQueue: 'demos-money-transfer',",
+        "      workflowsPath: new URL('./examples/money-transfer/workflow.ts', import.meta.url).href,",
+        '      workflowExports: { moneyTransfer: workflow0 },',
+        '    });',
+        "    registry.registerExample({ ...example0, targetId: 'demos-money-transfer' });",
+      ].join('\n'),
+    );
+    expect(content).toContain("taskQueue: 'demos-order-saga'");
+    expect(content).not.toContain("taskQueue: 'demos',");
+  });
+
+  it('keeps the shared registration unchanged when grouping is omitted', () => {
+    const sharedTarget = { ...target, grouping: undefined };
+    const explicitShared = { ...target, grouping: 'shared' as const };
+    const examples = [workflowExample('money-transfer', 'moneyTransfer')];
+
+    const omitted = renderCatalogSourceAssembly({
+      examples,
+      source,
+      target: sharedTarget,
+    });
+    const explicit = renderCatalogSourceAssembly({
+      examples,
+      source,
+      target: explicitShared,
+    });
+
+    expect(omitted).toEqual(explicit);
+    expect(String(omitted[0].content)).toContain(
+      "import * as workflows from './workflows.js';",
+    );
+    expect(String(omitted[0].content)).toContain("taskQueue: 'demos',");
+  });
+
+  it('allows the same workflow type in two per-example demos', () => {
+    expect(() =>
+      validateCatalogAuthoringGraph(graph, [
+        workflowExample('first-demo', 'demoWorkflow'),
+        workflowExample('second-demo', 'demoWorkflow'),
+      ]),
+    ).not.toThrow();
+  });
+
+  it('still rejects the same workflow type twice in a shared target', () => {
+    const sharedGraph = {
+      ...graph,
+      targets: [{ ...target, grouping: 'shared' as const }],
+    };
+
+    expect(() =>
+      validateCatalogAuthoringGraph(sharedGraph, [
+        workflowExample('first-demo', 'demoWorkflow'),
+        workflowExample('second-demo', 'demoWorkflow'),
+      ]),
+    ).toThrow('Workflow type "demoWorkflow" is declared by both');
+  });
+
+  it('rejects a derived task queue that collides with another target', () => {
+    const collidingGraph = {
+      ...graph,
+      sources: [
+        source,
+        {
+          ...source,
+          id: 'other',
+          registrationOutputPath: 'other/registration.ts',
+        },
+      ],
+      outputs: [
+        ...graph.outputs,
+        { consumers: ['worker'] as const, path: 'other/registration.ts' },
+        { consumers: ['worker'] as const, path: 'other/workflows.ts' },
+      ],
+      targets: [
+        target,
+        {
+          defaultNamespace: 'default',
+          defaultTaskQueue: 'demos-money-transfer',
+          id: 'other',
+          sourceId: 'other',
+          workflowsModulePath: 'other/workflows.ts',
+        },
+      ],
+    };
+
+    expect(() =>
+      validateCatalogAuthoringGraph(collidingGraph, [
+        workflowExample('money-transfer', 'moneyTransfer'),
+      ]),
+    ).toThrow(
+      'Catalog task queue "demos-money-transfer" is claimed by both target other and example money-transfer',
+    );
+  });
+
+  it('rejects an unknown grouping', () => {
+    expect(() =>
+      validateCatalogAuthoringGraph(
+        {
+          ...graph,
+          targets: [
+            { ...target, grouping: 'per-tenant' as unknown as 'shared' },
+          ],
+        },
+        [],
+      ),
+    ).toThrow('Catalog target has an unknown grouping: per-tenant');
+  });
+});