@north-light/crouter 0.3.312 → 0.3.313

package/dist/clients/inbox/controller.js

@@ -1,24 +1,24 @@
-import { existsSync, statSync, watch } from 'node:fs';
-import { basename } from 'node:path';
+import { existsSync, watch } from 'node:fs';
 import { visibleWidth } from '@earendil-works/pi-tui';
 import { renderMarkdown } from '../../core/termrender/termrender.js';
 import { BOLD, CYAN, DIM, GRAY, RESET, YELLOW, clipLine } from './tui/ansi.js';
 import { buildInboxLines, recommendedLabel } from './tui.js';
 import { inboxLayout } from './layout.js';
-import { scanInbox } from '../../core/human/scan.js';
 import { resolvePageComponents } from '../../core/config.js';
 import { watchInboxActivity } from '../../core/human/root.js';
 import { claimTicket, heartbeatClaim, releaseClaim } from '../../core/human/claim.js';
-import { readPageTicket, readTicketResult } from '../../core/human/tickets.js';
-import { claimPath, clearProgress, isResolved, pagePath, responsePath } from '../../core/human/convention.js';
+import { claimPath, clearProgress } from '../../core/human/convention.js';
 import { emitEvent } from '../../core/events/emit.js';
+import { cliClient } from '../../commands/api-client.js';
 import { projectPageDisplayMarkdown } from '../../core/human/page-markdown.js';
 import { projectHtmlDocumentMarkdown } from '../../core/human/page-html-markdown.js';
 import { pageBodyLines } from './tui/page-body.js';
+import { byNewestFirst, inboxRowFromDTO, pageViewFromDTO, settledStatusOf } from './dto-adapt.js';
 import { PageAdapter } from './page-adapter.js';
 import { ReviewAdapter } from './review-adapter.js';
+import { createReviewClient } from './review/review-client.js';
 import { editBufferInEditor } from './review/roundtrip.js';
