wendkeep 0.87.0 → 0.89.0

package/packages/observer/src/encryption.mjs

@@ -0,0 +1,75 @@
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+
+function encryptionError(code, message) {
+  return Object.assign(new Error(message), { code });
+}
+
+function resolveKey(adapter, operation) {
+  const candidate = adapter?.keyProvider?.({ keyId: adapter.keyId, operation });
+  if (candidate && typeof candidate.then === 'function') {
+    throw encryptionError('observer_encryption_key_invalid', 'Observer key provider deve ser síncrono para SQLite.');
+  }
+  const key = candidate == null ? null : Buffer.from(candidate);
+  if (!key || key.byteLength !== 32) {
+    throw encryptionError('observer_encryption_key_unavailable', 'Chave externa AES-256-GCM indisponível.');
+  }
+  return key;
+}
+
+export function createObserverEncryption({ keyProvider, required = false, keyId = '' } = {}) {
+  if (required && typeof keyProvider !== 'function') {
+    throw encryptionError('observer_encryption_key_unavailable', 'Key provider externo é obrigatório.');
+  }
+  return { algorithm: 'AES-256-GCM', keyProvider, required: Boolean(required), keyId: String(keyId || '') };
+}
+
+export function observerEncryptionFromEnvironment({ env = process.env, required = false } = {}) {
+  const raw = String(env.WENDKEEP_OBSERVER_ENCRYPTION_KEY || '').trim();
+  if (!raw) {
+    if (required) throw encryptionError('observer_encryption_key_unavailable', 'WENDKEEP_OBSERVER_ENCRYPTION_KEY é obrigatória.');
+    return null;
+  }
+  const key = /^[a-f0-9]{64}$/i.test(raw) ? Buffer.from(raw, 'hex') : Buffer.from(raw, 'base64');
+  if (key.byteLength !== 32) throw encryptionError('observer_encryption_key_invalid', 'WENDKEEP_OBSERVER_ENCRYPTION_KEY deve ter 32 bytes em hex/base64.');
+  return createObserverEncryption({
+    required: true,
+    keyId: String(env.WENDKEEP_OBSERVER_ENCRYPTION_KEY_ID || 'observer-local-v1'),
+    keyProvider: () => key,
+  });
+}
+
+export function encryptObserverValue(adapter, value, { aad = '' } = {}) {
+  if (!adapter?.required && typeof adapter?.keyProvider !== 'function') return null;
+  const key = resolveKey(adapter, 'encrypt');
+  const iv = randomBytes(12);
+  const cipher = createCipheriv('aes-256-gcm', key, iv);
+  if (aad) cipher.setAAD(Buffer.from(String(aad), 'utf8'));
+  const plaintext = Buffer.from(String(value ?? ''), 'utf8');
+  const ciphertext = Buffer.concat([cipher.update(plaintext), cipher.final()]);
+  return {
+    schema_version: 1,
+    algorithm: 'AES-256-GCM',
+    key_id: adapter.keyId,
+    iv: iv.toString('base64'),
+    ciphertext: ciphertext.toString('base64'),
+    auth_tag: cipher.getAuthTag().toString('base64'),
+  };
+}
+
+export function decryptObserverValue(adapter, envelope, { aad = '' } = {}) {
+  if (!envelope) return '';
+  try {
+    if (envelope.algorithm !== 'AES-256-GCM') throw new Error('unsupported envelope');
+    const key = resolveKey({ ...adapter, keyId: envelope.key_id || adapter?.keyId }, 'decrypt');
+    const decipher = createDecipheriv('aes-256-gcm', key, Buffer.from(envelope.iv, 'base64'));
+    if (aad) decipher.setAAD(Buffer.from(String(aad), 'utf8'));
+    decipher.setAuthTag(Buffer.from(envelope.auth_tag, 'base64'));
+    return Buffer.concat([
+      decipher.update(Buffer.from(envelope.ciphertext, 'base64')),
+      decipher.final(),
+    ]).toString('utf8');
+  } catch (cause) {
+    if (cause?.code === 'observer_encryption_key_unavailable') throw cause;
+    throw encryptionError('observer_decryption_failed', 'Conteúdo protegido indisponível ou chave incorreta.');
+  }
+}

