@dbx-tools/appkit 0.9.118 → 0.9.120

package/lib/src/tool-operations.js

@@ -0,0 +1,43 @@
+/** Zod-owned operation contracts converted into native AppKit agent tools. */
+import { defineTool } from "@databricks/appkit/beta";
+/** Preserve operation inference while declaring an exported operation map. */
+export function defineOperations(operations) {
+    return operations;
+}
+/** Convert exported Zod operation contracts into a native AppKit tool registry. */
+export function toolRegistryFromOperations(operations) {
+    return Object.fromEntries(Object.entries(operations).flatMap(([name, operation]) => {
+        const metadata = operation.schema.meta();
+        const tool = metadata?.appkitTool ?? {};
+        if (tool.agentTool !== true)
+            return [];
+        const effect = tool.effect ?? "write";
+        const approval = tool.approval === true || effect === "destructive";
+        const description = operation.schema.description?.trim();
+        if (!description) {
+            throw new TypeError(`AppKit operation ${name} requires a Zod schema description`);
+        }
+        return [
+            [
+                name,
+                defineTool({
+                    description,
+                    schema: operation.schema,
+                    annotations: {
+                        effect,
+                        ...(approval ? { destructive: true } : {}),
+                        ...(tool.requiresUserContext === undefined
+                            ? {}
+                            : { requiresUserContext: tool.requiresUserContext }),
+                        ...(tool.idempotent === undefined ? {} : { idempotent: tool.idempotent }),
+                    },
+                    ...(tool.autoInheritable === undefined
+                        ? {}
+                        : { autoInheritable: tool.autoInheritable }),
+                    execute: (input, signal) => operation.execute(operation.schema.parse(input), signal),
+                }),
+            ],
+        ];
+    }));
+}
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoidG9vbC1vcGVyYXRpb25zLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vLi4vc3JjL3Rvb2wtb3BlcmF0aW9ucy50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSw4RUFBOEU7QUFFOUUsT0FBTyxFQUFFLFVBQVUsRUFBcUIsTUFBTSx5QkFBeUIsQ0FBQztBQThCeEUsOEVBQThFO0FBQzlFLE1BQU0sVUFBVSxnQkFBZ0IsQ0FFOUIsVUFFRDtJQUNDLE9BQU8sVUFBVSxDQUFDO0FBQ3BCLENBQUM7QUFFRCxtRkFBbUY7QUFDbkYsTUFBTSxVQUFVLDBCQUEwQixDQUN4QyxVQUF5RTtJQUV6RSxPQUFPLE1BQU0sQ0FBQyxXQUFXLENBQ3ZCLE1BQU0sQ0FBQyxPQUFPLENBQUMsVUFBVSxDQUFDLENBQUMsT0FBTyxDQUFDLENBQUMsQ0FBQyxJQUFJLEVBQUUsU0FBUyxDQUFDLEVBQUUsRUFBRTtRQUN2RCxNQUFNLFFBQVEsR0FBRyxTQUFTLENBQUMsTUFBTSxDQUFDLElBQUksRUFBMkMsQ0FBQztRQUNsRixNQUFNLElBQUksR0FBRyxRQUFRLEVBQUUsVUFBVSxJQUFJLEVBQUUsQ0FBQztRQUN4QyxJQUFJLElBQUksQ0FBQyxTQUFTLEtBQUssSUFBSTtZQUFFLE9BQU8sRUFBRSxDQUFDO1FBQ3ZDLE1BQU0sTUFBTSxHQUFHLElBQUksQ0FBQyxNQUFNLElBQUksT0FBTyxDQUFDO1FBQ3RDLE1BQU0sUUFBUSxHQUFHLElBQUksQ0FBQyxRQUFRLEtBQUssSUFBSSxJQUFJLE1BQU0sS0FBSyxhQUFhLENBQUM7UUFDcEUsTUFBTSxXQUFXLEdBQUcsU0FBUyxDQUFDLE1BQU0sQ0FBQyxXQUFXLEVBQUUsSUFBSSxFQUFFLENBQUM7UUFDekQsSUFBSSxDQUFDLFdBQVcsRUFBRSxDQUFDO1lBQ2pCLE1BQU0sSUFBSSxTQUFTLENBQUMsb0JBQW9CLElBQUksb0NBQW9DLENBQUMsQ0FBQztRQUNwRixDQUFDO1FBQ0QsT0FBTztZQUNMO2dCQUNFLElBQUk7Z0JBQ0osVUFBVSxDQUFDO29CQUNULFdBQVc7b0JBQ1gsTUFBTSxFQUFFLFNBQVMsQ0FBQyxNQUFNO29CQUN4QixXQUFXLEVBQUU7d0JBQ1gsTUFBTTt3QkFDTixHQUFHLENBQUMsUUFBUSxDQUFDLENBQUMsQ0FBQyxFQUFFLFdBQVcsRUFBRSxJQUFJLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxDQUFDO3dCQUMxQyxHQUFHLENBQUMsSUFBSSxDQUFDLG1CQUFtQixLQUFLLFNBQVM7NEJBQ3hDLENBQUMsQ0FBQyxFQUFFOzRCQUNKLENBQUMsQ0FBQyxFQUFFLG1CQUFtQixFQUFFLElBQUksQ0FBQyxtQkFBbUIsRUFBRSxDQUFDO3dCQUN0RCxHQUFHLENBQUMsSUFBSSxDQUFDLFVBQVUsS0FBSyxTQUFTLENBQUMsQ0FBQyxDQUFDLEVBQUUsQ0FBQyxDQUFDLENBQUMsRUFBRSxVQUFVLEVBQUUsSUFBSSxDQUFDLFVBQVUsRUFBRSxDQUFDO3FCQUMxRTtvQkFDRCxHQUFHLENBQUMsSUFBSSxDQUFDLGVBQWUsS0FBSyxTQUFTO3dCQUNwQyxDQUFDLENBQUMsRUFBRTt3QkFDSixDQUFDLENBQUMsRUFBRSxlQUFlLEVBQUUsSUFBSSxDQUFDLGVBQWUsRUFBRSxDQUFDO29CQUM5QyxPQUFPLEVBQUUsQ0FBQyxLQUFLLEVBQUUsTUFBTSxFQUFFLEVBQUUsQ0FBQyxTQUFTLENBQUMsT0FBTyxDQUFDLFNBQVMsQ0FBQyxNQUFNLENBQUMsS0FBSyxDQUFDLEtBQUssQ0FBQyxFQUFFLE1BQU0sQ0FBQztpQkFDckYsQ0FBQzthQUNIO1NBQ0YsQ0FBQztJQUNKLENBQUMsQ0FBQyxDQUNILENBQUM7QUFDSixDQUFDIiwic291cmNlc0NvbnRlbnQiOlsiLyoqIFpvZC1vd25lZCBvcGVyYXRpb24gY29udHJhY3RzIGNvbnZlcnRlZCBpbnRvIG5hdGl2ZSBBcHBLaXQgYWdlbnQgdG9vbHMuICovXG5cbmltcG9ydCB7IGRlZmluZVRvb2wsIHR5cGUgVG9vbFJlZ2lzdHJ5IH0gZnJvbSBcIkBkYXRhYnJpY2tzL2FwcGtpdC9iZXRhXCI7XG5pbXBvcnQgeyB6IH0gZnJvbSBcInpvZFwiO1xuXG4vKiogTWV0YWRhdGEgc3RvcmVkIHVuZGVyIGBhcHBraXRUb29sYCBieSBhIFpvZCBzY2hlbWEncyBgLm1ldGEoKWAgdmFsdWUuICovXG5leHBvcnQgaW50ZXJmYWNlIEFwcEtpdFRvb2xNZXRhIHtcbiAgLyoqIE9wdCBpbiB0byBleHBvc2luZyB0aGlzIG9wZXJhdGlvbiBhcyBhbiBhZ2VudCB0b29sLiAqL1xuICByZWFkb25seSBhZ2VudFRvb2w/OiBib29sZWFuO1xuICAvKiogVG9vbCBzaWRlLWVmZmVjdCBjbGFzc2lmaWNhdGlvbi4gRGVmYXVsdHMgdG8gYHdyaXRlYC4gKi9cbiAgcmVhZG9ubHkgZWZmZWN0PzogXCJyZWFkXCIgfCBcIndyaXRlXCIgfCBcImRlc3RydWN0aXZlXCI7XG4gIC8qKiBSZXF1aXJlIGh1bWFuIGFwcHJvdmFsIGJlZm9yZSBleGVjdXRpb24uICovXG4gIHJlYWRvbmx5IGFwcHJvdmFsPzogYm9vbGVhbjtcbiAgLyoqIFdoZXRoZXIgZXhlY3V0aW9uIHJlcXVpcmVzIGFuIGF1dGhlbnRpY2F0ZWQgdXNlciBjb250ZXh0LiAqL1xuICByZWFkb25seSByZXF1aXJlc1VzZXJDb250ZXh0PzogYm9vbGVhbjtcbiAgLyoqIFdoZXRoZXIgcmVwZWF0ZWQgY2FsbHMgd2l0aCB0aGUgc2FtZSBpbnB1dCBhcmUgc2FmZS4gKi9cbiAgcmVhZG9ubHkgaWRlbXBvdGVudD86IGJvb2xlYW47XG4gIC8qKiBXaGV0aGVyIEFwcEtpdCBtYXkgaW5oZXJpdCB0aGUgdG9vbCBhdXRvbWF0aWNhbGx5LiAqL1xuICByZWFkb25seSBhdXRvSW5oZXJpdGFibGU/OiBib29sZWFuO1xufVxuXG4vKiogU2hhcGUgcGxhY2VkIGluIGEgWm9kIHNjaGVtYSdzIGAubWV0YSgpYCB2YWx1ZS4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgQXBwS2l0T3BlcmF0aW9uU2NoZW1hTWV0YSB7XG4gIHJlYWRvbmx5IGFwcGtpdFRvb2w/OiBBcHBLaXRUb29sTWV0YTtcbn1cblxuLyoqIE9uZSB0eXBlZCBvcGVyYXRpb24gYmFja2VkIGJ5IGEgc2luZ2xlIFpvZCBpbnB1dCBjb250cmFjdC4gKi9cbmV4cG9ydCBpbnRlcmZhY2UgQXBwS2l0T3BlcmF0aW9uPFRTY2hlbWEgZXh0ZW5kcyB6LlpvZFR5cGUgPSB6LlpvZFR5cGUsIFRSZXN1bHQgPSB1bmtub3duPiB7XG4gIHJlYWRvbmx5IHNjaGVtYTogVFNjaGVtYTtcbiAgcmVhZG9ubHkgZXhlY3V0ZTogKGlucHV0OiB6Lm91dHB1dDxUU2NoZW1hPiwgc2lnbmFsPzogQWJvcnRTaWduYWwpID0+IFRSZXN1bHQgfCBQcm9taXNlPFRSZXN1bHQ+O1xufVxuXG4vKiogUHJlc2VydmUgb3BlcmF0aW9uIGluZmVyZW5jZSB3aGlsZSBkZWNsYXJpbmcgYW4gZXhwb3J0ZWQgb3BlcmF0aW9uIG1hcC4gKi9cbmV4cG9ydCBmdW5jdGlvbiBkZWZpbmVPcGVyYXRpb25zPFxuICBjb25zdCBUU2NoZW1hcyBleHRlbmRzIFJlYWRvbmx5PFJlY29yZDxzdHJpbmcsIHouWm9kVHlwZT4+LFxuPihvcGVyYXRpb25zOiB7XG4gIHJlYWRvbmx5IFtUTmFtZSBpbiBrZXlvZiBUU2NoZW1hc106IEFwcEtpdE9wZXJhdGlvbjxUU2NoZW1hc1tUTmFtZV0sIHVua25vd24+O1xufSk6IHR5cGVvZiBvcGVyYXRpb25zIHtcbiAgcmV0dXJuIG9wZXJhdGlvbnM7XG59XG5cbi8qKiBDb252ZXJ0IGV4cG9ydGVkIFpvZCBvcGVyYXRpb24gY29udHJhY3RzIGludG8gYSBuYXRpdmUgQXBwS2l0IHRvb2wgcmVnaXN0cnkuICovXG5leHBvcnQgZnVuY3Rpb24gdG9vbFJlZ2lzdHJ5RnJvbU9wZXJhdGlvbnMoXG4gIG9wZXJhdGlvbnM6IFJlYWRvbmx5PFJlY29yZDxzdHJpbmcsIEFwcEtpdE9wZXJhdGlvbjx6LlpvZFR5cGUsIHVua25vd24+Pj4sXG4pOiBUb29sUmVnaXN0cnkge1xuICByZXR1cm4gT2JqZWN0LmZyb21FbnRyaWVzKFxuICAgIE9iamVjdC5lbnRyaWVzKG9wZXJhdGlvbnMpLmZsYXRNYXAoKFtuYW1lLCBvcGVyYXRpb25dKSA9PiB7XG4gICAgICBjb25zdCBtZXRhZGF0YSA9IG9wZXJhdGlvbi5zY2hlbWEubWV0YSgpIGFzIEFwcEtpdE9wZXJhdGlvblNjaGVtYU1ldGEgfCB1bmRlZmluZWQ7XG4gICAgICBjb25zdCB0b29sID0gbWV0YWRhdGE/LmFwcGtpdFRvb2wgPz8ge307XG4gICAgICBpZiAodG9vbC5hZ2VudFRvb2wgIT09IHRydWUpIHJldHVybiBbXTtcbiAgICAgIGNvbnN0IGVmZmVjdCA9IHRvb2wuZWZmZWN0ID8/IFwid3JpdGVcIjtcbiAgICAgIGNvbnN0IGFwcHJvdmFsID0gdG9vbC5hcHByb3ZhbCA9PT0gdHJ1ZSB8fCBlZmZlY3QgPT09IFwiZGVzdHJ1Y3RpdmVcIjtcbiAgICAgIGNvbnN0IGRlc2NyaXB0aW9uID0gb3BlcmF0aW9uLnNjaGVtYS5kZXNjcmlwdGlvbj8udHJpbSgpO1xuICAgICAgaWYgKCFkZXNjcmlwdGlvbikge1xuICAgICAgICB0aHJvdyBuZXcgVHlwZUVycm9yKGBBcHBLaXQgb3BlcmF0aW9uICR7bmFtZX0gcmVxdWlyZXMgYSBab2Qgc2NoZW1hIGRlc2NyaXB0aW9uYCk7XG4gICAgICB9XG4gICAgICByZXR1cm4gW1xuICAgICAgICBbXG4gICAgICAgICAgbmFtZSxcbiAgICAgICAgICBkZWZpbmVUb29sKHtcbiAgICAgICAgICAgIGRlc2NyaXB0aW9uLFxuICAgICAgICAgICAgc2NoZW1hOiBvcGVyYXRpb24uc2NoZW1hLFxuICAgICAgICAgICAgYW5ub3RhdGlvbnM6IHtcbiAgICAgICAgICAgICAgZWZmZWN0LFxuICAgICAgICAgICAgICAuLi4oYXBwcm92YWwgPyB7IGRlc3RydWN0aXZlOiB0cnVlIH0gOiB7fSksXG4gICAgICAgICAgICAgIC4uLih0b29sLnJlcXVpcmVzVXNlckNvbnRleHQgPT09IHVuZGVmaW5lZFxuICAgICAgICAgICAgICAgID8ge31cbiAgICAgICAgICAgICAgICA6IHsgcmVxdWlyZXNVc2VyQ29udGV4dDogdG9vbC5yZXF1aXJlc1VzZXJDb250ZXh0IH0pLFxuICAgICAgICAgICAgICAuLi4odG9vbC5pZGVtcG90ZW50ID09PSB1bmRlZmluZWQgPyB7fSA6IHsgaWRlbXBvdGVudDogdG9vbC5pZGVtcG90ZW50IH0pLFxuICAgICAgICAgICAgfSxcbiAgICAgICAgICAgIC4uLih0b29sLmF1dG9Jbmhlcml0YWJsZSA9PT0gdW5kZWZpbmVkXG4gICAgICAgICAgICAgID8ge31cbiAgICAgICAgICAgICAgOiB7IGF1dG9Jbmhlcml0YWJsZTogdG9vbC5hdXRvSW5oZXJpdGFibGUgfSksXG4gICAgICAgICAgICBleGVjdXRlOiAoaW5wdXQsIHNpZ25hbCkgPT4gb3BlcmF0aW9uLmV4ZWN1dGUob3BlcmF0aW9uLnNjaGVtYS5wYXJzZShpbnB1dCksIHNpZ25hbCksXG4gICAgICAgICAgfSksXG4gICAgICAgIF0sXG4gICAgICBdO1xuICAgIH0pLFxuICApO1xufVxuIl19

