Define repository structure and coverage for the Proof Engine API spec

[frisitano]

Define repository structure and coverage for the Proof Engine API spec

Context

eth-act/execution-proofs-api should become the implementation-neutral home for the Proof Engine API: the HTTP/SSE interface between a beacon node / honest prover and a proof engine.

Right now the closest concrete source is the openapi.json generated from zkboost, but the API contract should not be owned by a single implementation. This repo should define the canonical contract that clients, proof engines, test fixtures, and consensus-spec references can converge on.

We should take structural inspiration from ethereum/execution-apis:

• specs are split into readable source files rather than only one generated artifact;
• common definitions live separately from method-specific documents;
• shared schemas are factored into a dedicated schema area;
• build/validation commands produce a generated spec artifact;
• method-level tests/fixtures exist for conformance;
• versioning and compatibility expectations are documented explicitly.

Proposed repo shape

Aim for a layout that is easy to read in GitHub and easy to validate in CI:

README.md
CONTRIBUTING.md
LICENSE
Makefile / package scripts

src/
  proof-engine/
    README.md
    common.md
    authentication.md
    versioning.md
    lifecycle.md
    errors.md
    openapi/
      proof-engine-api.yaml
    methods/
      request-proof.md
      get-proof.md
      cancel-proof.md
      health.md
      capabilities.md
    sse/
      README.md
      events.md
      reconnect.md
  schemas/
    base-types.yaml
    proof-request.yaml
    proof-response.yaml
    proof-status.yaml
    proof-type.yaml
    sse-event.yaml
    errors.yaml

tests/
  request-proof/
  sse-events/
  errors/
  capabilities/

docs/
  contributors-guide.md
  tests.md

Coverage the initial spec should provide

• Transport and protocol model
• Request lifecycle
• Method / endpoint coverage
• SSE event coverage
• Shared schemas and base types
• Errors, retries, and timeouts
• Versioning and compatibility
• Conformance tests / fixtures