feat(studio): package-scope the metadata editor read (ADR-0048) (#1711)

Two installed packages may ship metadata with the same type/name; the Studio
editor now resolves the right one instead of first-match.

- MetadataClient: layered()/getDraft() accept { packageId }; get() emits the
  `package` query param (server prefer-local).
- ResourceListPage: each row's edit link carries its owning package
  (?package=<row._packageId>) so even the unscoped list disambiguates.
- ResourceEditPage: reads ?package= and scopes the layered + draft read. The
  route's :appName is the Studio app, not the edited item's owner, so the scope
  comes from the URL.

Verified live: /apps/com.objectstack.studio/metadata/doc/showcase_index loads
each package's own item per ?package= (showcase vs studio); no console errors.

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

.changeset/adr-0048-studio-editor-package-scope.md

@@ -0,0 +1,17 @@
+---
+"@object-ui/data-objectstack": patch
+"@object-ui/app-shell": patch
+---
+
+ADR-0048: package-scope the Studio metadata editor read. Two installed packages
+may ship metadata with the same `type`/`name`; the editor now resolves the right
+one instead of first-match.
+
+- `MetadataClient`: `layered()` and `getDraft()` accept `{ packageId }`, and
+  `get()` emits the `package` query param (→ server prefer-local, `?package=`).
+- `ResourceListPage`: each item's edit link carries its owning package
+  (`?package=<row._packageId>`), so even the unscoped "all" list disambiguates;
+  falls back to the workspace suffix for runtime/overlay-only rows.
+- `ResourceEditPage`: reads `?package=` and scopes the layered + draft read to
+  that package. (The route's `:appName` is the Studio app, not the edited item's
+  owner, so the scope must come from the URL, not the active app.)

packages/app-shell/src/views/metadata-admin/ResourceEditPage.tsx

@@ -222,6 +222,12 @@ function MetadataResourceEditPageImpl({
 }: MetadataResourceEditPageImplProps) {
   const navigate = useNavigate();
   const [searchParams, setSearchParams] = useSearchParams();
+  // ADR-0048 — the owning package of the item being edited, carried on the
+  // edit URL as `?package=` (emitted by the metadata list links). Scopes the
+  // layered/draft read so a same-name collision resolves to the right
+  // package's item. NOT the active Studio app's package — Studio edits items
+  // across all installed packages.
+  const ownerPackageId = searchParams.get('package') ?? undefined;
   const client = useMetadataClient();
   const { entries } = useMetadataTypes(client);
   const entry: RichMetadataTypeEntry | undefined = entries.find((t) => t.type === type);
@@ -511,12 +517,13 @@ function MetadataResourceEditPageImpl({
     setError(null);
     (async () => {
       try {
+        const scope = ownerPackageId ? { packageId: ownerPackageId } : {};
         const [lay, draftResp] = await Promise.all([
-          client.layered<any>(type, name),
+          client.layered<any>(type, name, scope),
           // Draft reads are best-effort — a 404/error must not block
           // the page; readers without overlay-write permission still
           // see the published item.
-          client.getDraft<any>(type, name).catch(() => null),
+          client.getDraft<any>(type, name, scope).catch(() => null),
         ]);
         if (cancelled) return;
         setLayered(lay);
@@ -564,7 +571,7 @@ function MetadataResourceEditPageImpl({
     return () => {
       cancelled = true;
     };
-  }, [client, type, name, createMode, reloadKey]);
+  }, [client, type, name, ownerPackageId, createMode, reloadKey]);
 
   // Lazy-load references the first time the References sheet opens.
   const [refsLoading, setRefsLoading] = React.useState(false);

packages/app-shell/src/views/metadata-admin/ResourceListPage.tsx

@@ -431,6 +431,15 @@ function DefaultMetadataList({ type }: { type: string }) {
                 {filtered.map((row, i) => {
                   const pk = config.primaryKey ?? 'name';
                   const name = String(row.item[pk] ?? `(unnamed-${i})`);
+                  // ADR-0048 — link to this row's OWNING package so the editor
+                  // resolves the right item even in the unscoped "all" list
+                  // where two packages may ship the same name. Falls back to the
+                  // workspace suffix for runtime/overlay-only rows (no real
+                  // package, or the `sys_metadata` rehydration sentinel).
+                  const rowPkg = (row.item as any)._packageId as string | undefined;
+                  const rowEditSuffix = rowPkg && rowPkg !== 'sys_metadata'
+                    ? `?package=${encodeURIComponent(rowPkg)}`
+                    : pkgSuffix;
                   const invalid = row.diagnostics?.valid === false;
                   const errorList = row.diagnostics?.errors ?? [];
                   const warnList = (row.diagnostics as any)?.warnings ?? [];
@@ -486,7 +495,7 @@ function DefaultMetadataList({ type }: { type: string }) {
                                   </span>
                                 )}
                                 <Link
-                                  to={`./${encodeURIComponent(name)}${pkgSuffix}`}
+                                  to={`./${encodeURIComponent(name)}${rowEditSuffix}`}
                                   className="text-primary hover:underline font-mono"
                                 >
                                   {cell}

packages/data-objectstack/src/metadata-client.ts

@@ -113,6 +113,13 @@ export interface MetadataGetOptions {
    * to read the active (published) value.
    */
   state?: 'active' | 'draft';
+  /**
+   * Software-package id to scope resolution (sent as the `package` query
+   * param → server prefer-local, ADR-0048). Set when reading one item that
+   * may collide by name across installed packages (e.g. the Studio editor
+   * passes the edited item's owning package). Omit for context-free reads.
+   */
+  packageId?: string;
 }
 
 export interface MetadataDeleteOptions extends MetadataSaveOptions {
@@ -451,6 +458,7 @@ export class MetadataClient {
     // `state=draft` reads the raw draft row explicitly; the overlay flag is
     // redundant (and the dispatcher resolves `state` first), so skip it.
     else if (this.previewDrafts) params.push('preview=draft');
+    if (options.packageId) params.push(`package=${encodeURIComponent(options.packageId)}`);
     const qs = params.length ? `?${params.join('&')}` : '';
     const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}${qs}`;
     const res = await this.fetchImpl(url, { method: 'GET', headers: this.headers, cache: 'no-store' });
@@ -471,8 +479,12 @@ export class MetadataClient {
    * unwrapped body, so this method preserves that asymmetry by
    * returning whatever the server sent.
    */
-  async getDraft<T = unknown>(type: string, name: string): Promise<T | null> {
-    return this.get<T>(type, name, { state: 'draft' });
+  async getDraft<T = unknown>(
+    type: string,
+    name: string,
+    options: { packageId?: string } = {},
+  ): Promise<T | null> {
+    return this.get<T>(type, name, { state: 'draft', ...(options.packageId ? { packageId: options.packageId } : {}) });
   }
 
   /**
@@ -545,8 +557,13 @@ export class MetadataClient {
    * `code` (the artifact / fallback default), `overlay` (the saved
    * customisation, if any), and `effective` (what the runtime sees).
    */
-  async layered<T = unknown>(type: string, name: string): Promise<MetadataLayered<T>> {
-    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true`;
+  async layered<T = unknown>(
+    type: string,
+    name: string,
+    options: { packageId?: string } = {},
+  ): Promise<MetadataLayered<T>> {
+    const pkg = options.packageId ? `&package=${encodeURIComponent(options.packageId)}` : '';
+    const url = `${this.base}/${encodeURIComponent(type)}/${encodeURIComponent(name)}?layers=true${pkg}`;
     const res = await this.fetchImpl(url, { method: 'GET', headers: this.headers, cache: 'no-store' });
     if (res.status === 404) {
       return { code: null, overlay: null, overlayScope: null, effective: null };