@datarails-ai/dr-appspace-cli 0.12.35 → 0.12.37

package/dist/cli.js

@@ -13,7 +13,7 @@ import { fileURLToPath as fileURLToPath6 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-appspace-cli",
-  version: "0.12.35",
+  version: "0.12.37",
   description: "Datarails App Space CLI \u2014 build, try, push and publish App Space apps",
   type: "module",
   engines: {
@@ -57,7 +57,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-26T12:46:38.741Z";
+var BUILD_TIME = "2026-10-26T14:01:26.088Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -6140,6 +6140,15 @@ function rendererOf(pages) {
   }
   return {};
 }
+function metricsOf(pages) {
+  for (const page of pages ?? []) {
+    const embedded = embeddedContractOf(page);
+    if (embedded === null) continue;
+    const metrics = embedded.data?.metrics;
+    return isPlainObject(metrics) ? { metrics } : {};
+  }
+  return {};
+}
 function cardSpecOf(element) {
   const card = element?.props?.card;
   return element?.type === "widget" && typeof card === "string" && card !== "" ? card : null;
@@ -6729,7 +6738,9 @@ function dataSection(app, manifest, spec, elements, describe7, problems) {
     ...application === null ? {} : { app: application },
     // Only when there are any: a contract written before sources existed
     // reads back byte for byte as it always did.
-    ...Object.keys(sources).length > 0 ? { sources } : {}
+    ...Object.keys(sources).length > 0 ? { sources } : {},
+    // The same for declared metrics, which only an app's pages carry.
+    ...isApp ? metricsOf(app.pages) : {}
   };
   if (describe7) {
     const widgets2 = isPlainObject(describe7.widgets) ? describe7.widgets : {};
@@ -7780,8 +7791,11 @@ var contract_schema_default = {
             required: ["from"],
             properties: {
               from: {
-                description: 'one of four spellings: {"financeos": {...}} (the dashboard SPEC source vocabulary), {"table": "<app table>"}, {"call": "<dotted method>", "args": {...}}, or ["<source>", ...] to compose others (with a transform, or with an expr the platform evaluates)',
-                oneOf: [{ type: "object" }, { type: "array", items: { type: "string" } }]
+                description: 'one of four spellings: {"financeos": {...}} (the dashboard SPEC source vocabulary; a metric is {"metric": "@<key>"}, a key data.metrics declares, or {"metric_id": <id>}, which ties the app to one company), {"table": "<app table>"}, {"call": "<dotted method>", "args": {...}}, or ["<source>", ...] to compose others (with a transform, or with an expr the platform evaluates)',
+                oneOf: [
+                  { type: "object", properties: { financeos: { type: "object", properties: { metric: { type: "string", description: 'OPTIONAL. The metric this source reads, as "@<key>": a key data.metrics declares ("@revenue_mom"). `app-space ship` binds the key to the company\'s own metric, so the contract names no metric id; the read parameters beside it (scenario, aggregation_type, period, honors, drill_rows, filterable) are what they are for metric_id, and the two never stand on one source. The compiler refuses the rest (source_metric).' } } } } },
+                  { type: "array", items: { type: "string" } }
+                ]
               },
               expr: { type: "string", description: "OPTIONAL, beside from as a list and no transform (lineage tier 3, docs/appspace/design-computed-card-lineage.md): the source's figure as a formula over its from sources' figures, which the PLATFORM evaluates, so the figure is made of Datarails reads and never computed by the app. It may use numbers, the operands' names, + - * / and parentheses (/ is a safe divide: a zero or missing divisor is no figure, and any missing figure makes the result none), and abs(x), min(a, b, ...), max(a, b, ...), round(x) or round(x, decimals 0-6, half away from zero), and if(comparison, then, else), the one place a comparison (< <= > >= == !=) may stand. Shape kpi (the value, and the compare where every operand carries one), series (point by point: each series operand draws one line, and a kpi operand is one figure at every point) or breakdown (member by member: every breakdown operand states top: null, and a kpi operand is one figure for every member). Its figure comes from an operand on every path: each branch of if() and each argument of min()/max() reads an operand, so a number alone (870000, or a fallback 0) is never the figure; write actual / budget, not if(budget > 0, actual / budget, 0). Every operand is a FinanceOS table read or metric (from.financeos) or another expr source over them - never a transform's output, a composed source, a call or an app table (a KPI belongs in the Datarails semantic layer, not in app data) - and every operand is used; compare is not stated here (it is the formula over the operands' compares). The compiler refuses the rest (source_expr)." },
               shape: { enum: ["rows", "series", "kpi", "breakdown", "table", "ohlc", "scatter", "narrative"] },
@@ -7798,6 +7812,53 @@ var contract_schema_default = {
             }
           }
         },
+        metrics: {
+          $comment: "Present only for kind: app, and only when the contract declares any (docs/appspace/research/2026-10-25-datarails-calc-layer/06-design-contract-declared-metrics.md \xA72). The package carries it in the contract its pages embed. The key pattern and the per-kind rules are the compiler's (this schema has no propertyNames and no conditional keyword): metric_decl, metric_kind_later, metric_formula, metric_base, metric_format.",
+          type: "object",
+          description: `the Datarails metrics this app reads, declared rather than addressed by id, keyed by a local name: a lowercase letter, then lowercase letters, digits or _ (revenue_mom), never sent to Datarails. A source reads one with from.financeos.metric "@<key>" and a CALC formula with [@<key>]. \`app-space ship\` binds each key in the company it ships to: it reuses the company's metric with the same definition, or the one with the same name when reuse is "name", and creates it otherwise (create), as the person shipping; a metric with the declared name and another definition is refused, never suffixed. So the contract names no company's metric, and every figure stays a Datarails metric read, the same number MCP and DR.METRIC give. A declaration with no definition binds the company's own metric by name: {"name": "Revenue", "reuse": "name", "create": false}.`,
+          additionalProperties: {
+            type: "object",
+            required: ["name"],
+            additionalProperties: false,
+            properties: {
+              name: { type: "string", minLength: 1, maxLength: 128, description: `the metric's name in Datarails, which finance users, MCP and DR.METRIC see, so a name a finance team would use ("Revenue MoM growth"), never an app id: at most 128 characters, no ' [ or ] (a CALC formula's reference delimiters), not starting with @, and not DAYS_IN_PERIOD or PERIODS_IN_YEAR (Datarails reserves both)` },
+              kind: { enum: ["base", "calc", "driver"], description: "base (a table's value field aggregated by its date field) or calc (a formula over other declared metrics). driver is reserved: the compiler refuses it (metric_kind_later) until driver declarations ship. Absent only on a declaration with no definition (create: false, reuse: name)" },
+              formula: { type: "string", description: "calc only: the metric in Datarails' CALC syntax: numbers, + - * / and parentheses over operands, each [@<key>] (another metric this block declares) or a system variable written bare, PERIODS_IN_YEAR or DAYS_IN_PERIOD. An operand may carry one modifier: .SHIFT(unit, offset), unit year, quarter, month, day or consumption_period and offset 0 to -1200, or .AS_OF(anchor), anchor year_end, quarter_end or month_end. A window function avg|min|max([@<key>], unit, periods), unit year, quarter or month and periods 1 to 120, compiles with a warning (metric_window): Datarails evaluates it only where the company has scenario_bound_calculations on. Never a metric's name, quoted or bracketed ('Revenue', [Revenue]): the contract names no company's metric. No scenario pin (| Budget), at least one [@<key>], at most 5000 characters, and no declaration that reads itself, however far round. ([@revenue] - [@revenue].SHIFT(month, -1)) / [@revenue].SHIFT(month, -1)" },
+              table: {
+                type: "object",
+                additionalProperties: false,
+                description: 'base only: the FinanceOS table, exactly one of {"alias": "<table alias>"} or {"name": "<table name>"}, resolved in the company at ship, or {"id": <id>}, which ties the app to one company as metric_id does',
+                properties: {
+                  alias: { type: "string", minLength: 1 },
+                  name: { type: "string", minLength: 1 },
+                  id: { type: "integer", minimum: 1 }
+                }
+              },
+              value: { type: "string", minLength: 1, description: "base only: the field aggregated, by its alias, falling back to its name; resolved to the field's id in the company at ship" },
+              date: { type: "string", minLength: 1, description: "base only: the field the metric's periods come from, by its alias, falling back to its name" },
+              aggregate: { enum: ["sum", "count", "cumulative_sum", "cumulative_count"], description: "base only: how the value field aggregates in a period; the cumulative ones carry the total forward" },
+              time_aggregation: { enum: ["sum", "eop", "avg"], description: "OPTIONAL, base only: how periods roll up into a longer one (a quarter of months). Absent: sum, or eop for a cumulative aggregate, which may not roll up with sum" },
+              filters: {
+                type: "array",
+                description: 'OPTIONAL, base only: the rows the metric reads, each {"field": "<alias or name>", "values": [...], "exclude": false}; exclude: true reads every row but those values',
+                items: {
+                  type: "object",
+                  required: ["field", "values"],
+                  additionalProperties: false,
+                  properties: {
+                    field: { type: "string", minLength: 1 },
+                    values: { type: "array", minItems: 1, items: { type: ["string", "number"] } },
+                    exclude: { type: "boolean" }
+                  }
+                }
+              },
+              format: { type: "string", description: `OPTIONAL: the metric's display in Datarails (its Metric page, MCP, Excel), one of the 180 strings the metric editor writes: an optional currency prefix ("$" quoted, or \u20AC \xA3 \u20AA), #,### or ####, optional decimals .# to .####, an optional scale [kilo]k or [mega]M, and an optional % suffix (never with a currency): #,###  "$"#,###.##  ####.#%. A card keeps its own format` },
+              description: { type: "string", description: "OPTIONAL: what the metric is, in words, for its page in Datarails" },
+              reuse: { enum: ["definition", "name"], description: "OPTIONAL. definition (the default): bind only a company metric whose definition matches this one. name: bind the company's metric of this name whatever its definition, so a finance team's own Revenue wins; created from this definition when the company has none" },
+              create: { type: "boolean", description: "OPTIONAL. true (the default): create the metric when the company has none to bind. false: bind only, never create; a declaration with no definition says false" }
+            }
+          }
+        },
         library: {
           oneOf: [
             { type: "null" },
@@ -10469,14 +10530,14 @@ var PROP_ORDER = ["kind", "params", "title", "subtitle", "description", "source"
 function compile(contract, { kit, extra = {} } = {}) {
   if (!isPlainObject6(kit)) throw new TypeError("compile(contract, {kit}): the kit manifest (kit.json) says which shelf modules a page loads");
   const problems = [];
-  const refuse = (code, where2, message) => {
+  const refuse2 = (code, where2, message) => {
     problems.push({ code, where: where2, lossy: false, message });
     return { files: {}, problems };
   };
   const source = isPlainObject6(contract) ? contract : {};
   const kind = source.app?.kind ?? null;
   if (kind !== "dashboard") {
-    return refuse(
+    return refuse2(
       "kind_not_compilable",
       MANIFEST_FILE,
       `this compiler writes dashboards; app.kind is ${JSON.stringify(kind)}, and a kind: app contract is compiled by compileApp`
@@ -10484,23 +10545,23 @@ function compile(contract, { kit, extra = {} } = {}) {
   }
   if (source.app?.renderer === RUNTIME_RENDERER2) return compileApp(source, { kit, extra });
   if (source.app?.renderer !== void 0) {
-    return refuse(
+    return refuse2(
       "renderer_not_compilable",
       MANIFEST_FILE,
       `app.renderer is ${JSON.stringify(source.app.renderer)}; the one renderer a dashboard may name is ${JSON.stringify(RUNTIME_RENDERER2)} (the app runtime, whose page compileApp writes), and absent means the dr-widgets page this compiler writes. Remove it, or set it to ${JSON.stringify(RUNTIME_RENDERER2)}`
     );
   }
   const described = describeTier(source.data);
-  if (described !== null) return refuse("describe_tier_not_compilable", described.where, described.message);
+  if (described !== null) return refuse2("describe_tier_not_compilable", described.where, described.message);
   const { contract: composed, applied } = composeLayout(source);
   for (const fill of applied) {
     problems.push({ code: "layout_composed", where: fill.where, lossy: false, message: `${fill.message} (${fill.what})` });
   }
   const pages = [...Array.isArray(composed.pages) ? composed.pages : []].sort((a, b) => natural3(a.path ?? "", b.path ?? ""));
-  if (pages.length === 0) return refuse("no_pages", MANIFEST_FILE, "the contract declares no pages; a dashboard is one page of widgets or more");
+  if (pages.length === 0) return refuse2("no_pages", MANIFEST_FILE, "the contract declares no pages; a dashboard is one page of widgets or more");
   const handlers = [...new Set(pages.map((page) => page.mount?.handler).filter((name) => typeof name === "string" && name !== ""))];
   if (handlers.length !== 1) {
-    return refuse(
+    return refuse2(
       "one_handler_per_dashboard",
       MANIFEST_FILE,
       handlers.length === 0 ? "no page names a mount handler; every widget on a dashboard is answered by one handler" : `the pages name ${handlers.length} mount handlers (${handlers.join(", ")}); a dashboard has one, and a second source is a second ROW in its SPEC`
@@ -10508,7 +10569,7 @@ function compile(contract, { kit, extra = {} } = {}) {
   }
   const handlerName = handlers[0];
   const handler = dashboardHandler(composed, handlerName, extra);
-  if (handler.unwritable !== null) return refuse(handler.unwritable.code, handler.unwritable.where, handler.unwritable.message);
+  if (handler.unwritable !== null) return refuse2(handler.unwritable.code, handler.unwritable.where, handler.unwritable.message);
   for (const note of handler.notes) problems.push(note);
   if (handler.refusals.length > 0) {
     for (const problem5 of handler.refusals) problems.push(problem5);
@@ -10522,7 +10583,7 @@ function compile(contract, { kit, extra = {} } = {}) {
   for (const page of pages) {
     files[page.path] = pageFile(page, { contract: composed, pages, kit, problems });
   }
-  return { files, problems: problems.sort(byProblem2) };
+  return { files, problems: problems.sort(byProblem2), warnings: narrativeOrderWarnings(composed, applied) };
 }
 var RUNTIME_RENDERER2 = "runtime";
 function dashboardHandler(composed, handlerName, extra = {}) {
@@ -10598,6 +10659,43 @@ function missingExpressions(widgets) {
   }
   return problems;
 }
+function narrativeOrderWarnings(composed, applied) {
+  const picked = new Set(applied.filter((fill) => fill.what === "layout.order").map((fill) => fill.where));
+  const elements = isPlainObject6(composed?.elements) ? composed.elements : {};
+  const widgets = isPlainObject6(composed?.data?.widgets) ? composed.data.widgets : {};
+  const pages = [...Array.isArray(composed?.pages) ? composed.pages : []].sort((a, b) => natural3(a.path ?? "", b.path ?? ""));
+  const named13 = (value) => typeof value === "string" && value !== "";
+  const quoted3 = (ids) => ids.map((id) => JSON.stringify(id)).join(", ");
+  const warnings = [];
+  for (const page of pages) {
+    if (picked.has(page.path)) continue;
+    const sections = Array.isArray(page.sections) ? page.sections : [];
+    const sectionOf4 = (uid) => sections.findIndex((entry) => isPlainObject6(entry) && entry.id === elements[uid].section);
+    const cards = Object.keys(elements).filter((uid) => elements[uid]?.page === page.path && elements[uid]?.type === "widget").sort((a, b) => sectionOf4(a) - sectionOf4(b) || order(elements[a]) - order(elements[b]) || natural3(a, b));
+    const specOf2 = (uid) => {
+      const element = elements[uid];
+      const props = isPlainObject6(element.props) ? element.props : {};
+      return named13(element.id) ? element.id : named13(props.card) ? props.card : named13(props.id) ? props.id : uid;
+    };
+    cards.forEach((uid, at) => {
+      const own2 = specOf2(uid);
+      const row = widgets[own2];
+      const about = isPlainObject6(row) && row.kind === "narrative" && Array.isArray(row.about) ? row.about.filter((id) => named13(id) && id !== own2) : [];
+      if (about.length === 0) return;
+      const after = cards.slice(at + 1).filter((other) => sectionOf4(other) === sectionOf4(uid) && about.includes(specOf2(other)));
+      if (after.length === 0) return;
+      const later = [...new Set(after.map(specOf2))];
+      const last = specOf2(after[after.length - 1]);
+      const where2 = sectionOf4(uid) === -1 ? page.path : `section "${sections[sectionOf4(uid)].id}" of ${page.path}`;
+      warnings.push({
+        code: "narrative_before_about",
+        pointer: `/elements/${escapePointer3(uid)}/order`,
+        message: `narrative "${own2}" comes before ${quoted3(later)}, ${later.length === 1 ? "a card" : "cards"} it is about, on ${where2}: it reads the cards it is about as it loads, so its context gives ${quoted3(later)} as "(not loaded yet)". The page keeps the order you stated; move "${own2}" after "${last}"`
+      });
+    });
+  }
+  return warnings;
+}
 var DEFAULT_CAPABILITIES = { financeos: ["metrics:read", "raw:read"] };
 function manifestFile(contract, handlerName) {
   const app = contract.app ?? {};
@@ -11008,7 +11106,7 @@ var DROPPED_REGIONS = /* @__PURE__ */ new Set(["controls", "band"]);
 var KEPT_CARD_PROPS = ["label", "format", "negative", "props"];
 function compileDashboard(contract, { kit = null, extra = {}, uiKit, charts, fmt, appComponents, appControls } = {}) {
   const problems = [];
-  const refuse = (code, pointer2, message) => problems.push({ code, pointer: pointer2, message });
+  const refuse2 = (code, pointer2, message) => problems.push({ code, pointer: pointer2, message });
   const note = (code, where2, message) => problems.push({ code, where: where2, lossy: false, message });
   const refused = (restated2 = contract) => ({ files: {}, problems, contract: restated2, warnings: [] });
   const source = isPlainObject7(contract) ? contract : {};
@@ -11016,19 +11114,19 @@ function compileDashboard(contract, { kit = null, extra = {}, uiKit, charts, fmt
   const markdown = named5(kit?.markdown) ? kit.markdown : MARKDOWN;
   const described = describeTier(source.data);
   if (described !== null) {
-    refuse("describe_tier_not_compilable", described.where, described.message);
+    refuse2("describe_tier_not_compilable", described.where, described.message);
     return refused();
   }
   const { contract: composed, applied } = composeLayout(source);
   for (const fill of applied) note("layout_composed", fill.where, `${fill.message} (${fill.what})`);
   const pages = [...Array.isArray(composed.pages) ? composed.pages : []].sort((a, b) => natural3(a.path ?? "", b.path ?? ""));
   if (pages.length === 0) {
-    refuse("no_pages", "/pages", "the contract declares no pages; a dashboard is one page of widgets or more");
+    refuse2("no_pages", "/pages", "the contract declares no pages; a dashboard is one page of widgets or more");
     return refused();
   }
   const handlers = [...new Set(pages.map((page) => page.mount?.handler).filter((name) => typeof name === "string" && name !== ""))];
   if (handlers.length !== 1) {
-    refuse(
+    refuse2(
       "one_handler_per_dashboard",
       "/pages",
       handlers.length === 0 ? "no page names a mount handler; every widget on a dashboard is answered by one handler" : `the pages name ${handlers.length} mount handlers (${handlers.join(", ")}); a dashboard has one, and a second source is a second ROW in its SPEC`
@@ -11038,15 +11136,15 @@ function compileDashboard(contract, { kit = null, extra = {}, uiKit, charts, fmt
   const handlerName = handlers[0];
   const handler = dashboardHandler(composed, handlerName, extra);
   if (handler.unwritable !== null) {
-    refuse(handler.unwritable.code, handler.unwritable.where, handler.unwritable.message);
+    refuse2(handler.unwritable.code, handler.unwritable.where, handler.unwritable.message);
     return refused();
   }
   problems.push(...handler.notes);
   if (handler.refusals.length > 0) {
-    for (const problem5 of handler.refusals) refuse(problem5.code, problem5.where, problem5.message);
+    for (const problem5 of handler.refusals) refuse2(problem5.code, problem5.where, problem5.message);
     return refused();
   }
-  const restated = restateDashboard(composed, pages, handlerName, handler, { refuse, note, stated: Array.isArray(source.pages) ? source.pages : [] });
+  const restated = restateDashboard(composed, pages, handlerName, handler, { refuse: refuse2, note, stated: Array.isArray(source.pages) ? source.pages : [] });
   const whole = canonical({
     ...composed.v !== void 0 ? { v: composed.v } : {},
     ...composed.generated_by !== void 0 ? { generated_by: composed.generated_by } : {},
@@ -11078,19 +11176,19 @@ function compileDashboard(contract, { kit = null, extra = {}, uiKit, charts, fmt
   files[handlerPath(composed, handlerName)] = handler.text;
   const shelf2 = { runtime: DASHBOARD_RUNTIME, widgets: DASHBOARD_WIDGETS, bar: DASHBOARD_BAR, assistant, markdown, uiKit, charts, fmt, appComponents, appControls };
   for (const page of whole.pages) files[page.path] = pageHtml(whole, page, elements, tree, shelf2);
-  return { files, problems, contract: whole, order: order2, warnings: [] };
+  return { files, problems, contract: whole, order: order2, warnings: narrativeOrderWarnings(composed, applied) };
 }
 function isRefusal(problem5) {
   return problem5.lossy !== false;
 }
-function restateDashboard(composed, pages, handlerName, handler, { refuse, note, stated: stated2 }) {
+function restateDashboard(composed, pages, handlerName, handler, { refuse: refuse2, note, stated: stated2 }) {
   const app = isPlainObject7(composed.app) ? composed.app : {};
   const typed = isPlainObject7(composed.elements) ? composed.elements : {};
   const declared = treeOf(typed);
   const conflicts = new Map(declared.problems.map((problem5) => [uidOfPointer(problem5.pointer), problem5]));
   const paths = new Set(pages.map((page) => page.path));
   const unplaced = Object.fromEntries(Object.keys(typed).filter((uid) => isPlainObject7(typed[uid]) && !paths.has(typed[uid].page)).map((uid) => [uid, typed[uid]]));
-  for (const problem5 of placementProblems(unplaced, pages, declared, [])) refuse(problem5.code, problem5.pointer, problem5.message);
+  for (const problem5 of placementProblems(unplaced, pages, declared, [])) refuse2(problem5.code, problem5.pointer, problem5.message);
   const elements = {};
   const outPages = [];
   for (const page of pages) {
@@ -11126,7 +11224,7 @@ function restateDashboard(composed, pages, handlerName, handler, { refuse, note,
     const onlyOne = (uids, what) => {
       for (const uid of uids.slice(1)) {
         duplicates.add(uid);
-        refuse(
+        refuse2(
           "chrome_duplicate",
           `/elements/${escapePointer3(uid)}`,
           `"${uid}" is a second ${what} on ${path3}, after "${uids[0]}"; a dashboard page has one of each piece of chrome \u2014 remove it, or merge it into "${uids[0]}"`
@@ -11200,12 +11298,12 @@ function restateDashboard(composed, pages, handlerName, handler, { refuse, note,
     const params = (Array.isArray(page.params) ? page.params : []).filter(isPlainObject7).map(canonical);
     const parts = [];
     for (const uid of own2.filter((uid2) => typed[uid2].type === "control")) {
-      const made = controlToPart(typed[uid], uid, path3, refuse);
+      const made = controlToPart(typed[uid], uid, path3, refuse2);
       if (made === null) continue;
       const param = canonical(made.param);
       const taken = params.find((one) => one?.name === param.name);
       if (taken !== void 0 && JSON.stringify(taken) !== JSON.stringify(param)) {
-        refuse(
+        refuse2(
           "control_conflict",
           `/elements/${escapePointer3(uid)}`,
           `control "${made.element.props.id}" declares page param ${JSON.stringify(param)}, and ${path3} already declares "${param.name}" as ${JSON.stringify(taken)}; one name is one declaration \u2014 make the two the same, or give the control its own param`
@@ -11222,14 +11320,14 @@ function restateDashboard(composed, pages, handlerName, handler, { refuse, note,
     const handled = /* @__PURE__ */ new Set([header, ...chrome, filters, ...nav === void 0 ? [] : [nav, ...elements[nav].children], ...parts, ...cards]);
     const kept = own2.filter((uid) => !handled.has(uid) && !dropped.has(uid) && !["region", "nav", "tab", "control", "widget"].includes(typed[uid].type));
     for (const uid of kept) {
-      if (conflicts.has(uid)) refuse(conflicts.get(uid).code, conflicts.get(uid).pointer, conflicts.get(uid).message);
+      if (conflicts.has(uid)) refuse2(conflicts.get(uid).code, conflicts.get(uid).pointer, conflicts.get(uid).message);
       elements[uid] = keptOf(typed[uid], uid, path3, typed, declared, dropped, kept, cards, sections);
     }
     for (const uid of cards) {
       const held = declared.parent.get(uid) ?? null;
       const parent = held !== null && kept.includes(held) ? held : null;
-      if (conflicts.has(uid) && (parent !== null || kept.includes(typed[uid].parent))) refuse(conflicts.get(uid).code, conflicts.get(uid).pointer, conflicts.get(uid).message);
-      elements[uid] = cardOf(typed[uid], uid, path3, handlerName, sections, refuse, parent);
+      if (conflicts.has(uid) && (parent !== null || kept.includes(typed[uid].parent))) refuse2(conflicts.get(uid).code, conflicts.get(uid).pointer, conflicts.get(uid).message);
+      elements[uid] = cardOf(typed[uid], uid, path3, handlerName, sections, refuse2, parent);
     }
     const otherRegions = own2.filter((uid) => typed[uid].type === "region" && !handled.has(uid) && !dropped.has(uid) && !duplicates.has(uid));
     for (const uid of otherRegions) elements[uid] = region(uid, typed[uid].role ?? "header", "section", []);
@@ -11242,7 +11340,7 @@ function restateDashboard(composed, pages, handlerName, handler, { refuse, note,
     const authored = stated2.findIndex((one) => isPlainObject7(one) && one.path === path3);
     const statedRoute = authored === -1 ? null : stated2[authored].route ?? null;
     if (statedRoute !== null && statedRoute !== route) {
-      refuse(
+      refuse2(
         "route_mismatch",
         `/pages/${authored}/route`,
         `${path3} states route ${JSON.stringify(statedRoute)}, and app.routes (${JSON.stringify(Array.isArray(app.routes) ? app.routes : [])}) ${route === null ? "serves it at no route" : `serves it at ${JSON.stringify(route)}`}; the manifest serves what app.routes lists \u2014 list the route there, or drop it from the page`
@@ -11258,11 +11356,11 @@ function restateDashboard(composed, pages, handlerName, handler, { refuse, note,
     data: dataOf(composed, handler)
   };
 }
-function cardOf(element, uid, path3, handlerName, sections, refuse, parent = null) {
+function cardOf(element, uid, path3, handlerName, sections, refuse2, parent = null) {
   const props = isPlainObject7(element.props) ? element.props : {};
   const spec = named5(element.id) ? element.id : named5(props.card) ? props.card : named5(props.id) ? props.id : null;
   if (spec === null) {
-    refuse(
+    refuse2(
       "card_unnamed",
       `/elements/${escapePointer3(uid)}`,
       `widget "${uid}" names no SPEC card; a dashboard card is bound to a row of its handler's SPEC by its id \u2014 the element's id, or props.card`
@@ -11297,12 +11395,12 @@ function cardOf(element, uid, path3, handlerName, sections, refuse, parent = nul
     ...section === void 0 ? {} : { section }
   };
 }
-function controlToPart(control, uid, path3, refuse) {
+function controlToPart(control, uid, path3, refuse2) {
   const props = isPlainObject7(control.props) ? control.props : {};
   const name = named5(props.param) ? props.param : named5(control.binding) ? control.binding : null;
   const id = named5(control.id) ? control.id : named5(props.id) ? props.id : name;
   if (name === null) {
-    refuse("control_unsupported", `/elements/${escapePointer3(uid)}`, `control "${id ?? uid}" names no param; a dashboard control parameterises its widgets by the param it writes (props.param)`);
+    refuse2("control_unsupported", `/elements/${escapePointer3(uid)}`, `control "${id ?? uid}" names no param; a dashboard control parameterises its widgets by the param it writes (props.param)`);
     return null;
   }
   const kind = named5(props.control_kind) ? props.control_kind : props.type === "range" ? "slider" : props.type === "number" ? "number" : props.type === "checkbox" ? "toggle" : null;
@@ -11337,7 +11435,7 @@ function controlToPart(control, uid, path3, refuse) {
       if (value === void 0 || value === null || value === "") continue;
       const n = typeof value === "number" ? value : Number(value);
       if (!Number.isFinite(n)) {
-        refuse("control_unsupported", `/elements/${escapePointer3(uid)}/props/${key}`, `control "${id}" states ${key} ${JSON.stringify(value)}, which is not a number; a ${kind} page param takes numbers`);
+        refuse2("control_unsupported", `/elements/${escapePointer3(uid)}/props/${key}`, `control "${id}" states ${key} ${JSON.stringify(value)}, which is not a number; a ${kind} page param takes numbers`);
         return null;
       }
       numbers[as] = n;
@@ -11349,7 +11447,7 @@ function controlToPart(control, uid, path3, refuse) {
   if (kind === "toggle") {
     return part("toggle", { name, kind: "toggle", ...label, default: props.checked !== void 0 && props.checked !== false && props.checked !== "false" });
   }
-  refuse(
+  refuse2(
     "control_unsupported",
     `/elements/${escapePointer3(uid)}`,
     `control "${id}" is ${kind === null ? "of no kind this compiler knows" : `a ${kind}`}; on a dashboard the app runtime renders a control is a part over a page param, and the parts here are a slider (a range), a number input and a toggle (a checkbox)`
@@ -11852,6 +11950,234 @@ function formulaProblems(text3, operands) {
   return problems.length > 0 ? { tree: null, problems } : { tree, problems: [] };
 }
 
+// ../flows/insights-builder/kit/contract/metricFormula.mjs
+var SHIFT_UNITS = Object.freeze(["year", "quarter", "month", "day", "consumption_period"]);
+var AS_OF_ANCHORS = Object.freeze(["year_end", "quarter_end", "month_end"]);
+var WINDOW_FUNCTIONS = Object.freeze(["avg", "min", "max"]);
+var WINDOW_UNITS = Object.freeze(["year", "quarter", "month"]);
+var MAX_WINDOW_PERIODS = 120;
+var SYSTEM_VARIABLES = Object.freeze(["DAYS_IN_PERIOD", "PERIODS_IN_YEAR"]);
+var MAX_FORMULA_LENGTH = 5e3;
+var MAX_SHIFT_OFFSET_MAGNITUDE = 1200;
+var METRIC_KEY_RE = /^[a-z][a-z0-9_]*$/;
+var OPERATOR_RE = /\s*([+\-*/])\s*/g;
+var SENTINEL = "\uE000";
+var STASH_RE = /(\d+)/g;
+var REF_WITH_MOD_RE = /\[([^[\]]+)\](\.(?:SHIFT|AS_OF)\([^)]*\))?/g;
+var WINDOW_RE = new RegExp(String.raw`\b(${WINDOW_FUNCTIONS.join("|")})\(\s*\[([^[\]]+)\]\s*,\s*(\w+)\s*,\s*([+-]?\d+)\s*\)`, "g");
+var SYSTEM_VARIABLE_RE = new RegExp(`\\b(?:${SYSTEM_VARIABLES.join("|")})\\b`, "g");
+var SHIFT_RE = /^\.SHIFT\(\s*(\w+)\s*,\s*([+-]?\d+)\s*\)$/;
+var AS_OF_RE = /^\.AS_OF\(\s*(\w+)\s*\)$/;
+var MetricFormulaError = class extends Error {
+};
+function refuse(sentence2) {
+  throw new MetricFormulaError(sentence2);
+}
+function modifierOnSystemVariable(token) {
+  return `cannot attach a time modifier to the reserved token "${token}" (resolved at runtime, not a metric); drop the modifier or move it to a [@key] operand`;
+}
+function timeModifierProblem(mod) {
+  const shift = SHIFT_RE.exec(mod);
+  if (shift) {
+    const unit = shift[1].toLowerCase();
+    const offset = Number(shift[2]);
+    if (!SHIFT_UNITS.includes(unit)) return `has an invalid SHIFT unit "${shift[1]}" (valid: ${SHIFT_UNITS.join(", ")})`;
+    if (offset > 0) return `has a future SHIFT offset ${shift[2]}; the offset must be negative or zero (e.g. SHIFT(${unit}, -1))`;
+    if (Math.abs(offset) > MAX_SHIFT_OFFSET_MAGNITUDE) {
+      return `has a SHIFT offset ${shift[2]} whose magnitude exceeds the server maximum of ${MAX_SHIFT_OFFSET_MAGNITUDE}; use a smaller offset`;
+    }
+    return null;
+  }
+  const asOf = AS_OF_RE.exec(mod);
+  if (asOf) {
+    if (!AS_OF_ANCHORS.includes(asOf[1].toLowerCase())) return `has an invalid AS_OF anchor "${asOf[1]}" (valid: ${AS_OF_ANCHORS.join(", ")})`;
+    return null;
+  }
+  return `has a malformed time modifier "${mod}" (expected .SHIFT(<unit>, <offset>) or .AS_OF(<anchor>))`;
+}
+function checkModifier(mod) {
+  const problem5 = timeModifierProblem(mod);
+  if (problem5 !== null) refuse(problem5);
+}
+function namedItself(spelled) {
+  return `names the metric ${spelled} itself; an operand is [@key], a key data.metrics declares, so the contract names no company's metric \u2014 declare it there (with "reuse": "name" and "create": false to bind the company's own) and write [@<its key>]`;
+}
+function declaredKey(inner, declared) {
+  if (!inner.startsWith("@")) refuse(namedItself(`[${inner}]`));
+  const key = inner.slice(1);
+  if (!METRIC_KEY_RE.test(key)) refuse(`writes [${inner}], and ${JSON.stringify(key)} is not a key: a key is a lowercase letter, then lowercase letters, digits or _`);
+  if (!declared.includes(key)) {
+    refuse(`reads [@${key}], which data.metrics does not declare (it declares ${declared.length > 0 ? declared.map((one) => `[@${one}]`).join(", ") : "none"})`);
+  }
+  return key;
+}
+function spelledEntry(entry) {
+  if (entry.kind === "token") return entry.token;
+  if (entry.kind === "window") return `${entry.fn}([@${entry.key}], ${entry.unit}, ${entry.periods})`;
+  return `[@${entry.key}]${entry.mod}`;
+}
+function arithmeticProblem(skeleton, stash) {
+  const tokens = [];
+  for (let at = 0; at < skeleton.length; ) {
+    const c = skeleton[at];
+    if (/\s/.test(c)) {
+      at += 1;
+    } else if (c === SENTINEL) {
+      const close = skeleton.indexOf(SENTINEL, at + 1);
+      tokens.push({ kind: "value", text: spelledEntry(stash[Number(skeleton.slice(at + 1, close))]) });
+      at = close + 1;
+    } else if ("+-*/()".includes(c)) {
+      tokens.push({ kind: c === "(" || c === ")" ? c : "op", text: c });
+      at += 1;
+    } else {
+      const start = at;
+      while (at < skeleton.length && /[0-9.]/.test(skeleton[at])) at += 1;
+      const spelled = skeleton.slice(start, at);
+      if (!/^(?:\d+\.?\d*|\.\d+)$/.test(spelled)) return `"${spelled || c}" is not a number`;
+      tokens.push({ kind: "value", text: spelled });
+    }
+  }
+  let expecting = "operand";
+  let depth = 0;
+  for (let at = 0; at <= tokens.length; at += 1) {
+    const found = tokens[at];
+    const before = tokens[at - 1];
+    if (expecting === "operand") {
+      if (found?.kind === "value") expecting = "operator";
+      else if (found?.kind === "(") depth += 1;
+      else if (found?.kind === "op" && found.text === "-") continue;
+      else if (found?.kind === "op") return before?.kind === "op" ? `two operators in a row ("${before.text} ${found.text}")` : `an operand is missing before "${found.text}"`;
+      else if (before?.kind === "(") return 'it has empty parentheses "()"';
+      else if (before !== void 0) return `an operand is missing after "${before.text}"`;
+      else return "it has no operand";
+    } else if (found === void 0) {
+      return depth > 0 ? 'a "(" is never closed' : null;
+    } else if (found.kind === "op") {
+      expecting = "operand";
+    } else if (found.kind === ")") {
+      if (depth === 0) return 'a ")" has no "(" before it';
+      depth -= 1;
+    } else {
+      return `no operator stands between "${before.text}" and "${found.text}"`;
+    }
+  }
+  return null;
+}
+function scan(formula, declared) {
+  if (typeof formula !== "string") refuse(`is ${JSON.stringify(formula ?? null)}, not text`);
+  if (formula.trim() === "") refuse("must be non-empty");
+  if (formula.length > MAX_FORMULA_LENGTH) {
+    refuse(`is ${formula.length} characters, over the server maximum of ${MAX_FORMULA_LENGTH}; shorten the formula`);
+  }
+  if (formula.includes(SENTINEL)) refuse("contains an unsupported character (U+E000)");
+  if (formula.includes("|")) refuse("pins a scenario (|); a scenario pin is not accepted in a declared metric's formula \u2014 read the scenario on the source instead (from.financeos.scenario)");
+  if (formula.includes("'")) {
+    const quoted3 = /'[^']*'/.exec(formula);
+    if (quoted3) refuse(namedItself(quoted3[0]));
+    refuse("holds an apostrophe ('), which Datarails reads as the edge of a quoted metric name; an operand is [@key], and a metric name has no apostrophe");
+  }
+  const stash = [];
+  const put = (entry) => {
+    stash.push(entry);
+    return `${SENTINEL}${stash.length - 1}${SENTINEL}`;
+  };
+  let working = formula.replace(WINDOW_RE, (_m, fn, inner, unit, periods) => {
+    if (SYSTEM_VARIABLES.includes(inner)) refuse(`has a window over the reserved token "${inner}"; a window function reads a [@key] operand`);
+    const key = declaredKey(inner, declared);
+    if (!WINDOW_UNITS.includes(unit.toLowerCase())) refuse(`has an invalid window unit "${unit}" in ${fn}() (valid: ${WINDOW_UNITS.join(", ")})`);
+    const count = Number(periods);
+    if (!Number.isInteger(count) || count < 1 || count > MAX_WINDOW_PERIODS) {
+      refuse(`has a window of ${periods} periods in ${fn}(); a window spans 1 to ${MAX_WINDOW_PERIODS} periods`);
+    }
+    return put({ kind: "window", fn, key, unit: unit.toLowerCase(), periods: String(count) });
+  });
+  working = working.replace(REF_WITH_MOD_RE, (_m, inner, mod) => {
+    if (SYSTEM_VARIABLES.includes(inner)) {
+      if (mod) refuse(modifierOnSystemVariable(inner));
+      return put({ kind: "token", token: inner });
+    }
+    const key = declaredKey(inner, declared);
+    if (mod) checkModifier(mod);
+    return put({ kind: "ref", key, mod: mod ?? "" });
+  });
+  working = working.replace(SYSTEM_VARIABLE_RE, (token, offset, whole) => {
+    if (/^\s*\.(?:SHIFT|AS_OF)\(/i.test(whole.slice(offset + token.length))) refuse(modifierOnSystemVariable(token));
+    return put({ kind: "token", token });
+  });
+  if (working.includes("[") || working.includes("]")) refuse("has unbalanced bracket(s); each operand must be wrapped as [@key]");
+  const unclosed = /\.(?:SHIFT|AS_OF)\([^)]*$/i.exec(working);
+  if (unclosed) checkModifier(unclosed[0]);
+  if (/\.(?:SHIFT|AS_OF)\(/i.test(working)) {
+    refuse("time modifiers must use uppercase .SHIFT/.AS_OF, must be attached to a [@key] operand (e.g. [@revenue].SHIFT(year, -1)), and cannot be chained on the same operand");
+  }
+  const window = new RegExp(String.raw`\b(${WINDOW_FUNCTIONS.join("|")})\s*\(`, "i").exec(working);
+  if (window) {
+    refuse(
+      `has a window function it cannot read (${window[1]}(...)); write it as ${window[1].toLowerCase()}([@key], unit, periods) \u2014 ${WINDOW_FUNCTIONS.join(", ")}, in lowercase, over one [@key] with no modifier \u2014 with unit ${WINDOW_UNITS.join(", ")} and periods from 1 to ${MAX_WINDOW_PERIODS}`
+    );
+  }
+  let depth = 0;
+  for (const ch of working) {
+    if (ch === "(") depth += 1;
+    else if (ch === ")" && --depth < 0) break;
+  }
+  if (depth !== 0) refuse('grouping is not balanced; every "(" must have a matching ")"');
+  const padded = working.replace(OPERATOR_RE, " $1 ").trim();
+  const residue = padded.replace(STASH_RE, "").replace(/[\s+\-*/()0-9.]/g, "");
+  if (residue.includes("@")) refuse(`writes @ outside brackets (offending characters: "${residue}"); an operand is [@key]`);
+  if (residue.length > 0) {
+    refuse(`has unbracketed identifier(s) (offending characters: "${residue}"); an operand is [@key], or ${SYSTEM_VARIABLES.join(" or ")} written bare`);
+  }
+  const malformed = arithmeticProblem(padded, stash);
+  if (malformed !== null) refuse(`is not a formula Datarails can evaluate: ${malformed}`);
+  if (!stash.some((entry) => entry.kind !== "token")) refuse("must read at least one declared metric, e.g. [@revenue]");
+  return { padded, stash };
+}
+function metricFormulaProblems(formula, declared) {
+  try {
+    const { stash } = scan(formula, Array.isArray(declared) ? declared.filter((one) => typeof one === "string") : []);
+    const operands = [...new Set(stash.filter((entry) => entry.kind !== "token").map((entry) => entry.key))].sort();
+    const windows = stash.filter((entry) => entry.kind === "window").map((entry) => `${entry.fn}([@${entry.key}], ${entry.unit}, ${entry.periods})`);
+    return { problems: [], operands, windows };
+  } catch (error) {
+    if (!(error instanceof MetricFormulaError)) throw error;
+    return { problems: [error.message], operands: [], windows: [] };
+  }
+}
+
+// ../flows/insights-builder/kit/contract/metricFormats.mjs
+var CURRENCY_PREFIXES = ['"$"', "\u20AC", "\xA3", "\u20AA"];
+var DIGITS = ["#,###", "####"];
+var DECIMALS = ["", ".#", ".##", ".###", ".####"];
+var SCALES = ["", "[kilo]k", "[mega]M"];
+var METRIC_FORMATS = Object.freeze(
+  (() => {
+    const signs = [{ prefix: "", suffix: "" }, ...CURRENCY_PREFIXES.map((prefix) => ({ prefix, suffix: "" })), { prefix: "", suffix: "%" }];
+    const all = [];
+    for (const { prefix, suffix } of signs) {
+      for (const digits of DIGITS) {
+        for (const decimals of DECIMALS) {
+          for (const scale of SCALES) all.push(`${prefix}${digits}${decimals}${scale}${suffix}`);
+        }
+      }
+    }
+    return all;
+  })()
+);
+var KNOWN = new Set(METRIC_FORMATS);
+function isMetricFormat(format) {
+  return typeof format === "string" && KNOWN.has(format);
+}
+function metricFormatProblem(format) {
+  if (isMetricFormat(format)) return null;
+  if (typeof format !== "string") return `is ${JSON.stringify(format ?? null)}; a format is one of the strings the metric editor writes, such as "#,###", "\\"$\\"#,###.##" or "####.#%"`;
+  const trimmed = format.trim();
+  const quoted3 = trimmed.startsWith("$") ? `"$"${trimmed.slice(1)}` : trimmed;
+  const hashed = quoted3.replace(/0/g, "#");
+  const meant = [quoted3, hashed].find((one) => one !== format && KNOWN.has(one));
+  return `is ${JSON.stringify(format)}, which the metric editor never writes${meant ? ` (did you mean ${JSON.stringify(meant)}?)` : ""}; build it from these parts, in this order: an optional currency prefix ("$" quoted, or \u20AC \xA3 \u20AA, never with %), #,### or ####, optional decimals .# to .####, an optional scale [kilo]k or [mega]M, and an optional % suffix`;
+}
+
 // ../flows/insights-builder/kit/contract/compileApp.mjs
 var RUNTIME = "dr-app-runtime@1.11.0";
 var UI_KIT2 = "ui-kit/v4";
@@ -12141,6 +12467,9 @@ function originOf(row) {
 function sourcesOf(contract) {
   return isPlainObject8(contract?.data?.sources) ? contract.data.sources : {};
 }
+function readsMetric(read) {
+  return isPlainObject8(read) && (read.metric_id !== void 0 && read.metric_id !== null || read.metric !== void 0 && read.metric !== null);
+}
 var FINANCEOS_SCOPES = {
   commands: {
     "status:read": ["status", "whoami"],
@@ -12185,7 +12514,7 @@ function financeosNeeds(row, origin) {
   }
   const read = isPlainObject8(row.from.financeos) ? row.from.financeos : {};
   const filterable = Array.isArray(row.filterable) && row.filterable.length > 0;
-  if (read.metric_id !== void 0 && read.metric_id !== null) {
+  if (readsMetric(read)) {
     if (read.drill_rows) need("data_models", scopesGranting("namespaces", "data_models"));
     else need("metric_series", scopesGranting("commands", "metric_series"));
     if (filterable) need("data_models", scopesGranting("namespaces", "data_models"), true);
@@ -12234,7 +12563,7 @@ function opensRows(row) {
   if (row.transform !== void 0 && row.transform !== null) return false;
   if (!MENU_SHAPES.includes(row.shape ?? "rows")) return false;
   const read = isPlainObject8(row.from.financeos) ? row.from.financeos : {};
-  if (read.metric_id !== void 0 && read.metric_id !== null) return false;
+  if (readsMetric(read)) return false;
   return Boolean(read.table_alias) || read.table_id !== void 0 && read.table_id !== null || read.address === "id" || read.address === "alias";
 }
 function fillMenuScope(app, sources, elements) {
@@ -12447,6 +12776,272 @@ function reaches2(sources, start, target, seen, isFormula) {
   if (!isFormula(row) || !Array.isArray(row.from)) return false;
   return row.from.filter(named5).some((one) => reaches2(sources, one, target, seen, isFormula));
 }
+var METRIC_DECL_KEYS = ["name", "kind", "formula", "table", "value", "date", "aggregate", "time_aggregation", "filters", "format", "description", "reuse", "create"];
+var METRIC_KINDS = ["base", "calc"];
+var METRIC_CALC_KEYS = ["formula"];
+var METRIC_BASE_KEYS = ["table", "value", "date", "aggregate", "time_aggregation", "filters"];
+var METRIC_AGGREGATES = ["sum", "count", "cumulative_sum", "cumulative_count"];
+var METRIC_TIME_AGGREGATIONS = ["sum", "eop", "avg"];
+var METRIC_REUSE = ["definition", "name"];
+var METRIC_TABLE_KEYS = ["alias", "name", "id"];
+var METRIC_FILTER_KEYS = ["field", "values", "exclude"];
+var METRIC_NAME_MAX = 128;
+function metricNameProblem(name) {
+  if (typeof name !== "string" || name.trim() === "") {
+    return `is ${JSON.stringify(name ?? null)}; every declaration names its metric in Datarails, as a finance team would ("Revenue MoM growth")`;
+  }
+  if (name.length > METRIC_NAME_MAX) return `is ${name.length} characters; Datarails takes at most ${METRIC_NAME_MAX}`;
+  if (/['[\]]/.test(name)) return `${JSON.stringify(name)} holds ' [ or ], which a CALC formula reads as the edges of a metric reference`;
+  if (name.startsWith("@")) return `${JSON.stringify(name)} starts with @, which marks a key of this contract, not a name in Datarails`;
+  if (SYSTEM_VARIABLES.includes(name)) return `is ${name}, which Datarails reserves for its own system variable`;
+  return null;
+}
+function metricTableProblem(table) {
+  if (!isPlainObject8(table)) return true;
+  const stated2 = Object.keys(table);
+  if (stated2.length !== 1 || !METRIC_TABLE_KEYS.includes(stated2[0])) return true;
+  const value = table[stated2[0]];
+  return stated2[0] === "id" ? !(Number.isInteger(value) && value >= 1) : typeof value !== "string" || value.trim() === "";
+}
+function metricFilterProblem(filter) {
+  if (!isPlainObject8(filter)) return `is ${JSON.stringify(filter ?? null)}`;
+  const extra = Object.keys(filter).filter((key) => !METRIC_FILTER_KEYS.includes(key)).sort(natural3);
+  if (extra.length > 0) return `states ${extra.join(", ")}, which a filter does not take`;
+  if (typeof filter.field !== "string" || filter.field.trim() === "") return `names field ${JSON.stringify(filter.field ?? null)}, which is no field's alias or name`;
+  if (!Array.isArray(filter.values) || filter.values.length === 0 || !filter.values.every((one) => typeof one === "string" || typeof one === "number" && Number.isFinite(one))) {
+    return `states values ${JSON.stringify(filter.values ?? null)}; values is a non-empty list of the field's values, each a string or a number`;
+  }
+  if (filter.exclude !== void 0 && typeof filter.exclude !== "boolean") return `states exclude ${JSON.stringify(filter.exclude)}; exclude is true or false`;
+  return null;
+}
+function metricReaches(operandsOf, start, target, seen) {
+  if (start === target) return true;
+  if (seen.has(start)) return false;
+  seen.add(start);
+  return (operandsOf.get(start) ?? []).some((one) => metricReaches(operandsOf, one, target, seen));
+}
+function calcShaped(node) {
+  if (node[0] === "num" || node[0] === "name") return true;
+  if (node[0] === "neg") return calcShaped(node[1]);
+  if (node[0] === "bin") return calcShaped(node[2]) && calcShaped(node[3]);
+  return false;
+}
+function metricProblems(metrics, sources) {
+  const problems = [];
+  const at = (key, field) => `/data/metrics/${escapePointer3(key)}${field ? `/${field}` : ""}`;
+  const say = (code, pointer2, message) => problems.push({ code, pointer: pointer2, message });
+  const advise = (code, pointer2, message) => problems.push({ code, pointer: pointer2, message, advisory: true });
+  if (metrics !== void 0 && metrics !== null && !isPlainObject8(metrics)) {
+    say("metric_decl", "/data/metrics", `data.metrics is ${JSON.stringify(metrics)}; it is an object of declarations keyed by a local name ({"revenue": {"name": "Revenue", "kind": "base", ...}})`);
+  }
+  const declared = isPlainObject8(metrics) ? metrics : {};
+  const keys2 = Object.keys(declared).sort(natural3);
+  const declaredKeys = keys2.filter((key) => METRIC_KEY_RE.test(key));
+  const formulas = /* @__PURE__ */ new Map();
+  for (const key of keys2) {
+    const decl = declared[key];
+    if (!METRIC_KEY_RE.test(key)) {
+      say("metric_decl", at(key), `data.metrics declares ${JSON.stringify(key)}, which is not a key: a key is a lowercase letter, then lowercase letters, digits or _ (revenue_mom), the handle a source reads as "@<key>" and a formula as [@<key>]`);
+      continue;
+    }
+    if (!isPlainObject8(decl)) {
+      say("metric_decl", at(key), `metric "${key}" is ${JSON.stringify(decl ?? null)}; a declaration is an object: {"name": "<its name in Datarails>", "kind": "base" | "calc", ...}`);
+      continue;
+    }
+    for (const field of Object.keys(decl).sort(natural3)) {
+      if (!METRIC_DECL_KEYS.includes(field)) say("metric_decl", at(key, field), `metric "${key}" states ${field}, which a declaration does not take; it takes ${either3(METRIC_DECL_KEYS)}`);
+    }
+    const nameProblem = metricNameProblem(decl.name);
+    if (nameProblem !== null) say("metric_decl", at(key, "name"), `metric "${key}"'s name ${nameProblem}`);
+    if (decl.reuse !== void 0 && !METRIC_REUSE.includes(decl.reuse)) {
+      say(
+        "metric_decl",
+        at(key, "reuse"),
+        `metric "${key}" states reuse ${JSON.stringify(decl.reuse)}; reuse is "definition" (the default: bind only a company metric with this definition) or "name" (bind the company's metric of this name, whatever its definition)`
+      );
+    }
+    if (decl.create !== void 0 && typeof decl.create !== "boolean") {
+      say("metric_decl", at(key, "create"), `metric "${key}" states create ${JSON.stringify(decl.create)}; create is true (the default: create the metric where the company has none to bind) or false (bind only)`);
+    }
+    if (decl.description !== void 0 && typeof decl.description !== "string") {
+      say("metric_decl", at(key, "description"), `metric "${key}" states description ${JSON.stringify(decl.description)}; a description is text for the metric's page in Datarails`);
+    }
+    if (decl.format !== void 0) {
+      const formatProblem = metricFormatProblem(decl.format);
+      if (formatProblem !== null) say("metric_format", at(key, "format"), `metric "${key}"'s format ${formatProblem}`);
+    }
+    const kind = decl.kind;
+    if (kind === void 0) {
+      const defining = [...METRIC_CALC_KEYS, ...METRIC_BASE_KEYS].filter((field) => decl[field] !== void 0);
+      if (defining.length > 0) {
+        say("metric_decl", at(key, "kind"), `metric "${key}" states ${defining.join(", ")} and no kind; state "kind": "base" (a table's field, aggregated) or "calc" (a formula over declared metrics)`);
+      } else if (decl.create !== false) {
+        say(
+          "metric_decl",
+          at(key),
+          `metric "${key}" has no definition (no kind), so nothing could create it; bind the company's own metric by name with "reuse": "name" and "create": false, or give it a definition`
+        );
+      } else if (decl.reuse !== "name") {
+        say(
+          "metric_decl",
+          at(key, "reuse"),
+          `metric "${key}" has no definition, so no company metric can match it by definition (reuse "definition", the default); bind the company's own metric by name with "reuse": "name"`
+        );
+      }
+      continue;
+    }
+    if (kind === "driver") {
+      say(
+        "metric_kind_later",
+        at(key, "kind"),
+        `metric "${key}" is kind "driver", which is reserved: driver declarations are not compiled yet. Declare a base or calc metric, or create the driver in Datarails and bind it with {"name": "<its name>", "reuse": "name", "create": false}`
+      );
+      continue;
+    }
+    if (!METRIC_KINDS.includes(kind)) {
+      say("metric_decl", at(key, "kind"), `metric "${key}" is kind ${JSON.stringify(kind)}; a declared metric is "base" (a table's field, aggregated) or "calc" (a formula over declared metrics)`);
+      continue;
+    }
+    for (const field of kind === "calc" ? METRIC_BASE_KEYS : METRIC_CALC_KEYS) {
+      if (decl[field] !== void 0) say("metric_decl", at(key, field), `metric "${key}" is a ${kind} metric and states ${field}, which only a ${kind === "calc" ? "base" : "calc"} metric takes`);
+    }
+    if (kind === "calc") {
+      if (decl.formula === void 0) {
+        say("metric_decl", at(key, "formula"), `metric "${key}" is a calc metric with no formula; state one over declared metrics, each written [@<key>] (([@revenue] - [@cogs]) / [@revenue])`);
+      } else {
+        formulas.set(key, decl.formula);
+      }
+      continue;
+    }
+    if (decl.table === void 0) {
+      say("metric_decl", at(key, "table"), `metric "${key}" is a base metric with no table; state {"alias": "<table alias>"} or {"name": "<table name>"}`);
+    } else if (metricTableProblem(decl.table)) {
+      say(
+        "metric_decl",
+        at(key, "table"),
+        `metric "${key}" states table ${JSON.stringify(decl.table)}; a table is exactly one of {"alias": "<table alias>"}, {"name": "<table name>"} or {"id": <id>} (which ties the app to one company)`
+      );
+    }
+    for (const [field, what] of [["value", "the field it aggregates"], ["date", "the field its periods come from"]]) {
+      if (decl[field] === void 0) say("metric_decl", at(key, field), `metric "${key}" is a base metric with no ${field}; state ${what}, by alias or name`);
+      else if (typeof decl[field] !== "string" || decl[field].trim() === "") say("metric_decl", at(key, field), `metric "${key}" states ${field} ${JSON.stringify(decl[field])}; ${field} is ${what}, by alias or name`);
+    }
+    if (decl.aggregate === void 0) {
+      say("metric_decl", at(key, "aggregate"), `metric "${key}" is a base metric with no aggregate; state ${either3(METRIC_AGGREGATES)}`);
+    } else if (!METRIC_AGGREGATES.includes(decl.aggregate)) {
+      say("metric_base", at(key, "aggregate"), `metric "${key}" aggregates ${JSON.stringify(decl.aggregate)}; a metric aggregates ${either3(METRIC_AGGREGATES)} (avg, min and max are not metric aggregates)`);
+    }
+    if (decl.time_aggregation !== void 0 && !METRIC_TIME_AGGREGATIONS.includes(decl.time_aggregation)) {
+      say("metric_base", at(key, "time_aggregation"), `metric "${key}" rolls up with ${JSON.stringify(decl.time_aggregation)}; time_aggregation is ${either3(METRIC_TIME_AGGREGATIONS)}`);
+    } else if (decl.time_aggregation === "sum" && (decl.aggregate === "cumulative_sum" || decl.aggregate === "cumulative_count")) {
+      say("metric_base", at(key, "time_aggregation"), `metric "${key}" aggregates ${decl.aggregate} and rolls up with sum, which Datarails refuses for a cumulative aggregate; use eop (the default) or avg`);
+    }
+    if (decl.filters !== void 0) {
+      if (!Array.isArray(decl.filters)) {
+        say("metric_base", at(key, "filters"), `metric "${key}" states filters ${JSON.stringify(decl.filters)}; filters is a list of {"field": "<alias or name>", "values": [...], "exclude": false}`);
+      } else {
+        decl.filters.forEach((filter, index) => {
+          const filterProblem = metricFilterProblem(filter);
+          if (filterProblem !== null) say("metric_base", at(key, `filters/${index}`), `metric "${key}"'s filter ${index} ${filterProblem}; a filter is {"field": "<alias or name>", "values": [...], "exclude": false}`);
+        });
+      }
+    }
+  }
+  const operandsOf = /* @__PURE__ */ new Map();
+  for (const key of [...formulas.keys()].sort(natural3)) {
+    const { problems: wrong, operands, windows } = metricFormulaProblems(formulas.get(key), declaredKeys);
+    for (const one of wrong) say("metric_formula", at(key, "formula"), `metric "${key}"'s formula ${one}`);
+    if (wrong.length > 0) continue;
+    operandsOf.set(key, operands);
+    if (windows.length > 0) {
+      advise(
+        "metric_window",
+        at(key, "formula"),
+        `metric "${key}"'s formula calls ${windows.join(" and ")}, a window function, which Datarails evaluates only where the company has scenario_bound_calculations on, and refuses to create elsewhere`
+      );
+    }
+  }
+  for (const key of [...operandsOf.keys()].sort(natural3)) {
+    for (const dep of operandsOf.get(key)) {
+      if (metricReaches(operandsOf, dep, key, /* @__PURE__ */ new Set())) {
+        say("metric_formula", at(key, "formula"), `metric "${key}"'s formula reads itself${dep === key ? "" : `, through [@${dep}]`}; a calc metric's operands are metrics that exist before it, so none may read it back`);
+        break;
+      }
+    }
+  }
+  const read = /* @__PURE__ */ new Set();
+  for (const name of Object.keys(sources ?? {}).sort(natural3)) {
+    const row = sources[name];
+    if (!isPlainObject8(row) || originOf(row) !== "financeos" || !isPlainObject8(row.from.financeos)) continue;
+    const metric = row.from.financeos.metric;
+    if (metric === void 0 || metric === null) continue;
+    const pointer2 = `/data/sources/${escapePointer3(name)}/from/financeos/metric`;
+    const metricId = row.from.financeos.metric_id;
+    if (metricId !== void 0 && metricId !== null) {
+      say(
+        "source_metric",
+        pointer2,
+        `source "${name}" states metric ${JSON.stringify(metric)} and metric_id ${JSON.stringify(metricId)}; a source reads one metric \u2014 keep metric (a key data.metrics declares, bound in each company at ship) and drop metric_id, which ties the app to one company`
+      );
+      continue;
+    }
+    if (typeof metric !== "string" || !metric.startsWith("@")) {
+      const meant = typeof metric === "string" && Object.prototype.hasOwnProperty.call(declared, metric) ? ` \u2014 write "@${metric}"` : "";
+      say("source_metric", pointer2, `source "${name}" reads metric ${JSON.stringify(metric)}; a metric is named "@<key>", a key data.metrics declares ("@revenue_mom")${meant}`);
+      continue;
+    }
+    const key = metric.slice(1);
+    if (!declaredKeys.includes(key)) {
+      say(
+        "source_metric",
+        pointer2,
+        `source "${name}" reads metric "@${key}", which data.metrics does not declare (it declares ${declaredKeys.length > 0 ? declaredKeys.map((one) => `"@${one}"`).join(", ") : "none"}); declare it there, or read one it declares`
+      );
+      continue;
+    }
+    read.add(key);
+  }
+  if (!problems.some((one) => one.code === "metric_formula")) {
+    const used = /* @__PURE__ */ new Set();
+    const visit = (key) => {
+      if (used.has(key)) return;
+      used.add(key);
+      for (const one of operandsOf.get(key) ?? []) visit(one);
+    };
+    for (const key of read) visit(key);
+    for (const key of declaredKeys) {
+      if (used.has(key)) continue;
+      advise(
+        "metric_unused",
+        at(key),
+        `metric "${key}" is declared and no source reads it, directly or through another declared metric's formula; \`app-space ship\` would still bind or create it in every company the app ships to \u2014 read it from a source (from.financeos.metric "@${key}"), or drop it`
+      );
+    }
+  }
+  for (const name of Object.keys(sources ?? {}).sort(natural3)) {
+    const row = sources[name];
+    if (!isPlainObject8(row) || typeof row.expr !== "string" || !Array.isArray(row.from)) continue;
+    const operands = [...new Set(row.from.filter(named5))];
+    if (operands.length === 0) continue;
+    const reads = operands.map((dep) => Object.hasOwn(sources, dep) ? sources[dep] : void 0);
+    const metricRead = (one) => isPlainObject8(one) && originOf(one) === "financeos" && (one.transform === void 0 || one.transform === null) && readsMetric(one.from.financeos);
+    if (!reads.every(metricRead)) continue;
+    if (new Set(reads.map((one) => JSON.stringify(one.from.financeos.scenario ?? null))).size !== 1) continue;
+    let tree;
+    try {
+      tree = parseFormula(row.expr);
+    } catch {
+      continue;
+    }
+    if (!calcShaped(tree)) continue;
+    advise(
+      "expr_could_be_metric",
+      `/data/sources/${escapePointer3(name)}/expr`,
+      `source "${name}"'s formula is arithmetic over Datarails metrics only (${operands.join(", ")}), in one scenario; declare it in data.metrics as a calc metric (its operands declared there too, each [@<key>]) and read it with from.financeos.metric, so it lives in Datarails, where MCP and DR.METRIC read the same number`
+    );
+  }
+  return problems;
+}
 var SOURCE_ORDERS = ["source", "declared"];
 function orderProblems(name, row, at) {
   const problems = [];
@@ -12625,22 +13220,22 @@ function themeProblems(app) {
   const theme = app?.theme;
   if (theme === void 0 || theme === null) return [];
   const at = (key) => `/app/theme${key ? `/${key}` : ""}`;
-  const refuse = (key, message) => ({ code: "theme_shape", pointer: at(key), message });
-  if (!isPlainObject8(theme)) return [refuse("", `app.theme is ${JSON.stringify(theme)}; it is {"file": "ui/theme.css", "tokens": {"--dr-\u2026": "\u2026"}}, or null for none`)];
+  const refuse2 = (key, message) => ({ code: "theme_shape", pointer: at(key), message });
+  if (!isPlainObject8(theme)) return [refuse2("", `app.theme is ${JSON.stringify(theme)}; it is {"file": "ui/theme.css", "tokens": {"--dr-\u2026": "\u2026"}}, or null for none`)];
   const out = [];
-  if (theme.file !== THEME_FILE4) out.push(refuse("file", `app.theme.file is ${JSON.stringify(theme.file ?? null)}; an app's theme is written to ${THEME_FILE4}, the one file its pages link after runtime.css`));
-  if (!isPlainObject8(theme.tokens)) out.push(refuse("tokens", `app.theme.tokens is ${JSON.stringify(theme.tokens ?? null)}; it is an object of --dr-* tokens to the values the app overrides them with ({} for none)`));
+  if (theme.file !== THEME_FILE4) out.push(refuse2("file", `app.theme.file is ${JSON.stringify(theme.file ?? null)}; an app's theme is written to ${THEME_FILE4}, the one file its pages link after runtime.css`));
+  if (!isPlainObject8(theme.tokens)) out.push(refuse2("tokens", `app.theme.tokens is ${JSON.stringify(theme.tokens ?? null)}; it is an object of --dr-* tokens to the values the app overrides them with ({} for none)`));
   else {
     for (const token of Object.keys(theme.tokens).sort(natural3)) {
       const value = theme.tokens[token];
       const pointer2 = `tokens/${escapePointer3(token)}`;
-      if (token === "--dr-app-theme") out.push(refuse(pointer2, "app.theme.tokens states --dr-app-theme, which is the compiler's own mark on the file it writes; drop it"));
-      else if (!TOKEN_RE.test(token)) out.push(refuse(pointer2, `app.theme.tokens states ${JSON.stringify(token)}; an app theme overrides --dr-* tokens only (the shadcn triples are computed from them)`));
+      if (token === "--dr-app-theme") out.push(refuse2(pointer2, "app.theme.tokens states --dr-app-theme, which is the compiler's own mark on the file it writes; drop it"));
+      else if (!TOKEN_RE.test(token)) out.push(refuse2(pointer2, `app.theme.tokens states ${JSON.stringify(token)}; an app theme overrides --dr-* tokens only (the shadcn triples are computed from them)`));
       else {
         const why = tokenValueProblem(value);
         if (why !== null) {
           out.push(
-            refuse(
+            refuse2(
               pointer2,
               `app.theme.tokens["${token}"] is ${JSON.stringify(value)}, which ${why}; a token holds one CSS value, with no ; { } /* */ \\ < or url(, its quotes and brackets balanced`
             )
@@ -12650,9 +13245,9 @@ function themeProblems(app) {
     }
   }
   if (theme.preset !== void 0 && !THEME_PRESETS.includes(theme.preset)) {
-    out.push(refuse("preset", `app.theme.preset is ${JSON.stringify(theme.preset)}; the ui-kit this compiler pins (${UI_KIT2}) carries ${either3(THEME_PRESETS)}${theme.preset === "presentation" ? " \u2014 presentation was planned for ui-kit v4, which shipped without it" : ""}`));
+    out.push(refuse2("preset", `app.theme.preset is ${JSON.stringify(theme.preset)}; the ui-kit this compiler pins (${UI_KIT2}) carries ${either3(THEME_PRESETS)}${theme.preset === "presentation" ? " \u2014 presentation was planned for ui-kit v4, which shipped without it" : ""}`));
   }
-  if (theme.density !== void 0 && !THEME_DENSITIES.includes(theme.density)) out.push(refuse("density", `app.theme.density is ${JSON.stringify(theme.density)}; it is ${either3(THEME_DENSITIES)}`));
+  if (theme.density !== void 0 && !THEME_DENSITIES.includes(theme.density)) out.push(refuse2("density", `app.theme.density is ${JSON.stringify(theme.density)}; it is ${either3(THEME_DENSITIES)}`));
   return out;
 }
 function themeValue(token, tokens, seen = /* @__PURE__ */ new Set()) {
@@ -12850,51 +13445,51 @@ function atPointer(root, pointer2) {
 function paramValueProblems(param, said2, at) {
   const problems = [];
   const kind = param.kind;
-  const refuse = (key, why) => problems.push({ code: "param_kind_value", pointer: at(key), message: `${said2} (${kind}) ${why}` });
+  const refuse2 = (key, why) => problems.push({ code: "param_kind_value", pointer: at(key), message: `${said2} (${kind}) ${why}` });
   const finite = (value2) => typeof value2 === "number" && Number.isFinite(value2);
   for (const key of ["min", "max", "step"]) {
     if (param[key] === void 0) continue;
-    if (!NUMERIC_PARAM_KINDS.has(kind)) refuse(key, `states ${key}, which only a slider or a number has`);
-    else if (!finite(param[key])) refuse(key, `states ${key} as ${JSON.stringify(param[key])}; it has to be a finite number \u2014 ${numberFix(param[key])}`);
+    if (!NUMERIC_PARAM_KINDS.has(kind)) refuse2(key, `states ${key}, which only a slider or a number has`);
+    else if (!finite(param[key])) refuse2(key, `states ${key} as ${JSON.stringify(param[key])}; it has to be a finite number \u2014 ${numberFix(param[key])}`);
   }
   if (param.values !== void 0) {
-    if (!STRING_PARAM_KINDS.has(kind)) refuse("values", `states values, which only a select, multi, period or month is held to`);
-    else if (!Array.isArray(param.values) || param.values.length === 0 || !param.values.every(named5)) refuse("values", `states values as ${JSON.stringify(param.values)}; it is a non-empty list of strings (leave it out to take the values from the source's catalog)`);
-    else if (new Set(param.values).size !== param.values.length) refuse("values", "lists one value twice");
+    if (!STRING_PARAM_KINDS.has(kind)) refuse2("values", `states values, which only a select, multi, period or month is held to`);
+    else if (!Array.isArray(param.values) || param.values.length === 0 || !param.values.every(named5)) refuse2("values", `states values as ${JSON.stringify(param.values)}; it is a non-empty list of strings (leave it out to take the values from the source's catalog)`);
+    else if (new Set(param.values).size !== param.values.length) refuse2("values", "lists one value twice");
   }
   if (param.max_selected !== void 0) {
-    if (kind !== "multi") refuse("max_selected", "states max_selected, which only a multi has");
-    else if (!Number.isInteger(param.max_selected) || param.max_selected < 1) refuse("max_selected", `states max_selected as ${JSON.stringify(param.max_selected)}; it is a whole number of at least 1`);
-    else if (Array.isArray(param.values) && param.max_selected > param.values.length) refuse("max_selected", `allows ${param.max_selected} of only ${param.values.length} values`);
+    if (kind !== "multi") refuse2("max_selected", "states max_selected, which only a multi has");
+    else if (!Number.isInteger(param.max_selected) || param.max_selected < 1) refuse2("max_selected", `states max_selected as ${JSON.stringify(param.max_selected)}; it is a whole number of at least 1`);
+    else if (Array.isArray(param.values) && param.max_selected > param.values.length) refuse2("max_selected", `allows ${param.max_selected} of only ${param.values.length} values`);
   }
   if (problems.length > 0) return problems;
   const { min, max, step } = param;
   if (NUMERIC_PARAM_KINDS.has(kind)) {
-    if (finite(min) && finite(max) && min > max) refuse("min", `has min ${min} above max ${max}`);
-    if (finite(step) && step <= 0) refuse("step", `steps by ${step}; a step is above 0`);
+    if (finite(min) && finite(max) && min > max) refuse2("min", `has min ${min} above max ${max}`);
+    if (finite(step) && step <= 0) refuse2("step", `steps by ${step}; a step is above 0`);
   }
   if (param.default === void 0) return problems;
   const value = param.default;
   const values = Array.isArray(param.values) ? param.values : null;
   if (NUMERIC_PARAM_KINDS.has(kind)) {
-    if (!finite(value)) refuse("default", `defaults to ${JSON.stringify(value)}; a ${kind} opens on a finite number`);
+    if (!finite(value)) refuse2("default", `defaults to ${JSON.stringify(value)}; a ${kind} opens on a finite number`);
     else if (finite(min) && value < min || finite(max) && value > max) {
-      refuse("default", `defaults to ${value}, outside its own range [${finite(min) ? min : "\u2026"}, ${finite(max) ? max : "\u2026"}] \u2014 the page would open on no value at all`);
+      refuse2("default", `defaults to ${value}, outside its own range [${finite(min) ? min : "\u2026"}, ${finite(max) ? max : "\u2026"}] \u2014 the page would open on no value at all`);
     }
   } else if (kind === "toggle") {
-    if (typeof value !== "boolean") refuse("default", `defaults to ${JSON.stringify(value)}; a toggle opens on true or false`);
+    if (typeof value !== "boolean") refuse2("default", `defaults to ${JSON.stringify(value)}; a toggle opens on true or false`);
   } else if (kind === "multi") {
-    if (!Array.isArray(value) || !value.every((one) => typeof one === "string")) refuse("default", `defaults to ${JSON.stringify(value)}; a multi opens on a list of strings`);
-    else if (values !== null && value.some((one) => !values.includes(one))) refuse("default", `defaults to ${JSON.stringify(value)}, which is not among its values ${JSON.stringify(values)}`);
-    else if (Number.isInteger(param.max_selected) && value.length > param.max_selected) refuse("default", `opens on ${value.length} values and allows ${param.max_selected}`);
+    if (!Array.isArray(value) || !value.every((one) => typeof one === "string")) refuse2("default", `defaults to ${JSON.stringify(value)}; a multi opens on a list of strings`);
+    else if (values !== null && value.some((one) => !values.includes(one))) refuse2("default", `defaults to ${JSON.stringify(value)}, which is not among its values ${JSON.stringify(values)}`);
+    else if (Number.isInteger(param.max_selected) && value.length > param.max_selected) refuse2("default", `opens on ${value.length} values and allows ${param.max_selected}`);
   } else if (typeof value !== "string") {
-    refuse("default", `defaults to ${JSON.stringify(value)}; a ${kind} opens on a string`);
+    refuse2("default", `defaults to ${JSON.stringify(value)}; a ${kind} opens on a string`);
   } else if (kind === "month" && !MONTH_RE.test(value)) {
-    refuse("default", `defaults to ${JSON.stringify(value)}; a month is written YYYY-MM`);
+    refuse2("default", `defaults to ${JSON.stringify(value)}; a month is written YYYY-MM`);
   } else if (kind === "date" && value !== "" && !isRealDay(value)) {
-    refuse("default", `defaults to ${JSON.stringify(value)}; a date is a real day written YYYY-MM-DD, or '' for none`);
+    refuse2("default", `defaults to ${JSON.stringify(value)}; a date is a real day written YYYY-MM-DD, or '' for none`);
   } else if (values !== null && !values.includes(value)) {
-    refuse("default", `defaults to ${JSON.stringify(value)}, which is not among its values ${JSON.stringify(values)}`);
+    refuse2("default", `defaults to ${JSON.stringify(value)}, which is not among its values ${JSON.stringify(values)}`);
   }
   return problems;
 }
@@ -13027,6 +13622,8 @@ function compileApp(contract, { kit = null, runtime = RUNTIME, extra = {} } = {}
   problems.push(...sourceFindings.filter((one) => !one.advisory));
   problems.push(...compareProblems(stated2, model));
   problems.push(...exprProblems(stated2));
+  const metricFindings = metricProblems(contract?.data?.metrics, stated2);
+  problems.push(...metricFindings.filter((one) => !one.advisory));
   problems.push(...paramProblems(contract, stated2));
   problems.push(...themeProblems(app));
   problems.push(...shellProblems(contract, typed, handlers, stated2));
@@ -13113,7 +13710,7 @@ function compileApp(contract, { kit = null, runtime = RUNTIME, extra = {} } = {}
   problems.push(...partPinProblems(declared, { "dr-components": appComponents, "dr-components-controls": appControls }));
   problems.push(...runtimePinProblems(declared, runtime));
   const widgetFindings = tree.problems.length === 0 ? widgetProblems(declared, tree, handlers, contract?.data?.sources, appWidgets) : [];
-  const warnings = [...sourceFindings, ...widgetFindings].filter((one) => one.advisory).map(({ advisory: _advisory, ...one }) => one);
+  const warnings = [...sourceFindings, ...metricFindings, ...widgetFindings].filter((one) => one.advisory).map(({ advisory: _advisory, ...one }) => one);
   problems.push(...widgetFindings.filter((one) => !one.advisory));
   if (tree.problems.length === 0) problems.push(...partProblems(declared, tree, handlers, sources, contract?.pages, model, { "dr-components": appComponents }));
   const backendFacts = inferredBackendHandlers(contract?.backend?.handlers, handlers, extra);
@@ -13310,51 +13907,51 @@ function shellProblems(contract, elements, handlers, sources) {
   const pages = Array.isArray(contract?.pages) ? contract.pages : [];
   const paths = new Set(pages.map((page) => page?.path).filter(named5));
   const params = new Set(pages.flatMap((page) => (Array.isArray(page?.params) ? page.params : []).map((param) => param?.name)).filter(named5));
-  const refuse = (pointer2, message) => problems.push({ code: "shell_shape", pointer: pointer2, message });
+  const refuse2 = (pointer2, message) => problems.push({ code: "shell_shape", pointer: pointer2, message });
   const roleNames = new Set(
     (Array.isArray(contract?.backend?.roles) ? contract.backend.roles : []).map((role) => typeof role === "string" ? role : role?.name).filter(named5)
   );
   if (app.shell !== void 0 && app.shell !== null) {
     const shell = app.shell;
-    if (!isPlainObject8(shell)) refuse("/app/shell", `app.shell is ${JSON.stringify(shell)}; it is {"nav": "tabs"|"rail", "topbar"?: true, "rail"?: {...}}`);
+    if (!isPlainObject8(shell)) refuse2("/app/shell", `app.shell is ${JSON.stringify(shell)}; it is {"nav": "tabs"|"rail", "topbar"?: true, "rail"?: {...}}`);
     else {
-      if (shell.nav !== void 0 && !SHELL_NAVS.includes(shell.nav)) refuse("/app/shell/nav", `app.shell.nav is ${JSON.stringify(shell.nav)}; it is ${either3(SHELL_NAVS)}`);
-      if (shell.topbar !== void 0 && typeof shell.topbar !== "boolean") refuse("/app/shell/topbar", `app.shell.topbar is ${JSON.stringify(shell.topbar)}; it is true or false`);
-      if (shell.rail !== void 0 && !isPlainObject8(shell.rail)) refuse("/app/shell/rail", `app.shell.rail is ${JSON.stringify(shell.rail)}; it is {"title"?, "entries"?: [...], "footer"?: [...]}`);
+      if (shell.nav !== void 0 && !SHELL_NAVS.includes(shell.nav)) refuse2("/app/shell/nav", `app.shell.nav is ${JSON.stringify(shell.nav)}; it is ${either3(SHELL_NAVS)}`);
+      if (shell.topbar !== void 0 && typeof shell.topbar !== "boolean") refuse2("/app/shell/topbar", `app.shell.topbar is ${JSON.stringify(shell.topbar)}; it is true or false`);
+      if (shell.rail !== void 0 && !isPlainObject8(shell.rail)) refuse2("/app/shell/rail", `app.shell.rail is ${JSON.stringify(shell.rail)}; it is {"title"?, "entries"?: [...], "footer"?: [...]}`);
       else if (isPlainObject8(shell.rail)) {
         for (const key of ["entries", "footer"]) {
           const list3 = shell.rail[key];
           if (list3 === void 0) continue;
           if (!Array.isArray(list3)) {
-            refuse(`/app/shell/rail/${key}`, `app.shell.rail.${key} is ${JSON.stringify(list3)}; it is a list of {"label", ...}`);
+            refuse2(`/app/shell/rail/${key}`, `app.shell.rail.${key} is ${JSON.stringify(list3)}; it is a list of {"label", ...}`);
             continue;
           }
           for (const [index, entry] of list3.entries()) {
             const at = `/app/shell/rail/${key}/${index}`;
             if (!isPlainObject8(entry) || !named5(entry.label)) {
-              refuse(at, `app.shell.rail.${key}[${index}] is ${JSON.stringify(entry)}; every entry has a label (the runtime drops one without)`);
+              refuse2(at, `app.shell.rail.${key}[${index}] is ${JSON.stringify(entry)}; every entry has a label (the runtime drops one without)`);
               continue;
             }
             if (entry.page !== void 0 && !(named5(entry.page) && paths.has(entry.page))) {
-              refuse(`${at}/page`, `rail entry "${entry.label}" links to ${JSON.stringify(entry.page)}, which pages[] does not declare; name a page of this app (${[...paths].sort(natural3).map((one) => JSON.stringify(one)).join(", ")})`);
+              refuse2(`${at}/page`, `rail entry "${entry.label}" links to ${JSON.stringify(entry.page)}, which pages[] does not declare; name a page of this app (${[...paths].sort(natural3).map((one) => JSON.stringify(one)).join(", ")})`);
             }
-            if (key === "footer" && !named5(entry.page)) refuse(`${at}/page`, `rail footer entry "${entry.label}" links nowhere; a footer entry is {"label", "page"}`);
+            if (key === "footer" && !named5(entry.page)) refuse2(`${at}/page`, `rail footer entry "${entry.label}" links nowhere; a footer entry is {"label", "page"}`);
             if (entry.param !== void 0) {
               if (!isPlainObject8(entry.param) || Object.keys(entry.param).length === 0) {
-                refuse(`${at}/param`, `rail entry "${entry.label}" states param as ${JSON.stringify(entry.param)}; it is {"<page param>": <value>}`);
+                refuse2(`${at}/param`, `rail entry "${entry.label}" states param as ${JSON.stringify(entry.param)}; it is {"<page param>": <value>}`);
               } else {
                 for (const name of Object.keys(entry.param).sort(natural3)) {
-                  if (!params.has(name)) refuse(`${at}/param/${escapePointer3(name)}`, `rail entry "${entry.label}" sets the param "${name}", which no page declares in pages[].params; the param store keeps only declared params, so the entry would do nothing`);
+                  if (!params.has(name)) refuse2(`${at}/param/${escapePointer3(name)}`, `rail entry "${entry.label}" sets the param "${name}", which no page declares in pages[].params; the param store keeps only declared params, so the entry would do nothing`);
                 }
               }
             }
-            if (entry.measure !== void 0 && !named5(entry.measure)) refuse(`${at}/measure`, `rail entry "${entry.label}" states measure as ${JSON.stringify(entry.measure)}; it is the name of one measure of the page's nav.counts.source`);
+            if (entry.measure !== void 0 && !named5(entry.measure)) refuse2(`${at}/measure`, `rail entry "${entry.label}" states measure as ${JSON.stringify(entry.measure)}; it is the name of one measure of the page's nav.counts.source`);
             if (entry.role !== void 0) {
               const names = named5(entry.role) ? entry.role.split(/\s+/).filter(named5) : [];
               const unknown = names.filter((name) => !roleNames.has(name));
-              if (names.length === 0) refuse(`${at}/role`, `rail entry "${entry.label}" states role as ${JSON.stringify(entry.role)}; it is one role name, or several space-separated`);
+              if (names.length === 0) refuse2(`${at}/role`, `rail entry "${entry.label}" states role as ${JSON.stringify(entry.role)}; it is one role name, or several space-separated`);
               else if (unknown.length > 0) {
-                refuse(
+                refuse2(
                   `${at}/role`,
                   `rail entry "${entry.label}" is for ${unknown.map((one) => JSON.stringify(one)).join(", ")}, which ${roleNames.size === 0 ? "the app does not declare (it declares no roles)" : `backend.roles does not declare (${[...roleNames].map((one) => JSON.stringify(one)).join(", ")})`}; the runtime would draw it for nobody`
                 );
@@ -13368,14 +13965,14 @@ function shellProblems(contract, elements, handlers, sources) {
   for (const [index, page] of pages.entries()) {
     if (!isPlainObject8(page) || page.owned === true) continue;
     if (isPlainObject8(page.header) && page.header.title_from !== void 0 && page.header.title_from !== "rail") {
-      refuse(`/pages/${index}/header/title_from`, `${page.path}'s header.title_from is ${JSON.stringify(page.header.title_from)}; the one this runtime reads is "rail" (the active rail entry's label)`);
+      refuse2(`/pages/${index}/header/title_from`, `${page.path}'s header.title_from is ${JSON.stringify(page.header.title_from)}; the one this runtime reads is "rail" (the active rail entry's label)`);
     }
     if (page.nav !== void 0) {
       const source = page.nav?.counts?.source;
       if (!isPlainObject8(page.nav) || !isPlainObject8(page.nav.counts) || !named5(source)) {
-        refuse(`/pages/${index}/nav`, `${page.path}'s nav is ${JSON.stringify(page.nav)}; it is {"counts": {"source": "<summary handler>"}}`);
+        refuse2(`/pages/${index}/nav`, `${page.path}'s nav is ${JSON.stringify(page.nav)}; it is {"counts": {"source": "<summary handler>"}}`);
       } else if (!Object.prototype.hasOwnProperty.call(handlers, source) && !Object.prototype.hasOwnProperty.call(sources ?? {}, source)) {
-        refuse(`/pages/${index}/nav/counts/source`, `${page.path}'s nav.counts.source is "${source}", which is not a handler or source of this app; name the summary handler whose measures are the rail's counts`);
+        refuse2(`/pages/${index}/nav/counts/source`, `${page.path}'s nav.counts.source is "${source}", which is not a handler or source of this app; name the summary handler whose measures are the rail's counts`);
       }
     }
   }
@@ -13822,7 +14419,7 @@ function queryablePlatformColumns(table) {
 function platformQueryProblems(name, row, table) {
   const problems = [];
   const allowed = queryablePlatformColumns(table);
-  const refuse = (key, column) => {
+  const refuse2 = (key, column) => {
     const why = column === "_created_by" ? `table "${table.name}" does not declare showAuthor, so no read returns the author and none may filter or sort by it \u2014 declare "showAuthor": true on the table, or drop it` : `no app read returns it, so none may filter or sort by it \u2014 use _created_at or _updated_at${table?.showAuthor ? ", or _created_by" : ""}`;
     problems.push({
       code: "platform_column_not_queryable",
@@ -13832,11 +14429,11 @@ function platformQueryProblems(name, row, table) {
   };
   if (named5(row.order_by)) {
     const column = row.order_by.replace(/^-+/, "");
-    if (column.startsWith("_") && !allowed.has(column)) refuse("order_by", column);
+    if (column.startsWith("_") && !allowed.has(column)) refuse2("order_by", column);
   }
   for (const key of Object.keys(isPlainObject8(row.where) ? row.where : {}).sort()) {
     const column = key.split("__")[0];
-    if (column.startsWith("_") && !allowed.has(column)) refuse("where", column);
+    if (column.startsWith("_") && !allowed.has(column)) refuse2("where", column);
   }
   return problems;
 }
@@ -15310,12 +15907,12 @@ function computedProblems(elements, tree, handlers, model) {
     const computed = computedIn(row.table);
     if (computed.size === 0) continue;
     const at = (...keys2) => `/data/app/handlers/${[name, ...keys2].map(escapePointer3).join("/")}`;
-    const refuse = (pointer2, column, how) => push(pointer2, `handler "${name}" ${how} "${column}", which is computed by the platform from its children; nothing writes it`);
+    const refuse2 = (pointer2, column, how) => push(pointer2, `handler "${name}" ${how} "${column}", which is computed by the platform from its children; nothing writes it`);
     if (row.role === "submit" || row.role === "save") {
       for (const key of ["fields", "required"]) {
-        for (const hit of (Array.isArray(row[key]) ? row[key] : []).filter((column) => computed.has(column))) refuse(at(key), hit, key === "fields" ? "takes" : "requires");
+        for (const hit of (Array.isArray(row[key]) ? row[key] : []).filter((column) => computed.has(column))) refuse2(at(key), hit, key === "fields" ? "takes" : "requires");
       }
-      for (const fixed of Object.keys(isPlainObject8(row.fixed) ? row.fixed : {}).filter((column) => computed.has(column))) refuse(at("fixed"), fixed, "fixes");
+      for (const fixed of Object.keys(isPlainObject8(row.fixed) ? row.fixed : {}).filter((column) => computed.has(column))) refuse2(at("fixed"), fixed, "fixes");
     }
   }
   if (tree.problems.length > 0) return problems;
@@ -24939,6 +25536,15 @@ function rendererOf3(pages) {
   }
   return {};
 }
+function metricsOf2(pages) {
+  for (const page of pages ?? []) {
+    const embedded = embeddedContractOf2(page);
+    if (embedded === null) continue;
+    const metrics = embedded.data?.metrics;
+    return isPlainObject12(metrics) ? { metrics } : {};
+  }
+  return {};
+}
 function cardSpecOf2(element) {
   const card = element?.props?.card;
   return element?.type === "widget" && typeof card === "string" && card !== "" ? card : null;
@@ -25525,7 +26131,9 @@ function dataSection2(app, manifest, spec, elements, describe7, problems) {
     ...application === null ? {} : { app: application },
     // Only when there are any: a contract written before sources existed
     // reads back byte for byte as it always did.
-    ...Object.keys(sources).length > 0 ? { sources } : {}
+    ...Object.keys(sources).length > 0 ? { sources } : {},
+    // The same for declared metrics, which only an app's pages carry.
+    ...isApp ? metricsOf2(app.pages) : {}
   };
   if (describe7) {
     const widgets2 = isPlainObject12(describe7.widgets) ? describe7.widgets : {};
@@ -29055,6 +29663,14 @@ var REFUSALS = /* @__PURE__ */ new Set([
   "source_compare_field",
   // a source's formula, which the platform evaluates (lineage tier 3)
   "source_expr",
+  // a declared Datarails metric (data.metrics, design 06), and a source that
+  // reads one by key
+  "metric_decl",
+  "metric_kind_later",
+  "metric_formula",
+  "metric_base",
+  "metric_format",
+  "source_metric",
   // dr-components parts (DC-4)
   "part_props",
   "part_source_shape",
@@ -29141,6 +29757,14 @@ var KPI_REFUSALS = {
 var EXPR_REFUSALS = {
   source_expr: "a source's formula (its expr) has a from that is no list, or sits beside a transform; answers a shape other than kpi, series or breakdown; states compare (its compare is its formula over its operands' compares); cannot be evaluated (it is not text, a syntax error, a function other than abs, min, max, round and if, a wrong number of arguments, round decimals other than a whole number from 0 to 6, an if whose first argument is no comparison, a comparison anywhere but if's condition, a name not in from); can be, on some path, a number it states rather than an operand's (numbers alone such as 870000, a typed if() branch such as if(actual > 0, 870000, actual), or a typed min() or max() bound such as max(actual, 0): each branch of if() and each argument of min() and max() must come from an operand, and / already gives no figure for a zero divisor, so no fallback number is needed); names an operand it never reads; reads an operand that is not a FinanceOS read or metric or a formula over them (a transform, a composed source, a call, one of the app's own tables); reads an operand of a shape it cannot take (a kpi formula takes kpis; a series or breakdown formula its own shape and kpis), or, as a series or breakdown formula, has no operand of its own shape; reads a breakdown operand that does not state top: null; or reads itself \u2014 the message names which"
 };
+var METRIC_REFUSALS = {
+  metric_decl: `a data.metrics key that is not a lowercase letter then lowercase letters, digits or _; a declaration that is no object, or states a key a declaration does not take; a name that is empty, over 128 characters, holds ' [ or ], starts with @, or is DAYS_IN_PERIOD or PERIODS_IN_YEAR; a kind other than base or calc; a calc with no formula; a base with no table, value, date or aggregate, or a table that is not exactly one of alias, name and id; one kind's keys on the other; a reuse other than definition or name, a create that is not true or false, a description that is not text; or a declaration with no definition that does not say "reuse": "name" and "create": false \u2014 the message names which`,
+  metric_kind_later: 'a declaration of kind driver, which is reserved until driver declarations ship \u2014 declare a base or calc metric, or bind the driver by name ("reuse": "name", "create": false)',
+  metric_formula: "a calc formula Datarails would refuse (dr-cli's checks: empty or over 5000 characters, unbalanced brackets or grouping, a time modifier that is lowercase, chained, on no operand, malformed, a future SHIFT or one past 1200, an invalid unit or anchor, a modifier on a system variable, an unbracketed word, no metric read); arithmetic out of order (two operators in a row, a missing operand or operator, empty parentheses, a number such as 1.2.3); an operand that is not a declared [@key] \u2014 a metric named itself, quoted or bracketed ('Revenue', [Revenue]), so the contract names no company's metric; a scenario pin (|); a window function it cannot read; or a declaration that reads itself, however far round",
+  metric_base: "a base aggregate other than sum, count, cumulative_sum or cumulative_count, a time_aggregation other than sum, eop or avg, a cumulative aggregate rolled up with sum, or a filter that is not {field, values, exclude}",
+  metric_format: 'a format the metric editor never writes (optional "$" quoted, \u20AC \xA3 \u20AA or a % suffix, #,### or ####, .# to .####, [kilo]k or [mega]M) \u2014 the message names the stored spelling where one was plainly meant',
+  source_metric: `a source's from.financeos.metric that is not "@<key>" of a key data.metrics declares, or that stands beside metric_id`
+};
 var TRANSFORM_REFUSALS = {
   transform_row: 'a row names a transform and is not a dataset series row ("kind": "series", "data": "<dataset>", and no source, compute, depends, drill, window or by), or its dataset reads with the period pushed down (a period other than "all")',
   transform_missing: "a row or source names a transform not spelled transforms/<name>.py, or that file is not beside contract.json",
@@ -30249,6 +30873,9 @@ function registerCompileCommand(parent) {
           ...Object.entries(KPI_REFUSALS).map(([code, what]) => `  ${code.padEnd(22)}${what}`),
           "A source that states its figure as a formula (expr over from, evaluated by the platform) is refused with:",
           ...Object.entries(EXPR_REFUSALS).map(([code, what]) => `  ${code.padEnd(22)}${what}`),
+          'A declared Datarails metric (data.metrics, read by a source as from.financeos.metric "@<key>") is refused with:',
+          ...Object.entries(METRIC_REFUSALS).map(([code, what]) => `  ${code.padEnd(22)}${what}`),
+          "  (warnings, never refusals: metric_window, a window function Datarails gates by company; metric_unused, a declaration no source reads; expr_could_be_metric, an expr a calc metric could say)",
           "",
           "A transform (a dashboard dataset series row's transforms/<name>.py, or an app source's) is refused with:",
           ...Object.entries(TRANSFORM_REFUSALS).map(([code, what]) => `  ${code.padEnd(22)}${what}`)
@@ -30299,29 +30926,29 @@ var ONTO_LIVE_MARK = ".onto-live";
 var ONTO_LIVE_OWNED = ["contract.json", "manifest.json", "data_model.json", "handlers", "ui", "transforms", ".appspace.json", ".appspace"];
 async function runShipOntoLive(dir, opts) {
   const appId = opts.appId;
-  const refuse = (why) => {
+  const refuse2 = (why) => {
     process.stderr.write(`ship --onto-live: ${why}
 `);
     return 1;
   };
-  if (appId === void 0 || appId.trim() === "") return refuse("pass --app-id <id>: the app to land on.");
-  if ((opts.draft ?? []).length === 0) return refuse("pass --draft <file>: the cards to land.");
+  if (appId === void 0 || appId.trim() === "") return refuse2("pass --app-id <id>: the app to land on.");
+  if ((opts.draft ?? []).length === 0) return refuse2("pass --draft <file>: the cards to land.");
   if (opts.skeleton === void 0) {
-    return refuse("pass --skeleton <file>: the frame the app is created from if nothing has landed yet.");
+    return refuse2("pass --skeleton <file>: the frame the app is created from if nothing has landed yet.");
   }
   if ((opts.expect ?? []).length > 0) {
-    return refuse("--expect holds the headline, which is the build's to confirm; a landing proves its own cards only.");
+    return refuse2("--expect holds the headline, which is the build's to confirm; a landing proves its own cards only.");
   }
   if (opts.force === true) {
-    return refuse(
+    return refuse2(
       "does not take --force: every landing builds on the cards already live, and --force would let this one replace them. Run the same command without it. If it refuses over files it did not write, the live app could not be read whole: run it again, and report the refusal if it repeats."
     );
   }
   const owned = await claimFolder(dir);
-  if (owned !== null) return refuse(owned);
+  if (owned !== null) return refuse2(owned);
   await defaultServerFromSession(opts);
   if (!hasServer(opts)) {
-    return refuse("needs a server: pass -s <server> (or set DR_APP_SPACE_HOST), or log in so a stored session supplies one.");
+    return refuse2("needs a server: pass -s <server> (or set DR_APP_SPACE_HOST), or log in so a stored session supplies one.");
   }
   return landWithRetries(async (createGuarded) => {
     for (const name of ONTO_LIVE_OWNED) await rm4(join15(dir, name), { recursive: true, force: true });
@@ -32751,7 +33378,7 @@ async function runUiSmoke(opts) {
   const { JSDOM, ResourceLoader, VirtualConsole } = await loadJsdom();
   let inFlight = 0;
   let lastActivity = Date.now();
-  async function record2(req, via, refuse) {
+  async function record2(req, via, refuse2) {
     const call = { method: req.method, url: maskToken(req.url), via };
     if (via === "fetch" && req.body) {
       try {
@@ -32763,8 +33390,8 @@ async function runUiSmoke(opts) {
     const auth = req.headers["authorization"];
     if (auth !== void 0) call.authorization = summariseAuthorization(auth);
     calls.push(call);
-    if (refuse !== void 0) {
-      call.failure = refuse;
+    if (refuse2 !== void 0) {
+      call.failure = refuse2;
       return void 0;
     }
     if (!sameOrigin(req.url, target)) {