pmx-canvas 0.8.0 → 0.9.0

package/src/server/knowledge-lifecycle.ts

@@ -0,0 +1,304 @@
+import type { Database } from 'bun:sqlite';
+import { z } from 'zod';
+import { normalizeBoardFolder } from '../shared/boards.js';
+import { currentActor, type ActorAttribution } from './attribution.js';
+import { OperationError } from './operations/types.js';
+import type { LifecycleQualification } from '../shared/lifecycle-status.js';
+import type { CanvasNodeState } from './canvas-state.js';
+import { RELATION_PRESETS, relationPresetSchema, type RelationPreset } from '../shared/relations.js';
+import {
+  categorySchema,
+  lifecycleSchema,
+  type KnowledgeCategory,
+  type Lifecycle,
+} from '../shared/knowledge-lifecycle.js';
+
+export {
+  categorySchema,
+  lifecycleSchema,
+  type KnowledgeCategory,
+  type Lifecycle,
+} from '../shared/knowledge-lifecycle.js';
+
+export interface ReviewCardSummary {
+  boardId: string;
+  cardId: string;
+  boardTitle: string;
+  folder: string | null;
+  title: string;
+}
+export const folderPropertiesSchema = z.object({
+  path: z.string(),
+  categoryId: z.string().nullable(),
+  lifecycleOverride: lifecycleSchema.nullable(),
+});
+export type FolderProperties = z.infer<typeof folderPropertiesSchema>;
+export interface ReviewRecord {
+  id: string;
+  boardId: string;
+  nodeId: string;
+  outcome: 'retain' | 'revise' | 'externalize' | 'retire' | 'unresolved' | 'restore';
+  evidence: string;
+  applied: boolean;
+  who: ActorAttribution;
+  when: string;
+  /** Exact semantic version reviewed; old unversioned records remain unknown. */
+  contentRevision: number | null;
+  sourceRevisions?: Record<string, number | null>;
+}
+
+export type KnowledgeInput =
+  | { action: 'list' }
+  | { action: 'category-set'; category: KnowledgeCategory }
+  | { action: 'category-remove'; id: string }
+  | { action: 'relation-preset-set'; preset: RelationPreset }
+  | { action: 'relation-preset-remove'; id: string }
+  | ({ action: 'folder-set' } & FolderProperties);
+export interface KnowledgeResults {
+  list: {
+    ok: true;
+    categories: KnowledgeCategory[];
+    folders: FolderProperties[];
+    relationPresets: RelationPreset[];
+    cards: Record<string, LifecycleQualification>;
+    reviewCards: ReviewCardSummary[];
+    resolvedFolders: Record<string, ReturnType<KnowledgeLifecycle['resolve']>>;
+  };
+  'category-set': { ok: true; category: KnowledgeCategory };
+  'category-remove': { ok: true; id: string };
+  'relation-preset-set': { ok: true; preset: RelationPreset };
+  'relation-preset-remove': { ok: true; id: string };
+  'folder-set': { ok: true; folder: FolderProperties };
+}
+export type LifecycleInput =
+  | { action: 'get'; id: string; board?: string }
+  | { action: 'set'; id: string; expectedBoardId?: string | null; lifecycleOverride: Lifecycle | null }
+  | {
+      action: 'review';
+      id: string;
+      expectedBoardId?: string | null;
+      outcome: Exclude<ReviewRecord['outcome'], 'restore'>;
+      evidence: string;
+      applied: boolean;
+      expectedContentRevision?: number;
+      expectedSources?: Record<string, number | null>;
+    }
+  | { action: 'restore'; id: string; expectedBoardId?: string | null; evidence: string };
+export interface LifecycleResults {
+  get: {
+    ok: true;
+    boardId: string;
+    nodeId: string;
+    contentRevision: number;
+    qualification: LifecycleQualification;
+  } & ReturnType<KnowledgeLifecycle['resolve']> &
+    ReturnType<KnowledgeLifecycle['reviews']>;
+  set: { ok: true };
+  review: { ok: true; record: ReviewRecord };
+  restore: { ok: true; record: ReviewRecord };
+}
+
+/** Workspace-owned data, deliberately outside board snapshots and read clocks. */
+export class KnowledgeLifecycle {
+  constructor(
+    private readonly getDb: () => Database | null,
+    private readonly changed: () => void,
+    private readonly getContentRevision: (boardId: string, nodeId: string) => number,
+    private readonly flush: () => void,
+  ) {}
+
+  private db(): Database {
+    const db = this.getDb();
+    if (!db) throw new Error('Knowledge lifecycle requires a workspace database.');
+    return db;
+  }
+
+  list(): { categories: KnowledgeCategory[]; folders: FolderProperties[]; relationPresets: RelationPreset[] } {
+    const db = this.db();
+    const read = <T>(table: string): T[] =>
+      (db.query(`SELECT value FROM ${table} ORDER BY 1`).all() as { value: string }[]).map((r) => JSON.parse(r.value));
+    const stored = db.query("SELECT value FROM meta WHERE key = 'relation-presets'").get() as { value: string } | null;
+    const relationPresets: RelationPreset[] = stored
+      ? JSON.parse(stored.value)
+      : Object.entries(RELATION_PRESETS).map(([name, vocabulary]) => ({
+          id: name,
+          name,
+          vocabulary: structuredClone(vocabulary),
+        }));
+    return { categories: read('knowledge_categories'), folders: read('folder_properties'), relationPresets };
+  }
+
+  setRelationPreset(value: RelationPreset): RelationPreset {
+    const preset = relationPresetSchema.parse(value);
+    const presets = this.list().relationPresets;
+    if (presets.some((item) => item.id !== preset.id && item.name === preset.name))
+      throw new OperationError('Relation preset names must be unique.', 409);
+    const index = presets.findIndex((item) => item.id === preset.id);
+    if (index < 0) presets.push(preset);
+    else presets[index] = preset;
+    this.db()
+      .query('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)')
+      .run('relation-presets', JSON.stringify(presets));
+    this.changed();
+    return preset;
+  }
+
+  removeRelationPreset(id: string): string {
+    const presets = this.list().relationPresets;
+    if (!presets.some((preset) => preset.id === id)) throw new OperationError('Unknown relation preset.', 404);
+    this.db()
+      .query('INSERT OR REPLACE INTO meta (key, value) VALUES (?, ?)')
+      .run('relation-presets', JSON.stringify(presets.filter((preset) => preset.id !== id)));
+    this.changed();
+    return id;
+  }
+
+  setCategory(value: KnowledgeCategory): KnowledgeCategory {
+    const category = categorySchema.parse(value);
+    this.db()
+      .query('INSERT OR REPLACE INTO knowledge_categories VALUES (?, ?)')
+      .run(category.id, JSON.stringify(category));
+    this.changed();
+    return category;
+  }
+
+  removeCategory(id: string): string {
+    const catalog = this.list();
+    if (!catalog.categories.some((category) => category.id === id))
+      throw new OperationError(`Unknown knowledge category: ${id}.`, 404);
+    const folders = catalog.folders.filter((folder) => folder.categoryId === id);
+    if (folders.length)
+      throw new OperationError(
+        `Category is assigned to folders: ${folders.map((folder) => folder.path).join(', ')}. Reassign or clear these folder categories before deleting it. Empty folders also count.`,
+        409,
+      );
+    this.db().query('DELETE FROM knowledge_categories WHERE id = ?').run(id);
+    this.changed();
+    return id;
+  }
+
+  setFolder(value: FolderProperties): FolderProperties {
+    const path = normalizeBoardFolder(value.path);
+    if (!path) throw new Error('A folder path is required.');
+    if (value.categoryId !== null && !this.list().categories.some((c) => c.id === value.categoryId)) {
+      throw new Error('Unknown knowledge category.');
+    }
+    const folder = {
+      path,
+      categoryId: value.categoryId,
+      lifecycleOverride: value.lifecycleOverride === null ? null : lifecycleSchema.parse(value.lifecycleOverride),
+    };
+    this.db().query('INSERT OR REPLACE INTO folder_properties VALUES (?, ?)').run(path, JSON.stringify(folder));
+    this.changed();
+    return folder;
+  }
+
+  resolve(folderPath: string | null, override?: Lifecycle | null, catalog = this.list()) {
+    const { categories, folders } = catalog;
+    let category: KnowledgeCategory | null = null;
+    let categorySourceFolder: string | null = null;
+    let lifecycle: Lifecycle | null = null;
+    let lifecycleSourceFolder: string | null = null;
+    const parts = normalizeBoardFolder(folderPath)?.split('/') ?? [];
+    for (let i = 1; i <= parts.length; i++) {
+      const path = parts.slice(0, i).join('/');
+      const properties = folders.find((f) => f.path === path);
+      if (!properties) continue;
+      if (properties.categoryId !== null) {
+        category = categories.find((c) => c.id === properties.categoryId) ?? null;
+        categorySourceFolder = category ? path : null;
+        lifecycle = category
+          ? {
+              decayType: category.decayType,
+              rate: category.rate,
+              triggers: category.triggers,
+              revalidationMethod: category.revalidationMethod,
+              ...(category.cadenceDays ? { cadenceDays: category.cadenceDays } : {}),
+            }
+          : null;
+        lifecycleSourceFolder = category ? path : null;
+      }
+      if (properties.lifecycleOverride) {
+        lifecycle = properties.lifecycleOverride;
+        lifecycleSourceFolder = path;
+      }
+    }
+    return {
+      category,
+      categorySourceFolder,
+      lifecycle: override ?? lifecycle,
+      lifecycleSourceFolder: override ? null : lifecycleSourceFolder,
+      lifecycleSource: override ? ('card' as const) : lifecycle ? ('folder' as const) : ('unknown' as const),
+    };
+  }
+
+  resolveCard(folderPath: string | null, node: Pick<CanvasNodeState, 'type' | 'data'>, catalog = this.list()) {
+    const resolved = this.resolve(folderPath, node.data.lifecycleOverride as Lifecycle | null, catalog);
+    if ((node.type === 'group' || node.type === 'board') && !node.data.lifecycleOverride) {
+      return { ...resolved, lifecycle: null, lifecycleSource: 'unknown' as const, lifecycleSourceFolder: null };
+    }
+    return resolved;
+  }
+
+  reviews(boardId: string, nodeId: string) {
+    const records = (
+      this.db()
+        .query('SELECT value FROM review_records WHERE board_id = ? AND node_id = ? ORDER BY sequence')
+        .all(boardId, nodeId) as { value: string }[]
+    ).map((r): ReviewRecord => {
+      const record = JSON.parse(r.value) as ReviewRecord;
+      return { ...record, contentRevision: record.contentRevision ?? null };
+    });
+    let retired = false;
+    let lastValidation: ReviewRecord | null = null;
+    for (const record of records) {
+      if (record.applied && record.outcome === 'retire') retired = true;
+      if (record.outcome === 'restore') retired = false;
+      if (record.applied && record.evidence.trim() && ['retain', 'revise', 'externalize'].includes(record.outcome))
+        lastValidation = record;
+    }
+    return { records, retired, lastValidation };
+  }
+
+  record(
+    boardId: string,
+    nodeId: string,
+    input: Pick<ReviewRecord, 'outcome' | 'evidence' | 'applied'> & { expectedContentRevision?: number },
+    sourceRevisions?: Record<string, number | null>,
+  ): ReviewRecord {
+    const validated = z
+      .object({
+        outcome: z.enum(['retain', 'revise', 'externalize', 'retire', 'unresolved', 'restore']),
+        evidence: z.string(),
+        applied: z.boolean(),
+        expectedContentRevision: z.number().int().nonnegative().optional(),
+      })
+      .parse(input);
+    if (validated.outcome === 'restore' && !validated.applied) throw new Error('Restore must be explicitly applied.');
+    const { expectedContentRevision, ...outcome } = validated;
+    const contentRevision = this.getContentRevision(boardId, nodeId);
+    const validates =
+      outcome.applied && outcome.evidence.trim() && ['retain', 'revise', 'externalize'].includes(outcome.outcome);
+    if (validates && expectedContentRevision === undefined)
+      throw new OperationError('Validating reviews require expectedContentRevision from the content you checked.');
+    if (expectedContentRevision !== undefined && expectedContentRevision !== contentRevision)
+      throw new OperationError('This card changed. Check its current content before recording your review.', 409);
+    // Do not persist evidence before the content it supports has successfully reached disk.
+    this.flush();
+    const record = {
+      ...outcome,
+      id: crypto.randomUUID(),
+      boardId,
+      nodeId,
+      who: currentActor(),
+      when: new Date().toISOString(),
+      contentRevision,
+      ...(sourceRevisions ? { sourceRevisions } : {}),
+    };
+    this.db()
+      .query('INSERT INTO review_records (board_id, node_id, value) VALUES (?, ?, ?)')
+      .run(boardId, nodeId, JSON.stringify(record));
+    this.changed();
+    return record;
+  }
+}

