@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/portfolio-mart/README.md

@@ -0,0 +1,133 @@
+# Portfolio Mart Contract
+
+**Status:** v1.2.0
+**Date:** 2026-05-19
+**Owner:** portfolio (derived portfolio store and the portfolio gold section)
+**Consumers:** strategy reporting consumers (leadership and operator dashboards); no operational domain consumes this contract
+**Related ADRs:** ADR-0015, ADR-0016, ADR-0003, ADR-0013, ADR-0014
+**Sub-specs (authoritative):** cross-market-performance.md, cross-discipline-performance.md, portfolio-level-funnel-health.md, org-topology.md, health-composites.md, cohort-funnel-panel.md
+**Validations:** consumer-isolation.md, decoupling-discipline.md
+
+## 1. Purpose and scope
+
+The Portfolio Mart Contract specifies the read surface of the `portfolio` section of the gold mart (ADR-0016): the cross-domain strategy metrics that leadership reads to see how the business performs across Markets, across disciplines, and across the funnel from acquisition through delivery. Portfolio composes these metrics over the warehouse silver tier and the conformed identity and geography spine, materializes them into its derived portfolio store, and serves them through this contracted section. The contract is what lets strategy reporting consumers build on a stable surface rather than on Portfolio's internal store shape, and it is the artifact that defines the firewall bound for the portfolio consumer tag per ADR-0016.
+
+Portfolio is a cross-domain reporting domain per ADR-0015. It owns no source-of-record data, mints no role records, and produces no domain events. Every fact in this contract originates in another domain and reaches Portfolio through silver. The contract therefore specifies a read surface and the guarantees Portfolio makes about it; it specifies no write path, no event, and no operational behavior.
+
+In scope: the served surface and how it is read, the grain and dimensions the mart is keyed by, the metric families the section exposes, the identity and dedup rules the composition follows, the versioning and deprecation policy, and the consumer and producer responsibilities. Out of scope: the silver tier shape (the `warehouse-silver` contract, owned by Platform), the gold mart shell and the consumer-firewall mechanism (Platform, per ADR-0016), financial reporting metrics (the `finance-mart` contract, owned by Finance per ADR-0015), any operational domain's per-domain gold section, canonical geography and Organization records (Platform, per ADR-0013 and ADR-0014), and Person identity (Platform). If a metric belongs to one operating domain, or is financial, or is a source-of-record fact, it does not belong in this contract.
+
+## 2. Normative language
+
+The key words MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, and MAY are to be interpreted per RFC 2119.
+
+## 3. Terminology
+
+- **Portfolio section**: the `portfolio` section of the single gold mart (ADR-0016), built across silver faces and the spine. The materialized surface this contract governs.
+- **Derived portfolio store**: Portfolio's own Prisma deployment, where composed metrics are materialized before they are served. An implementation detail of the producer, not part of the contracted surface.
+- **Silver face**: one conforming dbt view per warehouse, per the `warehouse-silver` contract. Portfolio reads across the five faces (growth, sales, delivery, coaching, revenue).
+- **Identity and geography spine**: the conformed reference dimension carrying the Person dimension and the Organization to Market analytics geography hierarchy, per the `warehouse-silver` contract. Service Area and Lesson Site are Platform-owned operational reference data and appear in this contract only as source-backed passthrough keys where a family manifest names them. Portfolio leans hardest on the spine.
+- **Discipline**: an operating unit modeled as its own Organization per ADR-0014. Cross-discipline metrics aggregate across these Organizations.
+- **Metric family**: a coherent group of strategy metrics sharing a grain and a dimensional key (for example cross-Market performance). Each family is the unit of the per-family column manifests named under future work.
+- **Strategy reporting consumer**: a leadership-facing or operator-facing dashboard or report that reads the portfolio section. Not a domain in the closed set; no operational domain consumes this contract.
+
+## 4. Surface
+
+### 4.1 The served surface
+
+The portfolio section is materialized, not computed per query, per the gold tier model in ADR-0016. Consumers read the section through the gold mart's consumer-firewall mechanism: the portfolio consumer tag is bounded by this contract, so a strategy reporting consumer sees the cross-silver composition this contract defines and nothing outside it. The firewall bound is contract-shaped rather than warehouse-shaped, which is the distinction ADR-0016 draws between a reporting section and an operational section.
+
+Every row the section serves carries an `as_of` timestamp (UTC ISO 8601) recording the refresh point of the underlying materialization. Consumers SHALL treat `as_of` as the freshness signal and SHALL NOT assume the section is real-time; it is materialized on the gold refresh cadence, which Platform owns and documents.
+
+### 4.2 Grain and dimensions
+
+Portfolio metrics are aggregate. The section exposes no Person-grain rows. Every metric family is keyed by some subset of the following dimensions. Market and Organization come from the conformed identity and geography spine; Service Area is a source-backed passthrough dimension only when a family manifest names it.
+
+- **Market**: the Platform-owned canonical geography dimension per ADR-0013. Portfolio reports across Markets; it does not mint or edit them.
+- **Service Area**: optional source-backed passthrough key on a silver face. Portfolio may slice by Service Area only where the relevant family manifest names the dependency and the contributing face carries it.
+- **Organization (discipline)**: each discipline as its own Organization per ADR-0014.
+- **Time period**: a conformed calendar grain (day, week, month, quarter). The smallest grain a family supports is named in that family's manifest.
+- **Funnel stage**: a conformed acquisition-through-delivery stage label, used by the funnel-health family.
+
+A metric family MUST declare its dimensional key in its manifest. A consumer reading a family SHALL key on the declared dimensions and SHALL NOT infer a finer grain than the family exposes.
+
+### 4.3 Metric families
+
+v1.2.0 contracts six metric families and names each family's exact column list in authoritative sibling manifests. This README contracts the family boundaries, the grain, and the cross-cutting rules.
+
+**Cross-Market performance.** How the business performs across Markets and, where source-backed, Service Areas: the steering metrics that compare one Market to another, keyed by Market or optional Service Area and time period. The family answers "which Markets are growing, which are not, and on what signal." The column manifest is `cross-market-performance.md`.
+
+**Cross-discipline performance.** How the business performs across disciplines, keyed by Organization and time period, with cross-discipline rollups that follow the dedup rule in §4.5. The family answers "how does each discipline perform, and what does the portfolio look like aggregated across all of them." The column manifest is `cross-discipline-performance.md`.
+
+**Portfolio-level funnel health.** The health of the funnel from acquisition through delivery at the portfolio grain, keyed by funnel stage and time period and optionally by Market or Organization. The family answers "where is the cross-domain funnel converting and where is it leaking," composed from the growth, sales, revenue, delivery, and coaching silver faces. The column manifest is `portfolio-level-funnel-health.md`.
+
+**Org topology.** The structure of the portfolio: the organizations (disciplines) and org-markets (Market × discipline operating units) that constitute the portfolio, their active status, and their age distribution. Keyed by Organization or org-market and snapshot-day. Sourced from the conformed identity and geography spine exclusively; this family reads no silver face. The column manifest is `org-topology.md`.
+
+**Health composites.** Composite health indicators at the org-market, org, and portfolio level, each derived by applying a declared formula over constituent metrics from the cross-Market performance and cross-discipline performance families. The family answers "what is the overall health signal for each operating unit, for each discipline, and for the portfolio as a whole." The column manifest is `health-composites.md`.
+
+**Cohort funnel panel.** A cross-domain cohort view of the customer funnel: for each intake cohort, the non-financial panel of counts from acquisition through delivery (intake, first credit reservation, completed lessons, status as of now). Keyed by org-market and intake-cohort week with current-week as a second axis. Composed from growth, revenue (reservation state only, not financial amounts), and delivery silver faces. Financial columns (revenue earned and paid at cohort grain) are served by the `finance-mart` `cohort_summary` sub-section; callers assemble the full §9 cohort panel by joining the two sections on the cohort key. The column manifest is `cohort-funnel-panel.md`.
+
+### 4.4 What the portfolio section does not expose
+
+- **No source-of-record data.** The section exposes composed metrics, not the underlying domain records. A consumer needing a domain's operational records reads that domain's surface, not this one.
+- **No financial metrics.** Revenue, margin, cash position, and reconciliation are the `finance-mart` contract's surface per ADR-0015. The boundary is grain and authority: if the question is financial, it is Finance's.
+- **No per-domain operational metrics.** A metric that belongs to one operating domain is that domain's gold section, not this one. The decoupling discipline in `validation/decoupling-discipline.md` is the producer-side guarantee that such metrics are not absorbed here.
+- **No Person-grain rows and no events.** The section is aggregate-only, and Portfolio produces nothing on the event envelope.
+
+### 4.5 Identity and dedup rule
+
+Portfolio does not mint Person and does not own Person identity. Cross-domain and cross-Organization joins go through `person_id` per ADR-0003; Person, geography, and Organization facts come from the conformed identity and geography spine, never from a shadow copy and never by reaching into another domain's storage. Cross-discipline counts follow ADR-0014's Person-level dedup rule: a person active in two disciplines is counted once in a portfolio-level rollup and once per discipline in the per-discipline cut, and a family's manifest names which of the two it reports. Consumers SHALL NOT sum per-discipline cuts to reconstruct a portfolio total; the deduped portfolio rollup is the authoritative cross-discipline figure.
+
+## 5. Versioning policy
+
+### 5.1 Semantic versioning
+
+- **Patch** (1.0.0 to 1.0.1): editorial clarifications, typo fixes. No change to the served surface.
+- **Minor** (1.x.y to 1.x+1.0): additive changes. A new metric family, a new column on an existing family, a new optional dimension. Consumers on older minors continue to work.
+- **Major** (1.x.y to 2.0.0): breaking changes. Removing or renaming a family or a column, changing a column type, changing a family's grain, narrowing a dimensional key.
+
+### 5.2 Deprecation policy
+
+On major-version publication, the previous major enters a two-week deprecation window per the org contract-currency standard. No strategy reporting consumer SHALL run against a deprecated version for more than two weeks after a new major publishes. The deprecation window is planned before the new major ships, not after, per `contracts/README.md`.
+
+### 5.3 Additive discipline within a major
+
+New columns MUST default to null or a backwards-compatible value. A new metric family is additive and does not change existing families. Consumers MUST treat unknown columns and unknown families, added in a later minor, as safe to ignore.
+
+### 5.4 Silver churn is not a contract change
+
+A change to a silver face or the spine does not by itself bump this contract. Portfolio absorbs silver churn in its composition logic. This contract bumps only when the served surface that strategy consumers see changes. That insulation is the point of the reporting-domain tier: silver insulates Portfolio from bronze, and this contract insulates strategy consumers from Portfolio's composition.
+
+## 6. Consumer responsibilities
+
+- A strategy reporting consumer SHALL read the portfolio section through the consumer-firewall tag and SHALL NOT read silver, bronze, another gold section, or Portfolio's derived store directly.
+- A consumer SHALL key on a family's declared dimensions and SHALL NOT infer a finer grain than the family exposes.
+- A consumer SHALL treat `as_of` as the freshness signal and degrade gracefully when the section is materialized behind real time.
+- A consumer SHALL NOT sum per-discipline cuts to reconstruct a portfolio total; it SHALL read the deduped portfolio rollup per §4.5.
+- A consumer SHALL treat unknown columns and unknown families as safe to ignore.
+- An operational domain SHALL NOT consume this contract as an input to operational behavior. The portfolio section is a reporting surface; an operational consumer of it is a trigger to revisit ADR-0015.
+
+## 7. Producer responsibilities
+
+- Portfolio SHALL compose every metric over the silver tier and the spine, never over bronze and never by reaching into another domain's storage.
+- Portfolio SHALL keep cross-domain strategy metrics in the portfolio section and SHALL NOT push a strategy metric back into any per-domain warehouse. This is Portfolio's core decoupling discipline; see `validation/decoupling-discipline.md`.
+- Portfolio SHALL resolve all cross-domain and cross-Organization joins through `person_id` per ADR-0003 and SHALL source Person, geography, and Organization facts from the spine, never from a shadow copy.
+- Portfolio SHALL apply the ADR-0014 Person-level dedup rule to every cross-discipline rollup and SHALL name, in each family's manifest, whether the family reports the deduped portfolio figure or the per-discipline figure.
+- Portfolio SHALL stamp every served row with an `as_of` timestamp reflecting the underlying materialization refresh.
+- Portfolio SHALL plan a two-week deprecation window before publishing any major version, per §5.2.
+- Portfolio SHALL decline, in writing through a memo, any request that belongs to an operational domain, to Finance, or to Platform's geography surface, rather than absorbing it into this contract.
+
+## 8. Security and privacy
+
+The portfolio section is aggregate-only: it exposes no Person-grain rows. The composition reads PII from the spine and the silver faces (`person_id` and conformed Person attributes) to compute deduped cross-discipline counts and funnel metrics, but the served surface carries aggregates, not Person records. Portfolio SHALL apply the same log-hygiene discipline to `person_id` and any Person attribute touched during composition that any consumer of the spine applies. The consumer firewall, a gold-tier mechanism Platform owns, is what scopes the portfolio consumer tag to this contract's surface; access to the section is Platform-controlled through that mechanism. Naming the fact for the next reader: there is no PII on the served surface in v1.0.0, and a future family that would change that is a major-version question, not a minor.
+
+## 9. Future work
+
+- **Per-family validation notes** under `validation/`, proving each family composes only over silver and the spine and holds the decoupling discipline against live traffic.
+- **Refresh-cadence alignment** with Platform's gold materialization decision (ADR-0016 action item 10). When Platform documents the gold refresh cadence and staleness monitoring, this contract gains a stated freshness expectation for the portfolio section.
+- **Consumer registry.** v1.0.0 names strategy reporting consumers as a class. If the set of consumers grows enough that per-consumer scoping within the portfolio tag becomes useful, a consumer registry lands as a minor.
+
+## 10. Change log
+
+- **v1.2.0** (2026-05-19): Adds three new metric families — `org_topology` (portfolio structure: orgs, org-markets, active counts, age distributions; spine-only reads), `health_composites` (composite health indicators at org-market, org, and portfolio grain derived from the cross-Market and cross-discipline families), and `cohort_funnel_panel` (cross-domain non-financial cohort view: intake, first credit reservation, completed lessons, status as of now, keyed by org-market × intake-cohort). The financial cohort columns (revenue earned and paid) are explicitly scoped out of this contract per §4.4 and are served by `finance-mart` v2.0.0 `cohort_summary`; callers assemble the full Them OS §9 cohort panel by joining the two sections. Per-family column manifests land as authoritative sibling files. Uses `created_at` on Organization and OrgMarket rows as the de-facto `active_from_at` source for age-distribution metrics, with a documented caveat in the `org-topology.md` manifest.
+- **v1.1.0** (2026-05-18): Adds authoritative per-family column manifests for cross-Market performance, cross-discipline performance, and portfolio-level funnel health. Clarifies that Market and Organization are spine dimensions while Service Area is an optional source-backed passthrough key where a family manifest names it. Names the served columns, silver input columns, grains, and ADR-0014 person-dedup rules Platform needs to implement the derived portfolio store models.
+- **v1.0.0** (2026-05-14): Initial publication. Establishes the portfolio gold section's served surface, the grain and dimensions, the three v1.0.0 metric families (cross-Market performance, cross-discipline performance, portfolio-level funnel health), the identity and dedup rules, the consumer and producer responsibilities, and the versioning and deprecation policy. Published per ADR-0015 action item 6 and ADR-0016 action item 8.

