gasp-standard-mcp 1.16.0 → 1.18.0

package/README.md

@@ -40,8 +40,17 @@ Restart your MCP client after adding the config.
 | `get_relationships` | One node of the relationship graph (metric, entity or concept) with its direct edges: upstream, measured by, downstream and measures. 21 relationship types across signal, lifecycle, ownership, interaction and financial flow categories. Metric names resolve as in `lookup_metric`, ambiguity included; a metric outside the graph says so. An entity also lists every metric whose formula reads its datasets (from `entityMappings`), with department and URL |
 | `get_data_requirements` | Data requirements for one metric, a department or every metric with a formula: per metric, each field and dataset pair with its type, the staged flag, source, grain, frequency, page URL and example SQL. The metric resolves exactly as in `lookup_metric`; `department` lists a department or picks between metrics sharing a name. Optional `breakdown` names a breakdown the metric declares (`by_plan` on MRR) and returns that breakdown's requirement: the dimension among the fields and example SQL with one row per value; an unknown name lists the declared ones. Optional `dialect` (`postgres` by default and for Redshift, `snowflake`, `bigquery`, `databricks`) writes the example SQL for that warehouse |
 | `search` | Whole-word phrase search across metrics (names, aliases, definitions, formulas, fields, categories, departments) and glossary terms (terms, definitions, sections); the last word may take a plural or verb ending. Up to 10 results, one per metric or term, ranked name, alias and term first, then words within them, then definitions, then formulas and fields, each with what matched and its gaspwiki.com URL. A query that matches nothing returns up to 6 close names as "Did you mean" |
-| `generate_query` | Compile warehouse SQL from the metric's canonical formula and an adapter. One scalar subquery per aggregate, each reading the table mapped for its dataset, with `:period_start` and `:period_end` date parameters (both inclusive). Unmapped pairs stay as `{{field@dataset}}` placeholders and are listed with any dataset lacking a table and any mapping conflict. Optional `breakdown` names a breakdown the metric declares (`by_plan` on MRR) and returns one row per value; an unknown name lists the declared ones. Optional `dialect` (`postgres`, `snowflake`, `bigquery`, `databricks`; `postgres` also covers Redshift) picks the SQL syntax for date arithmetic, casts and percentiles; without it the adapter's `warehouse` decides when it names one of them, else postgres. The output says which dialect it used |
-| `validate_adapter` | Validate a GASP adapter. Applies the bundled adapter JSON Schema (draft 2020-12, versions 1.0 and 1.1) first and lists each violation with its JSON path, then reports unknown fields and datasets, fields mapped to a dataset that does not carry them, bare column names on fields that live on several datasets, dataset table conflicts, enum fields mapped without a transform, covered metrics without an owner and owners naming unknown metrics. Scores every metric with a formula against the exact field and dataset pairs its compiled SQL reads (full, partial with the missing pairs or none) and ranks up to 15 unmapped pairs by how many partially covered metrics need them |
+| `generate_query` | Compile warehouse SQL from the metric's canonical formula and a mapping (a GASP adapter, or an Ossie mapping with its `semantic_model`). One scalar subquery per aggregate, each reading the table mapped for its dataset, with `:period_start` and `:period_end` date parameters (both inclusive). Unmapped pairs stay as `{{field@dataset}}` placeholders and are listed with any dataset lacking a table and any mapping conflict. Optional `breakdown` names a breakdown the metric declares (`by_plan` on MRR) and returns one row per value; an unknown name lists the declared ones. Optional `dialect` (`postgres`, `snowflake`, `bigquery`, `databricks`; `postgres` also covers Redshift) picks the SQL syntax for date arithmetic, casts and percentiles; without it the adapter's `warehouse` decides when it names one of them, else postgres. The output says which dialect it used |
+| `validate_mapping` | Validate a warehouse mapping in either format: a GASP adapter (JSON) or an Apache Ossie mapping document (YAML or JSON) over your semantic model, passed as `semantic_model`. A GASP adapter is converted on load into an Ossie mapping over a model synthesised from its tables and columns. Reports in layers: the schema (the adapter JSON Schema, and the bundled Ossie mapping schema for the Ossie form), GASP's cross-document checks against the GASP ontology and the model, then coverage: unknown fields and datasets, fields mapped to a dataset that does not carry them, table conflicts, every metric with a formula scored against the field and dataset pairs its compiled SQL reads (full, partial with the missing pairs or none), enum fields mapped without a transform, covered metrics without an owner, owners naming unknown metrics and up to 15 unmapped pairs ranked by how many partially covered metrics need them. `validate_adapter` is the same tool under its original name |
+| `score_drift` | Score how far your own metrics drift from GASP's canonical definitions, by result. Takes your mapping (either format) and your `semantic_model` holding your metrics; each is matched to a GASP metric by exact name, by the synonyms in its `ai_context` or by a pair in `matches`, a name ending in -O or -M matching that declared form, with near names listed for review and never scored on a guess. The canonical metric is compiled into your names and both run on the GASP synthetic SaaS dataset for six monthly periods in an in-process Postgres (PGlite, an optional dependency). Differences come with both values per period and the likely cause read from the canonical formula: a null on one side (a sum over no rows is NULL in your SQL and 0 in GASP's), a cohort or opening value the expression cannot state, a filter one side applies, a dataset one side reads, an aggregate with no equal on the other side. Your values are checked against the standard's range for the metric per period, and where both forms of a dual-lens metric are matched the O/M bridge (the Durability Gap for ARR, the Activation Delta for CAC and the others the Core metrics name) is scored beside the canonical gap. `output: json` returns the data |
+| `profile_schema` | Profile your warehouse schema into a minimal Ossie semantic model, the first step towards a mapping. Pass the rows of `information_schema.columns` (JSON or CSV), a tables list or `CREATE TABLE` statements, read through your own warehouse MCP or from a dump, and optionally statistics per column (`output: statistics` returns the query that gathers them). Every table gets a key, a time field and a kind (snapshot, event, fact or reference) with the evidence and a confidence, plus the relationships the columns imply; what the names cannot settle is a question for you rather than a guess. The model is returned as YAML to pass on as `semantic_model` |
+| `propose_mapping` | Propose a GASP mapping from the model `profile_schema` returned (or your own Ossie model, or a schema profiled on the way in). Every table is scored against the GASP datasets on its columns, its profiled kind, key and time field and its name; every column of a proposed table against the dataset's fields by name, structural role, a short synonym list, word order and near names, checked against the type and the listed values. A column in cents gets a divide-by-100 transform and enum values the standard does not use a `CASE` recode when one is known. High-confidence pairs become an Ossie mapping over the model (a transform a calculated field) for `validate_mapping`; medium ones are candidates with their evidence and what would settle them; `output: adapter` gives the pairs as a GASP adapter |
+| `derive_cel` | SQL that derives CEL `Revenue_Event` rows from your billing data by the rules in `cel.md`. `source: subscription` (default): the subscription dataset your mapping covers (snapshots at any cadence or a version history) becomes one event per movement, with the customer's `prior_mrr` and `new_mrr` chained so the row identity holds, the event type read from the customer's MRR around the step, the ATL lifecycle tag and an empty `expansion_classification` the ledger cannot fill. `source: invoice`: the invoice dataset read as one row per service period (`recurring_amount` over the months between `service_period_start` and `service_period_end`), for a billing system that keeps no subscription history. When the mapping covers the `usage_record` dataset (or `usage: true`), each period whose `usage_amount` exceeds its `committed_amount` adds an `expansion` tagged `usage_realisation` with `change_nature` `temporary` on the period's end and its `scheduled_reversal` the next day, chained with the ledger's steps. Same mapping input as `generate_query`, plus the ledger's currency; dialect from the request or the warehouse; unmapped fields listed |
+| `generate_checks` | SQL for the readiness checks the standard states, over the datasets your mapping covers: CEL row identity, MRR continuity, unique event ids, the ATL tags (lifecycle, expansion classification, cost function), customer identity both ways, freshness per dataset and, for every fully mapped metric with a hard range rule in the ontology (NRR at least 0, GRR at most 100%), its value in every reporting period of your period spine (`period_spine`, the table `compile_model` reads), one row per check. Paste the result rows back as `results` for pass or fail per check and per metric, each check naming the metrics it protects. Same mapping input as `generate_query`; dialect from the request or the warehouse |
+| `plan_fixes` | The ranked fix list: every unmapped field and every failing check, ordered by Core metrics unlocked, then all metrics unlocked, with an effort class shown and used only as a tiebreak. A fix unlocks a metric when it is the last thing between that metric and covered-and-passing. Takes the mapping and the `results` from `generate_checks` |
+| `readiness_report` | Which readiness level a company has reached and what stands between it and the next, read from the documents the other tools wrote: L1 Profiled (a semantic model exists), L2 Mapped (a metric fully covered, no open question or candidate), L3 Clean core (the CEL revenue events mapped, the checks run and every covered Core metric passing every check that protects it), L4 LLM-ready (the canonical metrics compiled into the model and none of your own metrics differing from its canonical counterpart). Takes the mapping, the `semantic_model` (with an adapter, the one `compile_model` returned) and the `results` from `generate_checks`; each blocker names the tool that clears it and the Next line is the one action to take
+| `record_decision` | Record the decisions people make on the proposed mapping, each named by content with its owner and date: a profiler question answered (key, time field, kind, datatype) is written into the model; a candidate accepted or rejected into the mapping (an accepted table matched column by column, an accepted column with an optional transform as a calculated field); a metric owner into `metricOwners`; a judgement call GASP cannot apply (reporting currency, churn date) recorded. All land in the mapping's GASP extension; a later decision on a subject replaces the earlier one. With no decisions it lists the open questions, candidates and unowned metrics and whether readiness level 2 is reached |
+| `compile_model` | Compile the GASP metrics your mapping covers into your Apache Ossie semantic model. Same input as `validate_mapping`; returns your model with a `gasp_` metric per covered formula entry (main formula, O and M forms, variants, named breakdowns): a direct `OSSIE_SQL_2026` expression over your datasets and fields where the language can state it, else staged through a `gasp_staged_` per-period dataset whose `source` is the compiled SQL over your tables in your warehouse `dialect`, reading the `period_spine` table you name. Entries with unmapped pairs are listed with the pairs they need; recompiling replaces the `gasp_` additions and leaves the rest. Optional `metrics` and `department` compile a subset; `output: report` returns the coverage without the document |
 | `infer_drivers` | Diagnose what could explain an observed metric movement: up to 25 upstream candidates ranked by attenuation score, each with its implied direction and path. Direction flips across `reduces` edges and negative-polarity inputs; a baseline input (MRR read at period start by NRR) is listed but not walked through. Metric nodes only; `maxDepth` 1 to 8 (default 6) |
 | `explain_path` | Up to 5 forward edge chains from one graph node to another, shortest first, with edge type, classification (metric_signal / structural / lifecycle / behavioral / assignment / generative), attenuation and direction flips per step and the target's end direction per path. A baseline edge can only start a path |
 | `coverage_gap` | Audit a metric set: metrics with a direct edge into or out of it that it leaves out, plus graph metrics with no path to or from it. Inputs that are ambiguous, outside the graph or not metrics are listed as unresolved with the reason |
