fix(knowledge): validate upload processing options without stranding live sessions

recipe and lang were accepted as free strings up to their length caps, silently
discarded, and echoed back nowhere, so a typo was unobservable: uploading with a
misspelled recipe returned 200 and quietly used the default. Both are now
validated at the boundary and a bad value answers 400 naming what is accepted.

The accepted recipe set deliberately includes the sentinel every first-party
caller sends today alongside the three real chunker recipes, and the three are
derived from the chunker's own union so removing one there is a compile error
here rather than a silent 400 in production.

The same schema also parses metadata read back off a persisted upload session,
so tightening it would have thrown out of resume and complete for any session
created before this - a 500 on work that could then never finish. The read-back
path now drops a value it no longer recognises instead of rejecting it; the
request boundary stays strict.

Neither field reaches chunking, so nothing here moves chunk boundaries,
embeddings, or search results.

Author: waleedlatif1

apps/sim/app/workspace/[workspaceId]/knowledge/hooks/use-knowledge-upload.ts

@@ -3,6 +3,7 @@ import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
 import { useQueryClient } from '@tanstack/react-query'
 import type { V2KnowledgeDocumentSummary } from '@/lib/api/contracts/v2/knowledge'
+import type { KnowledgeDocumentUploadRecipe } from '@/lib/knowledge/upload-metadata'
 import {
   assertMultiFileUploadAdmission,
   MultiFileUploadAdmissionError,
@@ -49,7 +50,7 @@ export interface UploadError {
 }
 
 export interface ProcessingOptions {
-  recipe?: string
+  recipe?: KnowledgeDocumentUploadRecipe
 }
 
 export interface UseKnowledgeUploadOptions {

apps/sim/lib/api/contracts/v2/knowledge.ts

@@ -59,7 +59,10 @@ import {
   rerankerModelSchema,
   rerankerStatusSchema,
 } from '@/lib/knowledge/reranker-models'
-import { knowledgeDocumentUploadMetadataSchema } from '@/lib/knowledge/upload-metadata'
+import {
+  KNOWLEDGE_DOCUMENT_UPLOAD_RECIPES,
+  knowledgeDocumentUploadMetadataSchema,
+} from '@/lib/knowledge/upload-metadata'
 import { MAX_KNOWLEDGE_DOCUMENT_FILE_SIZE } from '@/lib/uploads/shared/types'
 
 /**
@@ -481,10 +484,14 @@ const v2KnowledgeDocumentProcessingOptionsSchema =
     .extend({
       recipe: knowledgeDocumentUploadMetadataSchema.shape.processingOptions
         .unwrap()
-        .shape.recipe.describe('Optional document processing recipe.'),
+        .shape.recipe.describe(
+          `Optional document processing recipe. One of: ${KNOWLEDGE_DOCUMENT_UPLOAD_RECIPES.join(', ')}.`
+        ),
       lang: knowledgeDocumentUploadMetadataSchema.shape.processingOptions
         .unwrap()
-        .shape.lang.describe('Optional document language code.'),
+        .shape.lang.describe(
+          'Optional document language, as a BCP-47 tag such as `en` or `en-US`.'
+        ),
     })
     .strict()
 

apps/sim/lib/knowledge/application/upload-sessions.test.ts

@@ -362,6 +362,46 @@ describe('knowledge-document upload application lifecycle', () => {
     )
   })
 
+  it('completes a session whose persisted recipe and lang predate their validation', async () => {
+    mocks.getUpload.mockResolvedValue({
+      ...SESSION,
+      metadata: {
+        ...SESSION.metadata,
+        processingOptions: { recipe: 'super-chunker-9000', lang: 'en_US' },
+      },
+    })
+    mocks.completeUpload.mockImplementation(
+      async (params: {
+        session: UploadSessionRecord
+        finalize: (session: UploadSessionRecord) => Promise<{
+          value: { document: typeof DOCUMENT; created: boolean; knowledgeBaseName: string | null }
+          completedFileId?: string
+        }>
+      }) => {
+        const finalized = await params.finalize(params.session)
+        return {
+          session: { ...params.session, status: 'completed' as const },
+          value: finalized.value,
+          alreadyCompleted: false,
+        }
+      }
+    )
+
+    const result = await completeKnowledgeDocumentUpload.execute({
+      principal: PRINCIPAL,
+      input: {
+        knowledgeBaseId: 'knowledge-1',
+        assertedWorkspaceId: 'workspace-1',
+        uploadId: 'upload-1',
+        uploadToken: 'token',
+        source: 'api',
+      },
+      request: REQUEST,
+    })
+
+    expect(result.value.created).toBe(true)
+  })
+
   it('returns an already-bound document without re-billing, re-registering, or auditing', async () => {
     mocks.findBound.mockResolvedValue({ status: 'bound', document: DOCUMENT })
     mocks.completeUpload.mockImplementation(

apps/sim/lib/knowledge/application/upload-sessions.ts

@@ -23,7 +23,7 @@ import type { CreatedKnowledgeDocument } from '@/lib/knowledge/orchestration/doc
 import { findBoundKnowledgeDocument } from '@/lib/knowledge/orchestration/documents'
 import {
   type KnowledgeDocumentUploadMetadata,
-  knowledgeDocumentUploadMetadataSchema,
+  persistedKnowledgeDocumentUploadMetadataSchema,
 } from '@/lib/knowledge/upload-metadata'
 import { recordKnowledgeBaseFileOwnership } from '@/lib/uploads/server/metadata'
 import { requestOrigin } from '@/lib/uploads/upload-session/application'
@@ -456,9 +456,13 @@ async function reauthorizeKnowledgeDocumentUpload(
   return context
 }
 
+/**
+ * Reads metadata back off a persisted session, so it uses the lenient schema:
+ * a session created before `recipe`/`lang` were constrained must still resume.
+ */
 function knowledgeDocumentMetadataFor(session: UploadSessionRecord) {
   const { authBinding: _authBinding, ...metadata } = session.metadata
-  return knowledgeDocumentUploadMetadataSchema.parse(metadata)
+  return persistedKnowledgeDocumentUploadMetadataSchema.parse(metadata)
 }
 
 function knowledgeDocumentInputFor(session: UploadSessionRecord) {

apps/sim/lib/knowledge/upload-metadata.test.ts

@@ -0,0 +1,92 @@
+/**
+ * @vitest-environment node
+ */
+import { describe, expect, it } from 'vitest'
+import {
+  KNOWLEDGE_DOCUMENT_UPLOAD_RECIPES,
+  knowledgeDocumentUploadMetadataSchema,
+  persistedKnowledgeDocumentUploadMetadataSchema,
+} from '@/lib/knowledge/upload-metadata'
+
+describe('knowledgeDocumentUploadMetadataSchema', () => {
+  it('rejects a recipe outside the accepted set', () => {
+    const result = knowledgeDocumentUploadMetadataSchema.safeParse({
+      processingOptions: { recipe: 'totally-bogus-recipe' },
+    })
+    expect(result.success).toBe(false)
+    expect(result.error?.issues[0]?.path).toEqual(['processingOptions', 'recipe'])
+    expect(result.error?.issues[0]?.message).toContain('recipe must be one of')
+  })
+
+  it('rejects a lang that is not a BCP-47 tag', () => {
+    const result = knowledgeDocumentUploadMetadataSchema.safeParse({
+      processingOptions: { lang: 'zzzz-nonsense!' },
+    })
+    expect(result.success).toBe(false)
+    expect(result.error?.issues[0]?.message).toContain('BCP-47')
+  })
+
+  it('rejects the underscore locale form callers reach for', () => {
+    expect(
+      knowledgeDocumentUploadMetadataSchema.safeParse({ processingOptions: { lang: 'en_US' } })
+        .success
+    ).toBe(false)
+  })
+
+  it('accepts what first-party callers actually send today', () => {
+    const result = knowledgeDocumentUploadMetadataSchema.safeParse({
+      tag1: 'product',
+      processingOptions: { recipe: 'default', lang: 'en' },
+    })
+    expect(result.success).toBe(true)
+    expect(result.data?.processingOptions).toEqual({ recipe: 'default', lang: 'en' })
+  })
+
+  it('accepts a multi-subtag BCP-47 tag', () => {
+    expect(
+      knowledgeDocumentUploadMetadataSchema.safeParse({ processingOptions: { lang: 'zh-Hant-TW' } })
+        .success
+    ).toBe(true)
+  })
+
+  it('keeps the chunker recipes accepted alongside the default sentinel', () => {
+    expect(KNOWLEDGE_DOCUMENT_UPLOAD_RECIPES).toContain('default')
+    expect(
+      knowledgeDocumentUploadMetadataSchema.safeParse({ processingOptions: { recipe: 'markdown' } })
+        .success
+    ).toBe(true)
+  })
+})
+
+describe('persistedKnowledgeDocumentUploadMetadataSchema', () => {
+  it('drops a recipe persisted before the enum landed instead of throwing', () => {
+    const parsed = persistedKnowledgeDocumentUploadMetadataSchema.parse({
+      tag1: 'product',
+      processingOptions: { recipe: 'super-chunker-9000', lang: 'en' },
+    })
+    expect(parsed.processingOptions).toEqual({ recipe: undefined, lang: 'en' })
+    expect(parsed.tag1).toBe('product')
+  })
+
+  it('drops a lang persisted before the BCP-47 shape landed instead of throwing', () => {
+    const parsed = persistedKnowledgeDocumentUploadMetadataSchema.parse({
+      processingOptions: { recipe: 'default', lang: 'en_US' },
+    })
+    expect(parsed.processingOptions).toEqual({ recipe: 'default', lang: undefined })
+  })
+
+  it('does not throw on a session whose processing options are wholly unrecognized', () => {
+    expect(() =>
+      persistedKnowledgeDocumentUploadMetadataSchema.parse({
+        processingOptions: { recipe: 42, lang: false },
+      })
+    ).not.toThrow()
+  })
+
+  it('preserves recognized values', () => {
+    const parsed = persistedKnowledgeDocumentUploadMetadataSchema.parse({
+      processingOptions: { recipe: 'code', lang: 'en-US' },
+    })
+    expect(parsed.processingOptions).toEqual({ recipe: 'code', lang: 'en-US' })
+  })
+})

apps/sim/lib/knowledge/upload-metadata.ts

@@ -1,28 +1,90 @@
 import { z } from 'zod'
+import type { RecursiveRecipe } from '@/lib/chunkers/types'
+
+/**
+ * Recipes the recursive chunker implements. Mirrors `RecursiveRecipe`; the
+ * `satisfies` keeps a rename or removal there a compile error here.
+ */
+const RECURSIVE_RECIPES = [
+  'plain',
+  'markdown',
+  'code',
+] as const satisfies readonly RecursiveRecipe[]
+
+/**
+ * Recipes accepted on a document upload. `'default'` is not a chunker recipe —
+ * it is the long-standing sentinel every first-party caller sends to mean "use
+ * the knowledge base's configured strategy", so it must stay accepted.
+ */
+export const KNOWLEDGE_DOCUMENT_UPLOAD_RECIPES = ['default', ...RECURSIVE_RECIPES] as const
+
+export type KnowledgeDocumentUploadRecipe = (typeof KNOWLEDGE_DOCUMENT_UPLOAD_RECIPES)[number]
+
+/**
+ * BCP-47 language tag: a 2-8 letter primary subtag followed by any number of
+ * alphanumeric subtags, e.g. `en`, `en-US`, `zh-Hant-TW`.
+ */
+const BCP47_LANGUAGE_TAG = /^[A-Za-z]{2,8}(?:-[A-Za-z0-9]{1,8})*$/
 
 const knowledgeDocumentUploadTagSchema = z
   .string()
   .max(1000, 'Knowledge document tag values cannot exceed 1000 characters')
   .optional()
 
+const knowledgeDocumentUploadTagShape = {
+  tag1: knowledgeDocumentUploadTagSchema,
+  tag2: knowledgeDocumentUploadTagSchema,
+  tag3: knowledgeDocumentUploadTagSchema,
+  tag4: knowledgeDocumentUploadTagSchema,
+  tag5: knowledgeDocumentUploadTagSchema,
+  tag6: knowledgeDocumentUploadTagSchema,
+  tag7: knowledgeDocumentUploadTagSchema,
+}
+
+const recipeSchema = z.enum(KNOWLEDGE_DOCUMENT_UPLOAD_RECIPES, {
+  error: `recipe must be one of: ${KNOWLEDGE_DOCUMENT_UPLOAD_RECIPES.join(', ')}`,
+})
+
+const langSchema = z
+  .string()
+  .max(35, 'lang cannot exceed 35 characters')
+  .regex(BCP47_LANGUAGE_TAG, 'lang must be a BCP-47 language tag, for example "en" or "en-US"')
+
 /** Persisted metadata stored with a resumable Knowledge document upload session. */
 export const knowledgeDocumentUploadMetadataSchema = z
   .object({
-    tag1: knowledgeDocumentUploadTagSchema,
-    tag2: knowledgeDocumentUploadTagSchema,
-    tag3: knowledgeDocumentUploadTagSchema,
-    tag4: knowledgeDocumentUploadTagSchema,
-    tag5: knowledgeDocumentUploadTagSchema,
-    tag6: knowledgeDocumentUploadTagSchema,
-    tag7: knowledgeDocumentUploadTagSchema,
+    ...knowledgeDocumentUploadTagShape,
     processingOptions: z
       .object({
-        recipe: z.string().max(255, 'recipe cannot exceed 255 characters').optional(),
-        lang: z.string().max(35, 'lang cannot exceed 35 characters').optional(),
+        recipe: recipeSchema.optional(),
+        lang: langSchema.optional(),
       })
       .strict()
       .optional(),
   })
   .strict()
 
 export type KnowledgeDocumentUploadMetadata = z.output<typeof knowledgeDocumentUploadMetadataSchema>
+
+/**
+ * Read-back variant for metadata already persisted on an upload session.
+ *
+ * The strict schema above is a *request* boundary and rejects an unrecognized
+ * `recipe`/`lang`. Sessions created before those constraints existed can carry
+ * values that no longer parse, and rejecting them here would throw a raw
+ * `ZodError` out of resume/complete — a 500 on a session that could never be
+ * finished. Unrecognized values are dropped instead; neither field affects
+ * processing today, so dropping one changes nothing but the analytics property.
+ */
+export const persistedKnowledgeDocumentUploadMetadataSchema = z
+  .object({
+    ...knowledgeDocumentUploadTagShape,
+    processingOptions: z
+      .object({
+        recipe: recipeSchema.optional().catch(undefined),
+        lang: langSchema.optional().catch(undefined),
+      })
+      .strict()
+      .optional(),
+  })
+  .strict()