[antoinetoussaint-byte]

Summary

First of three PRs for codefly-dev/cli#1184 — every gRPC method of a module and every REST route of a solution becomes a tool by becoming a Runnable. The module half is already automatic; this makes a solution's routes derivable at all.

1. A REST read over GET is an operation. openAPIOperationMethods admitted only POST and PUT ("an operation applies an effect and is retried under a declared policy, which GET and DELETE do not describe"), while the module side already derives read-only operations ("a policy requiring only 'read' derives a read-only tool that is safe to re-run and carries no receipt"). A read is the safest operation to re-run, so GET is now admitted as a read only (readOnlyRoute): RECOVERY_RECOMPUTE, a read-only tool, and invoke scopes requiring nothing but read. Mutations keep their body, their receipt rules (untouched) and POST/PUT; DELETE and PATCH stay refused.

• A GET carries no body, so its query is its input (queryPayload): one object whose members are its query parameters, each a scalar, optional exactly when the parameter is; a GET with no parameter takes {}. Arrays, objects, nullables, a body, path parameters and path templates are refused by name.
• input_message is required by the package schema (min_len: 1). No component describes a query, so a GET records the identity the document publishes it under, its operationId; a GET without one is refused. (I chose this over relaxing the validated field, which would be a schema change.)
• HTTPRoute.verb in proto/codefly/runnable/v0/prepared.proto admitted only POST/PUT too, so a derived GET could not be prepared. It now admits GET (Go and Python regenerated with codefly generate proto … --local and --template buf.gen.python.yaml; proto/buf.lock restored, since only make buf-dep-update moves it). VerifyPrepared holds a delivered GET binding to the same read rule, so an installer does not trust that a generator applied it.

2. Dialect: core reads Swagger 2.0. I took the "core reads what exists" option. Evidence:

• solution-runtime-go/operations.go InterfaceDocument deliberately renders Swagger 2.0 — "the dialect the platform's proto-generated modules emit, so one reader handles every repository's artifact".
• Core's own OpenAPICombinator writes 2.0 (this file's previous comment said so), and protoc-gen-openapiv2 output is 2.0.
• The committed artifacts in obin-ai/core-solutions (solutions/{proposals,wiki}/contracts/api/backend/http/openapi.json on chore(deps): bump the docker-major group across 2 directories with 2 updates #451) are 2.0, and the CLI's route-policy reader (pkg/methodpolicy) already reads them as they are. Migrating to OpenAPI 3 would churn every solution's committed contract and collide with chore(deps): bump the docker-major group across 2 directories with 2 updates #451, for no change in what the document says.

ParseOpenAPIDocument now moves what Swagger spells differently — the in: body parameter, a response's schema, consumes/produces, typed parameters, #/definitions/ — into the OpenAPI 3 places before anything reads the document (fromSwagger). Every rule after that reads both alike, and TestTheTwoDialectsDeriveOneOperation holds the same operation in both dialects to a byte-identical package. Any other swagger version is still refused by name.

3. DefaultRouteOperation and RouteMarker. DefaultRouteOperation(method, path, authority, audience, name, description) is DefaultOperation's REST twin (core's default bounds, "503" as the HTTP spelling of UNAVAILABLE). RouteMarker(method, path, policyJSON, …) writes it as the x-codefly-operation marker from the x-codefly-authority-policy JSON an owner already publishes, byte-stably. That is how solution-runtime-go marks a route without inventing a bound — and without constructing core's wire messages, which its typed-boundary gates refuse in that package. A policy requiring nothing, a mutation over GET or a path template is ErrNotDerivable.

Classification

Fix at the owner: core owns the derivation, the bounded profile, the prepared-binding schema and the defaults. No stopgap.

Docs

docs/runnable.md (the two-builders table, "The REST reader": GET as a read, its query as input, both dialects), docs/runnable-binding-delivery.md (rest call verbs, the installer's GET rule).

Test plan

• go test -race ./runnable/... ./internal/ciguard/... — green; the existing TestPackageFromOpenAPIOperationIsByteStable digest is unchanged.
• New: runnable/operation_openapi_route_test.go — dialect drift gate, Swagger held to the same refusals, GET read derivation (/history query → input, /recorded → {}), every way a GET is refused, DefaultRouteOperation/RouteMarker (marker round-trips to the hand-written fixture's digest), prepared GET held to being a read. I removed the VerifyPrepared GET guard and watched TestAPreparedGetIsHeldToBeingARead fail, then restored it.
• make buf-lint, make buf-breaking (no breaking change against origin/main), and the Python contract tests with CI's exact command — green.
• golangci-lint is not in core's CI; locally one new note: goconst on the literal "object" (the projection beside it spells it the same way).

Not verified

• The full go test ./... of core: I ran ./runnable/..., ./internal/ciguard/..., ./generated/... and go build ./....
• Nothing executes a prepared GET yet. The two executors still refuse it: obin-ai/module-runtime pkg/runnable/transport.go bodiedMethods (POST/PUT/PATCH/DELETE), and obin-ai/module-robin runnable_catalog.go:94 skips every binding whose call is not Connect (prepared.GetCall().GetConnect() == nil), and toolowner/operation.go always POSTs a Connect procedure. Reported on feat(generate): a solution's routes become Runnables, and so tools, as a module's methods do (#1184) cli#1185; no issue filed without the owner's go-ahead.

Order

Merge this first. codefly-dev/solution-runtime-go#77 and codefly-dev/cli#1185 pin this branch's head d2cf8206, and re-pin to this PR's merge commit before they land (a squash would orphan d2cf8206).

Part of codefly-dev/cli#1184.

🤖 Generated with Claude Code