PLANO TECNICO: BK-124 Runtime base de Squads

1. Objetivo do plano

Traduzir a spec do BK-124 em um plano de implementacao realista, encaixado no codigo atual do kernel, sem reescrever o Studio nem criar um framework paralelo.

2. Estado atual confirmado no codigo

• O kernel/index.js ja concentra:
• entrada WS;
• sessionKey;
• historico de sessao;
• executionRegistry;
• aprovacoes;
• workflowPhase.
• O studio_chat_store.js ja resolve persistencia de chat e decisoes ignoradas, em SQLite e Postgres.
• O studio_execution_registry.js ja modela execucao ativa por requestId e sessionKey.
• O kernel/router.js ja cuida de selecao de engine/modelo/fallback.

Conclusao: o BK-124 nao precisa reinventar sessao, socket ou roteamento. Ele precisa adicionar um novo conceito persistido e orquestrado:

• squad definition
• squad run
• squad step
• artifact

3. Decisoes de arquitetura

3.1 Nao sobrecarregar studio_chat_store

O store atual e de conversa. Ele nao deve virar um deposito generico de workflow. O runtime de squads precisa de storage proprio.

Decisao:

• criar kernel/squad_store.js;
• manter o mesmo padrao dual SQLite/Postgres usado em studio_chat_store.js;
• integrar run de squad com sessionKey, mas sem acoplar as tabelas de chat ao modelo de run.

3.2 Runtime separado do index.js

kernel/index.js ja esta grande e operacionalmente critico. O runtime do squad deve viver em modulo proprio.

Decisao:

• criar kernel/squad_runtime.js;
• index.js apenas:
• recebe payload;
• valida contexto;
• chama runtime;
• emite eventos WS.

3.3 Definicao declarativa em kernel/config/squads/

Para que o Squad Social nao fique hardcoded.

Decisao:

• criar pasta kernel/config/squads/;
• primeiro arquivo: rnt-social-squad.json;
• cada definicao precisa descrever:
• squad_id;
• project;
• version;
• default_mode;
• steps;
• review_policy;
• artifacts_expected.

3.4 Primeiro release sem publish autonomo

O BK-124 cria o motor base, nao o publicador final.

Decisao:

• aceitar steps como research, copy, review;
• deixar publish fora do escopo de execucao automatica nesta fase;
• o runtime ja deve suportar esse tipo de etapa no schema, mas sem obrigar implementacao completa agora.

4. Modelo de dados proposto

4.1 Tabela studio_squad_runs

Campos minimos:

• run_id TEXT PRIMARY KEY
• session_key TEXT NOT NULL
• squad_id TEXT NOT NULL
• project_name TEXT NOT NULL
• mode TEXT NOT NULL
• status TEXT NOT NULL
• current_step_key TEXT NULL
• requested_engine TEXT NULL
• requested_by TEXT NULL
• input_payload_json TEXT/JSONB NULL
• summary_json TEXT/JSONB NULL
• created_at
• updated_at
• started_at
• finished_at

4.2 Tabela studio_squad_steps

Campos minimos:

• id INTEGER/BIGSERIAL PK
• run_id FK
• step_key
• step_type
• agent_id
• position
• status
• retry_count
• input_artifact_id NULL
• output_artifact_id NULL
• score_json TEXT/JSONB NULL
• feedback_text TEXT NULL
• started_at
• finished_at
• updated_at

4.3 Tabela studio_squad_artifacts

Campos minimos:

• artifact_id TEXT PRIMARY KEY
• run_id FK
• step_key
• artifact_type
• variant_key
• status
• parent_artifact_id NULL
• content_text TEXT NULL
• payload_json TEXT/JSONB NULL
• created_at
• updated_at

4.4 Status normalizados

Run

• queued
• running
• rework
• approved
• failed
• canceled

Step

• pending
• running
• done
• rework
• approved
• failed
• skipped

5. Contrato declarativo do squad

Exemplo de estrutura inicial para rnt-social-squad.json:

```json

{

"squad_id": "rnt-social-v1",

"project": "rionoteatro",

"version": 1,

"default_mode": "economico",

"modes": {

"economico": {

"max_review_loops": 1,

"budget_profile": "low"

},

"alta_performance": {

"max_review_loops": 2,

"budget_profile": "standard"

}

},

"steps": [

{

"key": "research",

"type": "research",

"agent_id": "planner",

"output_artifact_type": "research_brief"

},

{

"key": "copy",

"type": "copy",

"agent_id": "backend",

"input_from": "research",

"output_artifact_type": "copy_bundle"

},

{

"key": "review",

"type": "review",

"agent_id": "po",

"input_from": "copy",

"output_artifact_type": "review_report"

}

]

}

```

6. API interna do runtime

