@startsimpli/funnels 0.4.13 → 0.4.15

package/src/api/paths.test.ts

@@ -0,0 +1,138 @@
+/**
+ * Tests for the injectable funnel path family (bd startsim-pxzlf).
+ *
+ * The same client has to talk to four surfaces that differ ONLY in their URL
+ * prefix and, for the control plane, in whether a run is addressed globally or
+ * under its funnel:
+ *
+ *   central        /api/v1/funnels/…           + /api/v1/funnel-runs/<id>/
+ *   control plane  /api/v1/foundry/tenants/<slug>/funnels/… (runs nested)
+ *   tenant proxy   /central-api/api/v1/funnels/… (a prefix on the central family)
+ *   a fork's own   whatever the fork mounted
+ *
+ * Hardcoding '/api/v1/funnels' in the client (api/client.ts before this change)
+ * made the first the only one reachable.
+ */
+
+import { describe, it, expect } from 'vitest';
+import {
+  createFunnelPaths,
+  centralFunnelPaths,
+  foundryTenantFunnelPaths,
+  DEFAULT_FUNNEL_PATH_PREFIX,
+} from './paths';
+
+describe('centralFunnelPaths', () => {
+  it('is the /api/v1/funnels family the client used to hardcode', () => {
+    expect(centralFunnelPaths.list()).toBe('/api/v1/funnels/');
+    expect(centralFunnelPaths.detail('f1')).toBe('/api/v1/funnels/f1/');
+    expect(centralFunnelPaths.stages('f1')).toBe('/api/v1/funnels/f1/stages/');
+    expect(centralFunnelPaths.stage('f1', 's1')).toBe('/api/v1/funnels/f1/stages/s1/');
+    expect(centralFunnelPaths.run('f1')).toBe('/api/v1/funnels/f1/run/');
+    expect(centralFunnelPaths.runs('f1')).toBe('/api/v1/funnels/f1/runs/');
+    expect(centralFunnelPaths.preview('f1')).toBe('/api/v1/funnels/f1/preview/');
+    expect(centralFunnelPaths.fields()).toBe('/api/v1/funnels/fields/');
+  });
+
+  it('addresses a run globally, because the central API does', () => {
+    // config/api_router.py registers funnel-runs as its own router entry.
+    expect(centralFunnelPaths.runDetail('r1')).toBe('/api/v1/funnel-runs/r1/');
+    expect(centralFunnelPaths.runResults('r1')).toBe('/api/v1/funnel-runs/r1/results/');
+    expect(centralFunnelPaths.runCancel('r1')).toBe('/api/v1/funnel-runs/r1/cancel/');
+  });
+
+  it('exposes its prefix so callers can see which surface they are on', () => {
+    expect(centralFunnelPaths.prefix).toBe(DEFAULT_FUNNEL_PATH_PREFIX);
+  });
+});
+
+describe('createFunnelPaths', () => {
+  it('defaults to the central family', () => {
+    const paths = createFunnelPaths();
+    expect(paths.list()).toBe(centralFunnelPaths.list());
+    expect(paths.runDetail('r1')).toBe(centralFunnelPaths.runDetail('r1'));
+  });
+
+  it('mounts the whole family under a prefix — a tenant proxy', () => {
+    const paths = createFunnelPaths({ prefix: '/central-api/api/v1/funnels' });
+    expect(paths.list()).toBe('/central-api/api/v1/funnels/');
+    expect(paths.detail('f1')).toBe('/central-api/api/v1/funnels/f1/');
+    expect(paths.fields()).toBe('/central-api/api/v1/funnels/fields/');
+  });
+
+  it('takes the runs prefix separately, since runs need not live under funnels', () => {
+    const paths = createFunnelPaths({
+      prefix: '/central-api/api/v1/funnels',
+      runsPrefix: '/central-api/api/v1/funnel-runs',
+    });
+    expect(paths.runDetail('r1')).toBe('/central-api/api/v1/funnel-runs/r1/');
+    expect(paths.runCancel('r1')).toBe('/central-api/api/v1/funnel-runs/r1/cancel/');
+  });
+
+  it('nests runs under their funnel when asked (the control-plane shape)', () => {
+    const paths = createFunnelPaths({
+      prefix: '/api/v1/foundry/tenants/acme/funnels',
+      nestRuns: true,
+    });
+    expect(paths.runDetail('r1', 'f1')).toBe(
+      '/api/v1/foundry/tenants/acme/funnels/f1/runs/r1/'
+    );
+    expect(paths.runResults('r1', 'f1')).toBe(
+      '/api/v1/foundry/tenants/acme/funnels/f1/runs/r1/results/'
+    );
+  });
+
+  it('refuses a nested run address with no funnel, instead of building a wrong URL', () => {
+    const paths = createFunnelPaths({ prefix: '/api/v1/x/funnels', nestRuns: true });
+    expect(() => paths.runDetail('r1')).toThrow(/funnel/i);
+  });
+
+  it('normalizes a prefix given with or without a trailing slash', () => {
+    const withSlash = createFunnelPaths({ prefix: '/api/v1/funnels/' });
+    const without = createFunnelPaths({ prefix: '/api/v1/funnels' });
+    expect(withSlash.list()).toBe(without.list());
+    expect(withSlash.detail('f1')).toBe(without.detail('f1'));
+  });
+
+  it('URL-encodes ids so a slug or an id with a slash cannot escape the family', () => {
+    const paths = createFunnelPaths();
+    expect(paths.detail('a/b')).toBe('/api/v1/funnels/a%2Fb/');
+  });
+});
+
+describe('foundryTenantFunnelPaths', () => {
+  it('is the control-plane family for one foundry (startsim-9xbz2)', () => {
+    const paths = foundryTenantFunnelPaths('acme');
+    expect(paths.list()).toBe('/api/v1/foundry/tenants/acme/funnels/');
+    expect(paths.detail('f1')).toBe('/api/v1/foundry/tenants/acme/funnels/f1/');
+    expect(paths.runs('f1')).toBe('/api/v1/foundry/tenants/acme/funnels/f1/runs/');
+  });
+
+  it('triggers a run by POSTing to the runs COLLECTION, not to a run/ action', () => {
+    // FoundryViewSet mounts ONE `funnel_runs` action: GET lists, POST triggers.
+    // `funnels/<id>/run/` reaches no route there (verified against prod
+    // 2026-09-18: Django's 404 HTML, not a DRF body). bd startsim-em5mn.
+    const paths = foundryTenantFunnelPaths('acme');
+    expect(paths.run('f1')).toBe('/api/v1/foundry/tenants/acme/funnels/f1/runs/');
+    expect(paths.run('f1')).toBe(paths.runs('f1'));
+  });
+
+  it('addresses a run on the sibling funnel-runs collection, not under its funnel', () => {
+    // The action is `funnel-runs/(?P<run_id>[^/.]+)/results` — a sibling of
+    // `funnels/`, because `runs/` on that viewset is already the foundry's own
+    // build history. The old `nestRuns: true` built
+    // `funnels/f1/runs/r1/results/`, which has never resolved.
+    const paths = foundryTenantFunnelPaths('acme');
+    expect(paths.runResults('r1')).toBe(
+      '/api/v1/foundry/tenants/acme/funnel-runs/r1/results/'
+    );
+    // ...and it does NOT need the funnel id to do it.
+    expect(paths.runResults('r1', 'f1')).toBe(paths.runResults('r1'));
+  });
+
+  it('encodes the slug', () => {
+    expect(foundryTenantFunnelPaths('a b').list()).toBe(
+      '/api/v1/foundry/tenants/a%20b/funnels/'
+    );
+  });
+});

