@databricks/appkit 0.41.4 → 0.41.6

package/dist/appkit/package.js

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "@databricks/appkit";
-var version = "0.41.4";
+var version = "0.41.6";
 
 //#endregion
 export { name, version };

package/dist/shared/src/schemas/metric-fqn.js

@@ -0,0 +1,85 @@
+//#region ../shared/src/schemas/metric-fqn.ts
+/**
+* Unity Catalog object-name grammar - the single source of truth for metric
+* view FQN naming validation.
+*
+* This module is deliberately **zod-free**. A metric view's `source` FQN is
+* validated in two places that must agree:
+*
+*  1. The canonical Zod schema (`./metric-source.ts`), which composes the
+*     three-part FQN regex from {@link UC_FQN_PATTERN} for IDE/CI and the
+*     generated JSON schema (`docs/static/schemas/metric-source.schema.json`).
+*  2. The type-generator runtime (`packages/appkit/src/type-generator/mv-registry/config.ts`),
+*     which imports {@link UC_FQN_PATTERN} as a plain value to validate each
+*     dot-split segment.
+*
+* The type-generator's runtime path must NOT pull the shared Zod schema package
+* in (locked dependency-graph ruling - see the comment in
+* `packages/appkit/src/type-generator/cache.ts`). Keeping the pattern in this
+* zod-free module lets the runtime import the regex without dragging zod into
+* its bundle, while still single-sourcing the grammar.
+*
+* -- UC delimited (quoted) object-name rules ------------------------------
+* The metric view FQN is always backtick-quoted before interpolation into SQL
+* (see `quoteFqnForSql` in the type-generator), so the **delimited identifier**
+* grammar is the one that applies - not the narrower unquoted-identifier rule.
+*
+* Per the Databricks SQL names reference, a Unity Catalog object name:
+*  - cannot exceed 255 characters ({@link MAX_UC_OBJECT_NAME_LENGTH}); and
+*  - cannot contain any of these characters:
+*      - period (`.`)
+*      - space (U+0020)
+*      - forward slash (`/`)
+*      - all ASCII control characters (U+0000-U+001F)
+*      - the DELETE character (U+007F)
+*
+* Every other character is permitted in a quoted name, including non-ASCII
+* letters (the docs demonstrate Chinese/Russian/Portuguese names) and hyphens.
+* This is intentionally broader than the old hand-rolled allowlist
+* (`[a-zA-Z0-9_-]`), which was flagged in PR #433 review (pkosiec: "more
+* restrictive than UC"): the goal is to accept what UC accepts as a quoted
+* name and reject only what UC rejects.
+*
+* Verified against the Databricks docs on 2026-06-19:
+*   https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-names
+* (the link cited in the PR #433 review). If the published rules change,
+* re-confirm against that page.
+*
+* @note The period is excluded here because it is the FQN segment separator -
+* a name containing a literal dot cannot be expressed in the dotted `source`
+* string at all. The dotted-source arity (exactly three segments) and the
+* 255-char-per-segment cap are enforced structurally by the callers; this
+* pattern only encodes the per-segment allowed character set.
+*/
+/**
+* Maximum length, in characters, of a single Unity Catalog object name
+* (catalog, schema, or metric view). UC rejects names longer than this.
+*/
+const MAX_UC_OBJECT_NAME_LENGTH = 255;
+/**
+* Matches a single, non-empty Unity Catalog object name as it may appear in a
+* backtick-quoted (delimited) identifier - one segment of a metric view FQN.
+*
+* Accepts any non-empty run of characters EXCEPT the UC-prohibited set:
+* period, space, forward slash, ASCII control characters (U+0000-U+001F), and
+* DELETE (U+007F). Length is NOT bounded here - callers enforce
+* {@link MAX_UC_OBJECT_NAME_LENGTH} separately so they can emit a precise
+* "segment too long" message distinct from a charset violation.
+*
+* The negated character class encodes the prohibited set as one contiguous
+* range plus singletons: U+0000-U+0020 (every ASCII control character plus the
+* space, which sits at U+0020 immediately after the control range), U+007F
+* (DELETE), `.` (period - also the FQN segment separator), and `/` (slash).
+*
+* @example
+* UC_FQN_PATTERN.test("revenue_metrics"); // true
+* UC_FQN_PATTERN.test("prod-data");        // true (hyphens are UC-legal)
+* UC_FQN_PATTERN.test("cafe\u0301");       // true (non-ASCII is UC-legal)
+* UC_FQN_PATTERN.test("bad name");         // false (space is prohibited)
+* UC_FQN_PATTERN.test("a/b");              // false (slash is prohibited)
+*/
+const UC_FQN_PATTERN = /^[^\x00-\x20\x7f./]+$/;
+
+//#endregion
+export { MAX_UC_OBJECT_NAME_LENGTH, UC_FQN_PATTERN };
+//# sourceMappingURL=metric-fqn.js.map

