chore(audits): check raw-route parseRequest contracts and enforce surface-neutral application imports (#8883)

* chore(audits): check raw-route parseRequest contracts and enforce surface-neutral application imports

check:route-verbs now resolves the contract each raw withRouteHandler route
passes to parseRequest and checks the exported verb and path against it
(322 sites across 258 files, previously unchecked). check:boundaries now bans
next/server and app/api imports, and runtime route-contract, presenter and
Copilot-handler imports, from application code. listSearchSources takes its
cursor route from the adapter instead of importing the route contract.

* fix(tests): pass cursorRoute in the org source-summary integration case

* fix(audits): resolve aliased contract imports and export-list verbs in check:route-verbs

Read a contract by the name its module exports, not the local alias, and
read handler verbs from export lists (export { GET }, export { h as GET })
as well as inline exports. Both builder and raw parseRequest sites share
the fix.

* fix(audits): follow aliased parseRequest imports and relative application imports

check:route-verbs matched raw parseRequest calls only by the literal name, so
`import { parseRequest as parse }` left the contract unchecked; it now matches
every local name bound to parseRequest from @/lib/api/server(/validation).

check:boundaries applied the application rules only to @/ specifiers, so a
relative import of a contract object, presenter, Copilot handler or app/api
module passed; relative specifiers are now normalized to their @/ form first.

* fix(audits): accept HEAD on a GET contract and treat empty import/export clauses as runtime edges

* fix(audits): keep the HEAD-on-GET allowance off defineScimRoute and catch extension-suffixed presenter imports

* fix(audits): follow exported non-verb helpers when resolving raw-route contracts

Author: waleedlatif1

.agents/skills/migrate-application-operation/SKILL.md

@@ -226,7 +226,7 @@ Do not call shared authorization, principal audit attribution, or `recordAudit`
 
 Inspect legacy orchestration before reusing it. If it already authorizes, audits, notifies, or captures analytics, call a lower-level primitive or remove duplicate responsibility for migrated callers.
 
-Application code must remain surface-neutral. It must not import `app/api/**`, `next/server`, internal/v1/v2 contracts or presenters, or Copilot tool handlers. Return domain values and let each surface presenter project its own wire result.
+Application code stays surface-neutral (`check:boundaries`): never `next/server` or `app/api/**`, and never a runtime import of a route contract object, presenter, or Copilot handler (contract types, schemas, and constants are fine); a surface fact, such as a cursor's route, comes in as input. Return domain values and let each surface presenter project its own wire result.
 
 ## Adapt internal APIs
 

CLAUDE.md

@@ -72,7 +72,7 @@ packages/
 - Every protected read, write, canonical resource lookup, or authorization-sensitive reference resolution enters through an authorized application use case.
 - Define one stable semantic operation with its minimum role, workspace-key policy, allowed principal kinds, and delegated services. Internal APIs, v2 APIs, Copilot, and trusted tools call the same use case when the domain behavior is the same.
 - Surface adapters authenticate and construct a `Principal`, apply request-rate policy, parse contracts, map input, and present their own result. They never query protected data, decide resource authorization, implement business transactions, or record semantic audit.
-- Application use cases load canonical context, compare asserted scope, authorize current access, execute managers/repositories, project semantic audit, and trigger shared domain effects. Managers accept canonical IDs and scope, never credentials or principals. Application code stays surface-neutral: it never imports `app/api/**`, `next/server`, route contracts/presenters, or Copilot handlers.
+- Application use cases load canonical context, compare asserted scope, authorize current access, execute managers/repositories, project semantic audit, and trigger shared domain effects. Managers accept canonical IDs and scope, never credentials or principals. Application code stays surface-neutral (`check:boundaries`): never `next/server` or `app/api/**`, and never a runtime import of a route contract object, presenter, or Copilot handler (contract types, schemas, and constants are fine); a surface fact, such as a cursor's route, comes in as input.
 - Copilot is a surface adapter. Use `createCopilotApplicationAdapter` and the domain's registered operation object; never a Copilot-only authorization or business implementation.
 - Protected compound mutations belong in one top-level semantic application operation, never a sequence of independently committing mutations in a route or tool adapter.
 - Never substitute a billing owner, uploader, creator, or API-key owner for the acting principal. Fail fast when the identity model or operation policy cannot express the caller.

apps/sim/app/api/knowledge/sim-search/sources/route.ts

@@ -1,4 +1,5 @@
 import { listSearchSourcesContract } from '@/lib/api/contracts/knowledge'
+import { cursorRoute } from '@/lib/api/cursor-binding'
 import {
   defineInternalJsonRoute,
   internalRateLimits,
@@ -16,7 +17,7 @@ export const GET = defineInternalJsonRoute({
     reason: 'Workspace source summaries for the Search page and indexing status polling',
   }),
   errorPolicy: internalKnowledgeErrorPolicies.connectors,
-  mapInput: ({ query }) => query,
+  mapInput: ({ query }) => ({ ...query, cursorRoute: cursorRoute(listSearchSourcesContract) }),
   useCase: listSearchSources,
   present: (page) => ({ success: true as const, data: page }),
   staticResponseHeaders: { 'Cache-Control': 'private, no-store' },

apps/sim/lib/knowledge/__integration__/search-source-pagination.integration.ts

@@ -23,7 +23,8 @@ const sourceIds = Array.from({ length: 105 }, () => generateId())
   .sort()
   .reverse()
 const olderSourceId = generateId()
-const input = { workspaceId: ids.workspaceId }
+const cursorRoute = { method: 'GET', path: '/api/knowledge/sim-search/sources' }
+const input = { workspaceId: ids.workspaceId, cursorRoute }
 
 beforeAll(async () => {
   await seedKnowledgeAclFixture(ids)
@@ -157,8 +158,10 @@ describe('bounded live Search source configuration pagination', () => {
       connectorType: 'google_drive',
       approved: false,
     })
-    const owner = { organizationId: ids.organizationId }
-    const summary = await listSearchSources.execute({ principal: alice, input: owner })
+    const summary = await listSearchSources.execute({
+      principal: alice,
+      input: { organizationId: ids.organizationId, cursorRoute },
+    })
     expect(summary.sources[0]).toMatchObject({
       connectorId: approvalSourceId,
       approved: false,

apps/sim/lib/knowledge/application/search-sources.test.ts

@@ -47,7 +47,8 @@ workspaceAuthzMockFns.mockPermissionSatisfies.mockImplementation(
 )
 
 const principal = createSessionPrincipal({ userId: 'reader', sessionId: 'session' })
-const input = { workspaceId: 'workspace' }
+const cursorRoute = { method: 'GET', path: '/api/knowledge/sim-search/sources' }
+const input = { workspaceId: 'workspace', cursorRoute }
 const LAST_SYNC = new Date('2026-09-05T12:00:00.000Z')
 
 function source(id: string, connectorType = 'google_drive', accessMode = 'admin') {
@@ -156,7 +157,7 @@ describe('organization Search source summaries', () => {
       seed([source('drive')])
       const result = await listSearchSources.execute({
         principal,
-        input: { organizationId: 'org-1' },
+        input: { organizationId: 'org-1', cursorRoute },
       })
       expect(result.sources[0]).toMatchObject({
         connectorId: 'drive',
@@ -174,7 +175,7 @@ describe('organization Search source summaries', () => {
     })
     queueTableRows(member, [])
     await expect(
-      listSearchSources.execute({ principal, input: { organizationId: 'org-1' } })
+      listSearchSources.execute({ principal, input: { organizationId: 'org-1', cursorRoute } })
     ).rejects.toThrow('Organization not found')
   })
 })

apps/sim/lib/knowledge/application/search-sources.ts

@@ -3,11 +3,8 @@ import { db } from '@sim/db'
 import { knowledgeBase, knowledgeConnector } from '@sim/db/schema'
 import { toRecord } from '@sim/utils/object'
 import { and, desc, eq, inArray, isNull, lt, ne, or, sql } from 'drizzle-orm'
-import {
-  listSearchSourcesContract,
-  searchSourceCursorSchema,
-} from '@/lib/api/contracts/knowledge/connectors'
-import { cursorRoute, cursorScopeKey } from '@/lib/api/cursor-binding'
+import { searchSourceCursorSchema } from '@/lib/api/contracts/knowledge/connectors'
+import { type CursorScopeRoute, cursorScopeKey } from '@/lib/api/cursor-binding'
 import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { type ResourceOwner, resourceScopeFromOwner } from '@/lib/core/resource-scope'
 import { resourceScopeCondition } from '@/lib/core/resource-scope.server'
@@ -24,6 +21,8 @@ import { describeSearchSource } from '@/lib/sim-search/source-identity'
 import { getConnectorMeta } from '@/connectors/registry'
 
 export interface ListSearchSourcesInput extends ResourceOwner {
+  /** The list endpoint the adapter's cursors belong to; binds every cursor to it. */
+  cursorRoute: CursorScopeRoute
   cursor?: string
   connectorId?: string
   connectorType?: string
@@ -41,7 +40,7 @@ export const listSearchSources = defineAuthorizedKnowledgeUseCase({
     const search = input.search?.trim().toLowerCase() ?? ''
     const connectorType = input.connectorType?.trim()
     const excludeConnectorType = input.excludeConnectorType?.trim()
-    const cursorScope = cursorScopeKey(cursorRoute(listSearchSourcesContract), {
+    const cursorScope = cursorScopeKey(input.cursorRoute, {
       workspaceId: context.workspaceId,
       organizationId: context.organizationId,
       userId: userId,

apps/sim/lib/mothership/tools/server/search-sources.test.ts

@@ -68,7 +68,15 @@ describe('Search source direct tool', () => {
         audience: 'sim:knowledge',
         resourceScope: { chatId: 'actual-chat' },
       }),
-      input: { organizationId: 'actual-org', cursor: 'previous' },
+      input: {
+        organizationId: 'actual-org',
+        cursor: 'previous',
+        cursorRoute: {
+          method: 'GET',
+          path: '/api/knowledge/sim-search/sources',
+          params: undefined,
+        },
+      },
     })
     expect(mocks.chat).toHaveBeenCalledBefore(mocks.list)
   })
@@ -77,7 +85,17 @@ describe('Search source direct tool', () => {
       tool.execute({ action: 'get', connectorId: 'foreign' }, context)
     ).rejects.toMatchObject({ code: 'not_found' })
     expect(mocks.list).toHaveBeenCalledWith(
-      expect.objectContaining({ input: { organizationId: 'actual-org', connectorId: 'foreign' } })
+      expect.objectContaining({
+        input: {
+          organizationId: 'actual-org',
+          connectorId: 'foreign',
+          cursorRoute: {
+            method: 'GET',
+            path: '/api/knowledge/sim-search/sources',
+            params: undefined,
+          },
+        },
+      })
     )
   })
   it('returns existing setup UI without creating an index, connecting or changing approval', async () => {

apps/sim/lib/mothership/tools/server/search-sources.ts

@@ -1,9 +1,11 @@
+import { listSearchSourcesContract } from '@/lib/api/contracts/knowledge/connectors'
 import {
   type OrganizationSearchSourcesInput,
   type OrganizationSearchSourcesOutput,
   organizationSearchSourcesInputSchema,
   organizationSearchSourcesOutputSchema,
 } from '@/lib/api/contracts/mothership-search-sources'
+import { cursorRoute } from '@/lib/api/cursor-binding'
 import { OrchestrationError } from '@/lib/core/orchestration/types'
 import { knowledgeDelegationPolicy } from '@/lib/knowledge/application/authorization'
 import {
@@ -47,18 +49,23 @@ export const organizationSearchSourcesServerTool: BaseServerTool<
     context?.userStopSignal?.throwIfAborted()
     const input = organizationSearchSourcesInputSchema.parse(args)
     const owner = { organizationId: trusted.organizationId }
+    // Shares the Search page's cursor namespace, so a page cursor stays valid on either surface.
+    const sourcesCursorRoute = cursorRoute(listSearchSourcesContract)
     switch (input.action) {
       case 'list': {
         const { action, ...filters } = input
         return {
           action,
-          ...(await listSearchSources.execute({ principal, input: { ...owner, ...filters } })),
+          ...(await listSearchSources.execute({
+            principal,
+            input: { ...owner, ...filters, cursorRoute: sourcesCursorRoute },
+          })),
         }
       }
       case 'get': {
         const page = await listSearchSources.execute({
           principal,
-          input: { ...owner, connectorId: input.connectorId },
+          input: { ...owner, connectorId: input.connectorId, cursorRoute: sourcesCursorRoute },
         })
         const source = page.sources[0]
         if (!source) throw new OrchestrationError('not_found', 'Search source not found')

scripts/check-monorepo-boundaries.test.ts

@@ -66,4 +66,68 @@ describe('package boundary command', () => {
       rmSync(fixture, { recursive: true, force: true })
     }
   }, 30_000)
+
+  it('keeps application code surface-neutral while allowing shared contract vocabulary', () => {
+    const fixture = mkdtempSync(path.join(ROOT, 'node_modules/.boundary-audit-'))
+    try {
+      mkdirSync(path.join(fixture, 'scripts'))
+      mkdirSync(path.join(fixture, 'packages'))
+      mkdirSync(path.join(fixture, 'apps/sim/lib/widgets/application'), { recursive: true })
+      copyFileSync(
+        path.join(ROOT, 'scripts/check-monorepo-boundaries.ts'),
+        path.join(fixture, 'scripts/check-monorepo-boundaries.ts')
+      )
+      const useCase = 'apps/sim/lib/widgets/application/use-case.ts'
+      const cases = [
+        ["import { NextResponse } from 'next/server'", useCase, false],
+        ["import type { NextRequest } from 'next/server'", useCase, false],
+        ["import { GET } from '@/app/api/widgets/route'", useCase, false],
+        ["import { listWidgetsContract } from '@/lib/api/contracts/widgets'", useCase, false],
+        ["export { listWidgetsContract } from '@/lib/api/contracts/widgets'", useCase, false],
+        ["import * as contracts from '@/lib/api/contracts/widgets'", useCase, false],
+        ["import { presentWidget } from '@/lib/api/server/widget-presenters'", useCase, false],
+        ["import { presentWidget } from '@/lib/api/server/widget-presenters.ts'", useCase, false],
+        ["import { run } from '@/lib/mothership/tools/handlers/run-code'", useCase, false],
+        ["import {} from '@/lib/mothership/tools/handlers/run-code'", useCase, false],
+        ["export {} from '@/lib/api/server/widget-presenters'", useCase, false],
+        ["const tool = import('@/lib/mothership/tools/server/widgets')", useCase, false],
+        ["import { listWidgetsContract } from '../../api/contracts/widgets'", useCase, false],
+        ["import { GET } from '../../../app/api/widgets/route'", useCase, false],
+        ["import type { ListWidgetsContract } from '../../api/contracts/widgets'", useCase, true],
+        ["import type { ListWidgetsContract } from '@/lib/api/contracts/widgets'", useCase, true],
+        ["import { type listWidgetsContract } from '@/lib/api/contracts/widgets'", useCase, true],
+        [
+          "import { widgetBodySchema, MAX_WIDGETS } from '@/lib/api/contracts/widgets'",
+          useCase,
+          true,
+        ],
+        [
+          "import type { ServerToolContext } from '@/lib/mothership/tools/server/base-tool'",
+          useCase,
+          true,
+        ],
+        [
+          "import { NextResponse } from 'next/server'",
+          'apps/sim/lib/widgets/application/use-case.test.ts',
+          true,
+        ],
+        ["import { NextResponse } from 'next/server'", 'apps/sim/lib/widgets/routes.ts', true],
+      ] as const
+
+      for (const [source, file, allowed] of cases) {
+        rmSync(path.join(fixture, 'apps/sim/lib/widgets'), { recursive: true, force: true })
+        mkdirSync(path.join(fixture, 'apps/sim/lib/widgets/application'), { recursive: true })
+        writeFileSync(path.join(fixture, file), `${source}\n`)
+        const result = spawnSync(
+          'bun',
+          [path.join(fixture, 'scripts/check-monorepo-boundaries.ts')],
+          { cwd: fixture, encoding: 'utf8' }
+        )
+        expect.soft(result.status, `${file}: ${source}\n${result.stderr}`).toBe(allowed ? 0 : 1)
+        if (!allowed) expect.soft(result.stderr).toContain(`${file}:1`)
+      }
+    } finally {
+      rmSync(fixture, { recursive: true, force: true })
+    }
+  }, 30_000)
 })