feat(yaml): add resource declarations

[johanpel]

Description

Add YAML syntax and lowering for unit and capacity-based resources.

Resources can declare capacities with or without known-bounds, expose bounds through events with sets-resource-bounds, and resources can be claimed through uses. Generated usage and bounds record names can be overridden.

Example

quent: alpha
model: demo

entities:
  Memory:
    resource:
      capacities:
        bytes:
          kind: occupancy
          known-bounds: true
        bandwidth:
          kind: rate
      usage-record: MemoryClaim
      bounds-record: MemoryLimits

    events:
      resized:
        multi: true
        attributes:
          limits:
            sets-resource-bounds: true

fsms:
  Task:
    states:
      running:
        initial: true
        attributes:
          memory:
            uses: Memory
        to: [running, exit]

• kind is occupancy or rate.
• known-bounds defaults to false.
• usage-record and bounds-record are optional. Their defaults are MemoryUsage and MemoryBounds.
• sets-resource-bounds inserts the generated bounds record as the attribute type.
• uses generates a targeted entity reference carrying the usage record.
• A unit resource uses resource: true.

Written by Codex.

Related Issues

Solves #196. This is the final constraint necessary to make the YAML DSL capture an application event model at feature parity with PoC Quent as far as the application-agnostic parts are concerned.

Because resources are somewhat involved, I've decided not to add them to the instrumentation-build example, but will follow up later with more gently introduced examples in #419.

[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: a82e4202-bbdf-4157-a7b2-beb79097f462

📥 Commits

Reviewing files that changed from the base of the PR and between a5ce273 and e4d5723.

📒 Files selected for processing (3)

• Cargo.toml
• crates/yaml/Cargo.toml
• crates/yaml/tests/resource.rs

---

📝 Walkthrough

Walkthrough

Changes

The YAML crate now supports resource declarations, generated usage and bounds records, resource-aware type and event lowering, resource validation, and uses: references. Tests cover valid resource schemas, custom record names, unit resources, bounds handling, collisions, and invalid configurations.

YAML resource support

Layer / File(s)	Summary
Resource contracts and record naming crates/resource/src/builder.rs, Cargo.toml, crates/yaml/Cargo.toml, crates/yaml/src/ast.rs	Adds resource AST types, usage expressions, dependency wiring, and public default record-name helpers.
Resource validation integration crates/yaml/src/lib.rs, crates/yaml/src/lower.rs	Validates ResourceConstraint and rejects direct resource annotations outside resource: blocks.
Resource record generation crates/yaml/src/lower.rs	Discovers resource declarations, generates usage and bounds records, attaches resource annotations, and reports generated-record collisions.
Resource references and event fields crates/yaml/src/lower.rs	Resolves usage references and lowers resource bounds markers into event fields with resource-aware entity-reference annotations.
Resource behavior coverage crates/yaml/tests/resource.rs	Tests generated records, unit resources, FSM resources, bounds fields, usage references, custom names, and invalid configurations.

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

Possibly related PRs

• rapidsai/quent#387: Adds the resource-builder and resource-constraint foundation used by this change.
• rapidsai/quent#406: Shares the YAML FSM validation and event-lowering paths updated here.
• rapidsai/quent#438: Is directly connected to YAML reporting of resource constraint validation errors.

Suggested labels: feature request

Suggested reviewers: mbrobbel, dhruv9vats

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the main change: adding resource declarations to the YAML feature set.
Description check	✅ Passed	The description covers the purpose, behavior, example, and related issue, though Testing and Screenshots sections are missing.
Docstring Coverage	✅ Passed	Docstring coverage is 85.71% 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]

Note

Quiet mode is enabled, so only the most important comments were posted inline. Other review comments are grouped below.

🟡 Other comments (1)

crates/yaml/Cargo.toml-13-13 (1)

13-13: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Move quent-resource to the workspace table

In crates/yaml/Cargo.toml, reference quent-resource with workspace = true and add it once under [workspace.dependencies] in the root manifest.

🤖 Prompt for 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.

In `@crates/yaml/Cargo.toml` at line 13, Update the quent-resource dependency in
the YAML crate manifest to use the workspace dependency declaration, then add a
single quent-resource entry under the root manifest’s [workspace.dependencies]
table using its existing path configuration.

Source: Path instructions

🧹 Nitpick comments (1)

crates/yaml/tests/resource.rs (1)

27-49: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Missing test coverage for kind: rate capacities.

Every capacity fixture in this suite uses kind: occupancy; per the PR objective, resources can also declare capacities of kind: rate, but no test exercises that path (record generation, bounds, or validation for rate). Consider adding at least one test analogous to resource_declaration_generates_records_and_carries_bounds with a rate capacity, and optionally a resource with more than one capacity field, to close this gap.

🤖 Prompt for 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.

In `@crates/yaml/tests/resource.rs` around lines 27 - 49, Add test coverage in the
resource declaration tests for a capacity with kind: rate, analogous to
resource_declaration_generates_records_and_carries_bounds. Assert record
generation, propagated bounds, and validation for the rate capacity; include
multiple capacity fields only if needed to exercise the relevant path.

🤖 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.

Other comments:
In `@crates/yaml/Cargo.toml`:
- Line 13: Update the quent-resource dependency in the YAML crate manifest to
use the workspace dependency declaration, then add a single quent-resource entry
under the root manifest’s [workspace.dependencies] table using its existing path
configuration.

---

Nitpick comments:
In `@crates/yaml/tests/resource.rs`:
- Around line 27-49: Add test coverage in the resource declaration tests for a
capacity with kind: rate, analogous to
resource_declaration_generates_records_and_carries_bounds. Assert record
generation, propagated bounds, and validation for the rate capacity; include
multiple capacity fields only if needed to exercise the relevant path.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: QUIET

Plan: Enterprise

Run ID: b625d633-07aa-4fda-8835-0a1363589631

📥 Commits

Reviewing files that changed from the base of the PR and between 967aa83 and a5ce273.

⛔ 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 (6)

• crates/resource/src/builder.rs
• crates/yaml/Cargo.toml
• crates/yaml/src/ast.rs
• crates/yaml/src/lib.rs
• crates/yaml/src/lower.rs
• crates/yaml/tests/resource.rs

[johanpel]

/merge