Reconcile stale HarnessaaS gateway contract against current upstream source before binding generation

[ruvnet]

Milestone: M5 | Mission: Cognitum Agentic SDK Integration

ADR-0019 documents that the checked-in HarnessaaS gateway spec still describes Google ID-token auth and only covers /solve and /lineage/{request_id}, while current upstream source has newer tenant/API-key behavior.

This must be resolved before any Node/Python/Rust binding work starts -- this is the single biggest risk flagged in the mission plan. The SDK cannot safely generate bindings from the stale document without reconciling the contract first.

Governing ADR: 0019 (context section, HarnessaaS source-review note). Blocks #17.

---

Filed from the reviewed mission plan. Routes to Project #1 (Product Roadmap), cross-linked to #7.

[ruvnet]

HarnessaaS gateway-contract reconciliation — findings

Re-cloned cognitum-one/harnessaas read-only (no writes made to that repo) and
verified the ADR-0019 / ADR-0027a citations against the live upstream HEAD.
ADR doc fix: #107.

1. The cited commit hash is NOT actually stale

git log -1 --format=%H on a fresh clone returns
908e4a99332617fd321d6f23a1d5a70e07413ffa — the exact hash already cited in
ADR-0019 and ADR-0027a/0027b. 87 commits total, none newer than 2026-07-09
(clone date 2026-07-19). So the "stale commit hash" premise this issue was
filed under does not hold — the citation was already current. What did need
checking (and is the actual substance below) is whether the claims made
against that commit still hold, and whether anything else has drifted.

2. Current auth mechanism — reconfirmed cog_ API key, not Google ID token

• src/auth.ts:1-24 (module doc) and src/auth.ts:77
  (const KEY_RE = /^cog_[0-9a-fA-F]{64}$/) — inbound auth is a cog_ +
  64-hex-char key, SHA-256 hashed and looked up in a multi-tenant api_keys
  store.
• src/server.ts:262-274 (authenticate()) — reads X-API-Key /
  Authorization: Bearer, verifies against the KeyStore, and returns a
  TenantContext (401 on failure, opaque error).
• config/api-gateway.openapi.yaml:16-26 — still declares
  google_id_token / OAuth2 implicit flow against accounts.google.com as
  the gateway's security scheme. This file is genuinely stale/aspirational —
  a GCP API Gateway deploy scaffold that was never updated to match the
  service's real auth. ADR-0019's claim about this exact gap was already
  correct and remains correct today.

3. Current route surface — wider than ADR-0019's summary suggests

Confirmed in src/server.ts (602 lines) at current HEAD:

Route	Auth	Source
GET /health, /healthz, /status	public	server.ts:286-304
GET /webhooks/public-key	public	server.ts:308-311
POST/GET/DELETE /webhooks, GET /webhooks/:id/deliveries	cog_ key	server.ts:312-340 (ADR-0031)
/api/v1/* (IBO-console + meta-capabilities relay)	cog_ key	server.ts:342-365
POST /solve	cog_ key	server.ts:367-501
POST /microlora/run, GET /microlora/status, GET /microlora/lineage/:id	cog_ key	server.ts:503-508 (ADR-0032)
GET /lineage/:request_id	cog_ key	server.ts:510-526

None of the webhook, MicroLoRA, or /api/v1/* routes appear in
config/api-gateway.openapi.yaml (which only documents /healthz, /solve,
/lineage/{request_id}). ADR-0019's one-line table cell ("Solve, lineage,
receipt, conformance, and evolving job APIs") is directionally fine but
undersells how much already exists beyond solve/lineage.

4. SolveResponse shape — no drift

src/types.ts:786-793 (SolveResponse) matches both the README's example
JSON and ADR-0027a's cited shape exactly: request_id, patch, resolved,
cost_receipt, lineage_ref, conformance. No field-name/shape drift found.

5. THE most important finding — sync vs. async is real, but already known

POST /solve (server.ts:367-501) is genuinely synchronous: one HTTP
request in, the full SolveResponse out, in the same response body. There is
no job resource, status endpoint, cancellation, resumable SSE stream, or
approval gate anywhere in the running service. Confirmed by grep across
src/ and config/ for job/poll/SSE/approval-shaped API surface — the only
"polling" and "approval" hits are (a) src/batch.ts's poll loop against the
upstream model provider's batch API (an internal implementation detail, not
a client-facing HarnessaaS contract), and (b) a human-approval verification
model that's explicitly DEFERRED (src/types.ts:41,50) and used for
internal business-vertical dispositions, not job-state approvals.

This is a real structural gap — but it is not an oversight anyone needs to
discover. ADR-0027a's own Context section already states this plainly
("POST /solve is synchronous... There is no public durable job, status,
cancellation, progress, resume, or idempotency contract... an asynchronous
dispatcher/worker/status/webhook model [is] mandatory, but that model is not
implemented") and its "Decision" section is an explicit proposal to
replace one-shot solve semantics with an async job resource — it is not
describing something already shipped. ADR-0027a's own Status is Proposed.
So: the sync-vs-async question resolves cleanly, in the sense that there's no
contradiction between the ADR and the code — the ADR is honest about the gap
and is designing to close it. The risk is purely for anyone reading ADR-0027a
quickly and assuming its D1/D2 client surface (submitSolve, getSolve,
/v1/solves/{job_id}/events SSE, etc.) already exists server-side. It does
not.

One gap this audit does newly surface: MicroLoRA (/microlora/*,
ADR-0032) is also synchronous and is not mentioned anywhere in ADR-0027a's D1
client surface or D2 route table. If/when the async job model in ADR-0027a
is implemented, someone needs to explicitly decide whether MicroLoRA folds
into it too, or stays a separate synchronous surface — left undecided, it
risks becoming the next stale-contract issue.

6. Recommendation

M5 binding work (issues #68/#69) can proceed, scoped narrowly:

• Safe to bind against today's real, verified, synchronous surface:
  /health//healthz//status, POST /solve, GET /lineage/:id,
  /webhooks/*, /microlora/*, and the /api/v1/* relay — all confirmed
  live, cog_-key authenticated, and stable against the current HEAD.
• Do NOT generate bindings from config/api-gateway.openapi.yaml — it is
  confirmed stale (wrong auth scheme, missing >half the routes) and
  ADR-0027a already says as much ("The SDK does not code-generate from the
  stale Swagger 2 file").
• Do NOT bind against ADR-0027a's D1/D2 async job API
  (submitSolve/getSolve//v1/solves/*/SSE events/approvals/artifacts)
  yet — it is a Proposed design, not a deployed contract. Binding against it
  now would produce a client for an API that doesn't exist.
• Before implementation, HarnessaaS/SDK owners should explicitly decide
  MicroLoRA's fate under the ADR-0027a job model (fold in vs. stay separate)
  so it doesn't become a second version of this same issue.

Net: the specific risk this issue was filed to address (a stale gateway
contract blocking safe binding generation) is resolved for the current,
synchronous API — that contract is now reconciled and documented in ADR-0019
(PR #107). It remains a real, open, and already-tracked risk for the
not-yet-built async job API in ADR-0027a, which is a separate, larger
piece of work than this issue's scope.