@@ -0,0 +1,14 @@
+---
+'@objectstack/metadata-protocol': patch
+---
+
+fix(metadata-protocol): a publish build probe refused by read admission tells the publisher to get read access, not to change a correct dataset
+
+Clause-②: no
+Metadata-protocol: none
+
+The dashboard-widget probe runs the widget's dataset query as the publishing caller. A publisher who may not read the dataset's object got a `widget_query_failed` issue whose `fix` said to fix the dataset definition so the query compiles. The dataset was correct; the cause was the publisher's read access.
+
+- **An access refusal names the access.** When the analytics service refuses the query with `PERMISSION_DENIED` (an object or a field the caller may not read), the `fix` now says the dataset is not the cause, and that the publisher (or the role the dashboard is for) needs read access to the refused object, and the refused fields when the refusal names them. The refusal is told apart by the error's code, not its message.
+- **Every other failure keeps the dataset fix.** A selection the dataset does not declare, and a member the field-level gate cannot judge (also `PERMISSION_DENIED`, but its remedy is a dataset change), keep "Fix the dataset definition (or the widget's values/dimensions) so the query compiles, then republish."
+- **Nothing else changes.** The issue's `code` (`widget_query_failed`), `severity` (`error`) and `message` are the same, and so is every other probe plane.
@@ -0,0 +1,107 @@
+// Copyright (c) 2026 ObjectStack. Licensed under the Apache-2.0 license.
+
+/**
+ * A `widget_query_failed` issue's `fix` names the remedy for the failure that
+ * actually happened.
+ *
+ * The widget plane runs `queryDataset` as the publishing caller, so read
+ * admission can refuse a dataset that is correct. That refusal is told apart
+ * by the thrown error's ADR-0112 `code` (`PERMISSION_DENIED`), and its `fix`
+ * names the caller's read access — never a dataset edit. Every other throw
+ * (a selection the dataset does not declare, an unjudgeable member) keeps the
+ * dataset fix. `code`, `severity` and `message` are the same on both arms.
+ *
+ * The errors below are the analytics service's envelopes field for field
+ * (`read-admission.ts`, `field-read-admission.ts`, `dataset-refusal.ts`); the
+ * same leg through a real `AnalyticsService` is pinned in `@objectstack/runtime`
+ * (`packages-publish-drafts-probe-caller-context.test.ts`).
+ */
+
+import { describe, expect, it } from 'vitest';
+import { runBuildProbes, type ProbeEngine } from './build-probes.js';
+
+const ITEMS: Record<string, unknown> = {
+    'dashboard board': { name: 'board', widgets: [{ id: 'w1', dataset: 'ds', values: ['total'] }] },
+    'dataset ds': { name: 'ds', object: 'task_item', measures: [{ name: 'total', aggregate: 'count' }] },
+};
+const getItem = async (type: string, name: string) => ITEMS[`${type} ${name}`];
+const engine: ProbeEngine = { find: async () => [{ id: 'r1' }] };
+
+const DATASET_FIX = `Fix the dataset definition (or the widget's values/dimensions) so the query compiles, then republish.`;
+
+function envelope(message: string, fields: Record<string, unknown>): Error {
+    return Object.assign(new Error(message), fields);
+}
+
+async function probeThrowing(err: Error) {
+    const report = await runBuildProbes({
+        engine,
+        getItem,
+        analytics: { queryDataset: async () => { throw err; } },
+        context: { userId: 'u_publisher' },
+        published: [{ type: 'dashboard', name: 'board' }],
+    });
+    expect(report.checked.widgets).toBe(1);
+    expect(report.issues).toHaveLength(1);
+    const issue = report.issues[0]!;
+    // Unchanged on every arm: the code, the tier and the message the error carries.
+    expect(issue).toMatchObject({
+        layer: 'runtime',
+        severity: 'error',
+        code: 'widget_query_failed', // adr0112-ok: D6c build-probe diagnostics code
+        artifact: { type: 'dashboard', name: 'board' },
+        ref: { type: 'dataset', name: 'ds', member: 'w1' },
+    });
+    expect(issue.message).toContain(err.message);
+    return issue;
+}
+
+describe('widget_query_failed — the fix follows the failure', () => {
+    it('an object read-admission refusal names the caller\'s read access, not the dataset', async () => {
+        const issue = await probeThrowing(envelope(
+            '[Analytics] Access denied: reading "task_item" is not permitted for this user.',
+            { code: 'PERMISSION_DENIED', status: 403, object: 'task_item' },
+        ));
+        expect(issue.fix).toContain('read access to object "task_item"');
+        expect(issue.fix).toContain('Dataset "ds" is not the cause');
+        expect(issue.fix).not.toContain(DATASET_FIX);
+    });
+
+    it('names the object the refusal names — a joined object, not the dataset\'s base', async () => {
+        const issue = await probeThrowing(envelope(
+            '[Analytics] Access denied: reading "project" is not permitted for this user.',
+            { code: 'PERMISSION_DENIED', status: 403, object: 'project' },
+        ));
+        expect(issue.fix).toContain('read access to object "project"');
+        expect(issue.fix).not.toContain('"task_item"');
+    });
+
+    it('a field-level read refusal names the refused fields', async () => {
+        const issue = await probeThrowing(envelope(
+            "[Security] Field read denied: not permitted to aggregate [salary] on 'task_item'",
+            { code: 'PERMISSION_DENIED', status: 403, object: 'task_item', fields: ['salary'] },
+        ));
+        expect(issue.fix).toContain('read access to object "task_item" and its field(s) salary');
+    });
+
+    it('a selection the dataset does not declare keeps the dataset fix', async () => {
+        const issue = await probeThrowing(envelope(
+            'Dataset "ds" does not declare measure "nope".',
+            { code: 'DATASET_INVALID', status: 400 },
+        ));
+        expect(issue.fix).toBe(DATASET_FIX);
+    });
+
+    it('an unjudgeable member — PERMISSION_DENIED whose remedy IS the dataset — keeps the dataset fix', async () => {
+        const issue = await probeThrowing(envelope(
+            "[Analytics] Access denied: member 'total' on 'task_item' is not a column reference",
+            { code: 'PERMISSION_DENIED', status: 403, object: 'task_item', member: 'total' },
+        ));
+        expect(issue.fix).toBe(DATASET_FIX);
+    });
+
+    it('a bare Error keeps the dataset fix', async () => {
+        const issue = await probeThrowing(new Error('RAW_SQL_UNSUPPORTED'));
+        expect(issue.fix).toBe(DATASET_FIX);
+    });
+});
@@ -15,6 +15,8 @@
 // chat surfaces, and eval harnesses consume one stream regardless of which
 // verification plane found the problem.
 
