memorix 1.7.3 → 1.8.1

package/src/server/mcp-binding-store.ts

@@ -0,0 +1,79 @@
+import { randomUUID } from 'node:crypto';
+import { getDatabase } from '../store/sqlite-db.js';
+
+export interface McpProjectBinding {
+  handleId: string;
+  projectId: string;
+  projectRoot: string;
+  dataDir: string;
+  createdAt: string;
+  lastUsedAt: string;
+  expiresAt?: string;
+}
+
+function rowToBinding(row: any): McpProjectBinding {
+  return {
+    handleId: String(row.handle_id),
+    projectId: String(row.project_id),
+    projectRoot: String(row.project_root),
+    dataDir: String(row.data_dir),
+    createdAt: String(row.created_at),
+    lastUsedAt: String(row.last_used_at),
+    ...(row.expires_at ? { expiresAt: String(row.expires_at) } : {}),
+  };
+}
+
+/** Durable project binding handles for stateless MCP requests. */
+export class McpBindingStore {
+  private db: any = null;
+
+  async init(dataDir: string): Promise<void> {
+    this.db = getDatabase(dataDir);
+  }
+
+  private requireDb(): any {
+    if (!this.db) throw new Error('McpBindingStore is not initialized.');
+    return this.db;
+  }
+
+  create(input: { projectId: string; projectRoot: string; dataDir: string; ttlMs?: number }): McpProjectBinding {
+    const now = new Date();
+    const binding: McpProjectBinding = {
+      handleId: `mxh_${randomUUID().replace(/-/g, '')}`,
+      projectId: input.projectId,
+      projectRoot: input.projectRoot,
+      dataDir: input.dataDir,
+      createdAt: now.toISOString(),
+      lastUsedAt: now.toISOString(),
+      ...(input.ttlMs && input.ttlMs > 0 ? { expiresAt: new Date(now.getTime() + input.ttlMs).toISOString() } : {}),
+    };
+    this.requireDb().prepare(`
+      INSERT INTO mcp_bindings (handle_id, project_id, project_root, data_dir, created_at, last_used_at, expires_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?)
+    `).run(binding.handleId, binding.projectId, binding.projectRoot, binding.dataDir, binding.createdAt, binding.lastUsedAt, binding.expiresAt ?? null);
+    return binding;
+  }
+
+  get(handleId: string): McpProjectBinding | undefined {
+    const row = this.requireDb().prepare(`SELECT * FROM mcp_bindings WHERE handle_id = ?`).get(handleId);
+    if (!row) return undefined;
+    const binding = rowToBinding(row);
+    if (binding.expiresAt && Date.parse(binding.expiresAt) <= Date.now()) {
+      this.delete(handleId);
+      return undefined;
+    }
+    return binding;
+  }
+
+  touch(handleId: string): McpProjectBinding | undefined {
+    const binding = this.get(handleId);
+    if (!binding) return undefined;
+    const lastUsedAt = new Date().toISOString();
+    this.requireDb().prepare(`UPDATE mcp_bindings SET last_used_at = ? WHERE handle_id = ?`).run(lastUsedAt, handleId);
+    return { ...binding, lastUsedAt };
+  }
+
+  delete(handleId: string): void {
+    this.requireDb().prepare(`DELETE FROM mcp_bindings WHERE handle_id = ?`).run(handleId);
+  }
+}

package/src/server/mcp-diagnostics.ts

@@ -0,0 +1,40 @@
+/** MCP compatibility diagnostics shared by HTTP and CLI-facing checks. */
+
+export const CURRENT_MCP_PROTOCOL_VERSION = '2026-07-28';
+export const LEGACY_MCP_PROTOCOL_VERSION = '2024-11-05';
+export const MCP_SERVER_NAME = 'io.github.AVIDS2/memorix';
+
+export interface McpDiagnostics {
+  serverName: string;
+  protocol: {
+    current: string;
+    legacy: string;
+    statelessRequests: 'supported' | 'compatibility-only' | 'unsupported';
+    statefulStreamableHttp: 'supported';
+  };
+  capabilities: {
+    tasks: 'supported' | 'unsupported';
+    polling: 'supported' | 'unsupported';
+    listCache: 'supported';
+    explicitProjectHandle: 'supported';
+  };
+}
+
+/** The pinned SDK is stateful; do not present a fake durable task loop. */
+export function getMcpDiagnostics(): McpDiagnostics {
+  return {
+    serverName: MCP_SERVER_NAME,
+    protocol: {
+      current: CURRENT_MCP_PROTOCOL_VERSION,
+      legacy: LEGACY_MCP_PROTOCOL_VERSION,
+    statelessRequests: 'supported',
+      statefulStreamableHttp: 'supported',
+    },
+    capabilities: {
+      tasks: 'unsupported',
+      polling: 'unsupported',
+      listCache: 'supported',
+      explicitProjectHandle: 'supported',
+    },
+  };
+}