package/src/api/paths.ts

@@ -0,0 +1,192 @@
+/**
+ * The funnel path family (bd startsim-pxzlf).
+ *
+ * WHY THIS EXISTS: FunnelApiClient hardcoded '/api/v1/funnels' in every method,
+ * so the one client in the estate could only ever talk to the central API. The
+ * same endpoints are mounted on at least four surfaces:
+ *
+ *   central        /api/v1/funnels/…                     runs addressed globally
+ *   control plane  /api/v1/foundry/tenants/<slug>/funnels/…   runs nested (startsim-9xbz2)
+ *   tenant proxy   /central-api/api/v1/funnels/…         a prefix on the central family
+ *   a fork's own   whatever the fork mounted
+ *
+ * They differ in exactly two ways: the prefix, and whether a run is addressed
+ * on its own or under its funnel. So the family is data — a small object of
+ * path builders — and the client takes one.
+ *
+ * @packageDocumentation
+ */
+
+/** The central API's funnel prefix. */
+export const DEFAULT_FUNNEL_PATH_PREFIX = '/api/v1/funnels';
+
+/** The central API's run prefix — its own router entry, not nested. */
+export const DEFAULT_FUNNEL_RUNS_PATH_PREFIX = '/api/v1/funnel-runs';
+
+/**
+ * Every URL the funnel client needs, as builders.
+ *
+ * Run-addressing methods take an optional funnelId because a nested family
+ * needs it; on a flat family it is ignored.
+ */
+export interface FunnelPaths {
+  /** The prefix this family was built on — for logging and for telling surfaces apart. */
+  readonly prefix: string;
+
+  list(): string;
+  detail(funnelId: string): string;
+  stages(funnelId: string): string;
+  stage(funnelId: string, stageId: string): string;
+  preview(funnelId: string): string;
+  fields(): string;
+
+  run(funnelId: string): string;
+  runs(funnelId: string): string;
+  runDetail(runId: string, funnelId?: string): string;
+  runResults(runId: string, funnelId?: string): string;
+  runCancel(runId: string, funnelId?: string): string;
+}
+
+export interface FunnelPathsOptions {
+  /** Where the funnel collection is mounted. Default: the central API. */
+  prefix?: string;
+  /**
+   * Where runs are mounted when they are addressed on their own.
+   * Ignored when `nestRuns` is set. Default: the central API's /funnel-runs.
+   */
+  runsPrefix?: string;
+  /**
+   * Address a run under its funnel (<prefix>/<funnelId>/runs/<runId>/) instead
+   * of on its own.
+   */
+  nestRuns?: boolean;
+  /**
+   * Trigger a run by POSTing to the run COLLECTION (<prefix>/<id>/runs/)
+   * rather than to a separate <prefix>/<id>/run/ action.
+   *
+   * The control plane is built this way — one `funnel_runs` action where GET
+   * lists and POST triggers — while the central API keeps `run/` and `runs/`
+   * as two endpoints. Verified against prod 2026-09-18: a POST to the control
+   * plane's `funnels/<id>/run/` reaches no route at all (Django 404 HTML,
+   * not a DRF body), whereas `funnels/<id>/runs/` answers.
+   */
+  triggerOnRunsCollection?: boolean;
+}
+
+function trimSlashes(value: string): string {
+  return value.replace(/\/+$/, '');
+}
+
+/** Encode one path segment: an id or slug must not be able to escape the family. */
+function segment(value: string): string {
+  return encodeURIComponent(String(value));
+}
+
+/**
+ * Build a funnel path family.
+ *
+ * ```ts
+ * createFunnelPaths()                                        // central
+ * createFunnelPaths({ prefix: '/central-api/api/v1/funnels',
+ *                     runsPrefix: '/central-api/api/v1/funnel-runs' })
+ * createFunnelPaths({ prefix: '/api/v1/foundry/tenants/acme/funnels',
+ *                     nestRuns: true })
+ * ```
+ */
+export function createFunnelPaths(options: FunnelPathsOptions = {}): FunnelPaths {
+  const prefix = trimSlashes(options.prefix ?? DEFAULT_FUNNEL_PATH_PREFIX);
+  const runsPrefix = trimSlashes(options.runsPrefix ?? DEFAULT_FUNNEL_RUNS_PATH_PREFIX);
+  const nestRuns = options.nestRuns ?? false;
+  const triggerOnRunsCollection = options.triggerOnRunsCollection ?? false;
+
+  function runBase(runId: string, funnelId?: string): string {
+    if (!nestRuns) return `${runsPrefix}/${segment(runId)}`;
+    if (!funnelId) {
+      throw new Error(
+        `This funnel path family nests runs under their funnel, so addressing run ` +
+          `'${runId}' needs a funnelId. Pass it: getFunnelRun(runId, funnelId).`
+      );
+    }
+    return `${prefix}/${segment(funnelId)}/runs/${segment(runId)}`;
+  }
+
+  return {
+    prefix,
+
+    list: () => `${prefix}/`,
+    detail: (funnelId) => `${prefix}/${segment(funnelId)}/`,
+    stages: (funnelId) => `${prefix}/${segment(funnelId)}/stages/`,
+    stage: (funnelId, stageId) => `${prefix}/${segment(funnelId)}/stages/${segment(stageId)}/`,
+    preview: (funnelId) => `${prefix}/${segment(funnelId)}/preview/`,
+    // The registry endpoint lives beside the collection on every surface
+    // (config/api_router.py: path("funnels/fields/", FunnelFieldsView…)).
+    fields: () => `${prefix}/fields/`,
+
+    run: (funnelId) =>
+      triggerOnRunsCollection
+        ? `${prefix}/${segment(funnelId)}/runs/`
+        : `${prefix}/${segment(funnelId)}/run/`,
+    runs: (funnelId) => `${prefix}/${segment(funnelId)}/runs/`,
+    runDetail: (runId, funnelId) => `${runBase(runId, funnelId)}/`,
+    runResults: (runId, funnelId) => `${runBase(runId, funnelId)}/results/`,
+    runCancel: (runId, funnelId) => `${runBase(runId, funnelId)}/cancel/`,
+  };
+}
+
+/** The central API family: what the client used to hardcode. */
+export const centralFunnelPaths: FunnelPaths = createFunnelPaths();
+
+/**
+ * The control-plane family for one foundry (startsim-9xbz2).
+ *
+ * CORRECTED against the routes FoundryViewSet actually mounts (bd
+ * startsim-em5mn). Every URL below was exercised against prod on 2026-09-18 as
+ * the foundry QA owner; the ones marked ✗ answered with Django's 404 HTML page,
+ * which is what "this path reaches no route at all" looks like, as opposed to
+ * the DRF `{"error": …}` body a real route returns for a missing row.
+ *
+ *   ✓ funnels/                       GET list, POST create
+ *   ✓ funnels/<id>/                  GET, PATCH, DELETE
+ *   ✓ funnels/<id>/runs/             GET history, POST trigger (202)
+ *   ✓ funnel-runs/<runId>/results/   GET, paged, ?matched= ?stage=
+ *   ✗ funnels/<id>/run/              — trigger is a POST to `runs/`
+ *   ✗ funnels/<fid>/runs/<rid>/…     — results hang off `funnel-runs/`, a
+ *                                      SIBLING of `funnels/`, not under it
+ *   ✗ funnels/<id>/stages/           — stages are written nested in the funnel
+ *   ✗ funnels/<id>/preview/          — no preview action exists here
+ *
+ * The previous definition passed `nestRuns: true`, which built
+ * `funnels/<fid>/runs/<rid>/results/` — a path that has never resolved. It had
+ * no runtime consumer, so nothing was broken by it and nothing is broken by
+ * this correction; it was simply never driven by a page until now.
+ *
+ * `fields()` REMAINS A LIE ON THIS SURFACE and is the one thing this function
+ * cannot fix. `funnels/fields/` matches the `funnels/(?P<funnel_id>[^/.]+)`
+ * action first (DRF orders extra actions by method name, and `funnel_detail`
+ * sorts before any `funnel_fields` would), so it 404s with "funnel not found".
+ * The vocabulary is only served from central `/api/v1/funnels/fields/`, scoped
+ * to the CALLER's company. That is why FunnelsPage takes its fields client as a
+ * separate injection instead of reading `client.paths.fields()` — see
+ * `src/page/FunnelsPage.tsx`. bd startsim-em5mn.1 tracks mounting the route.
+ */
+export function foundryTenantFunnelPaths(slug: string): FunnelPaths {
+  const base = `/api/v1/foundry/tenants/${segment(slug)}`;
+  return createFunnelPaths({
+    prefix: `${base}/funnels`,
+    runsPrefix: `${base}/funnel-runs`,
+    triggerOnRunsCollection: true,
+  });
+}
+
+/**
+ * The same central family reached through a fork's same-origin proxy, e.g.
+ * '/central-api'. A tenant page cannot call the central API cross-origin
+ * (project_foreign_apex_sso_same_origin_proxy), so it proxies it.
+ */
+export function proxiedCentralFunnelPaths(proxyPrefix: string): FunnelPaths {
+  const base = trimSlashes(proxyPrefix);
+  return createFunnelPaths({
+    prefix: `${base}${DEFAULT_FUNNEL_PATH_PREFIX}`,
+    runsPrefix: `${base}${DEFAULT_FUNNEL_RUNS_PATH_PREFIX}`,
+  });
+}

