@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/finance-mart/cac-payback.md

@@ -0,0 +1,113 @@
+# Finance Mart CAC Payback Manifest
+
+**Status:** authoritative for finance-mart v2.0.x
+**Date:** 2026-05-19
+**Owner:** finance
+**Sub-section:** cac_payback
+**Related:** finance-mart README §4.6, 2026-05-19-finance-100-percent-deployment-decisions (Decisions 1 and 2: CAC cost decomposition and payback definition/granularity), 2026-05-19-platform-mart-round-status-and-next-silver-asks (Round 6 cac_per_first_lock wiring), 2026-05-19-platform-revenue-silver-wiring-landed (Round 7 canonical 4-class source_class enum)
+
+## Purpose
+
+This manifest defines the `cac_payback` sub-section in the finance gold section. The sub-section answers: what does it cost to acquire a customer, and how long does the customer take to pay back that cost?
+
+CAC composes Growth attribution silver with Sales journey silver (specifically `sales.lead_stage_history` for first-lock counts). Payback composes CAC with per-customer cumulative gross margin. Both are cohort-grain metrics, keyed by `(org_market_id, intake_cohort_week)`.
+
+## Served sub-section
+
+`GET /api/mart/sections/finance` exposes this sub-section at `groupings.cac_payback`. Three metrics: `cac` (with `cac_per_first_lock` as the source-class-split form Platform wired in Round 6), `cac_payback_weeks`, `payback_distribution`.
+
+## Served columns
+
+### `cac` / `cac_per_first_lock__<source_class>`
+
+Grain: one row per `(org_market_id, intake_cohort_week)` for the aggregate `cac`; one row per `(org_market_id, intake_cohort_week, source_class)` for the source-class split form `cac_per_first_lock__<source_class>`.
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `org_market_id` | string | yes | spine | |
+| `intake_cohort_week` | string | yes | sales journey | ISO week, the cohort key. |
+| `source_class` | string enum or null | conditional | revenue ad-spend-reconciled | Required on split metric; null on aggregate `cac`. One of `paid_social`, `paid_search`, `direct`, `other`. |
+| `total_acquisition_cost_cents` | integer or null | yes | finance composition | Numerator: marketing + sales-SDR cost attributable to the cohort. |
+| `first_lock_count` | integer or null | yes | sales.lead_stage_history | Denominator: cohort first-lock count. |
+| `cac_cents` | integer or null | yes | finance composition | `total_acquisition_cost_cents / first_lock_count`. |
+| `_cac_cost_decomposition` | string | yes | finance composition | `marketing_plus_sales_sdr`. |
+| `null_reason` | string or null | yes | finance composition | `null:upstream_unavailable` while Sales SDR allocation silver pending; `null:insufficient_data` below cohort floor of 5 first-locks. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | |
+
+Policy: `_cac_cost_decomposition: marketing_plus_sales_sdr`. Rollup rule: `weighted_mean_by_cohort_size`.
+
+### `cac_payback_weeks`
+
+Grain: one row per `(org_market_id, intake_cohort_week)`.
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `org_market_id` | string | yes | spine | |
+| `intake_cohort_week` | string | yes | sales journey | Cohort key. |
+| `weeks_to_payback` | integer or null | yes | finance composition | First week W where cumulative gross margin per cohort customer ≥ `cac_cents`. |
+| `_payback_definition` | string | yes | finance composition | `cumulative_gross_margin_geq_cac`. |
+| `null_reason` | string or null | yes | finance composition | `null:insufficient_observation_window` for cohorts that haven't paid back yet but are observable. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | |
+
+Policy: `_payback_definition: cumulative_gross_margin_geq_cac`. Rollup rule: `weighted_mean_by_cohort_size`.
+
+### `payback_distribution`
+
+Grain: one row per `(org_market_id, intake_cohort_week, payback_month_bucket)`.
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `org_market_id` | string | yes | spine | |
+| `intake_cohort_week` | string | yes | sales journey | |
+| `payback_month_bucket` | string | yes | finance composition | `M1` through `M24+` per `_payback_bucket_granularity: monthly`. |
+| `cohort_share_bps` | integer | yes | finance composition | Basis points of the cohort that paid back within this bucket. |
+| `_payback_bucket_granularity` | string | yes | finance composition | `monthly`. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | |
+
+Policy: `_payback_bucket_granularity: monthly`, `_payback_definition: cumulative_gross_margin_geq_cac`. The bucket dimension is dimensional, not summed.
+
+## Source silver columns
+
+| Silver object | Target column | Used for | Required |
+|---|---|---|---:|
+| Revenue `/api/v1/silver/ad-spend-reconciled` | `ad_spend_cents`, `source_class`, `week`, `org_market_id` | CAC numerator (marketing slice) | yes |
+| `sales.lead_intake` (or equivalent) | `intake_week`, `customer_id`, `org_market_id` | cohort identity | yes |
+| `sales.lead_stage_history` | first-lock event per customer | denominator | yes |
+| `sales.sdr_time_allocation` (or equivalent) | per-cohort SDR cost allocation | CAC numerator (sales-SDR slice) | yes (Sales-side commitment, may be pending) |
+| `revenue.revenue_recognition` | per-customer cumulative recognized revenue | payback observation | yes |
+| `coaching.coach.lesson_rate`, `coaching.coach.travel_comp`, `delivery.lesson_event` | per-customer cumulative gross margin (revenue minus cost-of-service) | payback definition | yes |
+| spine | `org_market_id` resolution | grain key | yes |
+
+## Composition rule
+
+`cac_cents`:
+
+1. Sum `ad_spend_cents` from the Revenue `ad-spend-reconciled` endpoint over weeks falling within `intake_cohort_week`'s attribution window, per `(org_market_id, source_class)`. Filter to acquisition source classes (`paid_social`, `paid_search`); `direct` and `other` excluded.
+2. Add Sales SDR-time allocation per cohort from `sales.sdr_time_allocation` (denominator: weeks × SDR-hours-per-week × SDR-rate-per-hour, attributed to the cohort).
+3. Sum to `total_acquisition_cost_cents`.
+4. Read `first_lock_count` from `sales.lead_stage_history` for the cohort.
+5. If `first_lock_count >= 5`, return `total_acquisition_cost_cents / first_lock_count`; otherwise emit `null:insufficient_data`.
+
+`weeks_to_payback`:
+
+1. For each cohort customer, walk weekly cumulative gross margin = sum of (recognized revenue − cost-of-service) per customer per week since intake.
+2. For each cohort, find the earliest week W where average per-customer cumulative gross margin ≥ `cac_cents`.
+3. Return W − intake_cohort_week as `weeks_to_payback`. If no week W is reached within the observation window, emit `null:insufficient_observation_window`.
+
+`payback_distribution.cohort_share_bps[Mk]`:
+
+1. Per cohort, count customers whose cumulative gross margin reaches `cac_cents` within month bucket Mk (M1 = first 4 weeks, M2 = weeks 5-8, ..., M24+ = beyond 24 months).
+2. Return `round(count_in_bucket / total_cohort_size × 10000)` as basis points per bucket.
+
+## Reconciliation tolerance
+
+- `ad_spend_cents` numerator slice reconciles to the Revenue `ad-spend-reconciled` silver with tolerance `0` cents.
+- Sales SDR-time allocation reconciles to `sales.sdr_time_allocation` with tolerance `0` cents once that silver lands.
+- `first_lock_count` reconciles to `sales.lead_stage_history` with tolerance `0`.
+- Cumulative gross margin per customer reconciles to the same Revenue + Coaching + Delivery composition the `margin` sub-section uses; tolerance `0` cents.
+- The derived ratios (`cac_cents`, `weeks_to_payback`, `cohort_share_bps`) have no external reconciliation target.
+
+## Known gaps
+
+- **Sales SDR-time allocation silver is the outstanding gate** for the full CAC numerator. Today's Round 6 wiring of `cac_per_first_lock` uses marketing-only CAC (the `ad-spend-reconciled` slice); the marketing+sales-SDR form requires Sales to expose SDR allocation per cohort. Per Finance's `2026-05-19-finance-round-6-next-silver-asks-response` ask 3, Sales confirms whether the cohort-triangle silver carries SDR allocation; if not, Finance falls back to marketing-only CAC and supplements via a registry edit memo.
+- **`cac_payback_weeks` and `payback_distribution`** stay at `null:upstream_unavailable` until cumulative gross margin per cohort customer is composable (gates on the same cost-of-service silver as `gross_margin` and `pnl_summary`, all of which are now live per Revenue's pushback routing).

package/contracts/finance-mart/cash-position.md

@@ -0,0 +1,98 @@
+# Finance Mart Cash Position Manifest
+
+**Status:** authoritative for finance-mart v1.0.0
+**Date:** 2026-05-18
+**Owner:** finance
+**Grouping:** cash_position
+**Related:** finance-mart README section 4.5, warehouse-silver v1.1.0, 2026-05-17-revenue-finance-mart-contract-reply
+
+## Purpose
+
+This manifest defines the `cash_position` grouping in the finance gold section. The grouping answers: what cash position does the business hold as of a reporting date, by Organization and Market?
+
+This is a cash-event reporting surface, not a bank-statement contract. It composes from Revenue's authoritative payment, refund, reservation, and credit ledger facts. If provider settlement data later becomes authoritative, that lands as an additive manifest revision or a minor contract change depending on the served surface.
+
+## Served grouping
+
+`GET /api/mart/sections/finance` exposes this grouping at `groupings.cash_position`.
+
+The grouping grain is one row per:
+
+- `reporting_date`
+- `organization_id`
+- `market_id`
+
+`org_market_id` is the stable mart coordination key for the Organization and Market pair.
+
+## Served columns
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `reporting_date` | date string | yes | finance request or materialization date | As-of date for the position. |
+| `organization_id` | string | yes | spine | Platform Organization ID for the discipline. |
+| `organization_slug` | string | yes | spine | Stable display slug for the Organization. |
+| `market_id` | string | yes | spine | Platform Market ID. |
+| `market_slug` | string | yes | spine | Stable display slug for the Market. |
+| `org_market_id` | string | yes | `OrgMarket.slug` | Stable mart key for the Organization and Market pair. |
+| `cash_received_cents` | integer | yes | `revenue.order.amount_paid_cents` | Paid orders with `paid_at` on or before `reporting_date`. |
+| `cash_refunded_cents` | integer | yes | `revenue.refund_item.amount_cents` | Refund cash out with `refunded_at` on or before `reporting_date`. |
+| `net_cash_cents` | integer | yes | finance composition | `cash_received_cents - cash_refunded_cents`. |
+| `reserved_credit_liability_cents` | integer | yes | `revenue.credit_reservation` and `revenue.credit_ledger` | Credits reserved against locks and not yet earned, released, forfeited, or refunded. |
+| `unearned_credit_balance_cents` | integer | yes | `revenue.credit_ledger` | Purchased credits not yet recognized, refunded, forfeited, or adjusted away. |
+| `cash_in_transit_cents` | integer | yes | `revenue.credit_reservation.funding_status`, payment status fields | Cash expected from provider or funding flow but not confirmed. |
+| `refunds_in_transit_cents` | integer | yes | refund status fields | Refund cash out initiated but not confirmed. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | Refresh point of the materialized grouping. |
+
+## Source silver columns
+
+The implementation reads the Revenue silver face with these source-backed conformed columns:
+
+| Silver object | Silver column | Required | Use |
+|---|---|---:|---|
+| `revenue.order` | `order_id` | yes | Cash receipt row identity. |
+| `revenue.order` | `person_id` | yes where source row is person-related | Join to the spine. |
+| `revenue.order` | `amount_paid_cents` | yes | Cash received. |
+| `revenue.order` | `paid_at` | yes | Cash receipt date. |
+| `revenue.order` | `payment_status` | yes | Distinguish paid, pending, failed, and reversed states where source-backed. |
+| `revenue.order` | `provider_reference` | yes when source-backed | Variance explanation and provider tie-back. |
+| `revenue.refund_item` | `refund_item_id` | yes | Refund row identity. |
+| `revenue.refund_item` | `person_id` | yes where source row is person-related | Join to the spine. |
+| `revenue.refund_item` | `amount_cents` | yes | Cash refunded. |
+| `revenue.refund_item` | `refunded_at` | yes | Refund date. |
+| `revenue.refund_item` | `refund_status` | yes | Distinguish confirmed and in-transit refunds. |
+| `revenue.credit_reservation` | `credit_reservation_id` | yes | Reserved credit obligation identity. |
+| `revenue.credit_reservation` | `person_id` | yes where source row is person-related | Join to the spine. |
+| `revenue.credit_reservation` | `funding_status` | yes | `PENDING_FUNDING`, `FUNDED`, `REFUNDING`, `REFUNDED`, or equivalent conformed values. |
+| `revenue.credit_reservation` | `reserved_amount_cents` | yes if source-backed | Reserved liability amount. |
+| `revenue.credit_ledger` | `credit_ledger_entry_id` | yes | Ledger movement identity. |
+| `revenue.credit_ledger` | `person_id` | yes where source row is person-related | Join to the spine. |
+| `revenue.credit_ledger` | `type` | yes | Movement classification. |
+| `revenue.credit_ledger` | `delta_credits` | yes | Credit movement. |
+| `revenue.credit_ledger` | `amount_cents` | yes if source-backed | Money-denominated movement. |
+| `revenue.credit_ledger` | `occurred_at` | yes | Ledger movement date. |
+
+If Revenue silver carries credit quantities but not a money-denominated `amount_cents` for ledger movements, Finance may compute unearned credit liability only where the purchase price basis is source-backed through order items or credit purchase records. Otherwise that figure must surface a gap in reconciliation.
+
+## Composition rule
+
+For each grouping row:
+
+`cash_received_cents = sum(amount_paid_cents where paid_at <= reporting_date and payment_status is confirmed paid)`
+
+`cash_refunded_cents = sum(amount_cents where refunded_at <= reporting_date and refund_status is confirmed refunded)`
+
+`net_cash_cents = cash_received_cents - cash_refunded_cents`
+
+`reserved_credit_liability_cents` includes funded credit reservations that have not moved to earned, released, forfeited, or refunded outcomes by the reporting date.
+
+`unearned_credit_balance_cents` is the money-denominated balance of purchased credits that remain unearned as of the reporting date.
+
+`cash_in_transit_cents` and `refunds_in_transit_cents` are status-specific explanatory figures. They do not change `net_cash_cents` until the source marks the cash movement confirmed.
+
+## Reconciliation tolerance
+
+Confirmed cash receipt and refund figures reconcile to Revenue with a tolerance of `0` cents. In-transit and unearned-credit figures reconcile to Revenue's status and ledger facts with a tolerance of `0` cents once the required source-backed money amount exists.
+
+## Known gaps
+
+Provider settlement state is not part of this v1.0.0 manifest. The grouping reports cash based on Revenue's confirmed payment and refund facts, not on external bank settlement. If settlement reporting becomes required, Finance will file a finance-mart change rather than overloading this manifest.

package/contracts/finance-mart/cohort-summary.md

@@ -0,0 +1,72 @@
+# Finance Mart Cohort Summary Manifest
+
+**Status:** authoritative for finance-mart v2.0.x (proposed sub-section pending Platform §8 spec text confirmation)
+**Date:** 2026-05-19
+**Owner:** finance
+**Sub-section:** cohort_summary
+**Related:** finance-mart README §4.9, 2026-05-19-finance-cohort-panel-financial-columns-position (Finance's option-2 position), 2026-05-19-portfolio-mart-scope-resolution-path-1-accepted (Portfolio's cohort_funnel_panel v1.2 commitment for the non-financial columns), 2026-05-19-platform-finance-round-6-three-asks-confirmations (Platform's encoding flexibility on cohort_summary placement)
+
+## Purpose
+
+This manifest defines the `cohort_summary` sub-section in the finance gold section. The sub-section answers: what is the per-cohort cumulative revenue (earned and paid) at each current week since intake, sliced by org_market?
+
+The sub-section exists because Portfolio's `cohort_funnel_panel` (v1.2 in portfolio-mart) cannot serve `revenue_earned` and `revenue_paid` columns per portfolio-mart §4.4's no-financial-metrics rule. The Them OS spec §9 `cohort_cross_domain_panel` calls for both non-financial and financial columns at the same cohort grain; Portfolio serves the non-financial slice, Finance serves the financial slice via this sub-section. The Them OS caller joins Portfolio's `cohort_funnel_panel` to Finance's `cohort_summary` on `(org_market_id, intake_cohort_week, current_week)` to assemble the full §9 panel.
+
+If Platform reads the §8 spec text as placing cohort-grain financial views inside `unit_economics` instead of as a separate sub-section, this manifest migrates under `unit-economics.md` in a v2.0.x patch and `cohort-summary.md` retires. Finance's option-2 position from `2026-05-19-finance-cohort-panel-financial-columns-position` and Platform's flexibility from `2026-05-19-platform-finance-round-6-three-asks-confirmations` both allow either placement; this manifest is the separate-sub-section form.
+
+## Served sub-section
+
+`GET /api/mart/sections/finance` exposes this sub-section at `groupings.cohort_summary`. Two metrics: `revenue_earned_by_cohort` and `revenue_paid_by_cohort`.
+
+## Served columns
+
+Grain: one row per `(org_market_id, intake_cohort_week, current_week)`.
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `org_market_id` | string | yes | spine | |
+| `intake_cohort_week` | string | yes | sales journey | ISO week, the cohort key. |
+| `current_week` | string | yes | finance composition | ISO week, the observation point. |
+| `weeks_since_intake` | integer | yes | finance composition | `current_week − intake_cohort_week` in weeks. |
+| `cohort_size` | integer | yes | sales.lead_stage_history | Distinct customers in the cohort with first-lock by `current_week`. |
+| `revenue_earned_cents` | integer or null | yes | revenue silver | Cumulative GAAP earned revenue for the cohort from `intake_cohort_week` through `current_week`. |
+| `revenue_paid_cents` | integer or null | yes | revenue silver | Cumulative cash revenue for the cohort from `intake_cohort_week` through `current_week`. |
+| `null_reason` | string or null | yes | finance composition | `null:upstream_unavailable` for cohorts preceding the silver face's earliest observation. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | |
+
+Rollup rule: `sum` (cumulative revenue is additive across geography).
+
+## Source silver columns
+
+| Silver object | Target column | Used for | Required |
+|---|---|---|---:|
+| `sales.lead_stage_history` | first-lock event per customer | cohort identity and size | yes |
+| `revenue.revenue_recognition` | `recognized_amount_cents`, `recognition_period`, `customer_id`, `org_market_id` | revenue_earned_cents per cohort customer | yes |
+| `revenue.orders` (or equivalent) | `amount_paid_cents`, `paid_at`, `customer_id`, `org_market_id` | revenue_paid_cents per cohort customer | yes |
+| spine | `org_market_id`, `customer_id` to `person_id` resolution | grain and join keys | yes |
+
+## Composition rule
+
+For each row at `(org_market_id, intake_cohort_week, current_week)`:
+
+1. Identify cohort customers: distinct `customer_id` rows from `sales.lead_stage_history` with their first-lock in `intake_cohort_week` at `org_market_id`. Cohort size as of `current_week` counts customers whose first-lock landed at or before `current_week`.
+2. `revenue_earned_cents` = sum of `recognized_amount_cents` from `revenue.revenue_recognition` for cohort customers where `recognition_period` falls between `intake_cohort_week` and `current_week`.
+3. `revenue_paid_cents` = sum of `amount_paid_cents` from `revenue.orders` for cohort customers where `paid_at` falls between `intake_cohort_week` and `current_week`.
+4. The two figures are cumulative since intake, not per-period; consumers compute per-period deltas client-side by subtracting consecutive `current_week` rows.
+
+## Join with Portfolio's `cohort_funnel_panel`
+
+The Them OS caller assembles the full §9 panel by joining Portfolio's `cohort_funnel_panel` to this sub-section on `(org_market_id, intake_cohort_week, current_week)`. Portfolio serves: `intake_count`, `first_lock_count`, `completed_lessons_count`, `status_as_of_now`. Finance serves: `revenue_earned_cents`, `revenue_paid_cents`. The caller-side join produces the §9 row shape end-to-end.
+
+Cohort identity (the join key `intake_cohort_week`) is derived consistently across both sub-sections from `sales.lead_stage_history`; both Portfolio and Finance compute the cohort from the same Sales silver. No identity drift expected; if a divergence is observed in production, it's a Sales silver consistency issue, not a Finance or Portfolio composition issue.
+
+## Reconciliation tolerance
+
+- `revenue_earned_cents` reconciles to `revenue.revenue_recognition` filtered to cohort customers, with tolerance `0` cents.
+- `revenue_paid_cents` reconciles to `revenue.orders.amount_paid_cents` filtered to cohort customers, with tolerance `0` cents.
+- `cohort_size` reconciles to `sales.lead_stage_history` with tolerance `0`.
+
+## Known gaps
+
+- **The sub-section is `not_started` pending Platform's confirmation** that the separate `cohort_summary` sub-section is the right encoding placement (vs. migrating under `unit_economics` per Platform's three-asks-confirmations flexibility note). Finance's option-2 position preferred a separate sub-section; this manifest lands the separate form, with the migrate-under-unit_economics fallback available as a v2.0.x patch.
+- **All upstream silver is live**: Sales journey, Revenue recognition, Revenue orders are all in silver today. The sub-section is compute-wirable as soon as Platform's encoding confirmation lands; metrics flip from `not_started` to `beta` then.

package/contracts/finance-mart/customer-journey-audit.md

@@ -0,0 +1,92 @@
+# Finance Mart Customer Journey Audit Manifest
+
+**Status:** authoritative for finance-mart v2.0.x
+**Date:** 2026-05-19
+**Owner:** finance
+**Sub-section:** customer_journey_audit (§4.10 customer-grain audit carve-out)
+**Related:** finance-mart README §4.10, 2026-05-19-finance-customer-audit-consolidation-cleanness (row-shape resolution; consolidation of Portfolio's §9.3 `cohort_customer_audit`), 2026-05-19-finance-mart-registry-portfolio-consolidation-position (three conditions on posture, scope, initiative-attribution), 2026-05-19-portfolio-mart-scope-resolution-path-1-accepted (Portfolio's removal of §9.3 from portfolio-mart)
+
+## Purpose
+
+This manifest defines the `customer_journey_audit` carve-out in the finance gold section. The carve-out answers (audit-only, rate-limited): for a specific customer, what is the journey snapshot across intake, lock, delivery, revenue, and current status?
+
+The carve-out is the ONLY customer-grain row shape in finance-mart. Aggregate sub-sections never expose customer grain. The carve-out consolidates Portfolio's §9.3 `cohort_customer_audit` per the 2026-05-19 path-1 resolution; Portfolio's contract forbids person-grain rows per portfolio-mart §4.4 + §8, and Finance is the only domain with the rate-limit and audit-only posture appropriate for a customer-grain audit.
+
+The carve-out preserves three Finance-staked conditions from `2026-05-19-finance-mart-registry-portfolio-consolidation-position`:
+
+1. **Posture preserved**: audit-only, rate-limited, tagged `cross_domain_customer_grain=true`. The carve-out is not a general customer-grain reporting surface.
+2. **`current_initiative_attribution` excluded**: initiative attribution is a coordination-layer artifact, not a financial fact. Consumers needing initiative attribution join to a Platform-owned coordination surface at audit time.
+3. **Surface inside Finance's contract bound**: Portfolio consumers reading the audit do so through Finance's access pattern (rate-limit, firewall bound, deprecation discipline).
+
+## Served carve-out
+
+`GET /api/mart/sections/finance` exposes the carve-out at a separate, rate-limited audit endpoint (Platform's `lib/mart/sections/finance.ts` shape; the exact endpoint path under Platform's routing convention). The endpoint accepts a customer-identifier filter (`customer_id` or `person_id`), an optional cohort slice (`intake_cohort_week`, `intake_cohort_week_range`), and returns one row per customer matching the filter.
+
+Posture: `cross_domain_customer_grain=true` tag on every served row. Rate-limit enforced per the Finance access pattern. Audit-log every read.
+
+## Served columns
+
+Grain: one row per `customer_id`.
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `customer_id` | string | yes | spine | Primary key. The audit row is identified by customer. |
+| `org_market_id` | string | yes | spine | Customer's org-market attribution. |
+| `intake_week` | string | yes | sales journey | ISO week. Doubles as the cohort slicing dimension. |
+| `first_lock_week` | string or null | yes | sales.lead_stage_history | ISO week of first-lock; null if customer hasn't locked. |
+| `first_delivery_lesson_week` | string or null | yes | delivery silver | ISO week of first completed Delivery lesson; null if no lesson yet. |
+| `lessons_completed_to_date` | integer | yes | delivery silver | Count of completed lessons as of `as_of`. |
+| `revenue_paid_to_date_cents` | integer | yes | revenue silver | Cumulative `amount_paid_cents` for the customer as of `as_of`. |
+| `current_status` | string enum | yes | finance composition | Derived from stage state: one of `pre_lock`, `active`, `dormant`, `churned`, `lapsed`. |
+| `_cross_domain_customer_grain` | boolean | yes | finance composition | Always `true`. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | Audit-time snapshot timestamp. |
+
+**Field deliberately excluded**: `current_initiative_attribution`. Coordination-layer artifact, not a financial fact. Consumers needing initiative attribution join to a Platform-owned coordination surface at audit time. The exclusion is named here so the contract is explicit; consumers should not request the column.
+
+## Source silver columns
+
+| Silver object | Target column | Used for | Required |
+|---|---|---|---:|
+| `sales.lead_intake` (or equivalent) | `customer_id`, `intake_week`, `org_market_id` | identity + intake | yes |
+| `sales.lead_stage_history` | first-lock event per customer | `first_lock_week` | yes |
+| `delivery.lesson_event` | `customer_id`, `completed_at` | `first_delivery_lesson_week`, `lessons_completed_to_date` | yes |
+| `revenue.orders` (or equivalent) | `customer_id`, `amount_paid_cents`, `paid_at` | `revenue_paid_to_date_cents` | yes |
+| `delivery.customer` | `status`, `last_lesson_at` | `current_status` derivation | yes |
+| spine | `customer_id`, `person_id`, `org_market_id` | grain and join | yes |
+
+## Composition rule
+
+For each row at `customer_id`:
+
+1. Read `intake_week`, `org_market_id` from `sales.lead_intake` for the customer.
+2. Read `first_lock_week` from `sales.lead_stage_history`: the earliest event with stage = `locked` for the customer; null if no such event.
+3. Read `first_delivery_lesson_week` from `delivery.lesson_event`: the earliest event with `completed_at` set; null if no completed lesson yet.
+4. Count `lessons_completed_to_date` = count of `delivery.lesson_event` rows with `completed_at <= as_of` for the customer.
+5. Sum `revenue_paid_to_date_cents` = sum of `revenue.orders.amount_paid_cents` rows with `paid_at <= as_of` for the customer.
+6. Derive `current_status`:
+   - `pre_lock` if `first_lock_week` is null.
+   - `active` if `delivery.customer.status = 'active'` and `delivery.customer.last_lesson_at` is within the prior 8 weeks.
+   - `dormant` if last lesson is between 8 and 52 weeks ago.
+   - `churned` if last lesson is more than 52 weeks ago and customer hasn't booked a future lesson.
+   - `lapsed` if no completed lesson since `first_lock_week`.
+
+## Cohort slicing
+
+The audit endpoint accepts an optional `intake_cohort_week` or `intake_cohort_week_range` filter that slices by `intake_week`. The slice is a filter on the existing row shape, not a parallel row. The cohort-spot-check use case (give me all customers in cohort X) is served by the same endpoint with the filter applied; no parallel cohort-row endpoint exists.
+
+## Rate-limit and access posture
+
+The endpoint is rate-limited per Finance's `/admin/mart` access configuration. Audit-log every read, including the requesting consumer identity, the query filter (`customer_id` or cohort), and the row count returned. The endpoint is not callable from non-audit access tags.
+
+## Reconciliation tolerance
+
+- `revenue_paid_to_date_cents` reconciles to `revenue.orders` with tolerance `0` cents.
+- `lessons_completed_to_date` reconciles to `delivery.lesson_event` with tolerance `0`.
+- `first_lock_week`, `first_delivery_lesson_week` are minimums; tolerance `0` weeks.
+- `current_status` is derived; no external reconciliation target.
+
+## Known gaps
+
+- **The endpoint shape and rate-limit machinery** require Finance-side implementation alongside Platform's `lib/mart/sections/finance.ts` consolidation work. The row-shape is settled in `2026-05-19-finance-customer-audit-consolidation-cleanness`; the endpoint wiring follows.
+- **`current_status` enum definition** is Finance's call and lands here. If Delivery's `delivery.customer.status` enum diverges from `pre_lock`/`active`/`dormant`/`churned`/`lapsed`, Finance maps from Delivery's enum into the Finance enum at composition time.
+- All upstream silver is live; the gates are the endpoint wiring and the rate-limit configuration.

package/contracts/finance-mart/ltv.md

@@ -0,0 +1,92 @@
+# Finance Mart LTV Manifest
+
+**Status:** authoritative for finance-mart v2.0.x
+**Date:** 2026-05-19
+**Owner:** finance
+**Sub-section:** ltv
+**Related:** finance-mart README §4.8, 2026-05-19-finance-100-percent-deployment-decisions (Decision 3: LTV decomposition), cac-payback.md (matching CAC decomposition for the LTV:CAC ratio)
+
+## Purpose
+
+This manifest defines the `ltv` sub-section in the finance gold section. The sub-section answers: what is the lifetime value of a cohort's customers, and what is the LTV:CAC ratio?
+
+LTV composes per-customer cumulative gross margin against cohort size. The decomposition is gross-margin LTV per Finance's `_ltv_decomposition: gross_margin` decision, which matches the CAC decomposition (`marketing_plus_sales_sdr`) so the LTV:CAC ratio composes coherently. Cohort grain: `(org_market_id, intake_cohort_week)`.
+
+## Served sub-section
+
+`GET /api/mart/sections/finance` exposes this sub-section at `groupings.ltv`. Two metrics: `ltv_per_first_lock_cohort` and `ltv_to_cac_ratio`.
+
+## Served columns
+
+### `ltv_per_first_lock_cohort`
+
+Grain: one row per `(org_market_id, intake_cohort_week)`.
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `org_market_id` | string | yes | spine | |
+| `intake_cohort_week` | string | yes | sales journey | |
+| `cohort_size` | integer | yes | sales.lead_stage_history | Distinct customers in the cohort with first-lock. |
+| `cumulative_gross_margin_cents` | integer or null | yes | finance composition | Sum across all cohort customers of cumulative gross margin since intake. |
+| `ltv_cents` | integer or null | yes | finance composition | `cumulative_gross_margin_cents / cohort_size`. |
+| `observation_window_weeks` | integer | yes | finance composition | Weeks elapsed since `intake_cohort_week`. |
+| `_ltv_decomposition` | string | yes | finance composition | `gross_margin`. |
+| `null_reason` | string or null | yes | finance composition | `null:upstream_unavailable` until cumulative gross margin per cohort customer is composable; `null:insufficient_data` below cohort floor of 5. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | |
+
+Policy: `_ltv_decomposition: gross_margin`. Rollup rule: `weighted_mean_by_cohort_size`.
+
+### `ltv_to_cac_ratio`
+
+Grain: one row per `(org_market_id, intake_cohort_week)`. Derived from matching `ltv_per_first_lock_cohort` and `cac` (or `cac_per_first_lock` aggregate) at the same cohort grain.
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `org_market_id` | string | yes | spine | |
+| `intake_cohort_week` | string | yes | sales journey | |
+| `ltv_cents` | integer or null | yes | finance composition | From `ltv_per_first_lock_cohort` at same grain. |
+| `cac_cents` | integer or null | yes | finance composition | From `cac` (aggregate across source classes) at same grain. |
+| `ltv_to_cac_ratio_bps` | integer or null | yes | finance composition | `round(ltv_cents / cac_cents × 10000)` as basis points. |
+| `null_reason` | string or null | yes | finance composition | `null:upstream_unavailable` when either component is null; `null:not_applicable` when CAC is zero (free-acquisition cohort). |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | |
+
+Policy: `_ltv_decomposition: gross_margin` and `_cac_cost_decomposition: marketing_plus_sales_sdr` paired. Rollup rule: `weighted_mean_by_cohort_size`.
+
+## Source silver columns
+
+| Silver object | Target column | Used for | Required |
+|---|---|---|---:|
+| `sales.lead_stage_history` | first-lock events per customer | cohort identity and size | yes |
+| `revenue.revenue_recognition` | per-customer cumulative recognized revenue since intake | LTV revenue side | yes |
+| `coaching.coach.lesson_rate`, `coaching.coach.travel_comp` | per-coach cost rates | cost-of-service per customer | yes |
+| `delivery.lesson_event` | `coach_id`, `duration`, `customer_id`, `org_market_id`, `completed_at` | per-customer cost-of-service composition | yes |
+| spine | `org_market_id`, `person_id` | grain and join keys | yes |
+| cac-payback.md `cac_cents` figure | matching cohort grain | `ltv_to_cac_ratio` denominator | yes (Finance composition, not silver) |
+
+## Composition rule
+
+`ltv_per_first_lock_cohort`:
+
+1. Identify the cohort: distinct customers with their first-lock in `intake_cohort_week` at `org_market_id`, from `sales.lead_stage_history`.
+2. For each cohort customer, compose cumulative gross margin since intake: sum of (per-lesson recognized revenue − per-lesson cost-of-service) over all lessons from `intake_cohort_week` to current observation date. Per-lesson cost-of-service uses the same Coaching + Delivery join as the `margin` sub-section.
+3. Sum across the cohort to `cumulative_gross_margin_cents`.
+4. Read `cohort_size` from step 1.
+5. Return `cumulative_gross_margin_cents / cohort_size` as `ltv_cents`.
+
+`ltv_to_cac_ratio_bps`:
+
+1. Read `ltv_cents` from `ltv_per_first_lock_cohort` at the row's `(org_market_id, intake_cohort_week)`.
+2. Read `cac_cents` from `cac` (aggregate, not split by source_class) at the same cohort grain.
+3. Return `round(ltv_cents / cac_cents × 10000)` as basis points. Emit `null:not_applicable` when `cac_cents = 0`.
+
+## Reconciliation tolerance
+
+- `cumulative_gross_margin_cents` reconciles to the same Revenue + Coaching + Delivery composition the `margin` sub-section uses; tolerance `0` cents.
+- `cohort_size` reconciles to `sales.lead_stage_history` with tolerance `0`.
+- `ltv_to_cac_ratio_bps` is derived from two Finance metrics; its reconciliation surface is the component figures.
+
+## Known gaps
+
+- **`ltv_per_first_lock_cohort`** is currently `null:upstream_unavailable` until per-customer cumulative cost-of-service composition is wired in `lib/mart/sections/finance.ts`. The upstream silver (Revenue recognition + Coaching cost + Delivery lesson_event) is all live; the gate is the Finance compute wiring per Platform's continuous-deployment cadence.
+- **`ltv_to_cac_ratio`** is gated on both `ltv_per_first_lock_cohort` and `cac` reaching beta. CAC is at beta in marketing-only form via Round 6's `cac_per_first_lock`; the full marketing+sales-SDR form gates on Sales SDR allocation silver (see cac-payback.md known gaps).
+- No silver-side gaps for this sub-section; the gaps are Finance composition wiring.

package/contracts/finance-mart/margin.md

@@ -0,0 +1,87 @@
+# Finance Mart Margin Manifest
+
+**Status:** authoritative for finance-mart v1.0.0
+**Date:** 2026-05-18
+**Owner:** finance
+**Grouping:** margin
+**Related:** finance-mart README section 4.4, warehouse-silver v1.1.0, 2026-05-17-revenue-finance-mart-contract-reply
+
+## Purpose
+
+This manifest defines the `margin` grouping in the finance gold section. The grouping answers: what margin did a reporting period earn, and where is margin concentrated by Organization and Market?
+
+Margin pairs recognized revenue with source-backed direct cost facts. Finance will not synthesize cost. If the current silver faces do not carry a cost fact, the served row must expose that gap rather than producing a false full-margin number.
+
+## Served grouping
+
+`GET /api/mart/sections/finance` exposes this grouping at `groupings.margin`.
+
+The grouping grain is one row per:
+
+- `reporting_period`
+- `organization_id`
+- `market_id`
+
+`org_market_id` is the stable mart coordination key for the Organization and Market pair. `service_area_id` MAY appear only when a source-backed silver face column exists and the implementation explicitly scopes a Service Area cut.
+
+## Served columns
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `reporting_period` | string | yes | `revenue.recognition.recognition_period` | Calendar period key. |
+| `reporting_period_grain` | string enum | yes | finance composition | `month` in the first implementation. |
+| `organization_id` | string | yes | spine | Platform Organization ID for the discipline. |
+| `organization_slug` | string | yes | spine | Stable display slug for the Organization. |
+| `market_id` | string | yes | spine | Platform Market ID. |
+| `market_slug` | string | yes | spine | Stable display slug for the Market. |
+| `org_market_id` | string | yes | `OrgMarket.slug` | Stable mart key for the Organization and Market pair. |
+| `recognized_revenue_cents` | integer | yes | revenue-recognition composition | Net recognized revenue, using the revenue-recognition manifest rule. |
+| `direct_cost_cents` | integer or null | yes | delivery or coaching silver cost columns | Null until source-backed cost facts exist. |
+| `gross_margin_cents` | integer or null | yes | finance composition | `recognized_revenue_cents - direct_cost_cents`; null when cost is unavailable. |
+| `gross_margin_rate_bps` | integer or null | yes | finance composition | Basis points, null when revenue is zero or cost is unavailable. |
+| `cost_basis_status` | string enum | yes | finance composition | One of `complete`, `partial`, `missing_cost_source`. |
+| `cost_gap_reason` | string or null | yes | finance composition | Required when `cost_basis_status` is not `complete`. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | Refresh point of the materialized grouping. |
+
+## Source silver columns
+
+The revenue side is sourced from `revenue.recognition` using the revenue-recognition manifest.
+
+The direct-cost side targets these source-backed cost columns if and only if the live silver faces carry them:
+
+| Silver object | Target column | Required for complete margin | Use |
+|---|---|---:|---|
+| `delivery.lesson` | `lesson_id` | yes | Lesson-level cost grain and join key. |
+| `delivery.lesson` | `person_id` | yes where lesson is person-related | Join to the spine. |
+| `delivery.lesson` | `completed_at` | yes | Period alignment for completed lesson cost. |
+| `delivery.lesson` | `organization_id` | yes when source-backed | Organization attribution when present on the face. |
+| `delivery.lesson` | `market_id` | yes when source-backed | Market attribution when present on the face. |
+| `delivery.lesson` | `service_area_id` | optional | Service Area cut, if source-backed. |
+| `delivery.lesson` | `coach_pay_cents` | yes for complete lesson-cost margin | Direct coach cost for delivered lessons. |
+| `delivery.lesson` | `facility_cost_cents` | optional | Direct facility cost, if the source carries it. |
+| `coaching.lesson_booking` | `lesson_booking_id` | optional | Booking-level cost grain when coaching carries the cost fact. |
+| `coaching.lesson_booking` | `coach_cost_cents` | optional | Direct coaching cost, if the source carries it. |
+
+If the live silver surface does not carry `coach_pay_cents` or an equivalent source-backed direct cost column, full margin is not implementable yet. In that case the grouping may still expose revenue-side rows with `direct_cost_cents = null`, `gross_margin_cents = null`, `gross_margin_rate_bps = null`, `cost_basis_status = missing_cost_source`, and `cost_gap_reason = direct_cost_fact_absent_from_silver`.
+
+## Composition rule
+
+For each grouping row:
+
+`recognized_revenue_cents` follows the revenue-recognition manifest.
+
+`direct_cost_cents = sum(source-backed direct cost columns aligned to the same reporting period, Organization, and Market)`
+
+`gross_margin_cents = recognized_revenue_cents - direct_cost_cents`
+
+`gross_margin_rate_bps = round(gross_margin_cents / recognized_revenue_cents * 10000)`
+
+When direct cost is partially available, the row must set `cost_basis_status = partial` and name the missing cost class in `cost_gap_reason`. Consumers must not treat partial margin as full gross margin.
+
+## Reconciliation tolerance
+
+The revenue side reconciles to Revenue with a tolerance of `0` cents. The cost side reconciles to the producing silver face with a tolerance of `0` cents once source-backed cost columns exist. Until then, the margin grouping is explicitly not fully reconcilable and the `reconciliation` grouping must report `not_reconcilable_missing_source` for margin-cost figures.
+
+## Known gaps
+
+Revenue confirmed it does not hold cost data. The expected gap is direct cost coverage on Delivery or Coaching silver. Platform should treat the direct-cost target columns in this manifest as a source-availability check, not as permission to synthesize cost in silver.