package/src/server/tool-profile.ts

@@ -40,6 +40,10 @@ export const TOOL_PROFILES: Record<string, ReadonlyArray<ToolProfile>> = Object.
   // multimodal support to one additional schema rather than enabling lite.
   memorix_session_start:      ['micro', 'lite', 'team', 'full'],
   memorix_media:              ['micro', 'lite', 'team', 'full'],
+  // Evidence and feedback are deliberate operator/context-control surfaces;
+  // keep the default micro profile at its nine-tool token budget.
+  memorix_evidence:           ['lite', 'team', 'full'],
+  memorix_feedback:           ['lite', 'team', 'full'],
 
   // ── lite: extended solo memory surface ────────────────────────────
   memorix_graph_context:      ['lite', 'team', 'full'],

package/src/server.ts

@@ -36,6 +36,8 @@ import { detectProject } from './project/detector.js';
 import { homeProjectRootError, isHomeDirectory, writeLastProjectRoot } from './project/launch-root.js';
 import { registerAlias, initAliasRegistry, resolveAliases, autoMergeByBaseName } from './project/aliases.js';
 import { getProjectDataDir } from './store/persistence.js';
+import { EvidenceCardStore } from './store/evidence-store.js';
+import { MemoryFeedbackStore } from './memory/feedback.js';
 import type { ObservationType, RuleSource, AgentTarget, MCPServerEntry, ObservationReader } from './types.js';
 import { RulesSyncer } from './rules/syncer.js';
 import { WorkspaceSyncEngine } from './workspace/engine.js';
