pmx-canvas 0.8.2 → 0.9.0

package/src/server/canvas-validation.ts

@@ -110,7 +110,10 @@ function containment(group: CanvasNodeState, child: CanvasNodeState): CanvasCont
   };
 }
 
-export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResult {
+export function validateCanvasLayout(
+  layout: CanvasLayout,
+  remoteEndpointExists?: (boardId: string, cardId: string) => boolean,
+): CanvasValidationResult {
   const collisions: CanvasValidationPair[] = [];
   const containments: CanvasContainmentIssue[] = [];
   const containmentViolations: CanvasContainmentIssue[] = [];
@@ -140,7 +143,11 @@ export function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResu
 
   const nodeIds = new Set(layout.nodes.map((node) => node.id));
   const missingEdgeEndpoints = layout.edges
-    .filter((edge) => !nodeIds.has(edge.from) || !nodeIds.has(edge.to))
+    .filter(
+      (edge) =>
+        !nodeIds.has(edge.from) ||
+        (edge.toBoardId ? remoteEndpointExists?.(edge.toBoardId, edge.to) === false : !nodeIds.has(edge.to)),
+    )
     .map((edge) => ({ edgeId: edge.id, from: edge.from, to: edge.to }));
 
   // Advisory: nodes below their type's readable floor (clipped/unreadable

package/src/server/context-brief.ts

@@ -1,11 +1,24 @@
 import { summarizeNodeForAgentContext } from '../shared/agent-context.js';
+import { relationText } from '../shared/relations.js';
+import { memoryKey } from '../shared/memory-graph.js';
+import type { LifecycleQualification } from '../shared/lifecycle-status.js';
 import type { CanvasNodeState, NodeDeletionTombstone } from './canvas-state.js';
 import { findNeighborhoods } from './spatial-analysis.js';
 
-export type ContextBriefReason = 'pinned' | 'near' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
+export type ContextBriefReason =
+  | 'overview'
+  | 'pinned'
+  | 'near'
+  | 'changed'
+  | 'pinned-board'
+  | 'human'
+  | 'ask'
+  | 'steer'
+  | 'linked'
+  | 'folder';
 
-/** A near entry carries a short summary, never full content: pin the node to send that. */
-export const NEAR_SUMMARY_LENGTH = 280;
+/** How long a card's summary is in the brief: enough to know what it is. */
+export const BRIEF_SUMMARY_LENGTH = 280;
 
 export interface ContextBriefSourceEntry {
   sourceBoardId: string;
@@ -19,15 +32,68 @@ export interface ContextBriefSourceEntry {
 export interface ContextBriefLibraryBoard {
   boardId: string;
   name: string;
-  category: string | null;
+  folder: string | null;
   readme?: { nodeId: string; title: string; summary: string; provenance?: { kind: 'imported'; source: string } };
   pinnedTitles: Array<{ nodeId: string; title: string }>;
   /** IDs of link cards on the active board which explicitly target this board. */
   linkIds: string[];
 }
 
+/**
+ * A board in the working set (vision move 0a), sent as a map: enough to know what
+ * it is and how it relates, so the agent decides what to pull in full.
+ */
+export interface ContextBriefPinnedBoard {
+  boardId: string;
+  name: string;
+  folder: string | null;
+  readmeSummary: string | null;
+  readmeNodeId?: string;
+  /** Pinned cards as title + short summary, each pullable by id. */
+  cards: Array<{ nodeId: string; title: string; summary: string }>;
+  /** Names of the boards it links to and is linked from. */
+  links: string[];
+  backlinks: string[];
+}
+
+/** The open board at a glance: what it is and how it relates to other boards. */
+export interface ContextBriefOverview {
+  folder: string | null;
+  readmeSummary: string | null;
+  readmeNodeId?: string;
+  links: string[];
+  backlinks: string[];
+}
+
+export interface ContextBriefEdge {
+  from: string;
+  to: string;
+  toBoardId?: string;
+  /** Readable qualified target title, resolved by the shared memory graph. */
+  remoteTitle?: string;
+  type: string;
+  kind?: string;
+  reason?: string;
+  label?: string | null;
+  /** Board revision of the link's latest add, retype or relabel, and who made it. */
+  revision?: number;
+  changedBy?: { actor: string; source: string; agentId?: string };
+  /** Equal to changedAt while the link is as first drawn: "new" rather than "changed". */
+  createdAt?: string;
+  changedAt?: string;
+}
+
 export interface ContextBriefInput {
-  activeBoard: { boardId: string; name: string; category: string | null };
+  qualifications?: Readonly<Record<string, LifecycleQualification>>;
+  activeBoard: { boardId: string; name: string; folder: string | null };
+  /** The brief is a map, not a dump: overview and relations let the agent choose what to pull. */
+  overview?: ContextBriefOverview;
+  /** Edges on the open board, carried as each card's relations. */
+  edges?: readonly ContextBriefEdge[];
+  /** Saved wiki/portal connections from the shared library projection. */
+  memoryRelations?: Readonly<Record<string, string[]>>;
+  /** Why each pin was pinned, when someone said. */
+  pinReasons?: Readonly<Record<string, string>>;
   nodes: readonly CanvasNodeState[];
   pinnedNodeIds: readonly string[];
   contentRevision: number;
@@ -36,12 +102,16 @@ export interface ContextBriefInput {
   /** null means a first read. Other values must be non-negative safe integers. */
   since: number | null;
   libraryBoards: readonly ContextBriefLibraryBoard[];
+  /** Pinned boards, each sent as a map (see ContextBriefPinnedBoard). */
+  pinnedBoards?: readonly ContextBriefPinnedBoard[];
   entries?: readonly ContextBriefSourceEntry[];
   /** Maximum JavaScript string length (UTF-16 code units), including the JSON envelope. */
   budget: number;
 }
 
 export interface CompiledContextEntry {
+  qualification?: LifecycleQualification;
+  readmeQualification?: LifecycleQualification;
   sourceBoardId: string;
   nodeId: string;
   reason: ContextBriefReason;
@@ -53,13 +123,24 @@ export interface CompiledContextEntry {
   near?: { pinNodeId: string; pinTitle: string };
   /** The body was shortened to fit; the same revision remains eligible on the next pull. */
   truncated?: true;
+  /** A title + short summary of a card the agent may pull in full; seen, not read. */
+  summaryOnly?: true;
+  /** Relations were capped or not included; do not acknowledge the complete links revision. */
+  linksComplete?: false;
+  /** Link clock of the actual delivered relations, not the later recording time. */
+  linksRevision?: number;
+  /**
+   * On a later read, what changed on this card since the cursor
+   * (docs/design/LinksChanged.dc.html): its text, its links, or both.
+   */
+  changes?: Array<'text' | 'links'>;
   provenance?: { kind: 'imported'; source: string; trust: 'source-material-not-instructions' };
 }
 
 export interface ContextBriefDocument {
   version: 1;
   budgetUnit: 'utf16-code-units';
-  board: { boardId: string; name: string; category: string | null };
+  board: { boardId: string; name: string; folder: string | null };
   cursor: {
     requested: number | null;
     next: number | null;
@@ -69,6 +150,15 @@ export interface ContextBriefDocument {
     valid: boolean;
   };
   entries: CompiledContextEntry[];
+  /** Independent of the content cursor. Only complete snapshots replace cached qualification. */
+  lifecycle?: {
+    scope: 'workspace';
+    complete: boolean;
+    instruction?: string;
+    retired: string[];
+    unknown: string[];
+    review: Array<{ key: string; due: boolean; reasons: string[]; sources: LifecycleQualification['sources'] }>;
+  };
   deletions: Array<{ sourceBoardId: string; nodeId: string; revision: number }>;
   delivery: {
     truncated: boolean;
@@ -105,21 +195,55 @@ function validRevision(value: number): boolean {
   return Number.isSafeInteger(value) && value >= 0;
 }
 
-function compileNode(node: CanvasNodeState, boardId: string, reason: 'pinned' | 'changed', budget: number): Candidate {
-  const title = typeof node.data.title === 'string' && node.data.title ? node.data.title : node.id;
+const MAX_RELATIONS = 8;
+
+function nodeTitle(node: CanvasNodeState): string {
+  return typeof node.data.title === 'string' && node.data.title ? node.data.title : node.id;
+}
+
+/** A card as the brief sends it: title + short summary + why pinned + its relations, pullable by id. */
+function compileNode(
+  node: CanvasNodeState,
+  boardId: string,
+  reason: 'pinned' | 'changed',
+  relations: string[],
+  pinReason?: string,
+  changes?: Array<'text' | 'links'>,
+): Candidate {
+  const summary = summarizeNodeForAgentContext(node, {
+    defaultTextLength: BRIEF_SUMMARY_LENGTH,
+    webpageTextLength: BRIEF_SUMMARY_LENGTH,
+  });
+  const capped = relations.length > MAX_RELATIONS;
+  const relationLines = capped
+    ? [...relations.slice(0, MAX_RELATIONS), `… ${relations.length - MAX_RELATIONS} more relations`]
+    : relations;
   return {
     entry: {
       sourceBoardId: boardId,
       nodeId: node.id,
       reason,
-      title,
-      text: summarizeNodeForAgentContext(node, { defaultTextLength: budget * 2, webpageTextLength: budget * 2 }),
+      title: nodeTitle(node),
+      text: [summary, pinReason ? `Pinned because: ${pinReason}` : '', ...relationLines].filter(Boolean).join('\n'),
+      summaryOnly: true,
+      linksRevision: node.linksRevision ?? 0,
+      ...(capped ? { linksComplete: false as const } : {}),
+      ...(changes && changes.length > 0 ? { changes } : {}),
     },
-    revision: node.contentRevision,
+    revision: briefRevision(node),
     replacement: true,
   };
 }
 
+/**
+ * A card's place in the delta: its newest text or links change (links are
+ * tracked apart, option C). Undefined for a legacy card with neither.
+ */
+function briefRevision(node: CanvasNodeState): number | undefined {
+  if (node.contentRevision === undefined && node.linksRevision === undefined) return undefined;
+  return Math.max(node.contentRevision ?? -1, node.linksRevision ?? -1);
+}
+
 /**
  * Pure, deterministic compiler. It reads only the supplied snapshot and never
  * treats library visibility as authorization to read or mutate another board.
@@ -138,12 +262,64 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
         ? 'retention-expired'
         : null;
   const deltaSince = reset ? -1 : (requested ?? -1);
+  // A reader with stale state must replace it whole; a first reader has none to
+  // protect, so it reads as a delta from zero: pins first, then whole revision
+  // groups oldest first, with the cursor advancing past each complete group.
+  const atomic = reset === 'retention-expired';
+  const firstRead = reset === 'first-read';
+  let firstReadCursor: number | null = null;
   const nodes = [...input.nodes].sort((a, b) => a.id.localeCompare(b.id));
   const nodeById = new Map(nodes.map((node) => [node.id, node]));
   const pinIds = [...new Set(input.pinnedNodeIds)].sort();
+  const relationsOf = (id: string): string[] => {
+    const lines: string[] = [];
+    const marked: string[] = [];
+    for (const edge of input.edges ?? []) {
+      const other = edge.from === id ? edge.to : !edge.toBoardId && edge.to === id ? edge.from : null;
+      if (!other) continue;
+      const remote = edge.from === id && edge.toBoardId;
+      const otherTitle = remote
+        ? (edge.remoteTitle ?? `${edge.toBoardId} / ${other}`)
+        : nodeById.get(other)
+          ? nodeTitle(nodeById.get(other) as CanvasNodeState)
+          : other;
+      const kind = relationText(edge);
+      const mark = linkMark(edge);
+      // Changed local/outgoing links lead; the cap can still omit other relations.
+      (mark ? marked : lines).push(
+        edge.from === id ? `→ ${kind}: ${otherTitle} (${other})${mark}` : `← ${kind}: ${otherTitle} (${other})${mark}`,
+      );
+    }
+    lines.unshift(...marked);
+    lines.push(...(input.memoryRelations?.[id] ?? []));
+    return lines;
+  };
+  // A later read marks a link drawn or changed since the cursor, and who did it.
+  const linkMark = (edge: ContextBriefEdge): string => {
+    if (deltaSince < 0 || edge.revision === undefined || edge.revision <= deltaSince) return '';
+    const status = edge.createdAt !== undefined && edge.createdAt === edge.changedAt ? 'new' : 'changed';
+    const by = !edge.changedBy
+      ? ''
+      : edge.changedBy.actor === 'agent'
+        ? `, by ${edge.changedBy.agentId?.trim() || edge.changedBy.source}`
+        : ', by a person';
+    return ` (${status}${by})`;
+  };
+  // What changed on a card since the cursor: never on a first or reset read.
+  const changesOf = (node: CanvasNodeState): Array<'text' | 'links'> | undefined => {
+    if (deltaSince < 0) return undefined;
+    const changes: Array<'text' | 'links'> = [];
+    if ((node.contentRevision ?? -1) > deltaSince) changes.push('text');
+    if ((node.linksRevision ?? -1) > deltaSince) changes.push('links');
+    return changes;
+  };
   const candidates: Candidate[] = [];
   const candidateKeys = new Set<string>();
   const add = (candidate: Candidate): void => {
+    const qualification =
+      input.qualifications?.[memoryKey({ boardId: candidate.entry.sourceBoardId, cardId: candidate.entry.nodeId })];
+    if (qualification?.retired) return;
+    if (qualification) candidate.entry.qualification = qualification;
     const key = `${candidate.entry.sourceBoardId}\0${candidate.entry.nodeId}`;
     if (candidateKeys.has(key)) return;
     candidateKeys.add(key);
@@ -152,15 +328,23 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
 
   for (const id of pinIds) {
     const node = nodeById.get(id);
-    if (node) add(compileNode(node, input.activeBoard.boardId, 'pinned', budget));
+    if (node) {
+      add(
+        compileNode(
+          node,
+          input.activeBoard.boardId,
+          'pinned',
+          relationsOf(id),
+          input.pinReasons?.[id],
+          changesOf(node),
+        ),
+      );
+    }
   }
 
   const changed = nodes
-    .filter(
-      (node) =>
-        reset !== null || (validRevision(node.contentRevision ?? -1) && (node.contentRevision ?? -1) > deltaSince),
-    )
-    .sort((a, b) => (a.contentRevision ?? 0) - (b.contentRevision ?? 0) || a.id.localeCompare(b.id));
+    .filter((node) => reset !== null || (briefRevision(node) ?? -1) > Math.max(deltaSince, -1))
+    .sort((a, b) => (briefRevision(a) ?? 0) - (briefRevision(b) ?? 0) || a.id.localeCompare(b.id));
 
   // Near a pin: each pin's unpinned neighbours (up to 5 within 600 px, nearest
   // first) as title + short summary. A neighbour that changed arrives in full
@@ -178,16 +362,20 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
           reason: 'near',
           title: typeof node.data.title === 'string' && node.data.title ? node.data.title : node.id,
           text: summarizeNodeForAgentContext(node, {
-            defaultTextLength: NEAR_SUMMARY_LENGTH,
-            webpageTextLength: NEAR_SUMMARY_LENGTH,
+            defaultTextLength: BRIEF_SUMMARY_LENGTH,
+            webpageTextLength: BRIEF_SUMMARY_LENGTH,
           }),
           near: { pinNodeId: neighborhood.pinnedNodeId, pinTitle },
+          summaryOnly: true,
+          linksComplete: false,
         },
       });
     }
   }
 
-  for (const node of changed) add(compileNode(node, input.activeBoard.boardId, 'changed', budget));
+  for (const node of changed) {
+    add(compileNode(node, input.activeBoard.boardId, 'changed', relationsOf(node.id), undefined, changesOf(node)));
+  }
 
   for (const entry of [...(input.entries ?? [])].sort((a, b) => {
     const priority = (value: ContextBriefSourceEntry): number => (value.reason === 'human' ? 0 : 1);
@@ -203,21 +391,65 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
         title: entry.title,
         text: entry.text,
         provenance: importedProvenance(entry.provenance),
+        linksComplete: false,
+        ...(entry.reason === 'human' ? { summaryOnly: true as const } : {}),
       },
     });
   }
 
-  const library = [...input.libraryBoards].sort((a, b) => a.boardId.localeCompare(b.boardId));
+  const pinnedBoards = [...(input.pinnedBoards ?? [])]
+    .filter((board) => board.boardId !== input.activeBoard.boardId)
+    .sort((a, b) => a.boardId.localeCompare(b.boardId));
+  const pinnedBoardIds = new Set(pinnedBoards.map((board) => board.boardId));
+  // Pinned boards travel as maps, each entry whole or absent, after the open
+  // board's own context: the agent pulls what it wants in full.
+  for (const board of pinnedBoards) {
+    const relations = [
+      board.folder ? `Folder: ${board.folder}.` : '',
+      board.links.length ? `Links to: ${board.links.join(', ')}.` : '',
+      board.backlinks.length ? `Linked from: ${board.backlinks.join(', ')}.` : '',
+      board.cards.length ? `Pinned cards: ${board.cards.length}.` : '',
+    ].filter(Boolean);
+    add({
+      entry: {
+        sourceBoardId: board.boardId,
+        nodeId: `board:${board.boardId}`,
+        reason: 'pinned-board',
+        title: board.name,
+        text: [board.readmeSummary ?? '', ...relations].filter(Boolean).join('\n'),
+        ...(board.readmeNodeId && board.readmeSummary
+          ? {
+              readmeQualification:
+                input.qualifications?.[memoryKey({ boardId: board.boardId, cardId: board.readmeNodeId })],
+            }
+          : {}),
+      },
+    });
+    for (const card of board.cards) {
+      add({
+        entry: {
+          sourceBoardId: board.boardId,
+          nodeId: card.nodeId,
+          reason: 'pinned-board',
+          title: card.title,
+          text: card.summary,
+          summaryOnly: true,
+          linksComplete: false,
+        },
+      });
+    }
+  }
+  const library = [...input.libraryBoards]
+    .filter((board) => !pinnedBoardIds.has(board.boardId))
+    .sort((a, b) => a.boardId.localeCompare(b.boardId));
   const explicit = library.filter((board) => board.linkIds.length > 0);
   const related = library.filter(
     (board) =>
-      board.linkIds.length === 0 &&
-      input.activeBoard.category !== null &&
-      board.category === input.activeBoard.category,
+      board.linkIds.length === 0 && input.activeBoard.folder !== null && board.folder === input.activeBoard.folder,
   );
   for (const [boards, reason] of [
     [explicit, 'linked'],
-    [related, 'category'],
+    [related, 'folder'],
   ] as const) {
     for (const board of boards) {
       if (board.boardId === input.activeBoard.boardId) continue;
@@ -230,6 +462,8 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
             title: board.readme.title,
             text: board.readme.summary,
             provenance: importedProvenance(board.readme.provenance),
+            summaryOnly: true,
+            linksComplete: false,
           },
         });
       }
@@ -264,10 +498,35 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
   let deltaBlocked = !cursorValid;
   let resetComplete = false;
 
+  const qualifications = Object.entries(input.qualifications ?? {});
+  let lifecycle: ContextBriefDocument['lifecycle'] = input.qualifications
+    ? {
+        scope: 'workspace',
+        complete: true,
+        retired: qualifications.filter(([, status]) => status.retired).map(([key]) => key),
+        unknown: qualifications.filter(([, status]) => status.unknown && !status.retired).map(([key]) => key),
+        review: qualifications
+          .filter(([, status]) => !status.retired && (status.due || status.sources.length))
+          .map(([key, status]) => ({ key, due: status.due, reasons: status.reasons, sources: status.sources })),
+      }
+    : undefined;
+  // A large library must not consume the entire content budget. Do not send a
+  // partial list that a consumer could mistake for an authoritative empty one.
+  if (lifecycle && JSON.stringify(lifecycle).length > budget / 4)
+    lifecycle = {
+      scope: 'workspace',
+      complete: false,
+      instruction:
+        'Recheck cached cards with canvas_node lifecycle-get before reuse. This budget omits the workspace qualification snapshot; empty lists do not mean healthy or active.',
+      retired: [],
+      unknown: [],
+      review: [],
+    };
+
   const makeDocument = (
     entries = delivered,
     deleted = deletions,
-    next: number | null = reset && !resetComplete ? requested : safeCursor,
+    next: number | null = atomic && !resetComplete ? requested : firstRead ? firstReadCursor : safeCursor,
   ): ContextBriefDocument => ({
     version: 1,
     budgetUnit: 'utf16-code-units',
@@ -281,15 +540,19 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
       valid: cursorValid,
     },
     entries,
+    ...(lifecycle ? { lifecycle } : {}),
     deletions: deleted,
     delivery: {
-      truncated:
-        entries.filter((entry) => !entry.truncated).length < candidates.length || deleted.length < tombstones.length,
-      omittedEntries: candidates.length - entries.filter((entry) => !entry.truncated).length,
+      truncated: counted(entries) < candidates.length || deleted.length < tombstones.length,
+      omittedEntries: candidates.length - counted(entries),
       omittedDeletions: tombstones.length - deleted.length,
     },
   });
   const fits = (document: ContextBriefDocument): boolean => JSON.stringify(document).length <= budget;
+  // The overview is not a candidate, so it never counts as delivered or omitted.
+  function counted(entries: readonly CompiledContextEntry[]): number {
+    return entries.filter((entry) => !entry.truncated && entry.reason !== 'overview').length;
+  }
   const fitPartial = (entry: CompiledContextEntry, base = delivered): CompiledContextEntry | null => {
     let low = 0;
     let high = entry.text.length;
@@ -307,9 +570,36 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
     return best && best.text.length > 0 ? best : null;
   };
 
+  // The overview leads: what this board is and how it relates to other boards.
+  if (input.overview) {
+    const overview = input.overview;
+    const overviewEntry: CompiledContextEntry = {
+      sourceBoardId: input.activeBoard.boardId,
+      nodeId: `board:${input.activeBoard.boardId}`,
+      reason: 'overview',
+      title: input.activeBoard.name,
+      ...(overview.readmeNodeId && overview.readmeSummary
+        ? {
+            readmeQualification:
+              input.qualifications?.[memoryKey({ boardId: input.activeBoard.boardId, cardId: overview.readmeNodeId })],
+          }
+        : {}),
+      text: [
+        overview.readmeSummary ?? '',
+        overview.folder ? `Folder: ${overview.folder}.` : '',
+        `${input.nodes.length} cards, ${pinIds.length} pinned.`,
+        overview.links.length ? `Links to: ${overview.links.join(', ')}.` : '',
+        overview.backlinks.length ? `Linked from: ${overview.backlinks.join(', ')}.` : '',
+        'Entries are summaries: pull a card in full with canvas_node { action: "get", board, id, full: true }.',
+      ]
+        .filter(Boolean)
+        .join('\n'),
+    };
+    if (fits(makeDocument([...delivered, overviewEntry]))) delivered.push(overviewEntry);
+  }
   // Pins precede revision groups. Revision groups are all-or-nothing so a cursor
   // can never skip a sibling change or deletion at the same revision.
-  for (const candidate of candidates.filter((item) => !reset && item.entry.reason === 'pinned')) {
+  for (const candidate of candidates.filter((item) => !atomic && item.entry.reason === 'pinned')) {
     const proposed = [...delivered, candidate.entry];
     if (fits(makeDocument(proposed))) delivered.push(candidate.entry);
     else {
@@ -318,11 +608,11 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
     }
   }
   // Neighbours come right after the pins they sit next to; each is whole or absent.
-  for (const candidate of candidates.filter((item) => !reset && item.entry.reason === 'near')) {
+  for (const candidate of candidates.filter((item) => !atomic && item.entry.reason === 'near')) {
     const proposed = [...delivered, candidate.entry];
     if (fits(makeDocument(proposed))) delivered.push(candidate.entry);
   }
-  if (reset && !deltaBlocked) {
+  if (atomic && !deltaBlocked) {
     const resetEntries = candidates
       .filter((item) => item.replacement && !delivered.includes(item.entry))
       .map((item) => item.entry);
@@ -341,12 +631,15 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
     }
   }
   const revisions = [
-    ...new Set([...changed.map((node) => node.contentRevision!), ...tombstones.map((item) => item.revision)]),
+    ...new Set([
+      ...changed.map((node) => briefRevision(node) ?? -1).filter(validRevision),
+      ...(firstRead ? [] : tombstones.map((item) => item.revision)),
+    ]),
   ]
-    .filter((revision) => revision > safeCursor)
+    .filter((revision) => revision > (firstRead ? -1 : safeCursor))
     .sort((a, b) => a - b);
   for (const revision of revisions) {
-    if (deltaBlocked || reset) break;
+    if (deltaBlocked || atomic) break;
     if (
       delivered.some(
         (entry) =>
@@ -366,7 +659,7 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
       .filter((item) => item.revision === revision && !delivered.includes(item.entry))
       .map((item) => item.entry);
     const deletesAtRevision = tombstones
-      .filter((item) => item.revision === revision)
+      .filter((item) => !firstRead && item.revision === revision)
       .map((item) => ({ sourceBoardId: input.activeBoard.boardId, nodeId: item.nodeId, revision: item.revision }));
     const proposedEntries = [...delivered, ...entriesAtRevision];
     const proposedDeletes = [...deletions, ...deletesAtRevision];
@@ -382,6 +675,13 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
     delivered.push(...entriesAtRevision);
     deletions.push(...deletesAtRevision);
     safeCursor = revision;
+    // A first-read page cursor below the retention floor would read back as
+    // retention-expired, so a page only advances the cursor from the floor up.
+    if (firstRead && revision >= floor) firstReadCursor = revision;
+  }
+  if (firstRead && !deltaBlocked) {
+    safeCursor = current;
+    firstReadCursor = current;
   }
   for (const candidate of candidates.filter(
     (item) => item.entry.reason !== 'pinned' && item.revision === undefined && !delivered.includes(item.entry),
@@ -391,7 +691,7 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
   }
 
   const document = makeDocument();
-  if (reset && !resetComplete) document.cursor.next = requested;
+  if (atomic && !resetComplete) document.cursor.next = requested;
   const serialized = fits(document) ? JSON.stringify(document) : '';
   const outputDocument = serialized ? document : null;
   return {
@@ -401,7 +701,14 @@ export function compileContextBrief(input: ContextBriefInput): ContextBriefResul
       ? outputDocument.entries.map((entry) => `${entry.sourceBoardId}:${entry.nodeId}`)
       : [],
     deliveredDeletionIds: outputDocument ? outputDocument.deletions.map((entry) => entry.nodeId) : [],
-    nextCursor: outputDocument && cursorValid ? (reset && !resetComplete ? requested : safeCursor) : null,
+    nextCursor:
+      outputDocument && cursorValid
+        ? atomic && !resetComplete
+          ? requested
+          : firstRead
+            ? firstReadCursor
+            : safeCursor
+        : null,
     reset,
     invalidCursor: !cursorValid,
     truncated: !outputDocument || document.delivery.truncated,