[MarioCadenas]

The POC works as we agreed in the interview: the database plugin now serves authorized operations next to generated CRUD. Build, lint, typecheck, the full test suite (310 files pass, 1 skipped) and pnpm docs:build all pass. It has not been run against a real Postgres or Lakebase.

What's new. Everything below is new proposed API on the existing database plugin, exported only from @databricks/appkit/beta. Nothing else in AppKit changes.

• Helpers: defineQuery, defineMutation and definePolicy. An operation with no authorize fails at definition time.
• Routes: database({ routes: { "METHOD /path": op } }). Without routes, setup loads every config/database/routes/*.ts file. A route that overlaps another route or a generated CRUD route fails setup.
• One pipeline (runOperation):
  1. The caller comes from the x-forwarded-user header. No header returns 401, and a user ID in the body or query is ignored.
  2. The input is validated before anything else runs.
  3. Each policy must return exactly true. false or { deny } returns 403. A policy that throws or returns anything else returns 500 and never allows.
  4. The operation runs on the service-principal database connection. A mutation runs its authorization and its write in one transaction, so a refusal or failure rolls back.
  5. Error responses never include internal messages.
• One change to existing code: transaction() now lets an OperationError through untouched, as it already does validation errors. Otherwise a deliberate 403 or 409 was logged as an unclassified database error.

Playground example.

• orders plus an example-only team_members table. The framework never requires team_members; it just gives the policies something to check.
• GET /orders filters by team in the SQL itself.
• POST /orders/:id/approve checks role, approval limit and "not your own order". It then updates only if the order is still pending, and returns 409 otherwise.
• Generated CRUD stays on for the note tables only.
• config/database/orders.sql creates and seeds the tables. The report has curl commands for allowed, denied and 409 requests.

Tests. They cover all 10 required cases, plus the body not being able to replace the path ID or the caller. The concurrency test uses an in-memory fake that mimics Postgres's conditional update, so it doesn't prove the real row-lock behavior.

Things to know:

• Anyone running the playground against an existing Lakebase must run orders.sql first, or database setup fails its table check.
• The approval-limit check and the update are separate statements, so a concurrent change to an order's total in between isn't re-checked. Adding the limit to the update's condition fixes it.
• Bad routes fail setup only after the database has connected, so the existing setup timing test still passes.
• The Agents adapter was skipped as you decided. The report shows where it would plug in.
• Nested operation calls, an output schema and an operations manifest aren't built. They're listed as follow-ups.

The commits are 528e4d9a (core) and fa0f7178 (playground), both signed. The full report is in ~/.herdr-projects/reports/app-kit/3/report.md: architecture, design choices, assumptions, the future CRUD-as-operations idea, the Agents sketch, and limitations.

Also noticed:

• The playground's root tsc -p . fails on its client JSX/SVG files. They need their own tsconfig, and pnpm -r typecheck passes (apps/dev-playground/tsconfig.json).

Task: KIT-3 (app-kit/3)

[github-actions]

📦 Bundle size report

Compared against bundle-size-baseline.json (main).

@databricks/appkit

npm tarball (packed): 1.2 MB (+12 KB) — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	1.3 MB (+12 KB)	462 KB (+4.2 KB)
Type declarations	468 KB (+4.3 KB)	170 KB (+1.6 KB)
Source maps	2.5 MB (+24 KB)	864 KB (+8.0 KB)
Other	11 KB	3.7 KB
Total	4.3 MB (+40 KB)	1.5 MB (+14 KB)

Per-entry composition (own code — deps external (as shipped))

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
.	106 KB	2.5 KB	108 KB	external	343 KB
./beta	104 KB (+1.8 KB)	485 B	105 KB (+1.8 KB)	external	314 KB (+5.2 KB)
./testing	45 KB	32 KB	77 KB	external	223 KB
./tsdown	520 B	0 B	520 B	external	813 B
./type-generator	26 KB	0 B	26 KB	external	74 KB

Chunks:

Entry	Chunk	Load	Size (gz)
.	index.js	initial	101 KB
.	utils.js	initial	4.6 KB
.	remote-tunnel-manager.js	lazy	2.5 KB
./beta	beta.js	initial	84 KB
./beta	modular.js	initial	6.0 KB
./beta	stream-manager.js	initial	5.9 KB
./beta	service-context.js	initial	4.2 KB
./beta	databricks.js	initial	3.3 KB
./beta	client.js	initial	647 B
./beta	index.js	initial	20 B
./beta	supervisor-api.js	lazy	192 B
./beta	databricks.js	lazy	178 B
./beta	index.js	lazy	115 B
./testing	manifest.js	initial	32 KB
./testing	index.js	initial	10 KB
./testing	wide-event-emitter.js	initial	2.9 KB
./testing	index.js	lazy	28 KB
./testing	remote-tunnel-manager.js	lazy	2.5 KB
./testing	utils.js	lazy	1.8 KB
./tsdown	index.js	initial	520 B
./type-generator	index.js	initial	26 KB

@databricks/appkit-ui

npm tarball (packed): 397 KB — gzipped download (dist + bin; excludes release-only docs/NOTICE).

dist	raw	gzip
JS (runtime)	429 KB	147 KB
Type declarations	267 KB	98 KB
Source maps	853 KB	286 KB
CSS	16 KB	3.2 KB
Total	1.5 MB	534 KB

Per-entry composition (consumer bundle — deps bundled, peerDeps external)

Entry	Initial (gz)	Lazy (gz)	Total (gz)	node_modules (min)	Own code (min)
./js	5.3 KB	49 KB	55 KB	208 KB	14 KB
./js/beta	2.1 KB	0 B	2.1 KB	0 B	5.0 KB
./react	433 KB	49 KB	481 KB	1.3 MB	177 KB
./react/beta	4.9 KB	0 B	4.9 KB	0 B	12 KB

Chunks:

Entry	Chunk	Load	Size (gz)
./js	index.js	initial	5.2 KB
./js	chunk	initial	120 B
./js	apache-arrow	lazy	49 KB
./js/beta	beta.js	initial	2.1 KB
./react	index.js	initial	431 KB
./react	tslib	initial	2.1 KB
./react	apache-arrow	lazy	49 KB
./react/beta	beta.js	initial	4.9 KB

[MarioCadenas]

Review 1 · Fail · 1 critical, 2 major

Does the change do what the task asked? No. Gate: major and worse must be fixed.

The main vertical slice works, including real PostgreSQL transactions, scoped reads, denials, rollback and concurrent approvals. It does not fully meet the task: authorization facts are not protected against concurrent changes, Express-equivalent route collisions are missed, and the concurrency test passes despite losing the successful write in its fake. The full suite, lint/format checks and recursive typechecking pass; the repository was left unchanged.

Required

• critical: Approval can commit using authorization facts that changed after the policy read. (apps/dev-playground/config/database/policies.ts:23; apps/dev-playground/config/database/routes/orders.ts:36)
  Proof: Static inspection: canApproveOrder reads the order and membership without locking either, then approveOrder updates using only id and pending status. The underlying Drizzle transaction supplies no stronger isolation option. Under the default READ COMMITTED isolation, sharing a transaction does not preserve the authorization snapshot: a concurrent change to the total, team, creator or membership can invalidate the decision before the write. The implementation report explicitly acknowledges the total-change case. The interview recommendation incorrectly said the permission lookup and write would
• major: Route collision detection misses case and trailing-slash variants that Express treats as the same route. (packages/appkit/src/plugins/database/operations.ts:237; packages/appkit/src/plugins/database/database.ts:428)
  Proof: Ran the built DatabasePlugin with real setup, local PostgreSQL and Express.Router(). GET /notes correctly failed setup against generated CRUD, but GET /Notes and GET /notes/ both passed setup and handled requests to /notes with the custom marker response. Registering GET /status and GET /STATUS also passed, and requesting /STATUS ran the first handler. routeSignature normalizes parameter names but preserves case and the trailing slash. See route-collisions.txt.
• major: The concurrency test passes even when its fake database discards the successful approval. (apps/dev-playground/server/orders-operations.test.ts:83; apps/dev-playground/server/orders-operations.test.ts:205)
  Proof: Extracted and executed the exact fakeDb and fixtures with the real approveOrder operation. The two calls returned [200,409], satisfying the committed assertion, but after both settled the order was pending with approved_by=null. The losing transaction restores a global snapshot over the successful write, and the test never asserts the final persisted row. The independent real-Postgres check retained the approval, so this is a test defect rather than evidence of production data loss. See concurrency-test.txt.

[github-actions]

🤖 AppKit PR bot

🔬 Run evals

Start an eval for this PR from the evals-monitor app: Go to Evals Monitor →

📦 Try this PR's app template

Scaffolds a new app from this PR's SDK build. Run it in any folder (requires the GitHub CLI — gh auth login — and the Databricks CLI):

gh run download 39601044161 -R databricks/appkit -n appkit-template-0.89.0-pr.a76c20b-work-3-poc-operations-first-api-defin-682 -D appkit-pr-682 \
  && unzip -o "appkit-pr-682/appkit-template-0.89.0-pr.a76c20b-work-3-poc-operations-first-api-defin-682.zip" -d "appkit-pr-682" \
  && databricks apps init --template "appkit-pr-682"

The template pins @databricks/appkit and @databricks/appkit-ui to tarballs built from this branch, so the scaffolded app runs against this PR's code.

[MarioCadenas]

Review 2 · Pass

Does the change do what the task asked? Yes. Gate: major and worse must be fixed.

The POC meets the agreed scope, and F1, F2 and F3 are fixed. Real PostgreSQL and HTTP checks confirm stable authorization facts, safe concurrent approvals and expected request outcomes; the corrected concurrency test detects the old rollback bug. No remaining findings or critical regressions were found in this round.

No findings.

[MarioCadenas]

Review 3 · Fail · 3 major

Does the change do what the task asked? No. Gate: major and worse must be fixed.

The core orders slice works through Express and real Postgres, including scoped reads, concurrent approvals, policy locks and rollback. The change still has two reproduced integration faults and an incorrect Agents caller-scope description. All 223 focused tests, workspace typechecks and 12 current GitHub checks pass; the repository was left unchanged.

Required

• major: Operation routes convert existing database-hook validation rejections into generic HTTP 500 responses. (packages/appkit/src/plugins/database/operations.ts:199–203)
  Proof: Using real Express, DatabasePlugin and Drizzle against local Postgres 14.20, I called a defineMutation that delegates to db.boards.create(). Its beforeCreate hook threw DatabaseValidationError. The operation returned 500 {"error":"Operation failed"}; generated CRUD with the identical hook and input returned 422 with the validation issue. Neither inserted a row. lifecycle.ts preserves this exception, but operationErrorResponse does not handle it. See postgres-http.txt.
• major: Auto-discovered operations fail recognition when using the package’s development export. (packages/appkit/src/plugins/database/operations.ts:58, isOperation() and loadDefaultDatabaseRoutes())
  Proof: From apps/dev-playground, node --conditions=development --import tsx resolved the public beta entry to src/beta.ts. Existing schema discovery succeeded and an inline operation returned 42, but both discovered example operations failed isOperation and runOperation returned 500 before database access. Actual plugin.setup() against local Postgres then failed with: Route "GET /orders" must map to an operation created with defineQuery() or defineMutation(). The module-local WeakSet does not recognize the loader’s operation instances. Default production discovery succeeds. See development-discovery.
• major: The Agents adapter documentation incorrectly assumes forwarded user identity establishes a caller scope for default agents. (/Users/mario.cadenas/.herdr-projects/reports/app-kit/3/report.md:170 and :188)
  Proof: The report says function tools run in the agent route’s caller scope and illustrates getCallerContext(). However, agents.ts:1261 calls fn() directly unless registered.auth is on-behalf-of-user; core/agent/types.ts:205–210 documents service-principal execution as the default. The sketch therefore needs an explicit OBO configuration prerequisite or another way to establish caller context. This is source/documentation inspection, not a live agent invocation; a working adapter was explicitly deferred. See agents-scope.txt.