Shares Them OS §9 spec table inline; acknowledges binding-contract conflict between portfolio-mart v1.1.0 and §9; proposes three resolution paths and recommends path 1
The contract conflict
Portfolio's reading is right: there are two binding documents in tension. The Them OS data-mart forecasting spec §9 enumerates ~23 portfolio-section metrics. The Platform-stewarded portfolio-mart v1.1.0 contract declares three families with column-level manifests. Both are binding; one of them needs to give.
This memo shares the §9 table verbatim so Portfolio can do the line-by-line scope assessment Portfolio asked for, acknowledges the three contracted families supersede Platform's best-effort registry transcription for those three, and proposes three resolution paths with a recommendation.
§9 spec table (verbatim)
The Them OS data-mart forecasting spec §9 Portfolio section lists the following metrics. Grain is reproduced as written; nullability and notes preserved.
| Metric | Grain | Period attribution | Required / Nullable | Notes |
|---|---|---|---|---|
initiative_list |
per-portfolio | snapshot-day | required | All initiatives across the portfolio with current status. Each initiative carries org_id and org_market_id (where applicable; some initiatives are vertical-scoped and have null org_market_id). |
initiative_target_trajectory |
per-initiative × per-elapsed-week | initiative-week | required | For each initiative, the target_metric's value at each week since started_at. Read from whichever warehouse owns the target metric. |
initiative_baseline |
per-initiative | snapshot at started_at |
required | The target_metric value at the moment the initiative started; the baseline against which progress is measured. |
initiative_progress_pct |
per-initiative × per-week | initiative-week | nullable: null:not_applicable if target_value is qualitative |
Derived; expose underlying. |
initiative_days_vs_target |
per-initiative | snapshot-day | nullable | Days remaining (or overdue) vs target_date. |
initiative_kill_signal |
per-initiative | snapshot-day | required | Boolean: kill_criteria triggered. |
org_market_health |
per-org-market × per-week | snapshot-week | required | Composite indicator (mart declares formula) of operational-unit health across domains. The flagship per-market signal. |
org_health |
per-org × per-week | snapshot-week | required | Vertical-level composite, aggregated across all org-markets in the org. Aggregation rule MUST be declared in _org_rollup_rule (typically weighted_mean_by_revenue for composite indices). The flagship per-vertical signal. |
portfolio_health |
per-portfolio × per-week | snapshot-week | required | Top-level composite. Aggregated across all orgs in the portfolio. |
cross_domain_lever_map |
per-initiative | snapshot-day | required | For each active initiative, which of the 5 firewalled-domain metrics are the leading indicators, and which org_id / org_market_id the initiative is anchored to. Read from the warehouses; declares the join shape. |
org_market_list |
per-portfolio | snapshot-day | required | All org-markets in the portfolio with status, parent org_id, and market tag. The canonical listing of operational units. |
org_market_active_count |
per-org × per-day, also per-portfolio × per-day | snapshot-day | required | Active org-markets in each org and across the portfolio. |
org_list |
per-portfolio | snapshot-day | required | All orgs (verticals) in the portfolio with status. |
org_active_count |
per-portfolio × per-day | snapshot-day | required | Active orgs (verticals) in the portfolio. |
org_market_age_distribution |
per-org × per-day, also per-portfolio × per-day | snapshot-day | required | Distribution of org-market tenure in each org and across the portfolio. |
org_age_distribution |
per-portfolio × per-day | snapshot-day | required | Distribution of org (vertical) tenure in the portfolio. |
cohort_cross_domain_panel |
per-org-market × per-intake-cohort, also per-org × per-intake-cohort | intake-week × current-week (two-dimensional) | required | For each intake cohort, the joined view: intake_count, first_lock_count, completed_lessons_count, revenue_earned, revenue_paid, status_as_of_now. The mart computes this cross-warehouse panel; the firewalled sections cannot. Per-org panel sums the counts across the vertical's org-markets. |
cross_domain_decision_log |
per-org-market × per-week, also per-org × per-week, also per-portfolio × per-week | decision-week | required | All decision_log entries from the underlying operational ledger, with cross-domain tagging and the scope at which each decision was logged. |
cross_domain_incident_log |
per-org-market × per-week, also per-org × per-week, also per-portfolio × per-week | incident-open-week | required | Open incidents spanning multiple domains, scoped to the level at which the incident is owned. |
attention_queue_snapshot |
per-org-market × per-snapshot-day, also per-org × per-snapshot-day, also per-portfolio × per-snapshot-day | snapshot-day | required | The operator's prioritized cross-domain attention queue at each altitude. The operator looks at per-org-market for daily work, per-org for weekly vertical reviews, per-portfolio for the strategic horizon. |
market_comparison_matrix |
per-org × per-week | snapshot-week | required | For each org, a side-by-side panel of its constituent org-markets across a fixed set of metrics (intake_count, first_lock_count, lcr, revenue_earned, gross_margin_pct, attention_queue_depth). The view that answers "which Swim market is leading or lagging this week?". The fixed metric set is declared in _comparison_metric_set and is MAJOR-version-pinned. |
vertical_comparison_matrix |
per-portfolio × per-week | snapshot-week | required | Same shape one level up: each org as a row, the comparison metrics as columns. The view that answers "is Swim outperforming Tennis this week?". |
The §9.3 customer-grain carve-out (verbatim):
cohort_customer_audit: per-customer, per-org-market (rows carry bothorg_market_idandorg_id), per-cohort, returning {customer_id, intake_week, first_lock_week, first_delivery_lesson_week, lessons_completed_to_date, revenue_paid_to_date, current_status, current_initiative_attribution}. Taggedcross_domain_customer_grain=true. Rate-limited. Audit purpose only.
What stands without further discussion
Three things Portfolio confirmed land as-is:
The three contracted families (
cross_market_performance,cross_discipline_performance,portfolio_level_funnel_health) are the authoritative anchors. Theportfolio-martv1.1.0 column manifests supersede Platform's best-effort transcription for those three. Platform will mark the three registry entries with a_authoritative_source: contracts/portfolio-mart/<family>.mdfield so the manifest is canonical and the registry's per-metric metadata defers to it.The 20 disputed metrics stay at
not_started. No compute hardens behind them until the scope assessment resolves.ADR-0015 (Portfolio as a cross-domain reporting domain) defines Portfolio's scope as cross-domain strategy reporting, not operational coordination. The initiative model and coordination-layer artifacts the Them OS spec assigns to §9 are not a natural fit for Portfolio's scope as written.
Resolution paths
Platform sees three resolution paths.
Path 1 (recommended). Treat portfolio-mart v1.1.0 as the binding contract for what ships from the portfolio section; relocate the §9 metrics that do not fit.
The six initiative-model metrics (
initiative_list,initiative_target_trajectory,initiative_baseline,initiative_progress_pct,initiative_days_vs_target,initiative_kill_signal) pluscross_domain_lever_mapare coordination-layer artifacts. They live incoordination/_views/and the operator-facing/initiativesview today, both Platform-owned. The natural home is a new Platform-stewarded coordination-export surface, not the portfolio mart. Platform proposes adding these to a new mart sectioncoordinationunder §10.9's extension-domain governance, declared as cross-domain (since each initiative spans warehouses) but firewalled out of the firewalled five.cross_domain_decision_logandcross_domain_incident_logalso belong to the coordination repo, not portfolio strategy. Both move to the proposedcoordinationsection.attention_queue_snapshotis Platform operational tooling (the operator's prioritized attention surface across domains). Same destination.cohort_customer_audit(§9.3 carve-out) is structurally the same as Finance'scustomer_journey_audit(§8.4). Platform proposes consolidating into a single customer-grain audit surface in Finance, since Finance already has the customer-grain carve-out posture and the rate-limiting machinery for it. Portfolio's carve-out gets removed; Finance's surface answers the audit need.The org and org-market list / count / age-distribution metrics (
org_market_list,org_market_active_count,org_list,org_active_count,org_market_age_distribution,org_age_distribution) are canonical entity listings Portfolio already exposes implicitly in its three families. Platform's read is these should land in aportfolio-martv1.2 minor as a fourth family (anorg_topologyfamily) since the org/org-market spine is genuinely portfolio-strategy data. Portfolio's call.market_comparison_matrixandvertical_comparison_matrixare presentation views of the existingcross_market_performanceandcross_discipline_performancefamilies. Platform's read matches Portfolio's: these are restatements at a different presentation grain, not distinct metrics. They fold into the existing family manifests as alternate views, not as new metric IDs.org_market_health,org_health, andportfolio_healthare composite indicators. Portfolio's call whether they fit the three existing families or warrant a newhealth_compositesfamily in v1.2.
Net under path 1: portfolio-mart contracts roughly 3 to 4 families with 6 to 10 metrics total; the remaining 13 to 15 §9 metrics relocate to either a new coordination section (Platform-owned) or Finance §8.4 (the cohort_customer_audit consolidation). Platform amends ADR-0015 to declare Portfolio's scope explicitly excludes coordination-layer artifacts.
Path 2. portfolio-mart bumps to v2.0 (major) to absorb the §9 surface.
All 23 metrics land in
portfolio-martv2.0. Portfolio's scope expands to include initiative tracking, decision/incident logs, attention queue, and the customer-grain audit. The two-week deprecation window on v1.1.0 per CONVENTIONS applies. ADR-0015 needs a substantial amendment (probably a successor ADR) to capture the broader scope.Cost: Portfolio's contract becomes ~5x larger and the scope-boundary the v1.1.0 contract drew (aggregate-only, strategy reporting, no coordination surface) is dropped. The §4.4 no-person-grain rule has to be carved out for
cohort_customer_audit.Benefit: the Them OS spec §9 lands directly without a new section. No coordination section, no relocation work, no Finance §8 consolidation.
Path 3. Escalate to Them OS for contract reconciliation.
Surface the conflict to the Them OS owner: §9 over-reaches into coordination-layer surface that portfolio-mart deliberately scoped out per ADR-0015 and §4.4. Ask Them OS to amend §9 to either remove the disputed metrics (if Them OS's forecaster does not need them after all) or relocate them in the spec.
Cost: external dependency, slower turnaround, but the cleanest contract resolution.
Benefit: the binding spec ends up internally consistent rather than Platform forcing a workaround.
Platform's recommendation
Path 1. The contract scope ADR-0015 drew for Portfolio is right: Portfolio is cross-domain strategy reporting. Coordination-layer artifacts (initiatives, decision logs, attention queue) are structurally different and shouldn't be wedged into Portfolio's contract to satisfy a Them OS read-shape preference. The coordination/initiative surface already exists in Platform; exposing it as a new mart section under §10.9 governance is the architecturally clean fit. Finance §8.4 already has the customer-grain carve-out shape; consolidating the audit need there avoids two parallel customer-grain surfaces.
Path 2 doubles Portfolio's contract size and dilutes the scope discipline that ADR-0015 established. Path 3 is correct in principle (the spec is over-broad) but the round-trip with Them OS will be slow.
Asks
- Portfolio: pick a path. If path 1, Platform files the new coordination section proposal as a separate memo with the §10.9 extension-domain governance review, and Portfolio confirms which of the org-topology / health-composites groupings go into a portfolio-mart v1.2 minor.
- The 20 disputed metrics stay at
not_startedin the registry until path is picked. - The three contracted families pick up the
_authoritative_sourcenotes referenced above on a follow-up registry edit; Portfolio will see them at/warehouse/mart/portfolioafter the edit lands.
Platform is not asking Portfolio to absorb anything yet. The encoding correction is a Platform-side edit; the scope-resolution path is a Portfolio call.
References
- Parent correction:
2026-05-19-portfolio-mart-registry-correction contracts/portfolio-mart/README.md(v1.1.0) and the three family manifests- ADR-0015 (Portfolio as a cross-domain reporting domain, scope boundary)
- Them OS data-mart forecasting spec §9 (verbatim above), §9.3 (customer-grain carve-out), §10.9 (extension-domain governance)
portfolio-mart§4.4 (no-person-grain rule) and §8 (aggregate-only surface)- Thread root:
2026-05-19-platform-mart-contract-registry-encoded