feat(appkit): distinguish bootstrap vs drift in blocking-mode typegen fatal

When blocking-mode typegen fails fatally (a cache MISS with no reachable/
authorized warehouse), branch the fatal remedy on whether the committed
.appkit/ cache file exists: bootstrap (never initialized → run
`generate-types --wait` against a warehouse and commit .appkit/) vs drift
(cache present but stale/missing the failing key → regenerate it). Same
crash, clearer next step. queryCacheFileExists() is called only on the fatal
path, so a warm all-hit run does no extra work. The write-then-throw contract
(always emit the .d.ts, then throw to fail the build) is unchanged.

Tests: all-hit blocking run makes ZERO warehouse round-trips (getWarehouse
never probed); both fatal message branches asserted.

Verify-at-implementation findings (no fix needed): (A) new WorkspaceClient({})
in query-registry constructs unconditionally but is lazy (no eager
auth/network) — all-hit runs make zero calls, confirmed by test; (B) SDK auth
errors (401/403) classify as fatal (not connectivity) via isConnectivityError,
so the authz cutover crashes the build loud as intended.

xavier loop: iteration 4 -- Phase 2 Wave 2 (2E)

Co-authored-by: Isaac
Signed-off-by: Atila Fassina <atila@fassina.eu>

Author: atilafassina

packages/appkit/src/type-generator/index.ts

@@ -9,6 +9,7 @@ import {
   loadCache,
   type MetricCacheEntry,
   metricCacheHash,
+  queryCacheFileExists,
   saveCache,
 } from "./cache";
 import { getErrorDiagnostic, isConnectivityError } from "./errors";
