codetac 0.1.0

package/src/sentences.mjs

@@ -0,0 +1,209 @@
+// Frases fixas, geradas só dos factos gravados (modo sem IA e base de
+// comparação para as frases da IA). Idioma: CODETAC_LANG (pt-PT por omissão).
+// Nenhuma frase interpreta o nome de uma função: diz o que se observou.
+
+export const LANGUAGES = ['pt-PT', 'en'];
+export function language(value = process.env.CODETAC_LANG) {
+  const text = String(value ?? '').toLowerCase();
+  return text.startsWith('en') ? 'en' : 'pt-PT';
+}
+
+const list = (items, and) => items.length <= 1 ? items.join('') : `${items.slice(0, -1).join(', ')} ${and} ${items.at(-1)}`;
+const names = (items, and, max = 4) => items.length > max ? `${items.slice(0, max).join(', ')} (+${items.length - max})` : list(items, and);
+
+function duration(ms, lang) {
+  if (ms == null) return '';
+  const text = ms < 1 ? ms.toFixed(2) + ' ms' : ms < 1000 ? ms.toFixed(1) + ' ms' : (ms / 1000).toFixed(2) + ' s';
+  return lang === 'en' ? text : text.replace('.', ',');
+}
+
+const PT = {
+  and: 'e',
+  rows: n => `${n} ${n === 1 ? 'linha' : 'linhas'}`,
+  read: (tables, rows) => `Lê ${tables || 'a base de dados'}${rows != null ? ` (${PT.rows(rows)})` : ''}`,
+  insert: (tables, n) => `Acrescenta ${n == null ? 'linhas' : PT.rows(n)} a ${tables || 'uma tabela'}`,
+  update: (tables, n) => n === 0 ? `Tenta alterar ${tables || 'uma tabela'}; nenhuma linha alterada` : `Altera ${n == null ? 'linhas' : PT.rows(n)} em ${tables || 'uma tabela'}`,
+  delete: (tables, n) => n === 0 ? `Tenta apagar em ${tables || 'uma tabela'}; nenhuma linha apagada` : `Apaga ${n == null ? 'linhas' : PT.rows(n)} em ${tables || 'uma tabela'}`,
+  create: (tables, ifNot) => `Cria a tabela ${tables || ''}${ifNot ? ' se ainda não existir' : ''}`.trim(),
+  alter: tables => `Altera a estrutura de ${tables || 'uma tabela'}`,
+  drop: tables => `Remove ${tables || 'uma tabela'}`,
+  otherDb: (op, tables) => `Comando ${op} na base de dados${tables ? ` (${tables})` : ''}`,
+  failed: 'falhou',
+  http: (method, host, path, status) => `Chama ${host}: ${method} ${path}${status != null ? ` (estado ${status})` : ''}`,
+  ai: (provider, model, usage) => `Pede uma resposta a ${provider}${model ? ` (${model})` : ''}${usage ? ` · ${usage.input ?? '?'} + ${usage.output ?? '?'} tokens` : ''}`,
+  email: (to, subject) => `Envia um email${to.length ? ` para ${to.join(', ')}` : ''}${subject ? ` «${subject}»` : ''}`,
+  message: (to, provider) => `Envia uma mensagem por ${provider}${to.length ? ` para ${to.join(', ')}` : ''}`,
+  payment: (provider, operation, mode) => `Pagamento em ${provider}: ${operation} (modo ${mode})`,
+  fileRead: (where, bytes) => `Lê o ficheiro ${where}${bytes ? ` (${bytes} bytes)` : ''}`,
+  fileWrite: (op, where, bytes) => `${op[0].toUpperCase() + op.slice(1)} de ficheiro: ${where}${bytes ? ` (${bytes} bytes)` : ''}`,
+  auth: (provider, operation) => `Autenticação em ${provider}${operation ? `: ${operation}` : ''}`,
+  // Funções
+  calls: items => `chama ${items}`,
+  noBoundary: 'Trabalho interno: nenhuma fronteira observada',
+  error: 'terminou com erro',
+  unfinished: 'não terminou durante a gravação',
+  dbSetupPart: n => `executa ${n} comandos de estrutura da base de dados`,
+  readPart: tables => `lê ${tables}`,
+  writePart: (verb, tables) => `${verb} ${tables}`,
+  writeVerbs: { INSERT: 'acrescenta a', UPDATE: 'altera', DELETE: 'apaga em', REPLACE: 'substitui em', UPSERT: 'acrescenta ou altera', MERGE: 'junta em' },
+  idleWritePart: tables => `tenta escrever em ${tables} sem alterar linhas`,
+  httpPart: hosts => `chama ${hosts}`,
+  aiPart: providers => `pede respostas a ${providers}`,
+  emailPart: n => n === 1 ? 'envia um email' : `envia ${n} emails`,
+  paymentPart: providers => `faz pagamentos em ${providers}`,
+  filePart: ops => `ficheiros: ${ops}`,
+  authPart: providers => `autenticação em ${providers}`,
+  // Grupos
+  dbSetup: (n, counts, tables, failed, changed, parentOk) => `Preparação da base de dados: ${n} comandos (${counts}) em ${tables} ${tables === 1 ? 'tabela' : 'tabelas'}` +
+    (failed ? ` · ${failed} falharam${parentOk ? ' sem interromper a função' : ''}` : '') +
+    (changed ? ` · inclui escritas que alteraram ${PT.rows(changed)}` : ''),
+  repeated: (sentence, n) => `${sentence} — ${n} vezes seguidas`,
+  block: (times, size, what) => `O mesmo conjunto de ${size} passos repetido ${times} vezes${what ? `: ${what}` : ''}`,
+  helpers: (n, fns) => `${n} funções auxiliares sem fronteiras: ${fns}`,
+  generated: n => `${n} funções de código gerado pelo bundler`,
+  devTools: n => `${n} ${n === 1 ? 'pedido' : 'pedidos'} da ferramenta de desenvolvimento (recompilação, hot reload)`,
+  // Efeitos
+  effects: {
+    added: (n, table) => `${n == null ? 'Linhas acrescentadas' : `${PT.rows(n)} ${n === 1 ? 'acrescentada' : 'acrescentadas'}`} em ${table}`,
+    changed: (n, table) => `${n == null ? 'Linhas alteradas' : `${PT.rows(n)} ${n === 1 ? 'alterada' : 'alteradas'}`} em ${table}`,
+    deleted: (n, table) => `${n == null ? 'Linhas apagadas' : `${PT.rows(n)} ${n === 1 ? 'apagada' : 'apagadas'}`} em ${table}`,
+    otherWrite: (op, table) => `${op} em ${table}`,
+    noChange: (op, table, n) => `${op} em ${table} sem linhas alteradas${n > 1 ? ` (${n} vezes)` : ''}`,
+    structure: (ok, failed) => `${ok + failed} comandos de estrutura da base de dados (${ok} sem erro${failed ? `, ${failed} falharam` : ''}); a gravação não indica se alteraram a base`,
+    email: (to, subject, failed) => `${failed ? 'Tentativa de email falhada' : 'Email enviado'}${to.length ? ` para ${to.join(', ')}` : ''}${subject ? ` «${subject}»` : ''}`,
+    message: (provider, failed) => `${failed ? 'Tentativa de mensagem falhada' : 'Mensagem enviada'} por ${provider}`,
+    payment: (provider, operation, mode) => `Pagamento em ${provider}: ${operation} (modo ${mode})`,
+    file: (op, where) => `Ficheiro: ${op} em ${where}`,
+    cookieSet: names => `Cookies guardados no browser: ${names}`,
+    cookieCleared: names => `Cookies apagados no browser: ${names}`,
+    ai: (provider, model, usage, cost) => `Chamada de IA a ${provider}${model ? ` (${model})` : ''}${usage ? ` · ${usage.input ?? '?'} + ${usage.output ?? '?'} tokens` : ''}${cost != null ? ` · ~US$ ${cost.toFixed(4)}` : ''}`,
+    external: (method, host, n) => `Chamada externa ${method} a ${host}${n > 1 ? ` (${n} vezes)` : ''}`,
+    none: 'Nenhum efeito permanente observado.',
+    unseen: 'Não observado: armazenamento local do browser e efeitos em serviços não reconhecidos.',
+  },
+  // Ação
+  action: {
+    click: label => `Clique em ${label}`,
+    submit: label => `Envio de ${label}`,
+    change: label => `Alteração em ${label}`,
+    continuation: 'Continuação após navegação',
+    request: (method, path, status) => `${method} ${path}${status != null ? ` (estado ${status})` : ''}`,
+    noServer: 'sem pedidos ao servidor',
+    screen: 'altera o ecrã',
+    noScreen: 'sem alteração visível no ecrã',
+    navigates: path => `muda para ${path}`,
+  },
+};
+
+const EN = {
+  and: 'and',
+  rows: n => `${n} ${n === 1 ? 'row' : 'rows'}`,
+  read: (tables, rows) => `Reads ${tables || 'the database'}${rows != null ? ` (${EN.rows(rows)})` : ''}`,
+  insert: (tables, n) => `Adds ${n == null ? 'rows' : EN.rows(n)} to ${tables || 'a table'}`,
+  update: (tables, n) => n === 0 ? `Tries to change ${tables || 'a table'}; no rows changed` : `Changes ${n == null ? 'rows' : EN.rows(n)} in ${tables || 'a table'}`,
+  delete: (tables, n) => n === 0 ? `Tries to delete from ${tables || 'a table'}; no rows deleted` : `Deletes ${n == null ? 'rows' : EN.rows(n)} from ${tables || 'a table'}`,
+  create: (tables, ifNot) => `Creates table ${tables || ''}${ifNot ? ' if it does not exist' : ''}`.trim(),
+  alter: tables => `Changes the structure of ${tables || 'a table'}`,
+  drop: tables => `Drops ${tables || 'a table'}`,
+  otherDb: (op, tables) => `${op} command on the database${tables ? ` (${tables})` : ''}`,
+  failed: 'failed',
+  http: (method, host, path, status) => `Calls ${host}: ${method} ${path}${status != null ? ` (status ${status})` : ''}`,
+  ai: (provider, model, usage) => `Asks ${provider} for a response${model ? ` (${model})` : ''}${usage ? ` · ${usage.input ?? '?'} + ${usage.output ?? '?'} tokens` : ''}`,
+  email: (to, subject) => `Sends an email${to.length ? ` to ${to.join(', ')}` : ''}${subject ? ` “${subject}”` : ''}`,
+  message: (to, provider) => `Sends a message via ${provider}${to.length ? ` to ${to.join(', ')}` : ''}`,
+  payment: (provider, operation, mode) => `Payment on ${provider}: ${operation} (${mode} mode)`,
+  fileRead: (where, bytes) => `Reads file ${where}${bytes ? ` (${bytes} bytes)` : ''}`,
+  fileWrite: (op, where, bytes) => `File ${op}: ${where}${bytes ? ` (${bytes} bytes)` : ''}`,
+  auth: (provider, operation) => `Authentication with ${provider}${operation ? `: ${operation}` : ''}`,
+  calls: items => `calls ${items}`,
+  noBoundary: 'Internal work: no boundary observed',
+  error: 'ended with an error',
+  unfinished: 'did not finish during the recording',
+  dbSetupPart: n => `runs ${n} database structure commands`,
+  readPart: tables => `reads ${tables}`,
+  writePart: (verb, tables) => `${verb} ${tables}`,
+  writeVerbs: { INSERT: 'adds to', UPDATE: 'changes', DELETE: 'deletes from', REPLACE: 'replaces in', UPSERT: 'adds or changes', MERGE: 'merges into' },
+  idleWritePart: tables => `tries to write to ${tables} without changing rows`,
+  httpPart: hosts => `calls ${hosts}`,
+  aiPart: providers => `asks ${providers} for responses`,
+  emailPart: n => n === 1 ? 'sends an email' : `sends ${n} emails`,
+  paymentPart: providers => `makes payments on ${providers}`,
+  filePart: ops => `files: ${ops}`,
+  authPart: providers => `authentication with ${providers}`,
+  dbSetup: (n, counts, tables, failed, changed, parentOk) => `Database setup: ${n} commands (${counts}) on ${tables} ${tables === 1 ? 'table' : 'tables'}` +
+    (failed ? ` · ${failed} failed${parentOk ? ' without stopping the function' : ''}` : '') +
+    (changed ? ` · includes writes that changed ${EN.rows(changed)}` : ''),
+  repeated: (sentence, n) => `${sentence} — ${n} times in a row`,
+  block: (times, size, what) => `The same ${size} steps repeated ${times} times${what ? `: ${what}` : ''}`,
+  helpers: (n, fns) => `${n} helper functions with no boundaries: ${fns}`,
+  generated: n => `${n} functions of bundler-generated code`,
+  devTools: n => `${n} development tool ${n === 1 ? 'request' : 'requests'} (recompilation, hot reload)`,
+  effects: {
+    added: (n, table) => `${n == null ? 'Rows' : EN.rows(n)} added to ${table}`,
+    changed: (n, table) => `${n == null ? 'Rows' : EN.rows(n)} changed in ${table}`,
+    deleted: (n, table) => `${n == null ? 'Rows' : EN.rows(n)} deleted from ${table}`,
+    otherWrite: (op, table) => `${op} on ${table}`,
+    noChange: (op, table, n) => `${op} on ${table} changed no rows${n > 1 ? ` (${n} times)` : ''}`,
+    structure: (ok, failed) => `${ok + failed} database structure commands (${ok} without error${failed ? `, ${failed} failed` : ''}); the recording does not show whether they changed the database`,
+    email: (to, subject, failed) => `${failed ? 'Failed email attempt' : 'Email sent'}${to.length ? ` to ${to.join(', ')}` : ''}${subject ? ` “${subject}”` : ''}`,
+    message: (provider, failed) => `${failed ? 'Failed message attempt' : 'Message sent'} via ${provider}`,
+    payment: (provider, operation, mode) => `Payment on ${provider}: ${operation} (${mode} mode)`,
+    file: (op, where) => `File: ${op} on ${where}`,
+    cookieSet: names => `Cookies stored in the browser: ${names}`,
+    cookieCleared: names => `Cookies deleted in the browser: ${names}`,
+    ai: (provider, model, usage, cost) => `AI call to ${provider}${model ? ` (${model})` : ''}${usage ? ` · ${usage.input ?? '?'} + ${usage.output ?? '?'} tokens` : ''}${cost != null ? ` · ~US$ ${cost.toFixed(4)}` : ''}`,
+    external: (method, host, n) => `External ${method} call to ${host}${n > 1 ? ` (${n} times)` : ''}`,
+    none: 'No lasting effect observed.',
+    unseen: 'Not observed: browser local storage and effects on unrecognised services.',
+  },
+  action: {
+    click: label => `Click on ${label}`,
+    submit: label => `Submit of ${label}`,
+    change: label => `Change in ${label}`,
+    continuation: 'Continuation after navigation',
+    request: (method, path, status) => `${method} ${path}${status != null ? ` (status ${status})` : ''}`,
+    noServer: 'no server requests',
+    screen: 'changes the screen',
+    noScreen: 'no visible change on screen',
+    navigates: path => `goes to ${path}`,
+  },
+};
+
+export function texts(lang) { return lang === 'en' ? EN : PT; }
+export { duration, names, list };
+
+// The sentence of one boundary, from its recorded facts.
+export function boundarySentence(step, lang) {
+  const t = texts(lang);
+  const r = step.result ?? {};
+  const failed = step.error || r.error;
+  const tables = (step.tables ?? []).join(', ');
+  let text;
+  switch (step.kind) {
+    case 'base-de-dados': {
+      const op = step.operation;
+      if (op === 'SELECT' || op === 'WITH' || op === 'PRAGMA') text = t.read(tables, r.rows);
+      else if (op === 'INSERT') text = t.insert(tables, r.affectedRows);
+      else if (op === 'UPDATE') text = t.update(tables, r.affectedRows);
+      else if (op === 'DELETE') text = t.delete(tables, r.affectedRows);
+      else if (op === 'CREATE') text = t.create(tables, /\bif\s+not\s+exists\b/i.test(step.sql ?? ''));
+      else if (op === 'ALTER') text = t.alter(tables);
+      else if (op === 'DROP') text = t.drop(tables);
+      else text = t.otherDb(op, tables);
+      break;
+    }
+    case 'http': text = t.http(step.method ?? '', step.host ?? '', step.path ?? '', r.status); break;
+    case 'ia': text = t.ai(step.provider, r.model ?? step.model, r.usage); break;
+    case 'email': text = t.email(step.to ?? [], step.subject); break;
+    case 'mensagem': text = t.message(step.to ?? [], step.provider ?? step.library); break;
+    case 'pagamento': text = t.payment(step.provider, step.operation, step.mode); break;
+    case 'ficheiros': {
+      const where = step.bucket ? `${step.provider} ${step.bucket}` : step.path ?? step.provider;
+      text = step.operation === 'leitura' || step.operation === 'verificação' ? t.fileRead(where, r.bytes) : t.fileWrite(step.operation ?? '?', where, step.bytes);
+      break;
+    }
+    case 'autenticação': text = t.auth(step.provider ?? step.library, step.operation); break;
+    default: text = `${step.kind}${step.operation ? `: ${step.operation}` : ''}`;
+  }
+  return failed ? `${text} — ${t.failed}` : text;
+}