package/packages/observer/src/index.mjs

@@ -0,0 +1,7 @@
+export * from './policy.mjs';
+export * from './redaction.mjs';
+export * from './authz.mjs';
+export * from './token-registry.mjs';
+export * from './encryption.mjs';
+export * from './retention.mjs';
+export * from './purge.mjs';

package/packages/observer/src/policy.mjs

@@ -0,0 +1,305 @@
+import { createHash } from 'node:crypto';
+import { redactObserverValue } from './redaction.mjs';
+
+const CAPTURE = {
+  document: new Set(['none', 'metadata', 'selected', 'full']),
+  transcript: new Set(['none', 'metadata', 'messages', 'full']),
+  prompt: new Set(['none', 'redacted', 'full']),
+  response: new Set(['none', 'redacted', 'full']),
+  usage: new Set(['none', 'aggregate', 'calls']),
+};
+
+const DEFAULTS = Object.freeze({
+  document_capture: 'metadata',
+  transcript_capture: 'metadata',
+  prompt_capture: 'redacted',
+  response_capture: 'redacted',
+  usage_capture: 'aggregate',
+  require_loopback_auth: false,
+  encryption_required: false,
+});
+
+const SESSION_FIELDS = [
+  'session_id', 'sessionId', 'provider', 'status', 'change_slug', 'changeSlug',
+];
+const SESSION_TIMESTAMPS = ['started_at', 'startedAt', 'ended_at', 'endedAt'];
+const AGENT_FIELDS = [
+  ...SESSION_FIELDS, 'agent_id', 'agentId', 'parent_agent_id', 'parentAgentId',
+  'role', 'agent_type', 'agentType', 'workflow', 'model', 'effort',
+];
+
+function structuralFields(strings, integers = [], timestamps = []) {
+  return Object.freeze({
+    strings: Object.freeze(strings),
+    integers: Object.freeze(integers),
+    timestamps: Object.freeze(timestamps),
+  });
+}
+
+export const OBSERVER_EVENT_STRUCTURAL_CONTRACT = Object.freeze({
+  envelope: structuralFields(['event_id', 'kind', 'project_id'], ['schema_version'], ['occurred_at']),
+  payload: Object.freeze({
+    'document.upsert': structuralFields([
+      'document_id', 'documentId', 'logical_path', 'logicalPath', 'entity_type', 'entityType',
+      'source_session_id', 'sourceSessionId', 'source_turn_id', 'sourceTurnId',
+      'operation', 'op',
+    ], ['revision'], ['captured_at', 'capturedAt']),
+    'document.delete': structuralFields([
+      'logical_path', 'logicalPath', 'entity_type', 'entityType',
+      'source_session_id', 'sourceSessionId', 'source_turn_id', 'sourceTurnId',
+      'operation', 'op',
+    ], ['revision']),
+    'session.upsert': structuralFields([...SESSION_FIELDS], [], [...SESSION_TIMESTAMPS]),
+    'agent.upsert': structuralFields([...AGENT_FIELDS], [], [...SESSION_TIMESTAMPS]),
+    'usage.rollup': structuralFields([
+      ...AGENT_FIELDS, 'rollup_key', 'rollupKey', 'model_provider', 'modelProvider',
+      'cost_status', 'costStatus', 'pricing_source', 'pricingSource', 'pricing_version', 'pricingVersion',
+    ], ['revision'], [...SESSION_TIMESTAMPS]),
+    llm_call: structuralFields([
+      ...AGENT_FIELDS, 'call_id', 'callId', 'model_provider', 'modelProvider',
+      'cost_status', 'costStatus', 'transcript_id', 'transcriptId',
+    ], ['sequence'], [...SESSION_TIMESTAMPS, 'occurred_at']),
+    'transcript.upsert': structuralFields([
+      ...AGENT_FIELDS, 'transcript_id', 'transcriptId', 'coverage', 'source',
+    ], [], [...SESSION_TIMESTAMPS]),
+  }),
+});
+
+function policyError(message) {
+  return Object.assign(new Error(message), { code: 'observer_policy_invalid' });
+}
+
+function assertObject(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw policyError(`${label} inválido.`);
+}
+
+function assertKnownKeys(value, allowed, label) {
+  const unknown = Object.keys(value).find((key) => !allowed.has(key));
+  if (unknown) throw policyError(`${label} contém campo desconhecido: ${unknown}`);
+}
+
+function captureFor(policy, dataClass) {
+  return policy[`${dataClass}_capture`];
+}
+
+function globMatches(pattern, value) {
+  if (!pattern) return true;
+  const escaped = String(pattern).replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replaceAll('**', '\u0000').replaceAll('*', '[^/]*').replaceAll('\u0000', '.*');
+  return new RegExp(`^${escaped}$`, 'u').test(String(value || '').replaceAll('\\', '/'));
+}
+
+function ruleMatches(rule, context) {
+  return (!rule.project_id || rule.project_id === context.projectId)
+    && (!rule.data_class || rule.data_class === context.dataClass)
+    && (!rule.entity_type || rule.entity_type === context.entityType)
+    && globMatches(rule.path, context.path);
+}
+
+export function createObserverPolicy(input = {}) {
+  assertObject(input, 'policy');
+  assertKnownKeys(input, new Set([
+    'document_capture', 'transcript_capture', 'prompt_capture', 'response_capture', 'usage_capture',
+    'require_loopback_auth', 'encryption_required', 'rules', 'redaction', 'retention',
+  ]), 'policy');
+  for (const field of ['require_loopback_auth', 'encryption_required']) {
+    if (Object.hasOwn(input, field) && typeof input[field] !== 'boolean') throw policyError(`${field} deve ser boolean.`);
+  }
+  if (Object.hasOwn(input, 'rules') && !Array.isArray(input.rules)) throw policyError('rules deve ser array.');
+  if (Object.hasOwn(input, 'redaction')) {
+    assertObject(input.redaction, 'redaction');
+    assertKnownKeys(input.redaction, new Set(['rules']), 'redaction');
+    if (Object.hasOwn(input.redaction, 'rules') && !Array.isArray(input.redaction.rules)) throw policyError('redaction.rules deve ser array.');
+  }
+  if (Object.hasOwn(input, 'retention')) {
+    assertObject(input.retention, 'retention');
+    assertKnownKeys(input.retention, new Set(['document', 'transcript', 'prompt', 'response', 'usage', 'documents', 'calls', 'transcripts']), 'retention');
+    if (Object.values(input.retention).some((value) => !Number.isInteger(value) || value < 0)) throw policyError('retention deve usar inteiros não negativos.');
+  }
+  const policy = {
+    ...DEFAULTS,
+    ...input,
+    rules: Array.isArray(input.rules) ? input.rules.map((rule) => ({ ...rule })) : [],
+    redaction: input.redaction && typeof input.redaction === 'object' ? structuredClone(input.redaction) : {},
+    retention: input.retention && typeof input.retention === 'object' ? structuredClone(input.retention) : {},
+  };
+  for (const rule of policy.rules) {
+    assertObject(rule, 'rule');
+    assertKnownKeys(rule, new Set(['project_id', 'data_class', 'path', 'entity_type', 'capture']), 'rule');
+  }
+  for (const rule of policy.redaction.rules || []) {
+    assertObject(rule, 'redaction rule');
+    assertKnownKeys(rule, new Set(['pattern', 'replacement']), 'redaction rule');
+    if (String(rule.replacement || '').length > 160) throw policyError('replacement de redaction excede o limite.');
+  }
+  for (const rule of policy.redaction.rules || []) {
+    const pattern = String(rule?.pattern || '');
+    if (!pattern || pattern.length > 512 || /\\[1-9]/.test(pattern)
+      || /\((?:[^()\\]|\\.)*[+*](?:[^()\\]|\\.)*\)\s*(?:[+*]|\{\d*,?\d*\})/.test(pattern)) {
+      throw policyError('regra de redaction insegura ou inválida.');
+    }
+    try { new RegExp(pattern, 'giu'); }
+    catch { throw policyError('regra de redaction insegura ou inválida.'); }
+  }
+  for (const dataClass of Object.keys(CAPTURE)) {
+    const capture = captureFor(policy, dataClass);
+    if (!CAPTURE[dataClass].has(capture)) throw policyError(`capture inválido para ${dataClass}: ${capture}`);
+  }
+  for (const rule of policy.rules) {
+    if (!CAPTURE[rule.data_class]?.has(rule.capture)) {
+      throw policyError(`regra de capture inválida para ${rule.data_class || 'classe ausente'}`);
+    }
+  }
+  return policy;
+}
+
+export function saveObserverPolicy(db, projectId, policyInput, { updatedAt = new Date().toISOString() } = {}) {
+  const policy = createObserverPolicy(policyInput);
+  db.prepare(`INSERT INTO observer_retention_policies(project_id, policy_json, updated_at)
+    VALUES (?, ?, ?) ON CONFLICT(project_id) DO UPDATE SET policy_json = excluded.policy_json, updated_at = excluded.updated_at`)
+    .run(projectId, JSON.stringify(policy), new Date(updatedAt).toISOString());
+  return policy;
+}
+
+export function readObserverPolicy(db, projectId) {
+  const row = db.prepare('SELECT policy_json FROM observer_retention_policies WHERE project_id = ?').get(projectId);
+  return row ? createObserverPolicy(JSON.parse(row.policy_json)) : createObserverPolicy();
+}
+
+export function evaluateObserverPolicy(policyInput, context = {}) {
+  const policy = policyInput?.rules ? policyInput : createObserverPolicy(policyInput);
+  const dataClass = String(context.dataClass || 'document');
+  if (!CAPTURE[dataClass]) throw policyError(`classe de dado desconhecida: ${dataClass}`);
+  let capture = captureFor(policy, dataClass);
+  for (const rule of policy.rules) {
+    if (ruleMatches(rule, { ...context, dataClass })) capture = rule.capture;
+  }
+  return {
+    data_class: dataClass,
+    capture,
+    encryption_required: Boolean(policy.encryption_required),
+    retention_days: Number(policy.retention?.[dataClass] ?? 0) || 0,
+  };
+}
+
+function metadataOnly(payload, capture) {
+  return {
+    ...payload,
+    content: '',
+    coverage: payload.coverage ? 'summary_only' : payload.coverage,
+    capture,
+  };
+}
+
+function protectText(value, capture, redaction) {
+  if (capture === 'none') return '';
+  if (capture === 'redacted') return redactObserverValue(value, redaction);
+  return String(value ?? '');
+}
+
+function preserveStructuralFields(original, protectedValue, contract) {
+  for (const key of contract?.strings || []) {
+    if (!Object.hasOwn(original, key)) continue;
+    const value = original[key];
+    if (value !== null && typeof value !== 'string') throw policyError(`${key} estrutural deve ser string ou null.`);
+    protectedValue[key] = value;
+  }
+  for (const key of contract?.integers || []) {
+    if (!Object.hasOwn(original, key)) continue;
+    const value = original[key];
+    if (!Number.isInteger(value) || value < 0) throw policyError(`${key} estrutural deve ser inteiro não negativo.`);
+    protectedValue[key] = value;
+  }
+  for (const key of contract?.timestamps || []) {
+    if (!Object.hasOwn(original, key)) continue;
+    const value = original[key];
+    if (value !== null && (typeof value !== 'string' || Number.isNaN(Date.parse(value)))) {
+      throw policyError(`${key} estrutural deve ser date-time ou null.`);
+    }
+    protectedValue[key] = value;
+  }
+  return protectedValue;
+}
+
+function protectedContentHash(value) {
+  return createHash('sha256').update(String(value ?? '')).digest('hex');
+}
+
+function transcriptMessagesOnly(value) {
+  const source = String(value || '');
+  const sanitizeMessage = (item) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) return null;
+    const role = String(item.role || '');
+    if (!['user', 'assistant', 'system'].includes(role) || typeof item.content !== 'string') return null;
+    return { role, content: item.content };
+  };
+  const sanitizeMessages = (items) => items.map(sanitizeMessage).filter(Boolean);
+  try {
+    const parsed = JSON.parse(source);
+    if (Array.isArray(parsed)) return JSON.stringify(sanitizeMessages(parsed));
+    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && Array.isArray(parsed.messages)) {
+      return JSON.stringify({ messages: sanitizeMessages(parsed.messages) });
+    }
+    return '';
+  } catch {
+    const lines = source.split(/\r?\n/u).filter(Boolean);
+    const items = lines.map((line) => {
+      try { return JSON.parse(line); } catch { return null; }
+    });
+    if (!lines.length || items.some((item) => item === null)) return '';
+    return sanitizeMessages(items).map(JSON.stringify).join('\n');
+  }
+}
+
+export function protectObserverEvent(event, { policy: policyInput = {} } = {}) {
+  const policy = policyInput?.rules ? policyInput : createObserverPolicy(policyInput);
+  const payload = structuredClone(event?.payload || {});
+  const context = {
+    projectId: String(event?.project_id || ''),
+    path: String(payload.logical_path || ''),
+    entityType: String(payload.entity_type || ''),
+  };
+  let protectedPayload = preserveStructuralFields(
+    payload,
+    redactObserverValue(payload, policy.redaction),
+    OBSERVER_EVENT_STRUCTURAL_CONTRACT.payload[event?.kind],
+  );
+  if (event?.kind === 'document.delete') {
+    delete protectedPayload.content;
+    delete protectedPayload.content_hash;
+    delete protectedPayload.contentHash;
+  } else if (event?.kind?.startsWith('document.')) {
+    const decision = evaluateObserverPolicy(policy, { ...context, dataClass: 'document' });
+    if (decision.capture === 'none') return null;
+    if (decision.capture === 'metadata' || decision.capture === 'selected') protectedPayload = metadataOnly(protectedPayload, decision.capture);
+    else protectedPayload.capture = decision.capture;
+  } else if (event?.kind === 'transcript.upsert') {
+    const decision = evaluateObserverPolicy(policy, { ...context, dataClass: 'transcript' });
+    if (decision.capture === 'none') return null;
+    if (decision.capture === 'metadata') protectedPayload = metadataOnly(protectedPayload, decision.capture);
+    else if (decision.capture === 'messages') {
+      protectedPayload.content = transcriptMessagesOnly(protectedPayload.content);
+      protectedPayload.capture = decision.capture;
+    }
+    else protectedPayload.capture = decision.capture;
+  } else if (event?.kind === 'usage.rollup') {
+    const usageDecision = evaluateObserverPolicy(policy, { ...context, dataClass: 'usage' });
+    if (usageDecision.capture === 'none') return null;
+    protectedPayload.capture = usageDecision.capture;
+  } else if (event?.kind === 'llm_call') {
+    const usageDecision = evaluateObserverPolicy(policy, { ...context, dataClass: 'usage' });
+    if (usageDecision.capture !== 'calls') return null;
+    const promptDecision = evaluateObserverPolicy(policy, { ...context, dataClass: 'prompt' });
+    const responseDecision = evaluateObserverPolicy(policy, { ...context, dataClass: 'response' });
+    protectedPayload.prompt_text = protectText(payload.prompt_text ?? payload.prompt, promptDecision.capture, policy.redaction);
+    protectedPayload.response_text = protectText(payload.response_text ?? payload.response, responseDecision.capture, policy.redaction);
+    delete protectedPayload.prompt;
+    delete protectedPayload.response;
+    protectedPayload.capture = usageDecision.capture;
+  }
+  if (event?.kind === 'document.upsert' || event?.kind === 'transcript.upsert') {
+    protectedPayload.content_hash = protectedContentHash(protectedPayload.content);
+    delete protectedPayload.contentHash;
+  }
+  return { ...event, payload: protectedPayload };
+}

