feat(appkit): execution identity and resource provisioning base

docs/docs/plugins/analytics.md

@@ -36,6 +36,22 @@ await createApp({
 
 The execution context is determined by the SQL file name, not by the hook call.
 
+### Warehouse binding
+
+The warehouse is an app resource, not part of the caller's identity. After
+`createApp()` initializes Analytics, custom plugins can read the binding with
+`getWarehouseId` from `@databricks/appkit`. It returns a `Promise<string>` and
+uses the same app warehouse for service-principal and caller executions.
+Credentials still come from the current execution context.
+
+`ServiceContextState.warehouseId` and the old context-module `getWarehouseId`
+helper are deprecated compatibility accessors. Use the package-root helper for
+new code. Warehouse environment lookup and development discovery are unchanged.
+
+The service-context property is retained for one release with a one-time
+deprecation warning, then scheduled for removal. Internal callers use the
+resource accessor already.
+
 ## SQL parameters
 
 Use `:paramName` placeholders and optionally annotate parameter types using SQL comments:

packages/appkit/src/connectors/lakebase/routing-pool.ts

@@ -1,7 +1,7 @@
 import type { Pool, PoolClient, QueryResult, QueryResultRow } from "pg";
 
-import { getUserContext } from "../../context/execution-context";
-import type { UserContext } from "../../context/user-context";
+import type { CallerContext } from "../../context/caller-context";
+import { getCallerContext } from "../../context/execution-context";
 
 /**
  * Subset of `pg.Pool` exposed by the Lakebase plugin.
@@ -26,7 +26,7 @@ export interface LakebasePool {
  * A `pg.Pool`-like wrapper that routes queries to the appropriate pool
  * based on the current execution context.
  *
- * When called inside `runInUserContext()` (set up by `Plugin.asUser(req)`),
+ * When called inside `runInCallerContext()` (set up by `Plugin.asUser(req)`),
  * queries route to the per-user pool returned by `resolveUserPool`.
  * Otherwise, queries route to the service-principal pool.
  *
@@ -37,11 +37,11 @@ export interface LakebasePool {
 export class RoutingPool implements LakebasePool {
   constructor(
     private spPool: Pool,
-    private resolveUserPool: (ctx: UserContext) => Pool,
+    private resolveUserPool: (ctx: CallerContext) => Pool,
   ) {}
 
   private activePool(): Pool {
-    const userCtx = getUserContext();
+    const userCtx = getCallerContext();
     return userCtx ? this.resolveUserPool(userCtx) : this.spPool;
   }
 

packages/appkit/src/connectors/lakebase/tests/routing-pool.test.ts

@@ -52,7 +52,13 @@ describe("RoutingPool", () => {
     expect(result.rows).toEqual([{ source: "user" }]);
     expect(userPool.query).toHaveBeenCalledWith("SELECT 1", undefined);
     expect(spPool.query).not.toHaveBeenCalled();
-    expect(resolveUserPool).toHaveBeenCalledWith(userCtx);
+    expect(resolveUserPool).toHaveBeenCalledWith(
+      expect.objectContaining({
+        client: userCtx.client,
+        workspaceId: userCtx.workspaceId,
+        principal: expect.objectContaining({ type: "user", userId: "user-1" }),
+      }),
+    );
   });
 
   test("connect() routes to user pool inside runInUserContext", async () => {