Catálogo de operaciones
Actualizado al 24-oct-2026 (main
f41235c7).
La unidad de trabajo del substrato es la operación. El catálogo vive en packages/substrate-spec y al 24-oct-2026 registra 75 pares id@versión (71 ids distintos). Ninguna está marcada como obsoleta. Una operación no es una función suelta: es un contrato versionado con inputs, outputs, efectos y, si toca el mundo, un binding de herramienta.
Anatomía de una operación
Sección titulada «Anatomía de una operación»Cada operación declara:
- id y versión: por ejemplo
video.compose@2.0.0. Las versiones conviven; una operación nueva no rompe la anterior. Cuatro ids tienen dos versiones:research.competitor_metrics,research.competitor_transcripts,research.keyword_demandyvideo.compose. - contract: referencias a los schemas de inputs y outputs, y el efecto (
pure,tool,delegate,human_gate,branch). - knowledge_access: si la operación necesita la capa vectorial, debe declararlo con una justificación. Hoy lo declaran
claim.recall_decisions,claim.recall_voiceydocument.query. - tool_binding (opcional): cuando la operación toca un servicio externo, declara su capability, provider y scope. Hoy lo tienen
demo.tool_echo,demo.gateway_probe,slack.postygithub.gist_create.
Qué hay en el catálogo hoy
Sección titulada «Qué hay en el catálogo hoy»Ids por familia al 24-oct-2026 (entre paréntesis, los pares id@versión cuando difieren):
| Familia | Operaciones |
|---|---|
research (16 ids, 19 pares) |
youtube_search, youtube_comments, reddit_search, channel_stats, opportunity_keyword_expand, link_reddit_evidence, audience_intelligence, rank_opportunities, youtube_traction, keyword_expand, keyword_demand, youtube_serp, competitor_metrics, competitor_transcripts, channel_watch, synthesize |
document (5) |
ingest, extract, chunk, anonymize, query |
text (3) |
compose_narrative (solo 2.0.0), compose_brief, compose_lead_brief |
video (5 ids, 6 pares) |
create_job, script_draft, compose, assemble, style_analysis |
media (3) |
ingest, transcribe, chunk |
junta (3) |
load_report, panel, compose_verdict |
claim (2) |
recall_decisions, recall_voice |
artifact (2) |
list_recent, publish |
prospect (2) |
search, score_batch |
vo (2) |
generate, qa |
thumbnail (2) |
generate, score |
heygen (2) |
brief, generate |
scene (2) |
render_slide, generate |
yt (2) |
publish, metrics |
demo (2) |
tool_echo, gateway_probe |
| Una sola operación cada una | trace.query, audience.load, evaluator.run, human_gate.approve, human_task, url.fetch_transcript, voice.tts, pricing.observe, broll.generate, cfstream.deliver, pipeline.status, ideation.interview, library.briefing, script.compose_rex, metrics.digest, slack.post, github.gist_create, analysis.run |
Para el motor, cuatro operaciones no tienen handler registrado en la API: human_gate.approve y human_task (las resuelve el motor) y slack.post y github.gist_create (solo se pueden despachar si FORGE forjó una capacidad con ese id). Las otras 71 sí.
Los cuatro touchpoints
Sección titulada «Los cuatro touchpoints»Registrar una operación correctamente significa tocar cuatro lugares. El error recurrente es registrarla en tres de los cuatro:
- Catálogo (
packages/substrate-spec/src/operations/): la definición de la operación, registrada encatalog.ts. - Schema de inputs (
apps/api/src/inngest/operations/schemas.ts): el schema al que apuntainputs_schema_ref. - Composición (
apps/api/src/substrate/nova-compose.ts): la guía que Nova usa para componer (COMPOSABLE_OPS). - Seguridad (
apps/api/src/forge/safety.ts): condicional, solo si la operación debe ser forjable por FORGE.
Además, una operación que el motor ejecuta necesita su handler en apps/api/src/inngest/operations/index.ts; ese registro queda fuera del checklist de cuatro.
Seguridad y forjabilidad
Sección titulada «Seguridad y forjabilidad»El cuarto touchpoint no es un registro obligatorio incondicional: es una decisión de negocio. El estado de seguridad de una operación es uno de:
- eligible_pure: sin efectos externos que requieran forjado.
- allowlisted: tiene binding y su capability está habilitada en
FORGEABLE_CAPABILITIES(hoydemo.gateway_probe,slack.postygithub.gist_create). - closed_by_policy: tiene binding pero la capability no está habilitada, una decisión humana deliberada (hoy,
demo.tool_echo, cuya capability esdemo.echo). - not_applicable: tiene efecto de herramienta pero sin binding declarado.
Una operación cerrada por política no queda incompleta salvo que la tarea exija explícitamente que sea forjable. Antes de ejecutar, el despachador valida los inputs con Zod y, si la operación tiene tool_binding, pide autorización al Tool Broker. El Tool Broker está apagado en producción: sin TOOL_BROKER_GRANT_SECRET esa autorización lanza un error, de modo que hoy una operación con binding no corre en producción.
Plantillas
Sección titulada «Plantillas»Sobre las operaciones se construyen plantillas de trabajo de extremo a extremo, también en packages/substrate-spec. Al 24-oct-2026 hay 27 plantillas exportadas:
brief-synthesisen 13 versiones: v1, v2, v3 y de v5 a v14 (no existe v4). En producción el brief corre con v13 (25 nodos); v14 existe, pero su flag no está encendido.standup-digest-v1,lead-research-v1,video-render-v1,video-script(v1 y v2),scene-production(v1 y v2),video-assembly-v1,video-publish-v1,short-factory-v1,document-extract-v1,document-query-v1,pricing-watch-v1yjunta-yt-review-v1.
Cada plantilla encadena operaciones para producir un entregable concreto. Los actores de los pasos ya no vienen fijos: casi todos se atan al roster del workspace al lanzar. Además existen dos colas derivadas, de recuperación y de reparación del informe, que no son plantillas seleccionables. Nova reconoce diez workflows curados, entre ellos content-brief-full, standup-digest, lead-research, document-extract y document-query.
Evaluadores
Sección titulada «Evaluadores»El catálogo de evaluadores tiene 12 entradas: un llm_judge declarado (eval.digest.completeness) y 11 deterministas. Ninguno llama a un modelo: evaluator.run usa implementaciones deterministas, incluso para el llm_judge. Un evaluador bloqueante que rechaza falla cerrado y el motor no lo reintenta.
Consultar el catálogo sin leer todo
Sección titulada «Consultar el catálogo sin leer todo»Para trabajar sobre el catálogo sin cargar sus archivos completos, el proyecto expone un servidor MCP de desarrollo, catalog-mcp, con tres herramientas compactas: buscar operaciones, describir el contrato de una, y verificar que esté registrada en los cuatro touchpoints. Lee el catálogo vivo por import, así que sus resultados siguen al código. Ver Herramientas de dev.