+import type { StandardErrorCode } from '@objectstack/spec/api';
+
 /** One runtime-verification finding (ADR-0038 BuildIssue, layer 'runtime'). */
 export interface RuntimeBuildIssue {
     layer: 'runtime';
@@ -106,6 +108,36 @@ function asArr(v: unknown): unknown[] {
     return Array.isArray(v) ? v : [];
 }
 
+/**
+ * `PERMISSION_DENIED`, pinned against the STANDARD catalog — the code the
+ * analytics service's read admission throws (ADR-0112 envelope, 403).
+ */
+const PERMISSION_DENIED: StandardErrorCode = 'PERMISSION_DENIED';
+
+/**
+ * The read-admission refusal a widget query can be answered with, judged by
+ * the thrown error's ADR-0112 `code` — never by its message text.
+ *
+ * The analytics service refuses a caller who may not read an object (or a
+ * field the dataset reads) with `PERMISSION_DENIED` and names the refused
+ * object in `object` (a joined object can be the one refused, so it is read
+ * from the error before the dataset's own) and the refused fields in
+ * `fields`. That is the caller's access, not the dataset's definition.
+ *
+ * One `PERMISSION_DENIED` is NOT an access question: a member that is no
+ * column reference, refused because the gate cannot tell which fields it
+ * reads, carries `member`, and its remedy IS a dataset change — so it keeps
+ * the dataset fix.
+ */
+function readAdmissionRefusal(e: unknown): { object?: string; fields: string[] } | undefined {
+    const err = e && typeof e === 'object' ? (e as Rec) : undefined;
+    if (!err || err.code !== PERMISSION_DENIED || typeof err.member === 'string') return undefined;
+    return {
+        object: typeof err.object === 'string' && err.object ? err.object : undefined,
+        fields: asArr(err.fields).filter((f): f is string => typeof f === 'string' && f.length > 0),
+    };
+}
+
 /** Result rows of a queryDataset call, tolerant of {rows}/{data}/array shapes. */
 function resultRows(result: unknown): unknown[] {
     if (Array.isArray(result)) return result;
@@ -384,14 +416,27 @@ export async function runBuildProbes(opts: RunBuildProbesOptions): Promise<Build
                     });
                 }
             } catch (e) {
+                // The query runs as the publishing caller, so read admission
+                // can refuse a dataset that is correct. That refusal names an
+                // access remedy; telling the author to edit the dataset would
+                // send them to change something that works.
+                const refusal = readAdmissionRefusal(e);
+                const refusedObject = refusal?.object ?? objectName;
+                const fix = refusal
+                    ? `Dataset "${dsName}" is not the cause and needs no change: read admission refused the publishing caller. ` +
+                      `The publisher (or the role this dashboard is for) needs read access to ` +
+                      `${refusedObject ? `object "${refusedObject}"` : 'the object this dataset reads'}` +
+                      `${refusal.fields.length ? ` and its field(s) ${refusal.fields.join(', ')}` : ''}; grant it, then republish. ` +
+                      `The finding is about this caller's access: a viewer who has that access can read the widget.`
+                    : `Fix the dataset definition (or the widget's values/dimensions) so the query compiles, then republish.`;
                 issues.push({
                     layer: 'runtime',
                     severity: 'error',
                     artifact: { type: 'dashboard', name: p.name },
                     ref: { type: 'dataset', name: dsName, member: widgetId },
                     code: 'widget_query_failed',
                     message: `Dashboard "${p.name}" widget "${widgetId}" query against dataset "${dsName}" failed: ${String((e as Error)?.message ?? e)}`,
-                    fix: `Fix the dataset definition (or the widget's values/dimensions) so the query compiles, then republish.`,
+                    fix,
                 });
             }
         }
 
