Owner review required
This spec page requires owner review before public visibility. Trace schema and sample renderings are ready for review.
Intent Capture, Assisted Commerce & Decision Trace
Three-audience rendering of every pipeline decision: developer JSON for debugging, merchant ops table for config review, buyer card for purchase UX. The trace is a pure derivation of the DecisionRecord — it transforms, never augments.
Section 1 — Decision Trace
The UCP pipeline (evaluateOffer) produces a DecisionRecord — a complete substrate containing every reason code emitted, every stage result, and provenance metadata. RAOS-0013 §1 defines how to render that substrate for three distinct audiences.
| Audience | Function |
|---|---|
| Developer | renderDeveloperTrace(trace) |
| Merchant | renderMerchantTrace(trace) |
| Buyer | renderBuyerTrace(trace) |
Developer trace
Full DecisionTrace serialized as JSON with alphabetically sorted keys at every nesting level. Round-trip safe: parse → re-render === original. The traceSchema field carries the version ("1.0.0").
Merchant trace
Only BLOCK and CONDITION reasons are shown — INFO reasons are too noisy for an ops view. Each row includes an actionHint derived from a hardcoded lookup table (no LLM; deterministic). A PASS row is returned when there are no actionable reasons.
| Stage | Status | Code | Message | Action Hint |
|---|---|---|---|---|
| ELIGIBILITY | BLOCK | TIER_RESTRICTION | This item requires gold membership tier. | Review eligibilityRules.requiredTier in your catalog config |
Buyer trace
At most four fields: canPurchase, headline, detail (optional), and nextStep (optional). The deny-list (§1.3) is enforced by construction and unit-tested.
Buyer audience deny-list (§1.3)
These fields must never appear in renderBuyerTrace output. Enforcement: construction + unit tests (JSON.stringify(result) must not contain any of these as JSON object keys).
traceSchema versioning
The traceSchema field on DecisionTrace carries the version of the trace shape (currently '1.0.0'). Consumers should parse this field before reading any other fields. Additive field additions are compatible within the same major version (RAOS-0000 §7.4 policy). Breaking removals or renames bump the major version.
Section 2 — Intent Capture & Routing
Planned — WP-14
When checkout is not the outcome, the agent needs an action vocabulary: out-of-stock notify-me, B2B quote request, WhatsApp/lead-form routing, wishlist. The full intent capture and routing contract will be defined in WP-14. See MASTER-BUILD-PLAN.md WP-14 brief.
Changelog
| Version | Date | Notes |
|---|---|---|
| 0.1.0 | June 2026 | Decision trace section (WP-08). Intent capture routing — planned WP-14. |