-import { cancelTicketViaDaemon, daemonErrorMessage, ticketIdFor, resolveFailureKind, resolveTicketPage, } from './resolve.js';
+import { daemonErrorMessage, dismissTicketViaDaemon, resolveFailureKind, resolveTicketPage, } from './resolve.js';
 /** Host-agnostic model for scanning, stable selection, claims, and rendering. */
 export class InboxController {
     options;
@@ -42,39 +42,66 @@ export class InboxController {
     heartbeat;
     started = false;
     closed = false;
-    /** The selected page's projected body, kept across frames because building it
-     *  reads and evaluates the page document. Keyed by what changes it. */
+    /** The selected page's projection, kept across frames because fetching it is
+     *  a round trip. `view` is held so a width change re-wraps without one. */
     preview;
+    /** A preview read that failed, so the panel says so instead of staying blank. */
+    previewFailed;
+    /** In-flight preview fetch, keyed by dir: one request per selection at a time. */
+    previewFetching;
+    /** Set by `invalidate`: the held preview may no longer be the current revision. */
+    previewStale = false;
+    /** The revision the open detail was loaded from, so a replacement published
+     *  while the reader has the page open reloads it. */
+    openRevision;
     constructor(options) {
         this.options = options;
         this.host = options.host;
-        this.scan = options.scan ?? (() => scanInbox());
+        this.scan = options.scan ?? defaultScan;
         this.cols = options.cols ?? 80;
         this.rows = options.rows ?? 24;
         // Seeded before the first rescan, which preserves a selected dir it finds.
         this.selectedDir = options.initialSelection;
-        this.rescan();
+        void this.rescan();
     }
     snapshot() {
         return { items: [...this.items], selectedDir: this.selectedDir, screen: this.screen, inputBuffer: this.adapter?.inputBuffer() };
     }
-    rescan() {
+    async rescan() {
         const priorDir = this.selectedDir;
         const priorIndex = this.selectedIndex;
-        this.items = this.scan();
+        const claim = this.claim;
+        // The row list is a round trip, and most rescans are fired from inbox
+        // activity with nobody awaiting them. A failed read keeps the rows already
+        // on screen and says so in the status line, rather than rejecting into a
+        // caller that cannot handle it.
+        try {
+            this.items = await this.scan();
+        }
+        catch (error) {
+            if (this.closed)
+                return;
+            this.status = daemonErrorMessage(error);
+            this.markDirty();
+            return;
+        }
+        if (this.closed)
+            return;
         const found = priorDir === undefined ? -1 : this.items.findIndex((item) => item.dir === priorDir);
         if (found >= 0) {
             this.selectedIndex = found;
             this.selectedDir = priorDir;
             return;
         }
-        if (this.adapter !== undefined && priorDir !== undefined) {
-            const canceled = readTicketResultOrNull(priorDir)?.kind === 'canceled';
+        if (this.adapter !== undefined && priorDir !== undefined && claim !== undefined) {
+            const canceled = (await this.requestOrNull(claim.id))?.state === 'canceled';
+            if (this.closed)
+                return;
             if (canceled)
                 clearProgress(priorDir);
             // Suppress the "resolved elsewhere" banner when WE are the ones resolving
-            // this ticket: the response.json we just published trips the root watch
-            // mid-submit, and that is our own completion, not an external event.
+            // this ticket: the settlement we just submitted drops the row from the
+            // scan mid-submit, and that is our own completion, not an external event.
             if (priorDir !== this.submittingDir)
                 this.status = canceled ? 'canceled by requester' : 'ticket resolved elsewhere';
             this.leaveDetail(priorDir !== this.submittingDir);
@@ -97,7 +124,24 @@ export class InboxController {
                 heartbeatClaim(this.claim.dir, this.claim.token);
         }, 10_000);
     }
-    invalidate() { this.rescan(); this.markDirty(); }
+    /** Inbox activity is the one signal a replacement always emits, and it is
+     *  emitted after the new revision is selected — so an open page reloads here
+     *  rather than from a file watch that cannot see a directory swap. */
+    async invalidate() {
+        // Activity is the one signal a replacement always emits, and it fires after
+        // the new revision is selected — so the held preview and any open page are
+        // re-read from the daemon here rather than from a file watch, which cannot
+        // see a directory swap at all.
+        this.previewStale = true;
+        await this.rescan();
+        if (this.closed)
+            return;
+        if (this.adapter !== undefined && this.claim !== undefined) {
+            await this.reloadSelectedPage();
+            return;
+        }
+        this.markDirty();
+    }
     resize(cols, rows) {
         this.cols = cols;
         this.rows = rows;
@@ -149,10 +193,10 @@ export class InboxController {
         }
         if (this.cancelConfirmation !== undefined) {
             if (input === 'y' || input === 'Y') {
-                const dir = this.cancelConfirmation.dir;
+                const item = this.cancelConfirmation.item;
                 this.cancelConfirmation = undefined;
                 this.status = 'canceling…';
-                void this.cancelFromInbox(dir);
+                void this.cancelFromInbox(item);
             }
             else if (input === 'n' || input === 'N' || key.escape) {
                 this.cancelConfirmation = undefined;
@@ -164,7 +208,7 @@ export class InboxController {
         if (input === 'x' || input === 'X') {
             const selected = this.items[this.selectedIndex];
             if (selected !== undefined) {
-                this.cancelConfirmation = { dir: selected.dir, title: selected.title };
+                this.cancelConfirmation = { item: selected };
                 this.status = undefined;
             }
             this.markDirty();
@@ -186,7 +230,7 @@ export class InboxController {
         else if (input === 'g' || input === 'G')
             void this.focusSelectedSource();
         else if (key.return || input === 'a')
-            this.activate();
+            void this.activate();
         this.markDirty();
     }
     /** Settle the selected ticket from the list with what crouter already put on
@@ -201,15 +245,18 @@ export class InboxController {
             this.status = 'no recommended answer on this ticket — Enter opens it';
             return;
         }
+        // Settlement is a daemon-owned state, so a claim still succeeds on a
+        // settled request's directory. The record decides whether this row is
+        // stale; only then does a refused claim mean another inbox holds it.
+        const request = await this.requestOrNull(item.id);
+        if (isSettled(request)) {
+            this.status = settledStatus(request);
+            await this.rescan();
+            return;
+        }
         const claim = claimTicket(item.dir);
         if (claim === null) {
-            // A null claim means either the ticket already settled (its response.json
-            // exists) or a live claim is held. Only the latter is "another inbox";
-            // the former is a stale row this scan should drop.
-            const resolved = isResolved(item.dir);
-            this.status = resolved ? safeCanonicalResultStatus(item.dir) : 'ticket is being edited by another inbox';
-            if (resolved)
-                this.rescan();
+            this.status = 'ticket is being edited by another inbox';
             return;
         }
         const settled = item.fastAction.kind === 'acknowledge'
@@ -217,25 +264,30 @@ export class InboxController {
             : `sent: ${recommendedLabel(item) ?? 'recommended answer'}`;
         this.submittingDir = item.dir;
         try {
-            await resolveTicketPage(item.dir, item.fastAction.responses);
+            await resolveTicketPage(item.id, item.fastAction.responses);
             this.status = settled;
         }
         catch (error) {
-            this.status = resolveFailureKind(error) === 'already_resolved'
-                ? safeCanonicalResultStatus(item.dir)
+            this.status = resolveFailureKind(error) === 'already_settled'
+                ? settledStatus(await this.requestOrNull(item.id))
                 : daemonErrorMessage(error);
         }
         finally {
             releaseClaim(item.dir, claim.token);
             this.submittingDir = undefined;
-            this.rescan();
+            await this.rescan();
             this.markDirty();
         }
     }
-    async cancelFromInbox(dir) {
-        this.submittingDir = dir;
+    /** A review and a page are two different durable records; the inbox dismisses
+     *  whichever one the selected row actually is. */
+    async cancelFromInbox(item) {
+        this.submittingDir = item.dir;
         try {
-            await cancelTicketViaDaemon(dir, { reason: 'Canceled from the inbox.', actor: 'human', disposition: 'dismissed' });
+            if (item.kind === 'review')
+                await createReviewClient().cancel(item.id, 'Canceled from the inbox.');
+            else
+                await dismissTicketViaDaemon(item.id, { reason: 'Canceled from the inbox.', actor: 'human' });
             this.status = 'canceled';
         }
         catch (error) {
@@ -243,46 +295,67 @@ export class InboxController {
         }
         finally {
             this.submittingDir = undefined;
-            this.rescan();
+            await this.rescan();
             this.markDirty();
         }
     }
-    activate() {
+    async activate() {
         const item = this.items[this.selectedIndex];
         if (item === undefined)
             return;
         if (item.kind === 'review') {
-            void this.activateReview(item);
+            await this.activateReview(item);
             return;
         }
-        if (item.kind !== 'page')
+        const request = await this.requestOrNull(item.id);
+        if (this.closed)
             return;
+        if (isSettled(request)) {
+            this.status = settledStatus(request);
+            await this.rescan();
+            return;
+        }
         const claim = claimTicket(item.dir);
         if (claim === null) {
-            const resolved = isResolved(item.dir);
-            this.status = resolved ? safeCanonicalResultStatus(item.dir) : 'ticket is being edited by another inbox';
-            if (resolved)
-                this.rescan();
+            this.status = 'ticket is being edited by another inbox';
             return;
         }
-        this.claim = { dir: item.dir, token: claim.token };
-        let loaded;
+        // One projection carries the revision AND the content it belongs to, so
+        // there is no window between reading the two in which a replacement lands.
+        let view;
+        let revision;
         try {
-            loaded = readPageTicket(item.dir);
+            const page = await cliClient().getHumanInboxPage(item.inboxTicketId);
+            // The claim is a presenter lock, not settlement authority, so a request
+            // that settled between the pre-claim check and this read would still
+            // claim. This projection already carries the state that decides it.
+            if (page.state === 'resolved' || page.state === 'canceled') {
+                releaseClaim(item.dir, claim.token);
+                this.status = settledStatusOf(page);
+                await this.rescan();
+                return;
+            }
+            view = pageViewFromDTO(page);
+            revision = page.revision;
         }
         catch {
             releaseClaim(item.dir, claim.token);
-            this.claim = undefined;
             this.status = 'page could not be read';
-            this.invalidate();
+            await this.invalidate();
+            return;
+        }
+        // Another activation (or a close) may have landed while this read was in
+        // flight; that one owns the detail screen, so this claim is released.
+        if (this.closed || this.claim !== undefined || this.adapter !== undefined) {
+            releaseClaim(item.dir, claim.token);
             return;
         }
-        const productKinds = resolvePageComponents();
+        this.claim = { dir: item.dir, id: item.id, ticketId: item.inboxTicketId, token: claim.token };
         this.screen = 'detail';
         this.adapter = new PageAdapter({
-            dir: item.dir,
-            ticket: loaded,
-            productKinds,
+            ticketId: item.inboxTicketId,
+            page: view,
+            productKinds: resolvePageComponents(),
             cols: this.detailSize().cols,
             rows: this.detailSize().rows,
             onDirty: () => this.markDirty(),
@@ -290,11 +363,13 @@ export class InboxController {
             onBack: () => { this.leaveDetail(); this.markDirty(); },
             onComplete: (responses) => { void this.complete(responses); },
         });
+        this.openRevision = revision;
         this.watchSelected(item.dir);
+        this.markDirty();
     }
     async activateReview(item) {
         this.reviewAdapter = new ReviewAdapter({
-            dir: item.dir,
+            reviewId: item.id,
             host: this.host,
         });
         try {
@@ -305,7 +380,7 @@ export class InboxController {
         }
         finally {
             this.reviewAdapter = undefined;
-            this.rescan();
+            await this.rescan();
             this.markDirty();
         }
     }
@@ -317,13 +392,21 @@ export class InboxController {
             this.markDirty();
         }
     }
-    reloadSelectedPage() {
-        if (this.adapter === undefined || this.claim === undefined) {
+    /** Re-read the open page and reload it only when its revision actually moved. */
+    async reloadSelectedPage() {
+        const claim = this.claim;
+        if (this.adapter === undefined || claim === undefined) {
             this.markDirty();
             return;
         }
         try {
-            this.adapter.reload(readPageTicket(this.claim.dir));
+            const page = await cliClient().getHumanInboxPage(claim.ticketId);
+            if (this.closed || this.claim !== claim || this.adapter === undefined)
+                return;
+            if (page.revision !== this.openRevision) {
+                this.openRevision = page.revision;
+                this.adapter.reload(pageViewFromDTO(page));
+            }
         }
         catch {
             this.status = 'page could not be read';
@@ -353,7 +436,7 @@ export class InboxController {
             return;
         this.submittingDir = claim.dir;
         try {
-            await resolveTicketPage(claim.dir, responses);
+            await resolveTicketPage(claim.id, responses);
         }
         catch (error) {
             this.submittingDir = undefined;
@@ -363,28 +446,28 @@ export class InboxController {
                 this.markDirty();
                 return;
             }
-            if (failure === 'already_resolved')
-                this.status = safeCanonicalResultStatus(claim.dir);
+            if (failure === 'already_settled')
+                this.status = settledStatus(await this.requestOrNull(claim.id));
             this.leaveDetail(false);
-            this.rescan();
+            await this.rescan();
             this.markDirty();
             return;
         }
         this.submittingDir = undefined;
         this.leaveDetail(false);
-        this.rescan();
+        await this.rescan();
         // A settled page whose row survives its own post-resolve rescan is the
-        // "row won't leave" defect. This records the disk truth at the exact moment
-        // the row should have dropped, so a live recurrence is diagnosable without a
-        // reproduction: was the response published, does the scan still list it, and
-        // was the claim left behind.
+        // "row won't leave" defect. This records the truth at the exact moment the
+        // row should have dropped, so a live recurrence is diagnosable without a
+        // reproduction: did the request reach a terminal state, does the scan still
+        // list it, and was the claim left behind.
         const stillListed = this.items.some((item) => item.dir === claim.dir);
         emitEvent({
             level: stillListed ? 'warn' : 'info',
             event: 'inbox.page.resolved',
             fields: {
-                ticket_id: basename(claim.dir),
-                response_published: existsSync(responsePath(claim.dir)),
+                ticket_id: claim.id,
+                request_settled: isSettled(await this.requestOrNull(claim.id)),
                 still_listed: stillListed,
                 claim_left_behind: existsSync(claimPath(claim.dir)),
             },
@@ -417,6 +500,7 @@ export class InboxController {
         if (release && this.claim !== undefined)
             releaseClaim(this.claim.dir, this.claim.token);
         this.claim = undefined;
+        this.openRevision = undefined;
         this.screen = 'list';
     }
     select(index) {
@@ -453,14 +537,21 @@ export class InboxController {
     focusAvailable(_dir) {
         return this.host.capabilities.canFocusNode;
     }
-    /** Ask the host to bring the selected ticket's node viewer into view. */
+    /** Ask the host to bring the requesting node's viewer into view — the
+     *  conversation that raised this ask. */
     async focusSelectedSource() {
         const item = this.items[this.selectedIndex];
         if (item === undefined || this.focusingSource)
             return;
+        const requesterNodeId = item.source.nodeId;
+        if (requesterNodeId === undefined) {
+            this.status = 'This request was not raised by a canvas node';
+            this.markDirty();
+            return;
+        }
         this.focusingSource = true;
         try {
-            const focused = await this.host.focusNode(ticketIdFor(item.dir));
+            const focused = await this.host.focusNode(requesterNodeId);
             if (focused)
                 this.close();
             else {
@@ -472,31 +563,65 @@ export class InboxController {
             this.focusingSource = false;
         }
     }
-    /** What the selected page actually says, projected once per document and
-     *  kept until the document, the selection, or the pane width changes — the
-     *  projection reads the ticket from disk and evaluates it. */
+    /** What the selected page actually says. Rendering is synchronous and the
+     *  page is a round trip, so the projection is held and a miss schedules the
+     *  fetch, marking the frame dirty when it lands. A width change re-wraps the
+     *  held projection without another read. */
     pagePreviewBody(item, width) {
-        let stamp;
+        const cached = this.preview;
+        if (cached !== undefined && cached.dir === item.dir) {
+            if (this.previewStale)
+                this.schedulePreview(item);
+            if (cached.width === width)
+                return cached.lines;
+            const lines = previewLines(cached.view, width);
+            this.preview = { ...cached, width, lines };
+            return lines;
+        }
+        this.schedulePreview(item);
+        // A failed read says so; an unfetched one is simply not there yet.
+        return this.previewFailed === item.dir ? [`${DIM}page could not be read${RESET}`] : [];
+    }
+    /** One in-flight preview read at a time. A revision that did not move keeps
+     *  the held projection, so activity on an unrelated ticket costs no re-wrap. */
+    schedulePreview(item) {
+        if (this.previewFetching === item.dir)
+            return;
+        this.previewFetching = item.dir;
+        this.previewStale = false;
+        void cliClient().getHumanInboxPage(item.inboxTicketId).then((page) => {
+            if (this.closed || this.previewFetching !== item.dir)
+                return;
+            this.previewFetching = undefined;
+            this.previewFailed = undefined;
+            if (this.preview?.dir === item.dir && this.preview.revision === page.revision)
+                return;
+            const view = pageViewFromDTO(page);
+            const width = this.preview?.width ?? inboxLayout(this.cols, this.rows, this.screen).detailWidth;
+            this.preview = { dir: item.dir, revision: page.revision, view, width, lines: previewLines(view, width) };
+            this.markDirty();
+        }, () => {
+            if (this.closed || this.previewFetching !== item.dir)
+                return;
+            this.previewFetching = undefined;
+            this.previewFailed = item.dir;
+            // Never leave the prior page's body standing under this row's title.
+            if (this.preview?.dir === item.dir)
+                this.preview = undefined;
+            this.markDirty();
+        });
+    }
+    /** The request record is the settlement authority: a settled page publishes
+     *  no file, so a claim would still succeed on its directory. An unreachable
+     *  daemon reads as "not known to be settled" — the settle attempt that
+     *  follows is the one that fails loudly. */
+    async requestOrNull(id) {
         try {
-            stamp = String(statSync(pagePath(item.dir, item.dialect)).mtimeMs);
+            return await cliClient().getHumanRequest(id);
         }
         catch {
-            stamp = 'missing';
+            return undefined;
         }
-        const cached = this.preview;
-        if (cached !== undefined && cached.dir === item.dir && cached.width === width && cached.stamp === stamp)
-            return cached.lines;
-        let lines = [];
-        try {
-            const ticket = readPageTicket(item.dir);
-            const display = ticket.manifest.dialect === 'html'
-                ? projectHtmlDocumentMarkdown(ticket.document)
-                : projectPageDisplayMarkdown(ticket.document, ticket.manifest);
-            lines = pageBodyLines(ticket.manifest, display, Math.min(Math.max(20, width - 4), 100), Math.max(20, width - 4));
-        }
-        catch { /* a half-written or removed ticket previews as its title alone */ }
-        this.preview = { dir: item.dir, width, stamp, lines };
-        return lines;
     }
     /** The read-only preview beside the list. It shows the page's own content,
      *  because `s` settles the selected ticket from here without ever opening
@@ -523,7 +648,7 @@ export class InboxController {
     withStatus(lines) {
         const status = this.cancelConfirmation === undefined
             ? this.status
-            : `cancel “${this.cancelConfirmation.title}”?  y yes · n/Esc no`;
+            : `cancel “${this.cancelConfirmation.item.title}”?  y yes · n/Esc no`;
         if (status === undefined || this.rows < 1)
             return lines;
         const next = [...lines];
@@ -536,50 +661,41 @@ export class InboxController {
         this.options.onDirty();
     }
     watchRoots() {
-        const unsubscribe = watchInboxActivity(this.options.onInboxActivity ?? (() => this.invalidate()));
+        const unsubscribe = watchInboxActivity(this.options.onInboxActivity ?? (() => { void this.invalidate(); }));
         this.watchers.push({ close: unsubscribe });
     }
+    /** The request directory still carries the claim and progress files other
+     *  inboxes write. Its page content lives in the daemon-selected revision,
+     *  which `invalidate` re-reads over the API. */
     watchSelected(dir) {
         this.selectedWatcher?.close();
         try {
-            this.selectedWatcher = watch(dir, (_event, file) => {
-                if (file === 'page.json') {
-                    this.reloadSelectedPage();
-                    return;
-                }
-                this.invalidate();
-            });
+            this.selectedWatcher = watch(dir, () => { void this.invalidate(); });
         }
         catch {
             this.selectedWatcher = undefined;
         }
     }
 }
-function canonicalResultStatus(result) {
-    if (result === null)
-        return 'ticket was already resolved';
-    if (result.kind === 'review')
-        return `ticket was already resolved: ${result.result.approved ? 'approved' : 'review submitted'}`;
-    if (result.kind === 'page')
-        return 'ticket was already resolved: page submitted';
-    return 'ticket was already canceled';
+/** The inbox the daemon lists IS the inbox: visibility, ordering and row
+ *  content all come from the one projection. */
+async function defaultScan() {
+    const { tickets } = await cliClient().listHumanInbox();
+    return tickets.map(inboxRowFromDTO).sort(byNewestFirst);
 }
-/** `readTicketResult` throws on a corrupt result file. In this long-lived TUI
- *  process there is no top-level catch, so a corrupt file must surface as a
- *  status line rather than crash the inbox. */
-function readTicketResultOrNull(dir) {
-    try {
-        return readTicketResult(dir);
-    }
-    catch {
-        return null;
-    }
+function previewLines(view, width) {
+    const display = view.manifest.dialect === 'html'
+        ? projectHtmlDocumentMarkdown(view.document)
+        : projectPageDisplayMarkdown(view.document, view.manifest);
+    return pageBodyLines(view.manifest, display, Math.min(Math.max(20, width - 4), 100), Math.max(20, width - 4));
 }
-function safeCanonicalResultStatus(dir) {
-    try {
-        return canonicalResultStatus(readTicketResult(dir));
-    }
-    catch (error) {
-        return `ticket result is unreadable: ${error instanceof Error ? error.message : String(error)}`;
-    }
+/** A request the daemon no longer reports on is not known to be settled. */
+function isSettled(request) {
+    return request !== undefined && request.state !== 'pending';
+}
+/** Why a second settlement was refused, in the status line's own wording. */
+function settledStatus(request) {
+    if (request?.page === undefined)
+        return 'ticket was already resolved';
+    return settledStatusOf(request.page);
 }

package/dist/clients/inbox/dto-adapt.d.ts

@@ -0,0 +1,28 @@
+import type { InboxPageDTO, InboxTicketSummaryDTO } from '../../api/dto/inbox.js';
+import type { PageManifest, PageResponses } from '../../core/human/page-schema.js';
+import type { PageTicketSummary, ReviewTicketSummary } from '../../core/human/types.js';
+/** A review row as the inbox actually uses it. The review's file and output
+ *  path belong to the review document surface, which reads them from the review
+ *  client — an inbox row never needs either. */
+export type InboxReviewRow = Omit<ReviewTicketSummary, 'file' | 'output'>;
+export type InboxRow = PageTicketSummary | InboxReviewRow;
+/** Everything the page renderer needs, plus the revision token that decides
+ *  whether an already-open page has to reload. */
+export interface InboxPageView {
+    manifest: PageManifest;
+    /** The authored JSX/HTML source the renderer projects — never the compiled host module. */
+    document: string;
+    progress: PageResponses | null;
+    state: 'pending' | 'resolved' | 'canceled' | 'passive';
+    /** Opaque equality token for the SQL-selected revision. Compare, never parse. */
+    revision: string;
+}
+export declare function inboxRowFromDTO(dto: InboxTicketSummaryDTO): InboxRow;
+export declare function pageViewFromDTO(dto: InboxPageDTO): InboxPageView;
+/** The stored one-line answer digest, or undefined when the page was not
+ *  answered. A canceled page carries no digest by construction. */
+export declare function answerDigestOf(dto: InboxPageDTO): string | undefined;
+/** What a surface says when a settled request refuses a second settlement. */
+export declare function settledStatusOf(dto: InboxPageDTO): string;
+/** The row sort every inbox surface shares: newest first, request id breaking ties. */
+export declare function byNewestFirst(a: InboxRow, b: InboxRow): number;