feat(gateway): Complete OpenAPI 3.0 specification

[gilbertsahumada]

What this PR does

Builds on the existing openapi.yaml to bring it up to full coverage of the Gateway API (27 endpoints). The original spec laid solid groundwork for the workflow endpoints; this PR extends it to cover the rest of the API surface and aligns a few field definitions with the latest code.

Schema alignments

• CreateWorkSubmissionRequest: updated to reflect the current dkg_evidence field (array of DKGEvidencePackage) which replaced the earlier thread_root/evidence_root fields
• CreateScoreSubmissionRequest: added worker_address and mode fields introduced with direct scoring support
• WorkflowResponse.progress: expanded to document progress shapes for all three workflow types
• WorkflowType enum: added AgentRegistration and StudioCreation
• HistoryEntry.role: updated to verifier to match the current return value
• Added nullable: true where the code can return null: epoch, evidence_anchor, derivation_root, thread_root, studioPolicy, workMandate

New endpoint coverage

• All /v1/* public read endpoints: reputation, history, work, evidence, context, viewer, leaderboard, skills, PR ingestion
• All /v1/sessions/* Engineering Studio session endpoints: create, append events, complete, context, evidence DAG, viewer
• All /admin/* key management endpoints
• Security schemes: x-api-key auth, admin auth
• Rate limiting documentation: 30 req/min write, 100 req/min read
• Reusable components: parameters, error responses, domain models
• Tags for logical grouping: Workflows, Agents, Work, Studios, Skills, Engineering, Sessions, Admin, Health

New: OpenAPI sync test

Added test/unit/openapi-sync.test.ts: a test that automatically detects drift between Express routes and the OpenAPI spec.

• Fails if a route exists in Express but not in the spec
• Fails if a path exists in the spec but not in Express
• Fails if HTTP methods don't match

This way, whenever someone adds or changes a route, the spec stays in sync without manual effort.

New: Gateway CI

Added .github/workflows/gateway-ci.yml: runs build + test on every PR that touches packages/gateway/.

Validation

• Spec validates cleanly with @redocly/cli lint: 0 errors
• All 465 tests pass, including the new sync test

---

Looking ahead: single source of truth for validation + docs

Note: This section is a recommendation for a future follow-up, not part of this PR.

The current validation layer uses hand-rolled functions (validateAddress, validateBytes32, etc.) with TypeScript as casts. This works, but it means the type definition, the validation logic, and the OpenAPI spec are maintained separately, which is what led to some of the fields drifting apart over time.

A natural evolution would be migrating to Zod schemas, which unify all three into a single source of truth:

// With Zod: one definition does everything
const WorkSubmissionSchema = z.object({
  studio_address: z.string().regex(/^0x[a-fA-F0-9]{40}$/),
  epoch: z.number().int().min(0),
  // ...
});
type WorkSubmissionInput = z.infer<typeof WorkSubmissionSchema>; // type is derived
const input = WorkSubmissionSchema.parse(req.body); // validates + types in one call

Benefits:

• Eliminates drift: type, validation, and spec come from the same schema
• ~160 lines of manual validation become declarative schemas: easier to read, review, and extend
• Runtime safety: z.parse() catches invalid data with clear error messages
• Auto-generated OpenAPI: with @asteasolutions/zod-to-openapi, the spec can be derived directly from the schemas
• Better DX for contributors: adding a new field means changing one schema, not three places

Happy to tackle this in a follow-up PR to keep this one focused on spec coverage. The migration is mechanical (interfaces -> Zod schemas, validate functions -> .parse()) with no API-facing changes.

[SumeetChougule]

@gilbertsahumada is this PR up to date?

[gilbertsahumada]

@gilbertsahumada is this PR up to date?

due to the latest updates, it's out of date. I'm going to merge the latest changes from the develop into my branch, push and it'll ready to be merged.