@@ -196,7 +198,7 @@ function createDeterministicInstanceId(projectId: string, agentType: string, age
  * Create and configure the Memorix MCP Server.
  */
 /** Optional shared TeamStore — passed by serve-http so all sessions share state */
-export interface SharedTeamInstances {
+export interface SharedTeamStore {
   teamStore: import('./team/team-store.js').TeamStore;
 }
 
@@ -243,7 +245,7 @@ export function shouldAwaitProjectRuntime(toolName: string): boolean {
 export async function createMemorixServer(
   cwd?: string,
   existingServer?: McpServer,
-  sharedTeam?: SharedTeamInstances,
+  sharedTeam?: SharedTeamStore,
   options: CreateMemorixServerOptions = {},
 ): Promise<{
   server: McpServer;
@@ -4418,7 +4420,7 @@ export async function createMemorixServer(
         console.error(`[memorix] Dashboard staticDir: ${staticDir}`);
 
         // Start in background (non-blocking), disable auto-open (we'll open it ourselves)
-        startDashboard(projectDir, portNum, staticDir, project.id, project.name, false, undefined, project.rootPath, projectResolved)
+        startDashboard(projectDir, portNum, staticDir, project.id, project.name, false, project.rootPath, projectResolved)
           .then(() => { dashboardRunning = true; })
           .catch((err) => { console.error('[memorix] Dashboard error:', err); dashboardRunning = false; });
 
@@ -4445,7 +4447,7 @@ export async function createMemorixServer(
           process.platform === 'win32' ? `start "" "${url}"` :
             process.platform === 'darwin' ? `open "${url}"` :
               `xdg-open "${url}"`;
-        execCmd(openCmd, () => { });
+        execCmd(openCmd, { windowsHide: true }, () => { });
 
         return {
           content: [{
@@ -4474,6 +4476,124 @@ export async function createMemorixServer(
   // Orchestration Coordination Tools (Multi-Agent) - SQLite-backed
   // ================================================================
 
+  server.registerTool(
+    'memorix_evidence',
+    {
+      title: 'Evidence Cards',
+      description:
+        'Inspect the bounded, project-scoped provenance cards behind Memorix context. ' +
+        'Use list for a compact index, get/events for one source, sync to repair the projection, ' +
+        'and stale when known source files changed. Cards expose sourceRef, locator, capturedHash, and freshness.',
+      inputSchema: {
+        action: z.enum(['list', 'get', 'sync', 'stale', 'events']).describe('Evidence operation'),
+        candidateKind: z.enum(['observation', 'code', 'git', 'test', 'document', 'workflow', 'graph']).optional().default('observation'),
+        candidateId: z.string().optional().describe('Candidate id, usually an observation id'),
+        query: z.string().optional().describe('Optional title/source query for list'),
+        paths: z.array(z.string()).max(200).optional().describe('Changed source paths for stale'),
+        reason: z.string().max(500).optional().describe('Why evidence became stale'),
+        limit: z.number().int().positive().max(100).optional().default(20),
+      },
+    },
+    async ({ action, candidateKind, candidateId, query, paths, reason, limit }) => {
+      const unresolved = requireResolvedProject('inspect evidence cards for the current project');
+      if (unresolved) return unresolved;
+      const cards = new EvidenceCardStore();
+      await cards.init(projectDir);
+      if (action === 'sync') {
+        const observations = await getObservationStore().loadByProject(project.id);
+        const synced = cards.syncObservations(observations);
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ projectId: project.id, synced: synced.length, cards: synced.slice(0, limit ?? 20) }, null, 2) }] };
+      }
+      if (action === 'stale') {
+        const changed = cards.markStaleForPaths(project.id, paths ?? [], reason ?? 'source file changed');
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ projectId: project.id, staleMarked: changed, paths: paths ?? [] }, null, 2) }] };
+      }
+      if (action === 'get') {
+        if (!candidateId?.trim()) return { content: [{ type: 'text' as const, text: 'candidateId is required for evidence get.' }], isError: true };
+        const card = cards.get(project.id, candidateKind ?? 'observation', candidateId.trim());
+        if (!card) return { content: [{ type: 'text' as const, text: 'Evidence card not found.' }], isError: true };
+        return { content: [{ type: 'text' as const, text: JSON.stringify({ card, events: cards.listEvents(card.id), projectId: project.id }, null, 2) }] };
+      }
+      if (action === 'events') {
+        if (!candidateId?.trim()) return { content: [{ type: 'text' as const, text: 'candidateId is required for evidence events.' }], isError: true };
+        const card = cards.get(project.id, candidateKind ?? 'observation', candidateId.trim());
+        if (!card) return { content: [{ type: 'text' as const, text: 'Evidence card not found.' }], isError: true };
+        return { content: [{ type: 'text' as const, text: JSON.stringify(cards.listEvents(card.id, limit), null, 2) }] };
+      }
+      const needle = query?.trim().toLowerCase();
+      const listed = cards.list(project.id, { limit: Math.max(limit ?? 20, 100) })
+        .filter((card) => !needle || [card.title, card.summary, card.sourceRef, card.locator ?? ''].join(' ').toLowerCase().includes(needle))
+        .slice(0, limit ?? 20);
+      return { content: [{ type: 'text' as const, text: JSON.stringify({ projectId: project.id, cards: listed }, null, 2) }] };
+    },
+  );
+
+  server.registerTool(
+    'memorix_feedback',
+    {
+      title: 'Memory Feedback',
+      description:
+        'Record or inspect auditable memory outcomes. Positive verification/use strengthens recall; correction, conflict, source change, or weaken lowers it. ' +
+        'Use revoke with targetEventId to undo one prior signal without deleting audit history.',
+      inputSchema: {
+        action: z.enum(['record', 'show', 'audit']).describe('Feedback operation'),
+        candidateKind: z.enum(['observation', 'claim', 'durable-memory', 'workflow']).optional().default('observation'),
+        candidateId: z.string().describe('Memory or knowledge candidate id'),
+        signal: z.enum(['user-correction', 'verification-success', 'verification-failure', 'code-change', 'used', 'not-used', 'code-conflict', 'strengthen', 'weaken', 'revoke']).optional(),
+        sourceRef: z.string().max(500).optional().describe('Source of this feedback, such as test:run-42 or user:chat'),
+        actor: z.string().max(200).optional(),
+        note: z.string().max(2_000).optional(),
+        targetEventId: z.string().optional().describe('Existing event id when action=record and signal=revoke'),
+        limit: z.number().int().positive().max(200).optional().default(100),
+      },
+    },
+    async ({ action, candidateKind, candidateId, signal, sourceRef, actor, note, targetEventId, limit }) => {
+      const unresolved = requireResolvedProject('record memory feedback for the current project');
+      if (unresolved) return unresolved;
+      const feedback = new MemoryFeedbackStore();
+      await feedback.init(projectDir);
+      const kind = candidateKind ?? 'observation';
+      if (action === 'show') {
+        return { content: [{ type: 'text' as const, text: JSON.stringify(feedback.getState(project.id, kind, candidateId), null, 2) }] };
+      }
+      if (action === 'audit') {
+        return { content: [{ type: 'text' as const, text: JSON.stringify(feedback.audit(project.id, kind, candidateId, limit), null, 2) }] };
+      }
+      if (!signal || !sourceRef?.trim()) {
+        return { content: [{ type: 'text' as const, text: 'record requires signal and sourceRef.' }], isError: true };
+      }
+      try {
+        const result = feedback.record({
+          projectId: project.id,
+          candidateKind: kind,
+          candidateId,
+          signal,
+          sourceRef,
+          ...(actor || currentAgentId ? { actor: actor ?? currentAgentId } : {}),
+          ...(note ? { note } : {}),
+          ...(targetEventId ? { targetEventId } : {}),
+        });
+        if (kind === 'observation') {
+          const cards = new EvidenceCardStore();
+          await cards.init(projectDir);
+          const card = cards.get(project.id, 'observation', candidateId);
+          if (card) {
+            const verification = signal === 'verification-success' || signal === 'strengthen' ? 'verified' : signal === 'user-correction' || signal === 'code-conflict' || signal === 'weaken' ? 'conflicted' : card.verification;
+            cards.recordEvent(project.id, card.id, `feedback:${signal}`, note);
+            if (verification !== card.verification) {
+              // Keep the card projection in sync with the feedback state while
+              // retaining the append-only feedback audit as the source of truth.
+              cards.setVerification(project.id, card.id, verification);
+            }
+          }
+        }
+        return { content: [{ type: 'text' as const, text: JSON.stringify(result, null, 2) }] };
+      } catch (error) {
+        return { content: [{ type: 'text' as const, text: error instanceof Error ? error.message : String(error) }], isError: true };
+      }
+    },
+  );
+
   // Use shared TeamStore (from HTTP server) or create new one (stdio mode).
   // All team state is canonical in SQLite — no JSON persistence, no sync/flush.
   if (teamFeaturesEnabled) {
@@ -4666,7 +4786,7 @@ export async function createMemorixServer(
   server.registerTool(
     'team_task',
     {
-      title: 'Task Board',
+      title: 'Task Status',
       description:
         'Create, claim, complete, or list tasks in the team task board. Supports dependencies. ' +
         'Action "create": create a task. Action "claim": assign to yourself (atomic, race-safe). ' +

package/src/store/evidence-store.ts

@@ -0,0 +1,261 @@
+import { createHash, randomUUID } from 'node:crypto';
+import type { Observation } from '../types.js';
+import { getDatabase } from './sqlite-db.js';
+
+export type EvidenceCandidateKind = 'observation' | 'code' | 'git' | 'test' | 'document' | 'workflow' | 'graph';
+export type EvidenceVerification = 'unverified' | 'verified' | 'conflicted';
+export type EvidenceFreshness = 'current' | 'stale' | 'unknown';
+
+export interface EvidenceCardRecord {
+  id: string;
+  projectId: string;
+  candidateKind: EvidenceCandidateKind;
+  candidateId: string;
+  title: string;
+  summary: string;
+  entityName?: string;
+  sourceKind: string;
+  sourceRef: string;
+  locator?: string;
+  capturedHash?: string;
+  sessionId?: string;
+  status: string;
+  verification: EvidenceVerification;
+  freshness: EvidenceFreshness;
+  staleReason?: string;
+  files: string[];
+  relatedEntities: string[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface EvidenceCardEvent {
+  id: string;
+  projectId: string;
+  cardId: string;
+  kind: string;
+  detail?: string;
+  createdAt: string;
+}
+
+function safeJson<T>(value: unknown, fallback: T): T {
+  if (typeof value !== 'string' || value.length === 0) return fallback;
+  try {
+    return JSON.parse(value) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+function rowToCard(row: any): EvidenceCardRecord {
+  return {
+    id: String(row.id),
+    projectId: String(row.project_id),
+    candidateKind: row.candidate_kind,
+    candidateId: String(row.candidate_id),
+    title: String(row.title),
+    summary: String(row.summary ?? ''),
+    ...(row.entity_name ? { entityName: String(row.entity_name) } : {}),
+    sourceKind: String(row.source_kind),
+    sourceRef: String(row.source_ref),
+    ...(row.locator ? { locator: String(row.locator) } : {}),
+    ...(row.captured_hash ? { capturedHash: String(row.captured_hash) } : {}),
+    ...(row.session_id ? { sessionId: String(row.session_id) } : {}),
+    status: String(row.status ?? 'active'),
+    verification: row.verification,
+    freshness: row.freshness,
+    ...(row.stale_reason ? { staleReason: String(row.stale_reason) } : {}),
+    files: safeJson(row.files_json, []),
+    relatedEntities: safeJson(row.related_entities_json, []),
+    createdAt: String(row.created_at),
+    updatedAt: String(row.updated_at),
+  };
+}
+
+function observationHash(observation: Observation): string {
+  return createHash('sha256')
+    .update(JSON.stringify({
+      projectId: observation.projectId,
+      id: observation.id,
+      title: observation.title,
+      narrative: observation.narrative,
+      facts: observation.facts,
+      files: observation.filesModified,
+      relatedEntities: observation.relatedEntities,
+    }))
+    .digest('hex');
+}
+
+function sourceKind(observation: Observation): string {
+  if (observation.source === 'git' || observation.sourceDetail === 'git-ingest') return 'git';
+  if (observation.sourceDetail === 'hook') return 'hook';
+  return observation.source ?? 'agent';
+}
+
+/** SQLite-backed provenance cards used by MCP, CLI, and Dashboard surfaces. */
+export class EvidenceCardStore {
+  private db: any = null;
+
+  async init(dataDir: string): Promise<void> {
+    this.db = getDatabase(dataDir);
+  }
+
+  private requireDb(): any {
+    if (!this.db) throw new Error('EvidenceCardStore is not initialized.');
+    return this.db;
+  }
+
+  upsertObservation(observation: Observation): EvidenceCardRecord {
+    const db = this.requireDb();
+    const now = new Date().toISOString();
+    const card: EvidenceCardRecord = {
+      id: `evidence:observation:${observation.projectId}:${observation.id}`,
+      projectId: observation.projectId,
+      candidateKind: 'observation',
+      candidateId: String(observation.id),
+      title: observation.title,
+      summary: observation.narrative.slice(0, 500),
+      entityName: observation.entityName,
+      sourceKind: sourceKind(observation),
+      sourceRef: `observation:${observation.id}`,
+      locator: observation.filesModified?.join(', ') || `observation:${observation.id}`,
+      capturedHash: observationHash(observation),
+      ...(observation.sessionId ? { sessionId: observation.sessionId } : {}),
+      status: observation.status ?? 'active',
+      verification: observation.status === 'resolved' ? 'verified' : 'unverified',
+      freshness: 'current',
+      files: observation.filesModified ?? [],
+      relatedEntities: observation.relatedEntities ?? [],
+      createdAt: observation.createdAt,
+      updatedAt: now,
+    };
+    db.prepare(`
+      INSERT INTO evidence_cards (
+        id, project_id, candidate_kind, candidate_id, title, summary, entity_name,
+        source_kind, source_ref, locator, captured_hash, session_id, status,
+        verification, freshness, stale_reason, files_json, related_entities_json,
+        created_at, updated_at
+      ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, NULL, ?, ?, ?, ?)
+      ON CONFLICT(project_id, candidate_kind, candidate_id) DO UPDATE SET
+        title = excluded.title,
+        summary = excluded.summary,
+        entity_name = excluded.entity_name,
+        source_kind = excluded.source_kind,
+        source_ref = excluded.source_ref,
+        locator = excluded.locator,
+        captured_hash = excluded.captured_hash,
+        session_id = excluded.session_id,
+        status = excluded.status,
+        freshness = 'current',
+        stale_reason = NULL,
+        files_json = excluded.files_json,
+        related_entities_json = excluded.related_entities_json,
+        updated_at = excluded.updated_at
+    `).run(
+      card.id,
+      card.projectId,
+      card.candidateKind,
+      card.candidateId,
+      card.title,
+      card.summary,
+      card.entityName ?? null,
+      card.sourceKind,
+      card.sourceRef,
+      card.locator ?? null,
+      card.capturedHash ?? null,
+      card.sessionId ?? null,
+      card.status,
+      card.verification,
+      card.freshness,
+      JSON.stringify(card.files),
+      JSON.stringify(card.relatedEntities),
+      card.createdAt,
+      card.updatedAt,
+    );
+    return this.get(card.projectId, card.candidateKind, card.candidateId) ?? card;
+  }
+
+  get(projectId: string, candidateKind: EvidenceCandidateKind, candidateId: string): EvidenceCardRecord | undefined {
+    const row = this.requireDb().prepare(`
+      SELECT * FROM evidence_cards WHERE project_id = ? AND candidate_kind = ? AND candidate_id = ?
+    `).get(projectId, candidateKind, candidateId);
+    return row ? rowToCard(row) : undefined;
+  }
+
+  list(projectId: string, options: { limit?: number; freshness?: EvidenceFreshness; status?: string } = {}): EvidenceCardRecord[] {
+    const limit = Math.min(100, Math.max(1, Math.floor(options.limit ?? 20)));
+    const clauses = ['project_id = ?'];
+    const args: unknown[] = [projectId];
+    if (options.freshness) { clauses.push('freshness = ?'); args.push(options.freshness); }
+    if (options.status) { clauses.push('status = ?'); args.push(options.status); }
+    args.push(limit);
+    const rows = this.requireDb().prepare(`
+      SELECT * FROM evidence_cards WHERE ${clauses.join(' AND ')} ORDER BY updated_at DESC, id DESC LIMIT ?
+    `).all(...args);
+    return rows.map(rowToCard);
+  }
+
+  syncObservations(observations: Observation[]): EvidenceCardRecord[] {
+    return observations.map((observation) => this.upsertObservation(observation));
+  }
+
+  markStaleForPaths(projectId: string, paths: string[], reason = 'source file changed'): number {
+    const normalized = new Set(paths.map((value) => value.replace(/\\/g, '/').toLowerCase()));
+    if (normalized.size === 0) return 0;
+    const db = this.requireDb();
+    const rows = db.prepare(`SELECT * FROM evidence_cards WHERE project_id = ? AND freshness != 'stale'`).all(projectId);
+    const update = db.prepare(`
+      UPDATE evidence_cards SET freshness = 'stale', stale_reason = ?, updated_at = ?
+      WHERE id = ?
+    `);
+    let changed = 0;
+    const now = new Date().toISOString();
+    const run = db.transaction(() => {
+      for (const row of rows) {
+        const files = safeJson<string[]>(row.files_json, []);
+        if (!files.some((file) => normalized.has(file.replace(/\\/g, '/').toLowerCase()))) continue;
+        update.run(reason, now, row.id);
+        changed++;
+      }
+    });
+    run();
+    return changed;
+  }
+
+  setVerification(projectId: string, cardId: string, verification: EvidenceVerification): void {
+    this.requireDb().prepare(`
+      UPDATE evidence_cards SET verification = ?, updated_at = ? WHERE project_id = ? AND id = ?
+    `).run(verification, new Date().toISOString(), projectId, cardId);
+  }
+
+  recordEvent(projectId: string, cardId: string, kind: string, detail?: string): EvidenceCardEvent {
+    const event: EvidenceCardEvent = {
+      id: randomUUID(),
+      projectId,
+      cardId,
+      kind,
+      ...(detail ? { detail: detail.slice(0, 2_000) } : {}),
+      createdAt: new Date().toISOString(),
+    };
+    this.requireDb().prepare(`
+      INSERT INTO evidence_card_events (id, project_id, card_id, kind, detail, created_at)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).run(event.id, event.projectId, event.cardId, event.kind, event.detail ?? null, event.createdAt);
+    return event;
+  }
+
+  listEvents(cardId: string, limit = 50): EvidenceCardEvent[] {
+    const rows = this.requireDb().prepare(`
+      SELECT * FROM evidence_card_events WHERE card_id = ? ORDER BY created_at DESC LIMIT ?
+    `).all(cardId, Math.min(200, Math.max(1, Math.floor(limit))));
+    return rows.map((row: any) => ({
+      id: String(row.id), projectId: String(row.project_id), cardId: String(row.card_id),
+      kind: String(row.kind), ...(row.detail ? { detail: String(row.detail) } : {}),
+      createdAt: String(row.created_at),
+    }));
+  }
+}
+
+export function buildEvidenceCardId(projectId: string, candidateKind: EvidenceCandidateKind, candidateId: string): string {
+  return `evidence:${candidateKind}:${projectId}:${candidateId}`;
+}