package/contracts/portfolio-mart/cohort-funnel-panel.md

@@ -0,0 +1,76 @@
+# Cohort Funnel Panel Manifest
+
+**Status:** v1.2.0
+**Date:** 2026-05-19
+**Owner:** portfolio
+**Parent contract:** `portfolio-mart` v1.2.0
+**Family key:** `cohort_funnel_panel`
+**Related:** `2026-05-19-portfolio-mart-v1-2-published`, `2026-05-19-portfolio-cohort-panel-finance-close`
+
+## Purpose
+
+The cohort funnel panel answers how each intake cohort progresses through the non-financial funnel from acquisition through delivery. For each org-market and intake-cohort week, it tracks where the cohort stands today: how many people were captured at intake, how many reserved a credit, how many completed lessons, and what their current status is.
+
+This family is the portfolio section of the cross-domain cohort view the Them OS §9 `cohort_cross_domain_panel` spec defines. It covers the non-financial columns only. The financial columns (`revenue_earned`, `revenue_paid`) are served by `finance-mart` v2.0.0 `cohort_summary` at the same grain; callers assemble the full §9 panel by joining the two sections on the cohort key (`org_market_id` + `intake_cohort_week`).
+
+## Grain
+
+One row per:
+
+- `org_market_id`
+- `intake_cohort_week` (the ISO week of the cohort's first intake touchpoint)
+- `snapshot_week` (the ISO week of the current materialization; the "current-week" axis)
+
+The panel is two-dimensional: `intake_cohort_week` and `snapshot_week`. For each cohort, new rows accumulate each week as the cohort ages. A single cohort (one `intake_cohort_week` value for one org-market) produces one row per snapshot week for as long as the portfolio mart is materialized.
+
+Org-level rollup rows (one row per `organization_id` × `intake_cohort_week` × `snapshot_week`) are served where `org_market_id` is null and `organization_id` is non-null; they sum the non-financial counts across the Organization's active org-markets and use the `distinct_person_id_within_organization` dedup rule for person counts. Portfolio does not serve a cross-org deduped rollup for this family because a person in two disciplines belongs to two separate cohort journeys.
+
+## Served columns
+
+| Column | Type | Required | Definition |
+| --- | --- | --- | --- |
+| `family_key` | string | yes | Constant `cohort_funnel_panel`. |
+| `org_market_id` | string or null | yes | OrgMarket slug from the spine. Null on org-level rollup rows. |
+| `organization_id` | string or null | yes | Organization identifier from the spine. Null on org-market rows. |
+| `organization_name` | string or null | yes | Organization display name from the spine. Null on org-market rows. |
+| `market_id` | string or null | yes | Market identifier from the spine. Null on org-level rollup rows. |
+| `intake_cohort_week` | date | yes | The Monday of the ISO week in which the cohort's first intake touchpoint occurred. The cohort key. |
+| `snapshot_week` | date | yes | The Monday of the ISO week of the current materialization snapshot. |
+| `cohort_age_weeks` | integer | yes | `(snapshot_week − intake_cohort_week) / 7` in complete weeks. |
+| `intake_person_count` | integer | yes | Distinct `person_id` count from `growth.touchpoint` where the touchpoint is an intake-stage touchpoint with the org-market and `intake_cohort_week` slice. Fixed at the cohort's birth week; does not change across snapshot weeks for the same cohort. |
+| `first_reservation_person_count` | integer | yes | Distinct `person_id` count from `revenue.credit_reservation` where the person has a first portfolio-relevant reservation with `reservation_state` indicating locked, and the person belongs to this cohort and org-market slice. Cumulative to `snapshot_week`. |
+| `completed_lesson_person_count` | integer | yes | Distinct `person_id` count from `delivery.attendance` where the person has at least one attended or completed lesson, belongs to this cohort and org-market slice, and the lesson occurred on or before `snapshot_week`. Cumulative to `snapshot_week`. |
+| `intake_to_first_reservation_rate` | decimal or null | yes | `first_reservation_person_count / intake_person_count`; null when denominator is zero or required source columns are unavailable. Increases monotonically as the cohort ages. |
+| `first_reservation_to_completed_lesson_rate` | decimal or null | yes | `completed_lesson_person_count / first_reservation_person_count`; null when denominator is zero or required source columns are unavailable. |
+| `intake_to_completed_lesson_rate` | decimal or null | yes | `completed_lesson_person_count / intake_person_count`; null when denominator is zero. The end-to-end funnel rate for this cohort as of the snapshot week. |
+| `cohort_status_summary` | string | yes | A derived status label for the cohort as of `snapshot_week`. Values: `early` (cohort age < 4 weeks), `converting` (age ≥ 4 weeks, at least one reservation, not all delivered), `delivered` (intake_to_completed_lesson_rate ≥ 0.5), `stalled` (age ≥ 8 weeks, first_reservation_person_count = 0), `partial` (age ≥ 8 weeks, first_reservation_person_count > 0, completed_lesson_person_count = 0). |
+| `dedup_rule` | string | yes | `distinct_person_id_within_org_market_cohort_slice` for org-market rows; `distinct_person_id_within_organization_cohort_slice` for org-level rollup rows. |
+| `as_of` | timestamp | yes | UTC ISO 8601 materialization timestamp. |
+
+## Silver inputs
+
+| Source | Required columns | Use |
+| --- | --- | --- |
+| `growth.touchpoint` | `person_id`, `occurred_at`, `intake_stage`, `org_market_id`, `organization_id`, `market_id` | Cohort assignment (intake week) and intake person count. |
+| `revenue.credit_reservation` | `person_id`, `reserved_at`, `reservation_state`, `org_market_id`, `organization_id` | First credit reservation counts. Reservation state only — no money amounts; this is a funnel-stage signal, not financial reporting. |
+| `delivery.attendance` | `person_id`, `lesson_id`, `attended_at`, `attendance_state`, `org_market_id`, `organization_id` | Completed lesson person counts cumulative to snapshot week. |
+| spine | `org_market_id` (slug), `organization_id`, `organization_name`, `market_id`, `market_name` | Entity identity for row keys and display columns. |
+
+## Composition rules
+
+- Cohort membership is determined at intake: a person belongs to a cohort based on the `intake_cohort_week` of their first intake-stage touchpoint for the org-market slice. If a person has multiple intake touchpoints (re-intakes), the first is canonical. Portfolio does not model re-intake separately in v1.2.
+- `intake_person_count` is immutable after the cohort birth week: it counts people whose first intake touchpoint falls in `intake_cohort_week`. It does not change as `snapshot_week` advances.
+- `first_reservation_person_count` and `completed_lesson_person_count` are cumulative: they count people who have reached the milestone at any point on or before `snapshot_week`, not within a specific calendar window.
+- Revenue inputs are used only for reservation state (whether a credit was reserved). Money amounts are not read. `revenue.credit_reservation.reservation_state` is the funnel-stage signal; `revenue.credit_reservation` financial columns are not read.
+- If a source field named above is absent from the live silver face, the affected column returns `null:upstream_unavailable` and the gap is filed back to Platform.
+- The org-market slug (`org_market_id`) is the cohort key Platform's registry uses for the `org_market_id` grain per ADR-0019. Portfolio uses the slug format, not the UUID.
+
+## Join pattern for the full §9 panel
+
+Callers assembling the Them OS §9 `cohort_cross_domain_panel` join this family's rows to `finance-mart` `cohort_summary` on (`org_market_id`, `intake_cohort_week`, `snapshot_week`). The financial columns `revenue_earned` and `revenue_paid` come from `finance-mart`; the non-financial columns above come from this family. Portfolio does not duplicate or proxy the financial columns.
+
+## Known coverage gaps for Platform assessment
+
+- `growth.touchpoint.org_market_id` is required to key cohort membership by org-market. If the growth face carries only `market_id` and `organization_id` separately (not the compound slug), Platform should derive the slug via the spine join before Portfolio reads it.
+- `revenue.credit_reservation.org_market_id` is required for the reservation count at org-market grain. If the revenue face carries only `market_id` and `organization_id` separately, same pattern applies.
+- `delivery.attendance.org_market_id` is required for the completed lesson count at org-market grain. Same pattern if not in the face.

package/contracts/portfolio-mart/cross-discipline-performance.md

@@ -0,0 +1,91 @@
+# Cross-Discipline Performance Manifest
+
+**Status:** v1.1.0
+**Date:** 2026-05-18
+**Owner:** portfolio
+**Parent contract:** `portfolio-mart` v1.1.0
+**Family key:** `cross_discipline_performance`
+**Related:** `2026-05-18-platform-portfolio-mart-silver-surface-and-firewall-confirmation`
+
+## Purpose
+
+The cross-discipline performance family compares performance by discipline, where each discipline is an Organization per ADR-0014, and serves a portfolio rollup that deduplicates people across disciplines. It answers how each discipline performs and what the portfolio looks like when people active in more than one discipline are counted once.
+
+This family is aggregate-only and reads silver plus the spine. It does not ask an operational domain to compute a cross-domain metric on Portfolio's behalf.
+
+## Grain
+
+One row per:
+
+- `period_grain`
+- `period_start`
+- `period_end`
+- `rollup_scope`
+- `organization_id` when `rollup_scope = discipline`
+
+`rollup_scope` values:
+
+- `discipline`: one row per Organization.
+- `portfolio`: one deduped rollup row across Organizations. `organization_id`, `organization_name`, and `discipline_key` are null on this row.
+
+The smallest supported period grain is `week`.
+
+## Served columns
+
+| Column | Type | Required | Definition |
+| --- | --- | --- | --- |
+| `family_key` | string | yes | Constant `cross_discipline_performance`. |
+| `period_grain` | enum | yes | `week`, `month`, or `quarter`. |
+| `period_start` | date | yes | Inclusive UTC date boundary. |
+| `period_end` | date | yes | Exclusive UTC date boundary. |
+| `rollup_scope` | enum | yes | `discipline` or `portfolio`. |
+| `organization_id` | string or null | yes | Organization identifier from the spine for discipline rows, null for portfolio rollup rows. |
+| `organization_name` | string or null | yes | Organization display name from the spine for discipline rows, null for portfolio rollup rows. |
+| `discipline_key` | string or null | yes | Stable discipline key from the spine for discipline rows, null for portfolio rollup rows. |
+| `intake_person_count` | integer | yes | Distinct `person_id` count from `growth.touchpoint`. |
+| `qualified_lead_person_count` | integer | yes | Distinct `person_id` count from `sales.lead` where the lead reaches qualified state. |
+| `first_reservation_person_count` | integer | yes | Distinct `person_id` count from `revenue.credit_reservation` where the first portfolio-relevant reservation is locked. |
+| `active_participant_person_count` | integer | yes | Distinct `person_id` count from `delivery.attendance` where the person attended or completed a lesson. This is the authoritative active customer denominator. |
+| `scheduled_lesson_count` | integer | yes | Distinct `lesson_id` count from `delivery.lesson` where a lesson is scheduled. |
+| `completed_lesson_count` | integer | yes | Distinct `lesson_id` count from `delivery.attendance` where attendance marks the lesson completed or attended. |
+| `active_coach_person_count` | integer | yes | Distinct coach `person_id` count from `coaching.coach` where the coach is active. |
+| `confirmed_booking_count` | integer | yes | Distinct booking count from `coaching.lesson_booking` where the booking is confirmed. |
+| `intake_to_active_participant_rate` | decimal or null | yes | `active_participant_person_count / intake_person_count`; null when denominator is zero or required source columns are unavailable. |
+| `coach_to_completed_lesson_ratio` | decimal or null | yes | `completed_lesson_count / active_coach_person_count`; null when denominator is zero or required source columns are unavailable. |
+| `dedup_rule` | string | yes | `distinct_person_id_within_organization` for discipline rows; `distinct_person_id_across_organizations` for portfolio rows. |
+| `as_of` | timestamp | yes | UTC ISO 8601 materialization timestamp. |
+
+## Silver inputs
+
+| Source | Required columns | Use |
+| --- | --- | --- |
+| spine | `organization_id`, `organization_name`, `discipline_key` | Discipline identity and Organization attributes. |
+| `growth.touchpoint` | `person_id`, `organization_id`, `occurred_at`, `intake_stage` | Intake counts by Organization and portfolio rollup. |
+| `sales.lead` | `person_id`, `organization_id`, `created_at`, `qualified_at`, `lead_stage`, `lead_substage` | Qualified lead counts by Organization and portfolio rollup. |
+| `revenue.credit_reservation` | `person_id`, `organization_id`, `reserved_at`, `reservation_state` | First reservation counts by Organization and portfolio rollup. |
+| `delivery.lesson` | `person_id`, `organization_id`, `lesson_id`, `scheduled_start_at`, `lesson_state` | Scheduled lesson counts by Organization and portfolio rollup. |
+| `delivery.attendance` | `person_id`, `organization_id`, `lesson_id`, `attended_at`, `attendance_state` | Active participant denominator and completed lesson counts. |
+| `coaching.coach` | `person_id`, `organization_id`, `coach_state`, `active_from_at`, `active_until_at` | Active coach denominator. |
+| `coaching.lesson_booking` | `person_id`, `organization_id`, `booking_id`, `booking_start_at`, `booking_state` | Confirmed booking counts. |
+
+## Dedup rule
+
+Discipline rows count a person once within an Organization and period. Portfolio rollup rows count a person once across all Organizations and period, even when the person appears in two disciplines. Consumers must read the `portfolio` rollup row for portfolio totals and must not sum `discipline` rows to reconstruct a portfolio total.
+
+The authoritative person-count denominator for active customers is `delivery.attendance.person_id` where `attendance_state` indicates attended or completed. `delivery.lesson.person_id` is not the active customer denominator because scheduled lessons can exist without attendance.
+
+The authoritative person-count denominator for active coaches is `coaching.coach.person_id` where `coach_state` indicates active during the period. `coaching.lesson_booking.person_id` is not the active coach denominator because a coach can be active without a confirmed booking in the period.
+
+## Composition rules
+
+- Each person metric uses `COUNT(DISTINCT person_id)` at the declared row key.
+- Each lesson metric uses `COUNT(DISTINCT lesson_id)` at the declared row key.
+- Each booking metric uses `COUNT(DISTINCT booking_id)` at the declared row key.
+- Revenue inputs are used only as non-financial funnel signals. Money amounts, margin, cash, and reconciliation remain Finance-owned.
+- If a source field named above is absent from the live silver face, the affected metric returns `null:upstream_unavailable` and the gap is filed back to Platform.
+
+## Known coverage gaps for Platform assessment
+
+- `discipline_key` is required for a stable discipline label. If the spine exposes Organization but not a separate discipline key, Organization is sufficient for v1.1.0 and `discipline_key` may mirror `organization_id` until Platform names a stable display-safe key.
+- `sales.lead.qualified_at` is required for period-correct qualified counts. If Sales silver carries only current lead stage, qualified lead counts by historical period should stay null until a source-backed qualification timestamp exists.
+- `coaching.lesson_booking.booking_id` is required for confirmed booking counts. If the live face names the booking identifier differently, Platform should map it through silver naming conformance rather than requiring Portfolio to depend on a source-local name.

package/contracts/portfolio-mart/cross-market-performance.md

@@ -0,0 +1,84 @@
+# Cross-Market Performance Manifest
+
+**Status:** v1.1.0
+**Date:** 2026-05-18
+**Owner:** portfolio
+**Parent contract:** `portfolio-mart` v1.1.0
+**Family key:** `cross_market_performance`
+**Related:** `2026-05-18-platform-portfolio-mart-silver-surface-and-firewall-confirmation`
+
+## Purpose
+
+The cross-Market performance family compares operating performance by Market and, where a source face carries it, by Service Area. It answers which Markets are growing, which are not, and on which source-backed signal.
+
+This family is aggregate-only. It reads silver faces and the conformed spine. It does not read bronze, another gold section, or a domain source database.
+
+## Grain
+
+One row per:
+
+- `period_grain`
+- `period_start`
+- `period_end`
+- `market_id`
+- optional `service_area_id`
+
+`market_id` and `market_name` come from the conformed spine. `service_area_id` and `service_area_name` are optional source-backed passthrough keys when a contributing silver face carries them. If a face does not carry Service Area, Service Area columns are `null` and the row is Market-grain.
+
+The smallest supported period grain is `week`. Daily rows are out of scope for v1.1.0.
+
+## Served columns
+
+| Column | Type | Required | Definition |
+| --- | --- | --- | --- |
+| `family_key` | string | yes | Constant `cross_market_performance`. |
+| `period_grain` | enum | yes | `week`, `month`, or `quarter`. |
+| `period_start` | date | yes | Inclusive UTC date boundary. |
+| `period_end` | date | yes | Exclusive UTC date boundary. |
+| `market_id` | string | yes | Platform-owned Market identifier from the spine. |
+| `market_name` | string | yes | Market display name from the spine. |
+| `service_area_id` | string or null | no | Source-backed passthrough Service Area identifier, where present. |
+| `service_area_name` | string or null | no | Source-backed passthrough Service Area display name, where present. |
+| `intake_person_count` | integer | yes | Distinct `person_id` count from `growth.touchpoint` where the touchpoint is an intake-stage touchpoint in the period and slice. |
+| `qualified_lead_person_count` | integer | yes | Distinct `person_id` count from `sales.lead` where the lead reaches a qualified stage in the period and slice. |
+| `first_reservation_person_count` | integer | yes | Distinct `person_id` count from `revenue.credit_reservation` where the first portfolio-relevant reservation is locked in the period and slice. |
+| `scheduled_lesson_count` | integer | yes | Distinct `lesson_id` count from `delivery.lesson` where a lesson is scheduled in the period and slice. |
+| `completed_lesson_count` | integer | yes | Distinct `lesson_id` count from `delivery.attendance` where attendance marks the lesson completed or attended in the period and slice. |
+| `active_participant_person_count` | integer | yes | Distinct `person_id` count from `delivery.attendance` where the person attended or completed at least one lesson in the period and slice. |
+| `active_coach_person_count` | integer | yes | Distinct coach `person_id` count from `coaching.coach` where the coach is active in the period and slice. |
+| `intake_to_qualified_rate` | decimal or null | yes | `qualified_lead_person_count / intake_person_count`; null when denominator is zero or required source columns are unavailable. |
+| `qualified_to_first_reservation_rate` | decimal or null | yes | `first_reservation_person_count / qualified_lead_person_count`; null when denominator is zero or required source columns are unavailable. |
+| `first_reservation_to_completed_lesson_rate` | decimal or null | yes | Distinct people with completed attendance after first reservation divided by `first_reservation_person_count`; null when denominator is zero or required source columns are unavailable. |
+| `person_dedup_basis` | string | yes | Constant `distinct_person_id_within_market_slice`. |
+| `as_of` | timestamp | yes | UTC ISO 8601 materialization timestamp. |
+
+## Silver inputs
+
+| Source | Required columns | Use |
+| --- | --- | --- |
+| `growth.touchpoint` | `person_id`, `occurred_at`, `market_id`, `intake_stage` | Intake person counts. |
+| `growth.touchpoint` | `service_area_id` | Optional Service Area slice when source-backed. |
+| `sales.lead` | `person_id`, `created_at`, `qualified_at`, `market_id`, `lead_stage`, `lead_substage` | Qualified lead counts and intake-to-qualified conversion. |
+| `sales.lead` | `service_area_id` | Optional Service Area slice when source-backed. |
+| `revenue.credit_reservation` | `person_id`, `reserved_at`, `reservation_state`, `market_id` | First reservation counts and qualified-to-reservation conversion. |
+| `revenue.credit_reservation` | `service_area_id` | Optional Service Area slice when source-backed. |
+| `delivery.lesson` | `person_id`, `lesson_id`, `scheduled_start_at`, `lesson_state`, `market_id` | Scheduled lesson counts. |
+| `delivery.lesson` | `service_area_id` | Optional Service Area slice when source-backed. |
+| `delivery.attendance` | `person_id`, `lesson_id`, `attended_at`, `attendance_state`, `market_id` | Completed lesson and active participant counts. |
+| `delivery.attendance` | `service_area_id` | Optional Service Area slice when source-backed. |
+| `coaching.coach` | `person_id`, `coach_state`, `active_from_at`, `active_until_at`, `market_id` | Active coach counts. |
+| `coaching.coach` | `service_area_id` | Optional Service Area slice when source-backed. |
+
+## Composition rules
+
+- Counts that name people use `COUNT(DISTINCT person_id)` within the row key.
+- Counts that name lessons use `COUNT(DISTINCT lesson_id)` within the row key.
+- Market attributes are joined from the spine. Portfolio does not persist shadow Market attributes in the derived store beyond the materialized aggregate row.
+- Revenue inputs are used only as non-financial funnel signals. Money amounts, margin, cash, and reconciliation remain Finance-owned.
+- If a source field named above is absent from the live silver face, the affected metric returns `null:upstream_unavailable` and the gap is filed back to Platform.
+
+## Known coverage gaps for Platform assessment
+
+- `service_area_id` is optional in this family because `warehouse-silver` v1.1.0 contracts Org and Market as analytics spine dimensions. Service Area may be used only where the live face carries it as source-backed passthrough.
+- `sales.lead.qualified_at` is required for period-correct qualified counts. If Sales silver carries only current lead stage, Platform should treat qualified conversion timing as a gap rather than deriving it from current state.
+- `coaching.coach.market_id` is required for active coach counts by Market. If coach Market assignment lives only on booking rows, active coach counts should stay null until the source-backed coach Market assignment is available.

package/contracts/portfolio-mart/health-composites.md

@@ -0,0 +1,88 @@
+# Health Composites Manifest
+
+**Status:** v1.2.0
+**Date:** 2026-05-19
+**Owner:** portfolio
+**Parent contract:** `portfolio-mart` v1.2.0
+**Family key:** `health_composites`
+**Related:** `2026-05-19-portfolio-mart-v1-2-published`
+
+## Purpose
+
+The health composites family provides a single composite health indicator at three altitudes — org-market, org, and portfolio — giving leadership one signal per operating unit per week rather than requiring them to synthesize across the performance families themselves. It answers "is this market healthy this week?", "is this discipline healthy?", and "what is the portfolio's overall health signal?"
+
+This family is a derived family: every constituent metric is computed by the cross-Market performance and cross-discipline performance families. The health composites cannot be materialized until both of those families have live data for the same period and slice. Portfolio declares the formula; Platform implements the aggregation once the constituent families are populated.
+
+## Grain
+
+One row per entity × per-week:
+
+- **`org_market` rows**: one row per OrgMarket × week.
+- **`org` rows**: one row per Organization × week, aggregated across that Organization's active org-markets.
+- **`portfolio` rows**: one row per portfolio × week, aggregated across all Organizations.
+
+The smallest supported period grain is `week`.
+
+## Formula declaration
+
+The composite is a weighted mean of a declared constituent metric set drawn from the v1.1.0 families. Portfolio declares the constituent set and their weights here; Platform encodes these weights in the registry's `_composite_formula` field.
+
+### Constituent metrics and weights (org-market grain)
+
+The `org_market_health` score is a weighted mean of the following rate columns from `cross_market_performance`, all read at the same org-market × week slice:
+
+| Constituent | Weight | Rationale |
+| --- | --- | --- |
+| `intake_to_qualified_rate` | 0.25 | Top-of-funnel health signal. |
+| `qualified_to_first_reservation_rate` | 0.35 | Close-rate signal; most directly operator-controllable. |
+| `first_reservation_to_completed_lesson_rate` | 0.40 | Delivery follow-through; the outcome signal. |
+
+Each rate column is already bounded [0, 1] or null. The composite is computed only when all three constituent columns are non-null for the slice; when any constituent is null, `org_market_health` is null with `allowed_null_reasons: [upstream_unavailable]`.
+
+The composite is a linear weighted mean, not a geometric mean or log-scaled blend: `health = 0.25 × r1 + 0.35 × r2 + 0.40 × r3`.
+
+### Org-level rollup
+
+`org_health` is the weighted mean of the constituent `org_market`s' `org_market_health` scores, weighted by each org-market's `active_participant_person_count` from `cross_discipline_performance` for the same period. This is the `weighted_mean_by_active_participant_count` rollup rule. An org-market with no active participants in the period contributes a weight of 0 (does not distort the rollup) but is still counted in the org-market availability check: if any org-market in the Org has non-null `org_market_health`, the org health is computed; otherwise null.
+
+### Portfolio-level rollup
+
+`portfolio_health` is the weighted mean of all Organizations' `org_health` scores, weighted by each Organization's total `active_participant_person_count` from `cross_discipline_performance` using the `distinct_person_id_across_organizations` dedup rule for the same period. This prevents double-counting people active in two disciplines when weighting the portfolio composite.
+
+## Served columns
+
+| Column | Type | Required | Definition |
+| --- | --- | --- | --- |
+| `family_key` | string | yes | Constant `health_composites`. |
+| `period_grain` | enum | yes | `week` (the only supported grain in v1.2.0). |
+| `period_start` | date | yes | Inclusive UTC date boundary. |
+| `period_end` | date | yes | Exclusive UTC date boundary. |
+| `entity_type` | enum | yes | `org_market`, `org`, or `portfolio`. |
+| `organization_id` | string or null | yes | Organization identifier from the spine. Null on `portfolio` rows. |
+| `organization_name` | string or null | yes | Organization display name from the spine. Null on `portfolio` rows. |
+| `org_market_id` | string or null | yes | OrgMarket slug from the spine. Null on `org` and `portfolio` rows. |
+| `market_id` | string or null | yes | Market identifier. Null on `org` and `portfolio` rows. |
+| `health_score` | decimal or null | yes | The composite health indicator in [0, 1]. Null when any required constituent is unavailable (`allowed_null_reasons: [upstream_unavailable]`). |
+| `constituent_count` | integer | yes | Number of constituent org-markets that contributed to the composite (for `org` and `portfolio` rows). Always 1 on `org_market` rows. |
+| `rollup_weight_basis` | string | yes | `weighted_mean_by_rate_formula` for `org_market` rows; `weighted_mean_by_active_participant_count` for `org` rows; `weighted_mean_by_active_participant_count_cross_org_dedup` for `portfolio` rows. |
+| `composite_formula_version` | string | yes | A stable version tag for the declared formula. Current: `v1`. Formula changes are MAJOR version bumps on this family manifest. |
+| `as_of` | timestamp | yes | UTC ISO 8601 materialization timestamp. |
+
+## Constituent family dependencies
+
+| Constituent family | Required columns |
+| --- | --- |
+| `cross_market_performance` | `intake_to_qualified_rate`, `qualified_to_first_reservation_rate`, `first_reservation_to_completed_lesson_rate` at `org_market × week` grain |
+| `cross_discipline_performance` | `active_participant_person_count` at `discipline × week` grain (for org-level weighting) and `distinct_person_id_across_organizations` deduped rollup (for portfolio weighting) |
+| `org_topology` | `org_market_active_count_in_org` (to know how many org-markets are in each org in the period) |
+
+## Composition rules
+
+- A formula change (any weight change, any constituent swap) is a MAJOR version bump on this manifest. Consumers downstream of `health_score` that build on this family need to know when the number changes because the formula changed, not because the underlying operational reality changed. The `composite_formula_version` field surfaces this on every row.
+- All constituent metrics must be read at the same period grain and the same entity slice. Portfolio does not mix grains within a composite row.
+- The health score is bounded [0, 1] by construction (all constituent rates are bounded [0, 1]). Platform should validate this invariant at materialization time and flag any out-of-range values as a computation error, not surface them.
+- The `portfolio` rollup uses the cross-discipline dedup rule from `cross_discipline_performance`; Platform MUST use the `distinct_person_id_across_organizations` deduped `active_participant_person_count` for the portfolio-level weight, not the sum of per-discipline counts. Summing per-discipline counts would double-count people active in two disciplines and distort the weight toward larger multi-discipline operating units.
+
+## Known implementation sequence
+
+Platform should implement this family last among the v1.2 families. The constituent families must have live data before composite materialization is meaningful. Implement in order: `org_topology` → `cross_market_performance` and `cross_discipline_performance` (already contracted in v1.1.0) → `cohort_funnel_panel` → `health_composites`.

package/contracts/portfolio-mart/org-topology.md

@@ -0,0 +1,70 @@
+# Org Topology Manifest
+
+**Status:** v1.2.0
+**Date:** 2026-05-19
+**Owner:** portfolio
+**Parent contract:** `portfolio-mart` v1.2.0
+**Family key:** `org_topology`
+**Related:** `2026-05-19-portfolio-mart-v1-2-published`
+
+## Purpose
+
+The org topology family exposes the structure of the portfolio: which Organizations (disciplines) and org-markets (Market × discipline operating units) exist, which are active, and how old each is. It answers the structural context questions that make the performance families interpretable to leadership — "how many markets does Swim operate in?", "which org-markets are newest?", "how many active operating units are in the portfolio today?"
+
+This family reads the conformed identity and geography spine exclusively. It reads no silver face. Canonical geography and Organization records are Platform-owned per ADR-0013 and ADR-0014; Portfolio reads them, it does not mint or edit them.
+
+## Grain
+
+Two distinct row kinds, declared by `entity_type`:
+
+- **`org` rows**: one row per Organization × snapshot-day.
+- **`org_market` rows**: one row per OrgMarket × snapshot-day.
+
+Rollup rows (one row per portfolio × snapshot-day) are covered by the `org_active_count` and `org_market_active_count` columns on a sentinel row where both `organization_id` and `org_market_id` are null and `entity_type = portfolio_rollup`.
+
+The smallest supported snapshot grain is `day`.
+
+## Served columns
+
+| Column | Type | Required | Definition |
+| --- | --- | --- | --- |
+| `family_key` | string | yes | Constant `org_topology`. |
+| `snapshot_date` | date | yes | UTC date of the materialization snapshot. |
+| `entity_type` | enum | yes | `org`, `org_market`, or `portfolio_rollup`. |
+| `organization_id` | string or null | yes | Organization identifier from the spine. Null on `portfolio_rollup` rows. |
+| `organization_name` | string or null | yes | Organization display name from the spine. Null on `portfolio_rollup` rows. |
+| `discipline_key` | string or null | yes | Stable discipline key from the spine. Null on `portfolio_rollup` rows. |
+| `org_market_id` | string or null | yes | OrgMarket slug from the spine (`{org_slug}-{market_slug}` format per Platform's ADR-0019 slug column). Null on `org` and `portfolio_rollup` rows. |
+| `market_id` | string or null | yes | Market identifier from the spine. Null on `org` and `portfolio_rollup` rows. |
+| `market_name` | string or null | yes | Market display name from the spine. Null on `org` and `portfolio_rollup` rows. |
+| `status` | string | yes | Current status from the spine: `active` or `inactive`. For `portfolio_rollup` rows, always `active` (the rollup is always materialized). |
+| `created_at` | timestamp | yes | UTC ISO 8601 row-creation timestamp from the spine. Used as the de-facto activation timestamp (see caveat below). |
+| `tenure_weeks` | integer | yes | `floor((snapshot_date − date(created_at)) / 7)`. The number of complete weeks since the entity was created. |
+| `org_active_count` | integer or null | yes | Count of active `org` rows in the portfolio on the snapshot date. Populated on `portfolio_rollup` rows; null on `org` and `org_market` rows. |
+| `org_market_active_count` | integer or null | yes | Count of active `org_market` rows in the portfolio on the snapshot date. Populated on `portfolio_rollup` rows; null on `org` and `org_market` rows. |
+| `org_market_active_count_in_org` | integer or null | yes | Count of active `org_market` rows within the Organization on the snapshot date. Populated on `org` rows; null on `org_market` and `portfolio_rollup` rows. |
+| `age_bucket` | string | yes | Tenure bucket: `0-12w`, `13-26w`, `27-52w`, `53-104w`, `105w+`. Derived from `tenure_weeks`. |
+| `person_dedup_basis` | string | yes | Constant `spine_read_no_dedup` — this family reads entity records, not person-level facts; no person dedup applies. |
+| `as_of` | timestamp | yes | UTC ISO 8601 materialization timestamp. |
+
+## Spine inputs
+
+| Source | Required columns | Use |
+| --- | --- | --- |
+| spine (Organization) | `organization_id`, `organization_name`, `discipline_key`, `created_at`, `status` | Org rows and portfolio rollup org counts. |
+| spine (OrgMarket) | `org_market_id` (slug), `organization_id`, `market_id`, `market_name`, `created_at`, `status` | Org-market rows and org-level org-market counts. |
+
+No silver face is read by this family.
+
+## active_from_at caveat
+
+The spine carries `created_at` on both Organization and OrgMarket rows (row-creation timestamp) but does not carry a separate `active_from_at` or status-transition-history surface. Platform confirmed (`2026-05-19-platform-mart-registry-spine-active-from-at-gap`) that Organization and OrgMarket rows are created at activation time in current practice, making `created_at` a near-equivalent to `active_from_at`. An entity that was activated, deactivated, and reactivated would require a status-history surface to compute strict active-from semantics; that surface does not exist today. Reactivation events are operationally rare; `created_at` is acceptable for leadership-grain age-distribution at this scale.
+
+If Platform adds a status-history surface in a future release, Portfolio will update the manifest to use the authoritative first-activation timestamp in a patch or minor. Until then, `created_at` is the declared source field and consumers should treat `tenure_weeks` as "weeks since row creation."
+
+## Composition rules
+
+- `org_active_count` and `org_market_active_count` on `portfolio_rollup` rows count rows where `status = active` on the snapshot date.
+- `org_market_active_count_in_org` on `org` rows counts active OrgMarket rows with matching `organization_id` on the snapshot date.
+- `tenure_weeks` uses UTC dates throughout; the snapshot date boundary is midnight UTC.
+- If a spine entity is absent from the live spine surface, the affected row is omitted and the gap is filed back to Platform.