feat(yaml): support ref targets, scope-refs, and ref data

[johanpel]

Description

Adds entity references to the YAML DSL, and makes their target type-safe in the generated instrumentation.

The DSL gains ref: <Entity> and scope-ref: <Entity> type forms, each with an optional data: payload. ref emits the quent.ref-target constraint; scope-ref also emits quent.ref-tree. Targets and tree shape are validated at load time.

In the generated instrumentation, EntityRef<E, T> is now parameterized by a per-entity marker, so a reference's target entity is checked at compile time. Each handle produces its own references via as_entity_ref / as_entity_ref_with (and as_any_entity_ref variants for untargeted fields).

The instrumentation-build example shows both forms end to end.

Related Issues

Part of #355

🤖 Generated with Claude Code

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: QUIET

Plan: Enterprise

Run ID: 57629685-5c0c-4766-be0e-33e0ede81ddc

📥 Commits

Reviewing files that changed from the base of the PR and between 9d4615f and f172590.

📒 Files selected for processing (2)

• crates/instrumentation-build/src/data_type.rs
• crates/yaml/tests/references.rs

---

📝 Walkthrough

Walkthrough

The YAML schema adds ref and scope-ref forms with target and tree constraints. Instrumentation references now carry entity marker types, generated handles expose typed conversions, and the example emits server-linked connection events with routing data.

Changes

Typed entity references

Layer / File(s)	Summary
YAML reference parsing and validation crates/yaml/..., crates/yaml/tests/references.rs	YAML reference forms are parsed, lowered into constrained entity references, validated, and covered by annotation tests.
Typed reference representation and code generation crates/instrumentation/src/..., crates/instrumentation-build/src/..., crates/instrumentation-build/Cargo.toml	EntityRef carries an entity marker, generated entities expose marker types and typed handle methods, and code generation maps target constraints to marker identifiers.
Example server and connection flow crates/instrumentation-build/example/...	The example defines Server and Route, links opened and routed connection events to servers, and handles connection and server events in the exporter.

Estimated code review effort: 4 (Complex) | ~45 minutes

Possibly related PRs

• rapidsai/quent#270: Earlier YAML AST and lowering work that this targeted-reference pipeline builds upon.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: YAML support for ref targets, scope refs, and optional ref data.
Description check	✅ Passed	It covers the main description and related issue, but omits the Testing and Screenshots sections from the template.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/instrumentation-build/src/data_type.rs`:
- Around line 59-84: Add a test covering EntityRef target-marker generation with
a quent.ref-target annotation, using a target such as Cluster and asserting the
generated type includes EntityRef<Cluster, ...>. Keep the existing
default-annotation test for the AnyEntity fallback, and place the new coverage
alongside tests for map_data_type or ref_target_marker.

In `@crates/yaml/Cargo.toml`:
- Around line 10-11: Add quent-ref-target and quent-ref-tree to the root
[workspace.dependencies], then update crates/yaml/Cargo.toml lines 10-11 to use
workspace-managed declarations with workspace = true instead of local path
dependencies. Apply the same workspace dependency change to quent-ref-target in
crates/instrumentation-build/Cargo.toml line 12; do not introduce git
dependencies.

In `@crates/yaml/src/lower.rs`:
- Around line 213-219: Update the docstring for the entity-reference helper near
the targeted/tree-forming reference construction to describe only the returned
reference type and its optional data/tree-forming behavior. Remove details about
ref-target/ref-tree constraint storage and validation responsibilities, keeping
the documentation focused on the helper’s public contract.

In `@crates/yaml/tests/references.rs`:
- Around line 97-116: Extend scope_emits_target_and_tree by adding a data
payload to the scope-ref for Cluster, then assert the resulting EntityRef data
type through the returned annotations. Preserve the existing target and tree
assertions while covering the advertised scope-ref data path.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: QUIET

Plan: Enterprise

Run ID: 2bf72a3c-6eb4-44b7-8753-bb0e8ca8bdc5

📥 Commits

Reviewing files that changed from the base of the PR and between b68dab1 and 9d4615f.

⛔ Files ignored due to path filters (2)

• Cargo.lock is excluded by !**/*.lock, !Cargo.lock
• crates/instrumentation-build/example/Cargo.lock is excluded by !**/*.lock

📒 Files selected for processing (14)

• crates/instrumentation-build/Cargo.toml
• crates/instrumentation-build/example/model.yaml
• crates/instrumentation-build/example/src/main.rs
• crates/instrumentation-build/src/data_type.rs
• crates/instrumentation-build/src/events.rs
• crates/instrumentation-build/src/runtime/handle.rs
• crates/instrumentation-build/src/runtime/mod.rs
• crates/instrumentation/src/entity_ref.rs
• crates/instrumentation/src/lib.rs
• crates/yaml/Cargo.toml
• crates/yaml/src/ast.rs
• crates/yaml/src/lib.rs
• crates/yaml/src/lower.rs
• crates/yaml/tests/references.rs

[johanpel]

/merge