pmx-canvas 0.8.2 → 0.9.0

package/dist/types/server/agent-presence.d.ts

@@ -13,7 +13,7 @@
  * richer hooks may `set` a phase, cursor, or focus explicitly.
  */
 import { z } from 'zod';
-import { type AgentPhase, type AgentPresence, type AgentPresenceSnapshot, type ContextBudget } from '../shared/agent-presence.js';
+import { type AgentPhase, type AgentPresence, type AgentPresenceSnapshot } from '../shared/agent-presence.js';
 import type { PmxAxActivityKind } from './ax-state.js';
 type PresenceEmitter = (event: string, payload: Record<string, unknown>) => void;
 /** A legal writer label: short, alphanumeric/dash, letter-first (header and env values). */
@@ -94,8 +94,6 @@ export declare const PRESENCE_SET_SHAPE: {
         total: z.ZodNumber;
     }, z.core.$strip>>>;
 };
-/** Token estimate of the pinned-context payload — the same serialization the MCP resource ships. */
-export declare function estimateContextBudget(): ContextBudget;
 /** Returns the id of the pre-session snapshot the server took, if any. */
 type SessionStartListener = (presence: AgentPresence) => string | null;
 export type SessionEndReason = 'human' | 'agent' | 'idle-timeout';
@@ -173,11 +171,20 @@ export declare class AgentPresenceRegistry {
      * (a gate opened or resolved) without any writer being touched.
      */
     refresh(): void;
+    /** Bumped when an agent read is recorded: the live lens's read list changed. */
+    private readVersion;
+    /** A read landed (server.ts's read listener): re-count and re-emit. */
+    noteRead(): void;
+    /** A board opened: attached sessions record it as they find it, before any write lands. */
+    boardOpened(): void;
     /** Remove a writer (session-end). */
     detach(sessionId: string): boolean;
     snapshot(now?: number): AgentPresenceSnapshot;
+    /** Latest attached session: a newly attached reviewer must check fast context again. */
+    reviewSessionStartedAt(): number | null;
     /** Test / shutdown hook. */
     reset(): void;
+    /** `withTouches`: only emitted snapshots carry the session's touches (they read the DB). */
     private publicView;
     private hasPendingGate;
     private evictOverflow;

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

@@ -22,7 +22,7 @@ export interface PmxAxSurfaceSnapshot {
  * human review text is redacted below.
  */
 export declare function buildCanvasAxSurfaceSnapshot(): PmxAxSurfaceSnapshot;
-export declare function buildCanvasAxPinnedContext(): PmxAxPinnedContext;
+export declare function buildCanvasAxPinnedContext(qualifications?: Record<string, import("../shared/lifecycle-status.js").LifecycleQualification>): PmxAxPinnedContext;
 export declare function buildCanvasAxContext(consumer?: string): PmxAxContext & {
     boardId: string | null;
 };

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

@@ -6,6 +6,7 @@
  */
 import { Database } from 'bun:sqlite';
 import type { ActorAttribution } from './attribution.js';
+import { type RelationDefinition } from '../shared/relations.js';
 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';
@@ -76,28 +77,50 @@ export declare function loadStateFromDB(db: Database, boardId?: string): Persist
 export interface CanvasBoard {
     id: string;
     name: string;
-    /** A human-chosen shelf on Home ("Planning", "Research"); null is uncategorized. */
-    category: string | null;
+    /** A human-chosen folder on Home ("Planning", "Research"); null is unfiled. */
+    folder: string | null;
     createdAt: string;
     lastOpenedAt: string | null;
     nodeCount: number;
     /** Markdown node used as this board's introduction. */
     readmeNodeId: string | null;
+    /** Human-dragged position in Home Map; null uses the generated folder layout. */
+    mapPosition?: {
+        x: number;
+        y: number;
+    } | null;
+    /** The source of a recurring/template board, separate from ordinary portals. */
+    previousBoardId?: string | null;
+    relationVocabulary?: RelationDefinition[];
+    /** Pinned into the agent's working set (vision move 0a); null when not pinned. */
+    pin: ContextPinMeta | 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 createBoardInDB(db: Database, name: string, folder?: string | null): CanvasBoard;
+/** Pin a board into the working set, or unpin it with null. False when the board does not exist. */
+export declare function setBoardPinInDB(db: Database, id: string, meta: ContextPinMeta | null): boolean;
+/** Rename and/or re-shelve a board; `folder: null` unfiles it. */
 export declare function updateBoardInDB(db: Database, id: string, patch: {
     name?: string;
-    category?: string | null;
+    folder?: string | null;
     readmeNodeId?: string | null;
+    mapPosition?: {
+        x: number;
+        y: number;
+    } | null;
+    previousBoardId?: string | null;
+    relationVocabulary?: RelationDefinition[];
 }): 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;
+export declare function createBoardWithStateInDB(db: Database, name: string, folder: string | null, state: PersistedCanvasState, readmeNodeId: string | null, invalidateTarget?: (boardId: string, nodeId: string) => void): CanvasBoard;
+/** Derived incoming-link metadata only: the target owns its clock and its body. */
+export declare function invalidateLinksInDB(db: Database, boardId: string, nodeId: string): number | undefined;
+/** A target's appearance/disappearance changes its incoming saved relations on source cards. */
+export declare function invalidateIncomingLinksInDB(db: Database, boardId: string, nodeId: string | null, invalidate: (boardId: string, nodeId: string) => void): void;
 /** Deletes a board with its rows and its snapshots. */
-export declare function deleteBoardFromDB(db: Database, id: string): boolean;
+export declare function deleteBoardFromDB(db: Database, id: string, invalidateTarget?: (boardId: string, nodeId: string) => void): 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;

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

@@ -38,6 +38,7 @@ export interface CanvasStructuredNodeUpdateInput extends Omit<CanvasGraphNodeUpd
     chartHeight?: unknown;
 }
 interface CanvasAddNodeInput {
+    prepareOnlyNodes?: CanvasNodeState[];
     type: CanvasNodeState['type'];
     title?: string;
     content?: string;
@@ -89,6 +90,10 @@ export declare function describeCreateSize(requestedWidth: number | undefined, r
     height: number;
 }): CanvasSizeAdjustment | undefined;
 interface CanvasCreateGroupInput {
+    destinationBoardId?: string;
+    requestId?: string;
+    expectedBoardId?: string | null;
+    intentId?: string;
     title?: string;
     childIds?: string[];
     x?: number;
@@ -101,6 +106,7 @@ interface CanvasCreateGroupInput {
 interface CanvasNodeLookupInput {
     id?: string;
     search?: string;
+    board?: string;
 }
 export declare function hasStructuredNodeUpdateFields(input: Record<string, unknown>): boolean;
 export declare function buildStructuredNodeUpdate(node: CanvasNodeState, input: CanvasStructuredNodeUpdateInput): {
@@ -226,16 +232,23 @@ export declare function deleteCanvasSnapshot(id: string): {
 };
 export declare function gcCanvasSnapshots(options?: Parameters<typeof canvasState.gcSnapshots>[0]): ReturnType<typeof canvasState.gcSnapshots>;
 export declare function addCanvasEdge(input: {
+    destinationBoardId?: string;
+    requestId?: string;
+    expectedBoardId?: string | null;
+    intentId?: string;
     from?: string;
     to?: string;
+    toBoardId?: string;
     fromSearch?: string;
     toSearch?: string;
     type: CanvasEdge['type'];
+    kind?: string;
+    reason?: string;
     label?: string;
     style?: CanvasEdge['style'];
     animated?: boolean;
 }): CanvasEdge;
-export declare function updateCanvasEdge(id: string, patch: Partial<Pick<CanvasEdge, 'type' | 'label' | 'style' | 'animated'>>): CanvasEdge;
+export declare function updateCanvasEdge(id: string, patch: Partial<Pick<CanvasEdge, 'type' | 'kind' | 'reason' | 'label' | 'style' | 'animated'>>): CanvasEdge;
 export declare function removeCanvasEdge(id: string): {
     removed: boolean;
 };
@@ -244,6 +257,12 @@ export declare function createCanvasGroup(input: CanvasCreateGroupInput): {
     node: CanvasNodeState;
     sizeAdjustment?: CanvasSizeAdjustment;
 };
+/** One logical creation identity across node, frame and link operations. */
+export declare function storedCreationTarget(input: object, operation: string): {
+    boardId: string;
+    requestId: string | undefined;
+    fingerprint: string;
+};
 export declare function groupCanvasNodes(groupId: string, childIds: string[], options?: {
     childLayout?: CanvasArrangeMode;
 }): {
@@ -305,7 +324,10 @@ export declare function createCanvasGraphNode(input: GraphNodeInput): {
     node: CanvasNodeState;
     sizeAdjustment?: CanvasSizeAdjustment;
 };
-export declare function setClientViewportSize(width: unknown, height: unknown): void;
+export declare function setClientViewportSize(width: unknown, height: unknown, insets?: {
+    top: number;
+    bottom: number;
+}): void;
 export declare function getClientViewportSize(): {
     width: number;
     height: number;

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

@@ -1,13 +1,33 @@
+import { z } from 'zod';
 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 type CanvasNodeProvenanceSourceKind = 'workspace-file' | 'webpage-url' | 'mcp-tool' | 'artifact-file' | 'image-url' | 'recipe';
+export type CanvasNodeRefreshStrategy = 'file-watch' | 'file-read-write' | 'image-reload' | 'webpage-refresh' | 'mcp-app-rehydrate' | 'artifact-reopen' | 'agent-request';
+declare const observedSourceSchema: z.ZodObject<{
+    boardId: z.ZodString;
+    cardId: z.ZodString;
+    contentRevision: z.ZodOptional<z.ZodNumber>;
+    observedAt: z.ZodOptional<z.ZodISODateTime>;
+    availability: z.ZodOptional<z.ZodEnum<{
+        live: "live";
+        cached: "cached";
+        unavailable: "unavailable";
+    }>>;
+}, z.core.$strip>;
+declare const recipeSchema: z.ZodObject<{
+    tool: z.ZodString;
+    input: z.ZodOptional<z.ZodUnknown>;
+    prompt: z.ZodString;
+}, z.core.$strip>;
 export interface CanvasNodeProvenance {
     sourceKind: CanvasNodeProvenanceSourceKind;
     sourceUri: string;
     refreshStrategy: CanvasNodeRefreshStrategy;
     snapshotContent: boolean;
     syncedAt?: string;
+    sources?: Array<z.infer<typeof observedSourceSchema>>;
+    recipe?: z.infer<typeof recipeSchema>;
     details?: Record<string, unknown>;
 }
 export declare function inferCanvasNodeProvenance(nodeType: CanvasNodeType, data: Record<string, unknown>): CanvasNodeProvenance | null;
 export declare function normalizeCanvasNodeData<T extends Record<string, unknown>>(nodeType: CanvasNodeType, data: T): T;
+export {};

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

@@ -1,6 +1,8 @@
 import type { CanvasAnnotation, CanvasLayout, CanvasNodeState, ViewportState } from './canvas-state.js';
 import { type CanvasNodeProvenance } from './canvas-provenance.js';
+import type { LifecycleQualification } from '../shared/lifecycle-status.js';
 export interface SerializedCanvasNode extends CanvasNodeState {
+    qualification?: LifecycleQualification;
     kind: string;
     title: string | null;
     content: string | null;

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 WorkspaceSettings } from '../shared/workspace-settings.js';
+import { KnowledgeLifecycle, type Lifecycle } from './knowledge-lifecycle.js';
 import { type Tour } from '../shared/tour.js';
-import { type CanvasBoard, type ContextPinMeta, type PersistedCanvasState, type CanvasTheme, type AxTimelineQuery } from './canvas-db.js';
+import { type WikiBoard } from './wiki-links.js';
+import { type WikiLink } from '../shared/memory-graph.js';
+import { updateBoardInDB, type CanvasBoard, type ContextPinMeta, 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';
@@ -75,6 +79,12 @@ export interface CanvasNodeState {
     lastEditedBy?: ActorAttribution;
     /** Board-monotonic revision of this node's latest semantic content. */
     contentRevision?: number;
+    /** Time of that semantic change; absent for content created before this clock was recorded. */
+    contentChangedAt?: string;
+    /** Initial authored freshness, not evidence validation. Imports and undated existing content have none. */
+    freshnessStartedAt?: string;
+    /** Board-monotonic revision of this node's latest link change, kept apart from its text. */
+    linksRevision?: number;
 }
 export interface NodeDeletionTombstone {
     nodeId: string;
@@ -101,10 +111,25 @@ export interface CanvasEdge {
     id: string;
     from: string;
     to: string;
+    /** Target on another board. Source and mutation ownership stay on the active board. */
+    toBoardId?: string;
     type: 'relation' | 'depends-on' | 'flow' | 'references';
+    /** Open semantic relation kind, independent of the structural edge type. */
+    kind?: string;
+    reason?: string;
+    /** Source content observed when an explicit dependency was authored. Never refreshed by reads. */
+    sourceRevision?: number;
     label?: string;
     style?: 'solid' | 'dashed' | 'dotted';
     animated?: boolean;
+    /** Board revision of this link's latest add, retype or relabel (0 = never stamped). */
+    revision?: number;
+    /** Who made that change, and when: the link's author until a person changes it again. */
+    changedBy?: ActorAttribution;
+    changedAt?: string;
+    /** Who first drew the link, and when (docs/design/LinkAuthorship.dc.html). */
+    createdBy?: ActorAttribution;
+    createdAt?: string;
 }
 export interface CanvasAnnotationPoint {
     x: number;
@@ -229,6 +254,7 @@ declare class CanvasStateManager {
     private _db;
     private _dbPath;
     private _saveTimer;
+    readonly knowledge: KnowledgeLifecycle;
     /** Workspace root backing persistence and workspace-relative path resolution. */
     get workspaceRoot(): string;
     /** Set the workspace root to enable auto-persistence. */
@@ -269,10 +295,14 @@ declare class CanvasStateManager {
     /** 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.
-     */
+    /** Synchronous, owner-controlled static creation. No board activation or runtime hydration. */
+    createStoredNode(boardId: string, requestId: string | undefined, fingerprint: string, build: (nodes: CanvasNodeState[]) => CanvasNodeState): CanvasNodeState;
+    private stampStoredNode;
+    createStoredGroup(boardId: string, requestId: string | undefined, fingerprint: string, build: (nodes: CanvasNodeState[]) => CanvasNodeState, childLayout?: 'grid' | 'column' | 'flow'): CanvasNodeState;
+    createStoredEdge(boardId: string, requestId: string | undefined, fingerprint: string, build: (nodes: CanvasNodeState[]) => CanvasEdge): CanvasEdge;
+    /** Stored creations share one durable receipt/commit boundary, never a temporary board switch. */
+    private createStoredCreation;
+    /** Read a board without activating it. This projection is not a write payload. */
     readBoard(id: string, includeBlobs?: boolean): {
         board: CanvasBoard;
         state: PersistedCanvasState;
@@ -305,17 +335,21 @@ declare class CanvasStateManager {
     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;
+    createBoard(name: string, folder?: string | null): CanvasBoard | null;
+    updateBoard(id: string, patch: Pick<Parameters<typeof updateBoardInDB>[2], 'name' | 'folder' | 'mapPosition' | 'relationVocabulary'>): boolean;
     setBoardReadme(id: string, nodeId: string | null): boolean;
+    /**
+     * Pin a board into the agent's working set (vision move 0a). Workspace-level:
+     * survives board switches and restarts. A repeat pin keeps its first
+     * attribution, like card pins. False when the board does not exist.
+     */
+    pinBoard(id: string, reason?: string): boolean;
+    unpinBoard(id: string): boolean;
     /** Bounded inactive-board creation; never replaces the state the human has open. */
     createBoardFromBoard(input: {
         sourceBoardId: string;
         name: string;
-        category?: string | null;
+        folder?: string | null;
         nodeIds?: string[];
         includeReadme?: boolean;
         includeStructure?: boolean;
@@ -337,6 +371,7 @@ declare class CanvasStateManager {
     /** Debounced save — coalesces rapid mutations into a single write. */
     private scheduleSave;
     flushToDisk(): void;
+    private persistedState;
     /** Write current state to SQLite immediately. */
     private saveToDisk;
     private _lastPersistenceError;
@@ -379,19 +414,49 @@ declare class CanvasStateManager {
     clearAllSnapshots(): void;
     private restampRestoredContent;
     private semanticData;
+    /** A small name/ID catalog, read only when Markdown is saved, never on a drag frame. */
+    wikiCatalog(): WikiBoard[];
+    /** Backfill only uninitialized live rows, not snapshots or authoritative empty/unresolved bindings. */
+    private initializePersistedWikiLinks;
+    private bindWikiLinks;
     private nodeContentChanged;
     private setSemanticNode;
     private recordDeletion;
     get viewport(): ViewportState;
-    addNode(node: CanvasNodeState): void;
+    addNode(node: CanvasNodeState, savedWikiLinks?: WikiLink[]): void;
+    private recordNodeCreation;
     addJsonRenderNode(node: CanvasNodeState): void;
     addGraphNode(node: CanvasNodeState): void;
-    updateNode(id: string, patch: Partial<CanvasNodeState>): void;
+    /** Metadata stays on the stored node: no blob hydration, wiki resolution or group reflow. */
+    setNodeLifecycle(id: string, value: Lifecycle | null): void;
+    updateNode(id: string, patch: Partial<CanvasNodeState>, savedWikiLinks?: WikiLink[] | null): void;
     removeNode(id: string): void;
     getNode(id: string): CanvasNodeState | undefined;
+    /** Who made and last edited each card, and its content revision — no content, no copies. */
+    nodeStamps(): Array<Pick<CanvasNodeState, 'id' | 'createdBy' | 'lastEditedBy' | 'contentRevision'>>;
     getNodeForPersistence(id: string): CanvasNodeState | undefined;
+    /**
+     * Links are tracked apart from text (connection changes, option C of
+     * docs/design/LinksOptions.dc.html): a link change advances both endpoints'
+     * links revision, never their content revision, so cards keep their read
+     * marks while the next incremental brief resends them with their new
+     * relations. Generated auto-edges (code graph, board map) do not count.
+     * Returns the stamp for the changed link.
+     */
+    private touchRelations;
+    private invalidateRelationTarget;
+    /** Saved wiki relationships have the same source/target clocks as native links. */
+    private touchWikiRelations;
+    private invalidateIncomingRelations;
     addEdge(edge: CanvasEdge): boolean;
-    updateEdge(id: string, patch: Partial<Pick<CanvasEdge, 'type' | 'label' | 'style' | 'animated'>>): CanvasEdge | null;
+    private relationSourceRevision;
+    updateEdge(id: string, patch: Partial<Pick<CanvasEdge, 'type' | 'kind' | 'reason' | 'label' | 'style' | 'animated'>>): CanvasEdge | null;
+    /**
+     * An edge as undo/redo puts it back. A relation change restores the link as it
+     * was, author included, under a new revision so the next brief carries it; a
+     * style-only change keeps the current stamp, so it never hides a later relabel.
+     */
+    private replayEdge;
     removeEdge(id: string): boolean;
     getEdges(): CanvasEdge[];
     getEdgesForNode(nodeId: string): CanvasEdge[];
@@ -409,6 +474,8 @@ declare class CanvasStateManager {
     };
     setViewport(v: Partial<ViewportState>): void;
     get theme(): CanvasTheme;
+    getWorkspaceSettings(): WorkspaceSettings;
+    updateWorkspaceSettings(patch: Partial<WorkspaceSettings>): WorkspaceSettings;
     setTheme(theme: CanvasTheme): CanvasTheme;
     get contextPinnedNodeIds(): Set<string>;
     getAxState(): PmxAxState;
@@ -614,10 +681,21 @@ declare class CanvasStateManager {
     getAxTimelineSummary(): PmxAxTimelineSummary;
     /** Records one agent context read (diagnostics; never notifies, so a read cannot trigger reads). */
     recordContextRead(input: ContextReadInput, boardId?: string | null): ContextRead | null;
-    /** The delivered ids that are nodes on the read board, each with its content revision now. */
+    /**
+     * The delivered ids that are nodes on the read board: those read in full with
+     * their content revision now, and every one that arrived (summaries included)
+     * with its links revision now.
+     */
     private readRevisions;
+    /** Per node on a board, the newest links revision an agent read carried. */
+    getSeenLinks(boardId?: string | null): Record<string, number>;
     /** Per node on a board, the latest agent read that delivered its content. */
     getNodeReadStatus(boardId?: string | null): NodeReadStatus[];
+    /** The latest agent read on a board, of any kind, or null. */
+    getBoardLastRead(boardId?: string | null): {
+        lastReadAt: string;
+        lastReadBy: string;
+    } | null;
     /** Nodes on a board whose content an agent read at or after `since` (ISO). */
     getReadNodeIdsSince(boardId: string | null, since: string): string[];
     getContextReads(limit?: number): {

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

@@ -46,4 +46,4 @@ export interface CanvasValidationResult {
         sizeWarnings: number;
     };
 }
-export declare function validateCanvasLayout(layout: CanvasLayout): CanvasValidationResult;
+export declare function validateCanvasLayout(layout: CanvasLayout, remoteEndpointExists?: (boardId: string, cardId: string) => boolean): CanvasValidationResult;

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

@@ -1,7 +1,8 @@
+import type { LifecycleQualification } from '../shared/lifecycle-status.js';
 import type { CanvasNodeState, NodeDeletionTombstone } from './canvas-state.js';
-export type ContextBriefReason = 'pinned' | 'near' | 'changed' | 'human' | 'ask' | 'steer' | 'linked' | 'category';
-/** A near entry carries a short summary, never full content: pin the node to send that. */
-export declare const NEAR_SUMMARY_LENGTH = 280;
+export type ContextBriefReason = 'overview' | 'pinned' | 'near' | 'changed' | 'pinned-board' | 'human' | 'ask' | 'steer' | 'linked' | 'folder';
+/** How long a card's summary is in the brief: enough to know what it is. */
+export declare const BRIEF_SUMMARY_LENGTH = 280;
 export interface ContextBriefSourceEntry {
     sourceBoardId: string;
     nodeId: string;
@@ -16,7 +17,7 @@ export interface ContextBriefSourceEntry {
 export interface ContextBriefLibraryBoard {
     boardId: string;
     name: string;
-    category: string | null;
+    folder: string | null;
     readme?: {
         nodeId: string;
         title: string;
@@ -33,12 +34,70 @@ export interface ContextBriefLibraryBoard {
     /** 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 {
+    qualifications?: Readonly<Record<string, LifecycleQualification>>;
     activeBoard: {
         boardId: string;
         name: string;
-        category: string | null;
+        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;
@@ -47,11 +106,15 @@ 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;
@@ -66,6 +129,17 @@ export interface CompiledContextEntry {
     };
     /** 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;
@@ -78,7 +152,7 @@ export interface ContextBriefDocument {
     board: {
         boardId: string;
         name: string;
-        category: string | null;
+        folder: string | null;
     };
     cursor: {
         requested: number | null;
@@ -89,6 +163,20 @@ 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;