@@ -21,6 +21,9 @@
  * The two legs are each other's control: the reader's publish must come back
  * clean, and the non-reader's must still carry the refusal, so neither "the
  * probe stopped running" nor "the probe now reads as the system" can pass.
+ * The refusal's `fix` names the caller's read access; a third leg, a query that
+ * cannot compile, keeps the dataset fix, so the fix follows the failure rather
+ * than the plane.
  */
 import { afterEach, describe, expect, it, vi } from 'vitest';
 import { DatasetSchema } from '@objectstack/spec/ui';
@@ -41,13 +44,27 @@ const DATASET = DatasetSchema.parse({
     measures: [{ name: 'task_count', label: 'Tasks', aggregate: 'count' }],
 });
 
-const ITEMS: Record<string, unknown> = {
+/**
+ * The same measure over a relationship path the dataset never declares in
+ * `include`: a dataset that cannot compile (`DATASET_INVALID`), whoever reads it.
+ */
+const DATASET_UNDECLARED_JOIN = DatasetSchema.parse({
+    ...DATASET,
+    measures: [{ name: 'task_count', label: 'Tasks', aggregate: 'sum', field: 'project.estimate' }],
+});
+
+const itemsWithDataset = (dataset: unknown): Record<string, unknown> => ({
     'dashboard task_board': {
         name: 'task_board',
         widgets: [{ id: 'w_tasks', dataset: 'task_metrics', values: ['task_count'] }],
     },
-    'dataset task_metrics': DATASET,
-};
+    'dataset task_metrics': dataset,
+});
+const ITEMS = itemsWithDataset(DATASET);
+const ITEMS_UNDECLARED_JOIN = itemsWithDataset(DATASET_UNDECLARED_JOIN);
+
+/** The fix every widget query failure that is NOT an access refusal keeps. */
+const DATASET_FIX = `Fix the dataset definition (or the widget's values/dimensions) so the query compiles, then republish.`;
 
 /** Both callers may publish; only the reader may read `task_item`. */
 const caller = (userId: string) => ({
@@ -60,7 +77,7 @@ const caller = (userId: string) => ({
 const READER = 'u_reader';
 const NON_READER = 'u_publisher_without_read';
 
-function makeDoor() {
+function makeDoor(items: Record<string, unknown> = ITEMS) {
     const admissionContexts: Array<ExecutionContext | undefined> = [];
     const analytics = new AnalyticsService({
         queryCapabilities: () => ({ nativeSql: false, objectqlAggregate: true, inMemory: false }),
@@ -80,16 +97,16 @@ function makeDoor() {
             { type: 'dashboard', name: 'task_board' },
         ],
         get: async (ref: any, opts: any) =>
-            opts?.state === 'draft' ? { body: ITEMS[`${ref.type} ${ref.name}`], hash: 'h' } : null,
+            opts?.state === 'draft' ? { body: items[`${ref.type} ${ref.name}`], hash: 'h' } : null,
     });
     vi.spyOn(p, 'promoteDraftForPublish').mockImplementation(async (req: any) => ({
         singularType: req.type,
         orgId: null,
         advisories: [],
-        result: { version: 'h', seq: 1, item: { body: ITEMS[`${req.type} ${req.name}`] }, packageId: null },
+        result: { version: 'h', seq: 1, item: { body: items[`${req.type} ${req.name}`] }, packageId: null },
     }));
     vi.spyOn(p, 'runPublishSideEffects').mockResolvedValue({});
-    p.getMetaItem = async ({ type, name }: any) => ({ item: ITEMS[`${type} ${name}`] });
+    p.getMetaItem = async ({ type, name }: any) => ({ item: items[`${type} ${name}`] });
     p.getMetaItems = async () => ({ items: [] });
     const engineFinds: Array<{ object: string; context: unknown }> = [];
     p.engine = {
@@ -125,8 +142,8 @@ function makeDoor() {
     return { dispatcher: new HttpDispatcher(kernel), admissionContexts, engineFinds };
 }
 
-async function publishAs(userId: string) {
-    const door = makeDoor();
+async function publishAs(userId: string, items: Record<string, unknown> = ITEMS) {
+    const door = makeDoor(items);
     const result = await door.dispatcher.handlePackages(
         '/com.tasks/publish-drafts', 'POST', {}, {}, caller(userId),
     );
@@ -166,6 +183,20 @@ describe('publish-drafts widget probes run as the publishing caller (#25484)', (
             artifact: { type: 'dashboard', name: 'task_board' },
             ref: { type: 'dataset', name: 'task_metrics', member: 'w_tasks' },
         });
+        expect(failed[0].message).toContain(`reading "${GATED}" is not permitted for this user`);
+        // The dataset is correct: the fix names the caller's read access, never a dataset edit.
+        expect(failed[0].fix).toContain(`read access to object "${GATED}"`);
+        expect(failed[0].fix).not.toContain(DATASET_FIX);
         expect(admissionContexts.every((ctx) => ctx?.userId === NON_READER)).toBe(true);
     });
+
+    it('a query that cannot compile, for a caller who CAN read, keeps the dataset fix', async () => {
+        const { probes } = await publishAs(READER, ITEMS_UNDECLARED_JOIN);
+
+        expect(probes?.checked?.widgets).toBe(1);
+        const failed = probes.issues.filter((i: any) => i.code === 'widget_query_failed'); // adr0112-ok: D6c build-probe diagnostics code
+        expect(failed).toHaveLength(1);
+        expect(failed[0]).toMatchObject({ layer: 'runtime', severity: 'error', fix: DATASET_FIX });
+        expect(failed[0].message).toContain('is not declared in the dataset');
+    });
 });