Skip to content

refactor(bridge): binding-first invariant resolution model for discovery #364

Description

@yeongseon

Context

Umbrella / architectural. Successive fixes (#347, #354, #358/#359, and the route/method follow-ups) have grown scan_endpoint_metadata into a special-case state machine: _reconcile_all_methods_expansion, explode_canonical, find_by_function_id, endpoint_key fallback, and short-name fallback all interact. Each new binding shape has required another branch.

Proposed invariant model to collapse the special cases:

  1. Azure @app.route binding is the source of truth for route + method.
  2. @openapi / endpoint / validation metadata is enrichment only (schema, description, params) — never routing truth (except explicit @openapi(route=/method=) as deliberate override).
  3. Registry operation identity = method::path (not function_id).
  4. function_id = source handler identity, one-to-many allowed.
  5. Scan flow: resolve binding → concrete operations FIRST, then merge each metadata source into the exact matching operation.

This makes route/method loss and method collapse structurally impossible rather than patched per-case, and subsumes the one-to-many function_id issue.

Acceptance Checklist

  • Refactor scan_endpoint_metadata to binding-first operation resolution.
  • Remove/inline the now-redundant reconciliation special cases.
  • Preserve all existing behavior via the current + newly added regression suites (POST/GET+POST/unspecified, route!=funcname, explicit overrides, idempotency, warnings).
  • No net behavior change vs. the sum of the point fixes; make check-all green; coverage >= 95%.

Out of scope

  • Point fixes shipped in the preceding P0/P1 issues (this refactor lands after them, in a minor release).

References

Metadata

Metadata

Assignees

No one assigned

    Labels

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions