pmx-canvas 0.1.26 → 0.1.28

package/src/server/ax-state.ts

@@ -10,9 +10,137 @@ export interface PmxAxFocusState {
   source: PmxAxSource | null;
 }
 
+// ── New enums ──────────────────────────────────────────────────────
+export type PmxAxEventKind =
+  | 'prompt' | 'assistant-message' | 'tool-start' | 'tool-result'
+  | 'failure' | 'approval' | 'steering';
+export type PmxAxEvidenceKind =
+  | 'logs' | 'tool-result' | 'screenshot' | 'file' | 'diff' | 'test-output';
+export type PmxAxWorkItemStatus = 'todo' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
+export type PmxAxApprovalStatus = 'pending' | 'approved' | 'rejected';
+export type PmxAxReviewKind = 'comment' | 'finding';
+export type PmxAxReviewSeverity = 'info' | 'warning' | 'error';
+export type PmxAxReviewStatus = 'open' | 'resolved' | 'dismissed';
+export type PmxAxReviewAnchorType = 'node' | 'file' | 'region';
+
+// ── Canvas-bound records (live inside PmxAxState; snapshotted) ──────
+export interface PmxAxWorkItem {
+  id: string;
+  title: string;
+  status: PmxAxWorkItemStatus;
+  detail: string | null;
+  nodeIds: string[];
+  createdAt: string;
+  updatedAt: string;
+  source: PmxAxSource | null;
+}
+
+export interface PmxAxApprovalGate {
+  id: string;
+  title: string;
+  detail: string | null;
+  action: string | null;
+  status: PmxAxApprovalStatus;
+  nodeIds: string[];
+  createdAt: string;
+  resolvedAt: string | null;
+  resolution: string | null;
+  source: PmxAxSource | null;
+}
+
+export interface PmxAxReviewRegion {
+  line?: number;
+  endLine?: number;
+  label?: string;
+}
+
+export interface PmxAxReviewAnnotation {
+  id: string;
+  kind: PmxAxReviewKind;
+  body: string;
+  severity: PmxAxReviewSeverity;
+  status: PmxAxReviewStatus;
+  anchorType: PmxAxReviewAnchorType;
+  nodeId: string | null;
+  file: string | null;
+  region: PmxAxReviewRegion | null;
+  author: string | null;
+  createdAt: string;
+  updatedAt: string;
+  source: PmxAxSource | null;
+}
+
+// ── Timeline records (separate DB tables; NOT in PmxAxState) ────────
+export interface PmxAxEvent {
+  id: string;
+  seq: number;
+  kind: PmxAxEventKind;
+  summary: string;
+  detail: string | null;
+  nodeIds: string[];
+  data: Record<string, unknown> | null;
+  createdAt: string;
+  source: PmxAxSource | null;
+}
+
+export interface PmxAxEvidence {
+  id: string;
+  seq: number;
+  kind: PmxAxEvidenceKind;
+  title: string;
+  body: string | null;
+  ref: string | null;
+  nodeIds: string[];
+  data: Record<string, unknown> | null;
+  createdAt: string;
+  source: PmxAxSource | null;
+}
+
+export interface PmxAxSteeringMessage {
+  id: string;
+  seq: number;
+  message: string;
+  delivered: boolean;
+  createdAt: string;
+  source: PmxAxSource | null;
+}
+
+// ── Host/session capability (own table; reported by adapters) ──────
+export interface PmxAxHostCapability {
+  host: string | null;
+  canvas: boolean;
+  hooks: boolean;
+  tools: boolean;
+  sessionMessaging: boolean;
+  permissions: boolean;
+  files: boolean;
+  uiPrompts: boolean;
+  reportedAt: string | null;
+  raw: Record<string, unknown> | null;
+}
+
+// ── Bounded timeline summary for context export ────────────────────
+export interface PmxAxTimelineSummary {
+  recentEvents: PmxAxEvent[];
+  recentEvidence: PmxAxEvidence[];
+  pendingSteering: PmxAxSteeringMessage[];
+  counts: { events: number; evidence: number; steering: number };
+}
+
+// ── Constants ──────────────────────────────────────────────────────
+export const AX_TIMELINE_RETENTION = 500;
+export const AX_TIMELINE_DEFAULT_LIMIT = 50;
+export const AX_TIMELINE_MAX_LIMIT = 200;
+export const AX_CONTEXT_EVENT_LIMIT = 20;
+export const AX_CONTEXT_EVIDENCE_LIMIT = 10;
+export const AX_CONTEXT_STEERING_LIMIT = 10;
+
 export interface PmxAxState {
   version: 1;
   focus: PmxAxFocusState;
+  workItems: PmxAxWorkItem[];
+  approvalGates: PmxAxApprovalGate[];
+  reviewAnnotations: PmxAxReviewAnnotation[];
 }
 
 export interface PmxAxPinnedContext {
@@ -35,6 +163,11 @@ export interface PmxAxContext {
   };
   pinned: PmxAxPinnedContext;
   focus: PmxAxFocusContext;
+  workItems: PmxAxWorkItem[];
+  approvalGates: PmxAxApprovalGate[];
+  reviewAnnotations: PmxAxReviewAnnotation[];
+  timeline: PmxAxTimelineSummary;
+  host: PmxAxHostCapability | null;
 }
 
 const AX_SOURCES = new Set<PmxAxSource>(['agent', 'api', 'browser', 'cli', 'codex', 'copilot', 'mcp', 'sdk', 'system']);
