Skip to content

Fase 1: fundação + Core Runner + SDK psrunner (specs 001, 002) - #1

Merged
net0well merged 7 commits into
mainfrom
fase-1/fundacao-core-sdk
Oct 19, 2026
Merged

net0well merged 7 commits into
mainfrom
fase-1/fundacao-core-sdk

Conversation

@net0well

@net0well net0well commented Oct 19, 2026 •

Copy link
Copy Markdown
Collaborator

Resumo

Primeira fase do PythonScriptRunner: estrutura da solução, Core Runner (execução síncrona de Stages) e o SDK Python psrunner, com CI em Windows e Linux.

Spec Entregue
001 Core Runner PythonScriptRunner.Abstractions + PythonScriptRunner.Core: catálogos (C# fluente e pasta + stage.json), validação dos 12 tipos, ambientes uv (lock com hashes, venv por hash, trava entre processos), executor de processo (ambiente limpo, timeout, cancelamento, Job Object no Windows, cauda de log com segredos mascarados), RunStageAsync com retry, telemetria
002 SDK psrunner @stage, Context, File, StageError, entrypoint psrunner.host, psrunner.testing.run_stage, CLI validate/run
009 (parte) .slnx, Directory.Build.props, CPM, .editorconfig, CI no GitHub Actions

RunPipelineAsync (trilhas) entra na Fase 2, como planejado.

Critérios de aceite

Spec 001 (testes Spec001_ACnn_*, Python real via uv)

  • AC-1 Stage em pasta (eco) devolve a saída
  • AC-2 Entrada obrigatória ausente → InputValidationException, nenhum processo iniciado
  • AC-3 Os 12 tipos sobrevivem à ida e volta (decimal com 28 casas, datetime com offset, table, list)
  • AC-4 / AC-5 Saída extra ou obrigatória ausente → OutputContractViolation
  • AC-6 StageError preserva código e traceback
  • AC-7 Timeout de 2 s encerra o processo e o filho (tentativa < 3,5 s)
  • AC-8 Cancelamento encerra a execução
  • AC-9 Limite de memória (256 MB) → MemoryLimitExceeded (Job Object no Windows, setrlimit no Linux)
  • AC-10 Segredo chega ao script, mascarado no log e fora do input.json
  • AC-11 Processo recebe ambiente limpo
  • AC-12 Segredo ausente → SecretNotFound sem iniciar Python
  • AC-13 Mesmo venv para dependências iguais; overhead p95 ≤ 300 ms em 50 execuções
  • AC-14 Criação concorrente do mesmo ambiente acontece uma vez
  • AC-15 Dependência inexistente → EnvironmentSetupFailed
  • AC-16 Arquivos de saída voltam como PsrFile e são apagados no DisposeAsync
  • AC-17 Arquivo acima do limite → ArtifactLimitExceeded
  • AC-18 Caminho de saída fora de out/ → OutputContractViolation
  • AC-19 stdout de 3 MB → cauda de 1 MB, truncated = true
  • AC-20 Stages com Python 3.11 e 3.12 usam suas versões
  • AC-21 / AC-22 Retry com backoff até o sucesso; sem retry = 1 tentativa
  • AC-23 Só o Core, sem banco nem fila
  • AC-24 psr.stage.execute (Activity) e psr.step.duration (métrica)
  • AC-25 Stage fluente e em pasta se comportam igual
  • AC-26 stage.json inválido → erro com arquivo e caminho JSON
  • AC-27 Chave inexistente → StageNotFoundException
  • AC-28 Tudo verde no Windows e no Linux (CI: 8/8 jobs)

Spec 002 (pytest)

  • AC-1 a AC-14 (inclusive AC-10, limite de memória, no Linux e no Windows)

Verificação local (Windows)

Fase Resultado
Build PASS: 0 erros, 0 avisos (warnings como erro)
Diagnósticos Roslyn PASS: 0
Antipadrões PASS: 0
Testes .NET PASS: 62/62
Testes Python PASS: 54 + 1 só-Linux; mypy strict e ruff limpos; também testado em Python 3.10
Segurança PASS: nenhum pacote vulnerável; sem segredos no código
Formatação PASS: dotnet format --verify-no-changes

Ajustes feitos durante o CI

  • astral-sh/setup-uv fixado na tag exata v10.3.0, porque a action não publica a tag flutuante v10.
  • AC-11: LC_CTYPE passou a ser aceito no ambiente do processo. No Linux é o próprio Python que define essa variável ao iniciar com locale C (PEP 538); ela não vem do host.
  • Limite de memória no Windows: o python.exe de um venv é um lançador que cria o interpretador real como processo filho. O Job Object atribuído pelo .NET logo após o Process.Start às vezes não pegava esse filho (AC-9 instável). Agora o psrunner aplica o limite no próprio interpretador: Job Object via ctypes no Windows, setrlimit no Linux. O Job Object do .NET continua encerrando a árvore de processos no timeout e no cancelamento.

Detalhes de implementação a observar

  • Protocolo: o caminho do script vai em PSR_SCRIPT; no Linux o ambiente limpo também tem HOME/TMPDIR apontando para tmp/.
  • O psrunner é instalado em cada venv com uv pip install --no-deps, depois do uv pip sync, na versão exata de PsrunnerRequirement (padrão psrunner==0.1.0, ou um wheel local). Essa versão entra no hash do ambiente. Enquanto o pacote não estiver no PyPI (Fase 7), é preciso apontar PsrunnerRequirement para um wheel local, como os testes fazem.
  • StageDefinition.PythonVersion é anulável (null usa o padrão 3.12). Em PsrFile, Length/Sha256 são anuláveis só para streams ainda não lidos.
  • dotnet test usa o Microsoft.Testing.Platform (exigência do .NET 10 com xunit.v3 4.x), configurado no global.json.

Como testar

dotnet test --project tests/PythonScriptRunner.Core.Tests   # requer uv no PATH
cd python/psrunner && uv sync && uv run pytest

🤖 Generated with Claude Code

net0well and others added 7 commits October 19, 2026 14:26
- global.json (SDK 10.0.400, Microsoft.Testing.Platform), .slnx
- Directory.Build.props (net10.0, nullable, warnings como erro, metadados de pacote)
- Directory.Packages.props (versões centralizadas), .editorconfig, .gitattributes
- README com o uso da Fase 1

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- @stage, Context (log, segredos, new_file), File e StageError
- entrypoint psrunner.host (protocolo 1): conversão e validação dos 12 tipos,
  table como DataFrame quando há pandas, limite de memória no Linux, traceback do usuário
- psrunner.testing.run_stage (pytest sem .NET) e CLI validate/run
- schemas/stage.v1.json
- pytest (54 testes), mypy strict e ruff

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- Abstractions: FieldType/FieldDefinition, StageDefinition, RunResult, PsrFile,
  ICatalog, ISecretProvider, IRunRecorder e exceções
- Core: catálogo em código e em pasta (stage.json validado pelo JSON Schema),
  binding/validação das entradas, ambientes uv com lock e cache por hash,
  executor de processo (ambiente limpo, timeout, cancelamento, Job Object no
  Windows, cauda de log com segredos mascarados, validação das saídas),
  RunStageAsync com retry, telemetria (ActivitySource/Meter) e AddPythonScriptRunner
- 62 testes (unitários + integração com Python real), um por critério de aceite

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
- .NET em Ubuntu e Windows (build + testes com uv), verificação de formatação
- psrunner: Python 3.10–3.13 no Ubuntu e 3.12 no Windows (ruff, mypy, pytest)

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
A action não publica a tag flutuante v10.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
No Linux o próprio Python define LC_CTYPE ao iniciar com locale C (PEP 538);
a variável não vem do host.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…no Windows

No Windows o python.exe do venv é um lançador que cria o interpretador real
como processo filho; o Job Object atribuído pelo .NET logo após o Process.Start
podia não alcançar esse filho (teste AC-9 instável no CI). O psrunner agora
cria um Job Object para o próprio processo via ctypes antes de importar o
script, como já fazia com setrlimit no Linux. O Job Object do .NET continua
encerrando a árvore de processos no timeout e no cancelamento.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@net0well
net0well merged commit 12589ab into main Oct 19, 2026
8 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant