@sguild/dispatcher 2.0.0 → 2.0.1

package/contracts/external-actions/README.md

@@ -0,0 +1,338 @@
+# External Actions Queue Contract
+
+**Status:** v1.0.0
+**Date:** 2026-05-06
+**Owner:** Platform
+**Consumers:** Revenue (Square outbound), Delivery (lesson-side notifications), Sales (Quo / SMS), Platform itself (Better Auth email-send, webhook-acknowledgments)
+**Related ADRs:** ADR-0011 (this contract is the spec the ADR commits to), ADR-0009 (dispatcher cross-process transport; the producer-transactional-guarantee seam mirrors here), ADR-0010 (provider externals; the `pex_` resolution snapshot rides on every action), ADR-0002 (entity ID prefixes; introduces `xa_` and `xat_`)
+**Related contracts:** Event Envelope Contract (`../event-envelope/README.md`; events that originate actions reference back via `originating_event_id`)
+
+## 1. Purpose and scope
+
+Sguild systems frequently need to perform an outbound effect against a partner system: HTTP POST to Square, email send via the auth provider, SMS via Quo, webhook acknowledgment back to a third party, and so on. These effects are non-idempotent at the destination, must be retried on transient failure, must dead-letter on terminal failure, and must compose with a Postgres transaction in the producing domain so the row write that motivates the action and the action itself land atomically from the caller's seat.
+
+This contract specifies the queue Platform stewards on behalf of every producing domain: the table shape, the producer SDK, the handler contract, the retry-classification taxonomy, the operator surface, and the responsibilities of producers and consumers.
+
+The queue is the outbound-side mirror of the dispatcher. The dispatcher (per the Event Envelope Contract) handles inbound: events fan out from one producer to many consumers with at-least-once delivery. The external-actions queue handles outbound: one action goes to one destination with retry, response correlation, and dead-letter.
+
+Out of scope: per-(provider, action-kind) request and response shapes (those live in the producing domain's module; the queue's `payload` and `response` columns are JSONB and the queue does not see the shape), provider authentication (each handler manages its own credentials), the bus underneath the runner (today the runner is a Vercel cron; transport choice is a Platform implementation detail).
+
+## 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
+
+- **Action.** One logical outbound effect. Persists as one row in `external_action`.
+- **Attempt.** One try against an action. Persists as one row in `external_action_attempt`. An action has 1..N attempts before reaching a terminal state.
+- **Producer.** The domain that enqueues the action. Must be one of `platform`, `growth`, `sales`, `delivery`, `revenue`, `coaching`.
+- **Provider.** The external system the action targets, identified by a free-text tag the producing domain owns (e.g., `square`, `quo`, `better-auth-email`). The queue treats provider as an opaque routing key; it does not enumerate providers in the schema.
+- **Action kind.** The specific operation against a provider, identified by a free-text tag the producing domain owns (e.g., `square.refund.create`, `quo.sms.send`). The (`provider`, `action_kind`) tuple selects the registered handler.
+- **Handler.** The producing-domain code that executes one action kind against one provider. Implements the `ExternalActionHandler` interface. Returns a classification.
+- **Classification.** The handler's verdict on an attempt: `succeeded`, `terminal_failure`, `retriable_failure`, or `pending`.
+- **Runner.** The Platform-side process that picks pending actions off the queue, dispatches to the registered handler, writes the resulting attempt, and advances the action's status.
+
+## 4. The `external_action` row
+
+Each action persists as one row. Fields below are normative.
+
+### 4.1 Required fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | text, `xa_<UUID v7 canonical>` per ADR-0002 | Action identifier. Globally unique. |
+| `producer` | enum (`platform`, `growth`, `sales`, `delivery`, `revenue`, `coaching`) | Which domain enqueued the action. |
+| `provider` | text, lowercase, dot-allowed | The partner system identifier. Producer-defined. |
+| `action_kind` | text, lowercase, dot-allowed | The operation against the provider. Producer-defined. |
+| `payload` | jsonb | The handler-specific request shape. The queue does not validate the payload; the handler does. |
+| `status` | enum | One of `pending`, `in_flight`, `succeeded`, `dead_lettered`, `cancelled`, `resolved`. |
+| `attempt_count` | integer | Count of attempts written so far. Starts at 0; increments before each attempt. |
+| `next_attempt_at` | timestamp | When the runner is allowed to next attempt. For `pending` actions the runner picks rows where `next_attempt_at <= now()`. |
+| `idempotency_key` | text | Stable per action. MUST be unique per (`producer`, `provider`, `action_kind`). Passed to handlers on every attempt and forwarded to the partner system's idempotency mechanism. |
+| `created_at` | timestamp | Enqueue time. Producer-side wall-clock at row write. |
+| `updated_at` | timestamp | Last status or attempt change. |
+
+### 4.2 Optional fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `originating_event_id` | text, `evt_<UUID v7>` | If the action was kicked off by a dispatcher event (per the Event Envelope Contract), the event id. Lets operators trace from inbound event to outbound action. |
+| `external_id_snapshot` | jsonb | The `pex_` resolution snapshot at enqueue time, per ADR-0010. Carries `{provider, external_id}` so audit can reconstruct the canonical-to-provider mapping the producer used, even if the underlying `person_externals` row changes later. |
+| `correlation_handle` | text | Producer-defined free text used to correlate response back to producer-side state (e.g., a row id in the producer's domain). |
+| `dead_letter_reason` | text | Set when status flips to `dead_lettered`. Names the terminal failure cause; never reset. |
+
+### 4.3 Field rules
+
+`id` MUST be `xa_<UUID v7>`. v7 because audit benefits from the time-ordered prefix.
+
+`producer` MUST match the actual producing domain. Cross-domain enqueues (one domain enqueueing on behalf of another) are NOT permitted; if domain A wants to trigger an outbound effect that B owns, A emits a dispatcher event and B's subscriber enqueues the action.
+
+`provider` and `action_kind` are producer-defined but MUST be stable. Renaming a provider or action_kind is a breaking change; the producing domain coordinates with Platform on the migration path.
+
+`payload` MAY be any JSON-serializable value. The queue does not enforce a schema; the handler does. The producing domain SHOULD include enough information in the payload that the handler does not need to read additional state at execute time (handlers run on Platform's runner, possibly delayed; reading state at execute time is a foot-gun for stale reads).
+
+For outbound communications, producers MUST preserve the domain's comms-routing obligations before the action can reach a provider. Sales and Delivery actions that target a minor Person MUST route through Platform's Guardian-aware comms-routing endpoint before enqueueing, or the producing-domain handler MUST call that endpoint before sending and send only to the returned routed recipient. Producers MUST NOT place minor contact details directly in `external_action.payload`; payloads carry either the routed adult recipient decision or enough immutable context to prove the routing decision used at execution time.
+
+`status` transitions are constrained: `pending → in_flight → {succeeded, dead_lettered, pending}` (the trailing `pending` covers the `retriable_failure` and `pending` classifications, which schedule a future attempt). `cancelled` is a terminal state set by either producer-driven cancellation through the SDK or operator-driven cancellation through the resolve surface. `resolved` is a terminal state for a dead-lettered action the operator has disposed without re-queueing.
+
+`attempt_count` increments BEFORE writing the attempt, so an attempt that crashes before completing still leaves an audit trail (the next attempt sees `attempt_count = N+1` where N is the count after the previous successful write; the runner reconciles on restart).
+
+`originating_event_id` SHOULD be present when the action is kicked off by a dispatcher event. Producers that emit actions from synchronous server actions (no inbound event) leave it null.
+
+`idempotency_key` MUST be stable for the lifetime of the action. If the producer supplies an `idempotencyKey` at enqueue time, the queue stores that value and treats a duplicate enqueue with the same key as a no-op. If the producer omits it, the queue mints one deterministically from the `xa_` action id. The same stored key is passed to the handler on every attempt, including retries and `pending` polls.
+
+## 5. The `external_action_attempt` row
+
+Each attempt persists as one row.
+
+### 5.1 Required fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | text, `xat_<UUID v7 canonical>` per ADR-0002 | Attempt identifier. Globally unique. |
+| `action_id` | text, FK to `external_action.id` | Which action this attempt belongs to. |
+| `attempt_number` | integer | 1-indexed sequence within the action. |
+| `started_at` | timestamp | Runner-side wall-clock at handler invocation. |
+| `ended_at` | timestamp | Runner-side wall-clock at handler return (or timeout). |
+| `classification` | enum | `succeeded`, `terminal_failure`, `retriable_failure`, or `pending`. |
+
+### 5.2 Optional fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `response` | jsonb | The handler's structured response (the partner system's response payload, parsed). Present on `succeeded` and SHOULD be present on `terminal_failure` and `retriable_failure` if the partner returned a structured body. |
+| `error_message` | text | Single-line error summary on non-`succeeded` classifications. |
+| `error_stack` | text | Full stack trace on non-`succeeded` classifications. Operator audit only. |
+| `poll_until` | timestamp | On `pending` classification, the deadline past which the action SHOULD escalate to dead-letter rather than continue polling. Producer-supplied per attempt. |
+
+### 5.3 Field rules
+
+Attempts are append-only. Once an attempt row is written it MUST NOT be mutated. Re-running an attempt produces a new row with the next `attempt_number`.
+
+`classification` is the single field that drives the runner's next move. The runner does not inspect `error_message`, `response`, etc. when deciding what to do next; the handler is responsible for compressing the partner system's response down to one of four classifications.
+
+## 6. The producer SDK
+
+The Platform-supplied SDK exposes one primary function for enqueueing.
+
+### 6.1 `enqueueExternalAction`
+
+```ts
+export async function enqueueExternalAction(input: {
+  producer: Domain;
+  provider: string;
+  actionKind: string;
+  payload: unknown;
+  originatingEventId?: EventId;
+  externalIdSnapshot?: { provider: string; externalId: string };
+  correlationHandle?: string;
+  idempotencyKey?: string;
+  client?: PrismaClient | TransactionClient;
+}): Promise<ExternalActionId>;
+```
+
+The SDK also exposes producer-driven cancellation:
+
+```ts
+export async function cancelExternalAction(input: {
+  externalActionId: ExternalActionId;
+  cancellationReason: string;
+  client?: PrismaClient | TransactionClient;
+}): Promise<void>;
+```
+
+Producers MUST pass `client: tx` when calling from inside `prisma.$transaction(async (tx) => …)` so the action enqueue and the producer-side row write land atomically. Producers that enqueue outside a transaction MAY omit `client`; in that case the SDK uses the default Prisma client.
+
+Producers MUST set `producer` to their own domain. The SDK validates the value against the calling module's known domain at startup; cross-domain enqueues are rejected at the type system if possible and at runtime otherwise.
+
+`provider` and `actionKind` MUST match a (provider, action_kind) pair that has a registered handler. The SDK validates registration at startup; an enqueue against an unregistered handler raises immediately. Unregistered enqueues are a producer bug, not a runtime condition.
+
+`idempotencyKey`, when set, MAY produce a return value pointing at an already-enqueued action with the same key. Producers MUST handle the return value as "the action is enqueued; might already be in flight" rather than assuming a fresh enqueue.
+
+`cancelExternalAction` is idempotent. Cancelling an already-cancelled action is a no-op. Cancelling an action that has already reached `succeeded`, `dead_lettered`, or `resolved` returns a conflict rather than rewriting history. Producers SHOULD call it inside the same transaction as the domain write that records the upstream business cancellation.
+
+### 6.2 What the SDK does NOT do
+
+The SDK does not execute the handler synchronously. Enqueue is a write to the `external_action` table only; the runner picks up the row on its next tick.
+
+The SDK does not retry the enqueue on transient Postgres failure. Producers compose `enqueueExternalAction` inside their own transactions; transaction-level retry is the producer's responsibility.
+
+The SDK does not return the handler's response. Handlers run asynchronously; producers that need the response correlate via `correlation_handle` or `originating_event_id` and read the relevant `external_action_attempt` row out of band.
+
+## 7. The handler contract
+
+Each producing domain implements a handler per (provider, action_kind) pair.
+
+### 7.1 Interface
+
+```ts
+export interface ExternalActionHandler<TPayload, TResponse> {
+  readonly provider: string;
+  readonly actionKind: string;
+  execute(
+    payload: TPayload,
+    context: HandlerContext,
+  ): Promise<HandlerResult<TResponse>>;
+}
+
+export interface HandlerContext {
+  readonly actionId: ExternalActionId;
+  readonly idempotencyKey: string;
+  readonly attemptNumber: number;
+  readonly enqueuedAt: Date;
+  readonly originatingEventId: EventId | null;
+  readonly externalIdSnapshot: { provider: string; externalId: string } | null;
+}
+
+export type HandlerResult<TResponse> =
+  | { classification: "succeeded"; response: TResponse }
+  | { classification: "terminal_failure"; error: string; response?: TResponse }
+  | { classification: "retriable_failure"; error: string; response?: TResponse }
+  | { classification: "pending"; pollUntil?: Date };
+```
+
+Handlers MUST forward `context.idempotencyKey` to the partner system using that provider's idempotency mechanism when one exists (for example Square and Stripe `Idempotency-Key` headers). When a provider has no explicit idempotency surface, the handler MUST use the key as the producer-side correlation key in logs and response reconciliation. The key is the primary defense against duplicate external side effects across retriable failures and `pending` polls; producer-side payload-composite dedup is defense in depth, not a substitute.
+
+### 7.2 Classification semantics
+
+`succeeded`. The action completed at the partner system. The runner writes the attempt with classification `succeeded`, sets the action status to `succeeded`, and stops.
+
+`terminal_failure`. The action will not succeed on retry. The runner writes the attempt and sets the action status to `dead_lettered` with `dead_letter_reason` derived from the handler's error message. Examples: validation errors at the partner system, authentication failures (until credentials change), `404 Not Found` on a resource the action references.
+
+`retriable_failure`. The action might succeed on retry. The runner writes the attempt, schedules `next_attempt_at` per the backoff schedule, and re-queues the action as `pending`. After the retry budget is exhausted (per §8.2), the action escalates to `dead_lettered`. Examples: connection timeout, `500 Internal Server Error` from the partner, rate limit exceeded.
+
+`pending`. The action is accepted at the partner system but the response is not yet available. The runner writes the attempt, schedules `next_attempt_at` per the poll cadence, and re-queues the action as `pending`. The handler MAY supply `pollUntil`; if the partner doesn't resolve by that time, the runner escalates to `dead_lettered`. Examples: Square refund settlement (typically minutes), webhook delivery confirmation from a system that ack's asynchronously.
+
+### 7.3 Handler timeout
+
+Handler execution is bounded at 30 seconds per attempt by default. Producers that need a longer timeout MUST opt in by registering a handler-specific timeout at registration time. Handlers that exceed their timeout return a synthetic `retriable_failure` attempt with `error_message = "handler timeout exceeded"` and standard backoff applies.
+
+### 7.4 Handler registration
+
+Each producing domain registers its handlers at module-load time. The Platform SDK exposes a registration surface:
+
+```ts
+import { registerHandler } from "@platform/external-actions-sdk";
+import { squareRefundCreateHandler } from "./square/refund";
+
+registerHandler(squareRefundCreateHandler);
+```
+
+Registration MUST occur before the runner picks up an action of that (provider, action_kind). The runner verifies registration at boot and refuses to start if any (provider, action_kind) referenced by `pending` actions in the table has no registered handler.
+
+## 8. Retry classification and backoff
+
+### 8.1 Backoff schedule
+
+Default backoff is exponential with jitter:
+
+| Attempt # | Base delay | Jitter window |
+|-----------|------------|---------------|
+| 1 → 2 | 5 seconds | ±2 seconds |
+| 2 → 3 | 30 seconds | ±10 seconds |
+| 3 → 4 | 2 minutes | ±30 seconds |
+| 4 → 5 | 10 minutes | ±2 minutes |
+| 5 → 6 | 1 hour | ±10 minutes |
+| 6 → 7 | 6 hours | ±30 minutes |
+
+After the 7th attempt, the action escalates to `dead_lettered` regardless of classification.
+
+### 8.2 Retry budget per (provider, action_kind)
+
+The default of 7 attempts MAY be overridden per (provider, action_kind) at handler registration time. Producers SHOULD raise the cap for actions with a long natural delay (e.g., webhook acknowledgments from systems that retry on hour-long cycles) and lower it for actions that should fail fast (e.g., real-time SMS sends where a delayed retry has no value).
+
+### 8.3 Pending poll cadence
+
+`pending` classification uses a flat 30-second poll interval with ±10s jitter, regardless of attempt number. The handler MAY override the next poll time by returning `pollUntil` plus the next attempt's natural cadence; the runner schedules the smaller of the two.
+
+### 8.4 Dead-lettering and operator resolve
+
+An action reaches `dead_lettered` when:
+- A handler returns `terminal_failure`.
+- The retry budget is exhausted on `retriable_failure`.
+- The `poll_until` deadline passes on `pending`.
+
+An action reaches `cancelled` separately when the producer calls `cancelExternalAction` before execution completes, or when an operator resolves a dead-lettered action with `disposition = cancelled`.
+
+Operators resolve dead-lettered actions via the routes in §9.
+
+## 9. Read and operator surface
+
+The Platform repo exposes reconciliation reads for producing domains and operator routes for dead-letter disposition.
+
+### 9.1 Reconciliation reads
+
+Producing domains read queue state through Platform HTTP APIs rather than cross-database Prisma reads.
+
+```
+GET /api/external-actions?producer=revenue&provider=square&status=in_flight,dead_lettered&since=2026-05-01
+GET /api/external-actions/{id}
+GET /api/external-actions/{id}/attempts
+```
+
+The list endpoint requires `producer` and supports optional `provider`, `status` (CSV), `actionKind`, `since`, and `limit` filters. `limit` defaults to 100 and caps at 500. Responses include the action row, `external_id_snapshot`, `correlation_handle`, `idempotency_key`, and enough attempt summary data for reconciliation runbooks to correlate provider-side state back to producer-owned domain rows.
+
+### 9.2 `POST /api/external-actions/{id}/resolve`
+
+Marks a dead-lettered action as resolved. Operator-only; requires an authenticated session.
+
+Request body:
+
+```json
+{
+  "resolved_by": "<operator-id>",
+  "disposition": "manual_reconciliation",
+  "resolution_note": "<optional free text>"
+}
+```
+
+`disposition` is one of `manual_reconciliation`, `abandoned`, or `cancelled`. `manual_reconciliation` means the operator verified the partner-side outcome and reconciled local state. `abandoned` means the action will not be retried and the producing domain must apply any compensating business state it requires. `cancelled` means the upstream business decision has been reversed and the action should not execute.
+
+Response: 200 with the updated action row. Resolution sets `resolved_at`, `resolved_by`, `disposition`, and `resolution_note` on the action; `status` flips from `dead_lettered` to `resolved`, except `disposition = cancelled` flips to `cancelled`. Resolution is one-shot: 409 on a row that was already resolved or cancelled.
+
+### 9.3 `POST /api/external-actions/{id}/retry`
+
+Re-queues a dead-lettered action for one more attempt. Operator-only.
+
+Request body:
+
+```json
+{
+  "operator_note": "<free text describing why retry is appropriate>"
+}
+```
+
+Response: 200 with the action's new `pending` status. Retry resets `next_attempt_at` to now, increments a separate `operator_retry_count`, and writes an audit entry. After 3 operator retries on the same action, further retries return 409 (the operator surface deliberately makes "retry forever" non-trivial; if 3 retries didn't fix it, escalation to root cause is the right move).
+
+### 9.4 `GET /api/external-actions/dead-lettered`
+
+Returns the list of active (un-resolved, un-cancelled) dead-lettered actions, optionally filtered by producer or provider. Operator dashboard read.
+
+## 10. Versioning
+
+This contract follows the same `@vMAJOR.MINOR.PATCH` cadence as the Event Envelope Contract.
+
+MAJOR bumps for breaking changes (column removal, behavior reversal). MINOR bumps for additive changes (new optional column, new classification value). PATCH bumps for clarification (wording fixes, examples).
+
+Bumps require a memo announcing the change, with a soft response window for consumer ack per the operator standard.
+
+## 11. Migration and rollout
+
+The Airtable-era `External Actions` surface on the Growth repo does not migrate. Pre-existing rows finish processing on the legacy path under Growth's stewardship until they retire or dead-letter; the Postgres queue starts fresh on Platform's table at the moment producers start emitting against it.
+
+Per ADR-0011 action item #5 and the operator standard (`_OPERATOR.md` Contracts section, two-week deprecation window), the three Growth-side routes (`POST /api/external-actions`, `/retry`, `/sync`) are absorbed by Platform as proxies during the deprecation window, then retire. Each absorb files its own reply memo on the carve-up thread.
+
+## 12. References
+
+- ADR-0011 (`../../adrs/ADR-0011-external-actions-at-platform.md`). The decision this contract specs.
+- ADR-0009 (`../../adrs/ADR-0009-dispatcher-cross-process-transport.md`). The dispatcher transport whose producer-transactional-guarantee seam mirrors §6.1's `client?` parameter.
+- ADR-0010 (`../../adrs/ADR-0010-provider-externals-at-platform.md`). The `pex_` resolution snapshot rides on every action via §4.2's `external_id_snapshot`.
+- ADR-0002 (`../../adrs/ADR-0002-person-id-shape.md`). The entity ID prefix template; `xa_` and `xat_` register here.
+- Event Envelope Contract (`../event-envelope/README.md`). Events that originate actions reference back via §4.2's `originating_event_id`.
+- `2026-05-25-growth-api-carveup-inventory`. Growth's carve-up that flagged the three external-actions routes as cross-cutting and asked for the ADR.
+- `2026-05-04-platform-growth-api-carveup-reply`. Platform's reply that took the cross-domain-infrastructure position and reserved ADR-0011.
+
+## 13. Change log
+
+- **v1.0.0** (2026-05-06) — Promoted on ADR-0011 acceptance. Folded Revenue's review notes into the normative surface: stable action-level idempotency keys in handler context, `cancelExternalAction`, producing-domain reconciliation reads, and explicit DLQ disposition vocabulary. Folded Sales and Delivery's comms-routing notes into producer payload rules: Guardian-aware routing remains mandatory for minor-facing outbound communication, and minor contact details do not ride directly in queue payloads.
+- **v0.1.0** (2026-05-04) — Initial draft paired with ADR-0011. Table pair, producer SDK, handler contract, retry classification, operator surface, and Growth route migration story.

package/contracts/finance-mart/README.md

@@ -0,0 +1,238 @@
+# Finance Mart Contract
+
+**Status:** v2.0.0
+**Date:** 2026-05-19
+**Owner:** finance (derived finance store and the finance gold section)
+**Consumers:** finance reporting consumers (leadership reporting and accounting exports); no operational domain consumes this contract
+**Related ADRs:** ADR-0015, ADR-0016, ADR-0006, ADR-0003, ADR-0013, ADR-0014
+**Sub-specs (authoritative):** revenue-recognition-rollup.md, margin.md, cash-position.md, reconciliation.md (v1.0.0 manifests carrying forward to the named v2.0.0 sub-sections); unit-economics.md, pnl.md, cac-payback.md, ltv.md, cohort-summary.md, customer-journey-audit.md (v2.0.x manifests landed 2026-05-19)
+**Validations:** n/a in v2.0.0; the reconciliation validation note, the consumer-isolation validation note, and the customer-grain audit-posture validation note land under `validation/` as the derived finance store models ship
+
+## 1. Purpose and scope
+
+The Finance Mart Contract specifies the read surface of the `finance` section of the gold mart (ADR-0016): the financial view of Sguild across domains that leadership reporting and accounting exports read, namely unit economics, profit and loss, margin, customer acquisition cost and payback, cash runway, lifetime value, and reconciliation against Revenue's transaction-grain ledger, at the business reporting grain. Finance composes these metrics over the warehouse silver tier and the conformed identity and geography spine, materializes them into its derived finance store, and serves them through this contracted section. The contract is what lets finance reporting consumers build on a stable surface rather than on Finance's internal store shape, and it is the artifact that defines the firewall bound for the finance consumer tag per ADR-0016.
+
+Finance 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 Finance through silver. The contract therefore specifies a read surface and the guarantees Finance 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 groupings (six sub-sections plus one proposed sub-section) the section exposes, the §8 customer-grain audit carve-out absorbing Portfolio's §9.3 cohort_customer_audit per the path-1 consolidation, the cross-cutting reconciliation guarantee, 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), Revenue's transaction-grain ledger and the orders, payments, credit reservations, and refunds behind it (Revenue owns these, per ADR-0006; finance-mart reconciles against them and does not restate them), strategy reporting metrics (the `portfolio-mart` contract, owned by Portfolio per ADR-0015), any operational domain's per-domain gold section, canonical geography and Organization records (Platform, per ADR-0013 and ADR-0014), Person identity (Platform), coordination-layer artifacts including initiative attribution (Platform's coordination surfaces). If a need to write a fact rather than report one appears, that is a domain-kind boundary question per ADR-0015, not a finance-mart change.
+
+## 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
+
+- **Finance section**: the `finance` section of the single gold mart (ADR-0016), built across silver faces and the spine rather than over a single warehouse. The materialized surface this contract governs.
+- **Derived finance store**: Finance's own Prisma deployment, where composed financial 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. Finance 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 to Service Area to Lesson Site geography hierarchy, per the `warehouse-silver` contract.
+- **Business reporting grain**: the grain at which Finance reports for aggregate metrics, namely a reporting period and a place in the geography hierarchy. Distinct from transaction grain.
+- **Transaction grain**: the grain at which Revenue holds commercial truth, namely the individual order, payment, credit reservation, ledger entry, or refund. Finance reconciles to this grain; it does not report at it.
+- **Cohort grain**: per-org-market × per-intake-cohort, with intake-week defining the cohort. Used by `cac_payback`, `ltv`, and `cohort_summary` sub-sections.
+- **Customer grain**: per-customer (one row per `customer_id`). Reserved for the §8 customer-grain audit carve-out; aggregate metrics never expose customer grain.
+- **Recognized revenue**: revenue attributed to a reporting period under Finance's recognition logic, as distinct from cash received or amounts invoiced.
+- **Reconciliation**: the cross-cutting guarantee that a business-grain figure on finance-mart ties back to Revenue's transaction-grain ledger within a stated tolerance, and that the variance is itself surfaced.
+- **Finance reporting consumer**: a leadership-facing or accounting-facing report or export that reads the finance section. Not a domain in the closed set; no operational domain consumes this contract.
+
+## 4. Surface
+
+### 4.1 The served surface
+
+The finance 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 finance consumer tag is bounded by this contract, so a finance 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.
+
+The v2.0.0 surface is organized into six sub-sections (`unit_economics`, `pnl`, `margin`, `cac_payback`, `runway`, `ltv`) covering 14 metrics, one proposed seventh sub-section (`cohort_summary`) covering the cohort-grain financial columns Portfolio's `cohort_funnel_panel` cannot serve, the §8 customer-grain audit carve-out (`customer_journey_audit`, consolidating Portfolio's §9.3 `cohort_customer_audit` per the 2026-05-19 path-1 resolution), and the cross-cutting reconciliation guarantee. The grouping topology aligns with the Them OS data-mart forecasting spec §8 per the 2026-05-19 registry encoding decision.
+
+### 4.2 Grain and dimensions
+
+Finance metrics are reported at one of three grains, all keyed from the conformed identity and geography spine:
+
+- **Business reporting grain**: a reporting period × geography_key, where geography_key is the (Organization, Market, Service Area) tuple per ADR-0013 and ADR-0014. Used by `pnl`, `margin`, and most of `runway`. The smallest reporting period a metric supports is named in that metric's manifest.
+- **Cohort grain**: per-org-market × per-intake-cohort, with intake-week defining the cohort. Used by `cac_payback`, `ltv`, and `cohort_summary`. Some metrics carry a second dimension (intake-week × current-week) for cumulative cohort views.
+- **Reporting date**: a point-in-time grain. Used by `cash_position` and `runway_weeks` in the `runway` sub-section.
+
+The §8 customer-grain audit carve-out is the only customer-grain surface in the section; aggregate metrics never expose customer grain. Per ADR-0014, per-discipline financial books follow the per-Organization boundary; cash is held at Organization grain per the `_cash_pooling_model: pooled_at_organization` declaration in `runway` §4.7.
+
+### 4.3 `unit_economics`
+
+Unit economics metrics: per-active-student revenue intensity, revenue concentration, and other operational-unit-level economic ratios. Composed across Revenue's recognition and Delivery's active-student counts.
+
+Metrics in v2.0.0:
+
+- `revenue_per_active_student`: GAAP earned revenue summed by `org_market × lesson_week` divided by Delivery's `active_student_count` summed by `org_market × snapshot_week` (snapshot-week-end value). Cohort floor: `active_student_count < 5` emits `null:insufficient_data`. Rollup rule: `weighted_mean_by_revenue`. Absorbed from Revenue's section per `2026-05-19-platform-mart-revenue-per-active-student-relocation` and Finance's acceptance in `2026-05-19-finance-revenue-per-active-student-absorption`.
+- `revenue_concentration`: top-N customer revenue share of total revenue at `org_market × reporting_period`. Top-N cutoff declared in the sub-section manifest. Rollup rule: `weighted_mean_by_revenue` (the concentration ratio rolls up weighted, not summed).
+
+Both metrics gate on Delivery's `active_student_count` reaching `beta` (the `delivery.customer.status='active'` silver column confirmed per `2026-05-19-delivery-revenue-per-active-student-ack`) and on Revenue's recognition compute reaching `beta`.
+
+### 4.4 `pnl`
+
+Profit and loss metrics: recognized revenue, P&L summary composing revenue minus cost-of-service minus operating expense, at the business reporting grain.
+
+Metrics in v2.0.0:
+
+- `revenue_recognition_summary`: recognized revenue for a reporting period, rolled up across domains and sliced by the geography hierarchy. Carries forward from v1.0.0 §4.3 with the manifest at `revenue-recognition-rollup.md`. Composed from the revenue silver face and the spine; reconcilable per §4.11.
+- `pnl_summary`: composite P&L view at `reporting_period × geography_key`. Numerator is recognized revenue minus cost-of-service minus operating expense. Cost-of-service silver gate per Revenue's P2/L ask; operating-expense allocation rule named in the sub-section manifest. Rollup: `sum`.
+
+### 4.5 `margin`
+
+Margin metrics: gross margin and operating margin at the business reporting grain.
+
+Metrics in v2.0.0:
+
+- `gross_margin`: recognized revenue minus cost-of-service at `reporting_period × geography_key`, with the manifest at `margin.md` (carrying forward from v1.0.0 §4.4). Rollup rule: `sum` for absolute amount, `weighted_mean_by_revenue` for percentage.
+- `gross_margin_pct`: gross margin as a percentage of recognized revenue. Rollup: `weighted_mean_by_revenue`.
+- `contribution_margin`: gross margin minus directly-attributable marketing and sales cost. Per-cohort allocation rule named in the sub-section manifest.
+- `operating_margin`: recognized revenue minus total operating cost. Rollup: `weighted_mean_by_revenue` for percentage.
+
+All margin metrics gate on Revenue's cost-of-service silver columns landing.
+
+### 4.6 `cac_payback`
+
+Customer acquisition cost and payback metrics: per-cohort acquisition cost, time-to-payback, and payback distribution.
+
+Metrics in v2.0.0:
+
+- `cac`: per-cohort customer acquisition cost. Cost decomposition: `_cac_cost_decomposition: marketing_plus_sales_sdr` per the 2026-05-19 100-percent-deployment decision. Numerator composes Growth `ad_spend_reconciled` plus Sales SDR-time allocation per cohort; denominator is per-cohort first-lock count. Grain: `cohort_week × geography_key`. Rollup: `weighted_mean_by_cohort_size`.
+- `cac_payback_weeks`: weeks until cumulative gross margin per cohort meets or exceeds CAC. Definition: `_payback_definition: cumulative_gross_margin_geq_cac`. Bucket granularity per `payback_distribution`.
+- `payback_distribution`: histogram of cohort payback across monthly buckets. `_payback_bucket_granularity: monthly`. Cohorts with no payback within the observation window emit `null:insufficient_observation_window`.
+
+Gates: Growth attribution silver, Revenue's `ad_spend_reconciled` cross-warehouse compute, Sales cohort-triangle silver carrying SDR-time allocation per cohort. If Sales does not expose SDR-time allocation, Finance falls back to marketing-only CAC and supplements via a registry edit memo.
+
+### 4.7 `runway`
+
+Cash runway metrics: cash position, burn rate, weeks of runway at the reporting date.
+
+Metrics in v2.0.0:
+
+- `cash_position`: cash held by the Organization at the reporting date, with market-grain and service-area-grain rows as informational allocations per `_cash_pooling_model: pooled_at_organization`. Allocation rule: `_allocation_rule: equal_share_by_active_student_count` (matching the `revenue_per_active_student` denominator). Rows carry `_balance_kind: held` at Organization grain or `_balance_kind: allocated` at market and service-area grain. Manifest at `cash-position.md` (carrying forward from v1.0.0 §4.5 with the v2.0.0 pooling-and-allocation extension).
+- `burn_rate`: net negative cash flow over the reporting period at `reporting_period × geography_key`. Gates on Revenue's cost-of-service silver and on operating-expense allocation. Rollup: `sum`.
+- `runway_weeks`: current cash divided by trailing-three-month average burn at `reporting_date × geography_key`. Formula: `_runway_formula: current_cash_div_trailing_3mo_avg_burn` per the 2026-05-19 100-percent-deployment decision. Emits `null:not_applicable` when burn is non-positive over the trailing window. Rollup: `weighted_mean_by_cash_position`.
+
+### 4.8 `ltv`
+
+Lifetime value metrics: per-cohort customer lifetime value.
+
+Metrics in v2.0.0:
+
+- `ltv_per_first_lock_cohort`: cumulative per-customer gross margin since intake, summed across the cohort, divided by distinct customer count. Decomposition: `_ltv_decomposition: gross_margin` per the 2026-05-19 100-percent-deployment decision. Grain: `cohort_week × geography_key`. Gates on cost-of-service silver (for gross margin) plus Sales cohort-triangle silver (for cohort identity) plus Revenue cash-ledger silver (for customer-grain cumulative revenue). Rollup: `weighted_mean_by_cohort_size`.
+
+### 4.9 `cohort_summary` (proposed)
+
+Proposed seventh sub-section covering the cohort-grain financial columns Portfolio's `cohort_funnel_panel` cannot serve per portfolio-mart §4.4. Finance's position in `2026-05-19-finance-cohort-panel-financial-columns-position` selected this as Portfolio's option-2 resolution; the Them OS caller assembles the full cross-domain panel by joining Portfolio's `cohort_funnel_panel` (non-financial columns) to this sub-section (financial columns).
+
+Metrics in v2.0.0 (pending Platform encoding confirmation):
+
+- `revenue_earned_by_cohort`: GAAP earned revenue at `org_market × intake_cohort × current_week`. Period attribution: intake-week for the cohort key, current-week for the cumulative state. Rollup: `sum`.
+- `revenue_paid_by_cohort`: cash revenue at the same grain. Rollup: `sum`.
+
+If Platform reads the §8 spec text as placing cohort-grain financial views inside `unit_economics` instead of as a separate sub-section, Finance follows the spec and migrates the two metrics under `unit_economics` in a v2.0.x patch.
+
+### 4.10 §8 customer-grain audit carve-out: `customer_journey_audit`
+
+The §8 carve-out consolidates Portfolio's §9.3 `cohort_customer_audit` per the path-1 consolidation in `2026-05-19-portfolio-mart-scope-resolution-path-1-accepted` and Finance's acceptance terms in `2026-05-19-finance-mart-registry-portfolio-consolidation-position` and `2026-05-19-finance-customer-audit-consolidation-cleanness`.
+
+Row shape: per-customer audit, one row per `customer_id`, returning the customer's journey snapshot across Revenue, Delivery, and the cohort it intook into. Fields: `customer_id`, `intake_week`, `first_lock_week`, `first_delivery_lesson_week`, `lessons_completed_to_date`, `revenue_paid_to_date`, `current_status`. The cohort dimension is a slicing filter off `intake_week`, not a parallel row shape.
+
+Field excluded from the row: `current_initiative_attribution`. Initiative attribution is a coordination-layer artifact, not a financial fact; consumers needing initiative attribution join to the Platform-owned coordination surface (the `/initiatives` view or its mart-surface equivalent if §10 returns to the Them OS spec) at audit time.
+
+Posture: audit-only, rate-limited, tagged `cross_domain_customer_grain=true`. The carve-out is bound to this contract; Portfolio consumers reading the audit do so through Finance's access pattern. The rate-limit, the firewall bound, and the deprecation discipline are Finance's.
+
+### 4.11 Reconciliation cross-cutting guarantee
+
+The reconciliation guarantee ties finance-mart to Revenue's authoritative records. For every reported figure in the sub-sections above, reconciliation exposes the tie back to Revenue's transaction-grain ledger and the variance against a stated tolerance. Revenue's ledger, orders, payments, credit reservations, and refunds are the authoritative transaction-grain source per ADR-0006; finance-mart reconciles against them and never restates or competes with them. A finance-mart figure that does not reconcile is a Finance incident per `domains/finance.md`, and reconciliation is where that condition is made visible rather than hidden. The reconciliation tolerance for each figure is named in the `reconciliation.md` manifest (carrying forward from v1.0.0 §4.6 with extension for the v2.0.0 metrics added in `unit_economics`, `cac_payback`, `ltv`, and `cohort_summary`).
+
+Reconciliation is a guarantee that applies to every figure in every sub-section, not a sub-section itself. The §4.6 guarantee in v1.0.0 carries forward unchanged in substance.
+
+### 4.12 What the finance section does not expose
+
+- **No transaction-grain records.** No individual order, payment, credit reservation, ledger entry, or refund. A consumer needing transaction-grain truth reads Revenue's surface, not this one.
+- **No strategy metrics.** Cross-Market, cross-discipline, and portfolio-level funnel metrics are the `portfolio-mart` contract's surface per ADR-0015. The boundary is subject: if the question is strategy rather than financial, it is Portfolio's.
+- **No silver or bronze.** The finance section is a gold-section surface. A consumer reads finance-mart, not silver, not bronze, and not Finance's derived store.
+- **No Person or geography source records.** Finance joins the spine for those facts and exposes only what a business-grain financial figure needs. Aggregate metrics are aggregate by default; the §8 audit carve-out is the only customer-grain exposure and carries the rate-limit and audit-only posture named in §4.10.
+- **No initiative attribution.** Coordination-layer artifacts including initiative attribution are sourced from Platform-owned coordination surfaces, not from finance-mart. The §4.10 carve-out explicitly excludes `current_initiative_attribution` from its row shape.
+- **No events.** Finance produces nothing on the event envelope.
+
+## 5. Versioning policy
+
+### 5.1 Semantic versioning
+
+- **Patch** (2.0.0 to 2.0.1): editorial clarifications, typo fixes, manifest landings for previously declared sub-sections. No change to the served surface that breaks consumers.
+- **Minor** (2.x.y to 2.x+1.0): additive changes. A new optional column on a sub-section, a new metric inside an existing sub-section, a new optional dimension, a new reconciliation dimension. Consumers on older minors continue to work.
+- **Major** (2.x.y to 3.0.0): breaking changes. Removing or renaming a sub-section or a column, changing a column type, changing a 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 and the Finance quality bar in `domains/finance.md`. The v1.0.0 → v2.0.0 deprecation window opens 2026-05-19 (v2.0.0 publish date) and closes 2026-06-02 (two weeks later, aligning with the default-accept window on Platform's registry encoding per `2026-05-19-platform-mart-contract-registry-encoded`).
+
+No finance reporting consumer SHALL run against v1.0.0 after 2026-06-02. v1.0.0 consumers running after the window contribute to drift and are a Finance quality-bar regression.
+
+The deprecation window is planned before the new major ships, not after, per `contracts/README.md` and `finance-mart` §7. This contract's v2.0.0 publish FYI memo (`2026-05-19-finance-finance-mart-v2-publish-announcement`) names the window and the consumer migration path.
+
+### 5.3 Additive discipline within a major
+
+New columns MUST default to null or a backwards-compatible value. A new metric inside an existing sub-section is additive and does not change existing metrics. New sub-section manifests landing as v2.0.x patches (for `unit_economics`, `cac_payback`, `ltv`, `cohort_summary`, and the customer-grain audit carve-out) are additive landings, not new major versions; the sub-sections are declared in v2.0.0's §4 and the manifests follow as compute develops. Consumers MUST treat unknown columns, unknown metrics, and unknown sub-section manifests, added in a later patch or minor, as safe to ignore.
+
+### 5.4 Upstream churn is not a contract change
+
+A change to a silver face, the spine, or Revenue's ledger schema does not by itself bump this contract. Finance absorbs upstream churn in its composition logic. This contract bumps only when the served surface that finance reporting consumers see changes. That insulation is the point of the reporting-domain tier: silver insulates Finance from bronze, and this contract insulates finance reporting consumers from Finance's composition.
+
+### 5.5 The v1.0.0 → v2.0.0 reshape rationale
+
+v2.0.0 reshapes the served surface from v1.0.0's four-grouping topology (`revenue_recognition`, `margin`, `cash_position`, `reconciliation`) to v2.0.0's six-sub-section-plus-one-proposed topology (`unit_economics`, `pnl`, `margin`, `cac_payback`, `runway`, `ltv`, plus the proposed `cohort_summary`), plus the §8 customer-grain audit carve-out (consolidating Portfolio's §9.3 per the 2026-05-19 path-1 resolution), plus the cross-cutting reconciliation guarantee unchanged in substance. The reshape aligns the contract to the binding Them OS data-mart forecasting spec §8 per Finance's 2026-05-19 acceptance in `2026-05-19-finance-mart-registry-encoding-response`, Platform's confirmation in `2026-05-19-platform-mart-registry-finance-v2-path-confirmed`, and the per-metric metadata review filed in `2026-05-19-finance-mart-registry-per-metric-metadata-review`.
+
+Migration mapping from v1.0.0 to v2.0.0:
+
+- v1.0.0 `revenue_recognition` (§4.3) → v2.0.0 `pnl` §4.4 (`revenue_recognition_summary` carries the manifest `revenue-recognition-rollup.md`; `pnl_summary` is new).
+- v1.0.0 `margin` (§4.4) → v2.0.0 `margin` §4.5 (`gross_margin` carries the manifest `margin.md`; `gross_margin_pct`, `contribution_margin`, `operating_margin` are new).
+- v1.0.0 `cash_position` (§4.5) → v2.0.0 `runway` §4.7 (`cash_position` carries the manifest `cash-position.md` with the v2.0.0 pooling-and-allocation extension; `burn_rate`, `runway_weeks` are new).
+- v1.0.0 `reconciliation` (§4.6) → v2.0.0 cross-cutting reconciliation guarantee §4.11 (manifest `reconciliation.md` carries forward; extended to cover the v2.0.0 added metrics).
+
+New v2.0.0 sub-sections and their metric sets are declared in §4.3, §4.6, §4.8, §4.9, §4.10 with manifests landing as v2.0.x patches.
+
+## 6. Consumer responsibilities
+
+- A finance reporting consumer SHALL read the finance section through the consumer-firewall tag and SHALL NOT read silver, bronze, another gold section, or Finance's derived store directly. Consumer isolation is a Finance quality-bar signal per `domains/finance.md`.
+- A consumer SHALL key on a sub-section's declared grain (business reporting, cohort, or reporting date per §4.2) and SHALL NOT infer a finer grain than the sub-section exposes. A consumer that needs transaction-grain detail SHALL read Revenue's surface, not finance-mart. A consumer that needs customer-grain detail SHALL use the §4.10 audit carve-out under its rate-limit posture, not a non-audit endpoint.
+- A consumer SHALL treat `as_of` as the freshness signal and degrade gracefully when the section is materialized behind real time.
+- A consumer SHALL reference reporting periods explicitly rather than assuming a default period, so that a contract minor that adds a period dimension does not silently change results.
+- A consumer SHALL treat unknown columns, unknown metrics, unknown sub-section manifests, and unknown allocation-rule values, added in a later patch or minor, as safe to ignore.
+- A consumer needing the cross-domain cohort panel (Portfolio's `cohort_funnel_panel` joined to Finance's `cohort_summary`) SHALL perform the join on `(org_market_id, intake_cohort)` at audit time; finance-mart does not serve the joined panel as a single endpoint.
+- An operational domain SHALL NOT consume this contract as an input to operational behavior. The finance section is a reporting surface; an operational consumer of it is a trigger to revisit ADR-0015.
+
+## 7. Producer responsibilities
+
+- Finance SHALL keep every finance-mart figure reconcilable to Revenue's transaction-grain ledger within the stated tolerance, and SHALL surface variance through the reconciliation guarantee rather than absorbing it silently.
+- Finance SHALL compose every metric over the warehouse silver tier and the conformed identity and geography spine, never over bronze and never by reaching into another domain's storage.
+- Finance SHALL keep cross-domain financial composition in the finance section and SHALL NOT push a composed metric back into any per-domain warehouse.
+- Finance SHALL resolve all cross-domain joins through `person_id` per ADR-0003 and SHALL source Person and geography facts from the spine, never from a shadow copy.
+- Finance SHALL stamp every served row with an `as_of` timestamp reflecting the underlying materialization refresh.
+- Finance SHALL plan a two-week deprecation window before publishing any major version, per §5.2, and SHALL announce each major to all domains by FYI memo, mirroring the warehouse-silver publication pattern. The v2.0.0 publish FYI is filed at `memos/2026/2026-05-19-finance-finance-mart-v2-publish-announcement.md`.
+- Finance SHALL preserve the §4.10 audit-only, rate-limited posture on the customer-grain carve-out, and SHALL NOT serve customer-grain rows outside the carve-out's access pattern.
+- Finance SHALL NOT emit events. Finance-mart is a reporting surface; if something in Finance looks like it wants to emit, it is a reporting artifact that belongs in the section or it belongs to an operational domain.
+- Finance SHALL decline, in writing through a memo, any request that belongs to an operational domain, to Portfolio's strategy surface, or to Revenue's commercial surface, rather than absorbing it into this contract.
+
+## 8. Security and privacy
+
+The finance section is composed at the business reporting grain and is aggregate by default for the six sub-sections (`unit_economics`, `pnl`, `margin`, `cac_payback`, `runway`, `ltv`) plus the proposed `cohort_summary` sub-section; most figures carry no Person association at the served surface. The composition reads PII from the spine and the silver faces (`person_id` and conformed Person attributes) to compose and reconcile figures, but the served aggregate surface carries aggregates, not Person records.
+
+The §4.10 customer-grain audit carve-out (`customer_journey_audit`) is the one exception: it serves per-customer rows under a strict rate-limit, audit-only posture, tagged `cross_domain_customer_grain=true`. The carve-out absorbs Portfolio's §9.3 `cohort_customer_audit` per the 2026-05-19 path-1 consolidation; Finance is the only domain serving customer-grain financial audit data in the mart. Access to the carve-out is bounded by Finance's rate-limit configuration and is logged for audit; access to the aggregate sub-sections is bounded by the Platform-owned consumer firewall scoped to this contract.
+
+Finance SHALL apply 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 finance consumer tag to this contract's surface; access to the section is Platform-controlled through that mechanism, with the §4.10 carve-out's rate-limit as the additional gate.
+
+Naming the fact for the next reader: the only customer-grain row shape in v2.0.0 is the §4.10 audit carve-out; aggregate sub-sections do not expose customer grain. A future sub-section that would change that is a major-version question per §5.1, not a minor.
+
+## 9. Future work
+
+- **The reconciliation validation note** under `validation/`, proving that business-grain figures tie back to Revenue's transaction-grain ledger within tolerance against live data, landing as the derived finance store models ship.
+- **The consumer-isolation validation note** under `validation/`, proving that no finance reporting consumer reads outside the finance section against live traffic.
+- **The customer-grain audit-posture validation note** under `validation/`, proving that the §4.10 carve-out's rate-limit and audit-only posture are enforced against live traffic, that `current_initiative_attribution` is excluded from the row shape, and that cohort-slicing filters do not relax the access pattern.
+- **Per-sub-section manifests** for `unit_economics`, `cac_payback`, `ltv`, `cohort_summary`, and `customer-journey-audit` land as v2.0.x patches as each sub-section's compute develops. The v1.0.0-carried manifests (`revenue-recognition-rollup.md`, `margin.md`, `cash-position.md`, `reconciliation.md`) carry their figures forward immediately at v2.0.0 publish; new sub-section manifests follow.
+- **Refresh-cadence alignment** with Platform's gold materialization decision (ADR-0016). When Platform documents the gold refresh cadence and staleness monitoring, this contract gains a stated freshness expectation for the finance section.
+- **`cohort_summary` placement decision**: if Platform reads the §8 spec text as placing cohort-grain financial views inside `unit_economics`, Finance migrates the two cohort metrics under `unit_economics` in a v2.0.x patch per the position in `2026-05-19-finance-cohort-panel-financial-columns-position`.
+
+## 10. Change log
+
+- **v2.0.0** (2026-05-19): Major version. Reshapes the served surface from v1.0.0's four-grouping topology to six sub-sections (`unit_economics`, `pnl`, `margin`, `cac_payback`, `runway`, `ltv`) plus the proposed seventh sub-section `cohort_summary`, plus the §4.10 customer-grain audit carve-out `customer_journey_audit` (consolidating Portfolio's §9.3 `cohort_customer_audit` per the 2026-05-19 path-1 resolution), plus the cross-cutting reconciliation guarantee §4.11 (unchanged in substance from v1.0.0 §4.6, extended to cover the v2.0.0 added metrics). Aligns the contract to the binding Them OS data-mart forecasting spec §8. Migration mapping documented in §5.5. Five `_*` registry declarations land per the 2026-05-19 100-percent-deployment decisions: `_cac_cost_decomposition: marketing_plus_sales_sdr`, `_payback_definition: cumulative_gross_margin_geq_cac`, `_payback_bucket_granularity: monthly`, `_ltv_decomposition: gross_margin`, `_runway_formula: current_cash_div_trailing_3mo_avg_burn`, `_cash_pooling_model: pooled_at_organization`, `_allocation_rule: equal_share_by_active_student_count`, `_balance_kind` per cash_position row. v1.0.0 enters its two-week consumer deprecation window 2026-05-19 → 2026-06-02 per §5.2. Published per ADR-0015 action item 5 and the Them OS spec §8 binding. Announced via FYI memo `2026-05-19-finance-finance-mart-v2-publish-announcement`.
+- **v1.0.0 manifest addendum** (2026-05-18): Added the four authoritative grouping manifests: `revenue-recognition-rollup.md`, `margin.md`, `cash-position.md`, and `reconciliation.md`. The manifests name the served columns, source silver inputs, reconciliation tolerances, and known cost-source gap for margin. This lands the per-figure column-manifest deliverable without changing the v1.0.0 grouping boundaries. The four manifests carry forward to v2.0.0 under the sub-sections noted in §5.5; new sub-section manifests land as v2.0.x patches.
+- **v1.0.0** (2026-05-14): Initial publication. Establishes the finance gold section's served surface, the grain and dimensions, the four metric groupings (revenue recognition rollups, margin, cash position, reconciliation), the reconciliation guarantee against Revenue's transaction-grain ledger, the consumer and producer responsibilities, and the versioning and deprecation policy with the two-week deprecation window. Published per ADR-0015 action item 5.