diff --git a/‎.changeset/20680-metadata-protocol-packaged-dashboard-base.md‎
Lines changed: 11 additions & 0 deletions b/‎.changeset/20680-metadata-protocol-packaged-dashboard-base.md‎
Lines changed: 11 additions & 0 deletions
diff --git a/‎.changeset/20680-spec-dashboard-catalog-override.md‎
Lines changed: 17 additions & 0 deletions b/‎.changeset/20680-spec-dashboard-catalog-override.md‎
Lines changed: 17 additions & 0 deletions
diff --git a/‎packages/metadata-protocol/src/protocol.ts‎
Lines changed: 42 additions & 0 deletions b/‎packages/metadata-protocol/src/protocol.ts‎
Lines changed: 42 additions & 0 deletions
diff --git a/‎packages/objectql/src/protocol-packaged-dashboard-base.test.ts‎
Lines changed: 237 additions & 0 deletions b/‎packages/objectql/src/protocol-packaged-dashboard-base.test.ts‎
Lines changed: 237 additions & 0 deletions
@@ -0,0 +1,11 @@
+---
+'@objectstack/metadata-protocol': minor
+---
+
+fix(metadata-protocol): `getPackagedDashboardBase(name)` answers the dashboard a code package ships, before any overlay (#20680)
+
+`ObjectStackProtocolImplementation` gains `getPackagedDashboardBase(name)`, the dashboard twin of `getPackagedObjectBase`. It returns the packaged (code-layer) declaration of a dashboard, which is the `packagedBase` that `translateDashboard` compares a served dashboard against, so that a tenant's published overlay is not overwritten by the packaged translation catalog.
+
+It reads the artifact registry's code-package entry only. An overlay that was hydrated under the plain registry key can therefore never be returned as the base it is compared against. It returns `undefined` for a dashboard that no code package ships, for an unknown or empty name, and for a registry that cannot answer. A caller treats `undefined` as "no base known", and the catalog applies as before.
+
+The method is additive. No existing read changes answer: the item and list reads already serve a published org overlay by the same identity the write stored (`type`, name, `package_id`, organization). Nothing is removed or renamed.
@@ -0,0 +1,17 @@
+---
+'@objectstack/spec': minor
+---
+
+fix(spec): `translateDashboard` lets an explicit override beat the packaged catalog when it is handed the packaged base (#20680)
+
+`translateDashboard` (`@objectstack/spec/system`) now follows the rule ADR-0029 D9.2a records for objects: an explicit override beats a packaged default. When the caller supplies `packagedBase` (the dashboard as its code package ships it, before any tenant overlay), a catalog string replaces a served string only while that string still equals its packaged counterpart. The comparison is made per string: the dashboard `label` and `description`, each widget's `title`, `description` and sub-caption (`options.description`), each global filter's `label`, and each static option `label`. Each string is matched by the key the bundle addresses it by (widget `id`, filter key, option value). A widget, filter or option that the packaged base does not carry counts as authored, so its strings keep their values.
+
+Why: an org overlay on a packaged dashboard (ADR-0126 Regime O) published, and `?layers=true` reported it as effective, but the served widget title stayed the shipped one whenever the dashboard's bundle carried that title. The platform's `system_overview` is one such dashboard, because `platform-objects` ships an `en` bundle that repeats every widget title. The catalog translated the packaged declaration and was applied over the tenant's edit.
+
+What changes for a caller:
+
+- `translateDashboard`'s third parameter is typed `TranslateDocumentOptions` (was `ResolveOptions`). That type is `ResolveOptions` plus the optional `packagedBase`, and `translateMetadataDocument` already passed it through. Every existing call compiles unchanged.
+- Without `packagedBase` (`undefined` or `null`), the output is byte-identical to before: the catalog applies. No serving layer in this release passes a dashboard base yet, so no served dashboard changes answer with this package alone.
+- An edit back to exactly the shipped string is a no-op: the catalog still translates it.
+
+Nothing is removed or renamed, and there is nothing to migrate.
@@ -7160,6 +7160,48 @@ export class ObjectStackProtocolImplementation implements
         }
     }
 
