@@ -18,7 +18,13 @@ Sim stores the token alongside your account host as one credential. Once it is a
 - A network policy covering the user, or an authentication policy that waives the requirement (see below).
 
 <Callout type="warn">
-By default Snowflake requires a **human** user to be subject to a **network policy** before a programmatic access token can be generated or used. If your account has no network policy, either create one (allowing Sim's egress) or set `NETWORK_POLICY_EVALUATION = ENFORCED_NOT_REQUIRED` on an authentication policy applied to the user. Without one of these, token generation fails and a generated token is rejected at run time. Service users (`TYPE = SERVICE`) are exempt from the requirement.
+Snowflake's **network policy** requirement varies by user type, and getting it wrong is the most common reason a token is rejected:
+
+- `TYPE = PERSON` — you can generate a token without a network policy, but the user **must** be covered by one to authenticate with it.
+- `TYPE = SERVICE` and `TYPE = LEGACY_SERVICE` — a network policy is required to generate **and** to use a token.
+- `TYPE = SERVICE_AGENT` — exempt; generate and use freely.
+
+If your account has no network policy, either create one (allowing Sim's egress) or set `NETWORK_POLICY_EVALUATION = ENFORCED_NOT_REQUIRED` on an authentication policy applied to the user.
 </Callout>
 
 ## Creating the Token
@@ -48,9 +54,9 @@ ALTER USER my_service_user ADD PROGRAMMATIC ACCESS TOKEN sim_workflows
   DAYS_TO_EXPIRY = 90;
 ```
 
-`DAYS_TO_EXPIRY` defaults to 15 days and cannot exceed 365. **A token can never be non-expiring**, and the value cannot be changed after creation — to extend it, generate a new token and swap the credential in Sim. Plan the rotation when you create it.
+`DAYS_TO_EXPIRY` defaults to 15 days and cannot exceed 365 — an authentication policy can lower that ceiling further via `PROGRAMMATIC_ACCESS_TOKEN_MAX_EXPIRY_IN_DAYS`. **A token can never be non-expiring**, and the value cannot be changed after creation — to extend it, generate a new token and swap the credential in Sim. Plan the rotation when you create it.
 
-Service users (`TYPE = SERVICE` or `SERVICE_AGENT`) **must** set `ROLE_RESTRICTION`. For person users it is optional but recommended: a restricted token can only ever act as that one role.
+Service users (`TYPE = SERVICE`, `LEGACY_SERVICE`, or `SERVICE_AGENT`) **must** set `ROLE_RESTRICTION`, unless an authentication policy exempts them. For person users it is optional but recommended: a restricted token can only ever act as that one role.
 
 <Callout type="info">
 If an authentication policy applies to the user, `'PROGRAMMATIC_ACCESS_TOKEN'` must appear in its `AUTHENTICATION_METHODS` list, otherwise the token is refused.
@@ -98,7 +104,7 @@ A token's expiry is fixed at creation. To rotate, generate a new token on the sa
   { question: "Why a programmatic access token instead of a password?", answer: "The token is scoped to one user, can be restricted to a single role, expires on a schedule you choose, and can be revoked on its own without changing anyone's password or breaking other integrations." },
   { question: "Does the token expire?", answer: "Yes. DAYS_TO_EXPIRY defaults to 15 days and can be set up to 365 at creation. It cannot be changed afterwards, so pick the value you want up front and plan a rotation." },
   { question: "I lost the token — can I see it again?", answer: "No. Snowflake shows the secret only at creation. Generate a new token and update the credential in Sim." },
-  { question: "Why does adding the credential fail with an authentication error?", answer: "The three common causes are a token that has expired or been revoked, a human user with no network policy (Snowflake requires one for token use unless an authentication policy waives it), and an authentication policy that omits PROGRAMMATIC_ACCESS_TOKEN from its AUTHENTICATION_METHODS. A wrong account host is reported separately — Snowflake resolves any *.snowflakecomputing.com name, so Sim identifies a mistyped host by the 404 it answers with." },
+  { question: "Why does adding the credential fail with an authentication error?", answer: "The three common causes are a token that has expired or been revoked, a user with no network policy (required to authenticate for every type except SERVICE_AGENT, unless an authentication policy waives it), and an authentication policy that omits PROGRAMMATIC_ACCESS_TOKEN from its AUTHENTICATION_METHODS. A wrong account host is reported separately — Snowflake resolves any *.snowflakecomputing.com name, so Sim identifies a mistyped host by the 404 it answers with." },
   { question: "Why is a picker empty?", answer: "The pickers run SHOW statements as the token's user under its default role — the block's execution role is not applied to them. If the objects you expect are visible only to another role, grant the default role usage on them, restrict the token to the role that has access, or type the name in advanced mode." },
   { question: "Does listing objects cost credits?", answer: "No. Every picker and the credential check run metadata-only statements, which Snowflake serves without a running warehouse." },
   { question: "Can one credential reach two Snowflake accounts?", answer: "No. A token is bound to the user in one account, and the credential stores that account's host. Add one credential per account." },
 
@@ -389,10 +389,10 @@ Export a table or query result to files in a Snowflake stage with COPY INTO.
 | `table` | string | No | Source table to unload; provide either this or a statement, not both |
 | `statement` | string | No | Source SELECT statement to unload; provide either this or a table, not both |
 | `fileFormat` | string | No | Named file format applied to the unloaded files |
-| `header` | boolean | No | Whether to write column headings into the unloaded files |
+| `header` | boolean | No | Whether to write column headings into the unloaded files; supported for CSV and Parquet only |
 | `overwrite` | boolean | No | Whether to replace existing files with matching names in the stage |
 | `singleFile` | boolean | No | Whether to write one file instead of splitting the output across files |
-| `maxFileSizeBytes` | number | No | Upper size limit per unloaded file in bytes; Snowflake defaults to 16000000 and allows up to 5000000000 |
+| `maxFileSizeBytes` | number | No | Upper size limit per unloaded file in bytes; Snowflake defaults to 16777216 \(16 MB\) and allows up to 5368709120 \(5 GB\) |
 
 #### Output
 
@@ -721,7 +721,7 @@ Resize a Snowflake warehouse or change its auto-suspend and auto-resume settings
 | `statementTimeoutSeconds` | number | No | Statement timeout in seconds; 0 uses Snowflake maximum of 604800 seconds |
 | `warehouseName` | string | Yes | Warehouse name |
 | `warehouseSize` | string | No | New warehouse size, one of $\{SNOWFLAKE_WAREHOUSE_SIZES.join\(', '\)\} |
-| `autoSuspendSeconds` | number | No | Seconds of inactivity before the warehouse suspends; 0 disables automatic suspension |
+| `autoSuspendSeconds` | number | No | Seconds of inactivity before the warehouse suspends. Snowflake polls every 30 seconds, so values under 30 or not a multiple of 30 may not behave as expected. 0 means the warehouse never suspends and keeps consuming credits |
 | `autoResume` | boolean | No | Whether the warehouse resumes automatically when a statement is submitted |
 
 #### Output
@@ -1151,7 +1151,7 @@ List queries that completed in the last seven days, optionally filtered.
 | `warehouseName` | string | No | Only queries run on this warehouse; cannot be combined with userName |
 | `startTime` | string | No | ISO-8601 start of the query completion window, within the last seven days |
 | `endTime` | string | No | ISO-8601 end of the query completion window, within the last seven days |
-| `errorOnly` | boolean | No | Whether to return only queries whose execution status is FAIL |
+| `errorOnly` | boolean | No | Whether to return only queries that failed \(execution status FAILED_WITH_ERROR or FAILED_WITH_INCIDENT\). Snowflake applies the limit before this filter, so it selects the failures among the most recent queries rather than the most recent failures |
 | `limit` | number | No | Maximum query rows, from 1 to 10000 |
 
 #### Output
 
@@ -128,6 +128,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     return NextResponse.json({ error: getErrorMessage(error, 'Invalid request') }, { status: 400 })
   }
 
+  let upstreamStatus = 0
   try {
     const response = await fetch(`${baseUrl}/api/v2/statements`, {
       method: 'POST',
@@ -153,6 +154,9 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       )
     }
 
+    // A 4xx names something wrong with the request (missing object, privilege
+    // gap); only a 5xx or a malformed body is a gateway failure.
+    upstreamStatus = response.status
     const result = await readSnowflakeResult(response)
     // A metadata-only statement completes synchronously; a 202 means Snowflake
     // deferred it, and returning an empty list would read as "no objects".
@@ -179,7 +183,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
     logger.error('Failed to list Snowflake objects', { kind, error })
     return NextResponse.json(
       { error: getErrorMessage(error, 'Failed to list Snowflake objects') },
-      { status: 502 }
+      { status: upstreamStatus >= 400 && upstreamStatus < 500 ? 400 : 502 }
     )
   }
 })
@@ -12,11 +12,11 @@ import type { SnowflakeSelectorKind } from '@/tools/snowflake/selector-kinds'
 type SnowflakeSelectorKey = Extract<SelectorKey, `snowflake.${string}`>
 
 /** What each picker needs in scope before it can list anything. */
-type SnowflakeSelectorScope = 'account' | 'database' | 'schema'
+type SnowflakeSelectorScopeLevel = 'account' | 'database' | 'schema'
 
 interface SnowflakeSelectorSpec {
   kind: SnowflakeSelectorKind
-  scope: SnowflakeSelectorScope
+  scope: SnowflakeSelectorScopeLevel
 }
 
 const SNOWFLAKE_SELECTOR_SPECS: Record<SnowflakeSelectorKey, SnowflakeSelectorSpec> = {
 
@@ -413,9 +413,9 @@ export const TOKEN_SERVICE_ACCOUNT_DESCRIPTORS: Record<
     ],
     docsUrl: 'https://docs.sim.ai/integrations/snowflake-service-account',
     helpText:
-      'A programmatic access token acts as the Snowflake user that owns it, or as the single role it was restricted to. It always expires — 15 days by default, 365 at most — and human users must be covered by a network policy unless an authentication policy waives it.',
+      'A programmatic access token acts as the Snowflake user that owns it, or as the single role it was restricted to. It always expires — 15 days by default, 365 at most — and every user type except SERVICE_AGENT must be covered by a network policy to authenticate with it, unless an authentication policy waives that.',
     invalidCredentialsHelp:
-      'Snowflake rejected this token. Check that it belongs to a user on this exact account host, has not expired, and that a network policy allows Sim to reach the account.',
+      'Snowflake rejected this token. Check that it belongs to a user on this exact account host, that it has not expired or been revoked, that a network policy allows Sim to reach the account, and that the SQL API is enabled for the account.',
   },
 }
 
 
@@ -16,10 +16,11 @@ function jsonResponse(status: number, body: unknown): Response {
 
 const fields = { apiToken: 'pat-secret', domain: 'MyOrg-MyAccount.snowflakecomputing.com' }
 
-async function expectCode(promise: Promise<unknown>, code: string) {
+async function expectCode(promise: Promise<unknown>, code: string, status?: number) {
   await expect(promise).rejects.toBeInstanceOf(TokenServiceAccountValidationError)
   await promise.catch((error: TokenServiceAccountValidationError) => {
     expect(error.code).toBe(code)
+    if (status !== undefined) expect(error.status).toBe(status)
   })
 }
 
@@ -30,7 +31,9 @@ describe('validateSnowflakeServiceAccount', () => {
 
   afterEach(() => {
     vi.unstubAllGlobals()
-    vi.clearAllMocks()
+    // resetAllMocks, not clearAllMocks: the latter leaves queued
+    // mockResolvedValueOnce values behind to leak into the next test.
+    vi.resetAllMocks()
   })
 
   it('verifies through the SQL API with the PAT headers the tools use', async () => {
@@ -72,20 +75,30 @@ describe('validateSnowflakeServiceAccount', () => {
     await expectCode(validateSnowflakeServiceAccount(fields), 'site_not_found')
   })
 
-  it('maps 401 to a rejected token and 403 to the SQL API being disabled', async () => {
+  /**
+   * Snowflake answers 403 both for a disabled SQL API and for a network-policy
+   * rejection, so both must reach the provider's invalid-credentials help,
+   * which names every cause — not a "provider is down" message.
+   */
+  it('maps 401 and 403 to a rejected credential', async () => {
     mockFetch.mockResolvedValueOnce(jsonResponse(401, { message: 'invalid token' }))
-    await expectCode(validateSnowflakeServiceAccount(fields), 'invalid_credentials')
+    await expectCode(validateSnowflakeServiceAccount(fields), 'invalid_credentials', 401)
 
-    mockFetch.mockResolvedValueOnce(jsonResponse(403, { message: 'SQL API not enabled' }))
-    await expectCode(validateSnowflakeServiceAccount(fields), 'provider_unavailable')
+    mockFetch.mockResolvedValueOnce(
+      jsonResponse(403, { message: 'not allowed to access Snowflake' })
+    )
+    await expectCode(validateSnowflakeServiceAccount(fields), 'invalid_credentials', 403)
   })
 
-  it('treats a deferred statement and a metadata-less success as provider problems', async () => {
+  it('treats a deferred statement and a metadata-less success as distinct provider problems', async () => {
+    // The status is what separates these two: without the 202 branch the
+    // deferred response would fall through to the metadata-less path and throw
+    // 502, so asserting only the code cannot tell them apart.
     mockFetch.mockResolvedValueOnce(jsonResponse(202, { statementHandle: 'abc' }))
-    await expectCode(validateSnowflakeServiceAccount(fields), 'provider_unavailable')
+    await expectCode(validateSnowflakeServiceAccount(fields), 'provider_unavailable', 202)
 
     mockFetch.mockResolvedValueOnce(jsonResponse(200, { data: [] }))
-    await expectCode(validateSnowflakeServiceAccount(fields), 'provider_unavailable')
+    await expectCode(validateSnowflakeServiceAccount(fields), 'provider_unavailable', 502)
   })
 
   it('falls back to the account when the token reports no user', async () => {
 
@@ -90,16 +90,11 @@ export async function validateSnowflakeServiceAccount(
       body: await readProviderErrorSnippet(res),
     })
   }
-  // Snowflake documents 403 as "the SQL API is not enabled for this account",
-  // which the shared 401/403 branch would misreport as a rejected token.
-  if (res.status === 403) {
-    throw new TokenServiceAccountValidationError('provider_unavailable', 403, {
-      step: 'identity_statement',
-      domain,
-      reason: 'SQL API not enabled for this account',
-      body: await readProviderErrorSnippet(res),
-    })
-  }
+  // 403 is left to the shared 401/403 branch on purpose. Snowflake returns it
+  // both when the SQL API is disabled and when a network policy rejects the
+  // caller's IP, and the response wording for neither is documented — so rather
+  // than guess from the body, both surface the provider's `invalidCredentialsHelp`,
+  // which names every cause.
   await throwForProviderResponse(res, 'identity_statement', { domain })
 
   // 202 means the statement is still executing. A context-only SELECT that
 
@@ -61,6 +61,56 @@ describe('migrateSubblockIds', () => {
     expect(blocks.b1.subBlocks.metrics).toBeUndefined()
   })
 
+  describe('snowflake block', () => {
+    it('renames the object fields onto their pickers', () => {
+      const input: Record<string, BlockState> = {
+        b1: makeBlock({
+          type: 'snowflake',
+          subBlocks: {
+            operation: { id: 'operation', type: 'dropdown', value: 'insert_rows' },
+            database: { id: 'database', type: 'short-input', value: 'ANALYTICS' },
+            schema: { id: 'schema', type: 'short-input', value: 'PUBLIC' },
+            table: { id: 'table', type: 'short-input', value: 'EVENTS' },
+          },
+        }),
+      }
+
+      const { blocks, migrated } = migrateSubblockIds(input)
+
+      expect(migrated).toBe(true)
+      expect(blocks.b1.subBlocks.databaseSelector?.value).toBe('ANALYTICS')
+      expect(blocks.b1.subBlocks.schemaSelector?.value).toBe('PUBLIC')
+      expect(blocks.b1.subBlocks.tableSelector?.value).toBe('EVENTS')
+      expect(blocks.b1.subBlocks.database).toBeUndefined()
+    })
+
+    /**
+     * Secret scrubbing for exports walks the block config, so a value parked
+     * under a key the config no longer declares would never be cleared. A
+     * `_removed_` target must drop the value, not carry it forward.
+     */
+    it('discards the retired host and programmatic access token', () => {
+      const input: Record<string, BlockState> = {
+        b1: makeBlock({
+          type: 'snowflake',
+          subBlocks: {
+            host: { id: 'host', type: 'short-input', value: 'acme.snowflakecomputing.com' },
+            apiKey: { id: 'apiKey', type: 'short-input', value: 'super-secret-pat' },
+          },
+        }),
+      }
+
+      const { blocks, migrated } = migrateSubblockIds(input)
+
+      expect(migrated).toBe(true)
+      expect(blocks.b1.subBlocks.apiKey).toBeUndefined()
+      expect(blocks.b1.subBlocks.host).toBeUndefined()
+      expect(blocks.b1.subBlocks._removed_apiKey).toBeUndefined()
+      expect(blocks.b1.subBlocks._removed_host).toBeUndefined()
+      expect(JSON.stringify(blocks.b1)).not.toContain('super-secret-pat')
+    })
+  })
+
   describe('knowledge block', () => {
     it('should rename knowledgeBaseId to knowledgeBaseSelector', () => {
       const input: Record<string, BlockState> = {
 
@@ -13,6 +13,12 @@ import type { BlockState } from '@/stores/workflows/workflow/types'
 
 const logger = createLogger('SubblockMigrations')
 
+/**
+ * Marks a migration target as "this field is gone", rather than a rename. The
+ * old value is discarded instead of being carried into workflow state.
+ */
+const REMOVED_SUBBLOCK_ID_PREFIX = '_removed_'
+
 /**
  * Maps old subblock IDs to their current equivalents per block type.
  *
@@ -21,6 +27,10 @@ const logger = createLogger('SubblockMigrations')
  * serializer silently drops the value, breaking execution.
  *
  * Format: { blockType: { oldSubblockId: newSubblockId } }
+ *
+ * A target prefixed with `_removed_` means the field was deleted outright; the
+ * stored value is dropped. Use it for fields with no replacement — never map a
+ * secret onto a live subblock.
  */
 export const SUBBLOCK_ID_MIGRATIONS: Record<string, Record<string, string>> = {
   instagram: {
@@ -151,6 +161,16 @@ function migrateBlockSubblockIds(
   for (const [oldId, newId] of Object.entries(renames)) {
     if (!(oldId in result)) continue
 
+    // A `_removed_` target means the field no longer exists in the block. Drop
+    // the value rather than parking it under a dead key: nothing ever reads
+    // these keys, and secret scrubbing walks the block config, so a parked
+    // `password: true` value would never be cleared and would ride along in
+    // workflow exports and templates.
+    if (newId.startsWith(REMOVED_SUBBLOCK_ID_PREFIX)) {
+      delete result[oldId]
+      continue
+    }
+
     if (newId in result) {
       delete result[oldId]
       continue
Original file line number	Diff line number	Diff line change
`@@ -128,6 +128,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {`
`128`	`128`	`return NextResponse.json({ error: getErrorMessage(error, 'Invalid request') }, { status: 400 })`
`129`	`129`	`}`
`130`	`130`
	`131`	`+ let upstreamStatus = 0`
`131`	`132`	`try {`
`132`	`133`	const response = await fetch(`${baseUrl}/api/v2/statements`, {
`133`	`134`	`method: 'POST',`
`@@ -153,6 +154,9 @@ export const POST = withRouteHandler(async (request: NextRequest) => {`
`153`	`154`	`)`
`154`	`155`	`}`
`155`	`156`
	`157`	`+ // A 4xx names something wrong with the request (missing object, privilege`
	`158`	`+ // gap); only a 5xx or a malformed body is a gateway failure.`
	`159`	`+ upstreamStatus = response.status`
`156`	`160`	`const result = await readSnowflakeResult(response)`
`157`	`161`	`// A metadata-only statement completes synchronously; a 202 means Snowflake`
`158`	`162`	`// deferred it, and returning an empty list would read as "no objects".`
`@@ -179,7 +183,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {`
`179`	`183`	`logger.error('Failed to list Snowflake objects', { kind, error })`
`180`	`184`	`return NextResponse.json(`
`181`	`185`	`{ error: getErrorMessage(error, 'Failed to list Snowflake objects') },`
`182`		`- { status: 502 }`
	`186`	`+ { status: upstreamStatus >= 400 && upstreamStatus < 500 ? 400 : 502 }`
`183`	`187`	`)`
`184`	`188`	`}`
`185`	`189`	`})`