@@ -66,6 +199,39 @@ function normalizeNodeIds(value: unknown, validNodeIds?: Set<string>): string[]
   return ids;
 }
 
+const AX_EVENT_KINDS = new Set<PmxAxEventKind>(['prompt', 'assistant-message', 'tool-start', 'tool-result', 'failure', 'approval', 'steering']);
+const AX_EVIDENCE_KINDS = new Set<PmxAxEvidenceKind>(['logs', 'tool-result', 'screenshot', 'file', 'diff', 'test-output']);
+const AX_WORK_STATUSES = new Set<PmxAxWorkItemStatus>(['todo', 'in-progress', 'blocked', 'done', 'cancelled']);
+const AX_APPROVAL_STATUSES = new Set<PmxAxApprovalStatus>(['pending', 'approved', 'rejected']);
+const AX_REVIEW_KINDS = new Set<PmxAxReviewKind>(['comment', 'finding']);
+const AX_REVIEW_SEVERITIES = new Set<PmxAxReviewSeverity>(['info', 'warning', 'error']);
+const AX_REVIEW_STATUSES = new Set<PmxAxReviewStatus>(['open', 'resolved', 'dismissed']);
+const AX_REVIEW_ANCHORS = new Set<PmxAxReviewAnchorType>(['node', 'file', 'region']);
+
+export function isAxEventKind(value: unknown): value is PmxAxEventKind {
+  return typeof value === 'string' && AX_EVENT_KINDS.has(value as PmxAxEventKind);
+}
+
+export function isAxEvidenceKind(value: unknown): value is PmxAxEvidenceKind {
+  return typeof value === 'string' && AX_EVIDENCE_KINDS.has(value as PmxAxEvidenceKind);
+}
+
+function nowIso(): string {
+  return new Date().toISOString();
+}
+
+function optionalString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null;
+}
+
+function boundedRecord(value: unknown): Record<string, unknown> | null {
+  return isRecord(value) ? value : null;
+}
+
+function axId(prefix: string): string {
+  return `${prefix}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
 export function createEmptyAxFocusState(): PmxAxFocusState {
   return {
     nodeIds: [],
@@ -79,6 +245,24 @@ export function createEmptyAxState(): PmxAxState {
   return {
     version: 1,
     focus: createEmptyAxFocusState(),
+    workItems: [],
+    approvalGates: [],
+    reviewAnnotations: [],
+  };
+}
+
+export function createEmptyAxHostCapability(): PmxAxHostCapability {
+  return {
+    host: null,
+    canvas: false,
+    hooks: false,
+    tools: false,
+    sessionMessaging: false,
+    permissions: false,
+    files: false,
+    uiPrompts: false,
+    reportedAt: null,
+    raw: null,
   };
 }
 
@@ -96,11 +280,264 @@ export function normalizeAxFocusState(input: unknown, validNodeIds?: Set<string>
   };
 }
 
+// ── Canvas-bound normalizers (drop on missing id) ──────────────────
+export function normalizeAxWorkItem(input: unknown, validNodeIds?: Set<string>): PmxAxWorkItem | null {
+  if (!isRecord(input) || typeof input.id !== 'string') return null;
+  const createdAt = normalizeTimestamp(input.createdAt) ?? nowIso();
+  return {
+    id: input.id,
+    title: typeof input.title === 'string' ? input.title : '(untitled)',
+    status: AX_WORK_STATUSES.has(input.status as PmxAxWorkItemStatus) ? input.status as PmxAxWorkItemStatus : 'todo',
+    detail: optionalString(input.detail),
+    nodeIds: normalizeNodeIds(input.nodeIds, validNodeIds),
+    createdAt,
+    updatedAt: normalizeTimestamp(input.updatedAt) ?? createdAt,
+    source: normalizeSource(input.source),
+  };
+}
+
+export function normalizeAxApprovalGate(input: unknown, validNodeIds?: Set<string>): PmxAxApprovalGate | null {
+  if (!isRecord(input) || typeof input.id !== 'string') return null;
+  return {
+    id: input.id,
+    title: typeof input.title === 'string' ? input.title : '(approval)',
+    detail: optionalString(input.detail),
+    action: optionalString(input.action),
+    status: AX_APPROVAL_STATUSES.has(input.status as PmxAxApprovalStatus) ? input.status as PmxAxApprovalStatus : 'pending',
+    nodeIds: normalizeNodeIds(input.nodeIds, validNodeIds),
+    createdAt: normalizeTimestamp(input.createdAt) ?? nowIso(),
+    resolvedAt: normalizeTimestamp(input.resolvedAt),
+    resolution: optionalString(input.resolution),
+    source: normalizeSource(input.source),
+  };
+}
+
+export function normalizeAxReviewAnnotation(input: unknown, validNodeIds?: Set<string>): PmxAxReviewAnnotation | null {
+  if (!isRecord(input) || typeof input.id !== 'string') return null;
+  const createdAt = normalizeTimestamp(input.createdAt) ?? nowIso();
+  const anchorType = AX_REVIEW_ANCHORS.has(input.anchorType as PmxAxReviewAnchorType) ? input.anchorType as PmxAxReviewAnchorType : 'node';
+  // node anchor pruned to a valid node; if invalid, drop the whole annotation (mirrors focus pruning)
+  let nodeId: string | null = null;
+  if (anchorType === 'node') {
+    if (typeof input.nodeId !== 'string') return null;
+    if (validNodeIds && !validNodeIds.has(input.nodeId)) return null;
+    nodeId = input.nodeId;
+  }
+  const region = isRecord(input.region) ? {
+    ...(typeof input.region.line === 'number' ? { line: input.region.line } : {}),
+    ...(typeof input.region.endLine === 'number' ? { endLine: input.region.endLine } : {}),
+    ...(typeof input.region.label === 'string' ? { label: input.region.label } : {}),
+  } : null;
+  return {
+    id: input.id,
+    kind: AX_REVIEW_KINDS.has(input.kind as PmxAxReviewKind) ? input.kind as PmxAxReviewKind : 'comment',
+    body: typeof input.body === 'string' ? input.body : '',
+    severity: AX_REVIEW_SEVERITIES.has(input.severity as PmxAxReviewSeverity) ? input.severity as PmxAxReviewSeverity : 'info',
+    status: AX_REVIEW_STATUSES.has(input.status as PmxAxReviewStatus) ? input.status as PmxAxReviewStatus : 'open',
+    anchorType,
+    nodeId,
+    file: anchorType === 'file' ? optionalString(input.file) : null,
+    region: anchorType === 'region' ? region : null,
+    author: optionalString(input.author),
+    createdAt,
+    updatedAt: normalizeTimestamp(input.updatedAt) ?? createdAt,
+    source: normalizeSource(input.source),
+  };
+}
+
+export function normalizeAxHostCapability(input: unknown): PmxAxHostCapability | null {
+  if (!isRecord(input)) return null;
+  const caps = isRecord(input.capabilities) ? input.capabilities : input;
+  const flag = (v: unknown): boolean => v === true;
+  return {
+    host: optionalString(input.host),
+    canvas: flag(caps.canvas),
+    hooks: flag(caps.hooks),
+    tools: flag(caps.tools),
+    sessionMessaging: flag(caps.sessionMessaging),
+    permissions: flag(caps.permissions),
+    files: flag(caps.files),
+    uiPrompts: flag(caps.uiPrompts),
+    reportedAt: normalizeTimestamp(input.reportedAt),
+    raw: boundedRecord(input.raw),
+  };
+}
+
+// ── Timeline normalizers (DB row parse; node ids kept as recorded) ──
+export function normalizeAxEvent(input: unknown): PmxAxEvent | null {
+  if (!isRecord(input) || typeof input.id !== 'string') return null;
+  const kind = AX_EVENT_KINDS.has(input.kind as PmxAxEventKind) ? input.kind as PmxAxEventKind : null;
+  if (!kind) return null;
+  return {
+    id: input.id,
+    seq: typeof input.seq === 'number' ? input.seq : 0,
+    kind,
+    summary: typeof input.summary === 'string' ? input.summary : '',
+    detail: optionalString(input.detail),
+    nodeIds: normalizeNodeIds(input.nodeIds),
+    data: boundedRecord(input.data),
+    createdAt: normalizeTimestamp(input.createdAt) ?? nowIso(),
+    source: normalizeSource(input.source),
+  };
+}
+
+export function normalizeAxEvidence(input: unknown): PmxAxEvidence | null {
+  if (!isRecord(input) || typeof input.id !== 'string') return null;
+  const kind = AX_EVIDENCE_KINDS.has(input.kind as PmxAxEvidenceKind) ? input.kind as PmxAxEvidenceKind : null;
+  if (!kind) return null;
+  return {
+    id: input.id,
+    seq: typeof input.seq === 'number' ? input.seq : 0,
+    kind,
+    title: typeof input.title === 'string' ? input.title : '',
+    body: typeof input.body === 'string' ? input.body : null,
+    ref: optionalString(input.ref),
+    nodeIds: normalizeNodeIds(input.nodeIds),
+    data: boundedRecord(input.data),
+    createdAt: normalizeTimestamp(input.createdAt) ?? nowIso(),
+    source: normalizeSource(input.source),
+  };
+}
+
+export function normalizeAxSteeringMessage(input: unknown): PmxAxSteeringMessage | null {
+  if (!isRecord(input) || typeof input.id !== 'string' || typeof input.message !== 'string') return null;
+  return {
+    id: input.id,
+    seq: typeof input.seq === 'number' ? input.seq : 0,
+    message: input.message,
+    delivered: input.delivered === true,
+    createdAt: normalizeTimestamp(input.createdAt) ?? nowIso(),
+    source: normalizeSource(input.source),
+  };
+}
+
+// ── Factories ──────────────────────────────────────────────────────
+export function createAxWorkItem(
+  input: { title: string; status?: PmxAxWorkItemStatus; detail?: string | null; nodeIds?: string[] },
+  source: PmxAxSource | null,
+  validNodeIds?: Set<string>,
+): PmxAxWorkItem {
+  const now = nowIso();
+  return {
+    id: axId('work'),
+    title: input.title,
+    status: input.status ?? 'todo',
+    detail: input.detail ?? null,
+    nodeIds: normalizeNodeIds(input.nodeIds, validNodeIds),
+    createdAt: now,
+    updatedAt: now,
+    source,
+  };
+}
+
+export function createAxApprovalGate(
+  input: { title: string; detail?: string | null; action?: string | null; nodeIds?: string[] },
+  source: PmxAxSource | null,
+  validNodeIds?: Set<string>,
+): PmxAxApprovalGate {
+  return {
+    id: axId('appr'),
+    title: input.title,
+    detail: input.detail ?? null,
+    action: input.action ?? null,
+    status: 'pending',
+    nodeIds: normalizeNodeIds(input.nodeIds, validNodeIds),
+    createdAt: nowIso(),
+    resolvedAt: null,
+    resolution: null,
+    source,
+  };
+}
+
+export function createAxReviewAnnotation(
+  input: {
+    body: string;
+    kind?: PmxAxReviewKind;
+    severity?: PmxAxReviewSeverity;
+    anchorType?: PmxAxReviewAnchorType;
+    nodeId?: string | null;
+    file?: string | null;
+    region?: PmxAxReviewRegion | null;
+    author?: string | null;
+  },
+  source: PmxAxSource | null,
+): PmxAxReviewAnnotation {
+  const now = nowIso();
+  const anchorType = input.anchorType ?? 'node';
+  return {
+    id: axId('rev'),
+    kind: input.kind ?? 'comment',
+    body: input.body,
+    severity: input.severity ?? 'info',
+    status: 'open',
+    anchorType,
+    nodeId: anchorType === 'node' ? (input.nodeId ?? null) : null,
+    file: anchorType === 'file' ? (input.file ?? null) : null,
+    region: anchorType === 'region' ? (input.region ?? null) : null,
+    author: input.author ?? null,
+    createdAt: now,
+    updatedAt: now,
+    source,
+  };
+}
+
+export function createAxEvent(
+  input: { kind: PmxAxEventKind; summary: string; detail?: string | null; nodeIds?: string[]; data?: Record<string, unknown> | null },
+  source: PmxAxSource | null,
+): Omit<PmxAxEvent, 'seq'> {
+  return {
+    id: axId('evt'),
+    kind: input.kind,
+    summary: input.summary,
+    detail: input.detail ?? null,
+    nodeIds: normalizeNodeIds(input.nodeIds),
+    data: input.data ?? null,
+    createdAt: nowIso(),
+    source,
+  };
+}
+
+export function createAxEvidence(
+  input: { kind: PmxAxEvidenceKind; title: string; body?: string | null; ref?: string | null; nodeIds?: string[]; data?: Record<string, unknown> | null },
+  source: PmxAxSource | null,
+): Omit<PmxAxEvidence, 'seq'> {
+  return {
+    id: axId('evd'),
+    kind: input.kind,
+    title: input.title,
+    body: input.body ?? null,
+    ref: input.ref ?? null,
+    nodeIds: normalizeNodeIds(input.nodeIds),
+    data: input.data ?? null,
+    createdAt: nowIso(),
+    source,
+  };
+}
+
+export function createAxSteeringMessage(message: string, source: PmxAxSource | null): Omit<PmxAxSteeringMessage, 'seq'> {
+  return {
+    id: axId('steer'),
+    message,
+    delivered: false,
+    createdAt: nowIso(),
+    source,
+  };
+}
+
 export function normalizeAxState(input: unknown, validNodeIds?: Set<string>): PmxAxState {
   if (!isRecord(input)) return createEmptyAxState();
   return {
     version: 1,
     focus: normalizeAxFocusState(input.focus, validNodeIds),
+    workItems: Array.isArray(input.workItems)
+      ? input.workItems.map((w) => normalizeAxWorkItem(w, validNodeIds)).filter((w): w is PmxAxWorkItem => w !== null)
+      : [],
+    approvalGates: Array.isArray(input.approvalGates)
+      ? input.approvalGates.map((g) => normalizeAxApprovalGate(g, validNodeIds)).filter((g): g is PmxAxApprovalGate => g !== null)
+      : [],
+    reviewAnnotations: Array.isArray(input.reviewAnnotations)
+      ? input.reviewAnnotations.map((r) => normalizeAxReviewAnnotation(r, validNodeIds)).filter((r): r is PmxAxReviewAnnotation => r !== null)
+      : [],
   };
 }
 
@@ -109,6 +546,11 @@ export function buildAxContext(input: {
   pinned: PmxAxPinnedContext;
   focus: PmxAxFocusState;
   focusNodes: AgentContextNode[];
+  workItems: PmxAxWorkItem[];
+  approvalGates: PmxAxApprovalGate[];
+  reviewAnnotations: PmxAxReviewAnnotation[];
+  timeline: PmxAxTimelineSummary;
+  host: PmxAxHostCapability | null;
 }): PmxAxContext {
   return {
     version: 1,
@@ -122,6 +564,11 @@ export function buildAxContext(input: {
       ...input.focus,
       nodes: input.focusNodes,
     },
+    workItems: input.workItems,
+    approvalGates: input.approvalGates,
+    reviewAnnotations: input.reviewAnnotations,
+    timeline: input.timeline,
+    host: input.host,
   };
 }
 

package/src/server/canvas-db.ts

@@ -17,7 +17,26 @@ import type {
   CanvasSnapshotListOptions,
   ViewportState,
 } from './canvas-state.js';
-import { createEmptyAxState, normalizeAxState, type PmxAxState } from './ax-state.js';
+import {
+  createEmptyAxState,
+  normalizeAxState,
+  normalizeAxEvent,
+  normalizeAxEvidence,
+  normalizeAxSteeringMessage,
+  normalizeAxHostCapability,
+  AX_TIMELINE_RETENTION,
+  AX_TIMELINE_DEFAULT_LIMIT,
+  AX_TIMELINE_MAX_LIMIT,
+  AX_CONTEXT_EVENT_LIMIT,
+  AX_CONTEXT_EVIDENCE_LIMIT,
+  AX_CONTEXT_STEERING_LIMIT,
+  type PmxAxState,
+  type PmxAxEvent,
+  type PmxAxEvidence,
+  type PmxAxSteeringMessage,
+  type PmxAxHostCapability,
+  type PmxAxTimelineSummary,
+} from './ax-state.js';
 
 // ── Schema ──────────────────────────────────────────────────────
 
@@ -148,6 +167,49 @@ const SCHEMA_SQL = `
     data BLOB NOT NULL,
     json_bytes INTEGER NOT NULL
   );