package/src/store.mjs

@@ -0,0 +1,376 @@
+// Local store: ingests the JSONL recordings into an SQLite database inside
+// CodeTAC's own folder and builds the dossier of each HTTP request.
+import { DatabaseSync } from 'node:sqlite';
+import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, statSync } from 'node:fs';
+import { join, relative, resolve, sep } from 'node:path';
+
+const WRITES = new Set(['INSERT', 'UPDATE', 'DELETE', 'UPSERT', 'REPLACE', 'MERGE']);
+const STRUCTURE = new Set(['CREATE', 'DROP', 'ALTER', 'TRUNCATE']);
+const KINDS = { a: 'ligação', button: 'botão', input: 'campo', select: 'lista', textarea: 'caixa de texto', label: 'etiqueta', summary: 'secção', form: 'formulário' };
+
+// "botão «Entrar»": the element as the person saw it.
+export function actionLabel(trigger) {
+  const element = trigger?.element;
+  if (!element) return 'continuação após navegação';
+  const button = element.role === 'button' || (element.tag === 'input' && /^(submit|button|reset)$/.test(element.type ?? ''));
+  const kind = button ? 'botão' : KINDS[element.tag] ?? element.role ?? element.tag ?? 'elemento';
+  const text = element.text || element.label || element.name || element.id;
+  const suffix = trigger.event === 'change' ? (element.type === 'file' ? ' (ficheiro escolhido)' : ' (alteração)') : '';
+  return `${kind}${text ? ` «${text}»` : ''}${suffix}`;
+}
+
+export function openStore(folder, { keep = 500, keepRuns = 20 } = {}) {
+  const directory = resolve(folder);
+  // A new installation has no data folder yet (~/.codetac).
+  mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const db = new DatabaseSync(join(directory, 'codetac.db'));
+  db.exec(`
+    pragma journal_mode = wal;
+    create table if not exists ingested (file text primary key, offset integer not null);
+    create table if not exists runs (run text primary key, root text, node text, level text);
+    create table if not exists requests (request_id text primary key, run text, process text, method text, path text,
+      query_keys text, at integer, status integer, duration_ns integer, aborted integer, ended integer not null default 0);
+    create table if not exists events (request_id text not null, process text, sequence integer, type text, id text, data text);
+    create index if not exists events_request on events(request_id);
+    create table if not exists limitations (run text, file text, reason text, line integer, detail text,
+      unique(run, file, reason, line));
+    create table if not exists actions (action_id text not null, segment integer not null, run text, at integer, data text,
+      primary key(action_id, segment));
+    create table if not exists origins (key text primary key, data text not null);
+    create table if not exists purposes (key text primary key, data text not null, at integer);
+  `);
+  // Recordings made before the browser link have no action columns.
+  const columns = new Set(db.prepare('pragma table_info(requests)').all().map(column => column.name));
+  if (!columns.has('action')) db.exec('alter table requests add column action text; alter table requests add column action_request integer;');
+  if (!columns.has('cookies')) db.exec('alter table requests add column cookies text;');
+  // Phase 5: the request that loaded a page (it received the bar).
+  if (!columns.has('document')) db.exec('alter table requests add column document integer;');
+  db.exec('create index if not exists requests_action on requests(action)');
+  // Phase 5: why a recording is in minimal mode.
+  if (!db.prepare('pragma table_info(runs)').all().some(column => column.name === 'reason')) db.exec('alter table runs add column reason text;');
+  // Offsets used to be kept by the path as given, so opening the store from
+  // another working directory read every recording again and duplicated its
+  // events. They are now kept relative to the store's folder.
+  if (db.prepare("select 1 from sqlite_master where type = 'table' and name = 'files'").get()) {
+    db.exec('begin');
+    const move = db.prepare('insert into ingested(file, offset) values (?, ?) on conflict(file) do update set offset = max(offset, excluded.offset)');
+    for (const row of db.prepare('select path, offset from files').all()) {
+      if (row.path.startsWith(directory + sep)) move.run(relative(directory, row.path), row.offset);
+    }
+    db.exec(`drop table files;
+      delete from events where rowid not in (select min(rowid) from events group by request_id, process, sequence, type);
+      commit;`);
+  }
+  db.exec('create unique index if not exists events_unique on events(request_id, process, sequence, type)');
+  const statements = {
+    offset: db.prepare('select offset from ingested where file = ?'),
+    setOffset: db.prepare('insert into ingested(file, offset) values (?, ?) on conflict(file) do update set offset = excluded.offset'),
+    run: db.prepare('insert into runs(run, root, node, level, reason) values (?, ?, ?, ?, ?) on conflict(run) do update set root = excluded.root, node = excluded.node, level = excluded.level, reason = excluded.reason'),
+    request: db.prepare('insert or ignore into requests(request_id, run, process, method, path, query_keys, at, action, action_request) values (?, ?, ?, ?, ?, ?, ?, ?, ?)'),
+    action: db.prepare('insert or replace into actions(action_id, segment, run, at, data) values (?, ?, ?, ?, ?)'),
+    requestEnd: db.prepare('update requests set status = ?, duration_ns = ?, aborted = ?, cookies = ?, ended = 1 where request_id = ?'),
+    event: db.prepare('insert or ignore into events(request_id, process, sequence, type, id, data) values (?, ?, ?, ?, ?, ?)'),
+    limitation: db.prepare('insert or ignore into limitations(run, file, reason, line, detail) values (?, ?, ?, ?, ?)'),
+    document: db.prepare('update requests set document = 1 where request_id = ?'),
+  };
+  // A page event and the request that follows it with the same path, by process.
+  const pages = new Map();
+  const documents = new Set();
+
+  // Reads only the bytes appended since the previous ingestion.
+  function ingestFile(run, path) {
+    const size = statSync(path).size;
+    const key = relative(directory, path);
+    const from = statements.offset.get(key)?.offset ?? 0;
+    if (size <= from) return;
+    const fd = openSync(path, 'r');
+    let text;
+    try {
+      const buffer = Buffer.alloc(Math.min(size - from, 64 * 1024 * 1024));
+      const read = readSync(fd, buffer, 0, buffer.length, from);
+      text = buffer.subarray(0, read).toString('utf8');
+    } finally { closeSync(fd); }
+    const complete = text.lastIndexOf('\n');
+    if (complete < 0) return;
+    for (const line of text.slice(0, complete).split('\n')) {
+      if (!line) continue;
+      let event;
+      try { event = JSON.parse(line); } catch { continue; }
+      switch (event.type) {
+        case 'capture-start': statements.run.run(run, event.root ?? null, event.node ?? null, event.level ?? null, event.reason ?? null); break;
+        case 'page': pages.set(event.process, event.path); break;
+        case 'request':
+          if (pages.get(event.process) === event.path) { pages.delete(event.process); documents.add(event.requestId); }
+          statements.request.run(event.requestId, run, event.process, event.method, event.path,
+          JSON.stringify(event.queryKeys ?? []), event.at ?? null, event.action ?? null, event.actionRequest ?? null);
+          if (documents.has(event.requestId)) statements.document.run(event.requestId);
+          break;
+        case 'browser-action': statements.action.run(event.actionId, event.segment ?? 1, run, event.startedAt ?? null, line); break;
+        case 'request-end': statements.requestEnd.run(event.status ?? null, event.durationNs ?? null, event.aborted ? 1 : 0,
+          event.cookies ? JSON.stringify(event.cookies) : null, event.requestId); break;
+        case 'limitation': statements.limitation.run(run, event.file ?? '', event.reason ?? '', event.line ?? null, event.detail ?? null); break;
+        case 'enter': case 'exit': case 'boundary': case 'boundary-end': case 'detail':
+          if (event.requestId) statements.event.run(event.requestId, event.process, event.sequence, event.type, event.id, line);
+          break;
+      }
+    }
+    statements.setOffset.run(key, from + Buffer.byteLength(text.slice(0, complete + 1)));
+  }
+
+  function ingest() {
+    if (!existsSync(directory)) return;
+    db.exec('begin');
+    try {
+      for (const run of readdirSync(directory)) {
+        const folder = join(directory, run);
+        if (run === 'projetos' || /^(test|bundle)-/.test(run) || !statSync(folder).isDirectory()) continue;
+        for (const name of readdirSync(folder)) if (name.endsWith('.jsonl')) ingestFile(run, join(folder, name));
+      }
+      // History: the last `keep` requests of each recording, and the last `keepRuns` recordings.
+      const remove = db.prepare('delete from events where request_id = ?');
+      const removeRequest = db.prepare('delete from requests where request_id = ?');
+      const runs = db.prepare('select run, max(at) as last, count(*) as n from requests group by run order by last desc').all();
+      runs.forEach((entry, index) => {
+        const excess = index >= keepRuns ? entry.n : entry.n - keep;
+        if (excess <= 0) return;
+        // Within a recording, files served without anything of the project in
+        // them (Vite modules, images…) go first: a single page may load more
+        // than a thousand, and the page load itself must stay.
+        const order = index >= keepRuns ? 'at asc' : `(action is null and document is null
+          and not exists (select 1 from events e where e.request_id = requests.request_id)) desc, at asc`;
+        for (const { request_id: id } of db.prepare(`select request_id from requests where run = ? order by ${order} limit ?`).all(entry.run, excess)) {
+          remove.run(id);
+          removeRequest.run(id);
+        }
+      });
+      // Browser actions follow the same rule, by recording.
+      for (const entry of db.prepare('select run, count(distinct action_id) as n from actions group by run').all()) {
+        const excess = entry.n - keep;
+        if (excess <= 0) continue;
+        db.prepare(`delete from actions where action_id in (select action_id from actions where run = ?
+          group by action_id order by min(at) asc limit ?)`).run(entry.run, excess);
+      }
+      db.exec('commit');
+    } catch (error) {
+      db.exec('rollback');
+      throw error;
+    }
+  }
+
+  function listRuns() {
+    return db.prepare(`select run, max(last) as last, sum(requests) as requests, sum(actions) as actions from (
+        select run, max(at) as last, count(*) as requests, 0 as actions from requests group by run
+        union all select run, max(at) as last, 0, count(distinct action_id) from actions group by run)
+      group by run order by last desc`).all();
+  }
+
+  function listActions({ limit = 200, run } = {}) {
+    const rows = db.prepare(`select action_id, run, min(at) as at, count(*) as segments from actions
+      ${run ? 'where run = ?' : ''} group by action_id order by at desc limit ?`).all(...(run ? [run, limit] : [limit]));
+    const first = db.prepare('select data from actions where action_id = ? order by segment limit 1');
+    const counts = db.prepare(`select count(*) as requests, sum(ended) as ended from requests where action = ?`);
+    return rows.map(row => {
+      const data = JSON.parse(first.get(row.action_id).data);
+      const server = counts.get(row.action_id);
+      return { actionId: row.action_id, run: row.run, at: row.at, segments: row.segments, label: actionLabel(data.trigger),
+        page: data.page?.path, browserRequests: data.requests?.length ?? 0, serverRequests: server.requests, pending: server.requests > (server.ended ?? 0) };
+    });
+  }
+
+  // The same action seen by the browser (segments: one per page it crossed)
+  // and by the server (requests carrying its id), in one sequence.
+  function actionDossier(actionId) {
+    const segments = db.prepare('select run, data from actions where action_id = ? order by segment').all(actionId)
+      .map(row => ({ run: row.run, ...JSON.parse(row.data) }));
+    const serverRows = db.prepare('select * from requests where action = ? order by at, request_id').all(actionId);
+    if (!segments.length && !serverRows.length) return null;
+    const server = serverRows.map(row => ({ number: row.action_request, dossier: dossier(row.request_id) }));
+    const used = new Set();
+    const timeline = [];
+    const take = number => server.filter(item => item.number === number && !used.has(item.dossier.request.requestId))
+      .map(item => { used.add(item.dossier.request.requestId); return item.dossier; });
+    segments.forEach((segment, index) => {
+      if (index === 0 && segment.trigger) timeline.push({ type: 'trigger', segment: segment.segment, page: segment.page, trigger: segment.trigger });
+      if (index > 0 || !segment.trigger) {
+        // A new document: the request that loaded it carries the action in a cookie.
+        timeline.push({ type: 'document', segment: segment.segment, page: segment.page, server: take(null) });
+      }
+      const events = [
+        ...(segment.requests ?? []).map(request => ({ at: request.startMs ?? 0, item: { type: 'request', segment: segment.segment, browser: request, server: take(request.n) } })),
+        ...(segment.navigations ?? []).filter(item => item.kind !== 'documento')
+          .map(navigation => ({ at: navigation.atMs ?? 0, item: { type: 'navigation', segment: segment.segment, ...navigation } })),
+      ].sort((a, b) => a.at - b.at);
+      for (const { item } of events) timeline.push(item);
+      timeline.push({ type: 'screen', segment: segment.segment, page: segment.page, screen: segment.screen ?? {}, durationMs: segment.durationMs,
+        closedBy: segment.closedBy });
+    });
+    // Requests the server saw for this action but the browser did not report
+    // (the page closed before sending, or a request made on its behalf).
+    const rest = server.filter(item => !used.has(item.dossier.request.requestId)).map(item => item.dossier);
+    if (rest.length) timeline.push({ type: 'unmatched', server: rest });
+
+    const all = timeline.flatMap(item => item.server ?? []);
+    const combined = [];
+    for (const mark of all.flatMap(item => item.marks)) {
+      const found = combined.find(entry => entry.key === mark.key);
+      if (found) found.count += mark.count; else combined.push({ ...mark });
+    }
+    for (const request of segments.flatMap(segment => segment.requests ?? []).filter(request => !request.sameOrigin && request.host)) {
+      const key = `browser:${request.host}`;
+      const found = combined.find(entry => entry.key === key);
+      if (found) found.count++; else combined.push({ key, count: 1, label: `chamada do browser a ${request.host}` });
+    }
+    const runs = [...new Set([...segments.map(segment => segment.run), ...serverRows.map(row => row.run)])];
+    const limitations = runs.flatMap(run => db.prepare('select reason, count(*) as count from limitations where run = ? group by reason').all(run));
+    const first = segments[0];
+    return {
+      actionId, run: first?.run ?? serverRows[0]?.run, label: first ? actionLabel(first.trigger) : 'ação sem registo do browser', origin: first?.origin ?? null,
+      startedAt: first?.startedAt ?? serverRows[0]?.at ?? null,
+      durationMs: segments.reduce((total, segment) => total + (segment.durationMs ?? 0), 0) || null,
+      browserSeen: segments.length > 0, pending: all.some(item => !item.request.ended),
+      scripts: [...new Set(segments.flatMap(segment => segment.scripts ?? []))],
+      root: runs.map(run => root(run)).find(Boolean) ?? null, ...runLevel(runs),
+      timeline, marks: combined, limitations,
+    };
+  }
+
+  function listRequests({ limit = 200, run, withoutAction = false } = {}) {
+    const filter = withoutAction ? ' and action is null' : '';
+    const rows = run
+      ? db.prepare(`select * from requests where run = ?${filter} order by at desc limit ?`).all(run, limit)
+      : db.prepare(`select * from requests where 1${filter} order by at desc limit ?`).all(limit);
+    const count = db.prepare("select sum(type = 'enter') as functions, sum(type = 'boundary') as boundaries from events where request_id = ?");
+    return rows.map(row => ({ ...shapeRequest(row), ...count.get(row.request_id) }));
+  }
+
+  function shapeRequest(row) {
+    return { requestId: row.request_id, run: row.run, action: row.action ?? null, method: row.method, path: row.path,
+      queryKeys: JSON.parse(row.query_keys ?? '[]'), at: row.at, status: row.status,
+      durationMs: row.duration_ns == null ? null : row.duration_ns / 1e6, aborted: Boolean(row.aborted), ended: Boolean(row.ended),
+      cookies: row.cookies ? JSON.parse(row.cookies) : [] };
+  }
+
+  function dossier(requestId) {
+    const row = db.prepare('select * from requests where request_id = ?').get(requestId);
+    if (!row) return null;
+    const events = db.prepare('select data from events where request_id = ? order by process, sequence').all(requestId).map(item => JSON.parse(item.data));
+    const endings = new Map(events.filter(event => event.type === 'exit' || event.type === 'boundary-end').map(event => [event.id, event]));
+    // Values and executed lines, for functions whose detail was asked for.
+    const recordedValues = new Map(events.filter(event => event.type === 'detail').map(event => [event.id, event]));
+    const starts = events.filter(event => event.type === 'enter' || event.type === 'boundary');
+    const ids = new Set(starts.map(event => event.id));
+    const depth = new Map();
+    const steps = starts.map(event => {
+      const level = event.parentId && ids.has(event.parentId) ? (depth.get(event.parentId) ?? 0) + 1 : 0;
+      depth.set(event.id, level);
+      const end = endings.get(event.id);
+      const common = { id: event.id, parentId: event.parentId, depth: level, sequence: event.sequence,
+        durationMs: end?.durationNs == null ? null : end.durationNs / 1e6, error: Boolean(end?.error), finished: Boolean(end) };
+      if (event.type === 'enter') {
+        const detail = recordedValues.get(event.id);
+        return { ...common, type: 'function', function: event.function, file: event.file, line: event.line,
+          endLine: event.endLine ?? null, mapped: event.mapped, async: event.async,
+          ...(detail ? { detail: { args: detail.args, lines: detail.lines, ...('returned' in detail ? { returned: detail.returned } : { threw: detail.threw }) } } : {}) };
+      }
+      const { type, id, parentId, requestId: _r, process, sequence, timeNs, version, ...details } = event;
+      const { type: _t, id: _i, requestId: _q, durationNs: _d, error: _e, process: _p, sequence: _s, timeNs: _n, version: _v, ...result } = end ?? {};
+      const step = { ...common, type: 'boundary', ...details, result };
+      if (step.kind === 'ia') step.costUsd = estimateCost(result.model ?? step.model, result.usage);
+      return step;
+    });
+    const limitations = db.prepare('select reason, count(*) as count from limitations where run = ? group by reason order by count desc').all(row.run);
+    const runInfo = db.prepare('select root, level, reason from runs where run = ?').get(row.run) ?? {};
+    return { request: shapeRequest(row), level: runInfo.level ?? 'normal', reason: runInfo.reason ?? null, root: runInfo.root ?? null,
+      steps, marks: marks(steps), limitations };
+  }
+
+  // Cost is derived, never recorded: prices come from a local table
+  // (.codetac/precos.json: { "modelo": { "entrada": USD/1M, "saida": USD/1M } }).
+  function estimateCost(model, usage) {
+    const path = join(directory, 'precos.json');
+    if (!model || !usage || !existsSync(path)) return null;
+    try {
+      const price = JSON.parse(readFileSync(path, 'utf8'))[model];
+      if (!price) return null;
+      return ((usage.input ?? 0) * (price.entrada ?? 0) + (usage.output ?? 0) * (price.saida ?? 0)) / 1e6;
+    } catch { return null; }
+  }
+
+  // Lasting effects and costs, summarised for the end of the dossier.
+  function marks(steps) {
+    const result = [];
+    const add = (label, key) => {
+      const found = result.find(item => item.key === key);
+      if (found) found.count++;
+      else result.push({ key, label, count: 1 });
+    };
+    const structure = { commands: 0, tables: new Set() };
+    for (const step of steps) {
+      if (step.type !== 'boundary') continue;
+      if (step.kind === 'base-de-dados' && STRUCTURE.has(step.operation)) {
+        structure.commands++;
+        for (const table of step.tables ?? []) structure.tables.add(table);
+      } else if (step.kind === 'base-de-dados' && WRITES.has(step.operation)) add(`escrita em ${step.tables?.join(', ') || 'base de dados'} (${step.operation})`, `db:${step.operation}:${step.tables}`);
+      else if (step.kind === 'ia') {
+        const model = step.result?.model ?? step.model;
+        const usage = step.result?.usage;
+        add(`chamada de IA a ${step.provider}${model ? ` (${model})` : ''}${usage ? ` · ${usage.input ?? '?'} + ${usage.output ?? '?'} tokens` : ''}${step.costUsd != null ? ` · ~US$ ${step.costUsd.toFixed(4)}` : ''}`, `ia:${step.id}`);
+      }
+      else if (step.kind === 'email' || step.kind === 'mensagem') add(`${step.kind === 'email' ? 'email' : 'mensagem'} enviado por ${step.provider ?? step.library}`, `mail:${step.provider}`);
+      else if (step.kind === 'pagamento') add(`pagamento ${step.provider} (${step.mode})`, `pay:${step.operation}`);
+      else if (step.kind === 'ficheiros' && step.operation !== 'leitura' && step.operation !== 'verificação') add(`ficheiro: ${step.operation} em ${step.bucket ?? step.provider}`, `file:${step.operation}:${step.bucket}`);
+      else if (step.kind === 'http' && !step.local) add(`chamada externa a ${step.host}`, `http:${step.host}`);
+    }
+    if (structure.commands) result.push({ key: 'db:structure', count: 1,
+      label: `estrutura da base de dados: ${structure.commands} comandos (CREATE/ALTER/DROP) em ${structure.tables.size} tabelas` });
+    return result;
+  }
+
+  // A file can only be shown if a function from it was recorded in that run.
+  const recorded = new Map();
+  function recordedFile(run, file) {
+    const key = `${run}\n${file}`;
+    // Only a positive answer is kept: a file may be recorded later.
+    if (recorded.has(key)) return true;
+    const found = recordedFileQuery(run, file);
+    if (found) recorded.set(key, true);
+    return found;
+  }
+  function recordedFileQuery(run, file) {
+    const pattern = `%"file":${JSON.stringify(file)}%`.replace(/[\\_]/g, match => `\\${match}`);
+    return Boolean(db.prepare(`select 1 from events e join requests r on r.request_id = e.request_id
+      where r.run = ? and e.type = 'enter' and e.data like ? escape '\\' limit 1`).get(run, pattern));
+  }
+
+  // The lowest level among the recordings of an action (minimal wins), with its reason.
+  function runLevel(runs) {
+    const rows = runs.map(run => db.prepare('select level, reason from runs where run = ?').get(run)).filter(Boolean);
+    const low = rows.find(row => row.level === 'minimo');
+    return { level: low?.level ?? rows[0]?.level ?? 'normal', reason: low?.reason ?? null };
+  }
+
+  function root(run) {
+    return db.prepare('select root from runs where run = ?').get(run)?.root ?? null;
+  }
+
+  // Browser positions already resolved to project files, so that a dossier
+  // keeps its locations after the application (and its source maps) stops.
+  const originGet = db.prepare('select data from origins where key = ?');
+  const originSet = db.prepare('insert or replace into origins(key, data) values (?, ?)');
+  function cachedOrigin(key) {
+    const row = originGet.get(key);
+    return row ? JSON.parse(row.data) : null;
+  }
+  function cacheOrigin(key, value) { originSet.run(key, JSON.stringify(value)); }
+
+  // Answers of the AI model, by prompt: the same function with the same facts
+  // is not sent again.
+  const purposeGet = db.prepare('select data from purposes where key = ?');
+  const purposeSet = db.prepare('insert or replace into purposes(key, data, at) values (?, ?, ?)');
+  const purposeCache = {
+    get: key => { const row = purposeGet.get(key); return row ? JSON.parse(row.data) : null; },
+    set: (key, value) => purposeSet.run(key, JSON.stringify(value), Date.now()),
+  };
+
+  return { ingest, listRuns, cachedOrigin, cacheOrigin, purposeCache, listRequests, listActions, actionDossier, dossier, root, recordedFile, close: () => db.close() };
+}