TorbatYar/docs/commercial-runtime-validation-report.md

# Commercial Runtime Validation Report — Wave-3

> **Validation only.** No implementation. No backend/API/product changes.  
> Date: 2026-07-28  
> Subject: Commercial Runtime Frontend Wave-2 vs Commercial Foundation `commercial.v1.2`  
> Inputs: project-status, commercial architecture/contracts, Wave-2 handover + snapshot, commercial module adapters (evidence)

---

## Executive verdict

**CONDITIONAL CERTIFICATION** — Commercial Runtime is **architecturally metadata-driven** for core catalogs (products, bundles, pricing, capabilities, assessment, recommendations) and **does not invent fake catalogs**. It is **not yet fully future-proof for zero React edits across every registry surface** (assets, extensions, automation, policies, metadata UI, notifications, search, marketplace readiness).

| Gate | Result |
| --- | --- |
| No fake catalogs | **PASS** |
| No hardcoded product/bundle lists in commercial path | **PASS** (legacy deprecated files remain but unused by Wave-2 path) |
| Bundles reference pricing only | **PASS** (contract + FE types use `pricing_refs`) |
| Domain policy before/after subscription | **PASS** |
| Ownership (Commercial orchestrates only) | **PASS** |
| Zero FE code for *any* future product deep-link | **FAIL / GAP** (`SERVICE_HUB_PATHS` routing map) |
| All listed surfaces dynamically driven | **PARTIAL** |
| No “coming soon” in commercial chrome | **FAIL** (Notifications disabled “به‌زودی”) |
| Core commercial APIs present | **FAIL** (graceful unavailable — expected) |

---

## 1. Dynamic Registry Validation

| Registry / surface | FE adapter? | Dynamic? | Admin→FE auto? | Notes |
| --- | --- | --- | --- | --- |
| Products | Yes (`/commercial/products` → Core `services`) | Yes | **When API or Core service row exists** | Names from backend; hub href may be null for unknown keys |
| Business Types | Via assessment schema only | Partial | When assessment schema includes types | No dedicated business-type adapter |
| Capabilities | Yes | Yes | Yes if registry/Core features | |
| Bundles | Yes (registry only) | Yes | Yes when `/commercial/bundles` exists | No FE fallback inventing bundles |
| Pricing references | Yes | Yes | Yes when pricing/plans exist | No invented amounts |
| Recommendations | Yes (POST) | Yes | When engine exists | Empty/unavailable otherwise — no fake scores |
| Feature Locks | Component exists | Partial | N/A | Used in domain policy; not universal on all hubs |
| Trial | Yes (subscription) | Yes | Via Core subscription | Quotas empty until usage APIs |
| Subscription banners | Yes | Yes | | |
| Apps launcher | Yes (`/apps`, dashboard, tenant site) | Yes | | |
| Dashboard cards | Dynamic products/checklist | Yes | | No Wave-1 dead “به‌زودی” cards |
| Sidebar | Dynamic products | Yes | | |
| Activation flow (UI) | Wizard transitions | Partial | | Event pipeline contracts not executed |
| Setup checklist | From discovered products | Yes | | Base workspace/brand/users steps fixed labels |
| Commercial dashboard | Yes | Yes | | |
| Header menus | Mostly static labels | Partial | Product list not in header | Nav labels hardcoded; destinations OK |
| Search indexes | **No** | No | Gap | |
| Notifications registration | **Shell only** | No | Gap | Disabled “به‌زودی” |
| Marketplace readiness | **No adapter** | No | Gap | Contract exists in foundation |
| Assets | **No adapter** | No | Gap | |
| Extensions | **No adapter** | No | Gap | |
| Automation Packs | **No adapter** | No | Gap | |
| Metadata | Field bag on types only | Partial | Gap | No metadata registry consumer UI |
| Policies | **No adapter** | No | Gap | |

---

## 2. Future Product Compatibility Matrix

Simulated products (Smart Locker, IoT Manager, Fleet AI, Warehouse, Video Surveillance, Rental, Insurance, Document Manager) and roadmap placeholders (QR, Short Links, Business Cards, Booking, Marketplace, Events, Learning, Ticketing, Storage, AI, future verticals):

| Scenario | Appear in catalog without FE edit? | Deep-link to hub without FE edit? | Bundle/recommend without FE edit? |
| --- | --- | --- | --- |
| Registered in `/api/v1/commercial/products` with `href` | **Yes** | **Yes** | **Yes** (if engine + bundles registry) |
| Registered only as Core `services` row | **Yes** (name/status) | **Only if** `service_key` already in `SERVICE_HUB_PATHS` or `href` later from commercial API | Bundles: only via commercial bundles API |
| Docs-only / not in any API | Shows empty — **correct** (no fake) | No | No |
| Future QR / Booking / Marketplace | No FE product code required | Hub routes may not exist yet — product can still list | Bundle refs only when Admin registers |

**Conclusion:** Catalog discovery is future-proof for **registry entries**. Navigation is future-proof only when **`href` (or equivalent) comes from the registry**, not when relying on the FE hub path map alone.

---

## 3. Commercial Flow Transition Check

