Tabla D1: bib_wiki_pending_commits

Descripción

Tabla D1 transitoria introducida en migration 0036 (PR#63, s80). Almacena los cuerpos .md de páginas wiki pendientes de commit durante el agentic loop del Bibliotecario-Ingest. Su propósito es permitir que wiki_create_page y wiki_update_page operen en modo defer_commit, consolidando todos los archivos en un único commit al final del loop mediante wiki_flush_pending_commits.

Naturaleza transitoria: las filas se eliminan (DELETE) justo después de que wiki_flush_pending_commits realiza el commit con éxito. Las filas residuales (flush fallido) son re-flushables manualmente.

Schema

CREATE TABLE bib_wiki_pending_commits (
  id             INTEGER PRIMARY KEY AUTOINCREMENT,
  trigger_ref    TEXT NOT NULL,              -- ej. 'PR#63', 'commit@abc1234'
  slug           TEXT NOT NULL,              -- slug wiki de la página
  file_path      TEXT NOT NULL,              -- ruta relativa del .md en el repo
  body           TEXT NOT NULL,              -- contenido completo del .md (front-matter incluido)
  operation      TEXT NOT NULL              -- 'create' | 'update'
                   CHECK (operation IN ('create', 'update')),
  commit_message TEXT NOT NULL,             -- mensaje para el commit individual (referencia)
  created_at     TEXT DEFAULT (datetime('now')),
  UNIQUE(trigger_ref, slug)
);

CREATE INDEX idx_wiki_pending_trigger
  ON bib_wiki_pending_commits(trigger_ref);

Columnas clave

Constraint UNIQUE(trigger_ref, slug) y semántica ON CONFLICT

Si Sonnet llama a wiki_create_page y luego wiki_update_page sobre el mismo slug dentro de la misma sesión de ingest (mismo trigger_ref):

• El body se sobreescribe con el último valor (excluded.body).
• La operation preserva 'create' si la fila previa era create:

  operation = CASE
    WHEN bib_wiki_pending_commits.operation = 'create' THEN 'create'
    ELSE excluded.operation
  END

  Esto evita que un update posterior enmascare que la página era nueva en esta sesión.

Ciclo de vida de una fila

wiki_create_page(defer_commit=true, trigger_ref="PR#63")
  → INSERT INTO bib_wiki_pending_commits ...
  → fila vive en tabla

wiki_flush_pending_commits(trigger_ref="PR#63")
  → SELECT * WHERE trigger_ref = "PR#63"
  → GitHub Trees API commit (N archivos en 1 commit)
  → commit OK → DELETE WHERE trigger_ref = "PR#63"
  → fila eliminada

Si el flush falla, las filas no se eliminan. Re-flush manual:

wiki_flush_pending_commits(trigger_ref="PR#63")

Relación con otras tablas D1

• bib_wiki_pages: tabla principal del catálogo wiki. wiki_create_page/wiki_update_page con defer_commit=true siguen escribiendo en bib_wiki_pages de forma inmediata (la metadata D1 no se difiere, solo el commit al repo).
• bib_wiki_log: el flush escribe una entrada operation='ingest' con la lista de slugs y el commit_sha resultante.

Operaciones de mantenimiento

Ver páginas pendientes de flush para un trigger

SELECT trigger_ref, slug, operation, created_at
FROM bib_wiki_pending_commits
WHERE trigger_ref = 'PR#63'
ORDER BY id;

Limpiar manualmente tras flush confirmado

DELETE FROM bib_wiki_pending_commits WHERE trigger_ref = 'PR#63';

Ver filas huérfanas (más de 24h sin flush)

SELECT * FROM bib_wiki_pending_commits
WHERE created_at < datetime('now', '-1 day');

Véase también

• [[feature—biblioteca—bib-ingest-batch]]
• [[concept—general—existe-documentacion-sobre-wikicreatepage-wikiupda]]