@elevasis/core 0.19.0 → 0.20.0

package/dist/index.js

@@ -386,6 +386,12 @@ var ProspectingBuildTemplateSchema = DisplayMetadataSchema.extend({
   id: ModelIdSchema,
   steps: z.array(ProspectingBuildTemplateStepSchema).min(1)
 });
+z.object({
+  id: ModelIdSchema,
+  label: z.string(),
+  description: z.string(),
+  resourceId: ModelIdSchema
+});
 var PROSPECTING_STEPS = {
   localServices: {
     sourceCompanies: {
@@ -1124,8 +1130,12 @@ var LEGACY_FEATURE_ALIASES = /* @__PURE__ */ new Map([
 function hasFeature(featuresById, featureId) {
   return featuresById.has(featureId) || featuresById.has(LEGACY_FEATURE_ALIASES.get(featureId) ?? "");
 }
+function defaultFeaturePathFor(id) {
+  return `/${id.replaceAll(".", "/")}`;
+}
 var OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ctx) => {
   const featuresById = collectIds(model.features, ctx, ["features"], "Feature");
+  const featureIdsByEffectivePath = /* @__PURE__ */ new Map();
   model.features.forEach((feature, featureIndex) => {
     const segments = feature.id.split(".");
     if (segments.length > 1) {
@@ -1141,6 +1151,20 @@ var OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ct
     const hasChildren = model.features.some(
       (candidate) => candidate.id.startsWith(`${feature.id}.`) && candidate.id !== feature.id
     );
+    const contributesRoutePath = feature.path !== void 0 || !hasChildren;
+    if (contributesRoutePath) {
+      const effectivePath = feature.path ?? defaultFeaturePathFor(feature.id);
+      const existingFeatureId = featureIdsByEffectivePath.get(effectivePath);
+      if (existingFeatureId !== void 0) {
+        addIssue(
+          ctx,
+          ["features", featureIndex, feature.path === void 0 ? "id" : "path"],
+          `Feature "${feature.id}" effective path "${effectivePath}" duplicates feature "${existingFeatureId}"`
+        );
+      } else {
+        featureIdsByEffectivePath.set(effectivePath, feature.id);
+      }
+    }
     if (hasChildren && feature.enabled) {
       const hasEnabledDescendant = model.features.some(
         (candidate) => candidate.id.startsWith(`${feature.id}.`) && candidate.enabled
@@ -1154,6 +1178,43 @@ var OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ct
       }
     }
   });
+  const surfacesById = collectIds(model.navigation.surfaces, ctx, ["navigation", "surfaces"], "Navigation surface");
+  if (model.navigation.defaultSurfaceId !== void 0 && !surfacesById.has(model.navigation.defaultSurfaceId)) {
+    addIssue(
+      ctx,
+      ["navigation", "defaultSurfaceId"],
+      `Navigation defaultSurfaceId references unknown surface "${model.navigation.defaultSurfaceId}"`
+    );
+  }
+  model.navigation.groups.forEach((group, groupIndex) => {
+    group.surfaceIds.forEach((surfaceId, surfaceIndex) => {
+      if (!surfacesById.has(surfaceId)) {
+        addIssue(
+          ctx,
+          ["navigation", "groups", groupIndex, "surfaceIds", surfaceIndex],
+          `Navigation group "${group.id}" references unknown surface "${surfaceId}"`
+        );
+      }
+    });
+  });
+  model.navigation.surfaces.forEach((surface, surfaceIndex) => {
+    if (surface.featureId !== void 0 && !hasFeature(featuresById, surface.featureId)) {
+      addIssue(
+        ctx,
+        ["navigation", "surfaces", surfaceIndex, "featureId"],
+        `Navigation surface "${surface.id}" references unknown feature "${surface.featureId}"`
+      );
+    }
+    surface.featureIds.forEach((featureId, featureIndex) => {
+      if (!hasFeature(featuresById, featureId)) {
+        addIssue(
+          ctx,
+          ["navigation", "surfaces", surfaceIndex, "featureIds", featureIndex],
+          `Navigation surface "${surface.id}" references unknown feature "${featureId}"`
+        );
+      }
+    });
+  });
   const segmentsById = new Map(model.customers.segments.map((seg) => [seg.id, seg]));
   model.offerings.products.forEach((product, productIndex) => {
     product.targetSegmentIds.forEach((segmentId, segmentIndex) => {
@@ -1199,6 +1260,7 @@ var OrganizationGraphNodeKindSchema = z.enum([
   "surface",
   "entity",
   "capability",
+  "stage",
   "resource",
   "knowledge"
 ]);

package/dist/knowledge/index.d.ts

@@ -1216,7 +1216,7 @@ declare const OrganizationModelSchema: z.ZodObject<{
 
 type OrganizationModel = z.infer<typeof OrganizationModelSchema>;
 
-type OrganizationGraphNodeKind = 'organization' | 'feature' | 'surface' | 'entity' | 'capability' | 'resource' | 'knowledge';
+type OrganizationGraphNodeKind = 'organization' | 'feature' | 'surface' | 'entity' | 'capability' | 'stage' | 'resource' | 'knowledge';
 type OrganizationGraphEdgeKind = 'contains' | 'references' | 'exposes' | 'maps_to' | 'operates-on' | 'uses' | 'governs';
 
 interface OrganizationGraphNode {

package/dist/organization-model/index.js

@@ -386,6 +386,12 @@ var ProspectingBuildTemplateSchema = DisplayMetadataSchema.extend({
   id: ModelIdSchema,
   steps: z.array(ProspectingBuildTemplateStepSchema).min(1)
 });
+z.object({
+  id: ModelIdSchema,
+  label: z.string(),
+  description: z.string(),
+  resourceId: ModelIdSchema
+});
 var PROSPECTING_STEPS = {
   localServices: {
     sourceCompanies: {
@@ -1124,8 +1130,12 @@ var LEGACY_FEATURE_ALIASES = /* @__PURE__ */ new Map([
 function hasFeature(featuresById, featureId) {
   return featuresById.has(featureId) || featuresById.has(LEGACY_FEATURE_ALIASES.get(featureId) ?? "");
 }
+function defaultFeaturePathFor(id) {
+  return `/${id.replaceAll(".", "/")}`;
+}
 var OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ctx) => {
   const featuresById = collectIds(model.features, ctx, ["features"], "Feature");
+  const featureIdsByEffectivePath = /* @__PURE__ */ new Map();
   model.features.forEach((feature, featureIndex) => {
     const segments = feature.id.split(".");
     if (segments.length > 1) {
@@ -1141,6 +1151,20 @@ var OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ct
     const hasChildren = model.features.some(
       (candidate) => candidate.id.startsWith(`${feature.id}.`) && candidate.id !== feature.id
     );
+    const contributesRoutePath = feature.path !== void 0 || !hasChildren;
+    if (contributesRoutePath) {
+      const effectivePath = feature.path ?? defaultFeaturePathFor(feature.id);
+      const existingFeatureId = featureIdsByEffectivePath.get(effectivePath);
+      if (existingFeatureId !== void 0) {
+        addIssue(
+          ctx,
+          ["features", featureIndex, feature.path === void 0 ? "id" : "path"],
+          `Feature "${feature.id}" effective path "${effectivePath}" duplicates feature "${existingFeatureId}"`
+        );
+      } else {
+        featureIdsByEffectivePath.set(effectivePath, feature.id);
+      }
+    }
     if (hasChildren && feature.enabled) {
       const hasEnabledDescendant = model.features.some(
         (candidate) => candidate.id.startsWith(`${feature.id}.`) && candidate.enabled
@@ -1154,6 +1178,43 @@ var OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ct
       }
     }
   });
+  const surfacesById = collectIds(model.navigation.surfaces, ctx, ["navigation", "surfaces"], "Navigation surface");
+  if (model.navigation.defaultSurfaceId !== void 0 && !surfacesById.has(model.navigation.defaultSurfaceId)) {
+    addIssue(
+      ctx,
+      ["navigation", "defaultSurfaceId"],
+      `Navigation defaultSurfaceId references unknown surface "${model.navigation.defaultSurfaceId}"`
+    );
+  }
+  model.navigation.groups.forEach((group, groupIndex) => {
+    group.surfaceIds.forEach((surfaceId, surfaceIndex) => {
+      if (!surfacesById.has(surfaceId)) {
+        addIssue(
+          ctx,
+          ["navigation", "groups", groupIndex, "surfaceIds", surfaceIndex],
+          `Navigation group "${group.id}" references unknown surface "${surfaceId}"`
+        );
+      }
+    });
+  });
+  model.navigation.surfaces.forEach((surface, surfaceIndex) => {
+    if (surface.featureId !== void 0 && !hasFeature(featuresById, surface.featureId)) {
+      addIssue(
+        ctx,
+        ["navigation", "surfaces", surfaceIndex, "featureId"],
+        `Navigation surface "${surface.id}" references unknown feature "${surface.featureId}"`
+      );
+    }
+    surface.featureIds.forEach((featureId, featureIndex) => {
+      if (!hasFeature(featuresById, featureId)) {
+        addIssue(
+          ctx,
+          ["navigation", "surfaces", surfaceIndex, "featureIds", featureIndex],
+          `Navigation surface "${surface.id}" references unknown feature "${featureId}"`
+        );
+      }
+    });
+  });
   const segmentsById = new Map(model.customers.segments.map((seg) => [seg.id, seg]));
   model.offerings.products.forEach((product, productIndex) => {
     product.targetSegmentIds.forEach((segmentId, segmentIndex) => {
@@ -1199,6 +1260,7 @@ var OrganizationGraphNodeKindSchema = z.enum([
   "surface",
   "entity",
   "capability",
+  "stage",
   "resource",
   "knowledge"
 ]);

package/dist/test-utils/index.js

@@ -19801,6 +19801,12 @@ var ProspectingBuildTemplateSchema = DisplayMetadataSchema.extend({
   id: ModelIdSchema,
   steps: z.array(ProspectingBuildTemplateStepSchema).min(1)
 });
+z.object({
+  id: ModelIdSchema,
+  label: z.string(),
+  description: z.string(),
+  resourceId: ModelIdSchema
+});
 var PROSPECTING_STEPS = {
   localServices: {
     sourceCompanies: {
@@ -20521,8 +20527,12 @@ var LEGACY_FEATURE_ALIASES = /* @__PURE__ */ new Map([
 function hasFeature(featuresById, featureId) {
   return featuresById.has(featureId) || featuresById.has(LEGACY_FEATURE_ALIASES.get(featureId) ?? "");
 }
+function defaultFeaturePathFor(id) {
+  return `/${id.replaceAll(".", "/")}`;
+}
 var OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ctx) => {
   const featuresById = collectIds(model.features, ctx, ["features"], "Feature");
+  const featureIdsByEffectivePath = /* @__PURE__ */ new Map();
   model.features.forEach((feature, featureIndex) => {
     const segments = feature.id.split(".");
     if (segments.length > 1) {
@@ -20538,6 +20548,20 @@ var OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ct
     const hasChildren = model.features.some(
       (candidate) => candidate.id.startsWith(`${feature.id}.`) && candidate.id !== feature.id
     );
+    const contributesRoutePath = feature.path !== void 0 || !hasChildren;
+    if (contributesRoutePath) {
+      const effectivePath = feature.path ?? defaultFeaturePathFor(feature.id);
+      const existingFeatureId = featureIdsByEffectivePath.get(effectivePath);
+      if (existingFeatureId !== void 0) {
+        addIssue(
+          ctx,
+          ["features", featureIndex, feature.path === void 0 ? "id" : "path"],
+          `Feature "${feature.id}" effective path "${effectivePath}" duplicates feature "${existingFeatureId}"`
+        );
+      } else {
+        featureIdsByEffectivePath.set(effectivePath, feature.id);
+      }
+    }
     if (hasChildren && feature.enabled) {
       const hasEnabledDescendant = model.features.some(
         (candidate) => candidate.id.startsWith(`${feature.id}.`) && candidate.enabled
@@ -20551,6 +20575,43 @@ var OrganizationModelSchema = OrganizationModelSchemaBase.superRefine((model, ct
       }
     }
   });
+  const surfacesById = collectIds(model.navigation.surfaces, ctx, ["navigation", "surfaces"], "Navigation surface");
+  if (model.navigation.defaultSurfaceId !== void 0 && !surfacesById.has(model.navigation.defaultSurfaceId)) {
+    addIssue(
+      ctx,
+      ["navigation", "defaultSurfaceId"],
+      `Navigation defaultSurfaceId references unknown surface "${model.navigation.defaultSurfaceId}"`
+    );
+  }
+  model.navigation.groups.forEach((group, groupIndex) => {
+    group.surfaceIds.forEach((surfaceId, surfaceIndex) => {
+      if (!surfacesById.has(surfaceId)) {
+        addIssue(
+          ctx,
+          ["navigation", "groups", groupIndex, "surfaceIds", surfaceIndex],
+          `Navigation group "${group.id}" references unknown surface "${surfaceId}"`
+        );
+      }
+    });
+  });
+  model.navigation.surfaces.forEach((surface, surfaceIndex) => {
+    if (surface.featureId !== void 0 && !hasFeature(featuresById, surface.featureId)) {
+      addIssue(
+        ctx,
+        ["navigation", "surfaces", surfaceIndex, "featureId"],
+        `Navigation surface "${surface.id}" references unknown feature "${surface.featureId}"`
+      );
+    }
+    surface.featureIds.forEach((featureId, featureIndex) => {
+      if (!hasFeature(featuresById, featureId)) {
+        addIssue(
+          ctx,
+          ["navigation", "surfaces", surfaceIndex, "featureIds", featureIndex],
+          `Navigation surface "${surface.id}" references unknown feature "${featureId}"`
+        );
+      }
+    });
+  });
   const segmentsById = new Map(model.customers.segments.map((seg) => [seg.id, seg]));
   model.offerings.products.forEach((product, productIndex) => {
     product.targetSegmentIds.forEach((segmentId, segmentIndex) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elevasis/core",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "license": "MIT",
   "description": "Minimal shared constants across Elevasis monorepo",
   "sideEffects": false,
@@ -41,8 +41,8 @@
     "rollup-plugin-dts": "^6.3.0",
     "tsup": "^8.0.0",
     "typescript": "5.9.2",
-    "@repo/eslint-config": "0.0.0",
-    "@repo/typescript-config": "0.0.0"
+    "@repo/typescript-config": "0.0.0",
+    "@repo/eslint-config": "0.0.0"
   },
   "dependencies": {
     "@anthropic-ai/sdk": "^0.62.0",

package/src/_gen/__tests__/__snapshots__/contracts.md.snap

@@ -1123,7 +1123,7 @@ export const DEFAULT_CRM_PRIORITY_RULE_CONFIG: CrmPriorityRuleConfig = {
 ### `DealStageSchema`
 
 ```typescript
-export const DealStageSchema = z.enum(['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing'])
+export const DealStageSchema = CrmStageKeySchema
 ```
 
 ### `AcqDealTaskKindSchema`
@@ -1215,7 +1215,7 @@ export const TransitionItemRequestSchema = z
   .object({
     pipelineKey: z.string().min(1),
     stageKey: z.string().min(1),
-    stateKey: z.string().nullable().optional(),
+    stateKey: z.string().min(1).nullable().optional(),
     reason: z.string().optional(),
     expectedUpdatedAt: z.string().datetime().optional()
   })
@@ -1409,6 +1409,11 @@ export const DealTaskListResponseSchema = z.array(DealTaskResponseSchema)
 
 ```typescript
 export const DealSchemas = {
+  // Primitives
+  CrmStageKey: CrmStageKeySchema,
+  CrmStateKey: CrmStateKeySchema,
+  DealStage: DealStageSchema,
+
   // Params
   DealIdParams: DealIdParamsSchema,
   DealTaskIdParams: DealTaskIdParamsSchema,
@@ -1421,7 +1426,7 @@ export const DealSchemas = {
   // Request bodies
   CreateDealNoteRequest: CreateDealNoteRequestSchema,
   CreateDealTaskRequest: CreateDealTaskRequestSchema,
-  TransitionItemRequest: TransitionItemRequestSchema,
+  TransitionItemRequest: CrmTransitionItemRequestSchema,
   TransitionDealStateRequest: TransitionDealStateRequestSchema,
   ExecuteActionParams: ExecuteActionParamsSchema,
   ExecuteActionRequest: ExecuteActionRequestSchema,
@@ -2552,7 +2557,7 @@ export const AcqSubstrateSchemas = {
   ListCompanyIdParams: ListCompanyIdParamsSchema,
   AcqListCompanyResponse: AcqListCompanyResponseSchema,
 
-  // Transition (shared with deals — TransitionItemRequestSchema)
+  // Transition (generic stateful substrate)
   TransitionItemRequest: TransitionItemRequestSchema
 }
 ```
@@ -2620,6 +2625,8 @@ export interface StatefulStageDefinition {
   /** Matches stage_key values written by workflow steps. */
   stageKey: string
   label: string
+  /** UI color token. Consumers may map this to their design system. */
+  color?: string
   states: StatefulStateDefinition[]
 }
 ```

package/src/business/acquisition/api-schemas.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import {
+  CRM_PIPELINE_DEFINITION,
   DEFAULT_CRM_PRIORITY_RULE_CONFIG,
   LEAD_GEN_PIPELINE_DEFINITIONS,
   LEAD_GEN_STAGE_CATALOG
@@ -19,6 +20,9 @@ import {
   CreateContactRequestSchema,
   CreateDealNoteRequestSchema,
   CreateDealTaskRequestSchema,
+  CrmStageKeySchema,
+  CrmStateKeySchema,
+  CrmTransitionItemRequestSchema,
   CreateListRequestSchema,
   DealDetailResponseSchema,
   DealListItemSchema,
@@ -37,6 +41,7 @@ import {
   ListStatusSchema,
   PipelineStageSchema,
   ScrapingConfigSchema,
+  TransitionDealStateRequestSchema,
   TransitionItemRequestSchema,
   UpdateCompanyRequestSchema,
   UpdateContactRequestSchema,
@@ -67,17 +72,31 @@ const PRIORITY = {
 // ---------------------------------------------------------------------------
 
 describe('DealStageSchema', () => {
-  it.each(['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing'])(
-    'accepts canonical stage "%s"',
-    (stage) => {
-      expect(DealStageSchema.safeParse(stage).success).toBe(true)
-    }
-  )
+  const crmStageKeys = CRM_PIPELINE_DEFINITION.stages.map((stage) => stage.stageKey)
+  const crmStateKeys = CRM_PIPELINE_DEFINITION.stages.flatMap((stage) => stage.states.map((state) => state.stateKey))
+
+  it('derives CRM stage keys from CRM_PIPELINE_DEFINITION', () => {
+    expect(CrmStageKeySchema.options).toEqual(crmStageKeys)
+    expect(DealStageSchema.options).toEqual(crmStageKeys)
+  })
+
+  it('derives CRM state keys from CRM_PIPELINE_DEFINITION', () => {
+    expect(CrmStateKeySchema.options).toEqual(crmStateKeys)
+  })
+
+  it.each(crmStageKeys)('accepts canonical stage "%s"', (stage) => {
+    expect(DealStageSchema.safeParse(stage).success).toBe(true)
+  })
 
   it('rejects an unknown stage value', () => {
     expect(DealStageSchema.safeParse('open').success).toBe(false)
     expect(DealStageSchema.safeParse('').success).toBe(false)
   })
+
+  it('rejects unknown CRM state values', () => {
+    expect(CrmStateKeySchema.safeParse('custom_state').success).toBe(false)
+    expect(CrmStateKeySchema.safeParse('').success).toBe(false)
+  })
 })
 
 // ---------------------------------------------------------------------------
@@ -86,7 +105,7 @@ describe('DealStageSchema', () => {
 
 describe('TransitionItemRequestSchema', () => {
   const valid = {
-    pipelineKey: 'default',
+    pipelineKey: 'lead-gen',
     stageKey: 'interested',
     stateKey: null
   }
@@ -122,11 +141,16 @@ describe('TransitionItemRequestSchema', () => {
   })
 
   it('accepts all canonical CRM deal stages', () => {
-    const stages = ['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing']
-    for (const stageKey of stages) {
-      expect(TransitionItemRequestSchema.safeParse({ pipelineKey: 'default', stageKey, stateKey: null }).success).toBe(
-        true
-      )
+    for (const stageKey of CRM_PIPELINE_DEFINITION.stages.map((stage) => stage.stageKey)) {
+      expect(TransitionItemRequestSchema.safeParse({ pipelineKey: 'crm', stageKey, stateKey: null }).success).toBe(true)
+    }
+  })
+
+  it('accepts catalog-derived CRM state keys', () => {
+    for (const stateKey of CRM_PIPELINE_DEFINITION.stages.flatMap((stage) =>
+      stage.states.map((state) => state.stateKey)
+    )) {
+      expect(TransitionItemRequestSchema.safeParse({ ...valid, stateKey }).success).toBe(true)
     }
   })
 
@@ -158,6 +182,11 @@ describe('TransitionItemRequestSchema', () => {
     expect(result.success).toBe(false)
   })
 
+  it('accepts unknown non-empty stage and state keys for generic substrate transitions', () => {
+    expect(TransitionItemRequestSchema.safeParse({ ...valid, stageKey: 'custom_stage' }).success).toBe(true)
+    expect(TransitionItemRequestSchema.safeParse({ ...valid, stateKey: 'custom_state' }).success).toBe(true)
+  })
+
   it('rejects unknown top-level fields (strict mode)', () => {
     const result = TransitionItemRequestSchema.safeParse({ ...valid, unknownField: 'x' })
     expect(result.success).toBe(false)
@@ -176,6 +205,64 @@ describe('TransitionItemRequestSchema', () => {
   })
 })
 
+// ---------------------------------------------------------------------------
+// CrmTransitionItemRequestSchema
+// ---------------------------------------------------------------------------
+
+describe('CrmTransitionItemRequestSchema', () => {
+  const valid = {
+    pipelineKey: 'crm',
+    stageKey: 'interested',
+    stateKey: null
+  }
+
+  it('accepts catalog-derived CRM stage and state keys', () => {
+    for (const stageKey of CRM_PIPELINE_DEFINITION.stages.map((stage) => stage.stageKey)) {
+      expect(CrmTransitionItemRequestSchema.safeParse({ ...valid, stageKey }).success).toBe(true)
+    }
+
+    for (const stateKey of CRM_PIPELINE_DEFINITION.stages.flatMap((stage) =>
+      stage.states.map((state) => state.stateKey)
+    )) {
+      expect(CrmTransitionItemRequestSchema.safeParse({ ...valid, stateKey }).success).toBe(true)
+    }
+  })
+
+  it('rejects non-CRM pipeline keys and unknown CRM keys', () => {
+    expect(CrmTransitionItemRequestSchema.safeParse({ ...valid, pipelineKey: 'lead-gen' }).success).toBe(false)
+    expect(CrmTransitionItemRequestSchema.safeParse({ ...valid, stageKey: 'unknown_stage' }).success).toBe(false)
+    expect(CrmTransitionItemRequestSchema.safeParse({ ...valid, stateKey: 'unknown_state' }).success).toBe(false)
+  })
+})
+
+// ---------------------------------------------------------------------------
+// TransitionDealStateRequestSchema
+// ---------------------------------------------------------------------------
+
+describe('TransitionDealStateRequestSchema', () => {
+  it('accepts catalog-derived CRM state keys', () => {
+    for (const stateKey of CRM_PIPELINE_DEFINITION.stages.flatMap((stage) =>
+      stage.states.map((state) => state.stateKey)
+    )) {
+      expect(TransitionDealStateRequestSchema.safeParse({ stateKey }).success).toBe(true)
+    }
+  })
+
+  it('rejects unknown state values', () => {
+    expect(TransitionDealStateRequestSchema.safeParse({ stateKey: 'unknown_state' }).success).toBe(false)
+    expect(TransitionDealStateRequestSchema.safeParse({ stateKey: '' }).success).toBe(false)
+  })
+
+  it('preserves strict request schema behavior', () => {
+    expect(
+      TransitionDealStateRequestSchema.safeParse({
+        stateKey: CRM_PIPELINE_DEFINITION.stages[0]?.states[0]?.stateKey,
+        extra: 'x'
+      }).success
+    ).toBe(false)
+  })
+})
+
 // ---------------------------------------------------------------------------
 // ExecuteActionRequestSchema
 // ---------------------------------------------------------------------------
@@ -698,7 +785,7 @@ describe('DealDetailResponseSchema (forward-compat)', () => {
     organization_id: VALID_UUID,
     contact_id: null,
     contact_email: 'test@example.com',
-    pipeline_key: 'default',
+    pipeline_key: 'crm',
     stage_key: null,
     state_key: null,
     activity_log: [],
@@ -1585,5 +1672,4 @@ describe('AcqContactResponseSchema (forward-compat)', () => {
   it('rejects an invalid emailValid value', () => {
     expect(AcqContactResponseSchema.safeParse({ ...baseContact, emailValid: 'BAD' }).success).toBe(false)
   })
-
 })

package/src/business/acquisition/api-schemas.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod'
 import { UuidSchema, NonEmptyStringSchema } from '../../platform/utils/validation'
-import { LEAD_GEN_STAGE_CATALOG } from '../../organization-model/domains/sales'
+import { CRM_PIPELINE_DEFINITION, LEAD_GEN_STAGE_CATALOG } from '../../organization-model/domains/sales'
 import { CAPABILITY_REGISTRY } from '../../organization-model/domains/prospecting'
 import { isProspectingBuildTemplateId } from './build-templates'
 export { CrmPriorityBucketKeySchema, CrmPriorityBucketOverrideSchema, CrmPriorityOverrideSchema } from './crm-priority'
@@ -16,10 +16,19 @@ export const LeadGenStageKeySchema = z
 
 export const LeadGenCapabilityKeySchema = z
   .string()
-  .refine((value) => Object.prototype.hasOwnProperty.call(CAPABILITY_REGISTRY, value), {
+  .refine((value) => CAPABILITY_REGISTRY.some((c) => c.id === value), {
     message: 'capabilityKey must match CAPABILITY_REGISTRY'
   })
 
+const crmStageKeys = CRM_PIPELINE_DEFINITION.stages.map((stage) => stage.stageKey) as [string, ...string[]]
+const crmStateKeys = CRM_PIPELINE_DEFINITION.stages.flatMap((stage) => stage.states.map((state) => state.stateKey)) as [
+  string,
+  ...string[]
+]
+
+export const CrmStageKeySchema = z.enum(crmStageKeys)
+export const CrmStateKeySchema = z.enum(crmStateKeys)
+
 export const ProcessingStateEntrySchema = z
   .object({
     status: ProcessingStageStatusSchema,
@@ -47,7 +56,7 @@ export const ContactProcessingStateSchema = ProcessingStateSchema
 // Enum literals (must match DB CHECK constraints exactly)
 // ---------------------------------------------------------------------------
 
-export const DealStageSchema = z.enum(['interested', 'proposal', 'closing', 'closed_won', 'closed_lost', 'nurturing'])
+export const DealStageSchema = CrmStageKeySchema
 
 export const AcqDealTaskKindSchema = z.enum(['call', 'email', 'meeting', 'other'])
 
@@ -115,7 +124,17 @@ export const TransitionItemRequestSchema = z
   .object({
     pipelineKey: z.string().min(1),
     stageKey: z.string().min(1),
-    stateKey: z.string().nullable().optional(),
+    stateKey: z.string().min(1).nullable().optional(),
+    reason: z.string().optional(),
+    expectedUpdatedAt: z.string().datetime().optional()
+  })
+  .strict()
+
+export const CrmTransitionItemRequestSchema = z
+  .object({
+    pipelineKey: z.literal(CRM_PIPELINE_DEFINITION.pipelineKey),
+    stageKey: CrmStageKeySchema,
+    stateKey: CrmStateKeySchema.nullable().optional(),
     reason: z.string().optional(),
     expectedUpdatedAt: z.string().datetime().optional()
   })
@@ -123,7 +142,7 @@ export const TransitionItemRequestSchema = z
 
 export const TransitionDealStateRequestSchema = z
   .object({
-    stateKey: z.string().min(1),
+    stateKey: CrmStateKeySchema,
     reason: z.string().optional(),
     expectedUpdatedAt: z.string().datetime().optional()
   })
@@ -331,6 +350,11 @@ export const DealTaskListResponseSchema = z.array(DealTaskResponseSchema)
 // ---------------------------------------------------------------------------
 
 export const DealSchemas = {
+  // Primitives
+  CrmStageKey: CrmStageKeySchema,
+  CrmStateKey: CrmStateKeySchema,
+  DealStage: DealStageSchema,
+
   // Params
   DealIdParams: DealIdParamsSchema,
   DealTaskIdParams: DealTaskIdParamsSchema,
@@ -343,7 +367,7 @@ export const DealSchemas = {
   // Request bodies
   CreateDealNoteRequest: CreateDealNoteRequestSchema,
   CreateDealTaskRequest: CreateDealTaskRequestSchema,
-  TransitionItemRequest: TransitionItemRequestSchema,
+  TransitionItemRequest: CrmTransitionItemRequestSchema,
   TransitionDealStateRequest: TransitionDealStateRequestSchema,
   ExecuteActionParams: ExecuteActionParamsSchema,
   ExecuteActionRequest: ExecuteActionRequestSchema,
@@ -366,6 +390,8 @@ export const DealSchemas = {
 // ---------------------------------------------------------------------------
 
 export type DealStage = z.infer<typeof DealStageSchema>
+export type CrmStageKey = z.infer<typeof CrmStageKeySchema>
+export type CrmStateKey = z.infer<typeof CrmStateKeySchema>
 export type AcqDealTaskKind = z.infer<typeof AcqDealTaskKindSchema>
 export type DealIdParams = z.infer<typeof DealIdParamsSchema>
 export type DealTaskIdParams = z.infer<typeof DealTaskIdParamsSchema>
@@ -375,6 +401,7 @@ export type ListDealTasksDueQuery = z.infer<typeof ListDealTasksDueQuerySchema>
 export type CreateDealNoteRequest = z.infer<typeof CreateDealNoteRequestSchema>
 export type CreateDealTaskRequest = z.infer<typeof CreateDealTaskRequestSchema>
 export type TransitionItemRequest = z.infer<typeof TransitionItemRequestSchema>
+export type CrmTransitionItemRequest = z.infer<typeof CrmTransitionItemRequestSchema>
 export type TransitionDealStateRequest = z.infer<typeof TransitionDealStateRequestSchema>
 export type ExecuteActionParams = z.infer<typeof ExecuteActionParamsSchema>
 export type ExecuteActionRequest = z.infer<typeof ExecuteActionRequestSchema>
@@ -1090,8 +1117,8 @@ export const AcqListCompanyResponseSchema = z.object({
 })
 
 // ---------------------------------------------------------------------------
-// Track B: Transition Request (shared by list, list-member, list-company)
-// TransitionItemRequestSchema already exists above (for deals) — reuse it.
+// Track B: Transition request for list, list-member, and list-company substrate routes.
+// CRM deals use DealSchemas.TransitionItemRequest, which is catalog-backed.
 // ---------------------------------------------------------------------------
 
 export const AcqCompanySchemas = {
@@ -1197,7 +1224,7 @@ export const AcqSubstrateSchemas = {
   ListCompanyIdParams: ListCompanyIdParamsSchema,
   AcqListCompanyResponse: AcqListCompanyResponseSchema,
 
-  // Transition (shared with deals — TransitionItemRequestSchema)
+  // Transition (generic stateful substrate)
   TransitionItemRequest: TransitionItemRequestSchema
 }