package/dist/shared/src/schemas/metric-fqn.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metric-fqn.js","names":[],"sources":["../../../../../shared/src/schemas/metric-fqn.ts"],"sourcesContent":["/**\n * Unity Catalog object-name grammar - the single source of truth for metric\n * view FQN naming validation.\n *\n * This module is deliberately **zod-free**. A metric view's `source` FQN is\n * validated in two places that must agree:\n *\n *  1. The canonical Zod schema (`./metric-source.ts`), which composes the\n *     three-part FQN regex from {@link UC_FQN_PATTERN} for IDE/CI and the\n *     generated JSON schema (`docs/static/schemas/metric-source.schema.json`).\n *  2. The type-generator runtime (`packages/appkit/src/type-generator/mv-registry/config.ts`),\n *     which imports {@link UC_FQN_PATTERN} as a plain value to validate each\n *     dot-split segment.\n *\n * The type-generator's runtime path must NOT pull the shared Zod schema package\n * in (locked dependency-graph ruling - see the comment in\n * `packages/appkit/src/type-generator/cache.ts`). Keeping the pattern in this\n * zod-free module lets the runtime import the regex without dragging zod into\n * its bundle, while still single-sourcing the grammar.\n *\n * -- UC delimited (quoted) object-name rules ------------------------------\n * The metric view FQN is always backtick-quoted before interpolation into SQL\n * (see `quoteFqnForSql` in the type-generator), so the **delimited identifier**\n * grammar is the one that applies - not the narrower unquoted-identifier rule.\n *\n * Per the Databricks SQL names reference, a Unity Catalog object name:\n *  - cannot exceed 255 characters ({@link MAX_UC_OBJECT_NAME_LENGTH}); and\n *  - cannot contain any of these characters:\n *      - period (`.`)\n *      - space (U+0020)\n *      - forward slash (`/`)\n *      - all ASCII control characters (U+0000-U+001F)\n *      - the DELETE character (U+007F)\n *\n * Every other character is permitted in a quoted name, including non-ASCII\n * letters (the docs demonstrate Chinese/Russian/Portuguese names) and hyphens.\n * This is intentionally broader than the old hand-rolled allowlist\n * (`[a-zA-Z0-9_-]`), which was flagged in PR #433 review (pkosiec: \"more\n * restrictive than UC\"): the goal is to accept what UC accepts as a quoted\n * name and reject only what UC rejects.\n *\n * Verified against the Databricks docs on 2026-06-19:\n *   https://docs.databricks.com/aws/en/sql/language-manual/sql-ref-names\n * (the link cited in the PR #433 review). If the published rules change,\n * re-confirm against that page.\n *\n * @note The period is excluded here because it is the FQN segment separator -\n * a name containing a literal dot cannot be expressed in the dotted `source`\n * string at all. The dotted-source arity (exactly three segments) and the\n * 255-char-per-segment cap are enforced structurally by the callers; this\n * pattern only encodes the per-segment allowed character set.\n */\n\n/**\n * Maximum length, in characters, of a single Unity Catalog object name\n * (catalog, schema, or metric view). UC rejects names longer than this.\n */\nexport const MAX_UC_OBJECT_NAME_LENGTH = 255;\n\n/**\n * Matches a single, non-empty Unity Catalog object name as it may appear in a\n * backtick-quoted (delimited) identifier - one segment of a metric view FQN.\n *\n * Accepts any non-empty run of characters EXCEPT the UC-prohibited set:\n * period, space, forward slash, ASCII control characters (U+0000-U+001F), and\n * DELETE (U+007F). Length is NOT bounded here - callers enforce\n * {@link MAX_UC_OBJECT_NAME_LENGTH} separately so they can emit a precise\n * \"segment too long\" message distinct from a charset violation.\n *\n * The negated character class encodes the prohibited set as one contiguous\n * range plus singletons: U+0000-U+0020 (every ASCII control character plus the\n * space, which sits at U+0020 immediately after the control range), U+007F\n * (DELETE), `.` (period - also the FQN segment separator), and `/` (slash).\n *\n * @example\n * UC_FQN_PATTERN.test(\"revenue_metrics\"); // true\n * UC_FQN_PATTERN.test(\"prod-data\");        // true (hyphens are UC-legal)\n * UC_FQN_PATTERN.test(\"cafe\\u0301\");       // true (non-ASCII is UC-legal)\n * UC_FQN_PATTERN.test(\"bad name\");         // false (space is prohibited)\n * UC_FQN_PATTERN.test(\"a/b\");              // false (slash is prohibited)\n */\n// biome-ignore lint/suspicious/noControlCharactersInRegex: UC explicitly prohibits ASCII control characters in object names; this negated class encodes that rule.\nexport const UC_FQN_PATTERN = /^[^\\x00-\\x20\\x7f./]+$/;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,MAAa,4BAA4B;;;;;;;;;;;;;;;;;;;;;;;AAyBzC,MAAa,iBAAiB"}

package/dist/type-generator/cache.js

@@ -5,6 +5,30 @@ import path from "node:path";
 
 //#region src/type-generator/cache.ts
 const logger = createLogger("type-generator:cache");
+/**
+* Structural gate for reviving a cached metric entry at partition time.
+*
+* The cache file lives in `node_modules/.databricks` and is plain JSON —
+* hand-edits, truncation, or a stale writer can leave entries whose shape no
+* longer matches {@link MetricCacheEntry}. A malformed entry must read as a
+* cache MISS (re-describe) rather than crash the pass or render revived
+* garbage into the artifacts. Checks exactly what the renderers and the
+* metadata bundle consume: `hash` string, `retry` boolean, and a schema with
+* `key`/`source` strings, a valid lane, an optional boolean `degraded`, and
+* measure/dimension arrays whose elements carry `name`/`type` strings
+* (other column fields are optional). Deliberately inline — the shared Zod
+* schemas must not enter the type-generator's runtime path.
+*/
+function isRevivableMetricCacheEntry(entry) {
+	if (typeof entry !== "object" || entry === null) return false;
+	const e = entry;
+	if (typeof e.hash !== "string" || typeof e.retry !== "boolean") return false;
+	const schema = e.schema;
+	if (typeof schema !== "object" || schema === null || Array.isArray(schema)) return false;
+	const s = schema;
+	const isColumnArray = (value) => Array.isArray(value) && value.every((col) => typeof col === "object" && col !== null && typeof col.name === "string" && typeof col.type === "string");
+	return typeof s.key === "string" && typeof s.source === "string" && (s.lane === "sp" || s.lane === "obo") && (s.degraded === void 0 || typeof s.degraded === "boolean") && isColumnArray(s.measures) && isColumnArray(s.dimensions);
+}
 const CACHE_VERSION = "3";
 const CACHE_FILE = ".appkit-types-cache.json";
 const CACHE_DIR = path.join(process.cwd(), "node_modules", ".databricks", "appkit");
@@ -18,6 +42,14 @@ function hashSQL(sql) {
 	return crypto.createHash("md5").update(sql).digest("hex");
 }
 /**
+* Change detector stored on {@link MetricCacheEntry.hash}: md5 over
+* `"<source>|<lane>"` — the two config inputs that determine a DESCRIBE —
+* so editing either invalidates the entry.
+*/
+function metricCacheHash(source, lane) {
+	return hashSQL(`${source}|${lane}`);
+}
+/**
 * Load the cache from the file system
 * If the cache is not found, run the query explain
 * @returns - the cache
@@ -47,5 +79,5 @@ async function saveCache(cache) {
 }
 
 //#endregion
-export { CACHE_VERSION, hashSQL, loadCache, saveCache };
+export { CACHE_VERSION, hashSQL, isRevivableMetricCacheEntry, loadCache, metricCacheHash, saveCache };
 //# sourceMappingURL=cache.js.map

package/dist/type-generator/cache.js.map

@@ -1 +1 @@
-{"version":3,"file":"cache.js","names":[],"sources":["../../src/type-generator/cache.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createLogger } from \"../logging/logger\";\n\nconst logger = createLogger(\"type-generator:cache\");\n\n/**\n * Cache types\n * @property hash - the hash of the SQL query\n * @property type - the type of the query\n */\ninterface CacheEntry {\n  hash: string;\n  type: string;\n  retry: boolean;\n}\n\n/**\n * Cache interface\n * @property version - the version of the cache\n * @property queries - the queries in the cache\n */\ninterface Cache {\n  version: string;\n  queries: Record<string, CacheEntry>;\n}\n\nexport const CACHE_VERSION = \"3\";\nconst CACHE_FILE = \".appkit-types-cache.json\";\nconst CACHE_DIR = path.join(\n  process.cwd(),\n  \"node_modules\",\n  \".databricks\",\n  \"appkit\",\n);\n\n/**\n * Hash the SQL query\n * Uses MD5 to hash the SQL query\n * @param sql - the SQL query to hash\n * @returns - the hash of the SQL query\n */\nexport function hashSQL(sql: string): string {\n  return crypto.createHash(\"md5\").update(sql).digest(\"hex\");\n}\n\n/**\n * Load the cache from the file system\n * If the cache is not found, run the query explain\n * @returns - the cache\n */\nexport async function loadCache(): Promise<Cache> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  try {\n    await fs.mkdir(CACHE_DIR, { recursive: true });\n\n    const raw = await fs.readFile(cachePath, \"utf8\");\n    const cache = JSON.parse(raw) as Cache;\n    if (cache.version === CACHE_VERSION) {\n      return cache;\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      logger.warn(\"Cache file is corrupted, flushing cache completely.\");\n    }\n  }\n  return { version: CACHE_VERSION, queries: {} };\n}\n\n/**\n * Save the cache to the file system\n * @param cache - cache object to save\n */\nexport async function saveCache(cache: Cache): Promise<void> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  await fs.writeFile(cachePath, JSON.stringify(cache, null, 2), \"utf8\");\n}\n"],"mappings":";;;;;;AAKA,MAAM,SAAS,aAAa,uBAAuB;AAuBnD,MAAa,gBAAgB;AAC7B,MAAM,aAAa;AACnB,MAAM,YAAY,KAAK,KACrB,QAAQ,KAAK,EACb,gBACA,eACA,SACD;;;;;;;AAQD,SAAgB,QAAQ,KAAqB;AAC3C,QAAO,OAAO,WAAW,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,MAAM;;;;;;;AAQ3D,eAAsB,YAA4B;CAChD,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,KAAI;AACF,QAAM,GAAG,MAAM,WAAW,EAAE,WAAW,MAAM,CAAC;EAE9C,MAAM,MAAM,MAAM,GAAG,SAAS,WAAW,OAAO;EAChD,MAAM,QAAQ,KAAK,MAAM,IAAI;AAC7B,MAAI,MAAM,YAAY,cACpB,QAAO;UAEF,KAAK;AACZ,MAAK,IAA8B,SAAS,SAC1C,QAAO,KAAK,sDAAsD;;AAGtE,QAAO;EAAE,SAAS;EAAe,SAAS,EAAE;EAAE;;;;;;AAOhD,eAAsB,UAAU,OAA6B;CAC3D,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,OAAM,GAAG,UAAU,WAAW,KAAK,UAAU,OAAO,MAAM,EAAE,EAAE,OAAO"}
+{"version":3,"file":"cache.js","names":[],"sources":["../../src/type-generator/cache.ts"],"sourcesContent":["import crypto from \"node:crypto\";\nimport fs from \"node:fs/promises\";\nimport path from \"node:path\";\nimport { createLogger } from \"../logging/logger\";\nimport type { MetricSchema } from \"./mv-registry/types\";\n\nconst logger = createLogger(\"type-generator:cache\");\n\n/**\n * Cache types\n * @property hash - the hash of the SQL query\n * @property type - the type of the query\n * @property retry - when true the entry never satisfies a cache hit, so the\n *   query is re-described on the next pass; fresh successful describes\n *   persist `retry: false`\n */\ninterface CacheEntry {\n  hash: string;\n  type: string;\n  retry: boolean;\n}\n\n/**\n * One cached metric-view DESCRIBE outcome.\n *\n * `hash` is md5 over `\"<source>|<lane>\"` — the two config inputs that\n * determine a DESCRIBE — so editing either invalidates the entry. `schema`\n * is the full {@link MetricSchema} persisted verbatim (it is JSON-safe by\n * design), letting a warm pass regenerate both metric artifacts without a\n * single warehouse call. `retry: true` marks a SELF-CONVERGING degraded\n * outcome (DESCRIBE skipped behind a not-running warehouse, unanswered, or\n * transiently failed): the cached schema still renders artifacts, but the\n * next eligible pass re-describes exactly these keys so degraded schemas\n * converge to real ones. A degraded schema with `retry: false` is a STICKY\n * failure — a deterministic DESCRIBE failure (bad FQN, unparseable\n * response, zero columns) or a deleted warehouse — that re-describing the\n * unchanged entry cannot fix; it hits like any cached entry until the\n * config hash changes or the cache is bypassed, and the type generator\n * warns about it on every pass that serves it.\n */\nexport interface MetricCacheEntry {\n  hash: string;\n  schema: MetricSchema;\n  retry: boolean;\n}\n\n/**\n * Structural gate for reviving a cached metric entry at partition time.\n *\n * The cache file lives in `node_modules/.databricks` and is plain JSON —\n * hand-edits, truncation, or a stale writer can leave entries whose shape no\n * longer matches {@link MetricCacheEntry}. A malformed entry must read as a\n * cache MISS (re-describe) rather than crash the pass or render revived\n * garbage into the artifacts. Checks exactly what the renderers and the\n * metadata bundle consume: `hash` string, `retry` boolean, and a schema with\n * `key`/`source` strings, a valid lane, an optional boolean `degraded`, and\n * measure/dimension arrays whose elements carry `name`/`type` strings\n * (other column fields are optional). Deliberately inline — the shared Zod\n * schemas must not enter the type-generator's runtime path.\n */\nexport function isRevivableMetricCacheEntry(entry: unknown): boolean {\n  if (typeof entry !== \"object\" || entry === null) return false;\n  const e = entry as Record<string, unknown>;\n  if (typeof e.hash !== \"string\" || typeof e.retry !== \"boolean\") {\n    return false;\n  }\n  const schema = e.schema;\n  if (typeof schema !== \"object\" || schema === null || Array.isArray(schema)) {\n    return false;\n  }\n  const s = schema as Record<string, unknown>;\n  const isColumnArray = (value: unknown): boolean =>\n    Array.isArray(value) &&\n    value.every(\n      (col) =>\n        typeof col === \"object\" &&\n        col !== null &&\n        typeof (col as Record<string, unknown>).name === \"string\" &&\n        typeof (col as Record<string, unknown>).type === \"string\",\n    );\n  return (\n    typeof s.key === \"string\" &&\n    typeof s.source === \"string\" &&\n    (s.lane === \"sp\" || s.lane === \"obo\") &&\n    (s.degraded === undefined || typeof s.degraded === \"boolean\") &&\n    isColumnArray(s.measures) &&\n    isColumnArray(s.dimensions)\n  );\n}\n\n/**\n * Cache interface\n * @property version - the version of the cache\n * @property queries - the queries in the cache\n * @property metrics - cached metric-view schemas keyed by metric key.\n *   OPTIONAL on purpose: version \"3\" files written before this section\n *   existed load unchanged (absent ⇒ treated as empty by the metric path),\n *   and the query path's `noCache` reinit literal stays valid as-is. The\n *   section rides through the query path's load → mutate → save cycle as a\n *   plain sibling key, so query-side saves preserve it byte-for-byte.\n */\ninterface Cache {\n  version: string;\n  queries: Record<string, CacheEntry>;\n  metrics?: Record<string, MetricCacheEntry>;\n}\n\nexport const CACHE_VERSION = \"3\";\nconst CACHE_FILE = \".appkit-types-cache.json\";\nconst CACHE_DIR = path.join(\n  process.cwd(),\n  \"node_modules\",\n  \".databricks\",\n  \"appkit\",\n);\n\n/**\n * Hash the SQL query\n * Uses MD5 to hash the SQL query\n * @param sql - the SQL query to hash\n * @returns - the hash of the SQL query\n */\nexport function hashSQL(sql: string): string {\n  return crypto.createHash(\"md5\").update(sql).digest(\"hex\");\n}\n\n/**\n * Change detector stored on {@link MetricCacheEntry.hash}: md5 over\n * `\"<source>|<lane>\"` — the two config inputs that determine a DESCRIBE —\n * so editing either invalidates the entry.\n */\nexport function metricCacheHash(source: string, lane: string): string {\n  return hashSQL(`${source}|${lane}`);\n}\n\n/**\n * Load the cache from the file system\n * If the cache is not found, run the query explain\n * @returns - the cache\n */\nexport async function loadCache(): Promise<Cache> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  try {\n    await fs.mkdir(CACHE_DIR, { recursive: true });\n\n    const raw = await fs.readFile(cachePath, \"utf8\");\n    const cache = JSON.parse(raw) as Cache;\n    if (cache.version === CACHE_VERSION) {\n      return cache;\n    }\n  } catch (err) {\n    if ((err as NodeJS.ErrnoException).code !== \"ENOENT\") {\n      logger.warn(\"Cache file is corrupted, flushing cache completely.\");\n    }\n  }\n  return { version: CACHE_VERSION, queries: {} };\n}\n\n/**\n * Save the cache to the file system\n * @param cache - cache object to save\n */\nexport async function saveCache(cache: Cache): Promise<void> {\n  const cachePath = path.join(CACHE_DIR, CACHE_FILE);\n  await fs.writeFile(cachePath, JSON.stringify(cache, null, 2), \"utf8\");\n}\n"],"mappings":";;;;;;AAMA,MAAM,SAAS,aAAa,uBAAuB;;;;;;;;;;;;;;;AAsDnD,SAAgB,4BAA4B,OAAyB;AACnE,KAAI,OAAO,UAAU,YAAY,UAAU,KAAM,QAAO;CACxD,MAAM,IAAI;AACV,KAAI,OAAO,EAAE,SAAS,YAAY,OAAO,EAAE,UAAU,UACnD,QAAO;CAET,MAAM,SAAS,EAAE;AACjB,KAAI,OAAO,WAAW,YAAY,WAAW,QAAQ,MAAM,QAAQ,OAAO,CACxE,QAAO;CAET,MAAM,IAAI;CACV,MAAM,iBAAiB,UACrB,MAAM,QAAQ,MAAM,IACpB,MAAM,OACH,QACC,OAAO,QAAQ,YACf,QAAQ,QACR,OAAQ,IAAgC,SAAS,YACjD,OAAQ,IAAgC,SAAS,SACpD;AACH,QACE,OAAO,EAAE,QAAQ,YACjB,OAAO,EAAE,WAAW,aACnB,EAAE,SAAS,QAAQ,EAAE,SAAS,WAC9B,EAAE,aAAa,UAAa,OAAO,EAAE,aAAa,cACnD,cAAc,EAAE,SAAS,IACzB,cAAc,EAAE,WAAW;;AAqB/B,MAAa,gBAAgB;AAC7B,MAAM,aAAa;AACnB,MAAM,YAAY,KAAK,KACrB,QAAQ,KAAK,EACb,gBACA,eACA,SACD;;;;;;;AAQD,SAAgB,QAAQ,KAAqB;AAC3C,QAAO,OAAO,WAAW,MAAM,CAAC,OAAO,IAAI,CAAC,OAAO,MAAM;;;;;;;AAQ3D,SAAgB,gBAAgB,QAAgB,MAAsB;AACpE,QAAO,QAAQ,GAAG,OAAO,GAAG,OAAO;;;;;;;AAQrC,eAAsB,YAA4B;CAChD,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,KAAI;AACF,QAAM,GAAG,MAAM,WAAW,EAAE,WAAW,MAAM,CAAC;EAE9C,MAAM,MAAM,MAAM,GAAG,SAAS,WAAW,OAAO;EAChD,MAAM,QAAQ,KAAK,MAAM,IAAI;AAC7B,MAAI,MAAM,YAAY,cACpB,QAAO;UAEF,KAAK;AACZ,MAAK,IAA8B,SAAS,SAC1C,QAAO,KAAK,sDAAsD;;AAGtE,QAAO;EAAE,SAAS;EAAe,SAAS,EAAE;EAAE;;;;;;AAOhD,eAAsB,UAAU,OAA6B;CAC3D,MAAM,YAAY,KAAK,KAAK,WAAW,WAAW;AAClD,OAAM,GAAG,UAAU,WAAW,KAAK,UAAU,OAAO,MAAM,EAAE,EAAE,OAAO"}

