feat(model): numeric primitives (Price, Quantity, Side, ArithmeticError)

[NotAProfDev]

Summary

First real content for oath-model, the workspace root contract: the exact-domain numeric primitives Price (signed i128), Quantity (unsigned u128 magnitude), Side (Buy/Sell), and ArithmeticError. Checked const fn add/sub that error rather than wrap (ADR-0023), serde-derived (the universal bus bound, ADR-0002/0020/0027), and property-tested. Built spec → plan → TDD per the superpowers workflow.

Related Issue

Closes #50

Type of change

• Feature

Changes

• Add Price, Quantity, Side, and ArithmeticError — one module each, re-exported from lib.rs.
• Checked const fn checked_add/checked_sub with correct signed/unsigned overflow→Overflow/Underflow mapping; no bare arithmetic operators exposed.
• Unit + proptest tests: raw round-trip, add/sub inverse, i128::MIN/MAX and u128::MAX boundaries, serde_json round-trip over the full numeric range; plus doctests.
• Manifest reconciliation: drop rust_decimal/uuid/time; add proptest/serde_json dev-deps; remove the now-empty cargo-machete ignore block.
• Ignore cargo-mutants output (mutants.out*/).
• Spec + plan under docs/superpowers/; CHANGELOG.md entry.

Checklist

• just ci passes locally (fmt + lint + test + deny + doc + …)
• Tests added or updated
• Documentation updated (rustdoc + spec/plan)
• CHANGELOG.md updated
• This PR introduces no breaking changes (pre-release crate, first content)

Mutation testing note

just mutants-diff: 13 caught, 2 surviving. Both survivors are provably equivalent mutants — the Price overflow-guard boundary (self.0 > 0 / rhs.0 < 0) is unreachable when the operand is 0 (addition/subtraction can't overflow against 0), so >/>= and </<= are behaviorally identical. Independently verified via an exhaustive i8 overflow sweep. Left as-is rather than contorting correct, clear code.

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features
  • Introduced numeric primitives for prices and quantities, plus a buy/sell direction type.
  • Added checked arithmetic APIs that return explicit overflow/underflow errors.
  • Enabled serialization/deserialization support for the new model types.
• Documentation
  • Added release and design documentation describing intended behavior and invariants.
• Tests
  • Expanded unit and property-based coverage for arithmetic, error behavior, and serialization.
• Chores
  • Updated build/output ignore rules and refreshed the model’s dependency setup.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 898231af-bdce-40b7-b2b7-f7fa0f44cca4

📥 Commits

Reviewing files that changed from the base of the PR and between dc30ae8 and 58e5b8e.

📒 Files selected for processing (1)

• crates/model/src/side.rs

🚧 Files skipped from review as they are similar to previous changes (1)

• crates/model/src/side.rs

---

📝 Walkthrough

Walkthrough

Adds four oath-model primitives: Price, Quantity, Side, and ArithmeticError. The crate now exposes checked const fn arithmetic, serde support, manifest updates for testing dependencies, and new design and implementation documentation.

oath-model Numeric Primitives

Layer / File(s)	Summary
Manifest and dependency reconciliation Cargo.toml, crates/model/Cargo.toml, .gitignore, CHANGELOG.md	Updates workspace and crate dependency declarations, adds a mutants output ignore rule, and records the slice in the changelog.
ArithmeticError enum crates/model/src/error.rs, crates/model/src/lib.rs	Defines ArithmeticError and wires the crate root to re-export it with the numeric primitive modules and crate docs.
Side enum and opposite method crates/model/src/side.rs	Defines Side with Buy/Sell, serde support, and opposite, with unit and property tests.
Quantity newtype and checked arithmetic crates/model/src/quantity.rs	Defines Quantity as a u128 newtype with checked arithmetic and serde-backed tests.
Price newtype and checked arithmetic crates/model/src/price.rs	Defines Price as an i128 newtype with checked arithmetic, ordering semantics, and serde-backed tests.
Design spec and implementation plan docs/superpowers/specs/..., docs/superpowers/plans/...	Adds the numeric primitives design spec and step-by-step implementation plan documents.

Changes

oath-model Numeric Primitives

Layer / File(s)	Summary
Manifest and dependency reconciliation Cargo.toml, crates/model/Cargo.toml, .gitignore, CHANGELOG.md	Updates workspace and crate dependency declarations, adds a mutants output ignore rule, and records the slice in the changelog.
ArithmeticError enum crates/model/src/error.rs, crates/model/src/lib.rs	Defines ArithmeticError and wires the crate root to re-export it with the numeric primitive modules and crate docs.
Side enum and opposite method crates/model/src/side.rs	Defines Side with Buy/Sell, serde support, and opposite, with unit and property tests.
Quantity newtype and checked arithmetic crates/model/src/quantity.rs	Defines Quantity as a u128 newtype with checked arithmetic and serde-backed tests.
Price newtype and checked arithmetic crates/model/src/price.rs	Defines Price as an i128 newtype with checked arithmetic, ordering semantics, and serde-backed tests.
Design spec and implementation plan docs/superpowers/specs/..., docs/superpowers/plans/...	Adds the numeric primitives design spec and step-by-step implementation plan documents.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title follows Conventional Commits and clearly describes the main change in the PR.
Linked Issues check	✅ Passed	The PR implements the four numeric primitives, checked arithmetic, serde, tests, and manifest updates required by #50.
Out of Scope Changes check	✅ Passed	The extra doc, changelog, and ignore-file updates are aligned with the linked issue's implementation plan and verification needs.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/oath-model-numeric-primitives

---

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