| Transition | Status | Evidence |
| --- | --- | --- |
| Business Type → Assessment | **PASS*** | Schema-driven; unavailable → empty + continue |
| Assessment → Recommendations | **PASS*** | POST recommendations; no fake results |
| Recommendations → Bundle | **PASS*** | Bundle cards from registry; may be empty |
| Bundle → Workspace | **PASS** | Session + `/onboarding` |
| Workspace → Trial | **PARTIAL** | Billing can start trial via Core; not auto on complete |
| Trial → Commercial Dashboard | **PASS** | `/dashboard` commercial OS |
| Dashboard → Apps Launcher | **PASS** | `/apps` + sidebar |
| Feature Locks | **PARTIAL** | Domain lock yes; not all capabilities gated everywhere |
| Subscription | **PASS** | `/billing` |
| Custom Domain | **PASS** | Unlock only when `subscription_status === active` |
| Production | **PARTIAL** | Checklist exists; no formal production gate event |

\*Depends on Core commercial APIs being live for a rich path; empty path is intentional.

---

## 4. Domain / Bundle / License / Ownership

| Rule | Result |
| --- | --- |
| Before active sub: `*.torbatyar.ir` only | **PASS** |
| After active sub: custom domain unlocks | **PASS** |
| Bundles must not contain prices | **PASS** (`pricing_refs` only) |
| Pricing from Pricing Catalog / plans | **PASS** |
| License / Subscription / Entitlement / Feature / Capability separated | **PASS** (types + Core check API; no conflation in FE models) |
| Commercial owns orchestration only | **PASS** |
| Payment / Accounting / Experience / Identity ownership | **PASS** (no module edits; no ownership bleed) |

---

## 5. UI quality (commercial path)

| Check | Result |
| --- | --- |
| No dead dashboard cards | **PASS** (Wave-2 dashboard) |
| No scaffold commercial pages | **PASS** (empty states instead of fake) |
| No “coming soon” in commercial flow | **FAIL** — Notifications button disabled / به‌زودی |
| No broken primary nav | **PASS** (routes exist) |
| No fake statistics | **PASS** |
| No placeholder pricing amounts | **PASS** (amount null / “نامشخص”) |

---

## 6. Remaining Gaps

1. **Core Commercial Registry APIs** not implemented (`products`, `bundles`, `pricing`, `capabilities`, `assessment/schema`, `recommendations`, plus assets/extensions/automation/policies/metadata).
2. **FE adapters missing** for assets, extensions, automation packs, policies, marketplace readiness, search, notifications.
3. **`SERVICE_HUB_PATHS`** residual routing map — undermines strict “zero code for deep-links” unless registry supplies `href`.
4. **Notifications** shell violates no–coming-soon gate.
5. **Legacy** `frontend/lib/business-bundles.ts` / `apps-catalog.ts` deprecated but still present.
6. **Activation event pipeline** not consumed (contracts-only).
7. **FeatureLock** not applied universally across product hubs (Payment/Experience untouched by design).
8. **Admin Portal** commercial screens not implemented (spec only) — auto-consume requires Admin writing to registries/APIs first.

---

## 7. Required Core APIs (minimum for full certification)

| API | Purpose |
| --- | --- |
| `GET /api/v1/commercial/products` | Product registry (include `href` / nav metadata) |
| `GET /api/v1/commercial/bundles` | Bundle catalog (pricing_refs only) |
| `GET /api/v1/commercial/pricing` | Pricing catalog |
| `GET /api/v1/commercial/capabilities` | Capability registry |
| `GET /api/v1/commercial/assessment/schema` | Unlimited assessment questions / business types |
| `POST /api/v1/commercial/recommendations` | Rule engine |
| `GET /api/v1/commercial/assets` | Asset registry |
| `GET /api/v1/commercial/extensions` | Extension registry |
| `GET /api/v1/commercial/automation-packs` | Automation catalog |
| `GET /api/v1/commercial/policies` | Policy engine read models |
| `GET /api/v1/commercial/metadata?...` | Metadata bags |
| Usage/quota + notification feeds | Trial counters / Notifications |

---

## 8. Scores

| Score | Value | Rationale |
| --- | --- | --- |
| **Architecture Score** | **86 / 100** | ADR-023 / v1.2 aligned; ownership clean; incomplete registry consumers |
| **Future-proof Score** | **72 / 100** | Open product registry path strong; hub map + missing registries weaken guarantee |
| **Automatic Discovery Score** | **68 / 100** | Products/capabilities/pricing/bundles adapters present; half of foundation registries not wired |
| **Commercial Flow Score** | **78 / 100** | End-to-end UI path exists; trial auto-activation & event pipeline incomplete |

---

## 9. Commercial Runtime Certification

### Status: **CONDITIONALLY CERTIFIED**

**Certified for:**

- Metadata-first commercial UX architecture (Wave-2)
- No fake product/bundle/pricing catalogs
- Graceful fallback when commercial APIs absent
- Domain policy, subscription/trial banners, dynamic apps/sidebar/dashboard products
- Bundle pricing-ref separation and ownership boundaries

**Not fully certified for:**

- “Frontend requires ZERO code changes for *all* future products” without registry-supplied `href`
- Full dynamic coverage of Assets / Extensions / Automation / Policies / Metadata / Marketplace / Search / Notifications
- Production-complete activation event orchestration

**Re-certification path:** Ship Core commercial registry APIs (with nav `href`), add thin generic adapters for remaining registries, remove Notifications “coming soon”, eliminate or replace `SERVICE_HUB_PATHS` with registry href only → target **FULL CERTIFICATION**.

---

## STOP

Validation complete. No implementation performed. No backend or business-service modifications.

> **Update 2026-07-28:** Completion Wave-3 closed the documented gaps. See [commercial-runtime-validation.md](commercial-runtime-validation.md) and [commercial-runtime-final-report.md](commercial-runtime-final-report.md). Status: **COMMERCIAL RUNTIME COMPLETE**.