gasp-standard-mcp 1.9.0 → 1.11.0

package/README.md

@@ -1,6 +1,6 @@
 # gasp-standard-mcp
 
-MCP server for the [GASP Standard](https://gaspwiki.com) — the Generally Accepted SaaS Principles standard for metric definitions, formulas, benchmarks, and relationships.
+MCP server for the [GASP Standard](https://gaspwiki.com), the Generally Accepted SaaS Principles standard for metric definitions, formulas, benchmarks and relationships.
 
 Works with Claude Code, Claude Desktop, or any [MCP](https://modelcontextprotocol.io/)-compatible client.
 
@@ -33,35 +33,42 @@ Restart your MCP client after adding the config.
 
 | Tool | Description |
 |------|-------------|
-| `lookup_metric` | Full metric details: definition, formula, benchmarks, entity, common mistakes, sources |
+| `lookup_metric` | Full metric details: definition, formula, benchmarks, entity, common mistakes, sources and page URL. Matches exactly (name, abbreviation or slug) and suggests close names instead of guessing. Falls back to glossary terms when no metric matches |
+| `lookup_definition` | Glossary term lookup (e.g. Signal Type, Sensitivity Tier, Access Scope, Metric Owner, CEL): full definition, section, canonical or reference link and page URL. Matches exactly and suggests close terms instead of guessing |
 | `list_metrics` | List all metrics, optionally filtered by department and/or signal type |
-| `get_formula` | Get formula(s) for a metric |
-| `get_relationships` | Upstream/downstream relationships for metrics, entities, or concepts — 21 relationship types across signal, lifecycle, ownership, interaction, and financial flow categories |
-| `get_data_requirements` | Data requirements for implementing a metric: fields, types, grain, source, and example SQL |
-| `search` | Full-text search across metrics, definitions, and data requirements |
-| `generate_query` | Generate warehouse-specific SQL from a metric name + adapter mapping |
-| `validate_adapter` | Validate a GASP adapter mapping file — reports which metrics are fully/partially/not covered |
-| `infer_drivers` | Diagnose what could explain an observed metric movement — ranked upstream candidates with paths and per-step edge classifications |
+| `get_formula` | Canonical formula in the GASP formula grammar, with unit, O/M forms, variants, inputs with polarity, raw fields and the datasets they live in. Metrics that cannot be computed carry the reason |
+| `get_relationships` | Upstream/downstream relationships for metrics, entities or concepts. 21 relationship types across signal, lifecycle, ownership, interaction and financial flow categories |
+| `get_data_requirements` | Data requirements for implementing a metric: fields, types, grain, source and example SQL |
+| `search` | Full-text search across metrics, definitions and data requirements. Metric and definition hits include their gaspwiki.com URL |
+| `generate_query` | Compile warehouse-specific SQL from the metric's canonical formula and an adapter mapping. One scalar subquery per aggregate, each reading the table mapped for its dataset, with `:period_start` and `:period_end` parameters. Matches the metric exactly and suggests close names instead of guessing |
+| `validate_adapter` | Validate a GASP adapter mapping file (schema 1.1). Reports schema-level problems, unknown fields and datasets, dataset table conflicts, enum fields mapped without a transform and covered metrics without an owner. Computes coverage per metric against the fields its formula needs (full, partial or none) and ranks the highest-value next fields to map |
+| `infer_drivers` | Diagnose what could explain an observed metric movement: ranked upstream candidates with paths and per-step edge classifications |
 | `explain_path` | Enumerate edge chains between two metrics, with classification (metric_signal / structural / lifecycle / behavioral / assignment / generative) per step |
 | `coverage_gap` | Audit a metric set: identify one-hop upstream/downstream metrics not in the set, plus any disconnected metrics |
 
-The traversal tools (`infer_drivers`, `explain_path`, `coverage_gap`) return *structure* — paths, classifications, attenuation scores — not numeric forecasts. They serve diagnosis, exploration, and coverage-audit workflows respectively, and compose: use `infer_drivers` to pick candidates, `explain_path` to scrutinise a chain, then `coverage_gap` to check whether the candidate is being measured. For counterfactual "what if" simulation, use the [TWIN Modifier](https://gaspwiki.com/v1/twin-modifier).
+The traversal tools (`infer_drivers`, `explain_path`, `coverage_gap`) return *structure* (paths, classifications, attenuation scores), not numeric forecasts. They serve diagnosis, exploration and coverage-audit workflows respectively and compose: use `infer_drivers` to pick candidates, `explain_path` to scrutinise a chain, then `coverage_gap` to check whether the candidate is being measured. For counterfactual "what if" simulation, use the [TWIN Modifier](https://gaspwiki.com/v1/twin-modifier).
 
 ## Data
 
+Version 1.11.0.
+
 - 300 metrics across 13 departments
 - 92 glossary definitions (80 SaaS domain + 12 GASP framework)
-- 82 relationship nodes (60 metrics + 15 entities + 7 concepts), 164 edges
+- 82 relationship nodes (60 metrics + 15 entities + 7 concepts), 176 edges
 - 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)
-- 78 data requirements with field types, grain, and example SQL
-- 15 business entities (Customer, Subscription, License, Lead, Opportunity, User, Ticket, Employee, Invoice, Partner, Project, Plan, Product, Campaign, Contact)
-- 7 business concepts (Revenue, Bookings, COGS, Cohort, Pipeline, Segment, TCV)
-- 22 source categories, 198 canonical fields
-- 60 structured formulas with decomposed inputs (metric refs + field refs)
-- 60 temporal mappings (grain, frequency, period for every metric node)
+- 270 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
+- 270 query templates, one per metric with a formula, compiled from the formulas by the same step (no hand-written SQL)
+- 15 business entities (Customer, Subscription, License, Lead, Opportunity, User, Ticket, Employee, Invoice, Partner, Project, Plan, Product, Campaign and Contact)
+- 7 business concepts (Revenue, Bookings, COGS, Cohort, Pipeline, Segment and TCV)
+- 251 canonical fields across 47 datasets (event, snapshot and fact tables with date and key fields, entities, CEL class and activation rules). Enum fields declare their allowed values
+- 59 structured formulas with decomposed inputs (metric refs + field refs)
+- Canonical formulas for every metric in the GASP formula grammar (`standard/formulas.json`): 289 entries covering all 300 metrics (268 with formulas, 19 marked not computable with a reason, 2 department-qualified ids for shared headings), with units, O/M forms 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)
 - Per-department cross-references (e.g. NRR under Customer Success, Gross Margin under Finance) now resolve to the full canonical content via slug lookup
+- Every metric and definition result carries its gaspwiki.com page URL; definitions keep their full body and reference links
+- Access classifications, structured formulas and entity mappings resolve for every graph metric, including cross-reference records (e.g. NRR under Customer Success, CAC under Marketing)
+- Adapter schema 1.1 (`standard/gasp-adapter-schema.json`): a `datasets` map, per-dataset mappings (a mapping names its `dataset`), informational fields and `$schema`. A ready template ships at `gasp-wiki-frontend/public/downloads/gasp-adapter-template.json` and is tested against the schema
 - Sources: the canonical [GASP Standard](https://gaspwiki.com) files
 
 ## Examples
@@ -82,11 +89,13 @@ Once installed, ask your AI assistant:
 - "Search for churn"
 
 **Diagnosis, exploration and coverage** (new in 1.9.0)
-- "ARR is down this month. What could explain it?" — `infer_drivers`
-- "How does Win Rate eventually affect Free Cash Flow?" — `explain_path`
-- "We track ARR, NRR, GRR, CAC and CAC Payback. What important metrics are we missing?" — `coverage_gap`
-- "Why might NRR be slipping? Trace the path back through Health Score." — composes `infer_drivers` → `explain_path`
+- "ARR is down this month. What could explain it?" (`infer_drivers`)
+- "How does Health Score eventually affect NRR?" (`explain_path`)
+- "We track ARR, NRR, GRR, CAC and CAC Payback. What important metrics are we missing?" (`coverage_gap`)
+- "Why might NRR be slipping? Trace the path back through Health Score." (composes `infer_drivers` and `explain_path`)
 
 ## License
 
+<!-- TODO: add a "Source" link and package.json "repository" field to https://github.com/403pagelabs/gasp-wiki once the repository is public. -->
+
 Apache-2.0

package/build/compile.d.ts

@@ -0,0 +1,21 @@
+import type { MetricFormula, OntologyDataset, OntologyField } from "./types.js";
+export interface CompileContext {
+    fields: Record<string, OntologyField>;
+    datasets: Record<string, OntologyDataset>;
+    formulas: Record<string, MetricFormula>;
+}
+export interface Compiled {
+    /** Scalar SELECT with placeholders */
+    sql: string;
+    /** Every field placeholder the SQL uses, including through metric refs */
+    fields: string[];
+    datasets: string[];
+    metricRefs: string[];
+    /** Uses cohort or lag, so it cannot run as one Ossie aggregate */
+    staged: boolean;
+}
+export declare class CompileError extends Error {
+}
+export declare function compileMetric(id: string, ctx: CompileContext, variant?: string): Compiled;
+/** Replace placeholders with plain names, for documentation examples. */
+export declare function exampleSql(sql: string): string;

package/build/compile.js

@@ -0,0 +1,227 @@
+/**
+ * Compiles GASP formulas (src/formula.ts) to parameterised ANSI SQL.
+ *
+ * Every aggregate becomes a scalar subquery over one dataset, so metrics that
+ * combine several datasets need no joins: each aggregate is a number per
+ * period. Placeholders:
+ *   {{<field>}}            a canonical field; the adapter maps it to a column
+ *   {{_table:<dataset>}}   the warehouse table behind a dataset
+ *   {{_period_start}}, {{_period_end}}   reporting period bounds (dates)
+ *
+ * Period semantics by dataset kind: event and fact rows are filtered to the
+ * period by the dataset's date field; snapshot rows are taken as of the period
+ * end, or the point named by `at`. `to_date` widens an event or fact filter to
+ * everything up to the period end. `lag` shifts both bounds. `over cohort`
+ * restricts every aggregate to keys present in the key's dataset at the point.
+ */
+import { parseFormula } from "./formula.js";
+export class CompileError extends Error {
+}
+const TEMPORAL = new Set(["date", "timestamp"]);
+export function compileMetric(id, ctx, variant) {
+    const f = ctx.formulas[id];
+    if (!f)
+        throw new CompileError(`No formula for '${id}'`);
+    const src = variant ? f.forms?.[variant] ?? f.variants?.[variant] : f.formula;
+    if (!src)
+        throw new CompileError(f.notComputable ? `'${id}' is not computable: ${f.notComputable}` : `'${id}' has no ${variant ?? "formula"}`);
+    const c = new Compiler(ctx);
+    const body = c.formula(parseFormula(src), { toDate: false, shift: [], path: [id] });
+    return {
+        sql: `SELECT ${body} AS ${id.replace(/[^a-z0-9_]/gi, "_")}`,
+        fields: [...c.fields].sort(),
+        datasets: [...c.datasets].sort(),
+        metricRefs: [...c.metricRefs].sort(),
+        staged: c.staged,
+    };
+}
+/** Replace placeholders with plain names, for documentation examples. */
+export function exampleSql(sql) {
+    return sql
+        .replace(/\{\{_table:(\w+)\}\}/g, "$1")
+        .replace(/\{\{_period_start\}\}/g, ":period_start")
+        .replace(/\{\{_period_end\}\}/g, ":period_end")
+        .replace(/\{\{(\w+)\}\}/g, "$1");
+}
+class Compiler {
+    ctx;
+    fields = new Set();
+    datasets = new Set();
+    metricRefs = new Set();
+    staged = false;
+    constructor(ctx) {
+        this.ctx = ctx;
+    }
+    formula(f, scope) {
+        const s = f.cohort ? { ...scope, cohort: scope.cohort ?? f.cohort } : scope;
+        if (f.cohort) {
+            this.staged = true;
+            this.fields.add(f.cohort.key);
+        }
+        return this.expr(f.expr, s);
+    }
+    bound(point, scope) {
+        let b = `{{_period_${point === "period_start" ? "start" : "end"}}}`;
+        for (const sh of scope.shift)
+            b = `(${b} - INTERVAL '${sh.n} ${sh.unit}')`;
+        return b;
+    }
+    type(id) {
+        return this.ctx.fields[id]?.type;
+    }
+    isTemporal(n) {
+        if (n.kind === "field")
+            return TEMPORAL.has(this.type(n.id) ?? "");
+        if (n.kind === "period_bound")
+            return true;
+        return false;
+    }
+    expr(n, scope) {
+        switch (n.kind) {
+            case "number": return String(n.value);
+            case "string": return `'${n.value.replace(/'/g, "''")}'`;
+            case "boolean": return n.value ? "TRUE" : "FALSE";
+            case "field":
+                this.fields.add(n.id);
+                return `{{${n.id}}}`;
+            case "period_bound": return this.bound(n.point, scope);
+            case "period_days": return `(${this.bound("period_end", scope)} - ${this.bound("period_start", scope)} + 1)`;
+            case "metric": return this.metric(n.id, scope);
+            case "neg": return `(-${this.expr(n.arg, scope)})`;
+            case "binary": {
+                const l = this.expr(n.left, scope);
+                const r = this.expr(n.right, scope);
+                if (n.op === "-" && this.isTemporal(n.left) && this.isTemporal(n.right)) {
+                    const ts = [n.left, n.right].some((x) => x.kind === "field" && this.type(x.id) === "timestamp");
+                    return ts ? `(EXTRACT(EPOCH FROM (${l} - ${r})) / 86400.0)` : `(${l} - ${r})`;
+                }
+                if (n.op === "/")
+                    return n.right.kind === "number" ? `(${l} / ${r})` : `(${l} / NULLIF(${r}, 0))`;
+                return `(${l} ${n.op} ${r})`;
+            }
+            case "scalar": {
+                const fn = { min: "LEAST", max: "GREATEST", abs: "ABS", coalesce: "COALESCE" }[n.fn];
+                return `${fn}(${n.args.map((a) => this.expr(a, scope)).join(", ")})`;
+            }
+            case "compare": return `${this.expr(n.left, scope)} ${n.op === "!=" ? "<>" : n.op} ${this.expr(n.right, scope)}`;
+            case "in": return `${this.expr(n.arg, scope)} ${n.negated ? "NOT IN" : "IN"} (${n.values.map((v) => this.expr(v, scope)).join(", ")})`;
+            case "isnull": return `${this.expr(n.arg, scope)} IS ${n.negated ? "NOT " : ""}NULL`;
+            case "logic": return `(${this.expr(n.left, scope)} ${n.op.toUpperCase()} ${this.expr(n.right, scope)})`;
+            case "not": return `NOT (${this.expr(n.arg, scope)})`;
+            case "at": return this.expr(n.arg, { ...scope, point: scope.point ?? n.point }); // outer at wins
+            case "to_date": return this.expr(n.arg, { ...scope, toDate: true });
+            case "lag":
+                this.staged = true;
+                return this.expr(n.arg, { ...scope, shift: [...scope.shift, { n: n.n, unit: n.unit }] });
+            case "agg":
+            case "percentile": return this.aggregate(n, scope);
+        }
+    }
+    metric(id, scope) {
+        if (scope.path.includes(id))
+            throw new CompileError(`Cycle: ${[...scope.path, id].join(" -> ")}`);
+        const f = this.ctx.formulas[id];
+        if (!f?.formula)
+            throw new CompileError(`metric.${id} has no formula`);
+        this.metricRefs.add(id);
+        const inner = new Compiler(this.ctx);
+        const body = inner.formula(parseFormula(f.formula), { ...scope, path: [...scope.path, id] });
+        inner.fields.forEach((x) => this.fields.add(x));
+        inner.datasets.forEach((x) => this.datasets.add(x));
+        inner.metricRefs.forEach((x) => this.metricRefs.add(x));
+        this.staged ||= inner.staged;
+        return `(${body})`;
+    }
+    fieldsIn(n, out = new Set()) {
+        switch (n.kind) {
+            case "field":
+                out.add(n.id);
+                break;
+            case "binary":
+            case "logic":
+            case "compare":
+                this.fieldsIn(n.left, out);
+                this.fieldsIn(n.right, out);
+                break;
+            case "in":
+                this.fieldsIn(n.arg, out);
+                n.values.forEach((v) => this.fieldsIn(v, out));
+                break;
+            case "scalar":
+                n.args.forEach((a) => this.fieldsIn(a, out));
+                break;
+            case "neg":
+            case "lag":
+            case "at":
+            case "to_date":
+            case "not":
+            case "isnull":
+                this.fieldsIn(n.arg, out);
+                break;
+            case "agg":
+            case "percentile":
+                this.fieldsIn(n.arg, out);
+                if (n.where)
+                    this.fieldsIn(n.where, out);
+                break;
+        }
+        return out;
+    }
+    datasetFor(fieldIds) {
+        const sets = fieldIds.map((id) => {
+            const f = this.ctx.fields[id];
+            if (!f)
+                throw new CompileError(`Unknown field '${id}'`);
+            return f.datasets ?? [];
+        });
+        const shared = sets.reduce((a, b) => a.filter((x) => b.includes(x)));
+        if (shared.length === 0)
+            throw new CompileError(`Fields share no dataset: ${fieldIds.join(", ")}`);
+        // Prefer the dataset keyed by one of the fields, then the first declared.
+        return shared.find((d) => fieldIds.includes(this.ctx.datasets[d]?.key)) ?? shared[0];
+    }
+    aggregate(n, scope) {
+        const ids = [...this.fieldsIn(n)];
+        const ds = this.datasetFor(ids);
+        const meta = this.ctx.datasets[ds];
+        if (!meta)
+            throw new CompileError(`Unknown dataset '${ds}'`);
+        this.datasets.add(ds);
+        const inner = this.expr(n.arg, scope);
+        const agg = n.kind === "percentile" ? `PERCENTILE_CONT(${n.p}) WITHIN GROUP (ORDER BY ${inner})`
+            : n.fn === "count_distinct" ? `COUNT(DISTINCT ${inner})`
+                : n.fn === "median" ? `PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY ${inner})`
+                    : `${n.fn.toUpperCase()}(${inner})`;
+        const where = [];
+        const date = `{{${meta.date}}}`;
+        this.fields.add(meta.date);
+        if (meta.kind === "snapshot") {
+            where.push(`${date} = ${this.bound(scope.point ?? "period_end", scope)}`);
+        }
+        else if (scope.toDate) {
+            where.push(`${date} <= ${this.bound(scope.point ?? "period_end", scope)}`);
+        }
+        else if (scope.point) {
+            // A point on an event or fact dataset reads as everything up to that point.
+            where.push(`${date} <= ${this.bound(scope.point, scope)}`);
+        }
+        else {
+            where.push(`${date} >= ${this.bound("period_start", scope)}`, `${date} <= ${this.bound("period_end", scope)}`);
+        }
+        if (n.where)
+            where.push(this.expr(n.where, scope));
+        if (scope.cohort && (this.ctx.fields[scope.cohort.key]?.datasets ?? []).includes(ds)) {
+            const key = scope.cohort.key;
+            this.fields.add(key);
+            const keyDs = Object.entries(this.ctx.datasets).find(([, d]) => d.key === key)?.[0];
+            if (!keyDs)
+                throw new CompileError(`Cohort key '${key}' is not the key of any dataset`);
+            this.datasets.add(keyDs);
+            const kmeta = this.ctx.datasets[keyDs];
+            this.fields.add(kmeta.date);
+            const active = kmeta.activeWhen ? ` AND ${this.expr(parseFormula(kmeta.activeWhen).expr, scope)}` : "";
+            where.push(`{{${key}}} IN (SELECT {{${key}}} FROM {{_table:${keyDs}}} WHERE {{${kmeta.date}}} = ${this.bound(scope.cohort.point, { ...scope, shift: [] })}${active})`);
+        }
+        return `(SELECT ${agg} FROM {{_table:${ds}}} WHERE ${where.join(" AND ")})`;
+    }
+}

package/build/derive.d.ts

@@ -0,0 +1,17 @@
+#!/usr/bin/env node
+import type { StandardData } from "./types.js";
+export declare const DERIVED_FILES: {
+    ontology: string;
+    relationships: string;
+    cypher: string;
+    template: string;
+};
+/** Replace one top-level key's value in a JSON document without reformatting the rest. */
+export declare function replaceJsonSection(raw: string, key: string, value: unknown): string;
+export declare function computeDerived(data: StandardData, current: Record<keyof typeof DERIVED_FILES, string>): {
+    ontology: string;
+    relationships: string;
+    cypher: string;
+    template: string;
+};
+export declare function readCurrent(): Record<keyof typeof DERIVED_FILES, string>;

package/build/derive.js

@@ -0,0 +1,261 @@
+#!/usr/bin/env node
+/**
+ * Regenerates everything that derives from standard/formulas.json so no
+ * hand-maintained copy can drift from the canon:
+ *
+ *   standard/ontology.json            structuredFormulas, entityMappings, field metricCount
+ *   gasp-wiki-frontend/src/data/relationships.json   component and measures edges
+ *   gasp-wiki-frontend/public/downloads/gasp-knowledge-graph.cypher   whole file
+ *   gasp-wiki-frontend/public/downloads/gasp-adapter-template.json    whole file
+ *
+ * Usage: npm run derive          write the files
+ *        npm run derive:check    exit 1 if any file differs (used by tests)
+ */
+import { readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { loadStandard, metricFormulaId, isMetricStub } from "./loader.js";
+import { parseFormula, analyzeFormula } from "./formula.js";
+import { compileMetric } from "./compile.js";
+import { metricUrl } from "./urls.js";
+const root = join(new URL(".", import.meta.url).pathname, "..", "..");
+export const DERIVED_FILES = {
+    ontology: join(root, "standard", "ontology.json"),
+    relationships: join(root, "gasp-wiki-frontend", "src", "data", "relationships.json"),
+    cypher: join(root, "gasp-wiki-frontend", "public", "downloads", "gasp-knowledge-graph.cypher"),
+    template: join(root, "gasp-wiki-frontend", "public", "downloads", "gasp-adapter-template.json"),
+};
+/** Replace one top-level key's value in a JSON document without reformatting the rest. */
+export function replaceJsonSection(raw, key, value) {
+    const marker = `\n  "${key}": `;
+    const start = raw.indexOf(marker);
+    if (start < 0)
+        throw new Error(`Section "${key}" not found`);
+    const valueStart = start + marker.length;
+    let depth = 0, inStr = false, i = valueStart;
+    for (; i < raw.length; i++) {
+        const c = raw[i];
+        if (inStr) {
+            if (c === "\\")
+                i++;
+            else if (c === '"')
+                inStr = false;
+            continue;
+        }
+        if (c === '"')
+            inStr = true;
+        else if (c === "{" || c === "[")
+            depth++;
+        else if (c === "}" || c === "]") {
+            depth--;
+            if (depth === 0) {
+                i++;
+                break;
+            }
+        }
+    }
+    const body = JSON.stringify(value, null, 2).split("\n").map((l, idx) => (idx ? "  " + l : l)).join("\n");
+    return raw.slice(0, valueStart) + body + raw.slice(i);
+}
+const q = (s) => `'${String(s).replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+export function computeDerived(data, current) {
+    const ont = data.ontology;
+    const formulas = data.formulas;
+    const fields = Object.fromEntries(ont.fields.map((f) => [f.id, f]));
+    const ctx = { fields, datasets: ont.datasets, formulas };
+    const nodeIds = new Set(data.nodes.filter((n) => !n.nodeType || n.nodeType === "metric").map((n) => n.id));
+    const byId = new Map();
+    for (const m of data.metrics)
+        if (!isMetricStub(m))
+            byId.set(metricFormulaId(data, m), m);
+    const slugOf = (id) => byId.get(id)?.slug;
+    // ── per-formula analysis ────────────────────────────────────────────────
+    const exprsOf = (f) => [f.formula, ...Object.values(f.forms ?? {}), ...Object.values(f.variants ?? {})].filter(Boolean);
+    const usage = new Map();
+    const compiled = new Map();
+    for (const [id, f] of Object.entries(formulas)) {
+        for (const src of exprsOf(f))
+            for (const fid of analyzeFormula(parseFormula(src)).fieldRefs)
+                (usage.get(fid) ?? usage.set(fid, new Set()).get(fid)).add(id);
+        if (f.formula)
+            compiled.set(id, compileMetric(id, ctx));
+    }
+    // ── ontology: structuredFormulas, entityMappings, metricCount ─────────────
+    const structured = {
+        description: "Derived from formulas.json by `npm run derive` (gasp-wiki-mcp). Each graph metric: its canonical formula, the metrics it reads (with arithmetic role and polarity: how the metric moves when the input rises) and the fields it reads, for graph traversal.",
+    };
+    for (const id of [...nodeIds].sort()) {
+        const f = formulas[id];
+        if (!f?.formula)
+            continue;
+        const a = analyzeFormula(parseFormula(f.formula));
+        const entry = {
+            expression: f.formula,
+            inputs: a.metricRefs.map((ref) => ({ ref, role: a.metricRoles[ref], polarity: a.metricPolarity[ref].length > 1 ? "mixed" : a.metricPolarity[ref][0] })),
+            fields: compiled.get(id).fields,
+        };
+        if (f.variants?.adjusted)
+            entry.adjustedVariant = f.variants.adjusted;
+        structured[id] = entry;
+    }
+    const keyEntity = new Map();
+    for (const [dsId, ds] of Object.entries(ont.datasets))
+        for (const e of ds.entities ?? [])
+            if (ds.key.endsWith("_id"))
+                keyEntity.set(ds.key, e);
+    const entityMappings = Object.fromEntries(ont.entities.map((e) => [e.id, []]));
+    for (const [id, c] of compiled) {
+        const ents = new Set();
+        for (const d of c.datasets)
+            for (const e of ont.datasets[d].entities ?? [])
+                ents.add(e);
+        for (const fid of c.fields) {
+            const e = keyEntity.get(fid);
+            if (e)
+                ents.add(e);
+        }
+        for (const e of ents)
+            entityMappings[e]?.push(id);
+    }
+    for (const k of Object.keys(entityMappings))
+        entityMappings[k].sort();
+    const fieldsOut = ont.fields.map((f) => {
+        const { metricCount: _old, ...rest } = f;
+        const out = {};
+        for (const k of ["id", "type", "datasets", "sources", "values", "dimension", "description"])
+            if (rest[k] !== undefined)
+                out[k] = rest[k];
+        out.metricCount = usage.get(f.id)?.size ?? 0;
+        return out;
+    });
+    let ontology = replaceJsonSection(current.ontology, "fields", fieldsOut);
+    ontology = replaceJsonSection(ontology, "entityMappings", entityMappings);
+    ontology = replaceJsonSection(ontology, "structuredFormulas", structured);
+    // ── relationships.json: component + measures edges ───────────────────────
+    const rel = JSON.parse(current.relationships);
+    const kept = rel.edges.filter((e) => e.type !== "component" && e.type !== "measures");
+    const component = [];
+    for (const id of [...nodeIds].sort()) {
+        const f = formulas[id];
+        if (!f?.formula)
+            continue;
+        for (const ref of analyzeFormula(parseFormula(f.formula)).metricRefs)
+            if (nodeIds.has(ref))
+                component.push({ source: ref, target: id, type: "component" });
+    }
+    const measures = [];
+    const entityNodes = new Set(data.nodes.filter((n) => n.nodeType === "entity").map((n) => n.id));
+    for (const [e, ids] of Object.entries(entityMappings))
+        for (const id of ids)
+            if (nodeIds.has(id) && entityNodes.has(`entity_${e}`))
+                measures.push({ source: id, target: `entity_${e}`, type: "measures" });
+    rel.edges = [...kept.filter((e) => nodeIds.has(e.source) && nodeIds.has(e.target)), ...component, ...measures, ...kept.filter((e) => !(nodeIds.has(e.source) && nodeIds.has(e.target)))];
+    const relationships = JSON.stringify(rel, null, 2) + "\n";
+    // ── cypher ────────────────────────────────────────────────────────────────
+    const L = [];
+    const metricNodes = data.nodes.filter((n) => nodeIds.has(n.id));
+    const entityEdges = ont.entityRelationships?.edges ?? [];
+    const metricEdges = rel.edges.filter((e) => nodeIds.has(e.source) && nodeIds.has(e.target));
+    const temporal = JSON.parse(current.ontology);
+    const sourcedFrom = ont.fields.flatMap((f) => (f.sources ?? []).map((s) => [f.id, s]));
+    const belongs = ont.fields.flatMap((f) => (f.datasets ?? []).map((d) => [f.id, d]));
+    L.push("// ═══════════════════════════════════════════════════════════════", "// GASP Standard — SaaS Metric Knowledge Graph (Full Ontology)", "// Generated from the GASP Standard (https://gaspwiki.com) by `npm run derive`", "// ═══════════════════════════════════════════════════════════════", "//", `// Nodes: ${metricNodes.length} Metrics, ${ont.entities.length} Entities, ${ont.concepts.length} Concepts, ${Object.keys(ont.datasets).length} Datasets, ${ont.fields.length} Fields, ${ont.sourceCategories.length} Source Categories`, `// Edges: ${metricEdges.length} metric relationships, ${measures.length} MEASURES, ${entityEdges.length} entity/concept relationships, ${belongs.length} BELONGS_TO, ${sourcedFrom.length} SOURCED_FROM`, "//", "// Relationship types (metric signal): DRIVES, REDUCES, PREDICTS, COMPONENT_OF, MEASURES", "// Relationship types (entity): " + Object.values(ont.entityRelationships?.edgeTypeClassification ?? {}).flat().join(", "), "// Relationship types (data lineage): BELONGS_TO (Field → Dataset), SOURCED_FROM (Field → SourceCategory)", "//", "// Import: paste into Neo4j Browser or pipe to cypher-shell", "// ═══════════════════════════════════════════════════════════════", "", "// Clean slate (optional, uncomment to clear existing data)", "// MATCH (n) DETACH DELETE n;", "");
+    L.push(`// ─── Metric Nodes (${metricNodes.length}) ─────────────────────────`);
+    for (const n of metricNodes) {
+        const m = byId.get(n.id) ?? data.metrics.find((x) => metricFormulaId(data, x) === n.id);
+        const t = temporal.temporalSemantics?.[temporal.temporalMapping?.[n.id]] ?? {};
+        const props = [`id: ${q(n.id)}`, `name: ${q(n.label)}`, `department: ${q(n.department ?? m?.department ?? "")}`, `signalType: ${q(n.signalType ?? "")}`, `level: ${n.level ?? 0}`,
+            `definition: ${q(m?.definition ?? n.description ?? "")}`, `formula: ${q(formulas[n.id]?.formula ?? m?.formulas?.[0] ?? "")}`, `url: ${q(m ? metricUrl(m) : "")}`];
+        if (t.grain)
+            props.push(`grain: ${q(t.grain)}`, `frequency: ${q(t.frequency)}`, `period: ${q(t.period)}`);
+        L.push(`CREATE (:Metric {${props.join(", ")}});`);
+    }
+    L.push("", `// ─── Entity Nodes (${ont.entities.length}) ──────────────────────────`);
+    for (const e of ont.entities)
+        L.push(`CREATE (:Entity {id: ${q(e.id)}, name: ${q(e.label)}, aliases: ${q((e.aliases ?? []).join(", "))}, definition: ${q(e.definition)}, level: ${q(e.level ?? "")}});`);
+    L.push("", `// ─── Concept Nodes (${ont.concepts.length}) ───────────────────────`);
+    for (const c of ont.concepts)
+        L.push(`CREATE (:Concept {id: ${q(c.id)}, name: ${q(c.label)}, definition: ${q(c.definition)}});`);
+    L.push("", `// ─── Source Category Nodes (${ont.sourceCategories.length}) ──────────────`);
+    for (const s of ont.sourceCategories)
+        L.push(`CREATE (:SourceCategory {id: ${q(s.id)}, name: ${q(s.label ?? s.id)}, description: ${q(s.description ?? "")}});`);
+    L.push("", `// ─── Dataset Nodes (${Object.keys(ont.datasets).length}) ─────────────────────────────`);
+    for (const [id, d] of Object.entries(ont.datasets))
+        L.push(`CREATE (:Dataset {id: ${q(id)}, name: ${q(d.label)}, kind: ${q(d.kind)}, dateField: ${q(d.date)}, keyField: ${q(d.key)}${d.cel ? `, cel: ${q(d.cel)}` : ""}});`);
+    L.push("", `// ─── Field Nodes (${ont.fields.length}) ─────────────────────────────`);
+    for (const f of fieldsOut)
+        L.push(`CREATE (:Field {id: ${q(f.id)}, type: ${q(f.type)}, metricCount: ${f.metricCount}${f.values ? `, values: ${q(f.values.join("|"))}` : ""}});`);
+    L.push("", `// ─── Metric Relationships (${metricEdges.length}) ──────────────────`);
+    for (const e of metricEdges)
+        L.push(`MATCH (a:Metric {id: ${q(e.source)}}), (b:Metric {id: ${q(e.target)}})`, `CREATE (a)-[:${e.type === "component" ? "COMPONENT_OF" : String(e.type).toUpperCase()}]->(b);`);
+    L.push("", `// ─── MEASURES Edges (${measures.length}) ──────────────────────────`);
+    for (const e of measures)
+        L.push(`MATCH (m:Metric {id: ${q(e.source)}}), (e:Entity {id: ${q(e.target.replace("entity_", ""))}})`, `CREATE (m)-[:MEASURES]->(e);`);
+    L.push("", `// ─── BELONGS_TO Edges (${belongs.length}) ─────────────────────────────`);
+    for (const [f, d] of belongs)
+        L.push(`MATCH (f:Field {id: ${q(f)}}), (d:Dataset {id: ${q(d)}})`, `CREATE (f)-[:BELONGS_TO]->(d);`);
+    L.push("", `// ─── SOURCED_FROM Edges (${sourcedFrom.length}) ─────────────────────────────`);
+    for (const [f, s] of sourcedFrom)
+        L.push(`MATCH (f:Field {id: ${q(f)}}), (s:SourceCategory {id: ${q(s)}})`, `CREATE (f)-[:SOURCED_FROM]->(s);`);
+    const conceptIds = new Set(ont.concepts.map((c) => c.id));
+    const classOf = (type) => Object.entries(ont.entityRelationships?.edgeTypeClassification ?? {}).find(([, ts]) => ts.includes(type))?.[0] ?? "other";
+    L.push("", `// ─── Entity Relationships (${entityEdges.length}) ──────────────`);
+    for (const cls of [...new Set(entityEdges.map((e) => classOf(e.type)))]) {
+        L.push(`// ${cls[0].toUpperCase()}${cls.slice(1)}`);
+        for (const e of entityEdges.filter((x) => classOf(x.type) === cls)) {
+            const target = conceptIds.has(e.to) ? `(t:Concept {id: ${q(e.to)}})` : `(t:Entity {id: ${q(e.to)}})`;
+            L.push(`MATCH (s:Entity {id: ${q(e.from)}}), ${target}`, `CREATE (s)-[:${e.type} {cardinality: ${q(e.cardinality)}, provenance: ${q(e.provenance)}}]->(t);`);
+        }
+    }
+    L.push("", "// ─── Indexes ──────────────────────────────────────────", "CREATE INDEX metric_id IF NOT EXISTS FOR (m:Metric) ON (m.id);", "CREATE INDEX metric_dept IF NOT EXISTS FOR (m:Metric) ON (m.department);", "CREATE INDEX metric_signal IF NOT EXISTS FOR (m:Metric) ON (m.signalType);", "CREATE INDEX entity_id IF NOT EXISTS FOR (e:Entity) ON (e.id);", "CREATE INDEX concept_id IF NOT EXISTS FOR (c:Concept) ON (c.id);", "CREATE INDEX dataset_id IF NOT EXISTS FOR (d:Dataset) ON (d.id);", "CREATE INDEX field_id IF NOT EXISTS FOR (f:Field) ON (f.id);", "CREATE INDEX source_id IF NOT EXISTS FOR (s:SourceCategory) ON (s.id);", "");
+    const cypher = L.join("\n");
+    // ── adapter template ──────────────────────────────────────────────────────
+    const label = new Map(ont.sourceCategories.map((s) => [s.id, s.label ?? s.id]));
+    const template = {
+        $schema: "https://gaspwiki.com/schemas/gasp-adapter-v1.json",
+        version: "1.1",
+        organization: "",
+        warehouse: "",
+        _instructions: "Map a warehouse table to each dataset you have (schema.table) and a column to each field (a bare column name, or schema.table.column). Fields that live on several datasets appear once per dataset; fill the ones you have. Fields you cannot map can be left with an empty warehouseRef or removed. Enum fields list the values the column must produce after transform. Run validate_adapter (GASP MCP) to see which metrics you can compute and which owners are missing.",
+        metricOwners: [],
+        datasets: Object.fromEntries(Object.keys(ont.datasets).sort().map((d) => [d, ""])),
+        mappings: ont.fields.flatMap((f) => {
+            const usedBy = [...(usage.get(f.id) ?? [])].map((id) => byId.get(id)?.name ?? id).sort();
+            const row = (dataset) => {
+                const m = { gaspField: f.id };
+                if (dataset)
+                    m.dataset = dataset;
+                m.type = f.type;
+                m.warehouseRef = "";
+                if (f.values)
+                    m.values = f.values;
+                m.source = label.get(f.sources?.[0] ?? "") ?? "";
+                m.usedBy = usedBy;
+                return m;
+            };
+            return (f.datasets ?? []).length > 1 ? f.datasets.map((d) => row(d)) : [row()];
+        }),
+    };
+    return { ontology, relationships, cypher, template: JSON.stringify(template, null, 2) + "\n" };
+}
+export function readCurrent() {
+    return Object.fromEntries(Object.entries(DERIVED_FILES).map(([k, p]) => [k, readFileSync(p, "utf-8")]));
+}
+const isMain = process.argv[1] && import.meta.url.endsWith(process.argv[1].split("/").pop().replace(/\.ts$/, ".js")) || process.argv[1]?.endsWith("derive.ts");
+if (isMain) {
+    const check = process.argv.includes("--check");
+    const current = readCurrent();
+    const out = computeDerived(loadStandard(), current);
+    const changed = Object.keys(out).filter((k) => out[k] !== current[k]);
+    if (check) {
+        if (changed.length) {
+            console.error(`Derived files out of date: ${changed.join(", ")}. Run npm run derive.`);
+            process.exit(1);
+        }
+        console.log("Derived files are current.");
+    }
+    else {
+        for (const k of changed)
+            writeFileSync(DERIVED_FILES[k], out[k]);
+        console.log(changed.length ? `Updated ${changed.join(", ")}` : "No changes.");
+    }
+}