wendkeep 0.69.0 → 0.71.1

package/src/observer-server.mjs

@@ -0,0 +1,333 @@
+import { createServer } from 'node:http';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import {
+  appendObserverEvent,
+  getObserverProject,
+  listRegisteredObserverProjects,
+  readObserverIndex,
+  registerObserverProject,
+} from './observer-store.mjs';
+import { MAX_SNAPSHOT_BYTES, validateObserverSnapshot } from './observer-snapshot.mjs';
+import {
+  applyMemoryEvent,
+  exportMemoryBundle,
+  readMemoryDocument,
+  readMemorySync,
+  readMemoryTree,
+  setMemoryMode,
+  searchMemory,
+  validateMemoryEvent,
+} from './observer-memory.mjs';
+
+const LOOPBACK_HOSTS = new Set(['127.0.0.1', 'localhost', '::1']);
+const MAX_BODY_BYTES = MAX_SNAPSHOT_BYTES + 4096;
+const MAX_MEMORY_BODY_BYTES = 8 * 1024 * 1024;
+const STATIC_ROOT = fileURLToPath(new URL('../web/observer/', import.meta.url));
+const STATIC_ASSETS = new Map([
+  ['/index.html', { file: 'index.html', type: 'text/html; charset=utf-8' }],
+  ['/styles.css', { file: 'styles.css', type: 'text/css; charset=utf-8' }],
+  ['/app.mjs', { file: 'app.mjs', type: 'text/javascript; charset=utf-8' }],
+  ['/favicon.svg', { file: 'favicon.svg', type: 'image/svg+xml' }],
+]);
+
+function loopbackOnly(host) {
+  return LOOPBACK_HOSTS.has(String(host || '').toLowerCase());
+}
+
+function json(res, status, body) {
+  const content = JSON.stringify(body);
+  res.writeHead(status, {
+    'content-type': 'application/json; charset=utf-8',
+    'cache-control': 'no-store',
+    'content-length': Buffer.byteLength(content),
+  });
+  res.end(content);
+}
+
+function errorResponse(res, status, code, message) {
+  json(res, status, { error: { code, message } });
+}
+
+function serveStatic(res, pathname) {
+  const asset = STATIC_ASSETS.get(pathname === '/' ? '/index.html' : pathname);
+  if (!asset) return false;
+  try {
+    const body = readFileSync(new URL(asset.file, `file://${STATIC_ROOT.replace(/\\/g, '/')}/`));
+    res.writeHead(200, {
+      'content-type': asset.type,
+      'cache-control': 'no-store',
+      'x-content-type-options': 'nosniff',
+      'content-length': body.byteLength,
+    });
+    res.end(body);
+  } catch {
+    errorResponse(res, 500, 'dashboard_asset_error', 'asset do dashboard indisponível.');
+  }
+  return true;
+}
+
+function readBody(req, maxBytes = MAX_BODY_BYTES) {
+  return new Promise((resolve, reject) => {
+    let size = 0;
+    let tooLarge = false;
+    const chunks = [];
+    req.on('data', (chunk) => {
+      if (tooLarge) return;
+      size += chunk.length;
+      if (size > maxBytes) {
+        tooLarge = true;
+        const error = new Error('corpo acima do limite.');
+        error.code = 'payload_too_large';
+        reject(error);
+        return;
+      }
+      chunks.push(chunk);
+    });
+    req.on('end', () => {
+      if (!tooLarge) resolve(Buffer.concat(chunks).toString('utf8'));
+    });
+    req.on('error', reject);
+  });
+}
+
+function parseJson(text) {
+  try { return JSON.parse(text || '{}'); }
+  catch {
+    const error = new Error('JSON inválido.');
+    error.code = 'invalid_json';
+    throw error;
+  }
+}
+
+function pathParts(url) {
+  return new URL(url, 'http://127.0.0.1').pathname.split('/').filter(Boolean).map((part) => decodeURIComponent(part));
+}
+
+function projectIdFrom(parts) {
+  return parts[0] === 'v1' && parts[1] === 'projects' && parts[2] ? parts[2] : '';
+}
+
+function projectKnown(dataDir, projectId) {
+  return Boolean(
+    getObserverProject(dataDir, projectId)
+    || listRegisteredObserverProjects(dataDir).some((item) => item.projectId === projectId),
+  );
+}
+
+export async function startObserverServer({
+  host = '127.0.0.1',
+  port = 8787,
+  dataDir,
+  allowNonLoopback = false,
+} = {}) {
+  if (!loopbackOnly(host) && !allowNonLoopback) {
+    throw new Error(`Observer HTTP aceita somente host loopback; recebido: ${host}`);
+  }
+  if (!dataDir) throw new Error('dataDir é obrigatório.');
+  const server = createServer(async (req, res) => {
+    try {
+      const pathname = new URL(req.url || '/', 'http://127.0.0.1').pathname;
+      if (req.method === 'GET' && pathname === '/healthz') {
+        json(res, 200, { ok: true, service: 'wendkeep-observer', schema_version: 1 });
+        return;
+      }
+      if (req.method === 'GET' && (pathname === '/' || STATIC_ASSETS.has(pathname))) {
+        serveStatic(res, pathname);
+        return;
+      }
+      if (req.method === 'GET' && !pathname.startsWith('/v1/')) {
+        errorResponse(res, 404, 'not_found', 'rota não encontrada.');
+        return;
+      }
+      const parts = pathParts(req.url || '/');
+      if (parts[0] !== 'v1' || parts[1] !== 'projects') {
+        errorResponse(res, 404, 'not_found', 'rota não encontrada.');
+        return;
+      }
+
+      if (parts.length === 2 && req.method === 'GET') {
+        const index = readObserverIndex(dataDir);
+        json(res, 200, {
+          schema_version: index.schema_version,
+          projects: index.projects.map(({ snapshot, ...summary }) => summary),
+        });
+        return;
+      }
+
+      const projectId = projectIdFrom(parts);
+      if (!projectId) {
+        errorResponse(res, 404, 'not_found', 'projeto não informado.');
+        return;
+      }
+
+      if (parts.length === 4 && parts[3] === 'sync' && req.method === 'GET') {
+        if (!projectKnown(dataDir, projectId)) {
+          errorResponse(res, 404, 'project_not_found', 'projeto não encontrado: ' + projectId);
+          return;
+        }
+        json(res, 200, readMemorySync(dataDir, projectId));
+        return;
+      }
+
+      if (parts.length === 4 && parts[3] === 'sync' && req.method === 'PUT') {
+        if (!projectKnown(dataDir, projectId)) {
+          errorResponse(res, 404, 'project_not_found', 'projeto não encontrado: ' + projectId);
+          return;
+        }
+        const body = parseJson(await readBody(req));
+        try {
+          json(res, 200, setMemoryMode(dataDir, projectId, body.mode));
+        } catch (error) {
+          errorResponse(res, 400, error?.code || 'invalid_memory_mode', error?.message || 'modo inválido.');
+        }
+        return;
+      }
+
+      if (parts.length >= 4 && parts[3] === 'memory') {
+        if (!projectKnown(dataDir, projectId)) {
+          errorResponse(res, 404, 'project_not_found', 'projeto não encontrado: ' + projectId);
+          return;
+        }
+        const memoryAction = parts[4] || '';
+        if (memoryAction === 'tree' && req.method === 'GET') {
+          const query = new URL(req.url || '/', 'http://127.0.0.1').searchParams;
+          json(res, 200, readMemoryTree(dataDir, projectId, query.get('prefix') || ''));
+          return;
+        }
+        if (memoryAction === 'document' && req.method === 'GET') {
+          const query = new URL(req.url || '/', 'http://127.0.0.1').searchParams;
+          try {
+            json(res, 200, readMemoryDocument(dataDir, projectId, query.get('path') || ''));
+          } catch (error) {
+            const status = error?.code === 'memory_not_found' ? 404 : 400;
+            errorResponse(res, status, error?.code || 'invalid_memory_path', error?.message || 'documento inválido.');
+          }
+          return;
+        }
+        if (memoryAction === 'search' && req.method === 'GET') {
+          const query = new URL(req.url || '/', 'http://127.0.0.1').searchParams;
+          json(res, 200, { project_id: projectId, query: query.get('q') || '', results: searchMemory(dataDir, projectId, query.get('q') || '') });
+          return;
+        }
+        if (memoryAction === 'export' && req.method === 'GET') {
+          json(res, 200, exportMemoryBundle(dataDir, projectId));
+          return;
+        }
+        if (memoryAction === 'events' && req.method === 'POST') {
+          const body = parseJson(await readBody(req, MAX_MEMORY_BODY_BYTES));
+          const events = Array.isArray(body.events) ? body.events : [];
+          if (events.length === 0) {
+            errorResponse(res, 400, 'invalid_memory_batch', 'events deve conter pelo menos um evento.');
+            return;
+          }
+          const results = [];
+          for (const event of events) {
+            if (event?.project_id !== projectId) {
+              results.push({ accepted: false, errors: ['project_id do evento não corresponde à rota.'] });
+              continue;
+            }
+            const validation = validateMemoryEvent(event);
+            results.push(validation.ok ? applyMemoryEvent(dataDir, event) : { accepted: false, errors: validation.errors });
+          }
+          const accepted = results.filter((item) => item.accepted).length;
+          const duplicates = results.filter((item) => item.duplicate).length;
+          const conflicts = results.filter((item) => item.conflict).length;
+          const rejected = results.length - accepted - duplicates - conflicts;
+          if (conflicts > 0 || rejected > 0) {
+            json(res, conflicts > 0 ? 409 : 400, { accepted, duplicates, conflicts, rejected, results });
+            return;
+          }
+          json(res, accepted > 0 ? 201 : 200, { accepted, duplicates, conflicts, rejected, results });
+          return;
+        }
+      }
+
+      if (parts.length === 3 && req.method === 'GET') {
+        const project = getObserverProject(dataDir, projectId);
+        if (!project) {
+          errorResponse(res, 404, 'project_not_found', `projeto não encontrado: ${projectId}`);
+          return;
+        }
+        json(res, 200, project);
+        return;
+      }
+
+      if (parts.length === 3 && req.method === 'PUT') {
+        const body = parseJson(await readBody(req));
+        if (body.project_id !== projectId) {
+          errorResponse(res, 400, 'project_mismatch', 'project_id do corpo não corresponde à rota.');
+          return;
+        }
+        const result = registerObserverProject(dataDir, {
+          projectId,
+          projectName: body.project_name,
+          wendkeepVersion: body.wendkeep_version,
+        });
+        if (!result.registered) {
+          errorResponse(res, 400, 'invalid_project', result.errors.join(' '));
+          return;
+        }
+        json(res, 201, result.project);
+        return;
+      }
+
+      if (parts.length === 4 && parts[3] === 'changes' && req.method === 'GET') {
+        const project = getObserverProject(dataDir, projectId);
+        if (!project) {
+          errorResponse(res, 404, 'project_not_found', `projeto não encontrado: ${projectId}`);
+          return;
+        }
+        json(res, 200, { project_id: projectId, changes: project.snapshot?.changes || [] });
+        return;
+      }
+
+      if (parts.length === 4 && ['snapshot', 'snapshots'].includes(parts[3]) && req.method === 'POST') {
+        const body = parseJson(await readBody(req));
+        const validation = validateObserverSnapshot(body, { projectId });
+        if (!validation.ok) {
+          errorResponse(res, 400, 'invalid_snapshot', validation.errors.join(' '));
+          return;
+        }
+        const result = appendObserverEvent(dataDir, body);
+        if (!result.accepted && result.duplicate) {
+          json(res, 200, { accepted: false, duplicate: true, event_id: body.event_id });
+          return;
+        }
+        if (!result.accepted) {
+          const unregistered = result.errors.some((item) => /não registrado/.test(item));
+          errorResponse(res, unregistered ? 409 : 400, unregistered ? 'project_not_registered' : 'invalid_event', result.errors.join(' '));
+          return;
+        }
+        json(res, 201, { accepted: true, duplicate: false, event_id: body.event_id });
+        return;
+      }
+
+      errorResponse(res, 404, 'not_found', 'rota não encontrada.');
+    } catch (error) {
+      if (res.headersSent) return;
+      const status = error?.code === 'payload_too_large' ? 413 : error?.code === 'invalid_json' ? 400 : 500;
+      errorResponse(res, status, error?.code || 'observer_error', error?.message || 'erro interno do Observer.');
+    }
+  });
+
+  await new Promise((resolve, reject) => {
+    const onError = (error) => {
+      server.off('listening', onListening);
+      reject(error);
+    };
+    const onListening = () => {
+      server.off('error', onError);
+      resolve();
+    };
+    server.once('error', onError);
+    server.once('listening', onListening);
+    server.listen(Number(port), host);
+  });
+
+  return {
+    server,
+    address: () => server.address(),
+    close: () => new Promise((resolve, reject) => server.close((error) => (error ? reject(error) : resolve()))),
+  };
+}

