traverse-framework / traverse-framework/registry

Publish capability: core.quote-with-caps (formula pricing quote with hard caps)

Open
#495 0 comments 0 reactions 0 assignees View on GitHub
enhancement good first issue help wanted no-spec-needed
Dominant language
Rust
Stars
1
Forks
1
Avg merge
1h 17m
Merged PRs (30d)
217

Description

## Why

`core.calculate-price` covers line × unit_price + optional discount/tax. Quoting engines also need **hard min/max caps and simple formula knobs** (e.g. base + per-unit, then clamp) so an agent cannot invent an uncapped price. This is a small, deterministic **quote-with-caps** companion — not a rewrite of `core.calculate-price`.

## One-PR ask

Publish **`core.quote-with-caps@1.0.0`**:

**Inputs:**
- `quantity`: number (≥ 0)
- `formula`: `{ "base": number, "per_unit": number, "currency": string }` (currency code string; no FX)
- `caps`: `{ "min_total"?: number, "max_total"?: number }` (if both set, require min ≤ max or fail closed)
- `config_version`: string

**Outputs:**
- `currency`: string
- `subtotal`: number (base + quantity * per_unit, before clamp)
- `total`: number (after clamp)
- `capped`: boolean
- `cap_applied`: `"none"|"min"|"max"`
- `config_version`: string
- `ok`: boolean
- `reason_code`: enum e.g. `ok` | `invalid_quantity` | `invalid_caps` | `invalid_formula`

**Behavior:** Deterministic arithmetic. Document rounding (e.g. round half-even to 2 decimal places for money-like numbers, or integer millis — pick one and lock tests). No tax/discount matrix (that's `core.calculate-price`).

Follow [`CONTRIBUTING.md`](https://github.com/traverse-framework/registry/blob/main/CONTRIBUTING.md) and [`capabilities/README.md`](https://github.com/traverse-framework/registry/blob/main/capabilities/README.md) publish checklist.

- Include `capability-src/` with real Rust tests meeting registry coverage gates (`functions` 100%, lines/regions ≥ 95%)
- Use `traverse-cli capability publish` (or the documented scaffold) so `artifact.digest` / `artifact.url` survive
- Declare `authoring.method` (`human` or `llm-assisted`)
- Ensure every `use_cases[].persona_ref` resolves (scaffold personas if needed)
- Run `bash scripts/ci/pre_pr_check.sh ` before opening
- One capability per PR; branch from `origin/main`, not another `publish/*` branch

**Apps are not ready — publish the capability only.** No app wiring, no demo product surface.

## Out of scope

- Full discount/tax engines (use / extend patterns from `core.calculate-price` instead)
- FX conversion, coupon catalogs, or cart state
- Host-persisted pricing config (`commerce.pricing-config` already exists)

## Done when

- CI green; published in next index
- Tests: uncapped, hit min, hit max, invalid caps fail closed, quantity 0

## Host / deps notes

**Pure WASM.** No connector, no network. Distinct id from `core.calculate-price`.

## Labels

`help wanted` · `good first issue` · `enhancement` · `no-spec-needed`

Contributor guide

Open the contributing guide

Research direction

Read CONTRIBUTING.md, capabilities/README.md, and the existing core.calculate-price patterns first. Use the documented scaffold or traverse-cli capability publish, add capability-src/ with Rust tests for uncapped, minimum, maximum, invalid-cap, and zero-quantity cases, and lock the chosen rounding behavior in tests. Run bash scripts/ci/pre_pr_check.sh against the draft PR body and confirm the published artifact metadata and persona references pass the registry checks.

Written by the indexing model from the issue text.

Assessment

Tech stack
rust, wasm
Domain
backend-api-design, release, testing
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
68/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.