package/packages/observer/src/purge.mjs

@@ -0,0 +1,100 @@
+import { createHash } from 'node:crypto';
+
+const TABLES = {
+  documents: { table: 'documents', time: 'captured_at', id: 'document_id' },
+  calls: { table: 'llm_calls', time: 'occurred_at', id: 'call_pk' },
+  transcripts: { table: 'transcripts', time: 'occurred_at', id: 'transcript_pk' },
+};
+
+function canonical(value) {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value && typeof value === 'object') return Object.fromEntries(Object.keys(value).sort().map((key) => [key, canonical(value[key])]));
+  return value;
+}
+
+function digest(value) {
+  return `sha256:${createHash('sha256').update(JSON.stringify(canonical(value))).digest('hex')}`;
+}
+
+export function verifyObserverPurgeReceipt(receipt = {}) {
+  const candidate = { ...receipt };
+  const expected = String(candidate.receipt_hash || '');
+  delete candidate.receipt_hash;
+  delete candidate.idempotent;
+  return Boolean(expected) && digest(candidate) === expected;
+}
+
+export function purgeObserverData(db, {
+  projectId, before, classes = Object.keys(TABLES), now = new Date().toISOString(), dryRun = false,
+  operationId = '', beforeCommit, receiptSink,
+} = {}) {
+  const normalizedClasses = [...new Set(classes)].sort();
+  if (!normalizedClasses.length || normalizedClasses.some((item) => !TABLES[item])) {
+    throw Object.assign(new Error('classes de purge inválidas.'), { code: 'observer_purge_invalid' });
+  }
+  const cutoff = new Date(before).toISOString();
+  const requestHash = digest({ project_id: projectId, before: cutoff, classes: normalizedClasses });
+  db.exec('BEGIN IMMEDIATE');
+  let transactionOpen = true;
+  try {
+    const requestedReceiptId = operationId
+      ? digest({ request_hash: requestHash, operation_id: String(operationId) }).slice(7, 39)
+      : '';
+    const candidates = Object.fromEntries(normalizedClasses.map((dataClass) => {
+      const spec = TABLES[dataClass];
+      const rows = db.prepare(`SELECT ${spec.id} AS id FROM ${spec.table} WHERE project_id = ? AND ${spec.time} < ? ORDER BY ${spec.id}`).all(projectId, cutoff);
+      return [dataClass, rows.map((row) => row.id)];
+    }));
+    const counts = Object.fromEntries(normalizedClasses.map((dataClass) => [dataClass, candidates[dataClass].length]));
+    if (dryRun) {
+      db.exec('COMMIT');
+      transactionOpen = false;
+      return { dry_run: true, project_id: projectId, before: cutoff, classes: normalizedClasses, counts };
+    }
+    const noCandidates = Object.values(counts).every((count) => count === 0);
+    if (noCandidates) {
+      const previous = requestedReceiptId
+        ? db.prepare('SELECT receipt_json FROM observer_purge_receipts WHERE receipt_id = ?').get(requestedReceiptId)
+        : db.prepare('SELECT receipt_json FROM observer_purge_receipts WHERE project_id = ? AND request_hash = ? ORDER BY purged_at DESC LIMIT 1').get(projectId, requestHash);
+      if (previous) {
+        db.exec('COMMIT');
+        transactionOpen = false;
+        const replay = { ...JSON.parse(previous.receipt_json), idempotent: true };
+        receiptSink?.(replay);
+        return replay;
+      }
+    }
+    const operationExists = requestedReceiptId && db.prepare('SELECT receipt_id FROM observer_purge_receipts WHERE receipt_id = ?').get(requestedReceiptId);
+    const receiptId = operationExists
+      ? digest({ request_hash: requestHash, operation_id: String(operationId), candidates }).slice(7, 39)
+      : requestedReceiptId || digest({ request_hash: requestHash, candidates }).slice(7, 39);
+    const receipt = {
+      schema_version: 1, receipt_id: receiptId, project_id: projectId, before: cutoff,
+      classes: normalizedClasses, counts, purged_at: new Date(now).toISOString(),
+    };
+    receipt.receipt_hash = digest(receipt);
+    for (const dataClass of normalizedClasses) {
+      const spec = TABLES[dataClass];
+      if (dataClass === 'documents' && db.prepare("SELECT COUNT(*) AS count FROM sqlite_master WHERE type = 'table' AND name = 'evidence_chunks_fts'").get().count) {
+        db.prepare('DELETE FROM evidence_chunks_fts WHERE project_id = ? AND logical_path IN (SELECT logical_path FROM documents WHERE project_id = ? AND captured_at < ?)').run(projectId, projectId, cutoff);
+      }
+      db.prepare(`DELETE FROM ${spec.table} WHERE project_id = ? AND ${spec.time} < ?`).run(projectId, cutoff);
+      const kind = dataClass === 'documents' ? 'document.%' : dataClass === 'calls' ? 'llm_call' : 'transcript.upsert';
+      const comparator = dataClass === 'documents' ? 'LIKE' : '=';
+      db.prepare(`DELETE FROM ingest_events WHERE project_id = ? AND kind ${comparator} ? AND occurred_at < ?`).run(projectId, kind, cutoff);
+    }
+    beforeCommit?.(receipt);
+    db.prepare(`INSERT INTO observer_purge_receipts(receipt_id, project_id, request_hash, cutoff_at, classes_json, counts_json, purged_at, receipt_hash, receipt_json)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(
+      receipt.receipt_id, projectId, requestHash, cutoff, JSON.stringify(normalizedClasses), JSON.stringify(counts),
+      receipt.purged_at, receipt.receipt_hash, JSON.stringify(receipt),
+    );
+    db.exec('COMMIT');
+    transactionOpen = false;
+    receiptSink?.(receipt);
+    return { ...receipt, idempotent: false };
+  } catch (error) {
+    if (transactionOpen) db.exec('ROLLBACK');
+    throw error;
+  }
+}

package/packages/observer/src/redaction.mjs

@@ -0,0 +1,54 @@
+import { basename } from 'node:path';
+
+const SENSITIVE_KEY = /(?:authorization|password|passwd|secret|api[_-]?key|connection[_-]?string|cookie)|^(?:token|access[_-]?token|refresh[_-]?token|auth[_-]?token|bearer[_-]?token)$/i;
+const PATH_KEY = /^(?:transcript_path|agent_transcript_path|transcriptPath|agentTranscriptPath)$/i;
+const BUILT_INS = [
+  [/\bBearer\s+[A-Za-z0-9._~+/=-]+/gi, 'Bearer [REDACTED]'],
+  [/\b(?:postgres(?:ql)?|mysql|mongodb(?:\+srv)?|redis):\/\/([^\s/:@]+):([^\s/@]+)@/gi, (_all, user) => `postgres://${user}:[REDACTED]@`],
+  [/\b(https?:\/\/)([^\s/:@]+):([^\s/@]+)@/gi, '$1$2:[REDACTED]@'],
+  [/\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi, '[EMAIL]'],
+  [/(?:\+?\d{1,3}[\s.-]?)?(?:\(?\d{2}\)?[\s.-]?)?\d{4,5}[\s.-]?\d{4}\b/g, '[PHONE]'],
+  [/\b(?:AKIA|ASIA)[A-Z0-9]{16}\b/g, '[ACCESS_KEY]'],
+];
+
+function sourceLabel(value) {
+  return basename(String(value || '').replaceAll('\\', '/'));
+}
+
+function customRules(config = {}) {
+  return (Array.isArray(config.rules) ? config.rules : []).flatMap((rule) => {
+    try {
+      if (!rule?.pattern) return [];
+      return [[new RegExp(String(rule.pattern), 'giu'), String(rule.replacement || '[REDACTED]')]];
+    } catch {
+      return [];
+    }
+  });
+}
+
+export function redactObserverText(value, config = {}) {
+  let result = String(value ?? '');
+  for (const [pattern, replacement] of [...BUILT_INS, ...customRules(config)]) {
+    result = result.replace(pattern, replacement);
+  }
+  return result;
+}
+
+export function redactObserverValue(value, config = {}, key = '') {
+  if (PATH_KEY.test(key)) return sourceLabel(value);
+  if (SENSITIVE_KEY.test(key)) return value ? '[REDACTED]' : value;
+  if (typeof value === 'string') return redactObserverText(value, config);
+  if (Array.isArray(value)) return value.map((item) => redactObserverValue(item, config));
+  if (!value || typeof value !== 'object') return value;
+  return Object.fromEntries(Object.entries(value).map(([childKey, item]) => [
+    childKey,
+    redactObserverValue(item, config, childKey),
+  ]));
+}
+
+export function sanitizeObserverAuditMetadata(metadata = {}, config = {}) {
+  const allowed = new Set(['route', 'method', 'remote_address', 'user_agent', 'reason', 'resource_id']);
+  return Object.fromEntries(Object.entries(metadata || {})
+    .filter(([key]) => allowed.has(key))
+    .map(([key, value]) => [key, redactObserverValue(value, config, key)]));
+}

package/packages/observer/src/retention.mjs

@@ -0,0 +1,39 @@
+import { purgeObserverData } from './purge.mjs';
+
+const CLASSES = ['documents', 'calls', 'transcripts'];
+
+export function observerRetentionCutoffs(policy = {}, now = new Date()) {
+  const timestamp = new Date(now);
+  if (Number.isNaN(timestamp.getTime())) throw Object.assign(new Error('retention clock inválido.'), { code: 'observer_retention_invalid' });
+  return Object.fromEntries(CLASSES.flatMap((dataClass) => {
+    const days = Number(policy[dataClass] ?? 0);
+    if (!Number.isInteger(days) || days < 0) throw Object.assign(new Error(`retention inválida para ${dataClass}.`), { code: 'observer_retention_invalid' });
+    return days === 0 ? [] : [[dataClass, new Date(timestamp.getTime() - days * 86_400_000).toISOString()]];
+  }));
+}
+
+export function runObserverRetention(db, {
+  projectId, policy = {}, clock = () => new Date(), dryRun = false, operationId = '', receiptSink,
+} = {}) {
+  const observedAt = clock();
+  const cutoffs = observerRetentionCutoffs(policy, observedAt);
+  const receipts = [];
+  for (const [dataClass, before] of Object.entries(cutoffs)) {
+    receipts.push(purgeObserverData(db, {
+      projectId,
+      before,
+      classes: [dataClass],
+      dryRun,
+      operationId: operationId ? `${operationId}:${dataClass}` : '',
+      now: observedAt,
+      receiptSink,
+    }));
+  }
+  return {
+    schema_version: 1,
+    project_id: projectId,
+    observed_at: new Date(observedAt).toISOString(),
+    cutoffs,
+    receipts,
+  };
+}