+
+  CREATE TABLE IF NOT EXISTS ax_events (
+    seq INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    kind TEXT NOT NULL,
+    summary TEXT NOT NULL,
+    detail TEXT,
+    node_ids TEXT NOT NULL DEFAULT '[]',
+    data TEXT,
+    created_at TEXT NOT NULL,
+    source TEXT
+  );
+  CREATE INDEX IF NOT EXISTS idx_ax_events_seq ON ax_events (seq);
+
+  CREATE TABLE IF NOT EXISTS ax_evidence (
+    seq INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    kind TEXT NOT NULL,
+    title TEXT NOT NULL,
+    body TEXT,
+    ref TEXT,
+    node_ids TEXT NOT NULL DEFAULT '[]',
+    data TEXT,
+    created_at TEXT NOT NULL,
+    source TEXT
+  );
+  CREATE INDEX IF NOT EXISTS idx_ax_evidence_seq ON ax_evidence (seq);
+
+  CREATE TABLE IF NOT EXISTS ax_steering (
+    seq INTEGER PRIMARY KEY AUTOINCREMENT,
+    id TEXT NOT NULL UNIQUE,
+    message TEXT NOT NULL,
+    delivered INTEGER NOT NULL DEFAULT 0,
+    created_at TEXT NOT NULL,
+    source TEXT
+  );
+  CREATE INDEX IF NOT EXISTS idx_ax_steering_seq ON ax_steering (seq);
+
+  CREATE TABLE IF NOT EXISTS ax_host_capabilities (
+    host TEXT PRIMARY KEY,
+    reported_at TEXT NOT NULL,
+    payload TEXT NOT NULL
+  );
 `;
 
 function normalizePositiveInteger(value: number | undefined): number | undefined {
@@ -743,3 +805,124 @@ export function hasBlobInDB(db: Database, sha256: string): boolean {
   ).get(sha256);
   return (row?.c ?? 0) > 0;
 }
+
+// ── AX Timeline Persistence (NOT snapshotted; bounded by retention) ──
+
+function safeParseJson(raw: string | null | undefined): unknown {
+  if (!raw) return null;
+  try {
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+
+export interface AxTimelineQuery {
+  limit?: number;
+  sessionId?: string;
+}
+
+function clampTimelineLimit(limit: number | undefined): number {
+  if (typeof limit !== 'number' || !Number.isFinite(limit) || limit <= 0) return AX_TIMELINE_DEFAULT_LIMIT;
+  return Math.min(Math.floor(limit), AX_TIMELINE_MAX_LIMIT);
+}
+
+function trimAxTable(db: Database, table: 'ax_events' | 'ax_evidence' | 'ax_steering'): void {
+  db.run(
+    `DELETE FROM ${table} WHERE seq <= (SELECT seq FROM ${table} ORDER BY seq DESC LIMIT 1 OFFSET ?)`,
+    [AX_TIMELINE_RETENTION],
+  );
+}
+
+function readLastSeq(db: Database, table: 'ax_events' | 'ax_evidence' | 'ax_steering'): number {
+  const row = db.query<{ seq: number }, []>(`SELECT seq FROM ${table} ORDER BY seq DESC LIMIT 1`).get();
+  return row ? Number(row.seq) : 0;
+}
+
+export function appendAxEventToDB(db: Database, ev: Omit<PmxAxEvent, 'seq'>): PmxAxEvent {
+  db.run(
+    'INSERT INTO ax_events (id, kind, summary, detail, node_ids, data, created_at, source) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+    [ev.id, ev.kind, ev.summary, ev.detail, JSON.stringify(ev.nodeIds), ev.data ? JSON.stringify(ev.data) : null, ev.createdAt, ev.source],
+  );
+  const seq = readLastSeq(db, 'ax_events');
+  trimAxTable(db, 'ax_events');
+  return { ...ev, seq };
+}
+
+export function appendAxEvidenceToDB(db: Database, ev: Omit<PmxAxEvidence, 'seq'>): PmxAxEvidence {
+  db.run(
+    'INSERT INTO ax_evidence (id, kind, title, body, ref, node_ids, data, created_at, source) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    [ev.id, ev.kind, ev.title, ev.body, ev.ref, JSON.stringify(ev.nodeIds), ev.data ? JSON.stringify(ev.data) : null, ev.createdAt, ev.source],
+  );
+  const seq = readLastSeq(db, 'ax_evidence');
+  trimAxTable(db, 'ax_evidence');
+  return { ...ev, seq };
+}
+
+export function appendAxSteeringToDB(db: Database, s: Omit<PmxAxSteeringMessage, 'seq'>): PmxAxSteeringMessage {
+  db.run(
+    'INSERT INTO ax_steering (id, message, delivered, created_at, source) VALUES (?, ?, ?, ?, ?)',
+    [s.id, s.message, s.delivered ? 1 : 0, s.createdAt, s.source],
+  );
+  const seq = readLastSeq(db, 'ax_steering');
+  trimAxTable(db, 'ax_steering');
+  return { ...s, seq };
+}
+
+export function markAxSteeringDeliveredInDB(db: Database, id: string): boolean {
+  const r = db.run('UPDATE ax_steering SET delivered = 1 WHERE id = ?', [id]);
+  return r.changes > 0;
+}
+
+export function loadAxEventsFromDB(db: Database, q: AxTimelineQuery = {}): PmxAxEvent[] {
+  interface Row { seq: number; id: string; kind: string; summary: string; detail: string | null; node_ids: string; data: string | null; created_at: string; source: string | null }
+  const rows = db.query<Row, [number]>('SELECT * FROM ax_events ORDER BY seq DESC LIMIT ?').all(clampTimelineLimit(q.limit));
+  return rows
+    .map((r) => normalizeAxEvent({ ...r, createdAt: r.created_at, nodeIds: safeParseJson(r.node_ids), data: safeParseJson(r.data) }))
+    .filter((e): e is PmxAxEvent => e !== null);
+}
+
+export function loadAxEvidenceFromDB(db: Database, q: AxTimelineQuery = {}): PmxAxEvidence[] {
+  interface Row { seq: number; id: string; kind: string; title: string; body: string | null; ref: string | null; node_ids: string; data: string | null; created_at: string; source: string | null }
+  const rows = db.query<Row, [number]>('SELECT * FROM ax_evidence ORDER BY seq DESC LIMIT ?').all(clampTimelineLimit(q.limit));
+  return rows
+    .map((r) => normalizeAxEvidence({ ...r, createdAt: r.created_at, nodeIds: safeParseJson(r.node_ids), data: safeParseJson(r.data) }))
+    .filter((e): e is PmxAxEvidence => e !== null);
+}
+
+export function loadAxSteeringFromDB(db: Database, q: AxTimelineQuery & { onlyPending?: boolean } = {}): PmxAxSteeringMessage[] {
+  interface Row { seq: number; id: string; message: string; delivered: number; created_at: string; source: string | null }
+  const sql = q.onlyPending
+    ? 'SELECT * FROM ax_steering WHERE delivered = 0 ORDER BY seq DESC LIMIT ?'
+    : 'SELECT * FROM ax_steering ORDER BY seq DESC LIMIT ?';
+  const rows = db.query<Row, [number]>(sql).all(clampTimelineLimit(q.limit));
+  return rows
+    .map((r) => normalizeAxSteeringMessage({ ...r, createdAt: r.created_at, delivered: r.delivered === 1 }))
+    .filter((s): s is PmxAxSteeringMessage => s !== null);
+}
+
+function countRows(db: Database, table: 'ax_events' | 'ax_evidence' | 'ax_steering'): number {
+  return Number(db.query<{ n: number }, []>(`SELECT COUNT(*) AS n FROM ${table}`).get()?.n ?? 0);
+}
+
+export function loadAxTimelineSummaryFromDB(db: Database): PmxAxTimelineSummary {
+  return {
+    recentEvents: loadAxEventsFromDB(db, { limit: AX_CONTEXT_EVENT_LIMIT }),
+    recentEvidence: loadAxEvidenceFromDB(db, { limit: AX_CONTEXT_EVIDENCE_LIMIT }),
+    pendingSteering: loadAxSteeringFromDB(db, { onlyPending: true, limit: AX_CONTEXT_STEERING_LIMIT }),
+    counts: { events: countRows(db, 'ax_events'), evidence: countRows(db, 'ax_evidence'), steering: countRows(db, 'ax_steering') },
+  };
+}
+
+export function upsertAxHostCapabilityToDB(db: Database, cap: PmxAxHostCapability): void {
+  const host = cap.host ?? 'default';
+  db.run(
+    'INSERT OR REPLACE INTO ax_host_capabilities (host, reported_at, payload) VALUES (?, ?, ?)',
+    [host, cap.reportedAt ?? new Date().toISOString(), JSON.stringify(cap)],
+  );
+}
+
+export function loadAxHostCapabilityFromDB(db: Database): PmxAxHostCapability | null {
+  const row = db.query<{ payload: string }, []>('SELECT payload FROM ax_host_capabilities ORDER BY reported_at DESC LIMIT 1').get();
+  return row ? normalizeAxHostCapability(safeParseJson(row.payload)) : null;
+}