feat: Add API trigger, AsyncAPI field, and orphan detection validation (#1506)

* feat: Add API trigger, AsyncAPI field, and orphan detection validation

Implement three validation enhancements for the manifest validator:

Task 2 - API trigger validation against OpenAPI spec: validates path
format, checks existence against the generated swagger spec, enforces
uniqueness across sagas, and provides "Did you mean?" suggestions.

Task 5 - AsyncAPI CEL field validation: cross-checks event filter CEL
expression field references against AsyncAPI payload schemas, producing
warnings (not errors) for unknown fields since specs may lag behind.

Task 11 - Operational gateway orphan detection: warns on provider
connections not referenced by any instruction route or webhook trigger,
and on instruction routes not dispatched by any saga script.

Uses functional options (WithOpenAPIPaths, WithAsyncAPISchemas) for
testability and graceful degradation when spec files are unavailable.

* fix: Update example manifests to use valid API trigger paths

The new API trigger validation correctly rejects fictional paths like
/v1/carbon/retire and /v1/energy/settlements. Update example manifests
to use /v1/sagas/execute which exists in the generated OpenAPI spec.

* fix: Address review feedback on validation enhancements

- Keep API path format and duplicate checks active when OpenAPI spec is
  unavailable; only skip the endpoint existence check
- Merge AsyncAPI fields across messages for the same channel instead of
  overwriting
- Reuse extractWebhookSource helper in validateWebhookTriggers to
  eliminate duplicated logic
- Extract resolveMessageFields to reduce parseAsyncAPIFile complexity
- Document regex-based Starlark scanning limitation for orphan detection
- Add tests for format/duplicate checks without spec and multi-message
  field merging

* fix: Handle bracket-notation CEL field refs and document auto-loading

- Extract field names from bracket notation (event["field"]) in CEL AST
  by detecting the _[_] index operator on the event variable
- Document auto-loading design rationale for OpenAPI/AsyncAPI specs
- Add regression tests for bracket and mixed dot/bracket CEL expressions

---------

Co-authored-by: Ben Coombs <bjcoombs@users.noreply.github.com>

Author: bjcoombs

examples/manifests/carbon.json

@@ -54,7 +54,7 @@
   "sagas": [
     {
       "name": "retire_carbon_credits",
-      "trigger": "api:/v1/carbon/retire",
+      "trigger": "api:/v1/sagas/execute",
       "script": "def execute(ctx):\n    retirement = ctx\n    amount = Decimal(str(retirement.get('tonnes', '0')))\n    position_keeping.initiate_log(amount=amount, direction='CREDIT')\n"
     }
   ]

examples/manifests/energy.json

@@ -87,7 +87,7 @@
   "sagas": [
     {
       "name": "process_energy_settlement",
-      "trigger": "api:/v1/energy/settlements",
+      "trigger": "api:/v1/sagas/execute",
       "script": "def execute(ctx):\n    settlement = ctx\n    amount = Decimal(str(settlement.get('amount', '0')))\n    position_keeping.initiate_log(amount=amount, direction='DEBIT')\n"
     }
   ]