package/src/components/FilterRuleEditor/FieldSelector.tsx

@@ -29,10 +29,12 @@
  * - Focus visible on keyboard navigation
  */
 
-import { FieldDefinition } from '../../types';
+import { FieldDefinitionInput } from '../../types';
+import { fieldKey } from '../../types';
 
 interface FieldSelectorProps {
-  fields: FieldDefinition[];
+  /** Canonical /fields/ entries or legacy {name,label,type,operators} ones. */
+  fields: FieldDefinitionInput[];
   value: string;
   onChange: (fieldName: string) => void;
   error?: string;
@@ -54,7 +56,7 @@ export function FieldSelector({
     }
     acc[category].push(field);
     return acc;
-  }, {} as Record<string, FieldDefinition[]>);
+  }, {} as Record<string, FieldDefinitionInput[]>);
 
   const categories = Object.keys(grouped).sort();
 
@@ -78,8 +80,8 @@ export function FieldSelector({
         {categories.map((category) => (
           <optgroup key={category} label={category}>
             {grouped[category].map((field) => (
-              <option key={field.name} value={field.name}>
-                {field.label}
+              <option key={fieldKey(field)} value={fieldKey(field)}>
+                {field.label ?? fieldKey(field)}
               </option>
             ))}
           </optgroup>

package/src/components/FilterRuleEditor/FilterRuleEditor.stories.tsx

@@ -6,7 +6,7 @@
 
 import { useState } from 'react';
 import { FilterRuleEditor } from './FilterRuleEditor';
-import { FilterRule, FilterLogic, FieldDefinition } from '../../types';
+import { FilterRule, FilterLogic, FieldDefinitionInput } from '../../types';
 
 export default {
   title: 'Components/FilterRuleEditor',
@@ -17,7 +17,7 @@ export default {
 // Investor Field Registry
 // ============================================================================
 
-const investorFields: FieldDefinition[] = [
+const investorFields: FieldDefinitionInput[] = [
   {
     name: 'name',
     label: 'Name',
@@ -101,7 +101,7 @@ const investorFields: FieldDefinition[] = [
 // Recipe Field Registry
 // ============================================================================
 
-const recipeFields: FieldDefinition[] = [
+const recipeFields: FieldDefinitionInput[] = [
   {
     name: 'title',
     label: 'Recipe Title',

package/src/components/FilterRuleEditor/FilterRuleEditor.test.tsx

@@ -5,7 +5,7 @@
  */
 
 import { describe, it, expect, vi } from 'vitest';
-import { FilterRule, FieldDefinition, FilterLogic } from '../../types';
+import { FilterRule, FieldDefinitionInput, FilterLogic } from '../../types';
 import { validateFilterRule } from '../../types';
 
 // ============================================================================
@@ -15,7 +15,7 @@ import { validateFilterRule } from '../../types';
 /**
  * Investor field registry
  */
-const investorFieldRegistry: FieldDefinition[] = [
+const investorFieldRegistry: FieldDefinitionInput[] = [
   {
     name: 'name',
     label: 'Name',
@@ -73,7 +73,7 @@ const investorFieldRegistry: FieldDefinition[] = [
 /**
  * Recipe field registry - completely different domain!
  */
-const recipeFieldRegistry: FieldDefinition[] = [
+const recipeFieldRegistry: FieldDefinitionInput[] = [
   {
     name: 'title',
     label: 'Recipe Title',
@@ -132,15 +132,20 @@ const recipeFieldRegistry: FieldDefinition[] = [
 // ============================================================================
 
 describe('FilterRuleEditor - Generic Validation', () => {
-  it('validates empty fieldPath', () => {
+  it('validates empty field', () => {
     const rule: FilterRule = {
-      fieldPath: '',
+      field: '',
       operator: 'eq',
       value: 'test',
     };
 
     const errors = validateFilterRule(rule);
-    expect(errors).toContain('fieldPath is required');
+    expect(errors).toContain('field is required');
+  });
+
+  it('still accepts a rule that names its field the deprecated way', () => {
+    const legacy = { fieldPath: 'name', operator: 'eq', value: 'test' } as FilterRule;
+    expect(validateFilterRule(legacy)).toEqual([]);
   });
 
   it('validates missing operator', () => {
@@ -414,7 +419,7 @@ describe('FilterRuleEditor - Field Registry Grouping', () => {
       }
       acc[category].push(field);
       return acc;
-    }, {} as Record<string, FieldDefinition[]>);
+    }, {} as Record<string, FieldDefinitionInput[]>);
 
     expect(Object.keys(grouped)).toContain('Profile');
     expect(Object.keys(grouped)).toContain('Investment');
@@ -431,7 +436,7 @@ describe('FilterRuleEditor - Field Registry Grouping', () => {
       }
       acc[category].push(field);
       return acc;
-    }, {} as Record<string, FieldDefinition[]>);
+    }, {} as Record<string, FieldDefinitionInput[]>);
 
     expect(Object.keys(grouped)).toContain('Basic Info');
     expect(Object.keys(grouped)).toContain('Classification');

package/src/components/FilterRuleEditor/FilterRuleEditor.tsx

@@ -50,7 +50,7 @@
  * - Transitions: transition-all, duration-200
  */
 
-import { FilterRule, FilterLogic, FieldDefinition } from '../../types';
+import { FilterRule, FilterLogic, FieldDefinitionInput } from '../../types';
 import { LogicToggle } from './LogicToggle';
 import { RuleRow } from './RuleRow';
 import { validateFilterRule } from '../../types';
@@ -63,7 +63,8 @@ export interface FilterRuleEditorProps {
   onChange: (rules: FilterRule[]) => void;
 
   /** Field registry for the entity type */
-  fieldRegistry: FieldDefinition[];
+  /** Canonical /fields/ entries or legacy {name,label,type,operators} ones. */
+  fieldRegistry: FieldDefinitionInput[];
 
   /** Filter logic (AND/OR) */
   logic?: FilterLogic;
@@ -86,6 +87,10 @@ export function FilterRuleEditor({
   // Add a new empty rule
   const handleAddRule = () => {
     const newRule: FilterRule = {
+      field: '',
+      // Both keys start empty: RuleRow decides which one carries the chosen
+      // name, depending on whether the registry entry is a resolver key or a
+      // hand-written one (see its handleFieldChange).
       fieldPath: '',
       operator: 'eq' as any,
       value: null,

package/src/components/FilterRuleEditor/OperatorSelector.tsx

@@ -24,7 +24,7 @@
  * - Focus visible on keyboard navigation
  */
 
-import { Operator, FieldDefinition } from '../../types';
+import { Operator, FieldDefinitionInput } from '../../types';
 import { OPERATOR_LABELS } from './constants';
 
 interface OperatorSelectorProps {

package/src/components/FilterRuleEditor/RuleRow.test.tsx

@@ -0,0 +1,166 @@
+/**
+ * RuleRow renders BOTH field-registry shapes (bd startsim-pxzlf).
+ *
+ * The canonical registry is the backend's /fields/ payload
+ * ({key,label,category,valueType,enumValues,allowedOperators}). The registries
+ * that predate it are hand-written arrays of {name,label,type,operators} —
+ * market-web's LEAD_FIELDS is one, and it is live. Both have to render, or
+ * "one contract" is just a rename that breaks a shipped app.
+ */
+
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen } from '@testing-library/react';
+import { RuleRow } from './RuleRow';
+import type { FieldDefinitionInput, FilterRule } from '../../types';
+
+const canonicalRegistry: FieldDefinitionInput[] = [
+  {
+    key: 'tag.stage_focus',
+    label: 'stage_focus',
+    category: 'Tags',
+    valueType: 'enum',
+    enumValues: ['pre_seed', 'seed'],
+    allowedOperators: ['eq', 'ne', 'exists', 'not_exists'],
+  },
+  {
+    key: 'metric.financial.check_size_min',
+    label: 'check_size_min',
+    category: 'Financial',
+    valueType: 'number',
+    allowedOperators: ['gte', 'lte', 'between'],
+  },
+];
+
+const legacyRegistry: FieldDefinitionInput[] = [
+  {
+    name: 'contact__name',
+    label: 'Name',
+    type: 'string',
+    category: 'Profile',
+    operators: ['eq', 'contains'],
+  },
+];
+
+function noop() {}
+
+describe('RuleRow with the canonical registry', () => {
+  it('selects the field the rule names with `field`', () => {
+    const rule: FilterRule = { field: 'tag.stage_focus', operator: 'eq', value: 'seed' };
+    render(
+      <RuleRow rule={rule} onChange={noop} onRemove={noop} fieldRegistry={canonicalRegistry} />
+    );
+
+    const fieldSelect = screen.getByLabelText('Field') as HTMLSelectElement;
+    expect(fieldSelect.value).toBe('tag.stage_focus');
+  });
+
+  it('offers the operators the registry allows, including the backend-only ones', () => {
+    const rule: FilterRule = {
+      field: 'metric.financial.check_size_min',
+      operator: 'gte',
+      value: 1,
+    };
+    render(
+      <RuleRow rule={rule} onChange={noop} onRemove={noop} fieldRegistry={canonicalRegistry} />
+    );
+
+    const operatorSelect = screen.getByLabelText('Operator') as HTMLSelectElement;
+    const offered = Array.from(operatorSelect.options).map((o) => o.value);
+    expect(offered).toEqual(expect.arrayContaining(['gte', 'lte', 'between']));
+  });
+
+  it('renders an enum field as a picker over its enum values', () => {
+    const rule: FilterRule = { field: 'tag.stage_focus', operator: 'eq', value: 'seed' };
+    render(
+      <RuleRow rule={rule} onChange={noop} onRemove={noop} fieldRegistry={canonicalRegistry} />
+    );
+
+    // The value input is a select over the tag category's known values.
+    const selects = screen.getAllByRole('combobox') as HTMLSelectElement[];
+    const values = selects.flatMap((s) => Array.from(s.options).map((o) => o.value));
+    expect(values).toEqual(expect.arrayContaining(['pre_seed', 'seed']));
+  });
+
+  it('writes the canonical key on the rule when the field changes', () => {
+    const onChange = vi.fn();
+    const rule: FilterRule = { field: '', operator: 'eq', value: null };
+    render(
+      <RuleRow
+        rule={rule}
+        onChange={onChange}
+        onRemove={noop}
+        fieldRegistry={canonicalRegistry}
+      />
+    );
+
+    const fieldSelect = screen.getByLabelText('Field') as HTMLSelectElement;
+    fieldSelect.value = 'tag.stage_focus';
+    fieldSelect.dispatchEvent(new Event('change', { bubbles: true }));
+
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ field: 'tag.stage_focus', operator: 'eq' })
+    );
+  });
+});
+
+describe('RuleRow with a hand-written registry that predates /fields/', () => {
+  it('does NOT write a non-registry name into `field` — that would be a 400', () => {
+    // 'contact__name' is not a resolver key. The serializer's strict branch
+    // fires on any truthy `field` and rejects an unknown one, so a picker
+    // driven by a hand-written registry has to keep taking the legacy branch:
+    // `field` empty, the name on `fieldPath`.
+    const onChange = vi.fn();
+    const rule = { field: '', operator: 'eq', value: null } as FilterRule;
+    render(
+      <RuleRow rule={rule} onChange={onChange} onRemove={noop} fieldRegistry={legacyRegistry} />
+    );
+
+    const fieldSelect = screen.getByLabelText('Field') as HTMLSelectElement;
+    fieldSelect.value = 'contact__name';
+    fieldSelect.dispatchEvent(new Event('change', { bubbles: true }));
+
+    expect(onChange).toHaveBeenCalledWith(
+      expect.objectContaining({ field: '', fieldPath: 'contact__name', operator: 'eq' })
+    );
+  });
+
+  it('resolves a row the backend auto-migrated, which carries BOTH keys', () => {
+    // The serializer's legacy branch sets attrs['field'] and does NOT clear
+    // field_path, and _create_rule_tree persists the whole validated dict — so
+    // every rule market has saved since that change round-trips as
+    // {field: 'contact.name', fieldPath: 'contact__name'}. Preferring `field`
+    // alone would leave the picker blank against a registry keyed the old way,
+    // and re-saving that blank row would drop the rule.
+    const migrated = {
+      field: 'contact.name',
+      fieldPath: 'contact__name',
+      operator: 'contains',
+      value: 'Ada',
+    } as FilterRule;
+    render(
+      <RuleRow rule={migrated} onChange={noop} onRemove={noop} fieldRegistry={legacyRegistry} />
+    );
+
+    const fieldSelect = screen.getByLabelText('Field') as HTMLSelectElement;
+    expect(fieldSelect.value).toBe('contact__name');
+
+    const operatorSelect = screen.getByLabelText('Operator') as HTMLSelectElement;
+    expect(operatorSelect.disabled).toBe(false);
+    expect(Array.from(operatorSelect.options).map((o) => o.value)).toEqual(
+      expect.arrayContaining(['eq', 'contains'])
+    );
+  });
+
+  it('still resolves a rule that names its field the deprecated way', () => {
+    const rule = { fieldPath: 'contact__name', operator: 'contains', value: 'Ada' } as FilterRule;
+    render(<RuleRow rule={rule} onChange={noop} onRemove={noop} fieldRegistry={legacyRegistry} />);
+
+    const fieldSelect = screen.getByLabelText('Field') as HTMLSelectElement;
+    expect(fieldSelect.value).toBe('contact__name');
+
+    const operatorSelect = screen.getByLabelText('Operator') as HTMLSelectElement;
+    expect(Array.from(operatorSelect.options).map((o) => o.value)).toEqual(
+      expect.arrayContaining(['eq', 'contains'])
+    );
+  });
+});