specverb: auto-resolve op by path+method convention, op becomes override #147

New issue

Closed

opened 2026-06-17 16:01:03 +00:00 by coilysiren · 2 comments

coilysiren commented

2026-06-17 16:01:03 +00:00

Owner

Problem

After ward#146 / commit 3dd1d4d (delete the engine expansion table), every can grant must hand-bind op "<operationId>". That made the engine durable across specs but pushed vendor-string boilerplate into every guardfile (createCurrentUserRepo, issueGetMilestonesList, ...). The Forgejo guardfile alone carried ~39 explicit ops.

Change

Resolve op automatically by generic REST convention, with op retained as an override seam. specverb.resolveOp (new, http/specverb/resolve.go) maps the canonical CRUD verbs (get/view/list/create/edit/delete) to an operation by HTTP method + the path's resource segment, against the embedded spec. Spec-agnostic: pure path+method, no vendor strings in engine code; the OpenAPI-3 reader lowers into the same internal model, so one resolver drives Swagger 2 / OpenAPI 3.x.

op becomes optional on can; explicit op always wins (irregular endpoints, fixed-body toggles, ambiguous matches).
Fail-closed: zero candidates, multiple candidates, or a non-CRUD verb is an error that names the candidates.
Wired into resolveDescriptor (specverb.go) and grantedPathMethods (prune.go) via the one resolveOp seam.

Decision

Pure runtime resolution, nothing recorded (no lock-table). Determinism comes from the vendored+locked+skew-checked spec; auditability from describe + fail-closed build errors.

Verification

Resolver reproduces the exact explicit op for every convention-resolvable grant across all three real ward specs (Forgejo/Tailscale/Trello) with zero mismatches. New resolve_test.go covers convention/override/fail-closed/ambiguous/PUT-fallback. Suite + vet + lint + godoc + doc-caps green.

Downstream: ward drops op on the resolvable grants in its four guardfiles.

## Problem After ward#146 / commit `3dd1d4d` (delete the engine expansion table), every `can` grant must hand-bind `op "<operationId>"`. That made the engine durable across specs but pushed vendor-string boilerplate into every guardfile (`createCurrentUserRepo`, `issueGetMilestonesList`, ...). The Forgejo guardfile alone carried ~39 explicit ops. ## Change Resolve `op` automatically by generic REST convention, with `op` retained as an override seam. `specverb.resolveOp` (new, `http/specverb/resolve.go`) maps the canonical CRUD verbs (`get`/`view`/`list`/`create`/`edit`/`delete`) to an operation by HTTP method + the path's resource segment, against the embedded spec. Spec-agnostic: pure path+method, no vendor strings in engine code; the OpenAPI-3 reader lowers into the same internal model, so one resolver drives Swagger 2 / OpenAPI 3.x. - `op` becomes optional on `can`; explicit `op` always wins (irregular endpoints, fixed-body toggles, ambiguous matches). - Fail-closed: zero candidates, multiple candidates, or a non-CRUD verb is an error that names the candidates. - Wired into `resolveDescriptor` (specverb.go) and `grantedPathMethods` (prune.go) via the one `resolveOp` seam. ## Decision Pure runtime resolution, nothing recorded (no lock-table). Determinism comes from the vendored+locked+skew-checked spec; auditability from `describe` + fail-closed build errors. ## Verification Resolver reproduces the exact explicit op for every convention-resolvable grant across all three real ward specs (Forgejo/Tailscale/Trello) with zero mismatches. New `resolve_test.go` covers convention/override/fail-closed/ambiguous/PUT-fallback. Suite + vet + lint + godoc + doc-caps green. Downstream: ward drops `op` on the resolvable grants in its four guardfiles.