+    /**
+     * [#20680] The PACKAGED (code-layer) declaration of a DASHBOARD — the
+     * body a code package ships, before any tenant `sys_metadata` overlay.
+     * The dashboard twin of {@link getPackagedObjectBase}, and the fact
+     * `translateDashboard` (`@objectstack/spec/system`) compares against as
+     * its `packagedBase`: the i18n catalog is the packaged translation of
+     * exactly this body, so it may only replace a string the served
+     * dashboard still carries unchanged from it (ADR-0029 D9.2a — an explicit
+     * override beats a packaged default; ADR-0126 Regime O — a packaged
+     * dashboard is overlay-editable, and a published overlay is what every
+     * read serves).
+     *
+     * Measured before this existed: an org overlay on `system_overview`
+     * published and was returned by {@link getMetaItem} and
+     * {@link getMetaItems} — the write and every protocol read resolve ONE
+     * identity (`type: 'dashboard'`, the name, `package_id: null`, the org) —
+     * yet the served widget title stayed the shipped one, because the
+     * translation of the served document had no base to compare with.
+     *
+     * {@link lookupArtifactItem}, and nothing wider: it answers only an item
+     * whose `_packageId` marks a genuine code package and is immune to an
+     * overlay row hydrated under the plain registry key, so the body it
+     * returns can never be the overlay it is meant to be compared against.
+     * A dashboard has no extension fold, so — unlike the object case — the
+     * artifact item IS the packaged declaration.
+     *
+     * Returns `undefined` — "no packaged baseline, infer nothing", which the
+     * translator reads as the catalog applying unchanged — for a
+     * runtime/tenant-authored dashboard (no code package ships it), an
+     * unknown name, and a registry double without the lookup.
+     */
+    getPackagedDashboardBase(name: string): unknown {
+        if (typeof name !== 'string' || name === '') return undefined;
+        try {
+            return this.lookupArtifactItem('dashboard', name);
+        } catch {
+            // A read over the in-memory registry; a failure here must never
+            // turn a served dashboard into a 5xx.
+            return undefined;
+        }
+    }
+
     /**
      * [#8268, generalising #8038] The REGISTRY-SIDE half of
      * {@link governServedItem}'s presence convergence: replay the registry's
 
@@ -0,0 +1,237 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * #20680 — `ObjectStackProtocolImplementation.getPackagedDashboardBase`, against
+ * a REAL `SchemaRegistry`, and the read it exists to feed.
+ *
+ * ## What was measured, and what it rules out
+ *
+ * An org overlay on the platform's own `system_overview` dashboard (ADR-0126
+ * Regime O — a packaged dashboard is overlay-editable) published `200`, and
+ * `?layers=true` reported it as effective, while the `/meta` item and list
+ * reads kept serving the shipped widget title. Measured on a booted showcase
+ * with an org-bound admin and a member of the same org: the write stored ONE
+ * row (`type: 'dashboard'`, the name, `package_id: null`, the org,
+ * `state: 'active'` after publish), and `getMetaItem` / `getMetaItems` both
+ * answered it — the overlay branch of the item read hit that row. So the write
+ * and every protocol read agree on the item's identity; the plain read's
+ * `_packageId: com.objectstack.plugin-auth` is only the code artifact's
+ * protection envelope, grafted onto the overlay body by
+ * `mergeArtifactProtection`.
+ *
+ * What replaced the title was the i18n catalog: `platform-objects` ships an
+ * `en` bundle whose `dashboards.system_overview.widgets.<id>.title` repeats
+ * the shipped string, and `translateDashboard` applied it over whatever the
+ * document said. The showcase dashboard (the control) ships no widget titles
+ * in its bundle, so the same overlay reached its reader untouched.
+ *
+ * The rule that fixes it is ADR-0029 D9.2a's — an explicit override beats a
+ * packaged default, decided by comparing against the PACKAGED declaration —
+ * and that comparison is only as good as the body this accessor returns. Hence
+ * a real registry: the body must be the one the code package shipped, never an
+ * overlay the protocol hydrated under the plain registry key.
+ */
+
+import { describe, it, expect } from 'vitest';
+import { ObjectStackProtocolImplementation } from '@objectstack/metadata-protocol';
+import { translateDashboard, type TranslationBundle } from '@objectstack/spec/system';
+import { SchemaRegistry } from './registry.js';
+import { assertEngineFindOnePredicate } from './engine-findone-predicate.js';
+
+const PKG = 'com.objectstack.plugin-auth';
+const DASH = 'system_overview';
+const ORG = 'org_acme';
+
+const SHIPPED_TITLE = 'Total Users';
+const EDITED_TITLE = 'Total Users (edited)';
+
+/** The dashboard as the code package ships it. */
+const packagedBody = () => ({
+    name: DASH,
+    label: 'System Overview',
+    columns: 12,
+    widgets: [
+        { id: 'widget_total_users', type: 'metric', title: SHIPPED_TITLE, object: 'sys_user', layout: { x: 0, y: 0, w: 3, h: 2 } },
+        { id: 'widget_organizations', type: 'metric', title: 'Organizations', object: 'sys_organization', layout: { x: 3, y: 0, w: 3, h: 2 } },
+    ],
+});
+
+/** The same dashboard as the org's published overlay stores it — one title edited. */
+const overlayBody = () => {
+    const body = packagedBody();
+    body.widgets[0] = { ...body.widgets[0], title: EDITED_TITLE };
+    return body;
+};
+
+/**
+ * The catalog `platform-objects` ships: `en` repeats the shipped strings,
+ * `zh-CN` translates them. Both locales, because the defect showed in the
+ * SOURCE locale — an `en` reader got the shipped English back over the edit.
+ */
+const BUNDLE: TranslationBundle = {
+    en: {
+        dashboards: {
+            [DASH]: {
+                widgets: {
+                    widget_total_users: { title: SHIPPED_TITLE },
+                    widget_organizations: { title: 'Organizations' },
+                },
+            },
+        },
+    } as any,
+    'zh-CN': {
+        dashboards: {
+            [DASH]: {
+                widgets: {
+                    widget_total_users: { title: '用户总数' },
+                    widget_organizations: { title: '组织' },
+                },
+            },
+        },
+    } as any,
+};
+
+const matchesWhere = (row: Record<string, unknown>, where: Record<string, unknown>) =>
+    Object.entries(where ?? {}).every(([k, v]) => {
+        if (k.startsWith('$')) throw new Error(`fake driver: unsupported operator ${k}`);
+        if (v === null) return row[k] === null || row[k] === undefined;
+        return row[k] === v;
+    });
+
+/**
+ * A real registry and the real protocol over a READ-ONLY in-memory
+ * `sys_metadata`: the rows are seeded exactly as the measured write left them,
+ * so no write verb is doubled here at all.
+ */
+function makeSession() {
+    const registry = new SchemaRegistry({ multiTenant: false });
+    registry.logLevel = 'silent';
+    const rows: Record<string, unknown>[] = [];
+    const engine: any = {
+        registry,
+        async findOne(table: string, o: { where: Record<string, unknown> }) {
+            // The real engine's #4419 predicate: a `findOne` naming no record is refused.
+            assertEngineFindOnePredicate(table, o);
+            if (table !== 'sys_metadata') return null;
+            return rows.find((r) => matchesWhere(r, o.where)) ?? null;
+        },
+        async find(table: string, o: { where: Record<string, unknown>; limit?: number }) {
+            if (table !== 'sys_metadata') return [];
+            const matched = rows.filter((r) => matchesWhere(r, o.where));
+            // The caller's bound, applied after the filter, by presence.
+            return typeof o?.limit === 'number' ? matched.slice(0, o.limit) : matched;
+        },
+    };
+    const protocol: any = new ObjectStackProtocolImplementation(engine, undefined, 'env_test');
+    return { protocol, registry, rows };
+}
+
+/** The code package's registration (plugin-auth's manifest, in the measured boot). */
+function registerPackaged(registry: SchemaRegistry) {
+    registry.registerItem('dashboard', packagedBody(), 'name', PKG);
+}
+
+/** The published org overlay row, in the identity the measured write stored. */
+function seedOrgOverlay(rows: Record<string, unknown>[]) {
+    rows.push({
+        id: 'r_1',
+        type: 'dashboard',
+        name: DASH,
+        package_id: null,
+        organization_id: ORG,
+        state: 'active',
+        metadata: JSON.stringify(overlayBody()),
+    });
+}
+
+const titleOf = (doc: any, id = 'widget_total_users') =>
+    (doc?.widgets as any[] | undefined)?.find((w) => w?.id === id)?.title;
+
+describe('#20680 getPackagedDashboardBase — the packaged declaration, never an overlay', () => {
+    it('answers the body the code package shipped', () => {
+        const s = makeSession();
+        registerPackaged(s.registry);
+        const base = s.protocol.getPackagedDashboardBase(DASH);
+        expect(titleOf(base)).toBe(SHIPPED_TITLE);
+        expect(base?._packageId).toBe(PKG);
+    });
+
+    it('is immune to an overlay hydrated under the plain registry key', () => {
+        // An env-wide overlay is hydrated into the registry's PLAIN key on
+        // publish. The accessor must still answer the packaged body — a base
+        // that returned the overlay would compare the edit equal to itself and
+        // hand the catalog straight back.
+        const s = makeSession();
+        registerPackaged(s.registry);
+        s.registry.registerItem('dashboard', overlayBody(), 'name');
+
+        // The trap is live: the plain registry read answers the overlay…
+        expect(titleOf(s.registry.getItem('dashboard', DASH))).toBe(EDITED_TITLE);
+        // …and the packaged base does not move.
+        expect(titleOf(s.protocol.getPackagedDashboardBase(DASH))).toBe(SHIPPED_TITLE);
+    });
+
+    it('is undefined for a dashboard no code package ships, an unknown name, and an empty name', () => {
+        // "No packaged baseline" is a real answer: the translator reads it as
+        // "infer nothing" and keeps the catalog, as before this change.
+        const s = makeSession();
+        s.registry.registerItem('dashboard', { ...packagedBody(), name: 'tenant_board' }, 'name');
+        expect(s.protocol.getPackagedDashboardBase('tenant_board')).toBeUndefined();
+        expect(s.protocol.getPackagedDashboardBase('no_such_board')).toBeUndefined();
+        expect(s.protocol.getPackagedDashboardBase('')).toBeUndefined();
+    });
+
+    it('is undefined when the host registry cannot answer', () => {
+        const partial: any = new ObjectStackProtocolImplementation({ registry: {} } as any, undefined, 'env_test');
+        expect(partial.getPackagedDashboardBase(DASH)).toBeUndefined();
+        const none: any = new ObjectStackProtocolImplementation({} as any, undefined, 'env_test');
+        expect(none.getPackagedDashboardBase(DASH)).toBeUndefined();
+    });
+});
+
+describe('#20680 the published org overlay, through the protocol read and the translation', () => {
+    it('the item read serves the overlay — one identity for the write and the read', async () => {
+        const s = makeSession();
+        registerPackaged(s.registry);
+        seedOrgOverlay(s.rows);
+        const served = await s.protocol.getMetaItem({ type: 'dashboard', name: DASH, organizationId: ORG });
+        expect(titleOf(served.item)).toBe(EDITED_TITLE);
+        // The code artifact's envelope rides on the overlay body; it names the
+        // registering package, not a second identity the overlay missed.
+        expect(served.item._packageId).toBe(PKG);
+    });
+
+    it('the translation serves the edit once it is handed the packaged base — en and zh-CN', async () => {
+        const s = makeSession();
+        registerPackaged(s.registry);
+        seedOrgOverlay(s.rows);
+        const served = (await s.protocol.getMetaItem({ type: 'dashboard', name: DASH, organizationId: ORG })).item;
+        const packagedBase = s.protocol.getPackagedDashboardBase(DASH);
+
+        for (const locale of ['en', 'zh-CN']) {
+            const out = translateDashboard(served, BUNDLE, { locale, packagedBase });
+            expect(titleOf(out), `${locale}: the edited widget keeps the edit`).toBe(EDITED_TITLE);
+        }
+        // The widget nobody edited is still translated.
+        const zh = translateDashboard(served, BUNDLE, { locale: 'zh-CN', packagedBase });
+        expect(titleOf(zh, 'widget_organizations')).toBe('组织');
+    });
+
+    it('CONTROL — without the base, the catalog replaces the edit (the measured defect)', async () => {
+        const s = makeSession();
+        registerPackaged(s.registry);
+        seedOrgOverlay(s.rows);
+        const served = (await s.protocol.getMetaItem({ type: 'dashboard', name: DASH, organizationId: ORG })).item;
+        expect(titleOf(translateDashboard(served, BUNDLE, { locale: 'en' }))).toBe(SHIPPED_TITLE);
+        expect(titleOf(translateDashboard(served, BUNDLE, { locale: 'zh-CN' }))).toBe('用户总数');
+    });
+
+    it('after reset (no overlay row) the shipped body is served and still translated', async () => {
+        const s = makeSession();
+        registerPackaged(s.registry);
+        const served = (await s.protocol.getMetaItem({ type: 'dashboard', name: DASH, organizationId: ORG })).item;
+        const packagedBase = s.protocol.getPackagedDashboardBase(DASH);
+        expect(titleOf(served)).toBe(SHIPPED_TITLE);
+        expect(titleOf(translateDashboard(served, BUNDLE, { locale: 'zh-CN', packagedBase }))).toBe('用户总数');
+    });
+});