feat(captures): add named API sources, CDL routes, and capturer grains

[Copilot]

Summary

This extends capture authoring and CDL to support named API sources with optional routes, renames the declarative capture interface to ICapturer, and adds initial backend capturer supervision grains. Documentation has been updated to match the current APIs and language behavior.

Added

• New declarative capture entry interface: ICapturer.
• API route support for capture sources in both client authoring and CDL (route on API sources).
• Initial backend capture supervision primitives in Core: capturer manager, trigger, and capturer grains.
• Expanded capture documentation covering named API usage and optional API routes.

Changed

• Declarative client API now references APIs by name instead of inline URLs (FromApi(api, ...)), with optional route configuration.
• Model-bound API capture attribute now uses API name semantics and supports optional route configuration.
• CDL API source properties now use api (required for API sources) and optional route instead of inline url.
• Declarative samples and language/spec docs updated to reflect current syntax and behavior.
• ICaptureFor is now compatibility-only via inheritance from ICapturer.

Fixed

• Corrected named-argument ordering in WebhookSourceBuilder to satisfy analyzer rule RCS1205 and unblock client build.

Removed

• None.

Security

• None.

Deprecated

• ICaptureFor is superseded by ICapturer and retained for compatibility.

[einari]

@copilot Great. And as we have for Projections in the workbench, we need a similar editor with full Monaco a language service implemented.

[Copilot]

@copilot Great. And as we have for Projections in the workbench, we need a similar editor with full Monaco a language service implemented.

Done in commit 7acc52c. Added the full Monaco language service for CDL and a Captures feature page, following the same conventions as the ProjectionEditor:

Components/CaptureEditor/

• language.ts — Monarch tokenizer with all CDL keywords highlighted, template-literal support, and $.path, $previous.path, $context.*, $env.* expressions
• CaptureDefinitionLanguageValidator.ts — inline validation (first line must be capture Name, checks for source/key, each append block needs a when)
• CaptureDefinitionLanguageCompletionProvider.ts — context-sensitive completions (source types, keyword suggestions, $., $previous., $context.occurred, etc.)
• CaptureDefinitionLanguageHoverProvider.ts — hover docs for every CDL keyword and built-in expression
• CaptureHelpPanel.tsx — slide-in reference panel with all CDL sections
• CaptureEditor.tsx — Monaco wrapper with ? help button and changed-line gutter decorations

Features/EventStore/General/Captures/Captures.tsx — two-pane page: capture list on the left, editor on the right, with New / Save toolbar actions.

EventStore.tsx — route (captures) and menu item wired in.

[einari]

@copilot Great. Lets do a few more things:

• Create 2 client APIs for this; declarative and model-bound - take inspiration from what we've done for Projections
• Create full documentation for this, including a language specification - like we've done for the Projection. Document both client approaches, and the language and an actual language specification as well.

[github-actions]

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Cratis Benchmarks'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.50.

Benchmark suite	Current: c9f6338	Previous: 9c41e1c	Ratio
Cratis.Chronicle.Benchmarks.AppendManyBenchmark.AppendManyEvents(EventCount: 100)	137919161.41666666 ns (± 7181163.209171882)	68128824.7 ns (± 7671149.609764319)	2.02

This comment was automatically generated by workflow using github-action-benchmark.

CC: @einari

[einari]

@copilot The API definition should not be done inline - but instead reference an API by name - the API should be defined in a similar way to how we do WebHooks, but we should be able to define the trigger; polling every N minutes - like done here, that is fine. But the API itself is typically something we configure independently.However, on the CDL we should also be able to define a route. So while the API is defined as a source, that can be the root for many different APIs and we then use routes on top. But if not a route is specified, we'll just use the URL straight up.

This means we need a way to handle this.

On the backend in Core. We need a Capturer manager that sets up the triggers. The manager should be a grain and the triggers should also be a grain, and the actual Capturer should also be a grain. That way we can easily scale things out. See them as supervisors over supervisors.

In the client, the interface ICaptureFor should be renamed to ICapturer.

[Copilot]

@copilot The API definition should not be done inline - but instead reference an API by name - the API should be defined in a similar way to how we do WebHooks, but we should be able to define the tri...

Implemented in 80c737a.

• Capture client API now references API definitions by name (FromApi(api, ...)) and supports optional route configuration (OnRoute(route)), with model-bound parity via [ApiCapture(api, Route = ...)].
• CDL source API configuration now supports api + optional route (and no inline url), including parser/compiler/spec updates and documentation.
• Added Core Orleans supervision primitives for captures: ICapturerManager/CapturerManager, ICaptureTrigger/CaptureTrigger, and ICapturerGrain/Capturer.
• Introduced ICapturer and updated docs/usages accordingly (ICaptureFor now inherits ICapturer for compatibility).