Variant-aware properties: per-variant field VALUES on a single artifact

[avrabe]

Problem

Today rivet has variant handling (feature model + variant config + binding model), but a single requirement cannot carry different field VALUES per variant. The motivating example: REQ-THERMAL-01.max-temp-c should be 80 in the automotive variant, 100 in industrial, 70 in consumer — same intent, same verification, same upstream stakeholder, just different numeric bounds.

Current workarounds (split into N artifacts, smuggle into description, reanchor on feature attributes) all damage traceability or break validation.

Design report

See docs/design/variant-aware-properties.md for the full report:

• Today's state in rivet (where the gap is)
• Competitor survey: Polarion, DOORS Next + pure::variants, sphinx-needs, FeatureIDE, Clafer, TVL
• Academic context: Czarnecki, Apel et al., COVAMOF, Attributed Feature Models
• Five candidate designs scored on validator complexity / dashboard / traceability / AI-friendliness / audit
• Recommendation + YAML shape + worked examples + MVP scope + open questions

Recommendation (v1)

Add an optional fields-per-variant: map on every artifact — a flat BTreeMap<variant_name, BTreeMap<field_name, Value>> overlay on top of the existing fields: defaults:

- id: REQ-THERMAL-01
  type: requirement
  fields:
    max-temp-c: 80          # default / fallback
    min-temp-c: -20
  fields-per-variant:
    automotive: { max-temp-c: 80,  min-temp-c: -40 }
    industrial: { max-temp-c: 100, min-temp-c: -40 }
    consumer:   { max-temp-c: 70,  min-temp-c:   0 }

Resolution = merge(fields, fields_per_variant.get(active_variant)) — no new evaluator needed. Forward-compatible to expression-valued fields (option B in the doc) without schema rework.

MVP scope

• Schema: fields-per-variant on Artifact, optional, default empty.
• Validate: variant-key cross-check against binding model's variants:; per-field type-check identical to existing fields: validator.
• API: Artifact::resolved_fields(variant: &str).
• CLI: rivet show REQ-XXX --variant automotive, rivet validate --variant automotive.
• Dashboard: variant selector + per-cell override marker.
• Tests: dogfood pass updated to enumerate variant resolution; golden-file test for the motivating example.

Out of scope for v1: expression-valued fields, predicate-keyed overrides (multi-axis), exhaustiveness check, ReqIF/OSLC explode-on-export, SAT/SMT attribute calculations.

Single most important open question

Exclusive vs compositional override keys. Should each artifact field have exactly one applicable variant override (PV-style first-true-wins, simple to validate / render) or should multiple keys be allowed to apply simultaneously and merge in order (real PLE multi-axis: market × ASIL × cooling-class)? The answer determines whether v1's data shape is BTreeMap<name, …> or Vec<{ when, fields }>.

Trace

Refs: FEAT-001

[avrabe]

Triage: the design report and "MVP scope" section are unusually thorough, but there is no ## Acceptance Criteria section. To run this under the oracle-gated workflow (ref), please lift the MVP-scope bullets into testable acceptance criteria so completion is mechanically checkable.

Suggested:

## Acceptance Criteria

- [ ] `Artifact` schema gains optional `fields-per-variant: BTreeMap<VariantKey, BTreeMap<FieldKey, Value>>` (default empty); round-trips through `rivet validate`
- [ ] Validate enforces: each variant key matches `binding.variants[]`; each per-variant field type-checks against the field's declared type in the artifact-type schema
- [ ] `Artifact::resolved_fields(variant: &str) -> BTreeMap<FieldKey, Value>` merges defaults + per-variant overrides; absent overrides fall back to the default value
- [ ] `rivet show <ID> --variant <name>` prints resolved fields; without `--variant` shows defaults only
- [ ] `rivet validate --variant <name>` validates field constraints under the resolved view
- [ ] Dashboard variant selector renders a per-cell override marker when the resolved value comes from `fields-per-variant`
- [ ] Tests: golden on the `REQ-THERMAL-01` example (3 variants, 2 fields), schema rejection of unknown variant key, type-check failure surfaced for an out-of-type per-variant value
- [ ] Commit trailer `Implements: REQ-010` (schema) + `Implements: REQ-007` (CLI)

Blocker on scope, not bullets: per the design doc, the open question on exclusive vs compositional override keys decides whether v1's data shape is BTreeMap<VariantKey, …> or Vec<{ when, fields }>. Until that is answered the AC above hard-codes the simpler shape; flipping later is a breaking schema change. Recommend resolving that question in the issue body before the AC lands.

---

Generated by Claude Code — issue-triage agent run 2026-05-01.

---

Generated by Claude Code

[avrabe]

User decision: use s-expr predicates for the override clause

