pmx-canvas 0.8.0 → 0.9.0

package/src/server/context-reads.ts

@@ -7,6 +7,8 @@
  */
 import type { Database } from 'bun:sqlite';
 import { randomUUID } from 'node:crypto';
+import type { MemoryGraph } from '../shared/memory-graph.js';
+import type { CompiledContextEntry } from './context-brief.js';
 
 export const CONTEXT_READ_RETENTION = 5000;
 const CONTEXT_READ_DEFAULT_LIMIT = 50;
@@ -17,6 +19,7 @@ export type ContextReadChannel = (typeof CONTEXT_READ_CHANNELS)[number];
 
 /** Registry reads that hand an agent canvas context; recorded in executeOperation. */
 export const CONTEXT_READ_OPS = new Set([
+  'node.get',
   'pinned-context.get',
   'ax.context.get',
   'ax.get',
@@ -24,6 +27,7 @@ export const CONTEXT_READ_OPS = new Set([
   'spatial.get',
   'layout.get',
   'context.get',
+  'memory-graph.get',
 ]);
 
 export interface ContextRead {
@@ -39,16 +43,22 @@ export interface ContextRead {
   deliveredNodeIds: string[];
   /** Every node on the read board whose content was delivered, with its content revision at read time. */
   readNodes: Record<string, number>;
+  /** Every node on the read board that arrived with its relations (summaries count), with its links revision then. */
+  seenLinks: Record<string, number>;
   bytes: number;
   /** The board open when the read happened (null on Home). */
   boardId: string | null;
 }
 
-export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId' | 'readNodes'> & {
+export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId' | 'readNodes' | 'seenLinks'> & {
   /** Explicit read target, captured before asynchronous formatting/proxy work. */
   boardId?: string | null;
   /** Ids of every serialized node in what the reader received; the server keeps those on the board. */
   readNodeIds?: string[];
+  /** Ids of every node that arrived, summaries included; defaults to readNodeIds. */
+  seenNodeIds?: string[];
+  /** Exact link clocks captured in the delivered projection, before asynchronous transport work. */
+  seenLinkRevisions?: Record<string, number>;
 };
 
 /** One node's read state on a board: the latest agent read that delivered its content. */
@@ -77,10 +87,13 @@ export interface ContextReadConsumerSummary {
  * `nodeId` with its text) in what the reader received. A bare id list, a
  * title, or a clipped-off node does not count — the agent got the node's
  * name, not its content. Non-node ids (edges, intents) are dropped by the
- * caller against the board's nodes.
+ * caller against the board's nodes. A summary is "seen", not "read": `read`
+ * holds only nodes pulled in full and `reached` adds the summaries. Content
+ * delivery alone never establishes that the card's relations were delivered.
  */
-export function deliveredIds(payloadText: string): Set<string> {
-  const delivered = new Set<string>();
+export function deliveredIds(payloadText: string): { read: Set<string>; reached: Set<string> } {
+  const read = new Set<string>();
+  const reached = new Set<string>();
   const objectStarts: number[] = [];
   let inString = false;
   let escaped = false;
@@ -102,20 +115,21 @@ export function deliveredIds(payloadText: string): Set<string> {
       if (start === undefined) continue;
       try {
         const value = JSON.parse(payloadText.slice(start, index + 1)) as unknown;
-        if (
-          typeof value === 'object' &&
-          value !== null &&
-          !Array.isArray(value) &&
-          (typeof (value as { id?: unknown }).id === 'string' ||
-            (typeof (value as { nodeId?: unknown }).nodeId === 'string' &&
-              (value as { titleOnly?: unknown }).titleOnly !== true &&
-              typeof (value as { text?: unknown }).text === 'string'))
-        ) {
-          delivered.add(
-            typeof (value as { id?: unknown }).id === 'string'
-              ? (value as { id: string }).id
-              : (value as { nodeId: string }).nodeId,
-          );
+        if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+          const item = value as {
+            id?: unknown;
+            nodeId?: unknown;
+            titleOnly?: unknown;
+            summaryOnly?: unknown;
+            text?: unknown;
+          };
+          if (typeof item.id === 'string') {
+            read.add(item.id);
+            reached.add(item.id);
+          } else if (typeof item.nodeId === 'string' && item.titleOnly !== true && typeof item.text === 'string') {
+            reached.add(item.nodeId);
+            if (item.summaryOnly !== true) read.add(item.nodeId);
+          }
         }
       } catch {
         // An inner object may be complete even when its containing object was clipped.
@@ -123,13 +137,27 @@ export function deliveredIds(payloadText: string): Set<string> {
     }
   }
 
-  return delivered;
+  return { read, reached };
 }
 
-/** Pinned nodes whose content is in what the reader received (see `deliveredIds`). */
-export function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string): string[] {
-  const delivered = deliveredIds(payloadText);
-  return pinnedNodeIds.filter((id) => delivered.has(id));
+/** Only complete, board-qualified brief relations can acknowledge their captured clock. */
+function briefLinkRevisions(entries: Partial<CompiledContextEntry>[], boardId: string): Record<string, number> {
+  return Object.fromEntries(
+    entries.flatMap((entry) =>
+      entry.sourceBoardId === boardId &&
+      typeof entry.nodeId === 'string' &&
+      !entry.nodeId.startsWith('board:') &&
+      typeof entry.text === 'string' &&
+      entry.titleOnly !== true &&
+      entry.truncated !== true &&
+      entry.linksComplete !== false &&
+      typeof entry.linksRevision === 'number' &&
+      Number.isSafeInteger(entry.linksRevision) &&
+      entry.linksRevision >= 0
+        ? [[entry.nodeId, entry.linksRevision]]
+        : [],
+    ),
+  );
 }
 
 export function contextReadFromPayload(
@@ -137,15 +165,104 @@ export function contextReadFromPayload(
   payload: unknown,
 ): ContextReadInput {
   const text = typeof payload === 'string' ? payload : (JSON.stringify(payload) ?? '');
-  const delivered = deliveredIds(text);
+  let delivered = text;
+  let seenLinkRevisions: Record<string, number> = {};
+  try {
+    const document = JSON.parse(text) as {
+      board?: { boardId?: string };
+      entries?: Partial<CompiledContextEntry>[];
+    };
+    if (document.board?.boardId && Array.isArray(document.entries)) {
+      // A brief carries several boards. Bare IDs from a remote README must
+      // never acknowledge a same-ID card on the open board.
+      const entries = document.entries.filter(
+        (entry) => entry.sourceBoardId === (base.boardId ?? document.board?.boardId),
+      );
+      delivered = JSON.stringify(entries);
+      seenLinkRevisions = briefLinkRevisions(entries, base.boardId ?? document.board.boardId);
+    }
+  } catch {
+    // Non-JSON and clipped payloads keep the complete-object delivery scanner.
+  }
+  // Delivery (did the pins reach the agent?) counts summaries; read marks do not.
+  const { read, reached } = deliveredIds(delivered);
   return {
     ...base,
-    deliveredNodeIds: base.pinnedNodeIds.filter((id) => delivered.has(id)),
-    readNodeIds: [...delivered],
+    deliveredNodeIds: base.pinnedNodeIds.filter((id) => reached.has(id)),
+    readNodeIds: [...read],
+    seenNodeIds: Object.keys(seenLinkRevisions),
+    seenLinkRevisions,
     bytes: Buffer.byteLength(text, 'utf-8'),
   };
 }
 
+/**
+ * Reads a `context.get` brief made on pinned boards (vision move 0a): one per
+ * pinned board whose map arrived, so the board shows as read. Its cards came as
+ * summaries, which mark nothing read until the agent pulls them; only summaries
+ * with complete, unclipped relations count as links seen on that board.
+ */
+export function pinnedBoardReads(
+  base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes' | 'readNodeIds' | 'pinnedNodeIds' | 'boardId'>,
+  payload: unknown,
+): ContextReadInput[] {
+  let document: unknown = payload;
+  if (typeof payload === 'string') {
+    try {
+      document = JSON.parse(payload);
+    } catch {
+      return [];
+    }
+  }
+  const entries = (document as { entries?: Partial<CompiledContextEntry>[] } | null)?.entries ?? [];
+  return entries
+    .filter(
+      (entry) =>
+        entry.reason === 'pinned-board' &&
+        typeof entry.sourceBoardId === 'string' &&
+        entry.nodeId === `board:${entry.sourceBoardId}`,
+    )
+    .map((entry) => {
+      const boardId = entry.sourceBoardId as string;
+      const seenLinkRevisions = briefLinkRevisions(entries, boardId);
+      return {
+        ...base,
+        boardId,
+        pinnedNodeIds: [],
+        deliveredNodeIds: [],
+        readNodeIds: [],
+        seenNodeIds: Object.keys(seenLinkRevisions),
+        seenLinkRevisions,
+        bytes: Buffer.byteLength(JSON.stringify(entry), 'utf-8'),
+      };
+    });
+}
+
+/** Graph summaries are seen on their own boards, never full-content reads or a board switch. */
+export function graphReads(
+  base: Pick<ContextReadInput, 'channel' | 'resource' | 'source' | 'consumer' | 'agentId'>,
+  graph: MemoryGraph,
+): ContextReadInput[] {
+  const boards = new Set(graph.nodes.map((node) => node.boardId));
+  return [...boards].map((boardId) => {
+    const nodes = graph.nodes.filter((node) => node.boardId === boardId);
+    return {
+      ...base,
+      boardId,
+      pinnedNodeIds: [],
+      deliveredNodeIds: [],
+      readNodeIds: [],
+      seenNodeIds: nodes.flatMap((node) => (node.cardId && node.linksComplete !== false ? [node.cardId] : [])),
+      seenLinkRevisions: Object.fromEntries(
+        nodes.flatMap((node) =>
+          node.cardId && typeof node.linksRevision === 'number' ? [[node.cardId, node.linksRevision]] : [],
+        ),
+      ),
+      bytes: Buffer.byteLength(JSON.stringify(nodes), 'utf-8'),
+    };
+  });
+}
+
 export const CONTEXT_READS_SCHEMA_SQL = `
   CREATE TABLE IF NOT EXISTS context_reads (
     seq INTEGER PRIMARY KEY AUTOINCREMENT,
@@ -160,7 +277,8 @@ export const CONTEXT_READS_SCHEMA_SQL = `
     delivered_node_ids TEXT NOT NULL DEFAULT '[]',
     bytes INTEGER NOT NULL DEFAULT 0,
     board_id TEXT,
-    read_nodes TEXT NOT NULL DEFAULT '{}'
+    read_nodes TEXT NOT NULL DEFAULT '{}',
+    seen_links TEXT NOT NULL DEFAULT '{}'
   );
 `;
 
@@ -169,11 +287,12 @@ export function appendContextReadToDB(
   input: ContextReadInput,
   boardId: string | null,
   readNodes: Record<string, number> = {},
+  seenLinks: Record<string, number> = {},
 ): ContextRead {
   const id = `read-${randomUUID()}`;
   const at = new Date().toISOString();
   db.run(
-    'INSERT INTO context_reads (id, at, channel, resource, source, consumer, agent_id, pinned_node_ids, delivered_node_ids, bytes, board_id, read_nodes) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    'INSERT INTO context_reads (id, at, channel, resource, source, consumer, agent_id, pinned_node_ids, delivered_node_ids, bytes, board_id, read_nodes, seen_links) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
     [
       id,
       at,
@@ -187,12 +306,13 @@ export function appendContextReadToDB(
       input.bytes,
       boardId,
       JSON.stringify(readNodes),
+      JSON.stringify(seenLinks),
     ],
   );
   const seq = Number(db.query<{ seq: number }, []>('SELECT last_insert_rowid() AS seq').get()?.seq ?? 0);
   db.run('DELETE FROM context_reads WHERE seq <= ?', [seq - CONTEXT_READ_RETENTION]);
-  const { readNodeIds: _readNodeIds, ...record } = input;
-  return { ...record, seq, id, at, boardId, readNodes };
+  const { readNodeIds: _readNodeIds, seenNodeIds: _seenNodeIds, ...record } = input;
+  return { ...record, seq, id, at, boardId, readNodes, seenLinks };
 }
 
 interface ContextReadRow {
@@ -209,6 +329,7 @@ interface ContextReadRow {
   bytes: number;
   board_id: string | null;
   read_nodes: string;
+  seen_links: string;
 }
 
 function rowToContextRead(row: ContextReadRow): ContextRead {
@@ -224,6 +345,7 @@ function rowToContextRead(row: ContextReadRow): ContextRead {
     pinnedNodeIds: JSON.parse(row.pinned_node_ids) as string[],
     deliveredNodeIds: JSON.parse(row.delivered_node_ids) as string[],
     readNodes: JSON.parse(row.read_nodes) as Record<string, number>,
+    seenLinks: JSON.parse(row.seen_links) as Record<string, number>,
     bytes: row.bytes,
     boardId: row.board_id,
   };
@@ -254,6 +376,33 @@ export function loadNodeReadStatusFromDB(db: Database, boardId: string): NodeRea
   return [...status.values()];
 }
 
+/** The latest agent read on a board, of any kind (a brief, a pinned-board map, a pull), or null. */
+export function loadBoardLastReadFromDB(
+  db: Database,
+  boardId: string,
+): { lastReadAt: string; lastReadBy: string } | null {
+  const row = db
+    .query<ContextReadRow, [string]>('SELECT * FROM context_reads WHERE board_id = ? ORDER BY seq DESC LIMIT 1')
+    .get(boardId);
+  if (!row) return null;
+  const read = rowToContextRead(row);
+  return { lastReadAt: read.at, lastReadBy: read.consumer ?? read.agentId ?? read.source };
+}
+
+/** Per node on a board, the newest links revision any agent read has carried (connection marks). */
+export function loadSeenLinksFromDB(db: Database, boardId: string): Record<string, number> {
+  const rows = db
+    .query<{ seen_links: string }, [string]>('SELECT seen_links FROM context_reads WHERE board_id = ?')
+    .all(boardId);
+  const seen: Record<string, number> = {};
+  for (const row of rows) {
+    for (const [nodeId, revision] of Object.entries(JSON.parse(row.seen_links) as Record<string, number>)) {
+      if (revision > (seen[nodeId] ?? -1)) seen[nodeId] = revision;
+    }
+  }
+  return seen;
+}
+
 /** Every node on a board whose content an agent read at or after `since` (ISO). */
 export function loadReadNodeIdsSince(db: Database, boardId: string, since: string): string[] {
   const rows = db