package/lib/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../src/_auto-configure.ts","../src/_cache-storage.ts","../src/appkit.ts","../src/brand-context.ts","../src/bundle.ts","../src/child-process.ts","../src/databricks.ts","../src/files-cache.ts","../src/identity.ts","../src/interceptor.ts","../src/lakebase-resolver.ts","../src/migration.ts","../src/pgaddress.ts","../src/plugin-execution.ts","../src/plugin-registry.ts","../src/provision.ts","../src/request-tags.ts","../src/tool-provider.ts","../src/toolkit-entries.ts","../index.ts"],"version":"5.9.3"}
+{"root":["../src/_auto-configure.ts","../src/appkit.ts","../src/brand-context.ts","../src/bundle.ts","../src/cache-storage.ts","../src/child-process.ts","../src/databricks.ts","../src/files-cache.ts","../src/identity.ts","../src/interceptor.ts","../src/lakebase-resolver.ts","../src/migration.ts","../src/pgaddress.ts","../src/plugin-execution.ts","../src/plugin-registry.ts","../src/provision.ts","../src/request-tags.ts","../src/tool-operations.ts","../src/tool-provider.ts","../src/toolkit-entries.ts","../index.ts"],"version":"5.9.3"}

package/package.json

@@ -20,7 +20,7 @@
   },
   "devDependencies": {
     "@databricks/appkit": "0.81.0",
-    "@dbx-tools/projen": "^0.9.118",
+    "@dbx-tools/projen": "^0.9.120",
     "@types/node": "^24.6.0",
     "typescript": "^5.9.3",
     "vitest": "3.2.4"
@@ -30,13 +30,13 @@
   },
   "dependencies": {
     "@databricks/sdk-experimental": "^0.17.0",
-    "@dbx-tools/auth": "^0.9.118",
-    "@dbx-tools/core": "^0.9.118",
-    "@dbx-tools/lakebase": "^0.9.118",
-    "@dbx-tools/postgres": "^0.9.118",
-    "@dbx-tools/shared-core": "^0.9.118",
-    "@dbx-tools/shared-fs": "^0.9.118",
-    "lru-cache": "11.5.3",
+    "@dbx-tools/auth": "^0.9.120",
+    "@dbx-tools/cache": "^0.9.120",
+    "@dbx-tools/core": "^0.9.120",
+    "@dbx-tools/lakebase": "^0.9.120",
+    "@dbx-tools/postgres": "^0.9.120",
+    "@dbx-tools/shared-core": "^0.9.120",
+    "@dbx-tools/shared-fs": "^0.9.120",
     "zod": "4.3.6"
   },
   "main": "./lib/index.js",