package/src/observer-snapshot.mjs

@@ -0,0 +1,153 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { basename } from 'node:path';
+import { allChangesState } from '../hooks/change-core.mjs';
+import { readControl, readSessionRegistry } from '../hooks/obsidian-common.mjs';
+import { runVaultHealth } from '../hooks/vault-health.mjs';
+import { readProjectForValidation } from '../packages/vault/src/validate-memory.mjs';
+
+export const OBSERVER_SCHEMA_VERSION = 1;
+export const MAX_SNAPSHOT_BYTES = 32 * 1024;
+const MAX_TEXT = 160;
+
+function fail(message, code = 'WENDKEEP_OBSERVER_SNAPSHOT_INVALID') {
+  const error = new Error(message);
+  error.code = code;
+  return error;
+}
+
+function safeText(value, max = MAX_TEXT) {
+  return String(value ?? '')
+    .replace(/[\u0000-\u001f\u007f]/g, ' ')
+    .replace(/[A-Za-z]:[\\/][^\s"']*/g, '[REDACTED_PATH]')
+    .replace(/\\\\[^\s"']+/g, '[REDACTED_PATH]')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, max);
+}
+
+function isoNow(value) {
+  const date = value instanceof Date ? value : new Date(value ?? Date.now());
+  if (Number.isNaN(date.getTime())) throw fail('captured_at inválido.');
+  return date.toISOString();
+}
+
+function packageVersion() {
+  try {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version || '0.0.0';
+  } catch {
+    return '0.0.0';
+  }
+}
+
+function activeSessionSummary(vaultBase, control, registry) {
+  const entries = Object.entries(registry?.sessions || {})
+    .map(([sessionId, entry]) => ({ sessionId, entry }))
+    .sort((a, b) => String(b.entry?.last_seen || b.entry?.updated_at || '').localeCompare(String(a.entry?.last_seen || a.entry?.updated_at || '')));
+  const selected = entries.find(({ sessionId }) => sessionId === control?.session_id) || entries[0];
+  const entry = selected?.entry || {};
+  return {
+    status: safeText(control?.status || entry.status || 'inactive', 32),
+    session_id: safeText(control?.session_id || selected?.sessionId || '', 100),
+    provider: safeText(entry.provider || '', 32),
+    change_slug: safeText(entry.change_slug || '', 100),
+    last_seen: safeText(entry.last_seen || entry.updated_at || '', 40),
+  };
+}
+
+function healthSummary(vaultBase) {
+  try {
+    const health = runVaultHealth({ vaultBase });
+    return {
+      ok: health.ok === true,
+      status: safeText(health.memoryStatus || (health.ok ? 'healthy' : 'degraded'), 40),
+      failure_count: Array.isArray(health.failures) ? health.failures.length : 0,
+      warning_count: Array.isArray(health.warnings) ? health.warnings.length : 0,
+      registry_sessions: Number(health.metrics?.registrySessions || 0),
+      derived_notes: Number(health.metrics?.derivedNotes || 0),
+    };
+  } catch {
+    return {
+      ok: false,
+      status: 'unavailable',
+      failure_count: 1,
+      warning_count: 0,
+      registry_sessions: 0,
+      derived_notes: 0,
+    };
+  }
+}
+
+function hashEvent(snapshot) {
+  const canonical = JSON.stringify({ ...snapshot, event_id: undefined });
+  return `obs-${createHash('sha256').update(canonical).digest('hex').slice(0, 24)}`;
+}
+
+function hasForbiddenKey(value) {
+  if (!value || typeof value !== 'object') return false;
+  for (const [key, child] of Object.entries(value)) {
+    if (/(?:core|shared|digest|transcript|secret|token|prompt|raw|path|vault)/i.test(key)) return true;
+    if (hasForbiddenKey(child)) return true;
+  }
+  return false;
+}
+
+function hasAbsolutePath(value) {
+  if (typeof value === 'string') {
+    return /[A-Za-z]:[\\/]|\\\\[^\\/]+[\\/]|(?:^|\s)\/(?:Users|home|mnt|var|tmp)\//.test(value);
+  }
+  if (!value || typeof value !== 'object') return false;
+  return Object.values(value).some(hasAbsolutePath);
+}
+
+export function validateObserverSnapshot(snapshot, { projectId = '' } = {}) {
+  const errors = [];
+  if (!snapshot || typeof snapshot !== 'object' || Array.isArray(snapshot)) {
+    return { ok: false, errors: ['snapshot deve ser um objeto JSON.'] };
+  }
+  if (snapshot.schema_version !== OBSERVER_SCHEMA_VERSION) errors.push('schema_version incompatível.');
+  for (const key of ['event_id', 'project_id', 'project_name', 'wendkeep_version', 'captured_at']) {
+    if (typeof snapshot[key] !== 'string' || !snapshot[key].trim()) errors.push(`${key} ausente ou inválido.`);
+  }
+  if (projectId && snapshot.project_id !== projectId) errors.push('project_id não corresponde ao projeto registrado.');
+  if (!Array.isArray(snapshot.changes)) errors.push('changes deve ser uma lista.');
+  if (!snapshot.session || typeof snapshot.session !== 'object') errors.push('session ausente.');
+  if (!snapshot.health || typeof snapshot.health !== 'object') errors.push('health ausente.');
+  if (hasForbiddenKey(snapshot)) errors.push('snapshot contém campo não permitido.');
+  if (hasAbsolutePath(snapshot)) errors.push('snapshot contém caminho absoluto.');
+  const size = Buffer.byteLength(JSON.stringify(snapshot), 'utf8');
+  if (size > MAX_SNAPSHOT_BYTES) errors.push(`snapshot excede ${MAX_SNAPSHOT_BYTES} bytes.`);
+  return { ok: errors.length === 0, errors, size };
+}
+
+export function buildProjectSnapshot({ vaultBase, projectRoot = process.cwd(), now = new Date() } = {}) {
+  if (!vaultBase) throw fail('vaultBase é obrigatório.');
+  const project = readProjectForValidation(vaultBase);
+  if (!project.ok || !project.projectId) throw fail(project.errors?.join(' ') || 'PROJECT.json inválido.');
+  const control = readControl(vaultBase);
+  const registry = readSessionRegistry(vaultBase);
+  const changes = allChangesState(vaultBase).changes.map((change) => ({
+    slug: safeText(change.slug, 100),
+    current: change.current === true,
+    openTasks: Number(change.openCount || 0),
+    doneTasks: Number(change.doneCount || 0),
+    warning: safeText(change.warning || '', 120),
+  }));
+  const markerName = project.marker?.projectName || basename(projectRoot);
+  const snapshot = {
+    schema_version: OBSERVER_SCHEMA_VERSION,
+    event_id: '',
+    project_id: project.projectId,
+    projectId: project.projectId,
+    project_name: safeText(markerName || project.projectId, 100),
+    wendkeep_version: packageVersion(),
+    captured_at: isoNow(now),
+    session: activeSessionSummary(vaultBase, control, registry),
+    changes,
+    health: healthSummary(vaultBase),
+  };
+  snapshot.event_id = hashEvent(snapshot);
+  const validation = validateObserverSnapshot(snapshot, { projectId: project.projectId });
+  if (!validation.ok) throw fail(validation.errors.join(' '));
+  return snapshot;
+}

package/src/observer-store.mjs

@@ -0,0 +1,155 @@
+import { appendFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { MAX_SNAPSHOT_BYTES, OBSERVER_SCHEMA_VERSION, validateObserverSnapshot } from './observer-snapshot.mjs';
+
+export const OBSERVER_DATA_SCHEMA_VERSION = 1;
+export const OBSERVER_EVENTS_FILE = 'EVENTS.jsonl';
+export const OBSERVER_INDEX_FILE = 'INDEX.json';
+export const OBSERVER_PROJECTS_FILE = 'PROJECTS.json';
+
+function ensureDataDir(dataDir) {
+  if (!dataDir) throw new Error('dataDir é obrigatório.');
+  mkdirSync(dataDir, { recursive: true });
+}
+
+function atomicJson(path, value) {
+  const temp = `${path}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  renameSync(temp, path);
+}
+
+function readJson(path, fallback) {
+  if (!existsSync(path)) return fallback;
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch { return fallback; }
+}
+
+function projectIdValid(projectId) {
+  return typeof projectId === 'string'
+    && /^[A-Za-z0-9][A-Za-z0-9._:-]{0,120}$/.test(projectId);
+}
+
+function registeredProjects(dataDir) {
+  const raw = readJson(join(dataDir, OBSERVER_PROJECTS_FILE), {
+    schema_version: OBSERVER_DATA_SCHEMA_VERSION,
+    projects: {},
+  });
+  return raw?.schema_version === OBSERVER_DATA_SCHEMA_VERSION && raw.projects && typeof raw.projects === 'object'
+    ? raw.projects
+    : {};
+}
+
+export function registerObserverProject(dataDir, {
+  projectId,
+  projectName = projectId,
+  wendkeepVersion = '',
+  registeredAt = new Date().toISOString(),
+} = {}) {
+  ensureDataDir(dataDir);
+  if (!projectIdValid(projectId)) return { registered: false, errors: ['project_id inválido.'] };
+  const projects = registeredProjects(dataDir);
+  const project = {
+    projectId,
+    projectName: String(projectName || projectId).replace(/[\u0000-\u001f\u007f]/g, ' ').slice(0, 120),
+    wendkeepVersion: String(wendkeepVersion || '').slice(0, 40),
+    registeredAt: String(registeredAt),
+  };
+  projects[projectId] = project;
+  atomicJson(join(dataDir, OBSERVER_PROJECTS_FILE), {
+    schema_version: OBSERVER_DATA_SCHEMA_VERSION,
+    projects,
+  });
+  return { registered: true, project };
+}
+
+export function listRegisteredObserverProjects(dataDir) {
+  return Object.values(registeredProjects(dataDir)).sort((a, b) => a.projectId.localeCompare(b.projectId));
+}
+
+function readEvents(dataDir) {
+  const path = join(dataDir, OBSERVER_EVENTS_FILE);
+  if (!existsSync(path)) return [];
+  const events = [];
+  const lines = readFileSync(path, 'utf8').replace(/\r\n/g, '\n').split('\n').filter((line) => line.trim());
+  for (const line of lines) {
+    try {
+      const event = JSON.parse(line);
+      if (validateObserverSnapshot(event).ok) events.push(event);
+    } catch { /* corrupt lines never become part of the derived index */ }
+  }
+  return events;
+}
+
+function newer(left, right) {
+  const leftTime = Date.parse(left?.captured_at || '') || 0;
+  const rightTime = Date.parse(right?.captured_at || '') || 0;
+  return leftTime > rightTime || (leftTime === rightTime && String(left?.event_id).localeCompare(String(right?.event_id)) > 0);
+}
+
+export function rebuildObserverIndex(dataDir) {
+  ensureDataDir(dataDir);
+  const byProject = new Map();
+  for (const event of readEvents(dataDir)) {
+    const current = byProject.get(event.project_id);
+    if (!current || newer(event, current.snapshot)) {
+      byProject.set(event.project_id, {
+        projectId: event.project_id,
+        projectName: event.project_name,
+        latestEventId: event.event_id,
+        capturedAt: event.captured_at,
+        snapshot: event,
+        eventCount: 0,
+      });
+    }
+  }
+  for (const event of readEvents(dataDir)) {
+    const item = byProject.get(event.project_id);
+    if (item) item.eventCount += 1;
+  }
+  const index = {
+    schema_version: OBSERVER_DATA_SCHEMA_VERSION,
+    generated_at: new Date().toISOString(),
+    projects: [...byProject.values()].sort((a, b) => a.projectId.localeCompare(b.projectId)),
+  };
+  atomicJson(join(dataDir, OBSERVER_INDEX_FILE), index);
+  return index;
+}
+
+export function readObserverIndex(dataDir) {
+  ensureDataDir(dataDir);
+  const path = join(dataDir, OBSERVER_INDEX_FILE);
+  const index = readJson(path, null);
+  if (index?.schema_version === OBSERVER_DATA_SCHEMA_VERSION && Array.isArray(index.projects)) return index;
+  return rebuildObserverIndex(dataDir);
+}
+
+export function appendObserverEvent(dataDir, event) {
+  ensureDataDir(dataDir);
+  const validation = validateObserverSnapshot(event);
+  if (!validation.ok || validation.size > MAX_SNAPSHOT_BYTES) {
+    return { accepted: false, errors: validation.errors || ['snapshot inválido.'] };
+  }
+  const projects = registeredProjects(dataDir);
+  if (!projects[event.project_id]) {
+    return { accepted: false, errors: [`project_id não registrado: ${event.project_id}`] };
+  }
+  const eventsPath = join(dataDir, OBSERVER_EVENTS_FILE);
+  const existing = readEvents(dataDir).find((item) => item.event_id === event.event_id);
+  if (existing) {
+    if (JSON.stringify(existing) !== JSON.stringify(event)) {
+      return { accepted: false, errors: [`event_id reutilizado com payload diferente: ${event.event_id}`] };
+    }
+    return { accepted: false, duplicate: true, event_id: event.event_id, index: readObserverIndex(dataDir) };
+  }
+  appendFileSync(eventsPath, `${JSON.stringify(event)}\n`, 'utf8');
+  return {
+    accepted: true,
+    duplicate: false,
+    event_id: event.event_id,
+    index: rebuildObserverIndex(dataDir),
+  };
+}
+
+export function getObserverProject(dataDir, projectId) {
+  return readObserverIndex(dataDir).projects.find((project) => project.projectId === projectId) || null;
+}