package/src/server/lifecycle-status.ts

@@ -0,0 +1,232 @@
+import { memoryKey, type MemoryTarget } from '../shared/memory-graph.js';
+import { relationKind, relationSourceEnd } from '../shared/relations.js';
+import type { LifecycleQualification } from '../shared/lifecycle-status.js';
+import { canvasState, type CanvasNodeState } from './canvas-state.js';
+import type { Lifecycle, ReviewCardSummary, ReviewRecord } from './knowledge-lifecycle.js';
+import { normalizeCanvasNodeData, type CanvasNodeProvenance } from './canvas-provenance.js';
+import { agentPresence } from './agent-presence.js';
+
+const processStartedAt = Date.now();
+
+interface Source {
+  key: string;
+  target: MemoryTarget;
+  baseline?: number;
+  kind: string;
+  observedAt?: string;
+  availability?: 'live' | 'cached' | 'unavailable';
+}
+
+/** A read-only qualification, shared by briefs, search, Home and card review. No clock is renewed. */
+export function lifecycleQualifications(
+  now = Date.now(),
+  atUse: MemoryTarget[] = [],
+): Record<string, LifecycleQualification> {
+  return lifecycleSnapshot(now, atUse).cards;
+}
+
+/** Compact queue metadata and qualifications come from the same authoritative read. */
+export function lifecycleSnapshot(now = Date.now(), atUse: MemoryTarget[] = []) {
+  const result: Record<string, LifecycleQualification> = {};
+  const cards = new Map<string, CanvasNodeState>();
+  const validations = new Map<string, ReviewRecord | null>();
+  const sources = new Map<string, Source[]>();
+  const portals = new Map<string, string>();
+  const policies = new Map<string, Lifecycle | null>();
+  const used = new Set<string>();
+  const reads = canvasState.listBoards().map((board) => ({ board, read: canvasState.readBoard(board.id, false) }));
+  const catalog = canvasState.databasePath
+    ? canvasState.knowledge.list()
+    : { categories: [], folders: [], relationPresets: [] };
+  const session =
+    agentPresence.reviewSessionStartedAt() ??
+    Date.parse(
+      reads.find(({ board }) => board.id === canvasState.activeBoardId)?.board.lastOpenedAt ??
+        new Date(processStartedAt).toISOString(),
+    );
+  for (const { board, read } of reads) {
+    const seen = new Map(canvasState.getNodeReadStatus(board.id).map((status) => [status.nodeId, status]));
+    for (const node of read?.layout.nodes ?? []) {
+      const key = memoryKey({ boardId: board.id, cardId: node.id });
+      cards.set(key, node);
+      const { lifecycle } = canvasState.knowledge.resolveCard(board.folder, node, catalog);
+      policies.set(key, lifecycle);
+      const { lastValidation, retired } = canvasState.databasePath
+        ? canvasState.knowledge.reviews(board.id, node.id)
+        : { lastValidation: null, retired: false };
+      validations.set(key, lastValidation);
+      const lastRead = seen.get(node.id);
+      const pinned = read!.state.contextPins.includes(node.id);
+      if (
+        canvasState.activeBoardId === board.id ||
+        board.pin ||
+        atUse.some((target) => target.boardId === board.id && (!target.cardId || target.cardId === node.id))
+      )
+        used.add(key);
+      const reasons: string[] = [];
+      if (lastValidation && lastValidation.contentRevision !== (node.contentRevision ?? 0))
+        reasons.push('Content changed since evidence validation.');
+      result[key] = {
+        retired,
+        unknown: !lifecycle,
+        due: false,
+        reasons,
+        changedSinceRead: !!lastRead && (node.contentRevision ?? 0) > lastRead.readRevision,
+        lastReadAt: lastRead?.lastReadAt ?? null,
+        lastValidatedAt: lastValidation?.when ?? null,
+        contentRevision: node.contentRevision ?? 0,
+        contentChangedAt: node.contentChangedAt ?? null,
+        observations: {},
+        sources: [],
+        relevance: pinned ? 'card-pinned' : board.pin ? 'board-pinned' : 'not-selected',
+      };
+      if (node.type === 'board' && typeof node.data.boardId === 'string') portals.set(key, node.data.boardId);
+      const provenance = normalizeCanvasNodeData(node.type, node.data).provenance as CanvasNodeProvenance | undefined;
+      for (const source of provenance?.sources ?? []) {
+        const existing = sources.get(key) ?? [];
+        existing.push({
+          key: `provenance:${memoryKey(source)}`,
+          target: { boardId: source.boardId, cardId: source.cardId },
+          baseline: source.contentRevision,
+          observedAt: source.observedAt,
+          availability: source.availability,
+          kind: 'derived-from',
+        });
+        sources.set(key, existing);
+      }
+    }
+    for (const edge of read?.layout.edges ?? []) {
+      const end = relationSourceEnd(edge);
+      if (!end) continue;
+      const from = { boardId: board.id, cardId: edge.from };
+      const to = { boardId: edge.toBoardId ?? board.id, cardId: edge.to };
+      const target = end === 'from' ? from : to;
+      const dependent = memoryKey(end === 'from' ? to : from);
+      const kind = relationKind(edge);
+      const existing = sources.get(dependent) ?? [];
+      existing.push({
+        key: JSON.stringify([board.id, edge.id, kind, memoryKey(target)]),
+        target,
+        kind,
+        baseline: edge.sourceRevision,
+      });
+      sources.set(dependent, existing);
+    }
+  }
+  for (const key of used) {
+    for (const source of sources.get(key) ?? []) used.add(memoryKey(source.target));
+    const portal = portals.get(key);
+    if (portal)
+      for (const node of reads.find(({ board }) => board.id === portal)?.read?.layout.nodes ?? [])
+        used.add(memoryKey({ boardId: portal, cardId: node.id }));
+  }
+  for (const [key, status] of Object.entries(result)) {
+    const policy = policies.get(key);
+    if (!policy) continue;
+    const checked = status.lastValidatedAt ? Date.parse(status.lastValidatedAt) : null;
+    const authored = cards.get(key)?.freshnessStartedAt;
+    const freshSince = checked ?? (authored ? Date.parse(authored) : null);
+    if (policy.rate === 'fast' && used.has(key) && (freshSince === null || freshSince < session))
+      status.reasons.push('Fast: check at use.');
+    if (
+      policy.rate === 'medium' &&
+      policy.cadenceDays &&
+      (freshSince === null || now - freshSince >= policy.cadenceDays * 86400000)
+    )
+      status.reasons.push(
+        `Review every ${policy.cadenceDays} days${freshSince === null ? '; no freshness baseline' : ''}.`,
+      );
+    if (policy.rate === 'slow' && used.has(key) && (freshSince === null || freshSince < session))
+      status.reasons.push('Slow: review on resumed work.');
+  }
+  for (const [key, dependencies] of sources) {
+    const status = result[key];
+    if (!status) continue;
+    const validation = validations.get(key);
+    for (const source of dependencies) {
+      const current = cards.get(memoryKey(source.target));
+      const revision = source.availability === 'unavailable' ? null : (current?.contentRevision ?? null);
+      status.observations[source.key] = revision;
+      const observed = validation ? validation.sourceRevisions?.[source.key] : source.baseline;
+      const title = current ? String(current.data.title ?? current.id) : 'Unavailable source';
+      if (!current) status.reasons.push('A dependency source is unavailable; no fresh check.');
+      else if (source.availability === 'unavailable')
+        status.reasons.push(`${title}: source unavailable; cached content is not a fresh check.`);
+      else if (observed !== revision || (!validation && ['contradicts', 'supersedes'].includes(source.kind)))
+        status.reasons.push(`${source.kind}: ${title}${observed === undefined ? ' needs review' : ' changed'}.`);
+    }
+  }
+  // Fixed point, not recursive traversal: cycles cannot overflow and unrelated links never propagate.
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const [key, status] of Object.entries(result)) {
+      if (status.due || status.retired) continue;
+      const sourceDue = (sources.get(key) ?? []).some((source) => {
+        const upstream = result[memoryKey(source.target)];
+        return upstream?.due || upstream?.retired;
+      });
+      if (status.reasons.length || sourceDue) {
+        if (sourceDue) status.reasons.push('An explicit source needs review.');
+        status.due = true;
+        changed = true;
+      }
+    }
+  }
+  for (const [key, status] of Object.entries(result)) {
+    const references: Source[] = [...(sources.get(key) ?? [])];
+    const boardId = portals.get(key);
+    if (boardId) {
+      const board = reads.find((entry) => entry.board.id === boardId);
+      if (!board?.read) references.push({ key: boardId, target: { boardId }, kind: 'portal' });
+      else
+        for (const node of board.read.layout.nodes)
+          references.push({ key: node.id, target: { boardId, cardId: node.id }, kind: 'portal' });
+    }
+    for (const source of references) {
+      const sourceKey = memoryKey(source.target);
+      const qualification = result[sourceKey];
+      const node = cards.get(sourceKey);
+      if (
+        qualification &&
+        !qualification.due &&
+        !qualification.retired &&
+        source.availability !== 'cached' &&
+        source.availability !== 'unavailable'
+      )
+        continue;
+      status.sources.push({
+        ...source.target,
+        title: node ? String(node.data.title ?? node.id) : 'Unavailable source',
+        reasons:
+          source.availability === 'unavailable'
+            ? ['Source unavailable; no fresh check.']
+            : source.availability === 'cached'
+              ? ['Cached observation; not freshly checked.', ...(qualification?.reasons ?? [])]
+              : qualification
+                ? qualification.retired
+                  ? ['Source is retired.']
+                  : qualification.reasons
+                : ['Source unavailable; no fresh check.'],
+        ...(node ? { contentRevision: node.contentRevision ?? 0 } : { unavailable: true as const }),
+        ...(source.baseline !== undefined ? { observedRevision: source.baseline } : {}),
+        ...(source.observedAt ? { observedAt: source.observedAt } : {}),
+      });
+    }
+  }
+  const reviewCards: ReviewCardSummary[] = [];
+  for (const { board, read } of reads) {
+    for (const node of read?.layout.nodes ?? []) {
+      const status = result[memoryKey({ boardId: board.id, cardId: node.id })];
+      if (status.retired || !(status.due || status.sources.length)) continue;
+      reviewCards.push({
+        boardId: board.id,
+        cardId: node.id,
+        boardTitle: board.name,
+        folder: board.folder,
+        title: String(node.data.title || 'Untitled card'),
+      });
+    }
+  }
+  return { cards: result, reviewCards };
+}