fix(v2-api): standardization (#6542)

* fix(v2-api): stop leaking resolved secrets in logs and serving doc source

Two regressions shipped with the v2 API (#5273) where v2 diverged from the
v1 path it replaced, plus the hardening that fell out of auditing them.

**v2 logs bypassed secret redaction.** `getPublicLog` and `listPublicLogs`
called raw `materializeExecutionData`, while every other reader — v1 list and
detail, CSV export, `fetch-log-detail`, both data-drain sources — calls
`materializeExecutionDataForDisplay`, which applies the resolved-secret
provenance projection. Both v2 routes then serialize `traceSpans` and
`finalOutput` straight onto the wire, so unredacted secrets could reach the
public API. Swapped to the display projection and threaded the principal's
subject user into the read context.

**v2 file download served generation source.** `GET /api/v2/files/{fileId}`
streamed `file.key` raw. AI-generated docs store their generation source as
the primary file, so a raw download yields source text under a `.pdf` name —
a file the recipient cannot open. Generated docs now resolve to their compiled
artifact; ordinary uploads still stream and are never materialized, gated on
the recorded generation-source type rather than the extension. The resolve is
capped at MAX_RENDERED_DOCUMENT_BYTES, and a still-compiling artifact returns
a retryable 409 rather than a 500.

Also in this change:

- Reconcile the two v2 verbs that used PUT for PATCH semantics:
  `PUT /v2/knowledge/{id}` and `PUT /v2/tables/{tableId}/rows` are both
  all-optional partial updates. Breaking for API-key clients, but the surface
  is dark-launched behind the `v2-api` gate and no in-repo caller issues PUT.
- Close the OpenAPI coverage blind spot that hid two routes: contract
  discovery was a non-recursive read of the flat `contracts/v2/` directory,
  so a contract in a subdirectory — or beside its non-v2 siblings, which is
  where the uploads contracts live — escaped the gate. The sweep is now
  recursive over the whole contracts tree, and the two upload data-plane
  routes are named in an explicit allowlist with reasons and staleness guards.
- Extract `needsRenderedArtifact` so the "recorded type is authoritative,
  extension is fallback" rule has one home instead of being duplicated.
- Extract `DocCompileUserError` into a leaf module so recognizing it no longer
  drags `app/api/**` and `next/server` into application modules.
- Correct the stale pagination docstring in `contracts/v2/shared.ts` and pin
  the paged/full-set split in a test so it cannot drift again.

* fix(v2-api): absolute imports for the extracted doc-compile error

Review follow-up.

- Use the `@/lib/...` alias for `doc-compile-error` in the three modules that
  imported it relatively. The repo requires absolute imports, and having all
  four consumers share one specifier also removes any chance of two module
  instances resolving apart and breaking `instanceof`.
- Memoize the v2 list-pagination sweep. It re-imported the whole contracts
  tree once per test and timed out against the default 10s limit under load;
  it now sweeps once and declares an explicit timeout. Its failure message
  also still pointed at an enumeration in `v2/shared.ts` that this branch
  replaced with a pointer to the test itself.

* fix(v2-api): correct three inaccurate claims found in verification

None of these change behavior; each is a comment or test-config assertion that
was not true as written.

- The artifact resolver's TSDoc implied the byte cap prevents an oversized
  artifact being materialized. It does not: the artifact-store fetch is not
  streaming-bounded, so the bytes are resident before the ceiling rejects
  them. Say what it actually guarantees.
- `v2/shared.ts` pointed at per-contract documentation for the two lists that
  still filter in memory. Neither contract documents it, so name the two lists
  and what they do inline instead of pointing at a page that does not exist.
- The knowledge update contract said "every field of the body is optional";
  `workspaceId` is required. Narrow the claim to mutable fields.
- Scope the pagination sweep's extended timeout to the one test that pays for
  it, so a genuine hang in the other two surfaces in 10s rather than 60s.

Author: waleedlatif1

apps/docs/openapi-v2-files-audit.json

@@ -566,7 +566,7 @@
       "get": {
         "operationId": "downloadFile",
         "summary": "Download File",
-        "description": "Download the current file bytes from a workspace.",
+        "description": "Download the current file bytes from a workspace. A generated document is served as its compiled artifact, so it returns `409` while that artifact is still compiling and `413` if it renders past the size ceiling.",
         "tags": ["Files"],
         "parameters": [
           {
@@ -638,6 +638,12 @@
           "404": {
             "$ref": "#/components/responses/NotFound"
           },
+          "409": {
+            "$ref": "#/components/responses/Conflict"
+          },
+          "413": {
+            "$ref": "#/components/responses/PayloadTooLarge"
+          },
           "429": {
             "$ref": "#/components/responses/RateLimited"
           },

apps/docs/openapi-v2-knowledge.json

@@ -273,7 +273,7 @@
           }
         }
       },
-      "put": {
+      "patch": {
         "operationId": "updateKnowledgeBase",
         "summary": "Update Knowledge Base",
         "description": "Update a knowledge base name, description, chunking configuration, or folder placement.",

apps/docs/openapi-v2-tables.json

@@ -864,7 +864,7 @@
           }
         }
       },
-      "put": {
+      "patch": {
         "operationId": "updateTableRows",
         "summary": "Update Rows by Filter",
         "description": "Apply the same partial data patch to every row matching a non-empty predicate.",

apps/sim/app/api/files/serve/[...path]/route.ts

@@ -4,10 +4,8 @@ import type { NextRequest } from 'next/server'
 import { NextResponse } from 'next/server'
 import { fileServeParamsSchema, fileServeQuerySchema } from '@/lib/api/contracts/storage-transfer'
 import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
-import {
-  DocCompileUserError,
-  resolveServableDocBytes,
-} from '@/lib/copilot/tools/server/files/doc-compile'
+import { resolveServableDocBytes } from '@/lib/copilot/tools/server/files/doc-compile'
+import { DocCompileUserError } from '@/lib/copilot/tools/server/files/doc-compile-error'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { CopilotFiles, isUsingCloudStorage } from '@/lib/uploads'
 import type { StorageContext } from '@/lib/uploads/config'

apps/sim/app/api/v1/files/[fileId]/route.test.ts

@@ -37,7 +37,7 @@ vi.mock('@sim/audit', () => ({
 }))
 vi.mock('@/lib/posthog/server', () => ({ captureServerEvent: vi.fn() }))
 
-import { DocCompileUserError } from '@/lib/copilot/tools/server/files/doc-compile'
+import { DocCompileUserError } from '@/lib/copilot/tools/server/files/doc-compile-error'
 import { GET } from '@/app/api/v1/files/[fileId]/route'
 
 const WORKSPACE_ID = 'ws-1'

apps/sim/app/api/v1/files/[fileId]/route.ts

@@ -10,7 +10,7 @@ import {
   fetchServableWorkspaceFileBuffer,
   getWorkspaceFile,
 } from '@/lib/uploads/contexts/workspace'
-import { docNotReadyMessage, isDocNotReadyError } from '@/lib/uploads/utils/servable-file-response'
+import { docNotReadyMessage, isDocNotReadyError } from '@/lib/uploads/utils/doc-not-ready'
 import { performDeleteWorkspaceFileItems } from '@/lib/workspace-files/orchestration'
 import {
   checkRateLimit,

apps/sim/app/api/v2/files/[fileId]/route.test.ts

@@ -111,6 +111,8 @@ describe('v2 single-file routes', () => {
     mocks.download.mockResolvedValue({
       file: fileRecord(),
       stream: new Blob(['id,name\n']).stream(),
+      contentType: 'text/csv',
+      contentLength: 'id,name\n'.length,
     })
     mocks.rename.mockResolvedValue({ file: fileRecord({ name: 'renamed.csv' }) })
     mocks.deleteFile.mockResolvedValue({

apps/sim/app/api/v2/files/[fileId]/route.ts

@@ -25,6 +25,8 @@ export const revalidate = 0
  * The response carries no JSON envelope, so rate-limit state is surfaced via
  * `X-RateLimit-*` headers. Errors still render the canonical v2 JSON error body.
  * Lookups are workspace-scoped (IDOR-safe): a file in another workspace 404s.
+ *
+ * A generated doc whose artifact is still compiling renders `CONFLICT`; retry.
  */
 export const GET = defineV2BinaryRoute({
   contract: v2DownloadFileContract,
@@ -37,11 +39,11 @@ export const GET = defineV2BinaryRoute({
     assertedWorkspaceId: query.workspaceId,
   }),
   useCase: downloadWorkspaceFileStream,
-  present: ({ file, stream }) => ({
+  present: ({ file, stream, contentType, contentLength }) => ({
     body: stream,
-    contentType: file.type || 'application/octet-stream',
+    contentType,
     contentDisposition: `attachment; filename="${file.name.replace(/[^\w.-]/g, '_')}"; filename*=UTF-8''${encodeURIComponent(file.name)}`,
-    contentLength: file.size,
+    contentLength,
   }),
 })
 

apps/sim/app/api/v2/knowledge/[id]/route.ts

@@ -35,8 +35,8 @@ export const GET = defineV2JsonRoute({
   }),
 })
 
-/** PUT /api/v2/knowledge/[id] — Update a knowledge base. */
-export const PUT = defineV2JsonRoute({
+/** PATCH /api/v2/knowledge/[id] — Partially update a knowledge base. */
+export const PATCH = defineV2JsonRoute({
   contract: v2UpdateKnowledgeBaseContract,
   auth: v2ApiKeyAuth,
   operation: knowledgeOperations.update,

apps/sim/app/api/v2/tables/[tableId]/rows/route.test.ts

@@ -42,7 +42,7 @@ vi.mock('@/lib/table/application/rows', () => ({
   deleteTableRows: { operation: { id: 'tables.rows.delete_many' }, execute: mocks.deleteRows },
 }))
 
-import { DELETE, GET, POST, PUT } from '@/app/api/v2/tables/[tableId]/rows/route'
+import { DELETE, GET, PATCH, POST } from '@/app/api/v2/tables/[tableId]/rows/route'
 
 const WORKSPACE_ID = 'workspace-1'
 const PRINCIPAL = {
@@ -76,7 +76,7 @@ const ROW = {
 }
 const CONTEXT = { params: Promise.resolve({ tableId: 'table-1' }) }
 
-function request(method: 'GET' | 'POST' | 'PUT' | 'DELETE', body?: unknown, query = '') {
+function request(method: 'GET' | 'POST' | 'PATCH' | 'DELETE', body?: unknown, query = '') {
   return new NextRequest(`http://localhost/api/v2/tables/table-1/rows${query}`, {
     method,
     headers: {
@@ -159,12 +159,12 @@ describe('/api/v2/tables/[tableId]/rows', () => {
 
   it('preserves authoritative bulk update counts including a zero-match result', async () => {
     mocks.updateRows.mockResolvedValue({ table: TABLE, affectedCount: 0, affectedRowIds: [] })
-    const req = request('PUT', {
+    const req = request('PATCH', {
       workspaceId: WORKSPACE_ID,
       filter: { all: [{ field: 'name', op: 'eq', value: 'missing' }] },
       data: { name: 'Grace' },
     })
-    const response = await PUT(req, CONTEXT)
+    const response = await PATCH(req, CONTEXT)
 
     expect(response.status).toBe(200)
     expect(await response.json()).toEqual({ data: { updatedCount: 0, updatedRowIds: [] } })