fix(api): retire route contracts that no route serves

The staging integ alarm fired because the session knowledge-document
inline-create check got a 405. #7179 moved tool operations in process and
deleted the routes that only existed to serve them, but
`createKnowledgeDocumentsContract` kept declaring
`POST /api/knowledge/[id]/documents` — a path whose surviving GET/PATCH make
Next.js answer POST with 405 rather than an honest 404. Nothing in the repo
called it: the KB UI creates documents through the presigned upload flow, and
the capability itself is unaffected because `knowledge_create_document` reaches
the same use case in process.

Audited all 1125 contracts for the same drift. It was the only one whose path
resolves to a live route missing the declared method; 259 others declare paths
of routes that were deleted outright, which 404 honestly and are left alone.

- Drop the create-documents route contract for plain `params`/`body` schemas
  plus a named response schema, so nothing declares an endpoint we do not
  serve. The schemas stay in the contracts tree next to the siblings they share
  (`documentDataSchema` is used by the v2 contracts, and
  `createKnowledgeDocumentsBodySchema` already backed the in-process operation).
- Delete four contracts with no consumer at all — both TTS contracts, docusign,
  and mistral. Their handlers own better schemas: TTS dispatches by `toolId`
  with eight per-provider schemas instead of one passthrough superset, and
  mistral bounds `pages` by the OCR request policy. crowdstrike and windchill
  look similar but are load-bearing (schema and derived types are imported by
  live code), so they stay.
- Add `check:api-contract-routes`, picked up automatically by `run-audits`.
  `check:route-verbs` scans routes to contracts, so a contract whose route
  method was deleted is invisible to it — verified it passes clean against the
  exact regression this catches.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

Author: icecrasher321

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

@@ -319,16 +319,23 @@ export const listKnowledgeDocumentsContract = defineRouteContract({
   },
 })
 