@@ -174,7 +175,21 @@ export class TypegenSyntaxError extends Error {
 export class TypegenFatalError extends Error {
   readonly queries: QueryFatalError[];
 
-  constructor(queries: QueryFatalError[], warehouseId?: string) {
+  constructor(
+    queries: QueryFatalError[],
+    warehouseId?: string,
+    cacheInitialized: boolean = true,
+  ) {
+    // Distinguish bootstrap (no committed cache yet) from drift (cache exists but is stale/missing key).
+    // Bootstrap → operator needs to initialize; drift → operator needs to regenerate the affected key.
+    const nextStep = cacheInitialized
+      ? // Drift: cache file exists but is missing/stale for the failing query/metric.
+        warehouseId
+        ? `The committed ${pc.bold(".appkit/")} cache is missing or stale for the failed ${plural(queries.length, "query", "queries")}. Regenerate with ${pc.bold("generate-types --wait")} against warehouse ${pc.bold(warehouseId)} and commit ${pc.bold(".appkit/")}.`
+        : `The committed ${pc.bold(".appkit/")} cache is missing or stale for the failed ${plural(queries.length, "query", "queries")}. Regenerate with ${pc.bold("generate-types --wait")} against a warehouse and commit ${pc.bold(".appkit/")}.`
+      : // Bootstrap: no committed cache found; operator needs to initialize from scratch.
+        `No committed type cache found (${pc.bold(".appkit/")}). Run ${pc.bold("generate-types --wait")} against a warehouse and commit ${pc.bold(".appkit/")} before building without warehouse access.`;
+
     super(
       formatTypegenFailureMessage({
         syntaxErrors: [],
@@ -187,9 +202,7 @@ export class TypegenFatalError extends Error {
           "authentication failure",
           "SDK configuration errors",
         ],
-        nextStep: warehouseId
-          ? `Verify access to warehouse ${pc.bold(warehouseId)} and rerun type generation.`
-          : "Verify warehouse access and rerun type generation.",
+        nextStep,
       }),
     );
     this.name = "TypegenFatalError";
@@ -391,7 +404,8 @@ export async function generateFromEntryPoint(options: {
     throw new TypegenSyntaxError(syntaxErrors, warehouseId, fatalErrors);
   }
   if (fatalErrors.length > 0) {
-    throw new TypegenFatalError(fatalErrors, warehouseId);
+    const cacheExists = await queryCacheFileExists();
+    throw new TypegenFatalError(fatalErrors, warehouseId, cacheExists);
   }
 
   logger.debug("Type generation complete!");

packages/appkit/src/type-generator/tests/generate-queries.test.ts

@@ -712,6 +712,37 @@ describe("generateQueriesFromDescribe", () => {
     expect(syntaxErrors).toEqual([]);
   });
 
+  test("blocking mode all-hit: makes ZERO warehouse round-trips on cache HIT", async () => {
+    const sql1 = "SELECT id FROM t1";
+    const sql2 = "SELECT name FROM t2";
+    mocks.readdir.mockResolvedValue(["t1.sql", "t2.sql"]);
+    mocks.readFile.mockResolvedValueOnce(sql1).mockResolvedValueOnce(sql2);
+    // All queries hit the cache with matching hashes.
+    mocks.loadCache.mockReturnValueOnce({
+      version: CACHE_VERSION,
+      queries: {
+        t1: { hash: hashSQL(sql1), type: CACHED_GOOD_TYPE, retry: false },
+        t2: { hash: hashSQL(sql2), type: CACHED_GOOD_TYPE, retry: false },
+      },
+    });
+
+    const { schemas, syntaxErrors, fatalErrors } = await describeQueries(
+      "/queries",
+      "wh-123",
+    );
+
+    // ZERO warehouse round-trips: no preflight probe (getWarehouse never called),
+    // no warehouse start, no DESCRIBE executions. All queries served from cache.
+    expect(mocks.getWarehouse).not.toHaveBeenCalled();
+    expect(mocks.startWarehouse).not.toHaveBeenCalled();
+    expect(mocks.executeStatement).not.toHaveBeenCalled();
+    expect(schemas).toHaveLength(2);
+    expect(schemas[0].type).toBe(CACHED_GOOD_TYPE);
+    expect(schemas[1].type).toBe(CACHED_GOOD_TYPE);
+    expect(syntaxErrors).toEqual([]);
+    expect(fatalErrors).toEqual([]);
+  });
+
   test("stale retry-flagged cache entry is re-described, not reused", async () => {
     const sql = "SELECT id FROM t";
     mocks.readdir.mockResolvedValue(["t.sql"]);

packages/appkit/src/type-generator/tests/index.test.ts

@@ -17,6 +17,7 @@ const mocks = vi.hoisted(() => ({
   startWarehouse: vi.fn(),
   waitUntilRunning: vi.fn(),
   executeStatement: vi.fn(),
+  queryCacheFileExists: vi.fn(),
   // In-memory stand-in for the on-disk typegen cache file. `undefined` means
   // "no file yet"; otherwise it holds the serialized JSON exactly as
   // saveCache would have written it, so load/save round-trips behave like
@@ -64,6 +65,7 @@ vi.mock("../cache", async (importOriginal) => {
     saveCache: vi.fn(async (cache: unknown) => {
       mocks.cacheFile.contents = JSON.stringify(cache, null, 2);
     }),
+    queryCacheFileExists: mocks.queryCacheFileExists,
   };
 });
 
@@ -270,6 +272,57 @@ describe("generateFromEntryPoint — query failure handling", () => {
     expect(fs.existsSync(outFile)).toBe(true);
     expect(fs.readFileSync(outFile, "utf-8")).toContain("bad_auth");
   });
+
+  test("bootstrap case: distinguishes missing cache from drift in fatal message", async () => {
+    mocks.generateQueriesFromDescribe.mockResolvedValue({
+      schemas: [unknownSchema("query1")],
+      syntaxErrors: [],
+      fatalErrors: [{ name: "query1", message: "PERMISSION_DENIED" }],
+    });
+    // Simulate first checkout: no committed cache file yet.
+    mocks.queryCacheFileExists.mockResolvedValue(false);
+
+    try {
+      await generateFromEntryPoint({
+        outFile,
+        queryFolder: "/queries",
+        warehouseId: "wh-1",
+      });
+      expect.fail("should have thrown TypegenFatalError");
+    } catch (err) {
+      expect(err).toBeInstanceOf(TypegenFatalError);
+      expect((err as Error).message).toMatch(/No committed type cache found/i);
+      expect((err as Error).message).toMatch(/generate-types --wait/i);
+      expect((err as Error).message).toMatch(/commit \.appkit\//i);
+    }
+  });
+
+  test("drift case: cache exists but is stale/missing for failing query", async () => {
+    mocks.generateQueriesFromDescribe.mockResolvedValue({
+      schemas: [unknownSchema("query1")],
+      syntaxErrors: [],
+      fatalErrors: [{ name: "query1", message: "PERMISSION_DENIED" }],
+    });
+    // Cache file exists but is out of date (the query's key is missing or stale).
+    mocks.queryCacheFileExists.mockResolvedValue(true);
+
+    try {
+      await generateFromEntryPoint({
+        outFile,
+        queryFolder: "/queries",
+        warehouseId: "wh-1",
+      });
+      expect.fail("should have thrown TypegenFatalError");
+    } catch (err) {
+      expect(err).toBeInstanceOf(TypegenFatalError);
+      expect((err as Error).message).toMatch(/missing or stale/i);
+      expect((err as Error).message).toMatch(/Regenerate with/i);
+      expect((err as Error).message).toMatch(/generate-types --wait/i);
+      expect((err as Error).message).not.toMatch(
+        /No committed type cache found/i,
+      );
+    }
+  });
 });
 
 describe("generateFromEntryPoint — metric-view emission", () => {