feat(app-shell): ADR-0048 Phase 2 — prefer-local metadata resolution (#1688)

Two installed packages may legitimately ship the same bare name (e.g. a `page`
named `home`); the install-time namespace gate keeps their namespaces distinct
and resolution disambiguates by container. Add `preferLocal(list, name,
ownerPackageId)`: prefer the item whose `_packageId` matches the active app's
package, falling back to the first name match (preserving prior behaviour when
the owner is unknown — runtime/DB apps with no `_packageId`).

Wire it at the bare-name resolution sites: PageView, DashboardView, ReportView
(rendered defs) and AppHeader (breadcrumb labels). The active app is read from
`useExpressionContext().app` / AppHeader's `currentApp`. v1 = namespace as the
route key (`/apps/crm`), so URLs are unchanged.

Test: utils/__tests__/preferLocal.test.ts (6). app-shell views/utils/layout
suites green (308).

Co-authored-by: Jack Zhuang <277994282+os-zhuang@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: 3 people

packages/app-shell/src/layout/AppHeader.tsx

@@ -61,7 +61,7 @@ import { useObjectTranslation, useObjectLabel } from '@object-ui/i18n';
 import type { BreadcrumbItem as BreadcrumbItemType } from '@object-ui/types';
 import { useAuth, getUserInitials } from '@object-ui/auth';
 import { useMetadata } from '../providers/MetadataProvider';
-import { resolveI18nLabel } from '../utils';
+import { resolveI18nLabel, preferLocal } from '../utils';
 import { getIcon } from '../utils/getIcon';
 import { useMobileViewSwitcher } from './MobileViewSwitcherContext';
 import { useNavigationContext } from '../context/NavigationContext';
@@ -483,23 +483,24 @@ export function AppHeader({
       extraSegments.push({ label: t('console.breadcrumb.dashboards'), href: baseHref });
       if (pathParts[3]) {
         const dashboardName = pathParts[3];
-        const dashboardDef = (metadataDashboards || []).find((d: any) => d.name === dashboardName);
+        // ADR-0048 Phase 2 — prefer the current app's package (container-scoped).
+        const dashboardDef = preferLocal(metadataDashboards as any[], dashboardName, (currentApp as any)?._packageId);
         const fallback = dashboardDef?.label || humanizeSlug(dashboardName);
         extraSegments.push({ label: dashboardLabel({ name: dashboardName, label: fallback }) });
       }
     } else if (routeType === 'page') {
       extraSegments.push({ label: t('console.breadcrumb.pages'), href: baseHref });
       if (pathParts[3]) {
         const pageName = pathParts[3];
-        const pageDef = (metadataPages || []).find((p: any) => p.name === pageName);
+        const pageDef = preferLocal(metadataPages as any[], pageName, (currentApp as any)?._packageId);
         const fallback = pageDef?.label || humanizeSlug(pageName);
         extraSegments.push({ label: pageLabel({ name: pageName, label: fallback }) });
       }
     } else if (routeType === 'report') {
       extraSegments.push({ label: t('console.breadcrumb.reports'), href: baseHref });
       if (pathParts[3]) {
         const reportName = pathParts[3];
-        const reportDef = (metadataReports || []).find((r: any) => r.name === reportName);
+        const reportDef = preferLocal(metadataReports as any[], reportName, (currentApp as any)?._packageId);
         const fallback = reportDef?.label || humanizeSlug(reportName);
         extraSegments.push({ label: reportLabel({ name: reportName, label: fallback }) });
       }

packages/app-shell/src/utils/__tests__/preferLocal.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest';
+import { preferLocal } from '../preferLocal';
+
+/**
+ * ADR-0048 Phase 2 — prefer-local (container-scoped) resolution.
+ */
+describe('preferLocal', () => {
+  const crmHome = { name: 'home', _packageId: 'com.acme.crm', title: 'CRM Home' };
+  const hrHome = { name: 'home', _packageId: 'com.acme.hr', title: 'HR Home' };
+  const list = [crmHome, hrHome];
+
+  it('prefers the item owned by the current package', () => {
+    expect(preferLocal(list, 'home', 'com.acme.crm')).toBe(crmHome);
+    expect(preferLocal(list, 'home', 'com.acme.hr')).toBe(hrHome);
+  });
+
+  it('falls back to first match when the package owns no such item', () => {
+    expect(preferLocal(list, 'home', 'com.acme.unknown')).toBe(crmHome);
+  });
+
+  it('falls back to first match when no owner package is given (legacy behaviour)', () => {
+    expect(preferLocal(list, 'home')).toBe(crmHome);
+    expect(preferLocal(list, 'home', undefined)).toBe(crmHome);
+  });
+
+  it('returns undefined for missing name or list', () => {
+    expect(preferLocal(list, undefined, 'com.acme.crm')).toBeUndefined();
+    expect(preferLocal(undefined, 'home', 'com.acme.crm')).toBeUndefined();
+    expect(preferLocal(null, 'home')).toBeUndefined();
+  });
+
+  it('returns undefined when nothing matches the name', () => {
+    expect(preferLocal(list, 'dashboard', 'com.acme.crm')).toBeUndefined();
+  });
+
+  it('resolves a single unambiguous item regardless of owner', () => {
+    expect(preferLocal([crmHome], 'home', 'com.acme.hr')).toBe(crmHome);
+  });
+});

packages/app-shell/src/utils/index.ts

@@ -13,6 +13,8 @@ export type {
 export { deriveRelatedLists } from './deriveRelatedLists';
 export type { DerivedRelatedList } from './deriveRelatedLists';
 
+export { preferLocal } from './preferLocal';
+
 /**
  * Resolves an I18nLabel to a plain string.
  * I18nLabel can be either a string or an object { key, defaultValue?, params? }.

packages/app-shell/src/utils/preferLocal.ts

@@ -0,0 +1,26 @@
+/**
+ * ADR-0048 Phase 2 — prefer-local (container-scoped) metadata resolution.
+ *
+ * Two installed packages may legitimately ship the same bare name (e.g. a
+ * `page` named `home`) — the install-time namespace gate keeps their namespaces
+ * distinct, and resolution disambiguates them by container. When resolving a
+ * bare name we prefer the item owned by the *current* container (the active
+ * app's package), so a user inside `/apps/crm` sees crm's `home`, not whichever
+ * package's `home` happened to load first.
+ *
+ * Falls back to the first name match when the container owns no such item or
+ * its owning package is unknown (runtime/DB apps with no `_packageId`), so this
+ * never regresses the prior first-match behaviour.
+ */
+export function preferLocal<T extends { name?: unknown; _packageId?: unknown }>(
+  list: readonly T[] | undefined | null,
+  name: string | undefined | null,
+  ownerPackageId?: unknown,
+): T | undefined {
+  if (!list || name == null) return undefined;
+  if (ownerPackageId) {
+    const local = list.find((x) => x.name === name && x._packageId === ownerPackageId);
+    if (local) return local;
+  }
+  return list.find((x) => x.name === name);
+}

packages/app-shell/src/views/DashboardView.tsx

@@ -40,7 +40,8 @@ import {
 import { MetadataPanel, useMetadataInspector } from './MetadataInspector';
 import { SkeletonDashboard } from '../skeletons';
 import { useMetadata } from '../providers/MetadataProvider';
-import { resolveI18nLabel } from '../utils';
+import { useExpressionContext } from '../providers/ExpressionProvider';
+import { resolveI18nLabel, preferLocal } from '../utils';
 import { useAdapter } from '../providers/AdapterProvider';
 import { useMetadataClient } from './metadata-admin/useMetadata';
 import { persistRuntimeMetadata } from './runtime-metadata-persistence';
@@ -177,7 +178,9 @@ export function DashboardView({ dataSource }: { dataSource?: any }) {
   }, [dashboardName]);
 
   const { dashboards, objects: metadataObjects, refresh } = useMetadata();
-  const dashboard = dashboards?.find((d: any) => d.name === dashboardName);
+  // ADR-0048 Phase 2 — prefer the dashboard owned by the current app's package.
+  const { app: activeApp } = useExpressionContext();
+  const dashboard = preferLocal(dashboards as any[], dashboardName, (activeApp as any)?._packageId);
 
   // Local schema state for live preview — initialized from metadata
   const [editSchema, setEditSchema] = useState<DashboardSchema | null>(null);

packages/app-shell/src/views/PageView.tsx

@@ -18,6 +18,8 @@ import { useObjectTranslation } from '@object-ui/i18n';
 import { useAuth } from '@object-ui/auth';
 import { MetadataPanel, useMetadataInspector } from './MetadataInspector';
 import { useMetadata } from '../providers/MetadataProvider';
+import { useExpressionContext } from '../providers/ExpressionProvider';
+import { preferLocal } from '../utils/preferLocal';
 import { ConsoleActionRuntimeProvider } from '../hooks/useConsoleActionRuntime';
 import { InterfaceListPage } from './InterfaceListPage';
 
@@ -34,11 +36,15 @@ export function PageView() {
   const isAdmin = user?.role === 'admin';
 
   const { pages, objects } = useMetadata();
+  // ADR-0048 Phase 2 — prefer the page owned by the current app's package so
+  // two packages shipping `page/<same-name>` each resolve within their own
+  // container instead of by load order.
+  const { app: activeApp } = useExpressionContext();
   const dataSource = useAdapter();
   // Bumped after a successful page action so embedded data (lists, etc.)
   // re-fetch. Threaded into the page context AND used to remount the renderer.
   const [refreshKey, setRefreshKey] = useState(0);
-  const page = pages?.find((p: any) => p.name === pageName);
+  const page = preferLocal(pages as any[], pageName, (activeApp as any)?._packageId);
 
   if (!page) {
     return (

packages/app-shell/src/views/ReportView.tsx

@@ -14,6 +14,8 @@ import { Pencil, BarChart3, Loader2 } from 'lucide-react';
 import { useObjectTranslation } from '@object-ui/i18n';
 import { MetadataPanel, useMetadataInspector } from './MetadataInspector';
 import { useMetadata } from '../providers/MetadataProvider';
+import { useExpressionContext } from '../providers/ExpressionProvider';
+import { preferLocal } from '../utils/preferLocal';
 import { useAdapter } from '../providers/AdapterProvider';
 import { useMetadataClient } from './metadata-admin/useMetadata';
 import { persistRuntimeMetadata } from './runtime-metadata-persistence';
@@ -51,7 +53,9 @@ export function ReportView({ dataSource }: { dataSource?: DataSource }) {
 
   // Find report definition from API-driven metadata
   const { reports, objects, loading, refresh } = useMetadata();
-  const initialReport = reports?.find((r: any) => r.name === reportName);
+  // ADR-0048 Phase 2 — prefer the report owned by the current app's package.
+  const { app: activeApp } = useExpressionContext();
+  const initialReport = preferLocal(reports as any[], reportName, (activeApp as any)?._packageId);
   const [reportData, setReportData] = useState(initialReport);
 
   // Local schema state for live preview — initialized from metadata