package/dist/type-generator/errors.js

@@ -0,0 +1,100 @@
+//#region src/type-generator/errors.ts
+/**
+* Shared error-introspection utilities for the type generator.
+*
+* Both describe paths — the query registry and the metric-view registry — must
+* classify a thrown failure the same way: a transient connectivity blip (which
+* self-converges and should never fail a build) versus a deterministic failure
+* (auth, bad warehouse id, truncated result, malformed request) that must be
+* surfaced. Keeping `isConnectivityError` (and the message/diagnostic helpers it
+* shares) in one module is the single source of truth for that decision, so the
+* two paths can never drift apart.
+*/
+function isObject(value) {
+	return typeof value === "object" && value !== null;
+}
+function getErrorMessage(error) {
+	if (error instanceof Error) return error.message;
+	if (isObject(error) && typeof error.message === "string") return error.message;
+	return String(error);
+}
+function getErrorDiagnostic(error) {
+	const seen = /* @__PURE__ */ new Set();
+	const messages = [];
+	const stack = [error];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (current === void 0 || seen.has(current)) continue;
+		seen.add(current);
+		const message = getErrorMessage(current);
+		if (message && message !== "[object Object]" && !messages.includes(message)) messages.push(message);
+		const code = getErrorCode(current);
+		if (code && !messages.includes(code)) messages.push(code);
+		stack.push(...getErrorChildren(current));
+	}
+	return messages.length > 0 ? messages.join(": ") : getErrorMessage(error);
+}
+function getErrorCode(error) {
+	if (!isObject(error)) return void 0;
+	const code = error.code ?? error.errno;
+	return typeof code === "string" ? code : void 0;
+}
+function getErrorStatus(error) {
+	if (!isObject(error)) return void 0;
+	const direct = error.status ?? error.statusCode;
+	if (typeof direct === "number") return direct;
+	if (isObject(error.response) && typeof error.response.status === "number") return error.response.status;
+}
+function getErrorChildren(error) {
+	if (!isObject(error)) return [];
+	const children = [];
+	if ("cause" in error) children.push(error.cause);
+	if (error instanceof AggregateError) children.push(...error.errors);
+	return children;
+}
+const CONNECTIVITY_ERROR_CODES = new Set([
+	"ECONNREFUSED",
+	"ECONNRESET",
+	"ENOTFOUND",
+	"ETIMEDOUT",
+	"EAI_AGAIN",
+	"EAI_NODATA",
+	"EAI_NONAME",
+	"EHOSTUNREACH",
+	"ENETUNREACH",
+	"CERT_HAS_EXPIRED",
+	"DEPTH_ZERO_SELF_SIGNED_CERT",
+	"ERR_TLS_CERT_ALTNAME_INVALID",
+	"SELF_SIGNED_CERT_IN_CHAIN",
+	"UNABLE_TO_VERIFY_LEAF_SIGNATURE"
+]);
+function isConnectivityMessage(message) {
+	return /\bconnection (?:refused|reset|timed out)\b/i.test(message) || /\bsocket hang up\b/i.test(message) || /\bnetwork error\b/i.test(message) || /\bcan'?t connect to\b/i.test(message) || /\bcertificate has expired\b/i.test(message) || /\bunable to verify the first certificate\b/i.test(message) || /\bupstream connect error or disconnect\/reset before headers\b/i.test(message);
+}
+/**
+* True when a thrown failure is a transport/connectivity problem (DNS, refused
+* connection, reset, TLS, 502/503/504, undici `UND_ERR_*`) rather than a
+* deterministic error the warehouse returned. Walks `cause`/`AggregateError`
+* chains so a wrapped connectivity error is still recognized. Callers degrade
+* (and retry) on `true`; everything else is surfaced as a build failure.
+*/
+function isConnectivityError(error) {
+	const seen = /* @__PURE__ */ new Set();
+	const stack = [error];
+	while (stack.length > 0) {
+		const current = stack.pop();
+		if (current === void 0 || seen.has(current)) continue;
+		seen.add(current);
+		const code = getErrorCode(current);
+		if (code && (CONNECTIVITY_ERROR_CODES.has(code) || code.startsWith("UND_ERR_"))) return true;
+		const status = getErrorStatus(current);
+		if (status === 502 || status === 503 || status === 504) return true;
+		if (isConnectivityMessage(getErrorMessage(current))) return true;
+		stack.push(...getErrorChildren(current));
+	}
+	return false;
+}
+
+//#endregion
+export { getErrorDiagnostic, getErrorMessage, isConnectivityError };
+//# sourceMappingURL=errors.js.map

