Files
canina/infra/hermes-worker/README.md
T

29 lines
4.9 KiB
Markdown

# Bounded PREPARE worker transport (not an LLM pilot)
This is an opt-in Nest dynamic module and one-shot deterministic Node executor. Nothing imports it into AppModule. No live service, credential, dispatch schedule or deployment is created.
## Required parent wiring
- Import `WorkerTransportModule.register(config)` from `backend/src/orchestration-worker/worker-transport.module.ts` in the parent application only after review. Default disabled; provide empty grants until secret provisioning. The module owns its own PrepareWorkflowService/config; do not broaden existing orchestration providers.
- Provision >=32 random-byte service credential through a mounted secret `/run/secrets/prepare_worker_credential` to the pilot, and provision only its SHA256 in server grants. Never accept identity/role from request bodies, JWT browser users, headers other than this credential, or a snapshot inventory.
- `grants` is an explicit digest -> `{id,role}` mapping with independent `workerIds`/`stageCiIds`. Worker and CI identities/digests cannot overlap. Use a separate CI-only secret for `STAGE_CI`; do not give it to this executor.
- Fixed config: absolute private writable `artifactDirectory`, authenticated HTTPS `artifactBaseUrl` pointing to `/internal/prepare-worker/artifacts`, separate persistent artifact volume. The fixture host `isolated.invalid` is NOT a real uploaded artifact URI. TLS routing/URI reachability must be verified by parent Stage CI.
- Restrict routes to service network, TLS, ingress body limit (8KiB recommended), rate limit, no browser CORS credentials, no public user JWT access. The module validates strict DTO fields, but production ingress/body limits/rate controls remain parent's wiring.
- Run `node infra/hermes-worker/pilot.mjs` with explicit `PREPARE_TASK_ID` UUID and `PREPARE_WORKER_BASE_URL` HTTPS origin. It consumes exactly one task/lease, has 5s per HTTP timeout, does not retry, and exits on SIGINT/SIGTERM. No polling or global dispatch. Disable all egress except backend; do not mount shell/Docker/browser credentials or repo write access. Loopback HTTP is available only via the exported test API option, not CLI.
## Contract and bounds
POST `/internal/prepare-worker/claim`: `{taskId}` -> `{lease:null|{...}}`; heartbeat: `{taskId,runId,leaseToken}`; complete: same binding plus `report` (max 2048 chars). Server accepts only byte-exact deterministic tracer JSON derived from the immutable run; it computes SHA256, writes real content, and chooses artifact URI/cost (0 cents), not client-supplied costs/URIs/pass flags. It does **not** inspect repository contents or validate application acceptance criteria. QA here means this harmless tracer succeeded, not application QA.
Core service still owns transactional Gate1, scope, kill checks, task locks, lease fencing, reservations and VERIFYING event. Transport requires exactly 20-cent task budgets and explicit task IDs. One expired unknown-cost reservation exhausts this pilot budget; do not release it to permit retries. Interrupt means cancellation/non-RUNNING state or STOP_AGENTS; heartbeat before compute, before complete, and atomic completion recheck. File writes may leave unregistered orphan content if the final transaction is denied; retrieval requires a registered QA artifact and verifies its bytes against the requested digest.
POST `/internal/prepare-worker/stage-evidence` has a separate strict CI DTO `{taskId,runId,commitSha,sha256,evidenceSha256,uri}` and calls independently authenticated core Stage evidence ingestion. This tracer never submits it. Valid CI evidence retrieval/provenance remains CI's responsibility. No Gate2 approval/release transport exists.
Shared department budgets are not implemented by core and are not claimed here. Do not expand beyond a single bounded pilot until aggregate budgeting and live provisioning are reviewed.
## Real isolated verification
Run `bash infra/hermes-worker/test-isolated.sh green`. It creates no-network disposable PostgreSQL16, applies only the three repository v4 migrations, copies readonly source and Node22 dependency donor into private writable storage, regenerates Prisma, runs actual Nest TCP HTTP and a child Node executor, then full backend compilation. Docker DB/anonymous volume removed on exit. No live tables/containers/volumes, RELEASE_AUTHORIZE, push or deploy touched.
Evidence: `/opt/services/canina/validation/v4-worker-transport/`: `red.log` (missing module initial RED), `integrity-red.log` (real 200 vs expected409 corruption regression), `green.log`, `build.log`, `generate.log`, `tracer-evidence.json` (actual artifact content/hash). Final tests cover credential/body identity denial, disabled/overlap config, Gate1 no-dispatch, competing claims, expired/token fencing, retained20-cent budget, interrupt/kill rechecks, CI separation, real executor to VERIFYING, authenticated artifact GET and tamper rejection. Fixture commit is 40 `a` characters; this is not a repository QA claim or live Stage deployment.