@@ -50,7 +59,7 @@ The traversal tools (`infer_drivers`, `explain_path`, `coverage_gap`) return pat
 
 ## Data
 
-Version 1.16.0.
+Version 1.18.0.
 
 - 306 metrics across 13 departments
 - 94 glossary definitions (81 SaaS domain + 13 GASP framework)
@@ -58,18 +67,29 @@ Version 1.16.0.
 - 21 relationship types: metric signal (drives, reduces, predicts, component, measures), entity lifecycle (converts_to, parent_of, belongs_to), entity ownership (owns, grants, priced_by), entity interactions (manages, serves, engages_via, submits, represented_by, sources), entity financial flows (generates, produces, contributes_to, incurs)
 - 279 data requirements, one per metric with a formula, compiled from the formula at load time: fields with types, datasets, grain and a compiled example query
 - 279 query templates, one per metric with a formula, compiled by the same step. None of the SQL is hand-written. Every field placeholder names the dataset it is read from (`{{customer_status@customer}}`), so `generate_query` resolves per-dataset adapter mappings by tag, inside cohort subqueries too. The grammar's `window(expr, n unit)` gives Daily, Weekly and Monthly Active Users (DAU, WAU, MAU) their 1, 7 and 30 day windows. `all_time(expr)` lets retention numerators read past the period end. A multi-argument `count_distinct` counts distinct tuples (Breadth of Adoption counts account and feature pairs). A formula with a `breakdown` field compiles to one row per value of that field, with `total(expr)` reading the whole population for shares of total (Ticket Distribution by Type, CAC by Channel)
-- The test suite executes every compiled template against a seeded fixture in an in-process Postgres (PGlite) and checks 25 metrics against independently computed values
+- The test suite executes every compiled template against a seeded fixture in an in-process Postgres (PGlite) and checks selected metrics against independently computed values
 - Apache Ossie (incubating) export, written by `npm run derive` to `standard/exports/ossie/` and served at https://gaspwiki.com/downloads/ossie/: `gasp.ontology.yaml` (every dataset and GASP concept as an entity type, every field as a value type or relationship, enum values as constraints), `gasp.semantic_model.yaml` (every dataset with `OSSIE_SQL_2026` field expressions, the foreign-key relationships between them and every canonical formula as a metric, either a direct expression or staged through a per-period dataset that carries the compiled SQL; O/M forms and variants are separate metrics with the form in `custom_extensions`), `gasp.mapping.yaml` (the ontology mapped onto the model) and `coverage.json` (how each formula was exported and why). All three documents pass the upstream validator (vendored at `ossie-validator/`) and GASP's own cross-reference checks in `src/ossie/check.ts`, which cover references the upstream validator leaves alone
 - 28 business entities (Customer, Subscription, License, Lead, Opportunity, User, Ticket, Employee, Invoice, Partner, Project, Plan, Product, Campaign, Contact, Incident, Deployment, Release, Issue, Vulnerability, Feature, Requisition, Project Milestone, Deliverable, Quote, Order, Knowledge Article and Deal Registration). Every dataset with its own identity maps to an entity; ledger and period-level facts (cost events, financials, forecasts, web traffic) stay entity-free
 - 7 business concepts (Revenue, Bookings, COGS, Cohort, Pipeline, Segment and TCV)
