pmx-canvas 0.6.4 → 0.7.0

package/dist/types/server/canvas-db.d.ts

@@ -5,12 +5,14 @@
  * WAL-mode persistence. Replaces the previous JSON file-based approach.
  */
 import { Database } from 'bun:sqlite';
+import { type Tour } from '../shared/tour.js';
 import { type CanvasThemeName } from '../shared/themes.js';
 import type { CanvasAnnotation, CanvasEdge, CanvasNodeState, CanvasSnapshot, CanvasSnapshotListOptions, ViewportState } from './canvas-state.js';
 import { type PmxAxState, type PmxAxEvent, type PmxAxEvidence, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
 export type CanvasTheme = CanvasThemeName;
 export declare function normalizeCanvasTheme(value: unknown, fallback?: CanvasTheme): CanvasTheme;
 export interface PersistedCanvasState {
+    tour?: Tour;
     version: number;
     theme?: CanvasTheme;
     viewport: ViewportState;
@@ -19,8 +21,27 @@ export interface PersistedCanvasState {
     annotations?: CanvasAnnotation[];
     contextPins: string[];
     ax?: PmxAxState;
+    revisionState?: PersistedRevisionState;
 }
-export declare function openCanvasDb(dbPath: string): Database;
+export interface PersistedRevisionState {
+    revision: number;
+    floor: number;
+    tombstones: Array<{
+        nodeId: string;
+        revision: number;
+        deletedBy: import('./attribution.js').ActorAttribution;
+    }>;
+}
+/** Durable, delivery-based context cursor. This is separate from the bounded diagnostic read log. */
+export declare function readContextBriefCursor(db: Database, boardId: string, consumer: string): number | null;
+/** Monotonic update prevents a stale concurrent response from regressing a consumer. */
+export declare function advanceContextBriefCursor(db: Database, boardId: string, consumer: string, revision: number): void;
+export interface OpenCanvasDbOptions {
+    /** Name for the board a pre-boards (0.6.x) database migrates into. */
+    migratedBoardName?: string;
+}
+export declare function openCanvasDb(dbPath: string, options?: OpenCanvasDbOptions): Database;
+export declare function createBoardId(): string;
 export declare function checkpointCanvasDb(db: Database): void;
 /**
  * Delete blob rows nothing references any more. Blobs are content-addressed and
@@ -37,17 +58,52 @@ export declare function checkpointCanvasDb(db: Database): void;
  */
 export declare function gcBlobsInDB(db: Database): number;
 export declare function finalizeCanvasDbForClose(db: Database): void;
-export declare function saveStateToDB(db: Database, state: PersistedCanvasState): void;
-/** Check if the DB has been populated with canvas state at least once. */
-export declare function isDbPopulated(db: Database): boolean;
-export declare function loadStateFromDB(db: Database): PersistedCanvasState | null;
-export declare function saveSnapshotToDB(db: Database, snapshot: CanvasSnapshot, state: PersistedCanvasState): void;
-export declare function loadSnapshotFromDB(db: Database, idOrName: string): {
+/** The theme is workspace-wide: it is saved even while no board is open. */
+export declare function saveThemeToDB(db: Database, theme: CanvasTheme | undefined): void;
+export declare function readThemeFromDB(db: Database): CanvasTheme | undefined;
+/** Saves one board's state; every other board's rows are untouched. */
+export declare function saveStateToDB(db: Database, boardId: string, state: PersistedCanvasState): void;
+/** Loads one board (the open board when `boardId` is omitted); null when there is no such board. */
+export declare function loadStateFromDB(db: Database, boardId?: string): PersistedCanvasState | null;
+export interface CanvasBoard {
+    id: string;
+    name: string;
+    /** A human-chosen shelf on Home ("Planning", "Research"); null is uncategorized. */
+    category: string | null;
+    createdAt: string;
+    lastOpenedAt: string | null;
+    nodeCount: number;
+    /** Markdown node used as this board's introduction. */
+    readmeNodeId: string | null;
+}
+/** Most recently opened first, then never-opened boards, newest first. */
+export declare function listBoardsFromDB(db: Database): CanvasBoard[];
+export declare function getBoardFromDB(db: Database, id: string): CanvasBoard | null;
+export declare function createBoardInDB(db: Database, name: string, category?: string | null): CanvasBoard;
+/** Rename and/or re-shelve a board; `category: null` removes it from its category. */
+export declare function updateBoardInDB(db: Database, id: string, patch: {
+    name?: string;
+    category?: string | null;
+    readmeNodeId?: string | null;
+}): boolean;
+/** Create and populate an inactive board as one SQLite transaction. */
+export declare function createBoardWithStateInDB(db: Database, name: string, category: string | null, state: PersistedCanvasState, readmeNodeId: string | null): CanvasBoard;
+/** Deletes a board with its rows and its snapshots. */
+export declare function deleteBoardFromDB(db: Database, id: string): boolean;
+export declare function readMetaFromDB(db: Database, key: string): string | null;
+/** Write a workspace-wide meta value; null removes it. */
+export declare function writeMetaToDB(db: Database, key: string, value: string | null): void;
+/** The board that was open last, if it still exists. */
+export declare function getActiveBoardIdFromDB(db: Database): string | null;
+export declare function setActiveBoardIdInDB(db: Database, id: string | null): void;
+export declare function saveSnapshotToDB(db: Database, boardId: string, snapshot: CanvasSnapshot, state: PersistedCanvasState): void;
+/** By id or name (most recent match) on `boardId`. */
+export declare function loadSnapshotFromDB(db: Database, idOrName: string, boardId: string | null): {
     snapshot: CanvasSnapshot;
     state: PersistedCanvasState;
 } | null;
-export declare function listSnapshotsFromDB(db: Database, options?: CanvasSnapshotListOptions): CanvasSnapshot[];
-export declare function renameSnapshotInDB(db: Database, id: string, name: string): boolean;
+export declare function listSnapshotsFromDB(db: Database, boardId: string, options?: CanvasSnapshotListOptions): CanvasSnapshot[];
+export declare function renameSnapshotInDB(db: Database, boardId: string, id: string, name: string): boolean;
 export declare function deleteSnapshotFromDB(db: Database, id: string): boolean;
 export declare function writeBlobToDB(db: Database, sha256: string, jsonValue: string): number;
 export declare function readBlobFromDB(db: Database, sha256: string): string | null;

package/dist/types/server/canvas-operations.d.ts

@@ -73,6 +73,21 @@ export declare const LEDGER_NODE_DEFAULT_SIZE: {
     width: number;
     height: number;
 };
+export interface CanvasSizeAdjustment {
+    requested: {
+        width: number | null;
+        height: number | null;
+    };
+    applied: {
+        width: number;
+        height: number;
+    };
+    reason: 'defaulted' | 'clamped-to-minimum' | 'defaulted-and-clamped-to-minimum' | 'fit-to-children';
+}
+export declare function describeCreateSize(requestedWidth: number | undefined, requestedHeight: number | undefined, resolvedWidth: number, resolvedHeight: number, applied: {
+    width: number;
+    height: number;
+}): CanvasSizeAdjustment | undefined;
 interface CanvasCreateGroupInput {
     title?: string;
     childIds?: string[];
@@ -146,6 +161,7 @@ export declare function addCanvasNode(input: CanvasAddNodeInput): {
     id: string;
     node: CanvasNodeState;
     needsCodeGraphRecompute: boolean;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 export declare function resolveCanvasNode(nodeRef: CanvasNodeLookupInput): {
     ok: true;
@@ -192,6 +208,29 @@ export declare function saveCanvasSnapshot(name: string): CanvasSnapshot | null;
 export declare function restoreCanvasSnapshot(idOrName: string): Promise<{
     ok: boolean;
 }>;
+/**
+ * Open a board (or Home for null): the state layer saves the current board and
+ * loads the next, and everything else that holds the old board in memory is
+ * reset — undo closures, pending intents, file watchers, app sessions and the
+ * code graph (the trace chain restarts itself when its last node is gone).
+ * Agent and human presence are kept: they belong to the people and agents,
+ * not to a board.
+ */
+export declare function openCanvasBoard(id: string | null): {
+    ok: boolean;
+};
+/**
+ * Restore the whole library from a backup file (the current file is kept as
+ * `<db>.before-restore`); the restored library opens on its last open board.
+ */
+export declare function restoreCanvasLibrary(file: string): void;
+/**
+ * A write that arrives while no board is open (Home) lands on the most recently
+ * opened board, or on a new board when the workspace has none — nothing on
+ * Home is displaced, because Home holds nothing. Intents and undo history are
+ * kept: whatever was signalled on Home was aimed at the board this opens.
+ */
+export declare function openBoardForWrite(): void;
 export declare function deleteCanvasSnapshot(id: string): {
     ok: boolean;
 };
@@ -213,11 +252,13 @@ export declare function removeCanvasEdge(id: string): {
 export declare function createCanvasGroup(input: CanvasCreateGroupInput): {
     id: string;
     node: CanvasNodeState;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 export declare function groupCanvasNodes(groupId: string, childIds: string[], options?: {
     childLayout?: CanvasArrangeMode;
 }): {
     ok: boolean;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 export declare function ungroupCanvasNodes(groupId: string): {
     ok: boolean;
@@ -230,6 +271,8 @@ export declare function createCanvasJsonRenderNode(input: JsonRenderNodeInput):
     url: string;
     spec: JsonRenderSpec;
     node: CanvasNodeState;
+    warnings: string[];
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 /**
  * Create an empty streaming json-render node. Unlike createCanvasJsonRenderNode
@@ -248,6 +291,7 @@ export declare function createCanvasStreamingJsonRenderNode(input: {
     url: string;
     spec: JsonRenderSpec;
     node: CanvasNodeState;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 /**
  * Apply a batch of SpecStream patches to an existing json-render node, bumping
@@ -269,6 +313,7 @@ export declare function createCanvasGraphNode(input: GraphNodeInput): {
     url: string;
     spec: JsonRenderSpec;
     node: CanvasNodeState;
+    sizeAdjustment?: CanvasSizeAdjustment;
 };
 export declare function setClientViewportSize(width: unknown, height: unknown): void;
 export declare function getClientViewportSize(): {

package/dist/types/server/canvas-provenance.d.ts

@@ -1,4 +1,4 @@
-export type CanvasNodeType = 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'diff' | 'mermaid' | 'image' | 'html' | 'group';
+export type CanvasNodeType = 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'board' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'diff' | 'mermaid' | 'image' | 'html' | 'group';
 export type CanvasNodeProvenanceSourceKind = 'workspace-file' | 'webpage-url' | 'mcp-tool' | 'artifact-file' | 'image-url';
 export type CanvasNodeRefreshStrategy = 'file-watch' | 'file-read-write' | 'image-reload' | 'webpage-refresh' | 'mcp-app-rehydrate' | 'artifact-reopen';
 export interface CanvasNodeProvenance {

package/dist/types/server/canvas-schema.d.ts

@@ -22,6 +22,7 @@ export interface StructuredValidationResult {
     ok: true;
     type: 'json-render' | 'graph' | 'html-primitive';
     normalizedSpec?: JsonRenderSpec;
+    warnings?: string[];
     normalizedPrimitive?: {
         kind: string;
         title: string;

package/dist/types/server/canvas-state.d.ts

@@ -11,8 +11,12 @@
  * `.pmx-canvas-snapshots/`, loose blob files) are no longer imported as of 0.4.0 —
  * the one-shot boot migration into SQLite was retired.
  */
-import { type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
+import { type Tour } from '../shared/tour.js';
+import { type CanvasBoard, type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
+import { type DocumentImport, type DocumentImportStatus, type ImportSection, type Attachment } from './document-import.js';
 import { type PmxAxActivityKind, type PmxAxElicitation, type PmxAxModeRequest, type PmxAxMode, type PmxAxCommandDescriptor, type PmxAxPolicy, type PmxAxFocusState, type PmxAxSource, type PmxAxState, type PmxAxWorkItem, type PmxAxWorkItemStatus, type PmxAxApprovalGate, type PmxAxReviewAnnotation, type PmxAxReviewKind, type PmxAxReviewSeverity, type PmxAxReviewStatus, type PmxAxReviewAnchorType, type PmxAxReviewRegion, type PmxAxEvent, type PmxAxEventKind, type PmxAxEvidence, type PmxAxEvidenceKind, type PmxAxSteeringMessage, type PmxAxHostCapability, type PmxAxTimelineSummary } from './ax-state.js';
+import { type ActorAttribution } from './attribution.js';
+import { type ContextRead, type ContextReadConsumerSummary, type ContextReadInput } from './context-reads.js';
 export declare const PMX_CANVAS_DIR = ".pmx-canvas";
 export interface PersistedBlobRef {
     __pmxCanvasBlob: 'v1';
@@ -53,7 +57,7 @@ export interface CanvasSnapshotGcResult {
 }
 export interface CanvasNodeState {
     id: string;
-    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'diff' | 'mermaid' | 'image' | 'html' | 'group';
+    type: 'markdown' | 'mcp-app' | 'webpage' | 'json-render' | 'graph' | 'board' | 'prompt' | 'response' | 'status' | 'context' | 'ledger' | 'trace' | 'file' | 'diff' | 'mermaid' | 'image' | 'html' | 'group';
     position: {
         x: number;
         y: number;
@@ -66,6 +70,27 @@ export interface CanvasNodeState {
     collapsed: boolean;
     pinned: boolean;
     data: Record<string, unknown>;
+    /** Server-owned provenance. Legacy rows normalize to unknown. */
+    createdBy?: ActorAttribution;
+    lastEditedBy?: ActorAttribution;
+    /** Board-monotonic revision of this node's latest semantic content. */
+    contentRevision?: number;
+}
+export interface NodeDeletionTombstone {
+    nodeId: string;
+    revision: number;
+    deletedBy: ActorAttribution;
+}
+export interface BoardContentRevision {
+    revision: number;
+    /** Cursors below this value are expired and must perform a full reset. */
+    retentionFloor: number;
+}
+export interface BoardContentDelta extends BoardContentRevision {
+    since: number;
+    reset: boolean;
+    nodes: CanvasNodeState[];
+    deleted: NodeDeletionTombstone[];
 }
 export interface ViewportState {
     x: number;
@@ -102,6 +127,7 @@ export interface CanvasAnnotation {
     createdAt: string;
 }
 export interface CanvasLayout {
+    tour?: Tour;
     viewport: ViewportState;
     theme: CanvasTheme;
     nodes: CanvasNodeState[];
@@ -121,6 +147,8 @@ export interface CanvasNodeUpdate {
     collapsed?: boolean;
 }
 export type CanvasChangeType = 'pins' | 'nodes' | 'ax' | 'ax-timeline';
+/** Name for a board nobody named yet: when it was made, to the minute. */
+export declare function defaultBoardName(): string;
 export interface MutationRecordInfo {
     operationType: 'addNode' | 'updateNode' | 'removeNode' | 'addEdge' | 'updateEdge' | 'removeEdge' | 'addAnnotation' | 'removeAnnotation' | 'clear' | 'restoreSnapshot' | 'setPins' | 'setAxFocus' | 'addWorkItem' | 'updateWorkItem' | 'requestApproval' | 'resolveApproval' | 'addReviewAnnotation' | 'updateReviewAnnotation' | 'requestElicitation' | 'respondElicitation' | 'requestMode' | 'resolveModeRequest' | 'setPolicy' | 'arrange' | 'batch' | 'groupNodes' | 'releaseGroupChildren' | 'viewport';
     description: string;
@@ -140,9 +168,13 @@ declare class CanvasStateManager {
     private edges;
     private annotations;
     private _viewport;
+    private _tour;
     private _theme;
     private _contextPinnedNodeIds;
     private _workspaceRoot;
+    private _contentRevision;
+    private _revisionFloor;
+    private _deletionTombstones;
     private readonly ax;
     private _changeListeners;
     /**
@@ -175,12 +207,22 @@ declare class CanvasStateManager {
     private applyResolvedGroupBounds;
     private getGroupSnapshot;
     private normalizeNode;
+    private nextContentRevision;
+    private revisionState;
+    /**
+     * Stable delta cursor contract: revisions strictly increase per active board;
+     * geometry-only writes do not advance them. `reset` means `since` predates
+     * retained tombstones, so callers must replace their view with `nodes`.
+     */
+    readContentDelta(since?: number): BoardContentDelta;
+    getContentRevision(): BoardContentRevision;
     private nodeForRead;
     private reflowAllGroups;
     private translateGroupChildren;
     private recomputeParentGroupBounds;
     private compactGroupChildren;
     private _db;
+    private _dbPath;
     private _saveTimer;
     /** Workspace root backing persistence and workspace-relative path resolution. */
     get workspaceRoot(): string;
@@ -198,8 +240,95 @@ declare class CanvasStateManager {
     private externalizePersistedStateBlobs;
     getWorkspaceRoot(): string;
     private emptyPersistedState;
-    /** Load canvas state from SQLite. Call once on server startup. */
+    /**
+     * Load the board that was open last. Call once on server startup. With no
+     * such board the workspace starts on Home (no board open).
+     */
     loadFromDisk(options?: LoadFromDiskOptions): boolean;
+    /** The SQLite file holding every board, or null without a workspace database. */
+    get databasePath(): string | null;
+    readWorkspaceMeta(key: string): string | null;
+    writeWorkspaceMeta(key: string, value: string | null): void;
+    /** A consistent copy of the whole library, safe while the server runs. */
+    backupDatabaseTo(path: string): void;
+    /**
+     * Replace the library with `file`: the current file is kept beside it as
+     * `<db>.before-restore`, then the restored file opens (migrating an older
+     * layout) on the board it had open last.
+     */
+    replaceDatabase(file: string): void;
+    private _activeBoardId;
+    private _boardGeneration;
+    /** Invalidates asynchronous work whenever the loaded board state is replaced. */
+    get boardGeneration(): number;
+    /** The open board, or null on Home. */
+    get activeBoardId(): string | null;
+    getActiveBoard(): CanvasBoard | null;
+    /**
+     * One board's content without opening it: the open board from memory, any
+     * other straight from SQLite. Null when there is no such board.
+     */
+    readBoard(id: string, includeBlobs?: boolean): {
+        board: CanvasBoard;
+        state: PersistedCanvasState;
+        layout: CanvasLayout;
+    } | null;
+    /** Every board in the workspace, most recently opened first. */
+    listBoards(): CanvasBoard[];
+    storeAttachment(input: {
+        boardId: string;
+        name: string;
+        mime: string;
+        bytes: Uint8Array;
+    }): Attachment | null;
+    getAttachment(id: string): Attachment | null;
+    readAttachmentBytes(id: string): Uint8Array | null;
+    createDocumentImport(attachmentId: string, position: {
+        x: number;
+        y: number;
+    }): DocumentImport | null;
+    getDocumentImport(id: string): DocumentImport | null;
+    listDocumentImports(boardId?: string): DocumentImport[];
+    updateDocumentImport(id: string, status: DocumentImportStatus, fields?: {
+        sections?: ImportSection[];
+        warnings?: string[];
+        agentDescription?: string;
+        reason?: string;
+        committedNodeIds?: string[];
+    }): DocumentImport | null;
+    commitDocumentImport(id: string, nodeIds: string[]): DocumentImport | null;
+    getContextBriefCursor(boardId: string, consumer: string): number | null;
+    advanceContextBriefCursor(boardId: string, consumer: string, revision: number): void;
+    /** Creates a board without opening it. */
+    createBoard(name: string, category?: string | null): CanvasBoard | null;
+    updateBoard(id: string, patch: {
+        name?: string;
+        category?: string | null;
+    }): boolean;
+    setBoardReadme(id: string, nodeId: string | null): boolean;
+    /** Bounded inactive-board creation; never replaces the state the human has open. */
+    createBoardFromBoard(input: {
+        sourceBoardId: string;
+        name: string;
+        category?: string | null;
+        nodeIds?: string[];
+        includeReadme?: boolean;
+        includeStructure?: boolean;
+    }): CanvasBoard | null;
+    /** Deletes a board and its snapshots; deleting the open board returns to Home first. */
+    deleteBoard(id: string): boolean;
+    /**
+     * Save the open board, then open `id` (or Home for null). The canvas state is
+     * replaced wholesale; callers own the runtime side (undo history, app
+     * sessions, watchers, SSE) — see `openCanvasBoard` in canvas-operations.
+     */
+    switchBoard(id: string | null): boolean;
+    /**
+     * Content written while no board is open (Home) lands on a new board, which
+     * opens: nothing the human was looking at is displaced.
+     */
+    private ensureActiveBoard;
+    private hasBoardContent;
     /** Debounced save — coalesces rapid mutations into a single write. */
     private scheduleSave;
     flushToDisk(): void;
@@ -236,12 +365,18 @@ declare class CanvasStateManager {
         nodes: CanvasNodeState[];
         edges: CanvasEdge[];
         annotations: CanvasAnnotation[];
+        tour?: Tour;
     } | null;
     /** Delete a snapshot. */
     renameSnapshot(id: string, name: string): boolean;
     deleteSnapshot(id: string): boolean;
     /** Remove all snapshots from the DB. Used by test teardown. */
     clearAllSnapshots(): void;
+    private restampRestoredContent;
+    private semanticData;
+    private nodeContentChanged;
+    private setSemanticNode;
+    private recordDeletion;
     get viewport(): ViewportState;
     addNode(node: CanvasNodeState): void;
     addJsonRenderNode(node: CanvasNodeState): void;
@@ -261,6 +396,8 @@ declare class CanvasStateManager {
     private removeEdgesForNode;
     getLayout(): CanvasLayout;
     getLayoutForPersistence(): CanvasLayout;
+    getTour(): Tour | undefined;
+    setTour(tour: Tour | null): void;
     applyUpdates(updates: CanvasNodeUpdate[], options?: ApplyUpdatesOptions): {
         applied: number;
         skipped: number;
@@ -470,6 +607,12 @@ declare class CanvasStateManager {
     }): PmxAxSteeringMessage[];
     getPendingSteeringCount(consumer?: string): number;
     getAxTimelineSummary(): PmxAxTimelineSummary;
+    /** Records one agent context read (diagnostics; never notifies, so a read cannot trigger reads). */
+    recordContextRead(input: ContextReadInput, boardId?: string | null): ContextRead | null;
+    getContextReads(limit?: number): {
+        reads: ContextRead[];
+        summary: ContextReadConsumerSummary[];
+    };
     getAxTimeline(q?: AxTimelineQuery): {
         events: PmxAxEvent[];
         evidence: PmxAxEvidence[];

package/dist/types/server/canvas-validation.d.ts

@@ -26,6 +26,8 @@ export interface CanvasValidationResult {
     collisions: CanvasValidationPair[];
     containments: CanvasContainmentIssue[];
     containmentViolations: CanvasContainmentIssue[];
+    /** Group frames overlapping nodes that are not members (advisory). */
+    groupFrameOverlaps: CanvasValidationPair[];
     missingEdgeEndpoints: Array<{
         edgeId: string;
         from: string;
@@ -39,6 +41,7 @@ export interface CanvasValidationResult {
         collisions: number;
         containments: number;
         containmentViolations: number;
+        groupFrameOverlaps: number;
         missingEdgeEndpoints: number;
         sizeWarnings: number;
     };

package/dist/types/server/context-brief.d.ts

@@ -0,0 +1,111 @@
+import type { CanvasNodeState, NodeDeletionTombstone } from './canvas-state.js';
+export type ContextBriefReason = 'pinned' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
+export interface ContextBriefSourceEntry {
+    sourceBoardId: string;
+    nodeId: string;
+    reason: 'human' | 'ask' | 'steer';
+    title: string;
+    text: string;
+    provenance?: {
+        kind: 'imported';
+        source: string;
+    };
+}
+export interface ContextBriefLibraryBoard {
+    boardId: string;
+    name: string;
+    category: 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[];
+}
+export interface ContextBriefInput {
+    activeBoard: {
+        boardId: string;
+        name: string;
+        category: string | null;
+    };
+    nodes: readonly CanvasNodeState[];
+    pinnedNodeIds: readonly string[];
+    contentRevision: number;
+    retentionFloor: number;
+    tombstones: readonly NodeDeletionTombstone[];
+    /** null means a first read. Other values must be non-negative safe integers. */
+    since: number | null;
+    libraryBoards: readonly ContextBriefLibraryBoard[];
+    entries?: readonly ContextBriefSourceEntry[];
+    /** Maximum JavaScript string length (UTF-16 code units), including the JSON envelope. */
+    budget: number;
+}
+export interface CompiledContextEntry {
+    sourceBoardId: string;
+    nodeId: string;
+    reason: ContextBriefReason;
+    title: string;
+    text: string;
+    /** A linked board's pin title is discovery metadata, not delivery of that pinned card. */
+    titleOnly?: true;
+    /** The body was shortened to fit; the same revision remains eligible on the next pull. */
+    truncated?: true;
+    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;
+    };
+    cursor: {
+        requested: number | null;
+        next: number | null;
+        current: number;
+        retentionFloor: number;
+        reset: 'first-read' | 'retention-expired' | null;
+        valid: boolean;
+    };
+    entries: CompiledContextEntry[];
+    deletions: Array<{
+        sourceBoardId: string;
+        nodeId: string;
+        revision: number;
+    }>;
+    delivery: {
+        truncated: boolean;
+        omittedEntries: number;
+        omittedDeletions: number;
+    };
+}
+export interface ContextBriefResult {
+    /** Empty only when the budget cannot hold even the bounded JSON envelope. */
+    serialized: string;
+    document: ContextBriefDocument | null;
+    deliveredEntryIds: string[];
+    deliveredDeletionIds: string[];
+    nextCursor: number | null;
+    reset: ContextBriefDocument['cursor']['reset'];
+    invalidCursor: boolean;
+    truncated: boolean;
+}
+/**
+ * Pure, deterministic compiler. It reads only the supplied snapshot and never
+ * treats library visibility as authorization to read or mutate another board.
+ */
+export declare function compileContextBrief(input: ContextBriefInput): ContextBriefResult;

package/dist/types/server/context-reads.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Context read instrumentation (vision Part 1 item 4, the delivery half):
+ * one row per agent read of canvas context — which surface, by whom, and
+ * which pinned nodes were in what came back. Diagnostics only, like the AX
+ * timeline: never snapshotted, never cleared with the canvas, bounded, and
+ * recording never notifies (a read must not trigger more reads).
+ */
+import type { Database } from 'bun:sqlite';
+export declare const CONTEXT_READ_RETENTION = 5000;
+export declare const CONTEXT_READ_CHANNELS: readonly ["operation", "mcp-resource", "mcp-prompt", "adapter"];
+export type ContextReadChannel = (typeof CONTEXT_READ_CHANNELS)[number];
+/** Registry reads that hand an agent canvas context; recorded in executeOperation. */
+export declare const CONTEXT_READ_OPS: Set<string>;
+export interface ContextRead {
+    seq: number;
+    id: string;
+    at: string;
+    channel: ContextReadChannel;
+    resource: string;
+    source: string;
+    consumer: string | null;
+    agentId: string | null;
+    pinnedNodeIds: string[];
+    deliveredNodeIds: string[];
+    bytes: number;
+    /** The board open when the read happened (null on Home). */
+    boardId: string | null;
+}
+export type ContextReadInput = Omit<ContextRead, 'seq' | 'id' | 'at' | 'boardId'> & {
+    /** Explicit read target, captured before asynchronous formatting/proxy work. */
+    boardId?: string | null;
+};
+export interface ContextReadConsumerSummary {
+    consumer: string;
+    reads: number;
+    readsWithPins: number;
+    readsDeliveringAllPins: number;
+    lastReadAt: string;
+    resources: Record<string, number>;
+}
+/**
+ * Pinned nodes whose serialized node (an object carrying `"id": "<id>"`) is in
+ * what the reader received. A bare id list, a title, or a clipped-off node does
+ * not count — the agent got the pin's name, not its content.
+ */
+export declare function deliveredPinnedIds(pinnedNodeIds: string[], payloadText: string): string[];
+export declare function contextReadFromPayload(base: Omit<ContextReadInput, 'deliveredNodeIds' | 'bytes'>, payload: unknown): ContextReadInput;
+export declare const CONTEXT_READS_SCHEMA_SQL = "\n  CREATE TABLE IF NOT EXISTS context_reads (\n    seq INTEGER PRIMARY KEY AUTOINCREMENT,\n    id TEXT NOT NULL UNIQUE,\n    at TEXT NOT NULL,\n    channel TEXT NOT NULL,\n    resource TEXT NOT NULL,\n    source TEXT NOT NULL,\n    consumer TEXT,\n    agent_id TEXT,\n    pinned_node_ids TEXT NOT NULL DEFAULT '[]',\n    delivered_node_ids TEXT NOT NULL DEFAULT '[]',\n    bytes INTEGER NOT NULL DEFAULT 0,\n    board_id TEXT\n  );\n";
+export declare function appendContextReadToDB(db: Database, input: ContextReadInput, boardId: string | null): ContextRead;
+/** Newest first. The summary covers every retained row, not just the returned page. */
+export declare function loadContextReadsFromDB(db: Database, limit?: number): {
+    reads: ContextRead[];
+    summary: ContextReadConsumerSummary[];
+};
+export declare function summarizeContextReads(reads: ContextRead[]): ContextReadConsumerSummary[];