Per maintainer feedback (1 May): rivet already has s-expression filters (rivet query --filter '(and (= type "requirement") (has-tag "stpa"))'). Reusing that engine for variant overrides is a sharp design choice.

Updated recommendation

The primary mechanism becomes a Vec<{ when: SExpr, fields: Map }> underneath the same surface, with first-match-wins merge semantics.

Worked example:

- id: REQ-001
  type: requirement
  fields:
    max-temp: 80              # default fallback
  fields-per-variant:
    - when: (= variant "automotive")
      fields: { max-temp: 80 }
    - when: (and (= variant "industrial") (>= asil "B"))
      fields: { max-temp: 100, redundancy: dual }
    - when: (= variant "medical")
      fields: { max-temp: 60 }

Pros vs the original BTreeMap-only option (option A)

• Reuses existing s-expr engine — no new predicate evaluator
• Multi-axis composes naturally (market × ASIL × cooling-class) without forcing predicate evaluation into v2
• Already understandable to anyone who's used rivet query
• Same predicate language across the codebase (variant overrides + filters + future when-clauses on artifact-types)

Cons

• Order-dependence is visible to authors. Document explicitly: first match wins, default fields: is the fallback if nothing matches.
• Slightly slower validation (predicate eval per artifact per variant) — but rivet's already paying that cost in rivet query
• More expressive = more rope; needs a clear "don't shadow yourself" gotcha in the docs

Compositional merge — opt-in v2

Multi-key merge-in-order (where multiple matching when: clauses contribute) stays out of v1. If real customer scenarios need it later: add fields-per-variant-merge: order flag at the artifact-type level. v1 = always first-match-wins.

MVP scope (revised)

1. Schema: extend artifact YAML with fields-per-variant: Vec<{ when, fields }>
2. Resolver: Artifact::resolved_fields(variant_context) = walk fields-per-variant in order, return first match's merge-with-default; no match = default fields:
3. Reuse the s-expr evaluator from rivet-core/src/sexpr.rs (or wherever query lives)
4. rivet validate --variant <name> evaluates per-variant; without flag, validates all variants and warns on unreached overrides (lint)
5. Dashboard variant selector shows resolved values
6. Dogfood test: a variant-aware artifact in rivet's own artifacts/

[avrabe]

Triage follow-up: the open question flagged in the 2026-05-01 triage comment (exclusive vs compositional override keys) was resolved later that day in the maintainer reply — Vec<{ when: SExpr, fields: Map }> with first-match-wins, reusing the existing s-expr engine. Compositional merge stays out of v1.

The remaining blocker for an autonomous implementation run is purely editorial: the revised AC needs to land in the issue body. Suggested lift, reflecting the maintainer decision:

## Acceptance Criteria

- [ ] `Artifact` schema gains optional `fields-per-variant: Vec<{ when: SExpr, fields: BTreeMap<FieldKey, Value> }>` (default empty); round-trips through `rivet validate`
- [ ] Validate enforces: each `when:` parses against the existing s-expr grammar; each per-variant field type-checks against the field's declared type in the artifact-type schema
- [ ] `Artifact::resolved_fields(variant_context: &VariantContext) -> BTreeMap<FieldKey, Value>` walks `fields-per-variant` in order, returns the **first** match's merge-with-default; no match falls back to the default `fields:`
- [ ] s-expr evaluator reused from `rivet-core/src/sexpr.rs` (or wherever query lives) — no new evaluator
- [ ] `rivet show <ID> --variant <name>` prints resolved fields; without `--variant` shows defaults only
- [ ] `rivet validate --variant <name>` validates field constraints under the resolved view; without flag, validates all known variants and emits a lint warning on any `when:` clause not reached by any variant
- [ ] Dashboard variant selector renders a per-cell override marker when the resolved value comes from `fields-per-variant`
- [ ] Documentation explicitly states: **first match wins; default `fields:` is the fallback if nothing matches; ordering is author-visible**
- [ ] Tests: golden on a 3-variant `REQ-THERMAL-01` example (automotive / industrial / medical), unreached-`when:` lint surfaces, type-check failure surfaced for an out-of-type per-variant value, dogfood test against a variant-aware artifact in rivet's own `artifacts/`
- [ ] Commit trailer `Implements: REQ-010` (schema) + `Implements: REQ-007` (CLI)

Out-of-scope-for-v1 per the maintainer reply (capture as follow-up issues if/when needed): compositional/multi-axis merge, fields-per-variant-merge: order flag at artifact-type level, expression-valued field values, exhaustiveness check.

Once these bullets land in the body, this becomes a clean implementation pickup.

---

Generated by Claude Code — issue-triage agent run 2026-05-05.

---

Generated by Claude Code