From b0ef9f4130f34804f06ad117bcce6cec97824da2 Mon Sep 17 00:00:00 2001
From: Daniel Salazar <daniel.salazar@puter.com>
Date: Sat, 10 Oct 2026 18:42:28 -0400
Subject: [PATCH] perf(apps): read the uid alias only after a direct lookup
 misses

Every AppDriver uid lookup fired an uncached system-KV GetItem for the
merge alias in parallel with the direct read, even when the direct read
hit. The alias is now read only on a miss.
---
 src/backend/drivers/apps/AppDriver.js      |  6 ++--
 src/backend/drivers/apps/AppDriver.test.ts | 33 ++++++++++++++++++++++
 2 files changed, 35 insertions(+), 4 deletions(-)

diff --git a/src/backend/drivers/apps/AppDriver.js b/src/backend/drivers/apps/AppDriver.js
index 4bb137018..1db8b1e45 100644
--- a/src/backend/drivers/apps/AppDriver.js
+++ b/src/backend/drivers/apps/AppDriver.js
@@ -862,14 +862,12 @@ export class AppDriver extends PuterDriver {
      * keeps resolving to the joined row. Mirrors v1 AppES's `#read` alias
      * plumbing.
      *
-     * The alias query is fired in parallel with the direct lookup so the common
-     * (no-alias) case pays only one round-trip.
+     * The alias is an uncached system KV read, so it waits for a direct miss.
      */
     async #getByUidWithAlias(uid) {
-        const aliasPromise = this.#readCanonicalAppUidAlias(uid);
         const direct = await this.appStore.getByUid(uid);
         if (direct) return direct;
-        const canonicalUid = await aliasPromise;
+        const canonicalUid = await this.#readCanonicalAppUidAlias(uid);
         if (
             typeof canonicalUid === 'string' &&
             canonicalUid &&
diff --git a/src/backend/drivers/apps/AppDriver.test.ts b/src/backend/drivers/apps/AppDriver.test.ts
index 0ed74ae36..41a18f340 100644
--- a/src/backend/drivers/apps/AppDriver.test.ts
+++ b/src/backend/drivers/apps/AppDriver.test.ts
@@ -371,6 +371,39 @@ describe('AppDriver.read', () => {
             withActor(actor, () => driver.read({ uid: 'app-nonexistent' })),
         ).rejects.toMatchObject({ statusCode: 404 });
     });
+
+    it('reads the uid alias only when the direct lookup misses', async () => {
+        const { actor } = await makeUser();
+        const created = await withActor(actor, () =>
+            driver.create({
+                object: {
+                    name: uniqueName('alias-read'),
+                    title: 't',
+                    index_url: uniqueIndexUrl(),
+                },
+            }),
+        );
+        const kvGet = vi.spyOn(server.stores.kv, 'get');
+        const aliasReads = () =>
+            kvGet.mock.calls.filter((call) =>
+                String((call[0] as { key?: string })?.key).startsWith(
+                    'app:canonicalUidAlias:',
+                ),
+            ).length;
+        try {
+            await withActor(actor, () => driver.read({ uid: created.uid }));
+            expect(aliasReads()).toBe(0);
+
+            await expect(
+                withActor(actor, () =>
+                    driver.read({ uid: `app-${uuidv4()}` }),
+                ),
+            ).rejects.toMatchObject({ statusCode: 404 });
+            expect(aliasReads()).toBe(1);
+        } finally {
+            kvGet.mockRestore();
+        }
+    });
 });
 
 // ── select ──────────────────────────────────────────────────────────