-export const createKnowledgeDocumentsContract = defineRouteContract({
-  method: 'POST',
-  path: '/api/knowledge/[id]/documents',
+/**
+ * Document creation from inline content has no HTTP route: `POST
+ * /api/knowledge/[id]/documents` was retired when tool operations moved
+ * in-process, and the surviving `GET`/`PATCH` on that path would answer a `POST`
+ * with 405. So these stay plain schemas rather than a `defineRouteContract` —
+ * `lib/internal/knowledge/execute-tool.ts` validates `knowledge_create_document`
+ * against them directly. Callers wanting an HTTP upload use v1 or v2, both of
+ * which take multipart file bodies rather than inline content.
+ */
+export const createKnowledgeDocumentsSchemas = {
   params: knowledgeBaseParamsSchema,
   body: createKnowledgeDocumentsBodySchema,
-  response: {
-    mode: 'json',
-    schema: successResponseSchema(z.union([bulkCreateDocumentsResponseSchema, documentDataSchema])),
-  },
-})
+} as const
+
+export const createKnowledgeDocumentsResponseSchema = successResponseSchema(
+  z.union([bulkCreateDocumentsResponseSchema, documentDataSchema])
+)
 
 export const updateKnowledgeDocumentContract = defineRouteContract({
   method: 'PUT',

apps/sim/lib/api/contracts/tools/docusign.ts

@@ -4,7 +4,6 @@ export * from './communication'
 export * from './crowdstrike'
 export * from './custom'
 export * from './databases'
-export * from './docusign'
 export * from './file'
 export * from './google'
 export * from './imap'

apps/sim/lib/api/contracts/tools/index.ts

@@ -3,7 +3,7 @@ import { resolvedSecretTraceProvenanceSchema } from '@/lib/api/contracts/primiti
 import { AWS_REGION_PATTERN, toolJsonResponseSchema } from '@/lib/api/contracts/tools/media/shared'
 import { defineRouteContract } from '@/lib/api/contracts/types'
 import { RESOLVED_SECRET_PROVENANCE_FIELD } from '@/lib/execution/private-tool-metadata'
-import { FileInputSchema, RawFileInputSchema } from '@/lib/uploads/utils/file-schemas'
+import { RawFileInputSchema } from '@/lib/uploads/utils/file-schemas'
 
 const textractQuerySchema = z.object({
   Text: z.string().min(1),
@@ -110,19 +110,6 @@ export const textractAnalyzeIdBodySchema = z
     }
   })
 
-export const mistralParseBodySchema = z.object({
-  apiKey: z.string().min(1, 'API key is required'),
-  filePath: z.string().min(1, 'File path is required').optional(),
-  fileData: FileInputSchema.optional(),
-  file: FileInputSchema.optional(),
-  resultType: z.string().optional(),
-  pages: z.array(z.number()).optional(),
-  includeImageBase64: z.boolean().optional(),
-  imageLimit: z.number().optional(),
-  imageMinSize: z.number().optional(),
-  [RESOLVED_SECRET_PROVENANCE_FIELD]: resolvedSecretTraceProvenanceSchema.optional(),
-})
-
 export const textractParseContract = defineRouteContract({
   method: 'POST',
   path: '/api/tools/textract/parse',
@@ -143,10 +130,3 @@ export const textractAnalyzeIdContract = defineRouteContract({
   body: textractAnalyzeIdBodySchema,
   response: { mode: 'json', schema: toolJsonResponseSchema },
 })
-
-export const mistralParseContract = defineRouteContract({
-  method: 'POST',
-  path: '/api/tools/mistral/parse',
-  body: mistralParseBodySchema,
-  response: { mode: 'json', schema: toolJsonResponseSchema },
-})

apps/sim/lib/api/contracts/tools/media/document-parse.ts

@@ -1,5 +1,4 @@
 export * from '@/lib/api/contracts/tools/media/document-parse'
 export * from '@/lib/api/contracts/tools/media/image'
 export * from '@/lib/api/contracts/tools/media/shared'
-export * from '@/lib/api/contracts/tools/media/tts'
 export * from '@/lib/api/contracts/tools/media/video'

apps/sim/lib/api/contracts/tools/media/index.ts

@@ -52,6 +52,33 @@ export type ResponseMode<S extends ApiSchema = ApiSchema> =
   | StreamResponseMode
   | RedirectResponseMode
 
+/**
+ * A contract is consumed in one of two modes, and `method`/`path` only describe
+ * the first.
+ *
+ * **Boundary mode** — the common one. The contract bridges the client/server
+ * gap: a route builder under `app/api/**` serves `method` at `path`, and
+ * `requestJson(contract, …)` on the client parses the request out and validates
+ * the response back. Both sides read the same declaration, so `method` and
+ * `path` are load-bearing.
+ *
+ * **In-process mode.** Tool operations that once self-hopped over HTTP now
+ * execute in the same process (`lib/internal/<domain>/execute-tool.ts`), and
+ * they kept their contract as the input/response schema bundle —
+ * `parseInternalContractInput` reads only `params`, `query`, and `body`, and
+ * never looks at `method` or `path`. For these there is no route and no client
+ * fetch; `method` and `path` are vestigial, describing the HTTP endpoint the
+ * operation *used* to expose. Do not read them as evidence that an endpoint
+ * exists, and do not point a client at one.
+ *
+ * The distinction is not expressed in the type, so which mode a contract is in
+ * is derived, never annotated per file — `bun run check:api-contract-routes
+ * --list-in-process` enumerates the in-process set from the tree rather than
+ * from a hand-maintained list that would drift. That same audit enforces the
+ * part which actually matters: an in-process contract may not claim a `path`
+ * whose live route serves other methods, because a caller trusting the
+ * declaration gets a 405 rather than an honest 404.
+ */
 export interface ApiRouteContract<
   TParams extends ApiSchema | undefined = undefined,
   TQuery extends ApiSchema | undefined = undefined,

apps/sim/lib/api/contracts/tools/media/tts.ts

@@ -1,8 +1,9 @@
 import { createLogger } from '@sim/logger'
-import type { AnyApiRouteContract } from '@/lib/api/contracts'
+import type { AnyApiRouteContract, ApiSchema } from '@/lib/api/contracts'
 import {
   createKnowledgeChunkContract,
-  createKnowledgeDocumentsContract,
+  createKnowledgeDocumentsResponseSchema,
+  createKnowledgeDocumentsSchemas,
   deleteKnowledgeChunkContract,
   deleteKnowledgeDocumentContract,
   getKnowledgeConnectorContract,
@@ -36,7 +37,10 @@ import {
   upsertDocumentOperation,
 } from '@/lib/internal/knowledge/operations'
 import { createExecutorPrincipalFromExecutionContext } from '@/lib/internal/principals/executor'
-import { parseInternalContractInput } from '@/lib/internal/tool-operations/parse-contract-input'
+import {
+  parseInternalContractInput,
+  parseInternalOperationInput,
+} from '@/lib/internal/tool-operations/parse-contract-input'
 import type { InternalToolOperationHandler } from '@/lib/internal/tool-operations/types'
 import { internalKnowledgeErrorPolicies } from '@/lib/knowledge/api/route-policies'
 import { KNOWLEDGE_DELEGATION_AUDIENCE } from '@/lib/knowledge/application/authorization'
@@ -92,15 +96,19 @@ function projectError(
   )
 }
 
+function schemaSuccessResponse(schema: ApiSchema, result: KnowledgeOperationResponse): Response {
+  const validated = schema.parse(result.body) as Record<string, unknown>
+  return Response.json({ ...validated, ...result.bodyFields }, { headers: result.headers })
+}
+
 function successResponse<C extends AnyApiRouteContract>(
   contract: C,
   result: KnowledgeOperationResponse
 ): Response {
   if (contract.response.mode !== 'json') {
     throw new Error('Knowledge tool contract must return JSON')
   }
-  const validated = contract.response.schema.parse(result.body) as Record<string, unknown>
-  return Response.json({ ...validated, ...result.bodyFields }, { headers: result.headers })
+  return schemaSuccessResponse(contract.response.schema, result)
 }
 
 /** Executes every Knowledge tool through the same authorized application use cases as HTTP. */
@@ -132,10 +140,10 @@ export const executeKnowledgeTool: InternalToolOperationHandler = async (request
     switch (toolId) {
       case 'knowledge_create_document': {
         policy = internalKnowledgeErrorPolicies.uploads
-        const parsed = parseInternalContractInput(createKnowledgeDocumentsContract, input)
+        const parsed = parseInternalOperationInput(createKnowledgeDocumentsSchemas, input)
         if (!parsed.success) return parsed.response
-        return successResponse(
-          createKnowledgeDocumentsContract,
+        return schemaSuccessResponse(
+          createKnowledgeDocumentsResponseSchema,
           await createDocumentsOperation(parsed.data.params.id, parsed.data.body, context)
         )
       }

apps/sim/lib/api/contracts/types.ts

@@ -1,9 +1,11 @@
 import type { z } from 'zod'
 import type {
   AnyApiRouteContract,
+  ApiSchema,
   ContractBody,
   ContractParams,
   ContractQuery,
+  EmptySchemaOutput,
 } from '@/lib/api/contracts'
 import { serializeZodIssues } from '@/lib/api/server/validation'
 
@@ -13,23 +15,55 @@ export interface ParsedInternalContractInput<P, Q, B> {
   body: B
 }
 
+/**
+ * The request slices an in-process operation validates, for an operation whose
+ * HTTP route has been retired: it passes its schemas directly rather than
+ * keeping a contract that declares a `method` and `path` nothing serves.
+ */
+export interface InternalOperationSchemas {
+  params?: ApiSchema
+  query?: ApiSchema
+  body?: ApiSchema
+}
+
+type ParseResult<P, Q, B> =
+  | { success: true; data: ParsedInternalContractInput<P, Q, B> }
+  | { success: false; response: Response }
+
 function validationError(error: z.ZodError): Response {
   return Response.json(
     { error: 'Validation error', details: serializeZodIssues(error) },
     { status: 400 }
   )
 }
 
+/**
+ * Contract callers keep their own entry point because `ContractParams<C>` and
+ * friends `infer` each slice out of the contract's generics. Reading the same
+ * slices off an optional-property shape widens every one of them with
+ * `undefined`, which breaks narrowing at every call site.
+ */
 export function parseInternalContractInput<C extends AnyApiRouteContract>(
   contract: C,
   input: unknown,
   options: { maxInputBytes?: number } = {}
-):
-  | {
-      success: true
-      data: ParsedInternalContractInput<ContractParams<C>, ContractQuery<C>, ContractBody<C>>
-    }
-  | { success: false; response: Response } {
+): ParseResult<ContractParams<C>, ContractQuery<C>, ContractBody<C>> {
+  return parseInternalOperationInput(contract, input, options) as ParseResult<
+    ContractParams<C>,
+    ContractQuery<C>,
+    ContractBody<C>
+  >
+}
+
+export function parseInternalOperationInput<S extends InternalOperationSchemas>(
+  schemas: S,
+  input: unknown,
+  options: { maxInputBytes?: number } = {}
+): ParseResult<
+  EmptySchemaOutput<S['params']>,
+  EmptySchemaOutput<S['query']>,
+  EmptySchemaOutput<S['body']>
+> {
   if (options.maxInputBytes !== undefined) {
     let serialized: string
     try {
@@ -53,21 +87,21 @@ export function parseInternalContractInput<C extends AnyApiRouteContract>(
     }
   }
 
-  const params = contract.params?.safeParse(input)
+  const params = schemas.params?.safeParse(input)
   if (params && !params.success) return { success: false, response: validationError(params.error) }
 
-  const query = contract.query?.safeParse(input)
+  const query = schemas.query?.safeParse(input)
   if (query && !query.success) return { success: false, response: validationError(query.error) }
 
-  const body = contract.body?.safeParse(input)
+  const body = schemas.body?.safeParse(input)
   if (body && !body.success) return { success: false, response: validationError(body.error) }
 
   return {
     success: true,
     data: {
-      params: (params?.data ?? undefined) as ContractParams<C>,
-      query: (query?.data ?? undefined) as ContractQuery<C>,
-      body: (body?.data ?? undefined) as ContractBody<C>,
+      params: (params?.data ?? undefined) as EmptySchemaOutput<S['params']>,
+      query: (query?.data ?? undefined) as EmptySchemaOutput<S['query']>,
+      body: (body?.data ?? undefined) as EmptySchemaOutput<S['body']>,
     },
   }
 }