CAM / sales-agent handoff pack — interop contract

The handoff pack is the bundle a producer gives a collection account manager (CAM) or sales agent at engagement onset. It is the outbound half of a two-way seam whose inbound half already exists (transparency-import.php → revenue_ledger). The pack tells the counterpart what rights exist, the recoupment order to apply, who to pay, and — section 9 — the exact statement format to report revenue back in, so their statements ingest with zero manual remapping.

Where it lives

• Generate / dispatch: handoff-pack.php?project=<id> — recipient picker (reuses spub_eligible_recipients), plus &download=pdf / &download=json for the raw artifacts. Linked from project-rights.php.
• Assembly: lib/handoff_pack.php — hp_collect() is pure read over the Cearta libs; hp_pdf_generate() / hp_json() render the two artifacts; hp_publish() dispatches via send_mail with both attached and records the audit in the sales_publications ledger (mig 157) tagged format = 'handoff-pack'.
• No migration — the audit rides the existing sales-publication tables.

What's in the pack (outbound)

1. Project header (title, stage, type, territory, primary currency)
2. Chain of title — what the producer can grant (chain_of_title)
3. Rights windows / avails map — territory × media × window, sold vs available (rights_windows)
4. Distribution arrangements + per-window fee schedules (distribution_arrangements / distribution_fees)
5. Pre-sales / territorial deals (project_presales)
6. Recoupment schedule — the waterfall definition, i.e. the order to apply (waterfall_tiers); not a computed run
7. Payee register — net-profit participants + pool shares (net_profit_participants)
8. Residual obligations — ongoing payee duties (residual_obligations)
9. Return-statement spec — see below

Return-statement spec (inbound contract)

This is the inverse of lib/transparency_imports.php. A CAM/agent that names columns per this spec produces statements transparency-import.php auto-maps into revenue_ledger with no manual review.

• Transport: CSV or XLSX, one row per (period × territory × exploitation type).
• Target fields (TI_TARGET_FIELDS): period_start, period_end, exploitation_type, territory, gross, commission, net, notes.
• Recognised column aliases are drawn live from TI_PROVIDER_PROFILES['other'] so the spec never drifts from the parser (e.g. gross receipts / gross → gross; country / region → territory; fee → commission; remitted / net receipts → net).
• Send gross + commission and Togra derives net, or send net directly. Dates ISO-8601; currency symbols/separators are stripped on import.

Once those statements are imported, revenue_ledger feeds the net_profits waterfall, sales_report, and the Transparency reports — Article 19 / S.I. 567/2021 (Art 19) — closing the loop on verified numbers.

Related

• Transparency reports — Article 19 / S.I. 567/2021 — Art 19 reports run off the same revenue_ledger the CAM's statements populate
• Net profits — the calculation basis — the waterfall whose definition the pack exports
• Recoupment Corridor · Residual obligations