kernel/squad_runtime.js deve expor no minimo:

• loadSquadDefinition(squadId)
• createRun({ sessionKey, squadId, mode, inputPayload, requestedBy, requestedEngine })
• startRun(runId, options)
• advanceRun(runId, options)
• markStepRework(runId, stepKey, reviewPayload)
• approveRun(runId, approvalPayload)
• getRun(runId)
• listRuns(filters)

7. Encaixe no kernel/index.js

7.1 Fase 1 do BK-124

Adicionar novos payloads WS, ainda sem UI final:

• studio_squad_run_start
• studio_squad_run_get
• studio_squad_run_list

Resposta sugerida:

• studio_squad_run_ack
• studio_squad_run_event
• studio_squad_run_state

7.2 Reuso da infraestrutura atual

• sessionKey continua sendo o agrupador primario da experiencia.
• executionRegistry continua sendo usado por requestId, agora tambem para runs de squad.
• callLLMWithAutoFallback(...) continua sendo o executor de cada step.
• studio_chat_store segue guardando a conversa; squad_store guarda a execucao estruturada.

8. Ordem de implementacao recomendada

Etapa A - Storage e contrato

1. Criar kernel/config/squads/.
2. Criar kernel/config/squads/rnt-social-squad.json.
3. Criar kernel/squad_store.js com adapters SQLite/Postgres.
4. Criar schema das tres tabelas.
5. Criar testes do store.

Etapa B - Runtime puro

1. Criar kernel/squad_runtime.js.
2. Implementar carregamento de definicao.
3. Implementar createRun.
4. Implementar startRun com execucao linear de steps.
5. Persistir step e artifact a cada transicao.

Etapa C - Integracao no index.js

1. Adicionar handlers WS novos.
2. Integrar com executionRegistry.
3. Emitir eventos studio_squad_run_event.
4. Garantir cleanup em success/error/abort.

Etapa D - Testes do runtime

1. Teste unitario do parser da definicao.
2. Teste unitario de transicao de status.
3. Teste unitario de run linear research -> copy -> review.
4. Teste de rework.
5. Teste de abort por session_stop.

9. Estratégia de execução das etapas

Para o BK-124, cada step pode usar um executor simples baseado em type.

Exemplo:

• research -> prompt estruturado para pesquisa/sintese
• copy -> prompt estruturado para gerar artefato textual
• review -> prompt estruturado para validar e devolver score

O importante nesta fase nao e a sofisticação do prompt; e o contrato de runtime:

• cada step recebe input artifacts;
• cada step gera output artifact;
• cada resultado atualiza estado persistido.

10. Estratégia de artefatos

No BK-124, artefato textual basta.

Tipos iniciais:

• research_brief
• copy_bundle
• review_report

Formato:

• content_text para leitura humana
• payload_json para dados estruturados

Isso prepara o caminho para BK-128 gerar:

• variacoes A/B
• carrossel
• legenda
• roteiro

11. Testes obrigatorios

Store

• SQLite cria schema automaticamente.
• createRun persiste run e steps.
• listagem por sessionKey funciona.
• artifact lineage funciona.

Runtime

• definicao invalida falha com erro claro.
• run valida entra em queued e depois running.
• steps mudam de pending para running/done.
• step de review consegue marcar rework.
• abort limpa execucao ativa e persiste falha/cancelamento.

Integração

• studio_squad_run_start cria run real.
• eventos WS chegam em ordem coerente.
• session_stop interrompe run em andamento.

12. Rollback

Rollback do BK-124 deve ser simples:

• remover handlers WS novos;
• deixar kernel/index.js sem acionar squad_runtime;
• manter tabelas novas sem uso, se necessario;
• nao tocar no fluxo atual do Studio Terminal.

Ou seja: o runtime de squads deve nascer como trilho paralelo, nao como substituicao do terminal atual.

13. Riscos e mitigacoes

Risco 1: inflar index.js

Mitigacao:

• logica de runtime e store em modulos separados.

Risco 2: confundir chat com run

Mitigacao:

• stores separados;
• ids separados (requestId vs run_id).

Risco 3: schema excessivo para MVP

Mitigacao:

• artefato textual simples no BK-124;
• multimodalidade fica para BKs seguintes.

Risco 4: acoplamento prematuro ao Studio UI final

Mitigacao:

• contrato WS minimo agora;
• builder bonito fica no BK-126.

14. Definicao de pronto para iniciar codigo

O BK-124 fica pronto para implementacao quando estes pontos estiverem aceitos:

• storage separado de squad confirmado;
• contrato do arquivo de definicao confirmado;
• lista de payloads WS minima confirmada;
• status de run e step congelados;
• path list da spec travada.

Se esses cinco pontos estiverem aceitos, o codigo pode comecar sem ambiguidade estrutural.