@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/finance-mart/pnl.md

@@ -0,0 +1,83 @@
+# Finance Mart PnL Manifest
+
+**Status:** authoritative for finance-mart v2.0.x
+**Date:** 2026-05-19
+**Owner:** finance
+**Sub-section:** pnl
+**Related:** finance-mart README §4.4, revenue-recognition-rollup.md (carries `revenue_recognition_summary` under the same sub-section), 2026-05-19-platform-mart-round-status-and-next-silver-asks (Round 6 wiring of pnl_summary v0), 2026-05-19-finance-100-percent-deployment-decisions (OPEX allocation rule)
+
+## Purpose
+
+This manifest defines the `pnl_summary` metric in the finance gold section's `pnl` sub-section. The metric answers: what is the P&L for a given period at the business reporting grain, composing recognized revenue, cost-of-service, and operating expense?
+
+The companion `revenue_recognition_summary` metric in the same sub-section is documented in `revenue-recognition-rollup.md` (carry-forward from v1.0.0 §4.3). This manifest covers `pnl_summary` only.
+
+## Served sub-section
+
+`GET /api/mart/sections/finance` exposes this metric under `groupings.pnl.pnl_summary` (or the equivalent typed grouping per Platform's `PnlSummaryRow` shape in `lib/mart/sections/finance.ts`). Three grains per Round 6: `per-org × per-month`, `per-portfolio × per-month` rollup with sum, and `per-org-market × per-month`.
+
+## Served columns
+
+Grain: one row per `(geography_key, reporting_period)` where `geography_key` is one of (org_market, organization, portfolio).
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `geography_key` | string | yes | spine | One of `org_market_id`, `organization_id`, `portfolio_id`. |
+| `geography_grain` | string enum | yes | finance composition | `org_market`, `organization`, `portfolio`. |
+| `reporting_period` | string | yes | finance composition | Month key in v2.0.x first implementation. |
+| `recognized_revenue_cents` | integer | yes | revenue silver | GAAP earned revenue from `revenue_recognition_summary`. |
+| `cost_of_service_cents` | integer or null | yes | coaching + delivery silver | Coach compensation joined to lesson-event; matches Coaching cost-trio plus Delivery `lesson_event`. |
+| `attributable_ad_spend_cents` | integer or null | yes | growth silver via revenue ad-spend-reconciled | S&M cost attributable to the reporting period; from Revenue's `ad-spend-reconciled` silver endpoint. |
+| `operating_expense_cents` | integer or null | yes | finance operator-recorded substrate + composition | Allocated per `_opex_allocation_rule`; null until OPEX feed lands. |
+| `contribution_margin_cents` | integer or null | yes | finance composition | `recognized_revenue_cents − cost_of_service_cents − attributable_ad_spend_cents`. |
+| `net_income_cents` | integer or null | yes | finance composition | `contribution_margin_cents − operating_expense_cents`; null when OPEX is `null:upstream_unavailable`. |
+| `opex_kind` | string enum or null | yes | finance composition | One of `native_grain`, `cross_grain_revenue_share_allocated`, `structurally_unallocated_held_at_portfolio`; null at coarsest grain when all OPEX is native-grain. |
+| `opex_allocation_rule_applied` | string or null | yes | finance composition | `native_grain_plus_revenue_share_for_cross_grain` when OPEX is included; null otherwise. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | |
+
+Policy: `_opex_allocation_rule: native_grain_plus_revenue_share_for_cross_grain`. Rollup rule: `sum`.
+
+## Source silver columns
+
+| Silver object | Target column | Used for | Required |
+|---|---|---|---:|
+| `revenue.revenue_recognition` | `recognized_amount_cents`, `recognition_period`, `org_market_id` | numerator | yes |
+| `coaching.coach` | `lesson_rate`, `travel_comp`, `coach_id` | cost-of-service per coach | yes |
+| `delivery.lesson_event` | `coach_id`, `duration`, `org_market_id`, `completed_at` | cost-of-service per lesson | yes |
+| Revenue `/api/v1/silver/ad-spend-reconciled` | `ad_spend_cents`, `source_class`, `week`, `org_market_id` | S&M cost attribution | yes |
+| Finance `cash_balance_entries` (Finance-owned table) | OPEX-tagged entries per period per Organization | operating_expense_cents native-grain | yes (when scoped) |
+| spine | `org_market_id`, `organization_id`, geography rollups | grain key resolution | yes |
+
+## Composition rule
+
+For each row:
+
+1. `recognized_revenue_cents` = sum from `revenue_recognition_summary` at the row's `(geography_key, reporting_period)`.
+2. `cost_of_service_cents` = sum of `(coaching.coach.lesson_rate + coaching.coach.travel_comp) × delivery.lesson_event.duration_hours` for lessons completed in the reporting period at the row's `geography_key`. Travel comp threshold per Coaching's 2026-05-19 cost-trio declaration (5-minute back-to-back).
+3. `attributable_ad_spend_cents` = sum of `ad_spend_cents` from the Revenue `ad-spend-reconciled` endpoint, filtered to paid-source-class slice (`paid_social`, `paid_search`; `direct` excluded as non-acquisition; `other` flagged) for weeks falling within `reporting_period`, at the row's `geography_key`.
+4. `operating_expense_cents` = native-grain OPEX entries from `cash_balance_entries` table tagged at the row's `geography_key`, plus revenue-share-allocated OPEX flowing down from coarser grains per the `_opex_allocation_rule`.
+5. `contribution_margin_cents` = `recognized_revenue_cents − cost_of_service_cents − attributable_ad_spend_cents`.
+6. `net_income_cents` = `contribution_margin_cents − operating_expense_cents`.
+7. `opex_kind` tags how the OPEX in row 4 was composed (`native_grain`, `cross_grain_revenue_share_allocated`, or the row sums structurally-unallocated portfolio-grain OPEX excluded from finer-grain rows).
+
+## OPEX allocation rule
+
+Per `_opex_allocation_rule: native_grain_plus_revenue_share_for_cross_grain`:
+
+- **Native-grain OPEX**: costs incurred at the row's `geography_grain` stay at that grain. A Market-grain OPEX entry sums into Market-grain rows; an Organization-grain entry sums into Organization-grain rows; a Portfolio-grain entry sums into the Portfolio-grain row.
+- **Cross-grain OPEX flowing down**: when a row at a finer grain needs to include OPEX incurred at a coarser grain, allocation is by revenue share. An Organization-grain OPEX of $X allocates to each Market in proportion to that Market's share of Organization revenue for the reporting period; an Organization gets a portion of Portfolio-grain OPEX in proportion to its share of Portfolio revenue.
+- **Structurally-unallocated OPEX held at portfolio**: capital, founder draws, one-time legal, and other genuinely portfolio-level non-allocatable entries stay at the Portfolio grain only. Finer-grain rows do not include this OPEX and surface it via `opex_kind = structurally_unallocated_held_at_portfolio` on the Portfolio-grain row only.
+
+## Reconciliation tolerance
+
+- `recognized_revenue_cents` reconciles to Revenue's ledger with tolerance `0` cents.
+- `cost_of_service_cents` reconciles to the Coaching + Delivery silver join with tolerance `0` cents.
+- `attributable_ad_spend_cents` reconciles to the Revenue `ad-spend-reconciled` silver with tolerance `0` cents.
+- `operating_expense_cents` reconciles to the `cash_balance_entries` table with tolerance `0` cents once the table is in place.
+- `contribution_margin_cents` and `net_income_cents` are derived; their reconciliation surface is their component figures.
+
+## Known gaps
+
+- **`operating_expense_cents` is `null:upstream_unavailable`** until the Finance-owned `cash_balance_entries` table is scoped and shipped (P3/S commitment in `2026-05-19-finance-three-asks-decisions`). Once the table is live with operator-recorded OPEX entries, `operating_expense_cents` populates and `net_income_cents` follows.
+- **`pnl_summary` v0 ships today with `operating_expense_cents` and `net_income_cents` null and `contribution_margin_cents` populated.** v0 corresponds to the Round 6 Platform wiring.
+- No outstanding silver gaps for the revenue, cost-of-service, or ad-spend slices.

package/contracts/finance-mart/reconciliation.md

@@ -0,0 +1,98 @@
+# Finance Mart Reconciliation Manifest
+
+**Status:** authoritative for finance-mart v1.0.0
+**Date:** 2026-05-18
+**Owner:** finance
+**Grouping:** reconciliation
+**Related:** finance-mart README section 4.6, warehouse-silver v1.1.0, 2026-05-17-revenue-finance-mart-contract-reply
+
+## Purpose
+
+This manifest defines the `reconciliation` grouping in the finance gold section. The grouping answers: does each business-grain finance figure tie back to Revenue's transaction-grain ledger within tolerance, and where is the variance?
+
+The reconciliation grouping is the safety surface. Finance must surface variance here rather than hiding it in the revenue recognition, margin, or cash position rows.
+
+## Served grouping
+
+`GET /api/mart/sections/finance` exposes this grouping at `groupings.reconciliation`.
+
+The grouping grain is one row per:
+
+- `reporting_period`
+- `organization_id`
+- `market_id`
+- `figure_name`
+
+`org_market_id` is the stable mart coordination key for the Organization and Market pair.
+
+## Served columns
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `reporting_period` | string | yes | finance composition | Calendar period being reconciled. |
+| `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. |
+| `figure_name` | string enum | yes | finance composition | One of the figures listed below. |
+| `reported_amount_cents` | integer or null | yes | finance grouping output | Amount reported by finance-mart. |
+| `source_amount_cents` | integer or null | yes | source silver columns | Amount independently summed from authoritative source facts. |
+| `variance_cents` | integer or null | yes | finance composition | `reported_amount_cents - source_amount_cents`. |
+| `tolerance_cents` | integer | yes | this manifest | Allowed absolute variance. |
+| `reconciliation_status` | string enum | yes | finance composition | `reconciled`, `variance`, `not_reconcilable_missing_source`, or `not_applicable`. |
+| `source_row_count` | integer | yes | source silver columns | Count of source rows behind the reconciliation target. |
+| `exception_count` | integer | yes | source silver columns | Count of exception or anomaly rows included in the target. |
+| `variance_reason` | string or null | yes | finance composition | Required when status is not `reconciled`. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | Refresh point of the materialized grouping. |
+
+## Figures and source targets
+
+| `figure_name` | Reported source | Authoritative source target | Tolerance | Notes |
+|---|---|---|---:|---|
+| `recognized_revenue` | `revenue_recognition.recognized_revenue_cents` | Sum of `revenue.recognition.recognized_amount_cents`, non-contra less contra, tied through `source_credit_ledger_entry_id` to `revenue.credit_ledger` | 0 cents | Primary revenue-recognition tie-back. |
+| `gross_recognized_revenue` | `revenue_recognition.gross_recognized_revenue_cents` | Sum of non-contra `revenue.recognition.recognized_amount_cents` | 0 cents | Gross before contra rows. |
+| `contra_revenue` | `revenue_recognition.contra_revenue_cents` | Sum of contra `revenue.recognition.recognized_amount_cents` | 0 cents | Refund and reversal recognition impact. |
+| `cash_received` | `cash_position.cash_received_cents` | Sum of confirmed paid `revenue.order.amount_paid_cents` by `paid_at` | 0 cents | Cash receipt tie-back. |
+| `cash_refunded` | `cash_position.cash_refunded_cents` | Sum of confirmed refunded `revenue.refund_item.amount_cents` by `refunded_at` | 0 cents | Cash-out tie-back. |
+| `net_cash` | `cash_position.net_cash_cents` | Confirmed cash received less confirmed cash refunded | 0 cents | Derived from the two source-backed cash figures. |
+| `reserved_credit_liability` | `cash_position.reserved_credit_liability_cents` | Sum of funded open `revenue.credit_reservation` obligations, cross-checked against `revenue.credit_ledger` movements | 0 cents where money amount exists | If money amount is absent, status is `not_reconcilable_missing_source`. |
+| `unearned_credit_balance` | `cash_position.unearned_credit_balance_cents` | Money-denominated purchased credits not yet earned, refunded, forfeited, or adjusted away in `revenue.credit_ledger` | 0 cents where money amount exists | If credit quantity cannot be converted from source-backed money amount, status is `not_reconcilable_missing_source`. |
+| `margin_revenue` | `margin.recognized_revenue_cents` | Same target as `recognized_revenue` | 0 cents | Revenue side of margin. |
+| `margin_cost` | `margin.direct_cost_cents` | Delivery or Coaching source-backed direct cost columns named in `margin.md` | 0 cents where source exists | Expected initial gap until direct cost facts are present. |
+| `gross_margin` | `margin.gross_margin_cents` | `margin_revenue - margin_cost` | 0 cents where both sides exist | Status is `not_reconcilable_missing_source` when cost source is missing. |
+
+## Source silver columns
+
+The source columns are the union of the columns named by:
+
+- `revenue-recognition-rollup.md`
+- `cash-position.md`
+- `margin.md`
+
+In addition, reconciliation uses Revenue's ledger tie-back columns:
+
+| Silver object | Silver column | Required | Use |
+|---|---|---:|---|
+| `revenue.credit_ledger` | `credit_ledger_entry_id` | yes | Ledger row identity. |
+| `revenue.credit_ledger` | `type` | yes | Movement classification, including `PURCHASE_CREDIT`, `LESSON_DEBIT`, `REFUND_DEBIT`, `RESERVATION_LOCK_DEBIT`, `CREDIT_FORFEIT`, and `ADJUSTMENT` or equivalent conformed values. |
+| `revenue.credit_ledger` | `delta_credits` | yes | Credit quantity movement. |
+| `revenue.credit_ledger` | `amount_cents` | yes when source-backed | Money movement for money-denominated reconciliation. |
+| `revenue.credit_ledger` | `occurred_at` | yes | Ledger movement timestamp. |
+| `revenue.credit_ledger` | `order_item_id` | yes when present in source | Tie-back to commercial order item. |
+| `revenue.credit_ledger` | `credit_reservation_id` | yes when present in source | Tie-back to reservation and lock state. |
+
+## Status rules
+
+`reconciled` means `abs(variance_cents) <= tolerance_cents`.
+
+`variance` means the source exists, the reported figure exists, and the absolute variance exceeds tolerance.
+
+`not_reconcilable_missing_source` means the reported figure depends on a source fact that is absent from silver or absent from the producing source. This status is expected for full margin-cost reconciliation until source-backed direct cost facts exist.
+
+`not_applicable` means the figure does not apply to the row's grain, for example a grouping with no source activity in that period and dimension.
+
+## Known gaps
+
+The margin-cost and gross-margin figures are not fully reconcilable until direct cost facts exist in Delivery or Coaching silver. Finance must not mark those figures reconciled based only on Revenue data.

package/contracts/finance-mart/revenue-recognition-rollup.md

@@ -0,0 +1,87 @@
+# Finance Mart Revenue Recognition Rollup Manifest
+
+**Status:** authoritative for finance-mart v1.0.0
+**Date:** 2026-05-18
+**Owner:** finance
+**Grouping:** revenue_recognition
+**Related:** finance-mart README section 4.3, warehouse-silver v1.1.0, 2026-05-17-revenue-finance-mart-contract-reply
+
+## Purpose
+
+This manifest defines the `revenue_recognition` grouping in the finance gold section. The grouping answers: what recognized revenue did a reporting period earn, and how does that revenue roll up by Organization and Market?
+
+The grouping is business-grain reporting over Revenue's transaction-grain truth. Finance composes it from the Revenue silver face and the identity and geography spine. Finance does not read Revenue bronze and does not restate Revenue's ledger.
+
+## Served grouping
+
+`GET /api/mart/sections/finance` exposes this grouping at `groupings.revenue_recognition`.
+
+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. Service Area is not assumed from the spine.
+
+## Served columns
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `reporting_period` | string | yes | `revenue.recognition.recognition_period` | Calendar period key. The first implementation uses month grain unless the route adds an explicit `reporting_period_grain`. |
+| `reporting_period_grain` | string enum | yes | finance composition | `month` in the first implementation. Future grains are additive if existing rows keep their meaning. |
+| `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 | finance composition over `revenue.recognition` | Net recognized revenue, gross recognitions less contra recognitions. |
+| `gross_recognized_revenue_cents` | integer | yes | `revenue.recognition.recognized_amount_cents` | Sum of non-contra recognition rows. |
+| `contra_revenue_cents` | integer | yes | `revenue.recognition.recognized_amount_cents`, `is_contra` | Sum of contra rows as a positive contra amount. |
+| `recognition_count` | integer | yes | `revenue.recognition.recognition_id` | Count of recognition rows in the grouping. |
+| `exception_recognition_count` | integer | yes | `revenue.recognition.has_exception` | Count of recognition rows marked with an exception. |
+| `exception_revenue_cents` | integer | yes | `revenue.recognition.has_exception`, `recognized_amount_cents` | Net recognized revenue from exception rows. |
+| `has_exception` | boolean | yes | finance composition | True when `exception_recognition_count` is greater than zero. |
+| `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, expected object `revenue.recognition`, with these source-backed conformed columns:
+
+| Silver column | Required | Use |
+|---|---:|---|
+| `recognition_id` | yes | Stable recognition-row identifier and row count. |
+| `person_id` | yes where source row is person-related | Join to the spine for Organization and Market. |
+| `recognition_period` | yes | Reporting period. |
+| `recognized_amount_cents` | yes | Amount in integer cents. |
+| `is_contra` | yes | Contra classification for refunds and reversals. |
+| `created_via` | yes | Variance analysis by recognition origin. Expected values include `LESSON_COMPLETION_JOB`, `REFUND_JOB`, `MANUAL`, and `BACKFILL`. |
+| `source_credit_ledger_entry_id` | yes | Tie-back into Revenue's credit ledger for reconciliation. |
+| `order_item_id` | yes when present in source | Commercial tie-back. |
+| `credit_reservation_id` | yes when present in source | Reservation and obligation tie-back. |
+| `occurred_at` | yes | Event timestamp. |
+| `created_at` | yes | Row creation timestamp, useful for freshness checks. |
+| `has_exception` | yes | Exception inclusion flag. |
+| `exception_reason` | yes when `has_exception` is true | Exception explanation. |
+
+The implementation joins the spine through `person_id` for `organization_id`, `organization_slug`, `market_id`, `market_slug`, and `org_market_id`.
+
+## Composition rule
+
+For each grouping row:
+
+`gross_recognized_revenue_cents = sum(recognized_amount_cents where is_contra = false)`
+
+`contra_revenue_cents = sum(recognized_amount_cents where is_contra = true)`
+
+`recognized_revenue_cents = gross_recognized_revenue_cents - contra_revenue_cents`
+
+Exception rows are included at face value. They are not filtered out. Their count and net amount are surfaced through `exception_recognition_count`, `exception_revenue_cents`, and `has_exception` so reporting consumers can see variance risk without Finance silently dropping Revenue facts.
+
+## Reconciliation tolerance
+
+This grouping reconciles to Revenue's `revenue.recognition` and `revenue.credit_ledger` surfaces with a tolerance of `0` cents. Money is carried as integer minor units, so rounding variance is not expected. Any non-zero variance belongs in the `reconciliation` grouping.
+
+## Known gaps
+
+None for the revenue-recognition figure set named here, assuming the live Revenue silver face carries the source-backed columns listed above. If the face uses different names for the same source-backed facts, Platform should conform them to the names in this manifest or return the equivalent mapping before implementation.

package/contracts/finance-mart/unit-economics.md

@@ -0,0 +1,94 @@
+# Finance Mart Unit Economics Manifest
+
+**Status:** authoritative for finance-mart v2.0.x
+**Date:** 2026-05-19
+**Owner:** finance
+**Sub-section:** unit_economics
+**Related:** finance-mart README §4.3, warehouse-silver v1.1.0, 2026-05-19-finance-revenue-per-active-student-absorption, 2026-05-19-platform-mart-round-status-and-next-silver-asks (Round 5 wiring of revenue_concentration)
+
+## Purpose
+
+This manifest defines the `unit_economics` sub-section in the finance gold section. The sub-section answers: what is the per-active-student revenue intensity at the operational unit level, and how concentrated is revenue across the customer base?
+
+Unit economics composes recognized revenue against operational-scale denominators. The sub-section is keyed at the business reporting grain (`reporting_period × geography_key`) for the per-period view, with `revenue_per_active_student` reading Delivery's snapshot-week-end active-student count and `revenue_concentration` reading per-customer revenue aggregates.
+
+## Served sub-section
+
+`GET /api/mart/sections/finance` exposes this sub-section at `groupings.unit_economics` (or the equivalent typed grouping per Platform's `FinanceComputeResult` shape). Two metrics, one row shape per metric, both at the business reporting grain.
+
+## Served columns
+
+### `revenue_per_active_student`
+
+Grain: one row per `(org_market_id, week)`.
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `org_market_id` | string | yes | spine | Stable mart key for the Organization and Market pair. |
+| `week` | string | yes | finance composition | ISO week (YYYY-Www, UTC), keyed to lesson-week for the numerator. |
+| `recognized_revenue_cents` | integer | yes | revenue silver | Numerator: GAAP earned revenue summed by `org_market × lesson_week`. |
+| `active_student_count` | integer or null | yes | delivery silver | Denominator: Delivery's `active_student_count` snapshot-week-end value. |
+| `revenue_per_active_student_cents` | integer or null | yes | finance composition | `recognized_revenue_cents / active_student_count`; null when denominator is below cohort floor of 5. |
+| `null_reason` | string or null | yes | finance composition | `null:insufficient_data` when `active_student_count < 5`; null otherwise. |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | Refresh point of the materialized row. |
+
+Policy: `_axis_reconciliation: revenue_lesson_week_div_delivery_snapshot_week_end`. Rollup rule `weighted_mean_by_revenue` per spec. Cohort floor `active_student_count < 5`.
+
+### `revenue_concentration`
+
+Grain: one row per `(org_market_id, reporting_period)` per Revenue's Round 5 decision (`_concentration_n: 10`, `_concentration_window_weeks: 52`).
+
+| Column | Type | Required | Source | Notes |
+|---|---|---:|---|---|
+| `org_market_id` | string | yes | spine | |
+| `reporting_period` | string | yes | finance composition | Calendar period key. |
+| `top_n_revenue_cents` | integer | yes | revenue silver | Sum of recognized revenue from the top-10 customers by GAAP earned revenue in the trailing 52-week window ending at `reporting_period`. |
+| `total_revenue_cents` | integer | yes | revenue silver | Sum of all customers' recognized revenue in the same window. |
+| `concentration_ratio_bps` | integer | yes | finance composition | `round(top_n_revenue_cents / total_revenue_cents × 10000)`; basis points. |
+| `_concentration_n` | integer | yes | finance composition | 10 (Revenue's Round 5 decision). |
+| `_concentration_window_weeks` | integer | yes | finance composition | 52 (trailing year). |
+| `as_of` | UTC ISO 8601 timestamp | yes | finance materialization | |
+
+Policy: `_concentration_n: 10`, `_concentration_window_weeks: 52`. Rollup rule `weighted_mean_by_revenue`.
+
+## Source silver columns
+
+| Silver object | Target column | Used for | Required |
+|---|---|---|---:|
+| `revenue.revenue_recognition` | `recognized_amount_cents` | both metrics, numerator | yes |
+| `revenue.revenue_recognition` | `recognition_period` | both metrics, period alignment | yes |
+| `revenue.revenue_recognition` | `person_id` | `revenue_concentration` per-customer aggregation | yes |
+| `revenue.revenue_recognition` | `org_market_id` | spine attribution | yes |
+| `delivery.customer` | `status = 'active'` filter | `revenue_per_active_student` denominator | yes |
+| `delivery.customer` | `org_market_id` | spine attribution | yes |
+| `delivery.customer` | `snapshot_week` | snapshot-week-end alignment | yes |
+| spine | `org_market_id`, `organization_id`, `market_id` | geography keys | yes |
+
+## Composition rule
+
+`revenue_per_active_student_cents`:
+
+1. Sum `recognized_amount_cents` from `revenue.revenue_recognition` over `recognition_period` falling within `lesson_week`, grouped by `org_market_id`.
+2. Read `active_student_count` from `delivery.customer` at the snapshot-week-end value matching `week`.
+3. If `active_student_count >= 5`, return `recognized_revenue_cents / active_student_count`; otherwise emit `null:insufficient_data`.
+
+`concentration_ratio_bps`:
+
+1. Aggregate `recognized_amount_cents` per `(org_market_id, person_id)` over the trailing 52-week window ending at `reporting_period`.
+2. Take the top-10 `person_id` rows by aggregate revenue; sum to `top_n_revenue_cents`.
+3. Sum all rows to `total_revenue_cents`.
+4. Return `round(top_n_revenue_cents / total_revenue_cents × 10000)` as basis points.
+
+## Reconciliation tolerance
+
+`revenue_per_active_student` numerator reconciles to Revenue's transaction-grain ledger with tolerance `0` cents (the numerator is the sum of recognized-revenue rows; identity).
+
+`revenue_concentration` numerator and denominator both reconcile to Revenue's ledger with tolerance `0` cents. The ratio itself is a derived figure with no reconciliation target outside Finance.
+
+## Known gaps
+
+`revenue_per_active_student` is wirable today: both upstream surfaces (`revenue.revenue_recognition`, `delivery.customer.status`) are live.
+
+`revenue_concentration` is wirable today: per-customer revenue aggregation from `revenue.revenue_recognition.person_id` is the standard cross-domain join. The metric flips to beta with Platform's Round 5 wiring.
+
+No outstanding silver gaps for this sub-section.

package/contracts/growth-warehouse-api/README.md

@@ -0,0 +1,162 @@
+# Growth Warehouse API contract
+
+**Status:** active
+**Version:** 1
+**Producer:** growth
+**Date:** 2026-05-12
+
+Read-only HTTP surface for forecasting and analytics consumers (primarily Them OS) to pull raw Growth-domain data without managing direct Postgres connections.
+
+The same data is also reachable via the dbt source declarations in `platform/warehouse/models/sources/growth.yml` for BI tools that prefer SQL. This API is the lower-friction option for application consumers.
+
+## Auth
+
+Bearer token shared with each consumer.
+
+- Header: `Authorization: Bearer <THEM_OS_API_KEY>`
+- Token lives in the Growth deploy's environment (`THEM_OS_API_KEY` on Vercel).
+- Consumers store the same value as their outbound credential.
+- Comparison is constant-time (`crypto.timingSafeEqual`) to avoid timing-leak attacks on the token.
+
+Tokens are not multi-tenant in v1. If a second consumer needs access, mint a separate token (`<CONSUMER>_API_KEY`) and add the auth check to recognize either; rotating one consumer should not invalidate the other.
+
+## Endpoints
+
+### `GET /api/warehouse/growth/manifest`
+
+Returns the catalogue: every exposed table, its primary key, cursor column, optional date filter column, and full column descriptors with types and nullability.
+
+Response (abbreviated):
+
+```json
+{
+  "generated_at": "2026-05-12T20:00:00.000Z",
+  "domain": "growth",
+  "api_version": 1,
+  "max_page_size": 5000,
+  "default_page_size": 1000,
+  "tables": [
+    {
+      "table": "lead_intake",
+      "description": "Form submissions ...",
+      "primary_key": "id",
+      "cursor_column": "id",
+      "date_column": "createdAt",
+      "columns": [
+        { "name": "id", "type": "string", "nullable": false, "description": "fsm_<UUIDv7>" },
+        { "name": "createdAt", "type": "datetime", "nullable": false }
+      ]
+    }
+  ]
+}
+```
+
+Consumers SHOULD fetch the manifest on startup to discover available tables, then cache it for the session. The manifest is cheap (~10 KB) but doesn't change between deploys.
+
+### `GET /api/warehouse/growth/<table>?since=&until=&cursor=&limit=`
+
+Returns one page of rows from the named table. Keyset pagination on the cursor column.
+
+Query params:
+
+| Param | Type | Default | Notes |
+|---|---|---|---|
+| `since` | ISO 8601 | none | Filters `<date_column> >= since`. Omit to start from the beginning. |
+| `until` | ISO 8601 | none | Filters `<date_column> <  until`. Exclusive upper bound. |
+| `cursor` | string | none | Opaque cursor returned from the previous page's `next_cursor`. |
+| `limit` | integer | 1000 | Page size. Capped at 5000. |
+
+Response shape:
+
+```json
+{
+  "table": "lead_intake",
+  "row_count": 1000,
+  "rows": [{ "id": "fsm_...", "firstName": "...", "createdAt": "2026-05-12T..." }],
+  "next_cursor": "fsm_...",
+  "has_more": true,
+  "served_at": "2026-05-12T20:00:01.234Z"
+}
+```
+
+Pagination loop on the consumer:
+
+```python
+cursor = None
+while True:
+    response = get(f"/api/warehouse/growth/lead_intake?since={since}&cursor={cursor}&limit=2000")
+    yield from response["rows"]
+    if not response["has_more"]:
+        break
+    cursor = response["next_cursor"]
+```
+
+## Exposed tables
+
+The current whitelist (v1; see `growth/src/modules/warehouse-api/schema.ts` for the canonical list and full column descriptors):
+
+| Table | Grain | Primary key | Cursor column | Date column |
+|---|---|---|---|---|
+| `lead_intake` | One per form submission | `id` (`fsm_<UUIDv7>`) | `id` | `createdAt` |
+| `lead_attribution` | One per visitor-id-stitched touch | `id` (`lat_<UUIDv7>`) | `id` | `capturedAt` |
+| `campaign` | One per campaign | `id` (`cmp_<UUIDv7>`) | `id` | `createdAt` |
+| `campaign_external_mapping` | One per (platform, ext acct, ext campaign) | `id` (`cem_<UUIDv7>`) | `id` | `createdAt` |
+| `campaign_spend_daily` | One per (campaign, date, source) | `id` (`csd_<UUIDv7>`) | `id` | `date` |
+| `qualified_intake` | One per qualified form_submission | `formSubmissionId` (`fsm_<UUIDv7>`) | `formSubmissionId` | `firstQualifiedAt` |
+| `lead_intake_correlation` | One per Sales Lead | `leadId` (`lead_<UUIDv7>`) | `leadId` | `observedAt` |
+| `subscriber` | One per email signup | `id` (`sub_<UUIDv7>`) | `id` | `createdAt` |
+| `acquisition_suppression` | One per archived person | `person_id` (`per_<UUIDv7>`) | `person_id` | `archived_at` |
+| `intake_event_correlation` | One per intake.captured emit | `eventId` (`evt_<UUIDv7>`) | `eventId` | `emittedAt` |
+
+The `growth.touchpoint` warehouse view (the fully-resolved, person-keyed funnel attribution surface) is NOT in this API. It lives in the dbt warehouse and is queryable via SQL only, by design: it depends on Platform's `intake.matched` events and would couple the API to the warehouse DSN. Forecasting consumers that need it should connect to the warehouse Postgres directly.
+
+## Column type encoding
+
+The manifest's column `type` values map to JSON values like this:
+
+| Manifest type | JSON value | Notes |
+|---|---|---|
+| `string` | string | Trimmed/normalized per Growth's writers. |
+| `bigint_string` | string | int8 / BigInt columns serialized as decimal strings to avoid JS Number precision loss. `spendCents` is the only field that uses this today. |
+| `number` | number | Standard JSON number. |
+| `boolean` | boolean | |
+| `datetime` | string (ISO 8601 UTC) | Postgres `timestamp(3)` → `2026-05-12T20:00:00.000Z`. Date-only columns (e.g., `campaign_spend_daily.date`) also serialize as ISO timestamps with midnight UTC. |
+| `json` | object/array | JSONB columns. |
+| `null_only` | null | Reserved; not currently used. |
+
+Null values come through as JSON null regardless of declared type.
+
+## Refresh cadence
+
+Reads are against Growth's live Postgres (the same database Growth's app writes to). There is no replication lag. The data is real-time to within transactional commit visibility.
+
+If/when this API moves to read from the warehouse Postgres (dbt-compiled views, separate Supabase project), the response will gain a `replication_lag_seconds` field and the warehouse refresh cadence will be documented here. Consumers should treat that future field as optional and degrade gracefully when it is absent.
+
+## Versioning
+
+Additive changes (new tables, new columns on existing tables, new optional query params) bump the manifest's column / table list without changing `api_version`.
+
+Breaking changes (removing a table, renaming a column, changing a column's type) bump `api_version` to 2 and ship a new path prefix (`/api/warehouse/growth/v2/...`) with a deprecation window of at least two weeks during which both versions are served.
+
+`acquisition_suppression`'s column names use snake_case (`person_id`, `archived_at`) where the rest use camelCase. This is because the underlying table maps differently in Prisma; consumers should treat column casing as opaque and rely on the manifest's `columns[].name`.
+
+## Out of scope for v1
+
+- Aggregations or derived models. Consumers do their own rollups. If a derived view becomes load-bearing, it lands as a dbt model in the warehouse, not as an API endpoint.
+- Write access. The API is read-only. Mutations to Growth data flow through Growth's existing app routes.
+- Cross-domain joins. The API exposes Growth-domain raw data only. Joins against Person facts (Platform), Lead lifecycle (Sales), Revenue ledger, etc. happen on the consumer side or via the dbt warehouse where source declarations from multiple domains can join.
+
+## Operational
+
+- Env var on Growth's deploy: `THEM_OS_API_KEY` (generate strong; rotate annually or on compromise).
+- Same value on Them OS's outbound credential store.
+- Rate limit: not yet implemented; v1 trusts the bearer token. If a second consumer joins, add per-token rate limits before issuing the second token.
+- Observability: every request logs to console (Vercel function logs) with the table name and the row count served. Add per-request latency tracking when usage grows past trivial.
+
+## References
+
+- API module source: `growth/src/modules/warehouse-api/`
+- Route handlers: `growth/src/app/api/warehouse/growth/manifest/route.ts` and `growth/src/app/api/warehouse/growth/[table]/route.ts`
+- dbt source declarations (parallel surface for SQL consumers): `platform/warehouse/models/sources/growth.yml`
+- Growth domain doc: `coordination/domains/growth.md`
+- Person archive propagation (where `acquisition_suppression` came from): `coordination/memos/2026/2026-05-11-platform-archive-propagation-sales-growth.md`