@@ -62,6 +62,10 @@
         "types": "./lib/src/bundle.d.ts",
         "default": "./lib/src/bundle.js"
       },
+      "./cache-storage": {
+        "types": "./lib/src/cache-storage.d.ts",
+        "default": "./lib/src/cache-storage.js"
+      },
       "./child-process": {
         "types": "./lib/src/child-process.d.ts",
         "default": "./lib/src/child-process.js"
@@ -110,6 +114,10 @@
         "types": "./lib/src/request-tags.d.ts",
         "default": "./lib/src/request-tags.js"
       },
+      "./tool-operations": {
+        "types": "./lib/src/tool-operations.d.ts",
+        "default": "./lib/src/tool-operations.js"
+      },
       "./tool-provider": {
         "types": "./lib/src/tool-provider.d.ts",
         "default": "./lib/src/tool-provider.js"
@@ -125,7 +133,7 @@
       "./package.json": "./package.json"
     }
   },
-  "version": "0.9.118",
+  "version": "0.9.120",
   "types": "./lib/index.d.ts",
   "dbxToolsConfig": {
     "tags": [
@@ -150,6 +158,10 @@
       "types": "./lib/src/bundle.d.ts",
       "default": "./lib/src/bundle.js"
     },
+    "./cache-storage": {
+      "types": "./lib/src/cache-storage.d.ts",
+      "default": "./lib/src/cache-storage.js"
+    },
     "./child-process": {
       "types": "./lib/src/child-process.d.ts",
       "default": "./lib/src/child-process.js"
@@ -198,6 +210,10 @@
       "types": "./lib/src/request-tags.d.ts",
       "default": "./lib/src/request-tags.js"
     },
+    "./tool-operations": {
+      "types": "./lib/src/tool-operations.d.ts",
+      "default": "./lib/src/tool-operations.js"
+    },
     "./tool-provider": {
       "types": "./lib/src/tool-provider.d.ts",
       "default": "./lib/src/tool-provider.js"

package/src/appkit.ts

@@ -39,8 +39,8 @@ import { profile as authProfile } from "@dbx-tools/auth";
 import { asyncUtils, environmentUtils, log } from "@dbx-tools/shared-core";
 
 import { resolveAutoConfigurePolicy } from "./_auto-configure.ts";
-import { createSoftPersistentStorage } from "./_cache-storage.ts";
 import { loadBrandContext } from "./brand-context.ts";
+import { createAppKitCacheStorage } from "./cache-storage.ts";
 import {
   createInterceptorContext,
   type Interceptor,
@@ -48,6 +48,7 @@ import {
   lifecycleBridge,
   type ResolvedAppEnv,
 } from "./interceptor.ts";
+import { installAsUserDevelopmentPatch } from "./identity.ts";
 import { applyLakebaseEnv, type LakebaseConnection } from "./lakebase-resolver.ts";
 import { provisionCacheSchema } from "./provision.ts";
 
@@ -244,20 +245,12 @@ function applyDefaultProfile(): string | undefined {
   return resolved.name;
 }
 
-/**
- * Whether `createApp` should inject soft-fail Lakebase cache storage.
- *
- * Skips when the caller disabled the cache, already supplied a storage
- * backend (including in-memory), or Lakebase is not in play.
- */
-function shouldInjectSoftPersistentCache(
-  config: CreateAppConfig | undefined,
-  lakebase: LakebaseConnection | undefined,
-): boolean {
+/** Whether `createApp` should inject the default memory-first cache storage. */
+function shouldInjectCacheStorage(config: CreateAppConfig | undefined): boolean {
   const cache = config?.cache;
   if (cache?.enabled === false) return false;
   if (cache?.storage) return false;
-  return Boolean(lakebase) || usesPlugin(config, LAKEBASE_PLUGIN);
+  return true;
 }
 
 function redactLakebaseConnection(resolved: LakebaseConnection): Record<string, unknown> {
@@ -306,6 +299,7 @@ function interceptorList(interceptor: CreateAppConfig["interceptor"]): Intercept
 export async function createApp<T extends AppKitPlugins>(
   config?: CreateAppConfig<T>,
 ): Promise<PluginMap<T>> {
+  installAsUserDevelopmentPatch();
   const plugins = pluginNames(config);
   const interceptors = interceptorList(config?.interceptor);
   logger.debug("createApp: start", {
@@ -328,15 +322,16 @@ export async function createApp<T extends AppKitPlugins>(
   delete appConfig.autoConfigure;
   delete appConfig.interceptor;
 
-  if (shouldInjectSoftPersistentCache(config, lakebase)) {
-    logger.debug("createApp: inject soft persistent cache storage");
-    const storage = await createSoftPersistentStorage(config?.cache);
-    if (storage) {
-      appConfig.cache = { ...config?.cache, storage };
-      logger.debug("createApp: soft persistent cache storage ready");
-    } else {
-      logger.debug("createApp: soft persistent cache storage unavailable");
-    }
+  if (shouldInjectCacheStorage(config)) {
+    logger.debug("createApp: inject memory-first cache storage");
+    const storage = await createAppKitCacheStorage({
+      cache: config?.cache,
+      preferLakebase: Boolean(lakebase) || usesPlugin(config, LAKEBASE_PLUGIN),
+    });
+    appConfig.cache = { ...config?.cache, storage };
+    logger.debug("createApp: memory-first cache storage ready", {
+      persistent: storage.isPersistent(),
+    });
   }
 
   if (interceptors.length === 0) {

package/src/{_cache-storage.ts → cache-storage.ts}

@@ -1,5 +1,5 @@
 /**
- * Soft-fail Lakebase cache storage for AppKit's persistent cache.
+ * Memory-first AppKit cache storage with soft-fail Lakebase persistence.
  *
  * AppKit's `PersistentStorage.initialize()` runs DDL migrations and throws on
  * any step failure. With `cache.strictPersistence: true` that throw makes
@@ -8,18 +8,25 @@
  * usable table keeps serving.
  *
  * `PersistentStorage` is not on AppKit's public export map. The deep load is
- * lazy and best-effort: if the installed AppKit layout changes, this returns
- * `undefined` and `createApp` leaves AppKit on its default cache path.
+ * lazy and best-effort: if the installed AppKit layout changes, Lakebase is
+ * skipped and the adapter keeps its project-scoped disk persistence.
  *
  * @module
  */
 
+import { EventEmitter } from "node:events";
 import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { createLakebasePool, getWorkspaceClient, type CacheConfig } from "@databricks/appkit";
+import {
+  closeCache,
+  createCache,
+  flushCache,
+  projectCache,
+  type CacheOptions,
+} from "@dbx-tools/cache/cache";
 import { postgresConnectionOptions } from "@dbx-tools/postgres";
 import { errorUtils, hash, log } from "@dbx-tools/shared-core";
-import { LRUCache } from "lru-cache";
 import { handleOwnershipMigrationError } from "./migration.ts";
 
 const logger = log.logger("cache-storage");
@@ -32,9 +39,17 @@ interface CacheEntry<T = unknown> {
   value: T;
 }
 
-/** Bounds for the process-local cache layered over persistent AppKit storage. */
-export interface L1CacheStorageOptions {
-  maxBytes?: number;
+/** Options for AppKit's memory-first cache storage adapter. */
+export interface AppKitCacheStorageOptions {
+  /** Native AppKit cache configuration. */
+  cache?: CacheConfig;
+  /** Whether to attempt AppKit's Lakebase PersistentStorage. Defaults to true. */
+  preferLakebase?: boolean;
+  /** Portable disk scope used when Lakebase is unavailable. */
+  diskScope?: string;
+  /** Write-behind coalescing delay in milliseconds. */
+  writeDelayMs?: number;
+  /** Maximum entries retained in the process-local memory primary. */
   maxEntries?: number;
 }
 
@@ -54,95 +69,126 @@ type PersistentStorageConstructor = new (
 
 let persistentStorageCtor: PersistentStorageConstructor | undefined | null = null;
 
-/** Process-local LRU that avoids a persistent cache query on every warm hit. */
-export class L1CacheStorage implements CacheStorage {
-  private readonly entries: LRUCache<string, CacheEntry>;
+class AppKitStorageLevel extends EventEmitter {
+  readonly opts = {};
+
+  constructor(private readonly storage: CacheStorage) {
+    super();
+  }
+
+  async get<T>(key: string): Promise<T | undefined> {
+    const entry = await this.storage.get<T>(key);
+    if (!entry) return undefined;
+    if (entry.expiry <= Date.now()) {
+      await this.storage.delete(key);
+      return undefined;
+    }
+    return entry.value;
+  }
+
+  async set(key: string, value: unknown, ttl?: number): Promise<void> {
+    await this.storage.set(key, {
+      value,
+      expiry: Date.now() + (ttl ?? 60_000),
+    });
+  }
+
+  async delete(key: string): Promise<boolean> {
+    await this.storage.delete(key);
+    return true;
+  }
+
+  clear(): Promise<void> {
+    return this.storage.clear();
+  }
+
+  has(key: string): Promise<boolean> {
+    return this.storage.has(key);
+  }
+
+  disconnect(): Promise<void> {
+    return this.storage.close();
+  }
+}
+
+/** Memory-first AppKit CacheStorage backed by @dbx-tools/cache. */
+export class AppKitCacheStorage implements CacheStorage {
+  private readonly cache: ReturnType<typeof createCache>;
+  private readonly keys = new Set<string>();
+  private closed = false;
 
   constructor(
-    private readonly storage: CacheStorage,
-    options: L1CacheStorageOptions = {},
+    cache: ReturnType<typeof createCache>,
+    private readonly persistent: CacheStorage | undefined,
   ) {
-    this.entries = new LRUCache({
-      max: positiveBound(options.maxEntries, 1_000, "maxEntries"),
-      maxSize: positiveBound(options.maxBytes, 64 * 1024 * 1024, "maxBytes"),
-      sizeCalculation: (entry, key) => retainedSize(key, entry),
-    });
+    this.cache = cache;
   }
 
   async get<T>(key: string): Promise<CacheEntry<T> | null> {
-    const local = this.entries.get(key);
-    if (local) return local as CacheEntry<T>;
-    const persisted = await this.storage.get<T>(key);
-    if (persisted && persisted.expiry > Date.now()) this.retain(key, persisted);
-    return persisted;
+    const entry = await this.cache.get<CacheEntry<T>>(key);
+    if (!entry) return null;
+    this.keys.add(key);
+    return entry;
   }
 
   async set<T>(key: string, entry: CacheEntry<T>): Promise<void> {
-    await this.storage.set(key, entry);
-    this.retain(key, entry);
+    const ttl = entry.expiry - Date.now();
+    if (ttl <= 0) {
+      await this.delete(key);
+      return;
+    }
+    await this.cache.set(key, entry, { ttl });
+    this.keys.add(key);
   }
 
   async delete(key: string): Promise<void> {
-    await this.storage.delete(key);
-    this.entries.delete(key);
+    await this.cache.delete(key);
+    this.keys.delete(key);
   }
 
   async clear(): Promise<void> {
-    await this.storage.clear();
-    this.entries.clear();
+    await this.cache.clear();
+    this.keys.clear();
   }
 
   async has(key: string): Promise<boolean> {
-    if (this.entries.has(key)) return true;
-    return this.storage.has(key);
+    return this.cache.has(key);
   }
 
-  size(): Promise<number> {
-    return this.storage.size();
+  async size(): Promise<number> {
+    return this.persistent ? this.persistent.size() : this.keys.size;
   }
 
   isPersistent(): boolean {
-    return this.storage.isPersistent();
+    return true;
   }
 
-  healthCheck(): Promise<boolean> {
-    return this.storage.healthCheck();
+  async healthCheck(): Promise<boolean> {
+    return this.persistent ? this.persistent.healthCheck() : true;
+  }
+
+  /** Drain tracked write-behind persistence without closing the storage. */
+  flush(): Promise<void> {
+    return flushCache(this.cache);
   }
 
   async close(): Promise<void> {
-    this.entries.clear();
-    await this.storage.close();
+    if (this.closed) return;
+    await closeCache(this.cache);
+    this.closed = true;
+    this.keys.clear();
   }
 
   /** Forward AppKit's runtime-only persistent cleanup hook when available. */
   async cleanupExpired(): Promise<number> {
     const cleanup = (
-      this.storage as CacheStorage & {
-        cleanupExpired?: () => Promise<number>;
-      }
-    ).cleanupExpired;
-    return cleanup ? cleanup.call(this.storage) : 0;
-  }
-
-  private retain<T>(key: string, entry: CacheEntry<T>): void {
-    const ttl = entry.expiry - Date.now();
-    if (ttl > 0) this.entries.set(key, entry, { ttl });
-  }
-}
-
-function positiveBound(value: number | undefined, fallback: number, name: string): number {
-  const resolved = value ?? fallback;
-  if (!Number.isFinite(resolved) || resolved <= 0) {
-    throw new RangeError(`${name} must be a finite positive number`);
-  }
-  return Math.floor(resolved);
-}
-
-function retainedSize(key: string, entry: CacheEntry): number {
-  try {
-    return Buffer.byteLength(key) + Buffer.byteLength(JSON.stringify(entry));
-  } catch {
-    return Number.MAX_SAFE_INTEGER;
+      this.persistent as
+        | (CacheStorage & {
+            cleanupExpired?: () => Promise<number>;
+          })
+        | undefined
+    )?.cleanupExpired;
+    return cleanup && this.persistent ? cleanup.call(this.persistent) : 0;
   }
 }
 
@@ -171,7 +217,7 @@ export function loadPersistentStorage(): PersistentStorageConstructor | undefine
     return loaded;
   } catch (err) {
     logger.debug("soft persistent cache skipped (PersistentStorage unavailable)", {
-      error: errorUtils.errorMessage(err),
+      error: errorUtils.toError(err),
     });
     persistentStorageCtor = undefined;
     return undefined;
@@ -257,9 +303,9 @@ export async function probeStorage(storage: PersistentStorageBase): Promise<void
 /**
  * Build a soft-fail Lakebase cache storage when a pool can be created and
  * AppKit's PersistentStorage can be loaded. Returns `undefined` otherwise so
- * AppKit can fall through to its normal cache path.
+ * the caller can use portable disk persistence.
  */
-export async function createSoftPersistentStorage(
+async function createPersistentStorage(
   cache: CacheConfig | undefined,
 ): Promise<CacheStorage | undefined> {
   const PersistentStorage = loadPersistentStorage();
@@ -281,13 +327,10 @@ export async function createSoftPersistentStorage(
     }
     await storage.initialize();
     await probeStorage(storage);
-    return new L1CacheStorage(storage, {
-      maxBytes: cache?.maxBytes,
-      maxEntries: cache?.maxSize,
-    });
+    return storage;
   } catch (err) {
     logger.debug("soft persistent cache unavailable", {
-      error: errorUtils.errorMessage(err),
+      error: errorUtils.toError(err),
     });
     if (pool) {
       await pool.end().catch(() => {});
@@ -295,3 +338,27 @@ export async function createSoftPersistentStorage(
     return undefined;
   }
 }
+
+/**
+ * Create AppKit CacheStorage with bounded memory first and tracked persistence.
+ * Lakebase remains AppKit's persistent owner when available; otherwise the
+ * shared project-scoped portable disk level is used.
+ */
+export async function createAppKitCacheStorage(
+  options: AppKitCacheStorageOptions = {},
+): Promise<AppKitCacheStorage> {
+  const nativeCache = options.cache;
+  const persistent =
+    options.preferLakebase === false ? undefined : await createPersistentStorage(nativeCache);
+  const common: CacheOptions = {
+    maxEntries: options.maxEntries ?? nativeCache?.maxSize,
+    writeDelayMs: options.writeDelayMs,
+  };
+  const cache = persistent
+    ? createCache({
+        ...common,
+        levels: [{ name: "appkit-persistent", store: new AppKitStorageLevel(persistent) }],
+      })
+    : projectCache(options.diskScope ?? "appkit", common);
+  return new AppKitCacheStorage(cache, persistent);
+}