package/dist/type-generator/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","names":[],"sources":["../../src/type-generator/errors.ts"],"sourcesContent":["/**\n * Shared error-introspection utilities for the type generator.\n *\n * Both describe paths — the query registry and the metric-view registry — must\n * classify a thrown failure the same way: a transient connectivity blip (which\n * self-converges and should never fail a build) versus a deterministic failure\n * (auth, bad warehouse id, truncated result, malformed request) that must be\n * surfaced. Keeping `isConnectivityError` (and the message/diagnostic helpers it\n * shares) in one module is the single source of truth for that decision, so the\n * two paths can never drift apart.\n */\n\nfunction isObject(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n\nexport function getErrorMessage(error: unknown): string {\n  if (error instanceof Error) return error.message;\n  if (isObject(error) && typeof error.message === \"string\") {\n    return error.message;\n  }\n  return String(error);\n}\n\nexport function getErrorDiagnostic(error: unknown): string {\n  const seen = new Set<unknown>();\n  const messages: string[] = [];\n  const stack = [error];\n\n  while (stack.length > 0) {\n    const current = stack.pop();\n    if (current === undefined || seen.has(current)) continue;\n    seen.add(current);\n\n    const message = getErrorMessage(current);\n    if (\n      message &&\n      message !== \"[object Object]\" &&\n      !messages.includes(message)\n    ) {\n      messages.push(message);\n    }\n\n    const code = getErrorCode(current);\n    if (code && !messages.includes(code)) messages.push(code);\n\n    stack.push(...getErrorChildren(current));\n  }\n\n  return messages.length > 0 ? messages.join(\": \") : getErrorMessage(error);\n}\n\nfunction getErrorCode(error: unknown): string | undefined {\n  if (!isObject(error)) return undefined;\n  const code = error.code ?? error.errno;\n  return typeof code === \"string\" ? code : undefined;\n}\n\nfunction getErrorStatus(error: unknown): number | undefined {\n  if (!isObject(error)) return undefined;\n  const direct = error.status ?? error.statusCode;\n  if (typeof direct === \"number\") return direct;\n  if (isObject(error.response) && typeof error.response.status === \"number\") {\n    return error.response.status;\n  }\n  return undefined;\n}\n\nfunction getErrorChildren(error: unknown): unknown[] {\n  if (!isObject(error)) return [];\n  const children: unknown[] = [];\n  if (\"cause\" in error) children.push(error.cause);\n  if (error instanceof AggregateError) children.push(...error.errors);\n  return children;\n}\n\nconst CONNECTIVITY_ERROR_CODES = new Set([\n  \"ECONNREFUSED\",\n  \"ECONNRESET\",\n  \"ENOTFOUND\",\n  \"ETIMEDOUT\",\n  \"EAI_AGAIN\",\n  \"EAI_NODATA\",\n  \"EAI_NONAME\",\n  \"EHOSTUNREACH\",\n  \"ENETUNREACH\",\n  \"CERT_HAS_EXPIRED\",\n  \"DEPTH_ZERO_SELF_SIGNED_CERT\",\n  \"ERR_TLS_CERT_ALTNAME_INVALID\",\n  \"SELF_SIGNED_CERT_IN_CHAIN\",\n  \"UNABLE_TO_VERIFY_LEAF_SIGNATURE\",\n]);\n\nfunction isConnectivityMessage(message: string): boolean {\n  return (\n    /\\bconnection (?:refused|reset|timed out)\\b/i.test(message) ||\n    /\\bsocket hang up\\b/i.test(message) ||\n    /\\bnetwork error\\b/i.test(message) ||\n    /\\bcan'?t connect to\\b/i.test(message) ||\n    /\\bcertificate has expired\\b/i.test(message) ||\n    /\\bunable to verify the first certificate\\b/i.test(message) ||\n    /\\bupstream connect error or disconnect\\/reset before headers\\b/i.test(\n      message,\n    )\n  );\n}\n\n/**\n * True when a thrown failure is a transport/connectivity problem (DNS, refused\n * connection, reset, TLS, 502/503/504, undici `UND_ERR_*`) rather than a\n * deterministic error the warehouse returned. Walks `cause`/`AggregateError`\n * chains so a wrapped connectivity error is still recognized. Callers degrade\n * (and retry) on `true`; everything else is surfaced as a build failure.\n */\nexport function isConnectivityError(error: unknown): boolean {\n  const seen = new Set<unknown>();\n  const stack = [error];\n\n  while (stack.length > 0) {\n    const current = stack.pop();\n    if (current === undefined || seen.has(current)) continue;\n    seen.add(current);\n\n    const code = getErrorCode(current);\n    if (\n      code &&\n      (CONNECTIVITY_ERROR_CODES.has(code) || code.startsWith(\"UND_ERR_\"))\n    ) {\n      return true;\n    }\n\n    const status = getErrorStatus(current);\n    if (status === 502 || status === 503 || status === 504) return true;\n\n    if (isConnectivityMessage(getErrorMessage(current))) return true;\n\n    stack.push(...getErrorChildren(current));\n  }\n\n  return false;\n}\n"],"mappings":";;;;;;;;;;;;AAYA,SAAS,SAAS,OAAkD;AAClE,QAAO,OAAO,UAAU,YAAY,UAAU;;AAGhD,SAAgB,gBAAgB,OAAwB;AACtD,KAAI,iBAAiB,MAAO,QAAO,MAAM;AACzC,KAAI,SAAS,MAAM,IAAI,OAAO,MAAM,YAAY,SAC9C,QAAO,MAAM;AAEf,QAAO,OAAO,MAAM;;AAGtB,SAAgB,mBAAmB,OAAwB;CACzD,MAAM,uBAAO,IAAI,KAAc;CAC/B,MAAM,WAAqB,EAAE;CAC7B,MAAM,QAAQ,CAAC,MAAM;AAErB,QAAO,MAAM,SAAS,GAAG;EACvB,MAAM,UAAU,MAAM,KAAK;AAC3B,MAAI,YAAY,UAAa,KAAK,IAAI,QAAQ,CAAE;AAChD,OAAK,IAAI,QAAQ;EAEjB,MAAM,UAAU,gBAAgB,QAAQ;AACxC,MACE,WACA,YAAY,qBACZ,CAAC,SAAS,SAAS,QAAQ,CAE3B,UAAS,KAAK,QAAQ;EAGxB,MAAM,OAAO,aAAa,QAAQ;AAClC,MAAI,QAAQ,CAAC,SAAS,SAAS,KAAK,CAAE,UAAS,KAAK,KAAK;AAEzD,QAAM,KAAK,GAAG,iBAAiB,QAAQ,CAAC;;AAG1C,QAAO,SAAS,SAAS,IAAI,SAAS,KAAK,KAAK,GAAG,gBAAgB,MAAM;;AAG3E,SAAS,aAAa,OAAoC;AACxD,KAAI,CAAC,SAAS,MAAM,CAAE,QAAO;CAC7B,MAAM,OAAO,MAAM,QAAQ,MAAM;AACjC,QAAO,OAAO,SAAS,WAAW,OAAO;;AAG3C,SAAS,eAAe,OAAoC;AAC1D,KAAI,CAAC,SAAS,MAAM,CAAE,QAAO;CAC7B,MAAM,SAAS,MAAM,UAAU,MAAM;AACrC,KAAI,OAAO,WAAW,SAAU,QAAO;AACvC,KAAI,SAAS,MAAM,SAAS,IAAI,OAAO,MAAM,SAAS,WAAW,SAC/D,QAAO,MAAM,SAAS;;AAK1B,SAAS,iBAAiB,OAA2B;AACnD,KAAI,CAAC,SAAS,MAAM,CAAE,QAAO,EAAE;CAC/B,MAAM,WAAsB,EAAE;AAC9B,KAAI,WAAW,MAAO,UAAS,KAAK,MAAM,MAAM;AAChD,KAAI,iBAAiB,eAAgB,UAAS,KAAK,GAAG,MAAM,OAAO;AACnE,QAAO;;AAGT,MAAM,2BAA2B,IAAI,IAAI;CACvC;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACD,CAAC;AAEF,SAAS,sBAAsB,SAA0B;AACvD,QACE,8CAA8C,KAAK,QAAQ,IAC3D,sBAAsB,KAAK,QAAQ,IACnC,qBAAqB,KAAK,QAAQ,IAClC,yBAAyB,KAAK,QAAQ,IACtC,+BAA+B,KAAK,QAAQ,IAC5C,8CAA8C,KAAK,QAAQ,IAC3D,kEAAkE,KAChE,QACD;;;;;;;;;AAWL,SAAgB,oBAAoB,OAAyB;CAC3D,MAAM,uBAAO,IAAI,KAAc;CAC/B,MAAM,QAAQ,CAAC,MAAM;AAErB,QAAO,MAAM,SAAS,GAAG;EACvB,MAAM,UAAU,MAAM,KAAK;AAC3B,MAAI,YAAY,UAAa,KAAK,IAAI,QAAQ,CAAE;AAChD,OAAK,IAAI,QAAQ;EAEjB,MAAM,OAAO,aAAa,QAAQ;AAClC,MACE,SACC,yBAAyB,IAAI,KAAK,IAAI,KAAK,WAAW,WAAW,EAElE,QAAO;EAGT,MAAM,SAAS,eAAe,QAAQ;AACtC,MAAI,WAAW,OAAO,WAAW,OAAO,WAAW,IAAK,QAAO;AAE/D,MAAI,sBAAsB,gBAAgB,QAAQ,CAAC,CAAE,QAAO;AAE5D,QAAM,KAAK,GAAG,iBAAiB,QAAQ,CAAC;;AAG1C,QAAO"}

package/dist/type-generator/index.js

@@ -1,7 +1,17 @@
 import { createLogger } from "../logging/logger.js";
+import { isRevivableMetricCacheEntry, loadCache, metricCacheHash, saveCache } from "./cache.js";
+import { getErrorDiagnostic, isConnectivityError } from "./errors.js";
 import { migrateProjectConfig, removeOldGeneratedTypes, resolveProjectRoot } from "./migration.js";
+import { readMetricConfig, resolveMetricConfig } from "./mv-registry/config.js";
+import { createWorkspaceDescribeFetcher } from "./mv-registry/describe.js";
+import { generateMetricsMetadataJson } from "./mv-registry/metadata.js";
+import { generateMetricTypeDeclarations } from "./mv-registry/render-types.js";
+import { emptyMetricSchema, syncMetrics } from "./mv-registry/sync.js";
+import { decidePreflight } from "./preflight.js";
+import { getWarehouseState, startWarehouse, waitUntilRunning } from "./warehouse-status.js";
 import { generateQueriesFromDescribe } from "./query-registry.js";
 import { generateServingTypes as generateServingTypes$1 } from "./serving/generator.js";
+import { WorkspaceClient } from "@databricks/sdk-experimental";
 import pc from "picocolors";
 import fs from "node:fs/promises";
 import path from "node:path";
@@ -10,6 +20,12 @@ import dotenv from "dotenv";
 //#region src/type-generator/index.ts
 dotenv.config();
 const logger = createLogger("type-generator");
+/**
+* Upper bound (~5 min) on how long the metric path's `blocking`-mode preflight
+* waits for a warehouse to reach RUNNING. Mirrors the query path's (unexported)
+* `PREFLIGHT_WAIT_MAX_MS` in query-registry.ts.
+*/
+const MV_PREFLIGHT_WAIT_MAX_MS = 3e5;
 function plural(count, singular, pluralForm = `${singular}s`) {
 	return count === 1 ? singular : pluralForm;
 }
@@ -131,14 +147,59 @@ declare module "@databricks/appkit-ui/react" {
 `;
 }
 /**
+* Status-only probe for the metric-view gate in {@link generateFromEntryPoint}:
+* what state is the warehouse in right now?
+*
+* Uses {@link getWarehouseState} (`warehouses.get`) — a read-only GET that can
+* never start the warehouse — unlike the metric DESCRIBE statements it guards,
+* whose execution auto-starts a stopped warehouse and waits on it.
+*
+* Returns the observed state so the gate can distinguish a transient
+* not-running state (STOPPED/STARTING/... → degraded entries that retry) from a
+* terminal one (DELETED/DELETING → degraded entries pinned sticky). Takes the
+* lazy client *getter* (not a client) so the probe also absorbs client
+* construction failure. A connectivity blip returns `undefined`, which the gate
+* reads as transient not-running; a deterministic failure (auth, bad id) is
+* re-thrown so the gate can classify it fatal rather than silently degrading.
+*/
+async function probeWarehouseState(getClient, warehouseId) {
+	try {
+		return await getWarehouseState(getClient(), warehouseId);
+	} catch (err) {
+		if (isConnectivityError(err)) return void 0;
+		throw err;
+	}
+}
+/**
 * Entry point for generating type declarations from all imported files
 * @param options - the options for the generation
 * @param options.entryPoint - the entry point file
 * @param options.outFile - the output file
-* @param options.querySchemaFile - optional path to query schema file (e.g. config/queries/schema.ts)
+* @param options.noCache - skip the typegen cache entirely: every query is
+*   re-described, and the metric path ignores its cached schemas (every
+*   configured key becomes describe-needed) and overwrites the cache's
+*   `metrics` section with this pass's results.
+* @param options.mode - preflight policy (see {@link PreflightMode}), default
+*   `"non-blocking"`. For queries, `"non-blocking"` never touches the
+*   warehouse. For metric views it makes one status-only probe and DESCRIBEs
+*   only when the warehouse is already RUNNING, otherwise emits permissive
+*   degraded types immediately. `"blocking"` waits for / starts the warehouse
+*   first, failing the build only for a deleted/deleting one.
+* @param options.mvOutFile - optional output file for the MetricRegistry
+*   augmentation. Defaults to a sibling `metric.d.ts` file under the same
+*   directory as `outFile`. Skipped entirely if `metric-views.json` is absent.
+* @param options.mvMetadataOutFile - optional output file for the
+*   build-time semantic metadata JSON bundle (`metrics.metadata.json`).
+*   Defaults to a sibling of `mvOutFile`. Skipped entirely if
+*   `metric-views.json` is absent.
+* @param options.metricFetcher - optional DescribeFetcher used by
+*   {@link syncMetrics} (tests inject a mock; production lazily builds a
+*   default WorkspaceClient-backed one). An injected fetcher always runs: it
+*   hits no warehouse, so it bypasses both the non-blocking gate and the
+*   blocking preflight.
 */
 async function generateFromEntryPoint(options) {
-	const { outFile, queryFolder, warehouseId, noCache, mode = "non-blocking" } = options;
+	const { outFile, queryFolder, warehouseId, noCache, mode = "non-blocking", mvOutFile, mvMetadataOutFile, metricFetcher } = options;
 	const projectRoot = resolveProjectRoot(outFile);
 	logger.debug("Starting type generation...");
 	let queryRegistry = [];
@@ -156,6 +217,121 @@ async function generateFromEntryPoint(options) {
 	const typeDeclarations = generateTypeDeclarations(queryRegistry);
 	await fs.mkdir(path.dirname(outFile), { recursive: true });
 	await fs.writeFile(outFile, typeDeclarations, "utf-8");
+	if (queryFolder) {
+		const mvConfig = await readMetricConfig(queryFolder);
+		if (mvConfig) {
+			const resolution = resolveMetricConfig(mvConfig);
+			const cache = await loadCache();
+			const mvCacheSection = Object.create(null);
+			if (!noCache && cache.metrics) for (const key of Object.keys(cache.metrics)) mvCacheSection[key] = cache.metrics[key];
+			const hitSchemas = /* @__PURE__ */ new Map();
+			const describeNeeded = [];
+			const stickyDegradedHits = [];
+			for (const entry of resolution.entries) {
+				const prior = mvCacheSection[entry.key];
+				if (prior !== void 0 && isRevivableMetricCacheEntry(prior) && prior.hash === metricCacheHash(entry.source, entry.lane) && !prior.retry) {
+					hitSchemas.set(entry.key, prior.schema);
+					if (prior.schema.degraded === true) stickyDegradedHits.push(entry.key);
+				} else describeNeeded.push(entry);
+			}
+			if (stickyDegradedHits.length > 0) logger.warn("cached failure for %s — fix the entry in metric-views.json or run with --no-cache to retry.", stickyDegradedHits.join(", "));
+			let mvClient;
+			const getMvClient = () => {
+				mvClient ??= new WorkspaceClient({});
+				return mvClient;
+			};
+			let preflightFatalMessage;
+			if (mode === "blocking" && metricFetcher === void 0 && describeNeeded.length > 0) try {
+				const state = await getWarehouseState(getMvClient(), warehouseId);
+				const decision = decidePreflight(state, mode);
+				if (decision === "fatal") preflightFatalMessage = `warehouse ${warehouseId} is ${state}`;
+				else if (decision === "startWaitProceed") {
+					await startWarehouse(getMvClient(), warehouseId);
+					const settled = await waitUntilRunning(getMvClient(), warehouseId, {
+						maxMs: MV_PREFLIGHT_WAIT_MAX_MS,
+						treatStoppedAsTransient: true
+					});
+					if (settled !== "RUNNING") preflightFatalMessage = `warehouse ${warehouseId} is ${settled}`;
+				} else if (decision === "waitThenProceed") {
+					const settled = await waitUntilRunning(getMvClient(), warehouseId, { maxMs: MV_PREFLIGHT_WAIT_MAX_MS });
+					if (settled === "DELETED" || settled === "DELETING") preflightFatalMessage = `warehouse ${warehouseId} is ${settled}`;
+				}
+			} catch (err) {
+				if (!isConnectivityError(err)) preflightFatalMessage = `warehouse ${warehouseId}: ${getErrorDiagnostic(err)}`;
+			}
+			let gateState;
+			let describeNow = metricFetcher !== void 0 || mode !== "non-blocking" || describeNeeded.length === 0;
+			if (!describeNow) {
+				try {
+					gateState = await probeWarehouseState(getMvClient, warehouseId);
+				} catch (err) {
+					preflightFatalMessage = `warehouse ${warehouseId}: ${getErrorDiagnostic(err)}`;
+				}
+				describeNow = gateState === "RUNNING";
+			}
+			let described;
+			let failures = [];
+			let terminalSkip = false;
+			if (preflightFatalMessage !== void 0) {
+				described = describeNeeded.map(emptyMetricSchema);
+				terminalSkip = true;
+				for (const entry of describeNeeded) fatalErrors.push({
+					name: entry.key,
+					message: preflightFatalMessage
+				});
+			} else if (describeNeeded.length === 0) described = [];
+			else if (describeNow) {
+				const fetcher = metricFetcher ?? createWorkspaceDescribeFetcher(getMvClient(), warehouseId);
+				({schemas: described, failures} = await syncMetrics({ entries: describeNeeded }, fetcher));
+				if (failures.length > 0) for (const f of failures) logger.warn("metric sync failed for %s (%s): %s", f.key, f.source, f.reason);
+				const failedKeys = new Set(failures.map((f) => f.key));
+				const degradedKeys = described.filter((s) => s.degraded && !failedKeys.has(s.key)).map((s) => s.key);
+				if (degradedKeys.length > 0) logger.info("Warehouse %s did not return schemas for %d metric view(s) (%s) — wrote degraded metric types (permissive); they will refresh once the warehouse is available.", warehouseId, degradedKeys.length, degradedKeys.join(", "));
+			} else {
+				described = describeNeeded.map(emptyMetricSchema);
+				terminalSkip = gateState === "DELETED" || gateState === "DELETING";
+				logger.info("Warehouse %s is not running — wrote degraded metric types (permissive) for %d metric view(s) (%s); they will refresh once the warehouse is available.", warehouseId, describeNeeded.length, describeNeeded.map((e) => e.key).join(", "));
+			}
+			const failureByKey = /* @__PURE__ */ new Map();
+			for (const failure of failures) failureByKey.set(failure.key, failure);
+			for (let i = 0; i < describeNeeded.length; i++) {
+				const entry = describeNeeded[i];
+				const failure = failureByKey.get(entry.key);
+				mvCacheSection[entry.key] = {
+					hash: metricCacheHash(entry.source, entry.lane),
+					schema: described[i],
+					retry: described[i].degraded === true && !terminalSkip && (failure === void 0 || failure.transient === true)
+				};
+			}
+			const configuredKeys = new Set(resolution.entries.map((e) => e.key));
+			let prunedCount = 0;
+			for (const key of Object.keys(mvCacheSection)) if (!configuredKeys.has(key)) {
+				delete mvCacheSection[key];
+				prunedCount++;
+			}
+			if (describeNeeded.length > 0 || noCache || prunedCount > 0) {
+				cache.metrics = mvCacheSection;
+				await saveCache(cache);
+			}
+			const describedByKey = /* @__PURE__ */ new Map();
+			for (const schema of described) describedByKey.set(schema.key, schema);
+			const mvSchemas = resolution.entries.map((entry) => {
+				const schema = hitSchemas.get(entry.key) ?? describedByKey.get(entry.key);
+				if (schema !== void 0) return schema;
+				logger.warn("no schema resolved for metric key %s — emitting degraded types (should not happen)", entry.key);
+				return emptyMetricSchema(entry);
+			});
+			const mvFile = mvOutFile ?? path.join(path.dirname(outFile), METRIC_TYPES_FILE);
+			const mvDeclarations = generateMetricTypeDeclarations(mvSchemas);
+			await fs.mkdir(path.dirname(mvFile), { recursive: true });
+			await fs.writeFile(mvFile, mvDeclarations, "utf-8");
+			const mvMetadataFile = mvMetadataOutFile ?? path.join(path.dirname(mvFile), METRIC_METADATA_FILE);
+			const metadataJson = generateMetricsMetadataJson(mvSchemas);
+			await fs.mkdir(path.dirname(mvMetadataFile), { recursive: true });
+			await fs.writeFile(mvMetadataFile, metadataJson, "utf-8");
+			logger.debug("Wrote MetricRegistry augmentation + metadata bundle for %d metric(s)%s", mvSchemas.length, failures.length > 0 ? ` (${failures.length} failure(s))` : "");
+		}
+	}
 	await removeOldGeneratedTypes(projectRoot, "appKitTypes.d.ts");
 	await migrateProjectConfig(projectRoot);
 	if (syntaxErrors.length > 0) throw new TypegenSyntaxError(syntaxErrors, warehouseId, fatalErrors);
@@ -169,6 +345,18 @@ const TYPES_DIR = "appkit-types";
 const ANALYTICS_TYPES_FILE = "analytics.d.ts";
 /** Default filename for serving endpoint type declarations. */
 const SERVING_TYPES_FILE = "serving.d.ts";
+/** Default filename for metric-view registry type declarations. */
+const METRIC_TYPES_FILE = "metric.d.ts";
+/**
+* Default filename for the build-time semantic-metadata JSON bundle, sibling of
+* {@link METRIC_TYPES_FILE}. Shape is `Record<metricKey, { measures,
+* dimensions }>` (UC FQN and execution lane are server-side concerns, kept out
+* of this client-shipped artifact). The consuming app imports it at build time
+* and registers it via `@databricks/appkit-ui/format`'s
+* `registerMetricsMetadata()`, so the React hook returns per-metric `metadata`
+* without a second network round-trip.
+*/
+const METRIC_METADATA_FILE = "metrics.metadata.json";
 
 //#endregion
 export { ANALYTICS_TYPES_FILE, SERVING_TYPES_FILE, TYPES_DIR, TypegenFatalError, TypegenSyntaxError, generateFromEntryPoint, generateServingTypes };