HarnessAasClient jobs/events/approvals/artifacts core (ADR-0027a)

[ruvnet]

Milestone: M5 | Mission: Cognitum Agentic SDK Integration

Implement the public client surface, HTTP v1 resources, solve request/job types, job state machine, submission/idempotency, polling/wait, resumable SSE, cancellation, approvals, and the artifact contract.

Blocked on #16 (contract reconciliation must land first).

Governing ADR: 0027a (D1-D11).

---

Filed from the reviewed mission plan. Routes to Project #1 (Product Roadmap).

[ruvnet]

Opened PR #108 to start this milestone: draft, not the full D1-D11 job/events/approvals/artifacts surface this issue names.

Why the scope is narrower than the issue title

The reconciliation audit this issue was blocked on (#16/#67, landed in PR #107 — see the "2026-07-19 reconciliation audit" notes now in docs/adr/0019-agentic-platform-bounded-contexts.md and docs/adr/0027a-harnessaas-jobs-events-approvals-and-artifacts.md) reconfirmed against a fresh clone of cognitum-one/harnessaas@908e4a99 that POST /solve is genuinely synchronous today — one HTTP request in, one full SolveResponse out, with no job/status/cancel/resume/SSE contract anywhere in the running service. ADR-0027a's "Decision" section (the async SolveHandle, /v1/solves/* job resource, state machine, resumable SSE, approvals, cancellation, artifacts) is an explicit proposal for something that doesn't exist upstream yet.

Building SDK bindings against that D2-D11 proposal now would repeat exactly the mistake the reconciliation audit was meant to prevent: generating client code for routes that don't correspond to anything deployed. So PR #108 implements only the real, live surface — this is the start of M5, not the finish. The full job/events/approvals/artifacts client (this issue's actual title) has to wait until the upstream service actually ships that contract.

What's in PR #108 (all 3 languages: node, python, rust)

• HarnessaaSClient construction — zero I/O, mirrors MetaLlmClient/MetaProxyClient/MetaHarnessClient conventions exactly.
• health() → GET /health (verified src/server.ts:286-304 — unauthenticated; deliberately NOT /healthz, which Cloud Run's frontend reserves and 404s to external callers).
• solve(request) → POST /solve, core code-repair fields (repo, test_command, issue, optional w/vertical). Vertical-specific compound fields (finding/scanner_command, migration/build_command, test_generation/coverage_command) are out of scope this pass.
• lineage(requestId) → GET /lineage/:id.
• Auth: verified cog_-prefixed API key via X-API-Key (preferred) or Authorization: Bearer (src/auth.ts:1-24,256-264) — same shape as Meta LLM, so StaticApiKeyCredentialProvider works unchanged.

Retry safety: grepped the upstream source directly — there is no Idempotency-Key handling anywhere in cognitum-one/harnessaas and no in-app rate limiter, so solve() makes exactly one HTTP attempt for every outcome except a verified 401 (auth is checked server-side before any spend, so a single refresh-and-retry there is provably safe). 429/502/503/5xx/transport failures are never auto-retried — this is the same failure mode independent review caught in Meta Proxy's forwarding (ADR-0025a, PR #93, commit eb553f7), avoided here from the start. lineage() (a safe GET) does get bounded 429/502/503 retry.

Verification (real output)

• Node: npm run build/typecheck/lint all clean; SKIP_SEED_INTEGRATION=1 npx vitest run → 485 passed, 8 skipped (43 files), including the new 23-test harnessaas-client.test.ts.
• Python: fresh uv venv + pip install -e ".[dev]"; pytest tests/harnessaas → 20 passed; ruff check . clean; mypy . → 28 pre-existing errors, confirmed via git stash diff against this branch's own parent commit to be zero new errors.
• Rust: added a new harnessaas Cargo feature, wired into both the main rust CI job's feature list and the rust-feature-matrix array (.github/workflows/ci.yml); cargo build/test --test harnessaas_client (18 passed) /clippy --all-targets -- -D warnings all clean with the new feature; full workspace test suite (all CI features together) stays green.

PR: #108

[ruvnet]

PR #108 merged — M5 started with `HarnessaaSClient` scoped strictly to the REAL, deployed synchronous surface of `cognitum-one/harnessaas` (health/solve/lineage), confirmed against the just-reconciled gateway contract (#67/PR #107) rather than ADR-0027a's proposed-but-unbuilt async job/poll/SSE/approval design.

Independent review confirmed: zero leakage of the not-real async API anywhere (no job/poll/cancel/approval/artifact/webhook/microlora methods, even as stubs); the retry-safety judgment (single-attempt `solve()`, no auto-retry on 429/502/503/5xx — mirroring the duplicate-spend lesson from Meta Proxy's PR #93) verified directly against the real upstream source (zero Idempotency-Key/rate-limit handling found); `lineage()`'s bounded GET retry confirmed safe (pure read, no side effects); the `/health` vs `/healthz` route choice and auth header placement both confirmed against actual upstream source rather than taken on faith.

One process gap caught and closed: the implementing agent's self-report only ran the new 20-test HarnessaaS file, not the full existing Python suite — the reviewer ran the full suite (535 passed, 11 skipped) and confirmed zero regressions.

Remaining scope: ADR-0027a's proposed async job/poll/SSE/approval/artifact contract is NOT implemented (it doesn't exist upstream yet — building against it would produce bindings matching zero live routes) and ADR-0027b (isolation/evidence/webhooks) is untouched. Both remain explicitly out of scope until the real service grows that surface.