traverse-framework / traverse-framework/registry
CREATIVE: Publish core.invoice-line-normalize (invoice line-item normalizer to schema)
- Dominant language
- Rust
- Stars
- 1
- Forks
- 1
- Avg merge
- 1h 17m
- Merged PRs (30d)
- 217
Description
## Why (creative vignette)
AP agents receive messy line items (free-text descriptions, mixed quantity fields). Creative ask: **normalize line items into a fixed invoice schema** (description, quantity, unit_price, currency, optional tax_code) with validation fail closed — agent proposes, capability accepts only schema-valid lines.
## Guardrails (required)
- Machine-readable contract
- Deterministic normalization rules OR fail-closed with explicit uncertainty — **no silent LLM invent of amounts**
- Tests + publish checklist
- Not a thin "LLM returns JSON string" wrapper
- Not a generic JSON util — must be invoice-line shaped
- Business domain
## One-PR ask
Publish **`core.invoice-line-normalize@1.0.0`**:
**Suggested contract:**
- Inputs: `raw_lines` array with loosely typed fields you document; frozen invoice line target schema (or embedded schema); `policy_version`
- Outputs: `lines` normalized array; `rejected` array of `{ "index", "reason_code" }`; `ok` (prefer fail closed for v1 money fields rather than silent partial money invent)
- Rules: coerce numeric strings with documented decimal policy; refuse currency mismatch; never invent missing unit_price
Creative freedom: B2B vs marketplace invoice vignettes OK within guardrails.
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 OCR / PDF invoice parsing pipelines
- General-purpose JSON reshape utilities
- Payment posting
## Done when
- CI green; published in next index
- Tests: happy normalize, reject missing price, currency conflict, quantity coerce
- Uncertainty/fail-closed behavior documented for ambiguous raw fields
## Host / deps notes
**Pure WASM** heuristics. If you add a model path for description cleanup only, amounts must still be deterministic/fail-closed and `ai` must be declared — prefer no model for v1.
## Labels
`help wanted` · `enhancement` · `no-spec-needed`
Contributor guide
Research direction
Start with CONTRIBUTING.md and capabilities/README.md, then inspect the documented scaffold or traverse-cli capability publish flow and the capability-src Rust test layout. Run bash scripts/ci/pre_pr_check.sh against the draft PR body and verify the published artifact retains its digest and URL, persona references resolve, coverage gates pass, and the required normalization and rejection cases are covered.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- bash, rust, wasm
- Domain
- backend-api-design, build-system, release
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100