Track 2 telco template: customer-impact swap (revenue × churn) + reviewer-feedback alignment

[cafzal]

Summary

Replaces PageRank-as-headline on CellTower.weighted_impact with a customer-impact weighting — Subscriber.customer_value = LTV × (1 + churn_risk_score) summed across STATUS == "ACTIVE" callers routed through each tower — keeping PageRank exposed alongside as weighted_pagerank for the secondary network-effect view. Stage 4's MIP objective is unchanged (still reads weighted_impact by name); only the measure underneath shifted.

Per-tower selection rationale added: every selected upgrade carries an operational / advisory/predicted / high-value tag answering the "…and why?" tail of an operator's framing question.

Aligns the template README + runbook with reviewer feedback on the Summit demo.

Why

The previous weighted_impact (sum of caller PageRank influence) answers a network-effects question, not the prioritization question a telco operator actually asks: "how much revenue / what SLA exposure sits behind this tower?" Reviewer feedback specifically flagged PageRank as missing the mark for a telco operator audience. Revenue × churn answers the operator question directly while keeping the graph reasoner's role intact.

Changes

Make the prioritization measure operator-credible

CellTower.weighted_impact now sums Subscriber.customer_value = LTV × (1 + churn_risk_score) over the ACTIVE callers routed through each tower — "how much revenue, weighted by churn risk, sits behind this tower?" The previous PageRank influence sum is retained as CellTower.weighted_pagerank for the secondary network-effect view. Stage 4's objective consumes weighted_impact by name; only the underlying measure shifted.

• Subscriber gains churn_risk_score, segment, status, and a precomputed customer_value
• Aggregation filters to STATUS == "ACTIVE" (excludes 24.5% suspended subs)
• weighted_pagerank is a sibling property; PageRank stays computed by the graph reasoner

Explain why each tower was picked

Every selected upgrade carries a rationale tag (operational / advisory/predicted / high-value) noting which upstream signal(s) drove inclusion, plus a rationale tally alongside the plan. Answers the "…and why?" an operator implicitly asks of the selected set.

Frame the demo honestly

README gains a Demo scope and caveats callout — synthetic-data shape, customer-impact scope (revenue + churn; SLA / strategic-corridor weighting deferred), enterprise concentration (~87% of customer-value from 50 ENT subs — realistic, with tuning knobs called out), and demo-vs-product framing. A notional source-system mapping table follows — OSS/NEM, EMS, NMS, CRM, mediation, vendor portals — typical operator integration sources. Runbook carries a parallel heads-up.

Latent bug surfaced by the swap

Binding-detection threshold lowered from 0.999 → 0.995. PageRank-era runs spent 99.96% of budget (cleared 0.999); customer-impact-weighted runs sit closer to 99.85% — still clearly budget-binding but was misreported as binding=none. New threshold handles both regimes.

Verified

Ran end-to-end against a real Snowflake-backed engine. GNN trained, MIP solved, 4 stages executed cleanly:

Selected upgrades: 27 across 5 regions
Total cost:               $4,992,276  (budget $5,000,000, binding)
Total install crew-weeks: 161         (budget 200, slack)
Capacity restored:        180 Gbps
Tier mix:                 {'BRONZE': 12, 'GOLD': 8, 'SILVER': 7}
Region breakdown:         {'SOUTH': 7, 'EAST': 6, 'WEST': 6, 'CENTRAL': 4, 'NORTH': 4}
Rationale tally: operational=2, advisory/predicted=27, high-value=17
                 (towers can fire on multiple signals)

vs. earlier PageRank-weighted runs (~36 towers, 207 Gbps, 17/15/4 tier mix, 194 install-weeks near-binding): the customer-value-weighted optimizer concentrates spend on fewer strategic towers with more GOLD share; install-weeks slack instead of near-binding. Top-10 subs by customer_value came out all ENTERPRISE_PREMIUM ($597K–$881K each) — confirms the enterprise-concentration caveat at runtime.

ruff check clean. py_compile clean. dev-templates-review post-change pass run; findings addressed in this PR (apologetic GNN-vs-SQL prose removed from README, runbook Section 6 response-density trimmed, chain-ASCII numbers refreshed, stage-number references in Section 7 prompt swapped for property names).

Out of scope (separate PRs)

• SLA tier extension — needs new SLA_TIER / is_emergency_service CSV fields
• Strategic-corridor weighting — needs new tower attribute
• Backhaul coupling constraint — gated on an engine-fit spike
• Full plan explainability — verbalized RestorePlanLine concept + Cortex agent
• Richer data model (vendor / sector / band / radio-unit) — separate data-gen rebuild
• Sharpened GNN-vs-SQL claim in template docs — dev-templates-review reclassified it as skill content, not customer-facing template README. Should land in the rai-predictive-modeling skill / agent dialogue instead.

[github-actions]

The docs preview for this pull request has been deployed to Vercel!

✅ Preview:	https://relationalai-docs-6snrmgvpi-relationalai.vercel.app/build/templates
🔍 Inspect:	https://vercel.com/relationalai/relationalai-docs/9Wgs8tZx3NZp4S1tQq7JqixZ7bqM