ucwm/specialists/quantity.md

# Quantity Specialist

**specialist_id:** `quantity`  
**trigger_gates:** `has_quantity`, `is_math`

---

## Responsibility

The quantity specialist extracts numeric values, attaches QuantityFacets to quantity objects, and emits arithmetic and comparison constraints. When arithmetic can be resolved deterministically, it resolves it. When resolution requires a solver, it emits a structured constraint for the resolver.

---

## Manifest

```
declared_facet_kinds:
  - quantity

declared_constraint_types:
  - quantity_equals
  - quantity_sum
  - quantity_difference
  - quantity_product
  - quantity_quotient
  - quantity_greater
  - quantity_less
  - quantity_at_least
  - quantity_at_most
  - quantity_bound

budget_caps:
  max_objects_proposed:     6
  max_facets_emitted:       6
  max_constraints_emitted: 10
  max_merges:               0
  max_splits:               0
```

---

## Output: QuantityFacet

Attach to any object of kind `quantity`.

```
QuantityFacet fields used:
  - value:              number or symbolic expression
  - unit:               string (apples, dollars, meters, etc.)
  - is_exact:           true/false
  - derived_from_refs:  quantity object IDs this was computed from
```

---

## Output: Constraints

### `quantity_equals(Q_result, expression)`

Emit when a quantity is defined as equal to an expression.

```
{
  "constraint_type": "quantity_equals",
  "argument_refs": ["Q_alice_final", "Q_expr_5_minus_2"],
  "expression": "quantity(Q_alice_final) = quantity(Q1) - quantity(Q2)",
  "strength": "hard"
}
```

### `quantity_difference(Q_result, Q_minuend, Q_subtrahend)`

Preferred form when the specific operation is subtraction.

```
argument_refs order: [result, minuend, subtrahend]
```

### `quantity_sum(Q_result, Q_addend1, Q_addend2, ...)`

Result equals the sum of all argument quantities.

### `quantity_greater(Q_a, Q_b)`

Q_a > Q_b.

### `quantity_less(Q_a, Q_b)`

Q_a < Q_b.

---

## Arithmetic resolution

When all inputs to an arithmetic constraint are exact numeric values, the quantity specialist SHOULD resolve the arithmetic inline and set the result quantity's `value` directly.

```
if quantity_difference(Q_result, Q1, Q2):
  if Q1.value is exact numeric AND Q2.value is exact numeric:
    Q_result.value = Q1.value - Q2.value
    Q_result.is_exact = true
    mark constraint as resolved
  else:
    emit constraint with status = unresolved
    resolver handles it
```

This avoids unnecessary round-trips through the resolver for simple arithmetic.

---

## Unit tracking

Units must be tracked and propagated. Emitting a `quantity_difference` constraint without units is not sufficient — the result unit must be declared or inferred.

Rules:
- Same unit on both operands: result inherits unit
- Different units on operands: emit a `quantity_bound` constraint marking the result as unit-ambiguous until a converter is applied
- Unitless operands: result is unitless

---

## Contract test requirements

- Given `Alice had 5 apples. She gave Bob 2 apples.`:
  - Must emit Q1 with value=5, unit="apples"
  - Must emit Q2 with value=2, unit="apples"
  - Must emit `quantity_difference(Q_alice_final, Q1, Q2)` or `quantity_equals(Q_alice_final, "5-2")`
  - Must set Q_alice_final.value = 3 (inline resolution)
- Must not emit temporal or entity constraints
- All quantity facets must have `unit` set or explicitly `"unitless"`
- All emitted constraints must have `source_module: quantity`