-- 268 canonical fields across 52 datasets (event, snapshot and fact tables with date and key fields, entities, CEL class and activation rules). Enum fields declare their allowed values
+- 274 canonical fields across 53 datasets (event, snapshot and fact tables with date and key fields, entities, CEL class and activation rules). Enum fields declare their allowed values
 - 65 structured formulas with decomposed inputs (metric refs + field refs, with baseline inputs marked)
 - Canonical formulas for every metric in the GASP formula grammar (`standard/formulas.json`): 294 entries covering all 306 metrics (279 with formulas, 15 marked not computable with a reason, 2 department-qualified ids for shared headings), with units, O/M forms for ARR, NRR, CAC, LTV, LTV:CAC, CAC Payback and Gross Margin (a form can reference another metric's form, `metric.gross_margin.O`) and variants such as Adjusted NRR (served by `get_formula` and compiled by `generate_query` and `get_data_requirements`)
 - Access control classifications for every graph metric (sensitivity tier + access scope)
 - CEL `change_nature` field for revenue quality analysis (Adjusted NRR/GRR) and `segment` on revenue, contract and amendment events, so MRR, retention and churn metrics break down by customer segment
 - Per-department cross-references (NRR under Customer Success, CAC under Marketing) resolve to the full canonical record, with its access classification, structured formula and entity mappings
 - Every metric and definition result carries its gaspwiki.com page URL; definitions keep their full body and reference links
+- One mapping format: a company's warehouse mapping is an Apache Ossie mapping document over its semantic model, and the v1 adapter is accepted everywhere and converted on load (`src/ossie/adapt.ts`). The upstream Ossie schemas travel in the bundled data as `ossieSchemas`, so `validate_mapping` checks an Ossie mapping offline
+- The schema profiler (`src/ossie/profile.ts`, behind `profile_schema`) turns a schema dump into a minimal Ossie semantic model with its evidence; the Acme DDL in `test/fixture/acme-schema.sql` is its fixture.
+- The mapping proposer (`src/ossie/propose.ts`, behind `propose_mapping`) turns that model into a draft GASP mapping with the evidence per pair, transforms where the name or the values call for one and candidates for the pairs the evidence does not settle; on the Acme DDL it reproduces the Acme adapter.
+- The CEL derivations (`src/cel.ts`, behind `derive_cel`) are the standard's rules for turning a subscription ledger, an invoice ledger or usage records into `Revenue_Event` rows, compiled over a company's mapping in its dialect. The test suite runs them over the synthetic dataset: every generated movement comes back from the subscription snapshots with monthly sums equal to the compiled MRR movement metrics, the monthly invoices give the month-start movements with a lapsed subscription churning the day after its last period, and the usage records give a tagged pair per month over the commitment, chained with the ledger's steps.
+- Two vendor worked examples beside Acme in `test/fixture/` (`stripe/`, Redshift; `salesforce/`, BigQuery): a DDL, a GASP mapping and a README stating the source documentation and every choice, written from public API documentation and never standard content. The Stripe example is taken from a validated mapping to readiness level 4 in the test suite, derives from its item snapshots with a metered item's usage records and from its invoices, and its drift report names a planted difference; the Salesforce example compiles in BigQuery and stops at level 2 because a CRM maps no revenue event
+- The readiness checks and the fix plan (`src/checks.ts`, behind `generate_checks` and `plan_fixes`) compile the rules in `cel.md` and `atl.md`, and the ontology's value ranges per reporting period (`src/ranges.ts`), into SQL over a mapping and rank what to fix by the metrics it unlocks; the synthetic dataset passes every check and a table of planted violations fails the right ones.
+- The readiness report (`src/readiness.ts`, behind `readiness_report`) reads the level a company has reached (L1 to L4 of the interop plan) from the mapping, the model and the pasted check rows, and names what blocks the next level; the test suite takes the synthetic dataset to L4.
+- The Decide step (`src/ossie/decide.ts`, behind `record_decision`) applies the answers people give to the model and the mapping and keeps every decision, with its owner, in the mapping's GASP extension; it closes readiness level 2 when no question and no candidate is open.
+- The drift scorer (`src/ossie/drift.ts`, behind `score_drift`) runs a company's metrics and the canonical ones side by side on the synthetic SaaS dataset (`src/synthetic.ts`, also the test fixture) in PGlite, loaded on first use from the optional dependency `@electric-sql/pglite`; without it the tool says so and runs nothing
+- The metric compiler (`src/ossie/company.ts`, behind `compile_model`) writes every covered GASP metric into a company's own Ossie model, direct or staged, over their datasets, sources and field expressions. The test suite compiles the fixture adapter and checks every direct and staged value against the reference export on the fixture rows
 - Adapter schema 1.1 (`standard/gasp-adapter-schema.json`, JSON Schema draft 2020-12, served at https://gaspwiki.com/schemas/gasp-adapter-v1.json): a `datasets` map, per-dataset mappings (a mapping names its `dataset`), informational fields and `$schema`. The schema travels in the bundled data as `adapterSchema` and `validate_adapter` applies it with Ajv, so validation works offline. `npm run derive` writes a ready template to `standard/exports/gasp-adapter-template.json` (served at https://gaspwiki.com/downloads/gasp-adapter-template.json) and the tests validate it against the schema
+- GASP Ossie extension schema 1 (`standard/gasp-ossie-extension-v1.json`, JSON Schema draft 2020-12, served at https://gaspwiki.com/schemas/gasp-ossie-extension-v1.json): the parsed `data` of every `custom_extensions` entry GASP writes under `vendor_name: GASP`, one definition per placement (model, dataset, metric, mapping), strict so each key GASP adds outside Ossie is listed. It travels in the bundled data as `extensionSchema` and the cross-document checks (`checkExport` in `src/ossie/check.ts`) validate every GASP payload against it in the export, `validate_mapping`, `compile_model`, `propose_mapping` and `record_decision`
 - Sources: the canonical [GASP Standard](https://gaspwiki.com) files
 
 ## Examples

package/build/cel.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Deriving CEL Revenue_Events from a subscription ledger (standard/cel.md,
+ * "Deriving Revenue Events from a Subscription Ledger").
+ *
+ * Most billing systems hold subscriptions, not events: a row per subscription
+ * whose MRR and status change over time, kept as snapshots or as a version
+ * history. The CEL needs the movements between those states. The rules here
+ * turn the GASP `subscription` dataset into `revenue_event` rows and are the
+ * same for every source system; a vendor appears only in a mapping.
+ *
+ *   1. A subscription's MRR on a snapshot is its `mrr` when `subscription_status`
+ *      is active, else 0. A customer's MRR is the sum over its subscriptions.
+ *   2. A step is a snapshot whose MRR differs from the subscription's previous
+ *      snapshot (by snapshot_date). A subscription's first snapshot steps from 0.
+ *   3. Rows on the ledger's first snapshot date are opening balances: they seed
+ *      the customer's MRR and produce no event (`firstSnapshot: "steps"` turns
+ *      that off for a ledger that starts with the business). The ledger holds
+ *      one row per subscription per snapshot date and keeps a cancelled
+ *      subscription's row, since a subscription that stops appearing has no step.
+ *   4. One Revenue_Event per step, dated the snapshot that first shows the change.
+ *      mrr_change is the subscription's change; prior_mrr and new_mrr are the
+ *      customer's MRR before and after it, chained through the customer's steps
+ *      in (snapshot_date, increases before decreases, subscription_id) order, so
+ *      prior_mrr + mrr_change = new_mrr holds on every row and the rows of one
+ *      date add up.
+ *   5. event_type from the customer's MRR at the start and end of the date: an
+ *      increase from 0 is `new`, or `reactivation` when the customer was active
+ *      on an earlier date; a decrease to 0 is `churn`; any other increase is
+ *      `expansion` and any other decrease `contraction`. So a plan swap onto a
+ *      new subscription id is an expansion and a contraction, two subscriptions
+ *      cancelled on one date are two churns. `renewal` is not a movement and
+ *      comes from Contract_Event or the renewal fields.
+ *   6. lifecycle_attribution follows the ATL rules for each type; change_nature
+ *      is `permanent`; segment is the snapshot's; expansion_classification is
+ *      NULL, because the ledger does not say what kind of expansion it was (the
+ *      amendment does), and the readiness check for the ATL tag names the gap.
+ *   7. event_id is the subscription id and the snapshot date.
+ *
+ * The cadence of the ledger is the grain of the events: with daily snapshots
+ * every movement is seen on its day; with month-end snapshots the movements
+ * inside a month net to one event dated the month end, and a churn followed by
+ * a reactivation inside one interval leaves no event. Where amendment events
+ * exist they are the better source and the pairing rule in cel.md applies.
+ *
+ * Two more sources feed the same rules (cel.md, "Deriving Revenue Events from
+ * an Invoice Ledger" and "Deriving Usage Realisation"):
+ *
+ *   - An invoice ledger (`source: "invoice"`) is a subscription ledger with one
+ *     row per service period: an invoice's MRR is its `recurring_amount` over
+ *     the months its service period covers, a subscription's MRR on a date is
+ *     the sum over the invoices covering it, and its ledger dates are the
+ *     starts of its service periods and the day after each end, up to the
+ *     ledger's horizon (the latest service period start). Rules 2 to 7 then
+ *     apply unchanged. The invoice dataset carries no segment.
+ *   - Usage records (`usage: true`) add one pair of events per period in which
+ *     `usage_amount` exceeds `committed_amount`: an `expansion` dated the
+ *     period's end for the overage over the months the period covers, tagged
+ *     `usage_realisation` with `change_nature` `temporary`, and its
+ *     `scheduled_reversal`, a `contraction` dated the next day. The commitment
+ *     is already in the subscription's MRR, so usage within it is no event. The
+ *     pairs chain with the ledger's steps, so prior_mrr and new_mrr hold.
+ *
+ * The template uses the compiler's placeholders ({{field@dataset}},
+ * {{_table:dataset}}), so `fillTemplate` compiles it over any adapter or Ossie
+ * mapping that covers the fields it reads.
+ */
+import { type DialectName } from "./dialect.js";
+import type { QueryTemplate, StandardData } from "./types.js";
+export declare const DERIVATION_DATASET = "subscription";
+/** The subscription fields the derivation reads, in the order the ledger CTE selects them. */
+export declare const DERIVATION_FIELDS: readonly ["subscription_id", "customer_id", "snapshot_date", "mrr", "subscription_status", "segment"];
+/** The invoice fields the invoice source reads. */
+export declare const INVOICE_FIELDS: readonly ["invoice_id", "subscription_id", "customer_id", "snapshot_date", "service_period_start", "service_period_end", "recurring_amount"];
+/** The usage_record fields the usage branch reads. */
+export declare const USAGE_FIELDS: readonly ["subscription_id", "customer_id", "period_start", "period_end", "committed_amount", "usage_amount"];
+/** The revenue_event fields the derivation writes, in column order. */
+export declare const DERIVED_FIELDS: readonly ["event_id", "event_date", "customer_id", "subscription_id", "event_type", "mrr_change", "currency", "prior_mrr", "new_mrr", "expansion_classification", "change_nature", "lifecycle_attribution", "segment"];
+export type DerivationSource = "subscription" | "invoice";
+export declare const DERIVATION_SOURCES: readonly DerivationSource[];
+export interface DerivationOptions {
+    dialect?: DialectName;
+    /** ISO 4217 code written on every event: the ledger's currency (the subscription dataset carries none). */
+    currency: string;
+    /**
+     * What the rows on the ledger's first snapshot date are: `opening` (the default) seeds each customer's
+     * MRR and produces no event, for a ledger that starts after the oldest subscription; `steps` treats them
+     * as steps from 0, for a ledger that starts with the business.
+     */
+    firstSnapshot?: "opening" | "steps";
+    /** The ledger: the `subscription` dataset (the default) or the `invoice` dataset read as one row per service period. */
+    source?: DerivationSource;
+    /** Read the `usage_record` dataset too and add the usage realisation pairs. */
+    usage?: boolean;
+}
+/** The `ledger` CTE of the subscription source: one row per subscription per snapshot date, MRR when active. */
+export declare function subscriptionLedgerSql(): string;
+/**
+ * The `ledger` CTE of the invoice source: each invoice's latest snapshot, its MRR
+ * as the recurring amount over the months of its service period, the boundaries
+ * of each subscription's periods as its ledger dates and the invoices covering
+ * each date summed into its MRR, up to the ledger's horizon.
+ */
+export declare function invoiceLedgerSql(dialect?: DialectName): string;
+/**
+ * The usage CTEs: each period whose usage exceeds its commitment, the overage
+ * over the months the period covers, and the pair of changes it adds to the
+ * customer's steps, a `usage` increase on the period's end and a
+ * `usage_reversal` decrease the day after.
+ */
+export declare function usageChangesSql(dialect?: DialectName): string;
+/** The SQL that derives revenue events from the ledger (and the usage records), with compiler placeholders. */
+export declare function revenueEventDerivationSql(opts: DerivationOptions): string;
+/** The (field, dataset) pairs the derivation reads for the given source and usage setting. */
+export declare function derivationPairs(opts: Pick<DerivationOptions, "source" | "usage">): Array<[field: string, dataset: string]>;
+/** The derivation as a query template, so `fillTemplate` resolves it over an adapter or Ossie mapping like a metric's. */
+export declare function revenueEventDerivation(opts: DerivationOptions): QueryTemplate;
+/** The reference SQL over the GASP field names, as cel.md prints it. */
+export declare function referenceDerivationSql(currency?: string): string;
+/** The invoice source's ledger CTEs over the GASP field names, as cel.md prints them. */
+export declare function referenceInvoiceLedgerSql(): string;
+/** The usage CTEs over the GASP field names, as cel.md prints them. */
+export declare function referenceUsageSql(): string;
+export interface DeriveCelOptions {
+    dialect?: string;
+    currency?: string;
+    firstSnapshot?: "opening" | "steps";
+    source?: string;
+    usage?: boolean;
+    output?: "report" | "sql";
+}
+/**
+ * The derive_cel tool: the derivation compiled over a company's mapping (a GASP
+ * adapter or an Ossie mapping with its model), from the subscription or the
+ * invoice dataset, with the usage records when the mapping covers them, in the
+ * dialect asked for or the one the adapter's warehouse names, as a report or
+ * the SQL alone.
+ */
+export declare function deriveCelFromText(documentText: string | undefined, modelText: string | undefined, data: StandardData, opts?: DeriveCelOptions): string;

package/build/cel.js

@@ -0,0 +1,376 @@
+/**
+ * Deriving CEL Revenue_Events from a subscription ledger (standard/cel.md,
+ * "Deriving Revenue Events from a Subscription Ledger").
+ *
+ * Most billing systems hold subscriptions, not events: a row per subscription
+ * whose MRR and status change over time, kept as snapshots or as a version
+ * history. The CEL needs the movements between those states. The rules here
+ * turn the GASP `subscription` dataset into `revenue_event` rows and are the
+ * same for every source system; a vendor appears only in a mapping.
+ *
+ *   1. A subscription's MRR on a snapshot is its `mrr` when `subscription_status`
+ *      is active, else 0. A customer's MRR is the sum over its subscriptions.
+ *   2. A step is a snapshot whose MRR differs from the subscription's previous
+ *      snapshot (by snapshot_date). A subscription's first snapshot steps from 0.
+ *   3. Rows on the ledger's first snapshot date are opening balances: they seed
+ *      the customer's MRR and produce no event (`firstSnapshot: "steps"` turns
+ *      that off for a ledger that starts with the business). The ledger holds
+ *      one row per subscription per snapshot date and keeps a cancelled
+ *      subscription's row, since a subscription that stops appearing has no step.
+ *   4. One Revenue_Event per step, dated the snapshot that first shows the change.
+ *      mrr_change is the subscription's change; prior_mrr and new_mrr are the
+ *      customer's MRR before and after it, chained through the customer's steps
+ *      in (snapshot_date, increases before decreases, subscription_id) order, so
+ *      prior_mrr + mrr_change = new_mrr holds on every row and the rows of one
+ *      date add up.
+ *   5. event_type from the customer's MRR at the start and end of the date: an
+ *      increase from 0 is `new`, or `reactivation` when the customer was active
+ *      on an earlier date; a decrease to 0 is `churn`; any other increase is
+ *      `expansion` and any other decrease `contraction`. So a plan swap onto a
+ *      new subscription id is an expansion and a contraction, two subscriptions
+ *      cancelled on one date are two churns. `renewal` is not a movement and
+ *      comes from Contract_Event or the renewal fields.
+ *   6. lifecycle_attribution follows the ATL rules for each type; change_nature
+ *      is `permanent`; segment is the snapshot's; expansion_classification is
+ *      NULL, because the ledger does not say what kind of expansion it was (the
+ *      amendment does), and the readiness check for the ATL tag names the gap.
+ *   7. event_id is the subscription id and the snapshot date.
+ *
+ * The cadence of the ledger is the grain of the events: with daily snapshots
+ * every movement is seen on its day; with month-end snapshots the movements
+ * inside a month net to one event dated the month end, and a churn followed by
+ * a reactivation inside one interval leaves no event. Where amendment events
+ * exist they are the better source and the pairing rule in cel.md applies.
+ *
+ * Two more sources feed the same rules (cel.md, "Deriving Revenue Events from
+ * an Invoice Ledger" and "Deriving Usage Realisation"):
+ *
+ *   - An invoice ledger (`source: "invoice"`) is a subscription ledger with one
+ *     row per service period: an invoice's MRR is its `recurring_amount` over
+ *     the months its service period covers, a subscription's MRR on a date is
+ *     the sum over the invoices covering it, and its ledger dates are the
+ *     starts of its service periods and the day after each end, up to the
+ *     ledger's horizon (the latest service period start). Rules 2 to 7 then
+ *     apply unchanged. The invoice dataset carries no segment.
+ *   - Usage records (`usage: true`) add one pair of events per period in which
+ *     `usage_amount` exceeds `committed_amount`: an `expansion` dated the
+ *     period's end for the overage over the months the period covers, tagged
+ *     `usage_realisation` with `change_nature` `temporary`, and its
+ *     `scheduled_reversal`, a `contraction` dated the next day. The commitment
+ *     is already in the subscription's MRR, so usage within it is no event. The
+ *     pairs chain with the ledger's steps, so prior_mrr and new_mrr hold.
+ *
+ * The template uses the compiler's placeholders ({{field@dataset}},
+ * {{_table:dataset}}), so `fillTemplate` compiles it over any adapter or Ossie
+ * mapping that covers the fields it reads.
+ */
+import { DIALECT } from "./dialect.js";
+import { exampleSql } from "./compile.js";
+import { chooseDialect, fillTemplate, resolveAdapter } from "./tools.js";
+import { loadAdapter } from "./ossie/adapt.js";
+import { resolveDocLink } from "./urls.js";
+export const DERIVATION_DATASET = "subscription";
+/** The subscription fields the derivation reads, in the order the ledger CTE selects them. */
+export const DERIVATION_FIELDS = ["subscription_id", "customer_id", "snapshot_date", "mrr", "subscription_status", "segment"];
+/** The invoice fields the invoice source reads. */
+export const INVOICE_FIELDS = ["invoice_id", "subscription_id", "customer_id", "snapshot_date", "service_period_start", "service_period_end", "recurring_amount"];
+/** The usage_record fields the usage branch reads. */
+export const USAGE_FIELDS = ["subscription_id", "customer_id", "period_start", "period_end", "committed_amount", "usage_amount"];
+/** The revenue_event fields the derivation writes, in column order. */
+export const DERIVED_FIELDS = ["event_id", "event_date", "customer_id", "subscription_id", "event_type", "mrr_change", "currency", "prior_mrr", "new_mrr", "expansion_classification", "change_nature", "lifecycle_attribution", "segment"];
+export const DERIVATION_SOURCES = ["subscription", "invoice"];
+const ph = (field, dataset = DERIVATION_DATASET) => `{{${field}@${dataset}}}`;
+/** MRR is kept to the cent, so a chained total within half a cent of zero is zero (the sums are floats on some warehouses). */
+const ZERO = "0.005";
+/** The length of a period of whole days in months (365.25 / 12 days each), as a fraction. */
+const monthsExpr = (d, start, end) => `${d.periodDays(end, start)} * 12.0 / 365.25`;
+/**
+ * The months a period covers, from its length in months: the nearest whole
+ * number (so January and February are one month each and a year is twelve), or
+ * the fraction itself for a period shorter than about a fortnight.
+ */
+const MONTHS_COVERED = "CASE WHEN ROUND(months) < 1 THEN months ELSE ROUND(months) END";
+/** The `ledger` CTE of the subscription source: one row per subscription per snapshot date, MRR when active. */
+export function subscriptionLedgerSql() {
+    return `ledger AS (
+  SELECT ${ph("subscription_id")} AS subscription_id,
+         ${ph("customer_id")} AS customer_id,
+         ${ph("snapshot_date")} AS snapshot_date,
+         ${ph("segment")} AS segment,
+         CASE WHEN ${ph("subscription_status")} = 'active' THEN ROUND(COALESCE(${ph("mrr")}, 0), 2) ELSE 0 END AS mrr
+  FROM {{_table:${DERIVATION_DATASET}}}
+  WHERE ${ph("snapshot_date")} IS NOT NULL
+)`;
+}
+/**
+ * The `ledger` CTE of the invoice source: each invoice's latest snapshot, its MRR
+ * as the recurring amount over the months of its service period, the boundaries
+ * of each subscription's periods as its ledger dates and the invoices covering
+ * each date summed into its MRR, up to the ledger's horizon.
+ */
+export function invoiceLedgerSql(dialect = "postgres") {
+    const d = DIALECT[dialect];
+    const i = (f) => ph(f, "invoice");
+    return `invoices AS (
+  SELECT invoice_id, subscription_id, customer_id, service_period_start, service_period_end, recurring_amount
+  FROM (
+    SELECT ${i("invoice_id")} AS invoice_id,
+           ${i("subscription_id")} AS subscription_id,
+           ${i("customer_id")} AS customer_id,
+           ${i("service_period_start")} AS service_period_start,
+           ${i("service_period_end")} AS service_period_end,
+           ${i("recurring_amount")} AS recurring_amount,
+           ROW_NUMBER() OVER (PARTITION BY ${i("invoice_id")} ORDER BY ${i("snapshot_date")} DESC) AS latest
+    FROM {{_table:invoice}}
+    WHERE ${i("subscription_id")} IS NOT NULL AND ${i("service_period_start")} IS NOT NULL AND ${i("service_period_end")} IS NOT NULL
+  ) i
+  WHERE latest = 1
+),
+periods AS (
+  SELECT invoice_id, subscription_id, customer_id, service_period_start, service_period_end,
+         ROUND(COALESCE(recurring_amount, 0) / (${MONTHS_COVERED}), 2) AS mrr
+  FROM (
+    SELECT i.*, ${monthsExpr(d, "service_period_start", "service_period_end")} AS months FROM invoices i
+  ) m
+),
+boundaries AS (
+  SELECT subscription_id, customer_id, service_period_start AS snapshot_date FROM periods
+  UNION
+  SELECT subscription_id, customer_id, CAST(${d.plus("service_period_end", 1, "day")} AS DATE) FROM periods
+),
+horizon AS (
+  SELECT MAX(service_period_start) AS latest FROM periods
+),
+ledger AS (
+  SELECT b.subscription_id, b.customer_id, b.snapshot_date,
+         ${d.toText("NULL")} AS segment,
+         ROUND(COALESCE(SUM(p.mrr), 0), 2) AS mrr
+  FROM boundaries b
+  LEFT JOIN periods p ON p.subscription_id = b.subscription_id AND p.service_period_start <= b.snapshot_date AND b.snapshot_date <= p.service_period_end
+  WHERE b.snapshot_date <= (SELECT latest FROM horizon)
+  GROUP BY b.subscription_id, b.customer_id, b.snapshot_date
+)`;
+}
+/**
+ * The usage CTEs: each period whose usage exceeds its commitment, the overage
+ * over the months the period covers, and the pair of changes it adds to the
+ * customer's steps, a `usage` increase on the period's end and a
+ * `usage_reversal` decrease the day after.
+ */
+export function usageChangesSql(dialect = "postgres") {
+    const d = DIALECT[dialect];
+    const u = (f) => ph(f, "usage_record");
+    return `usage_periods AS (
+  SELECT subscription_id, customer_id, period_end,
+         ROUND(overage / (${MONTHS_COVERED}), 2) AS overage
+  FROM (
+    SELECT ${u("subscription_id")} AS subscription_id,
+           ${u("customer_id")} AS customer_id,
+           ${u("period_end")} AS period_end,
+           ${u("usage_amount")} - ${u("committed_amount")} AS overage,
+           ${monthsExpr(d, u("period_start"), u("period_end"))} AS months
+    FROM {{_table:usage_record}}
+    WHERE ${u("period_start")} IS NOT NULL AND ${u("period_end")} IS NOT NULL
+      AND ${u("usage_amount")} > ${u("committed_amount")}
+  ) u
+),
+usage_changes AS (
+  SELECT subscription_id, customer_id, period_end AS snapshot_date, ${d.toText("NULL")} AS segment, 0 AS opening, overage AS mrr_change, 'usage' AS kind
+  FROM usage_periods WHERE overage >= 0.01
+  UNION ALL
+  SELECT subscription_id, customer_id, CAST(${d.plus("period_end", 1, "day")} AS DATE), ${d.toText("NULL")}, 0, -overage, 'usage_reversal'
+  FROM usage_periods WHERE overage >= 0.01
+)`;
+}
+/** The SQL that derives revenue events from the ledger (and the usage records), with compiler placeholders. */
+export function revenueEventDerivationSql(opts) {
+    const d = DIALECT[opts.dialect ?? "postgres"];
+    if (!/^[A-Z]{3}$/.test(opts.currency))
+        throw new Error(`currency must be an ISO 4217 code, got ${JSON.stringify(opts.currency)}`);
+    const source = opts.source ?? "subscription";
+    if (!DERIVATION_SOURCES.includes(source))
+        throw new Error(`source must be one of ${DERIVATION_SOURCES.join(", ")}, got ${JSON.stringify(source)}`);
+    const opening = opts.firstSnapshot === "steps" ? "0" : "CASE WHEN snapshot_date = MIN(snapshot_date) OVER () THEN 1 ELSE 0 END";
+    // Within a date a customer's increases come before its decreases, then subscription id and kind, so the chained MRR is deterministic.
+    const chain = "PARTITION BY c.customer_id ORDER BY c.snapshot_date, CASE WHEN c.mrr_change > 0 THEN 0 ELSE 1 END, c.subscription_id, c.kind";
+    const ledger = source === "invoice" ? invoiceLedgerSql(d.name) : subscriptionLedgerSql();
+    const usage = opts.usage ? `,
+${usageChangesSql(d.name)}` : "";
+    const union = opts.usage ? `
+  UNION ALL
+  SELECT subscription_id, customer_id, snapshot_date, segment, opening, mrr_change, kind FROM usage_changes` : "";
+    return `WITH ${ledger},
+steps AS (
+  SELECT subscription_id, customer_id, snapshot_date, segment, mrr,
+         COALESCE(LAG(mrr) OVER (PARTITION BY subscription_id ORDER BY snapshot_date), 0) AS prior_sub_mrr,
+         ${opening} AS opening
+  FROM ledger
+)${usage},
+changes AS (
+  SELECT subscription_id, customer_id, snapshot_date, segment, opening,
+         mrr - prior_sub_mrr AS mrr_change, 'ledger' AS kind
+  FROM steps
+  WHERE mrr <> prior_sub_mrr${union}
+),
+day_changes AS (
+  SELECT customer_id, snapshot_date, SUM(mrr_change) AS day_change
+  FROM changes
+  GROUP BY customer_id, snapshot_date
+),
+days AS (
+  SELECT customer_id, snapshot_date, day_change,
+         SUM(day_change) OVER (PARTITION BY customer_id ORDER BY snapshot_date ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS day_end
+  FROM day_changes
+),
+day_state AS (
+  SELECT customer_id, snapshot_date, day_end - day_change AS day_start, day_end,
+         COALESCE(MAX(CASE WHEN day_end > ${ZERO} THEN 1 ELSE 0 END) OVER (PARTITION BY customer_id ORDER BY snapshot_date ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING), 0) AS active_before
+  FROM days
+),
+chained AS (
+  SELECT c.subscription_id, c.customer_id, c.snapshot_date, c.segment, c.opening, c.mrr_change, c.kind,
+         COALESCE(SUM(c.mrr_change) OVER (${chain} ROWS BETWEEN UNBOUNDED PRECEDING AND 1 PRECEDING), 0) AS prior_mrr,
+         SUM(c.mrr_change) OVER (${chain} ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW) AS new_mrr,
+         s.day_start, s.day_end, s.active_before
+  FROM changes c
+  JOIN day_state s ON s.customer_id = c.customer_id AND s.snapshot_date = c.snapshot_date
+),
+typed AS (
+  SELECT subscription_id, customer_id, snapshot_date, segment, opening, mrr_change, prior_mrr, new_mrr, kind,
+         CASE
+           WHEN kind = 'usage' THEN 'expansion'
+           WHEN kind = 'usage_reversal' THEN 'contraction'
+           WHEN mrr_change > 0 AND ABS(day_start) < ${ZERO} AND active_before = 1 THEN 'reactivation'
+           WHEN mrr_change > 0 AND ABS(day_start) < ${ZERO} THEN 'new'
+           WHEN mrr_change < 0 AND ABS(day_end) < ${ZERO} THEN 'churn'
+           WHEN mrr_change > 0 THEN 'expansion'
+           ELSE 'contraction'
+         END AS event_type
+  FROM chained
+)
+SELECT ${d.toText("subscription_id")} || CASE WHEN kind = 'ledger' THEN ':' ELSE ':usage:' END || ${d.toText("snapshot_date")} AS event_id,
+       snapshot_date AS event_date,
+       customer_id,
+       subscription_id,
+       event_type,
+       mrr_change,
+       '${opts.currency}' AS currency,
+       prior_mrr,
+       new_mrr,
+       CASE WHEN kind = 'ledger' THEN ${d.toText("NULL")} ELSE 'usage_realisation' END AS expansion_classification,
+       CASE kind WHEN 'usage' THEN 'temporary' WHEN 'usage_reversal' THEN 'scheduled_reversal' ELSE 'permanent' END AS change_nature,
+       CASE event_type
+         WHEN 'new' THEN 'acquisition'
+         WHEN 'expansion' THEN 'expansion'
+         WHEN 'reactivation' THEN 'reactivation'
+         ELSE 'retention'
+       END AS lifecycle_attribution,
+       segment
+FROM typed
+WHERE opening = 0
+ORDER BY snapshot_date, customer_id, CASE WHEN mrr_change > 0 THEN 0 ELSE 1 END, subscription_id, kind`;
+}
+/** The (field, dataset) pairs the derivation reads for the given source and usage setting. */
+export function derivationPairs(opts) {
+    const source = opts.source ?? "subscription";
+    const ledger = source === "invoice" ? INVOICE_FIELDS.map((f) => [f, "invoice"]) : DERIVATION_FIELDS.map((f) => [f, DERIVATION_DATASET]);
+    return opts.usage ? [...ledger, ...USAGE_FIELDS.map((f) => [f, "usage_record"])] : ledger;
+}
+/** The derivation as a query template, so `fillTemplate` resolves it over an adapter or Ossie mapping like a metric's. */
+export function revenueEventDerivation(opts) {
+    const source = opts.source ?? "subscription";
+    const pairs = derivationPairs(opts);
+    const datasets = [...new Set(pairs.map(([, ds]) => ds))];
+    return {
+        metric: "cel_revenue_events",
+        fields: [...new Set(pairs.map(([f]) => f))],
+        datasets,
+        sourceTable: source,
+        grain: "event",
+        frequency: source === "invoice" ? "as the service periods start and end" : "as the ledger is snapshotted",
+        source: source === "invoice" ? "invoice ledger" : "subscription ledger",
+        parameterizedQuery: revenueEventDerivationSql(opts),
+        staged: false,
+        placeholders: pairs.map(([f, ds]) => `${f}@${ds}`),
+    };
+}
+/** The reference SQL over the GASP field names, as cel.md prints it. */
+export function referenceDerivationSql(currency = "USD") {
+    return exampleSql(revenueEventDerivationSql({ dialect: "postgres", currency }));
+}
+/** The invoice source's ledger CTEs over the GASP field names, as cel.md prints them. */
+export function referenceInvoiceLedgerSql() {
+    return exampleSql(invoiceLedgerSql("postgres"));
+}
+/** The usage CTEs over the GASP field names, as cel.md prints them. */
+export function referenceUsageSql() {
+    return exampleSql(usageChangesSql("postgres"));
+}
+/**
+ * The derive_cel tool: the derivation compiled over a company's mapping (a GASP
+ * adapter or an Ossie mapping with its model), from the subscription or the
+ * invoice dataset, with the usage records when the mapping covers them, in the
+ * dialect asked for or the one the adapter's warehouse names, as a report or
+ * the SQL alone.
+ */
+export function deriveCelFromText(documentText, modelText, data, opts = {}) {
+    if (!documentText?.trim())
+        return "Pass adapter: your mapping as text, a GASP adapter (JSON) or an Ossie mapping document (YAML or JSON) with its semantic_model. Check it with validate_mapping first.";
+    const currency = opts.currency?.trim().toUpperCase();
+    if (!currency)
+        return "Pass currency: the ISO 4217 code of the ledger's currency (USD, EUR, GBP ...). Every derived event carries it; the subscription dataset has no currency field to read it from.";
+    if (!/^[A-Z]{3}$/.test(currency))
+        return `currency must be a three-letter ISO 4217 code, got ${JSON.stringify(opts.currency)}.`;
+    const source = (opts.source?.trim().toLowerCase() || "subscription");
+    if (!DERIVATION_SOURCES.includes(source))
+        return `source must be one of ${DERIVATION_SOURCES.join(", ")}, got ${JSON.stringify(opts.source)}.`;
+    const loaded = loadAdapter(documentText, modelText, data);
+    if (!loaded.adapter)
+        return loaded.error;
+    const chosen = chooseDialect(opts.dialect, loaded.adapter.warehouse);
+    if ("error" in chosen)
+        return chosen.error;
+    const resolved = resolveAdapter(loaded.adapter, data);
+    const usageMapped = Boolean(resolved.tables.usage_record) || Object.keys(resolved.columns.usage_record ?? {}).length > 0;
+    const usage = opts.usage ?? usageMapped;
+    const template = revenueEventDerivation({ dialect: chosen.dialect, currency, firstSnapshot: opts.firstSnapshot, source, usage });
+    const r = fillTemplate(template, loaded.adapter, data);
+    if (opts.output === "sql")
+        return r.sql;
+    const ledgerName = source === "invoice" ? "invoice ledger" : "subscription ledger";
+    const rulesAnchor = source === "invoice" ? "cel.md#deriving-revenue-events-from-an-invoice-ledger" : "cel.md#deriving-revenue-events-from-a-subscription-ledger";
+    const ledgerPairs = template.placeholders.filter((p) => !p.endsWith("@usage_record"));
+    const usagePairs = template.placeholders.filter((p) => p.endsWith("@usage_record"));
+    const mappedOf = (pairs) => pairs.filter((p) => r.mapped.some((m) => `${m.field}@${m.dataset}` === p)).length;
+    const p = [
+        `# CEL Revenue_Events derived from your ${ledgerName}${usage ? " and usage records" : ""}`,
+        `**Rules:** ${resolveDocLink(rulesAnchor)}${usage ? ` and ${resolveDocLink("cel.md#deriving-usage-realisation")}` : ""}`,
+        `**Mapping:** ${loaded.format === "v1" ? "GASP adapter" : "Ossie mapping"}${loaded.adapter.organization ? ` (${loaded.adapter.organization})` : ""}`,
+        `**Warehouse:** ${loaded.adapter.warehouse || "not specified"}`,
+        `**Dialect:** ${chosen.note}`,
+        `**Reads:** the \`${source}\` dataset, ${mappedOf(ledgerPairs)} / ${ledgerPairs.length} fields mapped${usage ? `; the \`usage_record\` dataset, ${mappedOf(usagePairs)} / ${usagePairs.length} fields mapped${opts.usage === undefined ? " (read because the mapping covers it; pass usage: false to leave it out)" : ""}` : usageMapped ? "" : "; no usage records (map the `usage_record` dataset, or pass usage: true, for the usage realisation events)"}`,
+        `**Writes:** one \`revenue_event\` row per movement (${DERIVED_FIELDS.join(", ")}), currency \`${currency}\``,
+    ];
+    if (r.missingFields.length)
+        p.push(`**Unmapped fields (left as placeholders):** \`${r.missingFields.join("\`, \`")}\`. Map each on its dataset and run again.`);
+    if (r.missingTables.length)
+        p.push(`**Dataset with no table:** ${r.missingTables.join(", ")}. Name its table under "datasets" in the adapter, or map one of its fields with a schema.table column reference.`);
+    for (const c of r.conflicts)
+        p.push(`**Conflict:** ${c}`);
+    const firstRows = opts.firstSnapshot === "steps"
+        ? "Every first row is a step from 0 (first_snapshot: steps), so the ledger must start with the business."
+        : "Rows on the ledger's first date are opening balances and produce no event; a customer that churned before the ledger starts comes back as new, not reactivation. Pass first_snapshot: steps if the ledger starts with the business.";
+    const limits = source === "invoice"
+        ? `**What the invoices can and cannot say.** Each invoice is read at its latest snapshot as one service period: its MRR is \`recurring_amount\` over the months the period covers (whole months for monthly, quarterly and annual billing; a prorated invoice for part of a period is approximate). A subscription's MRR on a date is the sum over the invoices covering it, its ledger dates are the starts of its service periods and the day after each end, and a date after the ledger's horizon (the latest service period start) is not read, so a subscription whose last invoice is still current does not churn. Invoices with no subscription or no service period (one-off charges) produce no event. ${firstRows} Each movement is dated the service period that first bills it, so a change agreed mid-period shows on the next period's start unless a prorated invoice was issued. The invoice dataset carries no segment, so \`segment\` is empty; fill it from the customer snapshot. \`expansion_classification\` is empty: the invoices show that MRR rose, not what was bought, and the Operating forms of ARR and NRR read that tag; fill it from your amendment records or record the classification as a decision. Where a subscription ledger exists it is the better source (source: subscription).`
+        : `**What the ledger can and cannot say.** Each movement is dated the snapshot that first shows it, so the ledger's cadence is the grain of the events: daily snapshots show every movement on its day, month-end snapshots net a month's movements into one event dated the month end. ${firstRows} The ledger needs one row per subscription per snapshot date and must keep a cancelled subscription's row; a subscription that stops appearing produces no churn. A null MRR on an active row counts as 0. \`expansion_classification\` is empty: the ledger shows that MRR rose, not what was bought, and the Operating forms of ARR and NRR read that tag; fill it from your amendment records or record the classification as a decision. Renewals change no MRR and are not derived here.`;
+    p.push("", limits);
+    if (usage)
+        p.push("", "**Usage realisation.** Each usage period whose `usage_amount` exceeds its `committed_amount` adds a pair of events: an `expansion` dated the period's end for the overage over the months the period covers, tagged `usage_realisation` with `change_nature` `temporary`, and a `contraction` the next day with `change_nature` `scheduled_reversal`. The commitment is already in the subscription's MRR, so usage within it is no event, and a commitment raised to cover the usage shows on the ledger as a permanent expansion. The pairs chain with the ledger's steps, so `prior_mrr` and `new_mrr` hold across both. Their ids are `<subscription_id>:usage:<date>`.");
+    p.push("", `Run the query to build (or rebuild) the \`revenue_event\` table; it reads the whole ledger and carries no period parameters. Map the result as the \`revenue_event\` dataset and the MRR movement metrics, NRR and GRR compile over it with generate_query or compile_model.`, "", "\`\`\`sql\n" + r.sql + "\n\`\`\`");
+    if (r.mapped.length) {
+        p.push("", "**Field mapping used:**");
+        for (const m of r.mapped)
+            p.push(`- \`${m.field}\` (${m.dataset}) → \`${m.ref}\`${m.transform ? ` (transform: ${m.transform})` : ""}`);
+    }
+    return p.join("\n");
+}