diff --git a/‎.changeset/22473-approval-request-page.md‎
Lines changed: 18 additions & 0 deletions b/‎.changeset/22473-approval-request-page.md‎
Lines changed: 18 additions & 0 deletions
diff --git a/‎content/docs/automation/approvals.mdx‎
Lines changed: 3 additions & 1 deletion b/‎content/docs/automation/approvals.mdx‎
Lines changed: 3 additions & 1 deletion
diff --git a/‎packages/plugins/plugin-approvals/scripts/i18n-extract.config.ts‎
Lines changed: 17 additions & 4 deletions b/‎packages/plugins/plugin-approvals/scripts/i18n-extract.config.ts‎
Lines changed: 17 additions & 4 deletions
diff --git a/‎packages/plugins/plugin-approvals/src/action-predicate-sparse-face.test.ts‎
Lines changed: 17 additions & 4 deletions b/‎packages/plugins/plugin-approvals/src/action-predicate-sparse-face.test.ts‎
Lines changed: 17 additions & 4 deletions
diff --git a/‎packages/plugins/plugin-approvals/src/approval-service.test.ts‎
Lines changed: 118 additions & 0 deletions b/‎packages/plugins/plugin-approvals/src/approval-service.test.ts‎
Lines changed: 118 additions & 0 deletions
diff --git a/‎packages/plugins/plugin-approvals/src/approvals-plugin.ts‎
Lines changed: 7 additions & 0 deletions b/‎packages/plugins/plugin-approvals/src/approvals-plugin.ts‎
Lines changed: 7 additions & 0 deletions
@@ -0,0 +1,18 @@
+---
+'@objectstack/plugin-approvals': minor
+---
+
+feat(plugin-approvals): serve the approval request's record page, and declare the thread reply as `approval_comment`
+
+Clause-②: no
+
+**The request's record page is now metadata this plugin serves.** `ApprovalsServicePlugin` registers `sys_approval_request_detail` through its manifest `pages`: a slotted record page, default for every `sys_approval_request` record, that the metadata API serves like any other page. Its slots:
+
+- `actions`: one `record:approval_decision` node (the decision panel: the request's decision progress and its declared decision actions);
+- `highlights`: the object's `highlightFields` without `record_id`, so `record_id` stays in the details grid, where the console draws the target record of the `record_id` / `object_name` pointer pair. The object's own `highlightFields` is unchanged;
+- `tabs`: Details (`record:details`) and Timeline (`sys_approval_action` as a related list on `request_id`, newest first);
+- `discussion: []`: no generic discussion thread. The request's thread is its timeline.
+
+The page label is translated in the plugin's bundle as `pages.sys_approval_request_detail.label` (en, zh-CN, ja-JP, es-ES). The page stays module-internal: nothing new is exported from the package entry.
+
+**`approval_comment` declares the thread reply.** `sys_approval_request` now declares a ninth action, `approval_comment` ("Reply"). It posts `comment` (a required textarea) and `attachments` (optional, several files) to `POST /api/v1/approvals/requests/{id}/comment`, the route the console drawer posted to by hand. The service stores the reply as a `sys_approval_action` row with action `comment`, which the Timeline lists. Its `visible` gate is the route's own admission: a pending approver (`record.viewer.can_act`), or the submitter while the request is `pending`. It has no admin-override arm, because the comment route admits none.
@@ -613,7 +613,9 @@ You rarely call these routes by hand. The decision verbs above ship as
 **server-declared actions** on `sys_approval_request` (`actions[]` in its object
 metadata) — `approval_approve`, `approval_reject`, `approval_reassign`,
 `approval_send_back`, `approval_request_info`, `approval_remind`,
-`approval_recall`, `approval_resubmit`. The console's generic action runtime
+`approval_recall`, `approval_resubmit`, `approval_comment`. `approval_comment`
+is the thread reply: a pending approver sees it, and so does the submitter while
+the request is `pending`; it has no admin-override arm. The console's generic action runtime
 renders and executes them wherever the object is surfaced — the **Approvals
 inbox** included — so a decision (comment, a file-upload for `attachments`, the
 reassign user-picker) is collected by the generic action dialog with **no
 
@@ -39,16 +39,28 @@
  * `@objectstack/platform-objects` — this plugin translates only the objects it
  * owns, so it must not commit a second copy. Add `--check` to run the same
  * command as a drift gate.
+ *
+ * `pages` declares the record page this plugin ships
+ * (`sys_approval_request_detail`). The command above writes the objects
+ * sub-tree only, so the page's one bundle key — its page-level `label` — is
+ * HAND-AUTHORED in `src/translations/pages.ts`, the way
+ * `@objectstack/platform-objects` carries its own record pages' labels, and
+ * that section rides in the `translations` baseline below. Declaring the page
+ * here is what puts its label in the coverage ratchet's population, counted
+ * against that section: a page left out of this config is a label no gate
+ * looks at.
  */
 
 import { defineStack, type ObjectStackDefinition } from '@objectstack/spec';
 import { SysApprovalRequest } from '../src/sys-approval-request.object.js';
 import { SysApprovalAction } from '../src/sys-approval-action.object.js';
 import { SysApprovalDelegation } from '../src/sys-approval-delegation.object.js';
+import { SysApprovalRequestDetailPage } from '../src/sys-approval-request.page.js';
 import { enObjects } from '../src/translations/en.objects.generated.js';
 import { zhCNObjects } from '../src/translations/zh-CN.objects.generated.js';
 import { jaJPObjects } from '../src/translations/ja-JP.objects.generated.js';
 import { esESObjects } from '../src/translations/es-ES.objects.generated.js';
+import { approvalsPageTranslations } from '../src/translations/pages.js';
 
 /**
  * The annotation is load-bearing, not decoration (#10868). `defineStack`
@@ -66,11 +78,12 @@ import { esESObjects } from '../src/translations/es-ES.objects.generated.js';
  */
 const config: ObjectStackDefinition = defineStack({
   objects: [SysApprovalRequest, SysApprovalAction, SysApprovalDelegation] as any,
+  pages: [SysApprovalRequestDetailPage],
   translations: [
-    { en: { objects: enObjects } },
-    { 'zh-CN': { objects: zhCNObjects } },
-    { 'ja-JP': { objects: jaJPObjects } },
-    { 'es-ES': { objects: esESObjects } },
+    { en: { objects: enObjects, pages: approvalsPageTranslations.en } },
+    { 'zh-CN': { objects: zhCNObjects, pages: approvalsPageTranslations['zh-CN'] } },
+    { 'ja-JP': { objects: jaJPObjects, pages: approvalsPageTranslations['ja-JP'] } },
+    { 'es-ES': { objects: esESObjects, pages: approvalsPageTranslations['es-ES'] } },
   ],
 });
 
 
@@ -79,7 +79,7 @@ const BINDINGS: Array<[string, Record<string, unknown>]> = [
 describe('#8990 — sys_approval_request decision actions never fault on a sparse binding', () => {
   it('every action predicate reads record.* and is has()-guarded on each path', () => {
     const predicates = ACTIONS.map((a) => sourceOf(a.visible)).filter((v): v is string => typeof v === 'string');
-    expect(predicates.length).toBe(8);
+    expect(predicates.length).toBe(9);
     const unguarded: string[] = [];
     for (const source of predicates) {
       for (const m of source.matchAll(/record((?:\.[a-z_][a-z0-9_]*)+)/gi)) {
@@ -107,14 +107,14 @@ describe('#8990 — sys_approval_request decision actions never fault on a spars
 describe('#8990 — the fail-closed intent survives as a real false, and the levers still open', () => {
   it('an absent viewer block closes every viewer-gated lever', () => {
     const row = { status: 'pending' };
-    for (const name of ['approval_approve', 'approval_reject', 'approval_reassign', 'approval_send_back', 'approval_request_info', 'approval_remind', 'approval_recall', 'approval_resubmit']) {
+    for (const name of ['approval_approve', 'approval_reject', 'approval_reassign', 'approval_send_back', 'approval_request_info', 'approval_remind', 'approval_recall', 'approval_resubmit', 'approval_comment']) {
       expect([name, evaluate(visibleOf(name), row)]).toEqual([name, false]);
     }
   });
 
-  it('a current pending approver still gets approve / reject / reassign / send back / request info', () => {
+  it('a current pending approver still gets approve / reject / reassign / send back / request info, and the reply', () => {
     const approver = { status: 'pending', viewer: { can_act: true, can_override: false, is_submitter: false } };
-    for (const name of ['approval_approve', 'approval_reject', 'approval_reassign', 'approval_send_back', 'approval_request_info']) {
+    for (const name of ['approval_approve', 'approval_reject', 'approval_reassign', 'approval_send_back', 'approval_request_info', 'approval_comment']) {
       expect([name, evaluate(visibleOf(name), approver)]).toEqual([name, true]);
     }
     // Submitter levers stay closed for them.
@@ -144,6 +144,9 @@ describe('#8990 — the fail-closed intent survives as a real false, and the lev
     // moved, and remind/resubmit stay shut for an actor who is not the submitter.
     expect(evaluate(visibleOf('approval_remind'), admin)).toBe(false);
     expect(evaluate(visibleOf('approval_resubmit'), { ...admin, status: 'returned' })).toBe(false);
+    // Nor into the thread reply: the comment route admits the submitter and the
+    // slot holders only, so an override admin on no slot gets no reply button.
+    expect(evaluate(visibleOf('approval_comment'), admin)).toBe(false);
   });
 
   it('the recall override arm is pending-only in effect, because `can_override` is itself pending-scoped (#12716)', () => {
@@ -182,6 +185,16 @@ describe('#8990 — the fail-closed intent survives as a real false, and the lev
     expect(evaluate(visibleOf('approval_recall'), { status: 'approved', viewer: submitter })).toBe(false);
     expect(evaluate(visibleOf('approval_resubmit'), { status: 'pending', viewer: submitter })).toBe(false);
   });
+
+  it('the submitter gets the reply while the request is pending, and only then', () => {
+    // `is_submitter` carries no status test where it is computed, so the
+    // reply's submitter arm states the `pending` the comment route requires.
+    const submitter = { can_act: false, can_override: false, is_submitter: true };
+    expect(evaluate(visibleOf('approval_comment'), { status: 'pending', viewer: submitter })).toBe(true);
+    for (const status of ['returned', 'approved', 'rejected', 'recalled', 'cancelled']) {
+      expect([status, evaluate(visibleOf('approval_comment'), { status, viewer: submitter })]).toEqual([status, false]);
+    }
+  });
 });
 
 describe('#8990 — why the guard form is leaf-first (measured, not preferred)', () => {
 
@@ -13,6 +13,8 @@ import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { APPROVAL_REVISE_NODE_TYPE } from '@objectstack/spec/automation';
 import { ApprovalService, REMIND_COOLDOWN_MS, ESCALATION_ENABLED_FLIP_CUTOFF_MS, SLA_ACTOR_ID } from './approval-service.js';
 import { bindApprovalLockHook, bindDelegationWriteGuard, unbindAllHooks } from './lifecycle-hooks.js';
+import { celEngine } from '@objectstack/formula';
+import { SysApprovalRequest } from './sys-approval-request.object.js';
 
 interface FakeRow { [k: string]: any }
 
@@ -2048,6 +2050,122 @@ describe('ApprovalService — admin override (#3424)', () => {
   });
 });
 
+// ── approval_comment: the declared reply against the route it posts to ──────
+//
+// `sys_approval_request` declares the thread reply as the action
+// `approval_comment` (POST `/approvals/requests/{id}/comment`, body `comment` +
+// `attachments`, no actor). Its `visible` gate is evaluated on the row the
+// caller is served — `getRequest`, which attaches the `viewer` block — so the
+// gate is only honest if, for every caller shape, "the button shows" is exactly
+// "the route admits the post". This matrix measures both halves against the
+// REAL service for each shape, and the agreement is the pin: a predicate looser
+// than the route is a lever that fails on use, a narrower one a reply nobody
+// can send. The REST route resolves the actor as `body.actorId ?? body.actor_id
+// ?? context.userId`, and the declared action sends no actor, so the service is
+// driven with the caller's own id exactly as the route would drive it.
+describe('approval_comment — its visible gate is the comment route\'s admission', () => {
+  let engine: ReturnType<typeof makeFakeEngine>;
+  let svc: ApprovalService;
+  let n = 0;
+  const baseTime = new Date('2026-01-15T10:00:00Z').getTime();
+
+  const PLATFORM_ADMIN = { userId: 'root', tenantId: 't1', positions: [], permissions: ['admin_full_access'] } as any;
+  const SALES_MANAGER = { userId: 'u_sm', tenantId: 't1', positions: ['sales_manager'], permissions: [] } as any;
+
+  type Action = { name: string; visible?: { dialect: string; source: string } | string };
+  const reply = ((SysApprovalRequest as { actions?: Action[] }).actions ?? []).find((a) => a.name === 'approval_comment');
+
+  /** The predicate's verdict on the row this caller is served; no row, no button. */
+  const shown = (row: Record<string, unknown> | null, ctx: any): boolean => {
+    if (!row || !reply?.visible) return false;
+    const source = typeof reply.visible === 'string' ? reply.visible : reply.visible.source;
+    const r = celEngine.evaluate({ dialect: 'cel', source }, { record: row, user: { id: String(ctx.userId ?? '') } });
+    if (!r.ok) throw new Error(`approval_comment.visible faulted: ${r.error.message}`);
+    return r.value === true;
+  };
+
+  /** The route's verdict: the post as the declared action sends it, or the refusal's code. */
+  const admitted = async (id: string, ctx: any): Promise<true | string> => {
+    try {
+      await svc.comment(id, { actorId: ctx.userId, comment: 'a reply', attachments: ['file_1'] }, ctx);
+      return true;
+    } catch (err: any) {
+      return String(err?.message ?? err).split(':')[0];
+    }
+  };
+
+  async function open(input: ReturnType<typeof openInput>): Promise<string> {
+    const opened = await svc.openNodeRequest(input, CTX); // submitter u1
+    if ('autoApproved' in opened) throw new Error('fixture: the approver slate must not be empty');
+    return opened.id;
+  }
+
+  beforeEach(() => {
+    engine = makeFakeEngine();
+    n = 0;
+    svc = new ApprovalService({ engine: engine as any, clock: { now: () => new Date(baseTime + (n++) * 1000) } });
+  });
+
+  it('the action is declared, and posts to the comment route', () => {
+    expect(reply, 'sys_approval_request declares approval_comment').toBeDefined();
+  });
+
+  it('every caller shape: the button shows exactly when the route admits the post', async () => {
+    const pending = await open(openInput(['u9']));
+    const stuck = await open(openInput([], {
+      recordId: 'opp2', runId: 'run_2',
+      config: { approvers: [{ type: 'position' as const, value: 'sales_manager' }], behavior: 'first_response' as const, lockRecord: true },
+    }));
+    const approved = await open(openInput(['u9'], { recordId: 'opp3', runId: 'run_3' }));
+    await svc.decideNode(approved, { decision: 'approve', actorId: 'u9' }, SYS);
+    const recalled = await open(openInput(['u9'], { recordId: 'opp4', runId: 'run_4' }));
+    await svc.recall(recalled, { actorId: 'u1' }, CTX);
+
+    const cases: Array<[string, string, any, boolean, true | string]> = [
+      ['pending · the submitter', pending, CTX, true, true],
+      ['pending · a pending approver', pending, asUser('u9'), true, true],
+      ['pending · a holder of a position slot', stuck, SALES_MANAGER, true, true],
+      ['pending · an override admin on no slot', pending, PLATFORM_ADMIN, false, 'FORBIDDEN'],
+      ['pending · a stranger', pending, asUser('u_stranger'), false, 'FORBIDDEN'],
+      ['approved · the submitter', approved, CTX, false, 'INVALID_STATE'],
+      ['approved · the approver who decided', approved, asUser('u9'), false, 'INVALID_STATE'],
+      ['recalled · the submitter', recalled, CTX, false, 'INVALID_STATE'],
+    ];
+    const measured: Array<[string, boolean, true | string]> = [];
+    for (const [label, id, ctx] of cases) {
+      const row = (await svc.getRequest(id, ctx)) as Record<string, unknown> | null;
+      measured.push([label, shown(row, ctx), await admitted(id, ctx)]);
+    }
+    expect(measured).toEqual(cases.map(([label, , , show, admit]) => [label, show, admit]));
+    // The agreement itself, stated without the expected table: shown ⇔ admitted.
+    for (const [label, show, admit] of measured) expect([label, show], label).toEqual([label, admit === true]);
+  });
+
+  it('the override admin is a real non-arm, not a reader who cannot see the request', async () => {
+    // Without this the admin row above could pass because the admin is simply
+    // not served the request. The admin IS served it, with the override flag
+    // the decision levers OR in — and the reply deliberately does not.
+    const id = await open(openInput(['u9']));
+    const row = await svc.getRequest(id, PLATFORM_ADMIN);
+    expect(row?.viewer).toMatchObject({ can_act: false, is_submitter: false, can_override: true });
+  });
+
+  it('a reply the route admits is a comment row on the request timeline, attachments included', async () => {
+    const id = await open(openInput(['u9']));
+    await svc.comment(id, { actorId: 'u1', comment: 'Receipts attached.', attachments: ['file_a', 'file_b'] }, CTX);
+    await svc.comment(id, { actorId: 'u9', comment: 'Thanks, reviewing.' }, asUser('u9'));
+    const timeline = await svc.listActions(id, asUser('u9'));
+    const replies = timeline.filter((a) => a.action === 'comment');
+    expect(replies.map((a) => [a.comment, (a.attachments ?? []).map((f) => f.id)])).toEqual([
+      ['Receipts attached.', ['file_a', 'file_b']],
+      ['Thanks, reviewing.', []],
+    ]);
+    // A reply moves nothing: the request is still pending on the same slate.
+    const row = await svc.getRequest(id, SYS);
+    expect([row?.status, row?.pending_approvers]).toEqual(['pending', ['u9']]);
+  });
+});
+
 // #12769 — the read-back after a successful mutation narrows by the CALLER's
 // org (`loadRequest`), so an org-less request row (every schedule /
 // time-relative / api trigger run produces one — #10131, pinned rather than
 
@@ -12,6 +12,7 @@ import { SysApprovalAction } from './sys-approval-action.object.js';
 import { SysApprovalApprover } from './sys-approval-approver.object.js';
 import { SysApprovalToken } from './sys-approval-token.object.js';
 import { SysApprovalDelegation } from './sys-approval-delegation.object.js';
+import { SysApprovalRequestDetailPage } from './sys-approval-request.page.js';
 import { renderConfirmPage, renderResultPage } from './action-link-pages.js';
 import {
   ApprovalService,
@@ -124,6 +125,12 @@ export class ApprovalsServicePlugin implements Plugin {
       defaultDatasource: 'cloud',
       namespace: 'sys',
       objects: [SysApprovalRequest, SysApprovalAction, SysApprovalApprover, SysApprovalToken, SysApprovalDelegation],
+      // The request's record-detail page (a slotted page, default for every
+      // sys_approval_request record): the decision panel, the request's
+      // fields, and its timeline. This plugin owns the object, so it ships its
+      // page too — the shape plugin-auth ships sys_user's. The page and its
+      // slot map are documented on `SysApprovalRequestDetailPage`.
+      pages: [SysApprovalRequestDetailPage],
       // ADR-0029 D7 — contribute the Approvals entries into the Setup app's
       // `group_approvals` slot. This plugin owns these objects (K2.b), so it
       // ships their menu too; when the plugin isn't installed the slot is empty.