@malloy-publisher/server 0.9.12 → 0.9.14

package/dist/server.mjs

@@ -205316,6 +205316,8 @@ function internalErrorToHttpError(error2, { log = true, onLogged } = {}) {
     return httpError(404, error2.message, "TABLE_NOT_FOUND");
   } else if (error2 instanceof ConnectionNotFoundError) {
     return httpError(404, error2.message);
+  } else if (error2 instanceof StorageDestinationNotFoundError) {
+    return httpError(404, error2.message);
   } else if (error2 instanceof DestinationNotFoundError) {
     return httpError(422, error2.message);
   } else if (error2 instanceof ConnectionAuthError) {
@@ -205383,7 +205385,7 @@ function toQueryTextProblem(problem) {
     ...problem.at ? { at: { range: problem.at.range } } : {}
   };
 }
-var GENERIC_INTERNAL_MESSAGE = "Internal server error.", GENERIC_UPSTREAM_MESSAGE = "Upstream connection error.", GENERIC_UNREACHABLE_MESSAGE = "The database connection is down: the database could not be reached, so the query did not run.", GENERIC_AUTH_MESSAGE = "The database rejected the connection's credentials. Check the connection's user, password, key or token.", MAX_LOGGED_DETAIL_CHARS = 2000, FILESYSTEM_ACCESS_DESCRIPTIONS, NODE_CONNECTION_CODES, POSTGRES_CONNECTION_SQLSTATE, CODELESS_CONNECTION_MESSAGES, MYSQL_CONFIG_CODES, SQLSERVER_CONNECTION_CODES, TLS_VERIFICATION_CODES, POSTGRES_AUTH_SQLSTATE, MYSQL_AUTH_CODES, SQLSERVER_AUTH_CODES, SNOWFLAKE_AUTH_CODES, POSTGRES_STATEMENT_SQLSTATES, POSTGRES_UNDEFINED_TABLE = "42P01", POSTGRES_RELATION_MISSING, NotImplementedError, BadRequestError, InvalidArgumentError, CompileRefusedError, InvalidModelPathError, RenderTagRefusedError, UnparseableTextError, EnvironmentNotFoundError, PackageNotFoundError, ModelNotFoundError, DashboardNotFoundError, SkillNotFoundError, AgentNotFoundError, ConflictError, ConnectionNotFoundError, TableNotFoundError, ConnectionError, ConnectionFailedError, UnconfiguredConnectionError, ConnectionPoolExhaustedError, DestinationNotFoundError, ConnectionAuthError, UnsupportedCatalogFormatError, ModelCompilationError, PackageManifestError, MaterializationEligibilityError, ChainedUpstreamMissingError, ChainedShapeNotCarriedError, PublisherConfigError, ServerConfigurationError, FrozenConfigError, AccessDeniedError, QueryCompileError, NotQueryableError, OffSurfaceError, MaterializationNotFoundError, MaterializationConflictError, WriteConflictError, WriteRolledBackError, WriteRollbackFailedError, WriteVerifyError, InvalidStateTransitionError, ServiceUnavailableError, PackageAdmissionRefusedError, PayloadTooLargeError, ResponseUnserializableError, QueryTimeoutError;
+var GENERIC_INTERNAL_MESSAGE = "Internal server error.", GENERIC_UPSTREAM_MESSAGE = "Upstream connection error.", GENERIC_UNREACHABLE_MESSAGE = "The database connection is down: the database could not be reached, so the query did not run.", GENERIC_AUTH_MESSAGE = "The database rejected the connection's credentials. Check the connection's user, password, key or token.", MAX_LOGGED_DETAIL_CHARS = 2000, FILESYSTEM_ACCESS_DESCRIPTIONS, NODE_CONNECTION_CODES, POSTGRES_CONNECTION_SQLSTATE, CODELESS_CONNECTION_MESSAGES, MYSQL_CONFIG_CODES, SQLSERVER_CONNECTION_CODES, TLS_VERIFICATION_CODES, POSTGRES_AUTH_SQLSTATE, MYSQL_AUTH_CODES, SQLSERVER_AUTH_CODES, SNOWFLAKE_AUTH_CODES, POSTGRES_STATEMENT_SQLSTATES, POSTGRES_UNDEFINED_TABLE = "42P01", POSTGRES_RELATION_MISSING, NotImplementedError, BadRequestError, InvalidArgumentError, CompileRefusedError, InvalidModelPathError, RenderTagRefusedError, UnparseableTextError, EnvironmentNotFoundError, PackageNotFoundError, ModelNotFoundError, DashboardNotFoundError, SkillNotFoundError, AgentNotFoundError, ConflictError, ConnectionNotFoundError, TableNotFoundError, ConnectionError, ConnectionFailedError, UnconfiguredConnectionError, ConnectionPoolExhaustedError, DestinationNotFoundError, StorageDestinationNotFoundError, ConnectionAuthError, UnsupportedCatalogFormatError, ModelCompilationError, PackageManifestError, MaterializationEligibilityError, ChainedUpstreamMissingError, ChainedShapeNotCarriedError, PublisherConfigError, ServerConfigurationError, FrozenConfigError, AccessDeniedError, QueryCompileError, NotQueryableError, OffSurfaceError, MaterializationNotFoundError, MaterializationConflictError, WriteConflictError, WriteRolledBackError, WriteRollbackFailedError, WriteVerifyError, InvalidStateTransitionError, ServiceUnavailableError, PackageAdmissionRefusedError, PayloadTooLargeError, ResponseUnserializableError, QueryTimeoutError;
 var init_errors = __esm(() => {
   init_constants();
   init_logger();
@@ -205557,6 +205559,11 @@ var init_errors = __esm(() => {
       super(message);
     }
   };
+  StorageDestinationNotFoundError = class StorageDestinationNotFoundError extends Error {
+    constructor(message) {
+      super(message);
+    }
+  };
   ConnectionAuthError = class ConnectionAuthError extends Error {
     constructor(message) {
       super(message);
@@ -315102,7 +315109,7 @@ var require_code = __commonJS((exports) => {
   }
   exports._ = _3;
   var plus = new _Code("+");
-  function str(strs, ...args) {
+  function str3(strs, ...args) {
     const expr = [safeStringify(strs[0])];
     let i2 = 0;
     while (i2 < args.length) {
@@ -315113,7 +315120,7 @@ var require_code = __commonJS((exports) => {
     optimize(expr);
     return new _Code(expr);
   }
-  exports.str = str;
+  exports.str = str3;
   function addCodeArg(code, arg) {
     if (arg instanceof _Code)
       code.push(...arg._items);
@@ -315156,7 +315163,7 @@ var require_code = __commonJS((exports) => {
     return;
   }
   function strConcat(c1, c22) {
-    return c22.emptyStr() ? c1 : c1.emptyStr() ? c22 : str`${c1}${c22}`;
+    return c22.emptyStr() ? c1 : c1.emptyStr() ? c22 : str3`${c1}${c22}`;
   }
   exports.strConcat = strConcat;
   function interpolate(x4) {
@@ -316106,22 +316113,22 @@ var require_util11 = __commonJS((exports) => {
     return (0, codegen_1._)`${topSchemaRef}${schemaPath}${(0, codegen_1.getProperty)(keyword)}`;
   }
   exports.schemaRefOrVal = schemaRefOrVal;
-  function unescapeFragment(str) {
-    return unescapeJsonPointer(decodeURIComponent(str));
+  function unescapeFragment(str3) {
+    return unescapeJsonPointer(decodeURIComponent(str3));
   }
   exports.unescapeFragment = unescapeFragment;
-  function escapeFragment(str) {
-    return encodeURIComponent(escapeJsonPointer(str));
+  function escapeFragment(str3) {
+    return encodeURIComponent(escapeJsonPointer(str3));
   }
   exports.escapeFragment = escapeFragment;
-  function escapeJsonPointer(str) {
-    if (typeof str == "number")
-      return `${str}`;
-    return str.replace(/~/g, "~0").replace(/\//g, "~1");
+  function escapeJsonPointer(str3) {
+    if (typeof str3 == "number")
+      return `${str3}`;
+    return str3.replace(/~/g, "~0").replace(/\//g, "~1");
   }
   exports.escapeJsonPointer = escapeJsonPointer;
-  function unescapeJsonPointer(str) {
-    return str.replace(/~1/g, "/").replace(/~0/g, "~");
+  function unescapeJsonPointer(str3) {
+    return str3.replace(/~1/g, "/").replace(/~0/g, "~");
   }
   exports.unescapeJsonPointer = unescapeJsonPointer;
   function eachItem(xs2, f5) {
@@ -317105,8 +317112,8 @@ var require_json_schema_traverse = __commonJS((exports, module) => {
       post(schema, jsonPtr, rootSchema, parentJsonPtr, parentKeyword, parentSchema, keyIndex);
     }
   }
-  function escapeJsonPtr(str) {
-    return str.replace(/~/g, "~0").replace(/\//g, "~1");
+  function escapeJsonPtr(str3) {
+    return str3.replace(/~/g, "~0").replace(/\//g, "~1");
   }
 });
 
@@ -318202,16 +318209,16 @@ var require_utils96 = __commonJS((exports, module) => {
       isIPV6: true
     };
   }
-  function findToken(str, token) {
+  function findToken(str3, token) {
     let ind = 0;
-    for (let i2 = 0;i2 < str.length; i2++) {
-      if (str[i2] === token)
+    for (let i2 = 0;i2 < str3.length; i2++) {
+      if (str3[i2] === token)
         ind++;
     }
     return ind;
   }
-  function removeDotSegments(path20) {
-    let input = path20;
+  function removeDotSegments(path21) {
+    let input = path21;
     const output = [];
     let nextSlash = -1;
     let len = 0;
@@ -318611,8 +318618,8 @@ var require_schemes = __commonJS((exports, module) => {
     }
     if (wsComponent.resourceName) {
       const queryIndex = wsComponent.resourceName.indexOf("?");
-      const path20 = queryIndex === -1 ? wsComponent.resourceName : wsComponent.resourceName.slice(0, queryIndex);
-      wsComponent.path = path20 && path20 !== "/" ? path20 : undefined;
+      const path21 = queryIndex === -1 ? wsComponent.resourceName : wsComponent.resourceName.slice(0, queryIndex);
+      wsComponent.path = path21 && path21 !== "/" ? path21 : undefined;
       wsComponent.query = queryIndex === -1 ? undefined : wsComponent.resourceName.slice(queryIndex + 1);
       wsComponent.resourceName = undefined;
     }
@@ -319175,7 +319182,7 @@ var require_core = __commonJS((exports) => {
   var util_1 = require_util11();
   var $dataRefSchema = require_data();
   var uri_1 = require_uri2();
-  var defaultRegExp = (str, flags) => new RegExp(str, flags);
+  var defaultRegExp = (str3, flags) => new RegExp(str3, flags);
   defaultRegExp.code = "new RegExp";
   var META_IGNORE_OPTIONS = ["removeAdditional", "useDefaults", "coerceTypes"];
   var EXT_SCOPE_NAMES = new Set([
@@ -319937,16 +319944,16 @@ var require_multipleOf = __commonJS((exports) => {
 // ../../node_modules/@modelcontextprotocol/sdk/node_modules/ajv/dist/runtime/ucs2length.js
 var require_ucs2length = __commonJS((exports) => {
   Object.defineProperty(exports, "__esModule", { value: true });
-  function ucs2length(str) {
-    const len = str.length;
+  function ucs2length(str3) {
+    const len = str3.length;
     let length = 0;
     let pos = 0;
     let value;
     while (pos < len) {
       length++;
-      value = str.charCodeAt(pos++);
+      value = str3.charCodeAt(pos++);
       if (value >= 55296 && value <= 56319 && pos < len) {
-        value = str.charCodeAt(pos);
+        value = str3.charCodeAt(pos);
         if ((value & 64512) === 56320)
           pos++;
       }
@@ -321678,8 +321685,8 @@ var require_formats2 = __commonJS((exports) => {
   }
   var DATE = /^(\d\d\d\d)-(\d\d)-(\d\d)$/;
   var DAYS = [0, 31, 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31];
-  function date4(str) {
-    const matches = DATE.exec(str);
+  function date4(str3) {
+    const matches = DATE.exec(str3);
     if (!matches)
       return false;
     const year = +matches[1];
@@ -321698,8 +321705,8 @@ var require_formats2 = __commonJS((exports) => {
   }
   var TIME = /^(\d\d):(\d\d):(\d\d(?:\.\d+)?)(z|([+-])(\d\d)(?::?(\d\d))?)?$/i;
   function getTime(strictTimeZone) {
-    return function time3(str) {
-      const matches = TIME.exec(str);
+    return function time3(str3) {
+      const matches = TIME.exec(str3);
       if (!matches)
         return false;
       const hr2 = +matches[1];
@@ -321745,8 +321752,8 @@ var require_formats2 = __commonJS((exports) => {
   var DATE_TIME_SEPARATOR = /t|\s/i;
   function getDateTime(strictTimeZone) {
     const time3 = getTime(strictTimeZone);
-    return function date_time(str) {
-      const dateTime = str.split(DATE_TIME_SEPARATOR);
+    return function date_time(str3) {
+      const dateTime = str3.split(DATE_TIME_SEPARATOR);
       return dateTime.length === 2 && date4(dateTime[0]) && time3(dateTime[1]);
     };
   }
@@ -321771,13 +321778,13 @@ var require_formats2 = __commonJS((exports) => {
   }
   var NOT_URI_FRAGMENT = /\/|:/;
   var URI = /^(?:[a-z][a-z0-9+\-.]*:)(?:\/?\/(?:(?:[a-z0-9\-._~!$&'()*+,;=:]|%[0-9a-f]{2})*@)?(?:\[(?:(?:(?:(?:[0-9a-f]{1,4}:){6}|::(?:[0-9a-f]{1,4}:){5}|(?:[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){4}|(?:(?:[0-9a-f]{1,4}:){0,1}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){3}|(?:(?:[0-9a-f]{1,4}:){0,2}[0-9a-f]{1,4})?::(?:[0-9a-f]{1,4}:){2}|(?:(?:[0-9a-f]{1,4}:){0,3}[0-9a-f]{1,4})?::[0-9a-f]{1,4}:|(?:(?:[0-9a-f]{1,4}:){0,4}[0-9a-f]{1,4})?::)(?:[0-9a-f]{1,4}:[0-9a-f]{1,4}|(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?))|(?:(?:[0-9a-f]{1,4}:){0,5}[0-9a-f]{1,4})?::[0-9a-f]{1,4}|(?:(?:[0-9a-f]{1,4}:){0,6}[0-9a-f]{1,4})?::)|[Vv][0-9a-f]+\.[a-z0-9\-._~!$&'()*+,;=:]+)\]|(?:(?:25[0-5]|2[0-4]\d|[01]?\d\d?)\.){3}(?:25[0-5]|2[0-4]\d|[01]?\d\d?)|(?:[a-z0-9\-._~!$&'()*+,;=]|%[0-9a-f]{2})*)(?::\d*)?(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*|\/(?:(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)?|(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})+(?:\/(?:[a-z0-9\-._~!$&'()*+,;=:@]|%[0-9a-f]{2})*)*)(?:\?(?:[a-z0-9\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?(?:#(?:[a-z0-9\-._~!$&'()*+,;=:@/?]|%[0-9a-f]{2})*)?$/i;
-  function uri(str) {
-    return NOT_URI_FRAGMENT.test(str) && URI.test(str);
+  function uri(str3) {
+    return NOT_URI_FRAGMENT.test(str3) && URI.test(str3);
   }
   var BYTE = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/gm;
-  function byte(str) {
+  function byte(str3) {
     BYTE.lastIndex = 0;
-    return BYTE.test(str);
+    return BYTE.test(str3);
   }
   var MIN_INT32 = -(2 ** 31);
   var MAX_INT32 = 2 ** 31 - 1;
@@ -321791,11 +321798,11 @@ var require_formats2 = __commonJS((exports) => {
     return true;
   }
   var Z_ANCHOR = /[^\\]\\Z/;
-  function regex(str) {
-    if (Z_ANCHOR.test(str))
+  function regex(str3) {
+    if (Z_ANCHOR.test(str3))
       return false;
     try {
-      new RegExp(str);
+      new RegExp(str3);
       return true;
     } catch (e2) {
       return false;
@@ -321872,7 +321879,7 @@ var require_code3 = __commonJS((exports) => {
   }
   exports._ = _3;
   var plus = new _Code("+");
-  function str(strs, ...args) {
+  function str3(strs, ...args) {
     const expr = [safeStringify(strs[0])];
     let i2 = 0;
     while (i2 < args.length) {
@@ -321883,7 +321890,7 @@ var require_code3 = __commonJS((exports) => {
     optimize(expr);
     return new _Code(expr);
   }
-  exports.str = str;
+  exports.str = str3;
   function addCodeArg(code, arg) {
     if (arg instanceof _Code)
       code.push(...arg._items);
@@ -321926,7 +321933,7 @@ var require_code3 = __commonJS((exports) => {
     return;
   }
   function strConcat(c1, c22) {
-    return c22.emptyStr() ? c1 : c1.emptyStr() ? c22 : str`${c1}${c22}`;
+    return c22.emptyStr() ? c1 : c1.emptyStr() ? c22 : str3`${c1}${c22}`;
   }
   exports.strConcat = strConcat;
   function interpolate(x4) {
@@ -322876,22 +322883,22 @@ var require_util12 = __commonJS((exports) => {
     return (0, codegen_1._)`${topSchemaRef}${schemaPath}${(0, codegen_1.getProperty)(keyword)}`;
   }
   exports.schemaRefOrVal = schemaRefOrVal;
-  function unescapeFragment(str) {
-    return unescapeJsonPointer(decodeURIComponent(str));
+  function unescapeFragment(str3) {
+    return unescapeJsonPointer(decodeURIComponent(str3));
   }
   exports.unescapeFragment = unescapeFragment;
-  function escapeFragment(str) {
-    return encodeURIComponent(escapeJsonPointer(str));
+  function escapeFragment(str3) {
+    return encodeURIComponent(escapeJsonPointer(str3));
   }
   exports.escapeFragment = escapeFragment;
-  function escapeJsonPointer(str) {
-    if (typeof str == "number")
-      return `${str}`;
-    return str.replace(/~/g, "~0").replace(/\//g, "~1");
+  function escapeJsonPointer(str3) {
+    if (typeof str3 == "number")
+      return `${str3}`;
+    return str3.replace(/~/g, "~0").replace(/\//g, "~1");
   }
   exports.escapeJsonPointer = escapeJsonPointer;
-  function unescapeJsonPointer(str) {
-    return str.replace(/~1/g, "/").replace(/~0/g, "~");
+  function unescapeJsonPointer(str3) {
+    return str3.replace(/~1/g, "/").replace(/~0/g, "~");
   }
   exports.unescapeJsonPointer = unescapeJsonPointer;
   function eachItem(xs2, f5) {
@@ -324725,7 +324732,7 @@ var require_core3 = __commonJS((exports) => {
   var util_1 = require_util12();
   var $dataRefSchema = require_data2();
   var uri_1 = require_uri3();
-  var defaultRegExp = (str, flags) => new RegExp(str, flags);
+  var defaultRegExp = (str3, flags) => new RegExp(str3, flags);
   defaultRegExp.code = "new RegExp";
   var META_IGNORE_OPTIONS = ["removeAdditional", "useDefaults", "coerceTypes"];
   var EXT_SCOPE_NAMES = new Set([
@@ -325487,16 +325494,16 @@ var require_multipleOf2 = __commonJS((exports) => {
 // ../../node_modules/ajv-formats/node_modules/ajv/dist/runtime/ucs2length.js
 var require_ucs2length2 = __commonJS((exports) => {
   Object.defineProperty(exports, "__esModule", { value: true });
-  function ucs2length(str) {
-    const len = str.length;
+  function ucs2length(str3) {
+    const len = str3.length;
     let length = 0;
     let pos = 0;
     let value;
     while (pos < len) {
       length++;
-      value = str.charCodeAt(pos++);
+      value = str3.charCodeAt(pos++);
       if (value >= 55296 && value <= 56319 && pos < len) {
-        value = str.charCodeAt(pos);
+        value = str3.charCodeAt(pos);
         if ((value & 64512) === 56320)
           pos++;
       }
@@ -346494,6 +346501,9 @@ async function attachDuckLake(connection, dbName, ducklakeConfig) {
     readOnly: true
   });
 }
+async function attachDuckLakeReadOnly(connection, dbName, ducklakeConfig) {
+  await attachDuckLake(connection, dbName, ducklakeConfig);
+}
 async function attachDuckLakeReadWrite(connection, dbName, ducklakeConfig) {
   await attachDuckLakeWithMode(connection, dbName, ducklakeConfig, {
     readOnly: false
@@ -355750,7 +355760,7 @@ The agent orchestrates these. Each query and chart step hands off to a focused s
 2. READ THE MODEL. Get the model's real source and view names, through your environment's context tool if it has one, or by opening the \`.malloy\` file directly. Never guess field or view names.
 3. SCAFFOLD the package (template below).
 4. WRITE THE QUERIES. Read \`reference/runtime.md\`. Validate each before pasting it into the page, using whatever query tool your environment provides or a running Publisher (see \`reference/runtime.md\`). Malloy syntax questions go to \`skill:malloy-queries\`.
-5. CHOOSE CHARTS with \`skill:malloy-charts\` when rendering through \`<malloy-render>\`; otherwise it is your own chart library drawing the returned rows. Vendor any chart library into \`public/\` and load it locally, not from a CDN. Two reasons: embedded author JavaScript runs with the viewing user's data authority, and a blocked CDN (agent sandboxes and many corporate networks block them) is easy to miss, because the script never runs and the charts come up empty. The \`storefront\` example ships its chart library in \`public/vendor/\` and loads it from \`public/index.html\` as \`./vendor/chart.umd.js\`. Copy that, but resolve the path against the page's own directory: a page in a subdirectory (\`public/reports/index.html\`) needs \`../vendor/chart.umd.js\`. A wrong relative path 404s and leaves the charts blank, which is the failure you are trying to avoid.
+5. CHOOSE CHARTS with \`skill:malloy-charts\` when rendering through \`<malloy-render>\`; otherwise it is your own chart library drawing the returned rows. Vendor any chart library into \`public/\` and load it locally, not from a CDN. Two reasons: embedded author JavaScript runs with the viewing user's data authority, and a blocked CDN (agent sandboxes and many corporate networks block them) is easy to miss, because the script never runs and the charts come up empty. The \`storefront\` example ships its chart library in \`public/vendor/\` and loads it from \`public/index.html\` as \`./vendor/chart.umd.js\`. Copy its vendoring, not its loading (it uses a plain \`<script>\`, which the next sentences rule out), and resolve the path against the page's own directory: a page in a subdirectory (\`public/reports/index.html\`) needs \`../vendor/chart.umd.js\`. A wrong relative path 404s and leaves the charts blank, which is the failure you are trying to avoid. Load it off the critical path (\`<link rel="preload">\`, then injected on the first chart), not as a plain \`<script>\` ahead of the app: it is usually most of the page's weight and would hold every query until it has parsed (\`reference/performance.md\`).
 6. EMBED (optional). Read \`reference/embedding.md\`.
 7. PREVIEW with the local authoring loop (below).
 8. VERIFY before you call it done (see "What 'done' means" below). This step is not optional.
@@ -355770,6 +355780,9 @@ A data app you can defend has all of these. Build to this list, not to the scaff
 - **Visible assumptions.** When you assume something (two sources joined by month, an in-month proxy that differs from a certified definition) or a metric is incomplete, say so *in the app*: a caption, a footnote, a placeholder card with the reason. The non-technical user cannot see your reasoning; bury a caveat and you have misled them. Don't silently drop a metric you couldn't model. Show a placeholder that names what's missing and why.
 - **Built to the design brief, not to the model's shape.** The app matches the archetype, forms, and depth plan from step 1 (\`reference/design.md\`), carries a real token contract (surfaces, text ramp, semantic colors, a categorical chart palette) that the chart code reads at runtime rather than hardcoding, and puts visible weight on the two or three numbers that lead. A uniform grid of same-size cards, or a tile per view, means the brief was skipped.
 - **Vendored libraries.** Chart and helper libraries live in \`public/\`, loaded locally (step 5).
+- **Light, and nothing waits on the chart library.** Pages that draw charts preload the library and load it on first use; a page that draws none never loads it. Trim it to the series types the app draws once it is big enough to matter, and verify a trimmed build by reading pixels, because a missing type draws an empty box without an error. One query text per resource, so any cache or prefetch actually hits. (\`reference/performance.md\`, which also has two opt-in recipes, answering from the last visit and starting a drawer's queries on intent, each with the conditions it needs.)
+- **Holds still while it loads.** Script-filled blocks reserve their final size in the HTML, skeletons are sized from what is coming, settled tile heights are remembered for the next visit, and a tile re-running for a new filter keeps its last answer dimmed instead of collapsing. Target: layout shift under 0.1 on a first visit and 0 on a repeat, embedded as well as standalone. (\`reference/performance.md\`.)
+- **Works embedded.** Inside an auto-sized frame there is no viewport: the frame never scrolls, nothing extends past the content, and anything that floats (a drawer, a tray) is placed over the slice of the page the reader can see, keeps its scroll to itself, and returns the reader exactly where they were. A drawer built the standalone way opens at the top of the document and drags the host page up to meet it. (\`reference/embedding.md\`, \`reference/overlays.md\`.)
 - **Lazy-load below the fold, once the page has more than about eight query-backed tiles.** ("Many" is not decidable; that is the threshold.) Tiles sitting below the fold is *why* the technique works, not a second trigger for it - almost every real data app scrolls, so reading it as one makes the rule "always" and contradicts the count. Under that threshold, firing every tile at once is cheaper than the machinery. Don't fire every tile's query on load. \`reference/lazy-load.md\` is the recipe: \`IntersectionObserver\` (rootMargin ~240px) + a small concurrency cap + reserve each tile's height so lazy tiles don't reflow. Includes the verification trap - on a short/tall-default viewport all tiles intersect at once and you get a false "everything deferred" pass, so test on a deliberately small viewport.
 
 ### Verify before you call it done
@@ -355778,6 +355791,7 @@ You are building for someone who cannot tell a correct dashboard from a broken o
 
 - **Validate every query against the model before wiring it in** (step 4): confirm it compiles and that the column names match what your render code reads.
 - **Load the finished page and confirm every tile shows real numbers**: not stuck on "Loading…", not an error, not an empty state you didn't intend. In a headless browser, wait on \`load\` plus a content selector, not network idle (\`publisher.js\` holds an SSE stream open; see \`reference/runtime.md\`). Don't hand-roll this each time - \`reference/verification-harness.md\` is a copy-adaptable recipe: a mock \`sdk/publisher.js\` returning canned rows keyed by \`(model, query)\`, a \`python3 -m http.server\` webroot, and Playwright assertions (KPIs non-null, no \`.is-error\`, no stuck \`.kit-skeleton\`, a chart/table present). It also documents the false-"stuck skeleton" trap (assert after the mock's async delay, never on \`networkidle\`).
+- **Check it embedded, for stability, and through its drawers.** Load each page inside the Publisher console (\`/<env>/<package>/data-apps/<path>\`) as well as on its own, measure layout shift on a first and a repeat visit, confirm the app never scrolls inside its frame, and open a drawer from well down the page after scrolling the host with real wheel events: the page behind must not move, the drawer must span exactly the visible area, and its scroll must stay in it. \`reference/verification-harness.md\` section 4 has the checks. A tile check alone passed on a build where every one of these was broken.
 - **Unit-test any non-trivial pure logic** (a month-join, a de-cumulation, a unit conversion). Keep that logic in DOM-free helpers so \`node --test\` can cover it, and run it.
 
 ## Minimal scaffold
@@ -355882,7 +355896,7 @@ Publishing an app is publishing its package: get the package into publishable sh
 
 This skill's \`reference/\` files are served as separate prompts, one per file, fetched only when you ask for them. Where the text above says to read \`reference/<name>.md\`, get the prompt named \`malloy-html-data-apps/<name>\` instead.
 
-Available: archetypes, depth-patterns, design, embedding, lazy-load, runtime, token-contract, verification-harness, visual-craft.`
+Available: archetypes, depth-patterns, design, embedding, lazy-load, overlays, performance, runtime, token-contract, verification-harness, visual-craft.`
     },
     {
       name: "malloy-html-data-apps/archetypes",
@@ -356064,7 +356078,7 @@ Write down that you did this and why. A reader who later sees hand-built drill q
 
 ## Drill-down: the panel side
 
-An entity drawer has six parts. Skipping any one produces a bug that only shows up in use, not in a screenshot.
+An entity drawer has six parts, and four more decide whether it feels finished. Skipping any one produces a bug that only shows up in use, not in a screenshot.
 
 \`\`\`js
 const drill = { entity: null, charts: [], returnFocus: null };
@@ -356094,7 +356108,7 @@ function closeDrill() {
   document.removeEventListener("keydown", onTab);
   drill.charts.forEach((c) => c.destroy());     // 4. tear charts down
   drill.charts = [];
-  drill.returnFocus?.focus();                   // 5. give focus back
+  drill.returnFocus?.focus({ preventScroll: true }); // 5. give focus back, without scrolling
 }
 \`\`\`
 
@@ -356107,6 +356121,13 @@ What each part prevents:
 5. **Chart teardown** - most chart libraries keep a registry and attach resize listeners; reopening a drawer twenty times without destroying leaks memory and can leave ghost tooltips from the old instance.
 6. Also re-render the drawer when the global filter changes underneath it, or it silently shows numbers for a period the rest of the page has moved off.
 
+The four that separate a working drawer from a polished one:
+
+7. **Open on the click, resolve inside.** When the drawer needs a lookup before it can query (a name resolved to an id), open it at once with the name as its title and a skeleton, and swap the content in when the id arrives, under the stale-response guard. Waiting for the lookup before opening anything makes the click look dead for as long as the query takes.
+8. **Drilling from a drawer replaces it in place.** A product opened from inside a market drawer swaps the drawer's title and body without a second slide-in, and the new subject reads from its top: reset the body's \`scrollTop\` to 0, or it opens wherever the reader had scrolled the previous one.
+9. **The panel body is its only scroller, and its scroll stays in it.** Wheel and touch inside the drawer scroll the drawer; nothing scrolls the page behind it, over the scrim either, and closing returns the reader to exactly where they were. On a real build the wheel inside an open drawer scrolled the page behind it by 2,000 to 3,000px, and closing left the reader that far from the row they had clicked.
+10. **It lands on the reader's screen when embedded.** Inside an auto-sized frame \`position: fixed\` means the top of the whole document, so a drawer built the standalone way opens far above the reader and drags the host page up to meet it. \`reference/overlays.md\` is the recipe for 9 and 10: finding the visible band, one clipped layer over it, scroll containment, and focus that does not scroll.
+
 ## Cross-filtering (shared scope)
 
 Clicking a category filters the other tiles. Express scope as a \`where:\` refinement on the **same named view** each tile already runs, so a filtered tile and an unfiltered one still share one definition.
@@ -356336,6 +356357,15 @@ Omit \`height\` and the frame auto-sizes. The embedded page measures its real co
 
 Do not rely on \`body { min-height: 100vh }\` to drive the frame height. The runtime deliberately measures the content's bottom edge, not the viewport, to avoid a grow-forever loop.
 
+## Inside the frame there is no viewport
+
+The host scrolls; the frame does not. Inside an auto-sized frame \`window.innerHeight\` is the whole document, \`window.scrollY\` stays 0, and \`position: fixed\` means the top of the document rather than the top of the reader's screen. Two consequences, both invisible when the page is opened directly:
+
+- **An auto-sized frame must never become scrollable.** Anything whose box reaches past the content's bottom edge (a sentinel, an absolutely positioned helper, an overlay) is scrollable overflow: the document grows past the height the host sized, and the reader's first wheel turns scroll the app inside its frame before the host moves. Keep every added element within the content, and check it with the harness rather than hiding overflow: a fixed-height frame (\`height\` above, or \`publisher:fit\`) needs the app to scroll inside it.
+- **Anything that floats over the page needs placing.** A drawer, a compare tray, a toast: built with \`position: fixed\` it opens at the top of the document, far above the reader, and focusing it scrolls the host page up to meet it. \`reference/overlays.md\` is the recipe: track the slice of the page the reader can see, place one clipped layer over it, contain its scroll, and focus without scrolling.
+
+Test embedded, not just standalone: the Publisher console renders a package's app at \`/<env>/<package>/data-apps/<path>\`, which exercises the same resize contract a host does (\`reference/verification-harness.md\`).
+
 ## Auth
 
 - Same-origin or same-tenant: pass no token. The browser's cookies authenticate the iframe.
@@ -356433,11 +356463,262 @@ for (let y = 0; y <= pageH; y += vh) {
 }
 await page.waitForFunction((n) => document.querySelectorAll(".tile .value").length >= n, total);
 \`\`\``
+    },
+    {
+      name: "malloy-html-data-apps/overlays",
+      description: "Drawers, trays and toasts in an embedded app. Reference detail for the malloy-html-data-apps skill.",
+      body: "# Drawers, trays and toasts in an embedded app\n\n> How to place anything that floats over the page (an entity drawer, a compare tray, a toast) so it lands on the reader's screen and the page behind it holds still, standalone and inside an auto-sized frame. Referenced from `SKILL.md` and `reference/embedding.md`. Every rule below is a bug a real build shipped and a reader found.\n\n## Why `position: fixed` breaks when embedded\n\nA host that auto-sizes the frame (the Publisher console, a page using `Publisher.embed` without a `height`, any host that honours the resize messages) sizes the iframe to the app's full content height and scrolls its own container. So inside the frame:\n\n- `window.innerHeight` is the whole document, thousands of pixels;\n- `window.scrollY` is always 0, because the frame never scrolls; the host does;\n- `position: fixed; top: 0` means **the top of the document**, not the top of the reader's screen.\n\nA drawer built the standalone way therefore opens at the top of the app, far above where the reader is. Then focusing its close button scrolls the *host* up to meet it, and the page the reader was on jumps. Measured on a real build: the clicked row moved about 1,000px, the drawer was the height of the whole document so it could not scroll on its own, and closing it left the reader thousands of pixels from where they had been. None of this shows up when the page is opened directly, because standalone `fixed` is correct.\n\nThe host does not tell the frame where the reader is: the resize protocol goes one way, frame to host. The frame has to work it out.\n\n## Find the visible band\n\nAn `IntersectionObserver` with the implicit root reports against the **top-level** viewport, clipped by the host's scroll container, for same-origin and cross-origin frames alike, and its `intersectionRect` comes back in the frame's own coordinates. Observe a column of thin strips down the page, keep the union of their visible parts current from page load, and read it synchronously when something opens.\n\n```js\n// view.js: which slice of our document is on the reader's screen.\nexport const EMBEDDED = (() => { try { return window.self !== window.top; } catch { return true; } })();\nlet VIEW = { top: 0, height: innerHeight, known: !EMBEDDED };\nconst listeners = new Set();\nexport const onView = (fn) => (listeners.add(fn), () => listeners.delete(fn));\n\nif (EMBEDDED && \"IntersectionObserver\" in window) {\n  const STEP = 100, holder = document.createElement(\"div\"), strips = [], vis = {};\n  holder.className = \"view-strips\";                        // height 0: see the rules below\n  const io = new IntersectionObserver((entries) => {\n    const sy = window.scrollY;                             // viewport -> document coordinates\n    for (const e of entries) {\n      const r = e.intersectionRect;\n      if (e.isIntersecting && r.height > 0) vis[e.target.__i] = [r.top + sy, r.bottom + sy];\n      else delete vis[e.target.__i];\n    }\n    const spans = Object.values(vis);\n    if (!spans.length) return;\n    const top = Math.min(...spans.map((s) => s[0])), bottom = Math.max(...spans.map((s) => s[1]));\n    VIEW = { top: Math.round(top), height: Math.round(bottom - top), known: true };\n    listeners.forEach((fn) => fn(VIEW));\n  }, { threshold: Array.from({ length: 21 }, (_, i) => i / 20) });   // every 5% of a strip\n\n  // Cover the content and STOP AT ITS BOTTOM EDGE, measured the way the SDK\n  // measures the height it reports: the lowest bottom among body's children,\n  // plus body's bottom padding.\n  const contentBottom = () => Math.ceil(Math.max(0, ...[...document.body.children]\n    .filter((k) => k !== holder && !k.classList.contains(\"overlay\"))\n    .map((k) => k.getBoundingClientRect().bottom + window.scrollY))\n    + (parseFloat(getComputedStyle(document.body).paddingBottom) || 0));\n  const cover = () => {\n    const end = contentBottom(), need = Math.max(1, Math.ceil(end / STEP));\n    while (strips.length < need) { const s = document.createElement(\"div\"); s.__i = strips.length; strips.push(s); holder.append(s); io.observe(s); }\n    while (strips.length > need) { const s = strips.pop(); io.unobserve(s); s.remove(); delete vis[s.__i]; }\n    strips.forEach((s, i) => {\n      const h = Math.max(1, Math.min(STEP, end - i * STEP)) + \"px\";\n      s.style.top = i * STEP + \"px\";\n      // A strip that is fully visible before and after a resize crosses no threshold,\n      // so the observer would keep its old rect: observe it afresh.\n      if (s.style.height !== h) { s.style.height = h; io.unobserve(s); io.observe(s); }\n    });\n  };\n  document.body.append(holder);\n  cover();\n  new ResizeObserver(cover).observe(document.body);        // tiles land; the page grows and shrinks\n}\n\n// The band an overlay should occupy, in document coordinates. The top is pinned\n// to the top of what the reader sees; only the height gives way.\nexport function visibleBand() {\n  if (!EMBEDDED) return { top: window.scrollY, height: innerHeight };\n  if (!VIEW.known) return { top: 0, height: Math.min(innerHeight, 900) };\n  const room = document.documentElement.scrollHeight - VIEW.top;\n  return { top: VIEW.top, height: Math.min(Math.max(VIEW.height, 360), room) };\n}\n```\n\n```css\n.view-strips { position: absolute; top: 0; left: 0; width: 1px; height: 0; pointer-events: none; visibility: hidden; }\n.view-strips > div { position: absolute; left: 0; width: 1px; }\n```\n\n## Place one layer over the band\n\nPut the scrim and the panel in one layer. Standalone it is `position: fixed; inset: 0`. Embedded it is `position: absolute` with its `top` and `height` set from `visibleBand()`, re-set whenever `onView` fires, so it follows the host if the reader scrolls it by other means. The layer clips its contents (`overflow: hidden`), so the panel's slide-in never widens the page.\n\n```css\n.overlay { position: fixed; inset: 0; z-index: 40; overflow: hidden; pointer-events: none; }\n.overlay.is-open, .overlay.is-open > * { pointer-events: auto; }\n.overlay.is-anchored { position: absolute; inset: auto 0 auto 0; }   /* top/height from JS */\n.overlay .scrim { position: absolute; inset: 0; background: var(--scrim); opacity: 0; transition: opacity var(--dur-base); }\n.overlay.is-open .scrim { opacity: 1; }\n.overlay .panel {\n  position: absolute; top: 0; right: 0; bottom: 0; width: min(760px, 94vw);\n  display: flex; flex-direction: column;\n  transform: translateX(calc(100% + 64px));         /* parked past its own shadow */\n  transition: transform var(--dur-base) var(--ease-out);\n}\n.overlay.is-open .panel { transform: none; }\n.overlay .panel-head { flex: none; }\n.overlay .panel-body {                               /* the panel's only scroller */\n  flex: 1 1 auto; min-height: 0; overflow-y: auto; overscroll-behavior: contain;\n  display: grid; align-content: start; gap: var(--space-4);\n}\n```\n\nA tray or toast pinned to the bottom of the screen follows the same rule: embedded, give it `position: absolute` and set its `top` to `band.top + band.height - itsHeight - gap` on every `onView`.\n\n## The rules, and the bug each one prevents\n\n- **Read the band synchronously; never wait on a fresh measurement to open.** An async probe with a timeout fallback raced the click, lost, and opened the drawer at the top of the document.\n- **Pin the overlay's top to the top of the band; let only its height give way.** Pushing the top up to honour a minimum height puts the header above the screen when only the bottom of the app is visible.\n- **Nothing you add may extend the content.** Sentinels, strips, an overlay layer: anything whose box reaches past the content's bottom edge is scrollable overflow. The document then becomes taller than the frame the host sized, the reader's first wheel turns scroll the app *inside* its frame, and everything placed by the band is offset by that much. Measured: strips rounded up to the next 100px made every drawer open 7 to 46px too high, header under the host's breadcrumb bar, bottom short of the window. Keep sentinels in a zero-height holder, end the last one at the content edge, and keep overlays inside the band.\n- **An auto-sized frame never scrolls.** It cannot, as long as nothing extends the content (the rule above), and the harness asserts it. Do not force it with `overflow: hidden` on the document: the app cannot tell an auto-sized frame from a fixed-height one (`Publisher.embed({ height })`, a page with `<meta name=\"publisher:fit\" content=\"viewport\">`), and a fixed-height frame needs the app to scroll inside it. Hidden overflow there makes everything below the fold unreachable.\n- **Work in document coordinates.** `intersectionRect` is in viewport coordinates; an absolutely positioned layer is placed in document coordinates. Add `window.scrollY` at the moment you read it. They agree only while the frame is unscrolled, which is exactly the assumption the previous bug broke.\n- **Focus without scrolling.** `el.focus({ preventScroll: true })`, both when focusing into the panel and when handing focus back on close. A plain `focus()` scrolls whatever ancestor (including the host) it takes to bring the element into view.\n- **Consume scroll that is not the panel's.** A non-passive `wheel` and `touchmove` listener on the layer calls `preventDefault()` unless the event is inside the panel body and the body can still scroll that way. `overscroll-behavior: contain` on the body stops chaining at its ends. Without both, the wheel inside a drawer scrolled the page behind it by 2,000 to 3,000px.\n- **Scroll keys scroll the panel.** With focus on the close button, PageDown and Space go to the page behind. Handle the scroll keys on the panel and scroll the body. Escape closes; Tab stays inside.\n- **Nothing behind the panel moves.** No `overflow: hidden` toggled on the page (it removes a scrollbar and reflows everything), no `backdrop-filter: blur` on the scrim (it re-rasterises the page on every frame of the slide and reads as the page itself moving).\n- **Exits keep their content.** Remove the open class, let the panel slide out with what it showed, then remove the layer. Under `prefers-reduced-motion: reduce`, remove it at once.\n- **Page rules leak into the panel.** A panel section built from `<section>` inherits the page's `section { margin-top }`, and in a grid that margin does not collapse: measured as a 44px hole above every panel. Reset margins on panel content.\n\n## Verify it embedded\n\nNone of this can be checked standalone. Load the app inside a real host (the Publisher console at `/<env>/<package>/data-apps/<path>`, or a test page that calls `Publisher.embed` inside a scrolling container), scroll the host with real wheel events, open a drawer from well down the page, and assert on screen coordinates. `reference/verification-harness.md` has the checks."
+    },
+    {
+      name: "malloy-html-data-apps/performance",
+      description: "Performance and layout stability. Reference detail for the malloy-html-data-apps skill.",
+      body: `# Performance and layout stability
+
+> What a data app downloads, what it asks the server for, and whether the page holds still while it loads. Referenced from \`SKILL.md\`. Every rule here came from a real build that passed its functional checks while being slow, heavy, or jumpy: a working app is not yet a polished one.
+
+## Measure first
+
+Record these per page, before and after any change, with the harness in \`reference/verification-harness.md\`. A change you did not measure is a guess.
+
+| Measure | How | Bar |
+|---|---|---|
+| Bytes downloaded, by type | sum of response sizes on a cold load | the chart library is usually most of it; see below |
+| Queries issued | count of \`/query\` requests until the page settles | one per tile, no more |
+| Identical queries | same model + same query text twice on one page | 0 |
+| Layout shift (CLS) | a \`layout-shift\` \`PerformanceObserver\`, first visit and repeat visit | under 0.1 first visit, 0 on repeat |
+| Time to settled | until no query has been in flight for ~1.5s | depends on the warehouse; measure, do not promise |
+
+Measure embedded as well as standalone (\`reference/embedding.md\`). Inside an auto-sized frame the whole document is "the viewport", so every shift anywhere on the page counts, and numbers that looked fine standalone (0.01 to 0.07) measured 0.12 to 0.41 embedded on the same build.
+
+## Keep the chart library off the critical path
+
+A vendored chart library is typically 80 to 90% of a data app's bytes, and as a plain \`<script>\` ahead of the app code it blocks every query until it has downloaded and parsed. It also lets the browser paint the page before the app code can size it, which is where much of the first-visit layout shift comes from.
+
+- **Preload it, load it on the first chart.** Put \`<link rel="preload" as="script" href="./vendor/echarts.min.js">\` in the \`<head>\` of pages that draw charts, and have the chart layer inject the script the first time it mounts a chart. The download starts at once, nothing waits for it, and a tile whose rows land before the library does waits only for itself. The preload's \`href\` and the injected script's \`src\` must resolve to the same URL, or the preload is a second download that nothing uses.
+- **A page that draws no chart never loads it.** An overview or landing page of numbers and links should not pay for a chart library at all. Measured: 1,464 KB to 348 KB for one such page.
+- **Hand back a stand-in while it loads.** Callers usually wire a click handler on the chart instance right after mounting it. Return an object that records \`.on(...)\` calls and replays them on the real instance once it exists, so the calling code does not change shape.
+
+The loader below is written for ECharts (a global \`echarts\`, click handlers wired with \`.on()\`). For another library change the file name, the global, and the stand-in to record whatever its callers call; Chart.js, for one, takes its click handler as an option rather than through \`.on()\`. The URL is resolved against \`charts.js\` itself, so it is right from a page in any directory as long as \`charts.js\` sits beside \`vendor/\` (the layout in \`reference/runtime.md\`).
+
+\`\`\`js
+// charts.js
+let libP = null;
+function chartLib() {
+  if (window.echarts) return Promise.resolve(window.echarts);
+  libP ??= new Promise((res, rej) => {
+    const s = document.createElement("script");
+    s.src = new URL("./vendor/echarts.min.js", import.meta.url).href;   // same URL as the preload
+    s.onload = () => res(window.echarts);
+    s.onerror = () => { libP = null; rej(new Error("Chart library failed to load")); };
+    document.head.append(s);
+  });
+  return libP;
+}
+
+export function mount(host, buildOption) {
+  if (!window.echarts) {
+    const calls = [], stub = { on: (...a) => (calls.push(a), stub) };
+    const mine = (host.__mount = (host.__mount || 0) + 1);   // a newer mount wins
+    chartLib().then(() => {
+      if (host.__mount !== mine || !host.isConnected) return;
+      const inst = mount(host, buildOption);
+      calls.forEach((a) => inst.on(...a));
+    }).catch((e) => showError(host, e));              // the tile's own error state
+    return stub;
+  }
+  host.__mount = (host.__mount || 0) + 1;
+  echarts.getInstanceByDom(host)?.dispose();         // a remount replaces, never merges
+  const inst = echarts.init(host);
+  inst.setOption(buildOption());
+  return inst;
+}
+\`\`\`
+
+### Trim the library to what the app draws
+
+Most chart libraries publish a modular build. A bundle of only the series types and components the app actually uses is typically a third smaller (one build: 1,122 KB to 713 KB, 369 KB to 243 KB gzipped). Inventory what the code passes the library (every series \`type:\`, and components such as legend, tooltip, visualMap, markLine), bundle exactly those once with a bundler outside the package, and commit the bundle together with its entry file and the command that rebuilt it.
+
+**A trimmed build fails silently.** A series type left out of the bundle still mounts its canvas, throws nothing and logs nothing, and draws an empty box. A canvas count proves nothing. Verify by reading pixels: open every page and every kind of drawer, and require each chart canvas to have drawn pixels, against the full build first and then the trimmed one. Write the list of included types next to the bundle, so the next person to add a chart type knows to rebuild.
+
+## Ask once
+
+- **One query text per resource.** \`Publisher.query\` caches nothing: every call is a request. Any cache the app keeps, any sharing of an in-flight request, and any prefetch are keyed on the exact query string. Two pages that read the same tile with different text (one adds \`order_by\`, one does not) get two cache entries and two round trips for one answer. Where order does not matter to a caller, send the text the other caller sends.
+- **A prefetch must match what the destination sends.** Warming the next page's queries on nav hover is worth it only if the warmed text is byte-for-byte what that page will ask for. Check it: list what each page sends and what each prefetch warms, and diff them.
+- **Count identical queries on a page.** It should be 0. Two tiles or two drawer panels needing the same rows should share one in-flight request.
+
+## Hold still while loading
+
+Layout shift is the most visible difference between a generated app and a polished one, and almost all of it has three causes.
+
+**1. Script-filled blocks at the top of the page.** A KPI strip, a provenance line or a filter bar that is an empty \`<div>\` in the HTML and is filled by script appears *after* the first paint, and pushes everything below it down. Measured: about 180px of drop on every page of one app, from three such blocks. Give each its final size in the first paint:
+
+- put placeholder markup in the HTML, built from the same classes the script renders, so the layout reserves the right height at every width (four \`.kpi\` placeholder cards in the KPI grid, replaced when the numbers arrive);
+- give a one-line block a \`min-height\` while it is \`:empty\`.
+
+**2. A tile that changes height when its rows land.** A four-line skeleton replaced by a 25-row list shifts everything below it by hundreds of pixels.
+
+- **Size the skeleton from what is coming.** If the query carries a \`limit:\` or the tile slices to N rows, skeleton N rows at the real row height.
+- **Remember the settled height.** Store each tile's rendered height per page, tile and width bucket in \`localStorage\`, and hold it as \`min-height\` on the next load. Data that refreshes daily keeps its height, so a returning reader sees the page at its final size from the first frame. Measured: 0 layout shift on repeat visits on every page.
+
+\`\`\`js
+const KEY = "app-size:" + location.pathname;
+const sizes = (() => { try { return JSON.parse(localStorage.getItem(KEY) || "{}"); } catch { return {}; } })();
+const sizeKey = (host) => host.id && \`\${host.id}@\${Math.round(host.clientWidth / 40)}\`;
+function holdSize(host) { const k = sizeKey(host); if (k && sizes[k]) host.style.minHeight = sizes[k] + "px"; return k; }
+function settleSize(host, k) {                       // call right after render, same task
+  host.style.minHeight = "";
+  if (!k) return;
+  const h = Math.round(host.getBoundingClientRect().height);
+  if (h > 0 && sizes[k] !== h) { sizes[k] = h; try { localStorage.setItem(KEY, JSON.stringify(sizes)); } catch {} }
+}
+\`\`\`
+
+**3. A tile that re-runs for a new filter.** Dropping back to a skeleton on every scope change makes the page collapse and regrow. Keep the last answer on screen, dimmed and \`aria-busy\`, at its current height, until the new one lands. And guard the race: number each run per tile, and drop a response that is not the latest, or a slow query for the previous filter paints over the new one.
+
+\`\`\`js
+function load(host, query, render) {
+  const seq = (host.__seq = (host.__seq || 0) + 1);
+  if (host.__drawn) { host.style.minHeight = host.offsetHeight + "px"; host.classList.add("is-busy"); host.setAttribute("aria-busy", "true"); }
+  else showSkeleton(host);
+  const unbusy = () => { host.classList.remove("is-busy"); host.removeAttribute("aria-busy"); };
+  return Publisher.query(MODEL, query).then((rows) => {
+    if (seq !== host.__seq) return;                  // a newer run owns this tile
+    unbusy(); host.__drawn = true;
+    render(rows, host);
+    host.style.minHeight = "";                       // released after the new rows are in
+  }, (e) => {
+    if (seq !== host.__seq) return;
+    unbusy(); showError(host, e);                    // a failed re-run must not stay dimmed and busy
+    host.style.minHeight = "";
+  });
+}
+\`\`\`
+
+## Answer from the last visit (opt-in)
+
+A per-tab cache (\`sessionStorage\`, or memory) starts every new tab and every next-day visit from nothing: every query is re-sent and every tile waits on it. Measured on a real build: 1.6 to 3.8 s before the first screen filled in a new tab. Most data apps read tables built on a schedule, so the last visit's rows are usually still right. A persistent cache can draw them at once, but it is the one recipe here that can show someone rows they may not read, so it is opt-in and has conditions.
+
+**Use it only when every reader sees the same rows.** Check the model before adding it: no \`given:\` declarations the app or a host sets per reader, no \`#(authorize)\` gates, no access filters, nothing that makes the same query text answer differently for different people. If any of those apply, do not persist results; a per-tab cache is the most you can do.
+
+**Why the conditions.** Every \`public/\` app on a deployment is served from the API's own origin, so they all share one IndexedDB. The page is served without a sign-in, and it cannot tell who is viewing it. A row-level refusal is a 200 with fewer rows, not a 403, so no error marks the cached answer as wrong. A cache keyed on query text alone shows one reader's rows to the next person on the same browser profile, signed in or not, and keeps showing them to someone whose access was withdrawn.
+
+How it stays safe:
+
+- **Nothing paints from the store until this visit has proven it may read.** Every tile sends its query at once, as without a cache. Stored answers are held back until one query on the page has answered successfully, then painted together while the rest of the queries finish. A signed-out visitor, or someone whose access was withdrawn, gets an error before any stored row reaches the screen. The first screen then waits one round trip rather than every query.
+- **Every stored answer is re-asked.** There is no window in which the page trusts the store and sends nothing. A stored answer older than the build schedule plus a margin (a day and a half for a daily build) is not painted at all.
+- **The key is everything the answer depends on:** the environment and package (the page's own path), the model, the exact query text, and the query's options (\`givens\`, \`filterParams\`, a target \`environment\` or \`package\`).
+- **A 401 or 403 on any query wipes the store**, and that tile shows its error.
+- **Repaint only the tile that still shows that query, and only when the rows differ.** A tile whose filter changed while its query was in flight ignores the late answer (the sequence guard in "Hold still while loading"). An unchanged answer must not redraw: it would re-animate charts for no reason.
+- **The store is capped.** Every filter combination is a new key; prune the oldest past a few hundred entries.
+- **Show how old the number is.** A tile that can draw yesterday's answer should carry the as-of date of its data.
+
+Measured before the session gate was added: the new-tab load drew its first screen in 87 to 93 ms. The gate adds one query's round trip to that.
+
+\`\`\`js
+// cache.js: draw the last visit's answer once this visit has proven it may read.
+// Opt-in: only for models whose rows are the same for every reader (see above).
+const STALE = 36 * 3600e3, CAP = 300;
+const SCOPE = location.pathname.split("/").slice(0, 5).join("/");   // /environments/<env>/packages/<pkg>
+let mayRead; const live = new Promise((res) => (mayRead = res));     // resolves on the first good answer
+const inflight = new Map();
+const db = new Promise((res) => {
+  try { const rq = indexedDB.open("app-cache", 1);
+    rq.onupgradeneeded = () => rq.result.createObjectStore("q").createIndex("t", "t");
+    rq.onsuccess = () => res(rq.result); rq.onerror = rq.onblocked = () => res(null);
+  } catch { res(null); }                                   // private mode: no persistence
+});
+const store = (mode, fn) => db.then((d) => d && new Promise((res) => {
+  try { const tx = d.transaction("q", mode); const r = fn(tx.objectStore("q")); tx.oncomplete = () => res(r?.result ?? null); tx.onerror = () => res(null); }
+  catch { res(null); }
+}));
+const wipe = () => store("readwrite", (s) => s.clear());
+const prune = () => store("readwrite", (s) => {
+  const c = s.count(); c.onsuccess = () => {
+    let extra = c.result - CAP; if (extra <= 0) return;
+    s.index("t").openCursor().onsuccess = (e) => { const cur = e.target.result; if (cur && extra-- > 0) { cur.delete(); cur.continue(); } };
+  };
+});
+
+// Resolves with rows for the tile: the stored answer once the page may read, or the
+// network answer if that comes first. onFresh(rows, err) fires if the network answer
+// arrives after a stored one was drawn and differs, or if the query is refused.
+export function cachedQuery(model, q, opts = {}, onFresh) {
+  const k = JSON.stringify([SCOPE, model, q, opts]);
+  let net = inflight.get(k);                                 // two tiles, one request
+  if (!net) {
+    net = Publisher.query(model, q, opts).then((rows) => {
+      mayRead();
+      store("readwrite", (s) => s.put({ t: Date.now(), r: rows }, k)).then(prune);
+      return rows;
+    }, (e) => { if (e?.status === 401 || e?.status === 403) wipe(); throw e; })
+      .finally(() => inflight.delete(k));
+    inflight.set(k, net);
+  }
+  const stored = store("readonly", (s) => s.get(k)).then((box) =>
+    box && Date.now() - box.t < STALE ? live.then(() => box.r) : new Promise(() => {}));   // never: wait for the network
+  return Promise.race([net.then((r) => ({ r })), stored.then((r) => ({ r, stored: true }))]).then((first) => {
+    if (first.stored) net.then(                              // drawn from the store: follow up once
+      (rows) => { if (JSON.stringify(rows) !== JSON.stringify(first.r)) onFresh?.(rows, null); },
+      (e) => onFresh?.(null, e));
+    return first.r;
+  });
+}
+\`\`\`
+
+## Start on intent (opt-in)
+
+Resting the pointer on something that opens a drawer, or focusing it, usually comes a few hundred milliseconds before the click. Start the drawer's queries then, and the click finds them in flight or answered. Measured on one build: all 7 queries of a market drawer and all 15 of a product drawer (a name lookup included) were in flight before the click, and the click itself sent none. Worth it on pages whose drawers are the main way in; skip it where drawers are rare.
+
+Build each drawer in one function that both the click and the warm-up call. A hand-written list of each drawer's queries, warmed on hover, is a second copy of every drawer's query text and drifts the first time a panel changes. Do not warm by dispatching a synthetic click on the row either: capture-phase listeners still run, a row that is a link navigates, a \`<summary>\` toggles, and an app that wires its drawers by delegation gets no warm-up at all and no error saying so.
+
+\`\`\`js
+// drawers.js: a drill row names its drawer (data-drawer="market" data-key="42").
+// DRAWERS.market(key, body, { warm }) sends the drawer's queries; warm, it stops there.
+export function drawerFor(row, { warm = false } = {}) {
+  const build = DRAWERS[row.dataset.drawer];
+  if (!build) return;
+  if (warm) return build(row.dataset.key, null, { warm });   // queries only: nothing rendered, nothing opened
+  return build(row.dataset.key, openDrawer(row), { warm });   // openDrawer: the real open (reference/overlays.md)
+}
+document.addEventListener("click", (e) => { const row = e.target.closest?.("[data-drawer]"); if (row) drawerFor(row); });
+
+// Intent: an 80ms rest, by pointer or keyboard, so a sweep down a list warms nothing;
+// at most two drawers warming at once.
+let timer = 0, warmingNow = 0;
+const warmed = new WeakSet();
+const intent = (e) => {
+  clearTimeout(timer);
+  const row = e.target.closest?.("[data-drawer]");
+  if (!row || warmed.has(row) || e.pointerType === "touch") return;
+  timer = setTimeout(() => {
+    if (warmingNow >= 2) return;
+    warmed.add(row); warmingNow++;
+    Promise.resolve(drawerFor(row, { warm: true })).catch(() => {}).finally(() => warmingNow--);
+  }, 80);
+};
+document.addEventListener("pointerover", intent);
+document.addEventListener("focusin", intent);
+\`\`\`
+
+What makes it safe:
+
+- **A warm build only asks.** It sends the drawer's queries through the same cache as the real open (see "Ask once") and returns; it renders nothing, so no chart instance is left on a detached node, and nothing opens, navigates, or writes.
+- **The warm flag is an argument, not a global.** A drawer that first resolves a name to an id passes \`{ warm }\` on to the step that runs after the lookup, so a warm-up never opens a drawer when the lookup returns.
+- **Warm what the click will ask for.** The click and the warm-up run the same \`DRAWERS\` function, so they send the same query text.
+- **Never warm on page load.** Warm-ups wait for intent. Warming every drawer a page could open is a query storm the reader pays for.
+
+## Respond before the answer arrives
+
+A click that waits on a query before anything visible happens reads as a dead click. The common case is a drill that must first resolve a name to an id: open the drawer immediately, titled with the name and a skeleton, run the lookup inside it, and replace the skeleton in place when the id arrives. Drop the late answer if the reader has closed the drawer or opened another subject meanwhile (\`reference/depth-patterns.md\`, stale-response guard).
+
+## What the page cannot fix
+
+Compression and cache headers belong to whatever serves \`public/\`. Check them (\`curl -sI -H 'Accept-Encoding: gzip, br' <url>\`): a chart library served uncompressed is downloaded at full size on the first visit, and with \`max-age=0\` every later page asks the server again before using it (a conditional request answered 304, one round trip per file). Report it to whoever runs the server rather than working around it in the page.`
     },
     {
       name: "malloy-html-data-apps/runtime",
       description: "HTML Data App Runtime. Reference detail for the malloy-html-data-apps skill.",
-      body: '# HTML Data App Runtime\n\n> `Publisher.query(modelPath, malloy)` returns an array of plain row objects. Build the Malloy string, let the model do the work, and render the rows with whatever front-end code you like.\n\nThe runtime loads from the root-relative `<script src="/sdk/publisher.js">` and adds one global, `window.Publisher`.\n\n## The query contract\n\n| Call | Returns | Use for |\n|---|---|---|\n| `Publisher.query(modelPath, malloy, opts?)` | `Promise<Array>` of rows | driving your own charts and tables |\n| `Publisher.queryFull(modelPath, malloy, opts?)` | `Promise<MalloyResult>` | handing to `<malloy-render>` |\n\n- `modelPath` is the model FILE path within the package, with `/` separators (`"subscriptions.malloy"`, `"models/events.malloy"`). It is not the source name.\n- `malloy` is any query string, written in standard Malloy. This skill covers only the JavaScript glue, not Malloy syntax.\n- `opts` (all optional): `sourceName`, `queryName` (`queryName` runs a saved query, with `sourceName` qualifying the source a view hangs off; `sourceName` on its own is a 400), `givens` (a `{ name: value }` map bound to the model\'s Malloy `given:` runtime parameters for this query; safe parameterization, values are bound by Publisher server-side, not string-interpolated), `filterParams` (values for the model\'s legacy `#(filter)` source filters), `bypassFilters`, and `environment` / `package` (only if the page is served from outside `/environments/<env>/packages/<pkg>/`). `givens` and `filterParams` compose (both apply).\n\n## Structure the app as modules, not one inline script\n\nPast a single tile, an inline `<script>` becomes unmaintainable and untestable. Split the work, and load it without a build step: put your shared libraries first as plain globals, then one ES-module entry point that `import`s your own files.\n\n```html\n<!-- Globals first: the runtime, then any vendored chart library. -->\n<script src="/sdk/publisher.js"></script>\n<script src="./vendor/chart.umd.js"></script>\n<!-- One module entry; it imports the rest. ES modules resolve with no bundler. -->\n<script type="module" src="./app.js"></script>\n```\n\nA separation that keeps each piece testable and changeable on its own:\n\n- **`format.js`**. Pure functions only: number/date formatting, a series-align-by-month helper, status thresholds. No DOM, no globals. This is the file `node --test` can cover directly.\n- **`charts.js`**. Turns a prepared data object into a drawn chart; the only file that touches the chart library.\n- **`tiles.js`**. Your tiles as *data*: for each, its model/source/view (and target source, if any), plus a pure `build(rows)` that shapes query rows for the chart. This is the single source of truth for what each tile queries.\n- **`app.js`**. The thin entry point: reads `tiles.js`, runs the queries, wires results to the DOM. Adding a tile means adding a `tiles.js` entry, not editing `app.js`.\n\nDeclare each tile\'s source and view names once, in `tiles.js`, and have everything else (render code, any agent prompt, tests) read from there. A second copy of those names in another file is the classic drift bug, and a *derived* name (`okr_4_4_2_targets` invented from a tile code) is simply wrong: a target source may have an irregular name or not exist at all. Read the model; don\'t compute names.\n\n## Patterns that work\n\nThese assume a `subscriptions.malloy` model whose `subscriptions` source defines the views `plan_mix`, `mrr_by_industry`, and `kpis`. The names are illustrative; swap in your own model and view names.\n\nRun a named view:\n\n```js\nconst rows = await Publisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix");\n```\n\nRefine a view from UI state by appending a `where:`. Restrict the values to ones you control (for example a dropdown populated from the model\'s own distinct values) and escape each interpolated value with a backslash before quotes and backslashes (Malloy rejects the SQL-style `\'\'` doubling). An unescaped apostrophe in a value breaks out of the literal:\n\n```js\nfunction whereClause(state) {\n  const q = (s) => s.replace(/\\\\/g, "\\\\\\\\").replace(/\'/g, "\\\\\'"); // backslash-escape for Malloy\n  const parts = [];\n  if (state.plan) parts.push(`plan = \'${q(state.plan)}\'`);\n  if (state.industry) parts.push(`industry = \'${q(state.industry)}\'`);\n  return parts.length ? `where: ${parts.join(", ")}` : "";\n}\nconst rows = await Publisher.query(\n  "subscriptions.malloy",\n  `run: subscriptions -> plan_mix + { ${whereClause(state)} }`,\n);\n```\n\nDo not interpolate free-text or otherwise untrusted input into the query string. Route parameterized input through `opts.givens` (or the legacy `opts.filterParams`) instead: Publisher binds those values server-side as typed parameters, so they are never concatenated into query text and can\'t inject query syntax. (One nuance: a `filter<T>`-typed given takes Malloy filter syntax as its value, so validate it against a known set like any other input; scalar givens carry no syntax at all.) `opts.givens` is safe *parameterization*, not an authorization boundary: a client-supplied given is client-trusted unless a trusted tier upstream sets it from verified identity. Publisher has no per-package control that strips or finalizes one; identity-bound givens are a planned milestone, not a shipped feature. Where you must build query text from input, constrain it to a known set and escape it, or keep the filtering in model-defined views.\n\nKPI or single-row view. Destructure element zero:\n\n```js\nconst [kpis] = await Publisher.query("subscriptions.malloy", "run: subscriptions -> kpis");\nel.textContent = kpis.active_mrr;   // the result is an array; kpis.active_mrr, not rows.active_mrr\n```\n\nRefresh a dashboard. Fire the tiles together:\n\n```js\nconst [planMix, byIndustry, kpisRows] = await Promise.all([\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix"),\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> mrr_by_industry"),\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> kpis"),\n]);\n```\n\nPrefer defining the views in the model (one per tile, pre-aggregated and sorted) over building long query strings in JS.\n\nGet the numbers right. The fastest way to ship a wrong-but-convincing dashboard is to paper over missing data:\n\n- **Missing is not zero.** When you join two series (actuals to a separately-keyed target) and a key is absent, leave it `null` so the chart skips it. Do not `|| 0`, which plots a real-looking zero and reads as "we hit nothing that month." Align on a normalized key (`"YYYY-MM"`), and let the renderer omit null points:\n\n  ```js\n  // monthKey/monthLabel are your own format.js helpers: monthKey normalizes a\n  // date to a "YYYY-MM" string; monthLabel formats it for display.\n  // target may not cover every actual month; an absent month stays null, never 0.\n  const target = new Map(planRows.map((r) => [monthKey(r.plan_month), Number(r.target_revenue)]));\n  const data = actualRows.map((r) => ({\n    label: monthLabel(r.order_month),\n    actual: Number(r.revenue),\n    target: target.has(monthKey(r.order_month)) ? target.get(monthKey(r.order_month)) : null,\n  }));\n  ```\n\n- **"Current" means latest non-null.** For a KPI scorecard, scan back to the last month that actually has data rather than reading the final row, which may be an incomplete current month.\n- **Guard division in Malloy, not after.** `avg(paid / nullif(active, 0))`. A `nullif` in the query beats catching `Infinity`/`NaN` in JS.\n- **Convert units explicitly.** If the model stores a 0 to 1 fraction and you show a percent, multiply once in `build()` and comment it. Mismatched units are a silent off-by-100.\n\nLoading, empty, and error states. Handle all three; a bare `.then()` that assumes rows leaves the page blank when the query is slow or fails:\n\n```js\nconst el = document.getElementById("out");\nel.textContent = "Loading...";\nPublisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix")\n  .then((rows) => {\n    if (!rows.length) { el.textContent = "No data."; return; }\n    render(rows);\n  })\n  .catch((err) => {\n    el.textContent = `Query failed (${err.status ?? ""}): ${err.response?.message ?? err.message}`;\n  });\n```\n\nRender through `<malloy-render>`. `queryFull` returns the full Malloy result envelope (the JSON form of the server\'s result, not a live result object) to hand to the component:\n\n```js\nconst el = document.querySelector("malloy-render");\nel.result = await Publisher.queryFull("subscriptions.malloy", "run: subscriptions -> plan_mix");\n```\n\nPublisher does not serve or bundle `<malloy-render>`; you must obtain a built component bundle matched to your model\'s Malloy version and vendor it into `public/` yourself, then confirm it accepts the envelope as-is. The `storefront` example draws with Chart.js and has no `<malloy-render>` element in its pages, so the component itself is not exercised there. A view tagged in the model (for example `# bar_chart`) drives how it draws.\n\nValidate every query before wiring it into render code, using whatever query tool your environment provides, or by POSTing the query to a running Publisher at `/api/v0/environments/<env>/packages/<pkg>/models/<modelPath>/query` with body `{"compactJson":true,"query":"..."}`, or by running `Publisher.query` once and logging the rows. Malloy names result columns after the `group_by` / `aggregate` field names (`group_by: plan` gives a `plan` column; `aggregate: account_count` gives an `account_count` column), so confirm those names against real output before you read them.\n\nIf you validate the rendered page in a headless browser (Playwright or Puppeteer), do not wait for network idle: `publisher.js` holds the live-reload SSE stream open, so the page never reaches it. Wait on `domcontentloaded` or `load` plus a content selector instead.\n\n## Context, auth, live reload (all automatic)\n\n- Context. A page served under `/environments/<env>/packages/<pkg>/...` infers its environment and package, so `query` needs no env or package args. Serving from elsewhere? Pass `opts.environment` and `opts.package`.\n- Auth. By default the runtime sends cookies (`credentials: include`), so a signed-in user is authenticated with no code. For a bearer token, call `Publisher.setToken(token)` first; `Publisher.setToken(null)` reverts to cookies.\n- Live reload. Under `--watch-env`, the page reloads on package changes by itself. Nothing to wire.\n\n## When the app fails\n\n| Symptom | Likely cause and fix |\n|---|---|\n| 404 or "model not found" | `modelPath` wrong. It is the file path (`"subscriptions.malloy"`), with `/` separators, not the source name. |\n| "source/view not defined" | View or source name guessed. Read the model (your environment\'s context tool, or open the `.malloy` file) and use the real names. |\n| Promise rejects, message starts `Publisher.query:` | Read `error.status` and `error.response` for the server\'s reason (compile error, missing required parameter, permission). |\n| Empty array when you expect rows | Filter value mismatch (case, spelling, type, or a non-ASCII character like `≤` or an en-dash in the literal). Copy the literal verbatim from the model, do not retype the user\'s paraphrase, and confirm it with a distinct-values query (`run: src -> { group_by: the_dimension }`). Quote strings, use `@` for dates. |\n| 400 on a given (ungated source) | An unknown given name (check spelling; names are case-sensitive), a required given left unset, or a value that doesn\'t fit the declared type. Malloy rejects it when preparing the query; supply declared givens via `opts.givens` with the right shape (see the givens type table). |\n| 403 on a query that should be allowed, when passing givens to a gated source | On a gated source, a bad given (unknown name or wrong-typed value) fails closed, so it looks like access denied rather than validation. A `#(authorize)` lock also answers 403 for a caller it simply does not admit. Check the given names and values against the model. |\n| KPI shows `undefined` | The result is an array. Read `rows[0].field` (or destructure `const [k] = ...`), not `rows.field`. |\n| A NEW file under `public/` 404s while the rest of the app serves | The server loaded the package **before** `public/` existed, and it is not watching. Without `--watch-env` the package is COPIED into `publisher_data/<env>/<pkg>/` at load and static files are served from that copy, so a file you add afterwards is never seen. Restart with `--watch-env <env>`, or mirror the file into the served copy. Verified by writing a probe file into the real package and getting a 404 while the copy served fine - and note the existing row below sends you looking under `public/`, which is exactly the wrong place for this one. |\n| Page loads in dev but is not listed or not served | The file is not under the package\'s `public/` directory. Publisher serves only `public/`; a page written anywhere else (for example `/tmp`) is never reachable at `/environments/<env>/packages/<pkg>/<file>`. |\n| Queries fail only when embedded cross-origin | Cookies are not sent cross-site. Serve same-origin, or pass a bearer token. |\n| No live reload | Watch mode is off. Start with `--watch-env <env>`; without it the events stream reports `mode: disabled` and never reloads. |'
+      body: '# HTML Data App Runtime\n\n> `Publisher.query(modelPath, malloy)` returns an array of plain row objects. Build the Malloy string, let the model do the work, and render the rows with whatever front-end code you like.\n\nThe runtime loads from the root-relative `<script src="/sdk/publisher.js">` and adds one global, `window.Publisher`.\n\n## The query contract\n\n| Call | Returns | Use for |\n|---|---|---|\n| `Publisher.query(modelPath, malloy, opts?)` | `Promise<Array>` of rows | driving your own charts and tables |\n| `Publisher.queryFull(modelPath, malloy, opts?)` | `Promise<MalloyResult>` | handing to `<malloy-render>` |\n\n- `modelPath` is the model FILE path within the package, with `/` separators (`"subscriptions.malloy"`, `"models/events.malloy"`). It is not the source name.\n- `malloy` is any query string, written in standard Malloy. This skill covers only the JavaScript glue, not Malloy syntax.\n- `opts` (all optional): `sourceName`, `queryName` (`queryName` runs a saved query, with `sourceName` qualifying the source a view hangs off; `sourceName` on its own is a 400), `givens` (a `{ name: value }` map bound to the model\'s Malloy `given:` runtime parameters for this query; safe parameterization, values are bound by Publisher server-side, not string-interpolated), `filterParams` (values for the model\'s legacy `#(filter)` source filters), `bypassFilters`, and `environment` / `package` (only if the page is served from outside `/environments/<env>/packages/<pkg>/`). `givens` and `filterParams` compose (both apply).\n\n## Structure the app as modules, not one inline script\n\nPast a single tile, an inline `<script>` becomes unmaintainable and untestable. Split the work, and load it without a build step: the runtime first as a plain global, then one ES-module entry point that `import`s your own files.\n\n```html\n<head>\n  <!-- Start the chart library\'s download now, without making anything wait for it.\n       Only on pages that draw a chart. -->\n  <link rel="preload" as="script" href="./vendor/chart.umd.js">\n</head>\n...\n<script src="/sdk/publisher.js"></script>\n<!-- One module entry; it imports the rest. ES modules resolve with no bundler. -->\n<script type="module" src="./app.js"></script>\n```\n\n**Do not load the chart library with a plain `<script>` ahead of your code.** It is usually most of the page\'s weight, and loaded that way it holds every query until it has downloaded and parsed. `charts.js` injects it the first time it draws, so the queries start at once. `reference/performance.md` has the loader, and the stand-in that lets callers wire chart clicks before the library has arrived.\n\nA separation that keeps each piece testable and changeable on its own:\n\n- **`format.js`**. Pure functions only: number/date formatting, a series-align-by-month helper, status thresholds. No DOM, no globals. This is the file `node --test` can cover directly.\n- **`charts.js`**. Turns a prepared data object into a drawn chart; the only file that touches the chart library, and the one that loads it.\n- **`tiles.js`**. Your tiles as *data*: for each, its model/source/view (and target source, if any), plus a pure `build(rows)` that shapes query rows for the chart. This is the single source of truth for what each tile queries.\n- **`app.js`**. The thin entry point: reads `tiles.js`, runs the queries, wires results to the DOM. Adding a tile means adding a `tiles.js` entry, not editing `app.js`.\n\nDeclare each tile\'s source and view names once, in `tiles.js`, and have everything else (render code, any agent prompt, tests) read from there. A second copy of those names in another file is the classic drift bug, and a *derived* name (`okr_4_4_2_targets` invented from a tile code) is simply wrong: a target source may have an irregular name or not exist at all. Read the model; don\'t compute names.\n\n## Patterns that work\n\nThese assume a `subscriptions.malloy` model whose `subscriptions` source defines the views `plan_mix`, `mrr_by_industry`, and `kpis`. The names are illustrative; swap in your own model and view names.\n\nRun a named view:\n\n```js\nconst rows = await Publisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix");\n```\n\nRefine a view from UI state by appending a `where:`. Restrict the values to ones you control (for example a dropdown populated from the model\'s own distinct values) and escape each interpolated value with a backslash before quotes and backslashes (Malloy rejects the SQL-style `\'\'` doubling). An unescaped apostrophe in a value breaks out of the literal:\n\n```js\nfunction whereClause(state) {\n  const q = (s) => s.replace(/\\\\/g, "\\\\\\\\").replace(/\'/g, "\\\\\'"); // backslash-escape for Malloy\n  const parts = [];\n  if (state.plan) parts.push(`plan = \'${q(state.plan)}\'`);\n  if (state.industry) parts.push(`industry = \'${q(state.industry)}\'`);\n  return parts.length ? `where: ${parts.join(", ")}` : "";\n}\nconst rows = await Publisher.query(\n  "subscriptions.malloy",\n  `run: subscriptions -> plan_mix + { ${whereClause(state)} }`,\n);\n```\n\nDo not interpolate free-text or otherwise untrusted input into the query string. Route parameterized input through `opts.givens` (or the legacy `opts.filterParams`) instead: Publisher binds those values server-side as typed parameters, so they are never concatenated into query text and can\'t inject query syntax. (One nuance: a `filter<T>`-typed given takes Malloy filter syntax as its value, so validate it against a known set like any other input; scalar givens carry no syntax at all.) `opts.givens` is safe *parameterization*, not an authorization boundary: a client-supplied given is client-trusted unless a trusted tier upstream sets it from verified identity. Publisher has no per-package control that strips or finalizes one; identity-bound givens are a planned milestone, not a shipped feature. Where you must build query text from input, constrain it to a known set and escape it, or keep the filtering in model-defined views.\n\nKPI or single-row view. Destructure element zero:\n\n```js\nconst [kpis] = await Publisher.query("subscriptions.malloy", "run: subscriptions -> kpis");\nel.textContent = kpis.active_mrr;   // the result is an array; kpis.active_mrr, not rows.active_mrr\n```\n\nRefresh a dashboard. Fire the tiles together:\n\n```js\nconst [planMix, byIndustry, kpisRows] = await Promise.all([\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix"),\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> mrr_by_industry"),\n  Publisher.query("subscriptions.malloy", "run: subscriptions -> kpis"),\n]);\n```\n\nPrefer defining the views in the model (one per tile, pre-aggregated and sorted) over building long query strings in JS.\n\n**Same question, same query text.** `Publisher.query` caches nothing, but a cache the app keeps, a shared in-flight request, and any prefetch are all keyed on the exact string. Two pages reading the same view with different text (one adds an `order_by`) pay for two round trips for one answer, and a prefetch that warms different text from what the destination page sends warms nothing. Build each tile\'s query in one place and reuse that string wherever the same rows are needed.\n\n**Set ARIA and data attributes as attributes.** A small element helper that does `Object.assign(document.createElement(tag), props)` silently drops `aria-modal`, `aria-label`, `aria-busy` and `data-*`: they are not properties, so assigning them does nothing and no error says so. Route any `aria-*`, `data-*` and `role` key through `setAttribute`. And a clickable row is a control: give it `tabIndex = 0` and Enter/Space handling, or keyboard users cannot open what a mouse user can.\n\nGet the numbers right. The fastest way to ship a wrong-but-convincing dashboard is to paper over missing data:\n\n- **Missing is not zero.** When you join two series (actuals to a separately-keyed target) and a key is absent, leave it `null` so the chart skips it. Do not `|| 0`, which plots a real-looking zero and reads as "we hit nothing that month." Align on a normalized key (`"YYYY-MM"`), and let the renderer omit null points:\n\n  ```js\n  // monthKey/monthLabel are your own format.js helpers: monthKey normalizes a\n  // date to a "YYYY-MM" string; monthLabel formats it for display.\n  // target may not cover every actual month; an absent month stays null, never 0.\n  const target = new Map(planRows.map((r) => [monthKey(r.plan_month), Number(r.target_revenue)]));\n  const data = actualRows.map((r) => ({\n    label: monthLabel(r.order_month),\n    actual: Number(r.revenue),\n    target: target.has(monthKey(r.order_month)) ? target.get(monthKey(r.order_month)) : null,\n  }));\n  ```\n\n- **"Current" means latest non-null.** For a KPI scorecard, scan back to the last month that actually has data rather than reading the final row, which may be an incomplete current month.\n- **Guard division in Malloy, not after.** `avg(paid / nullif(active, 0))`. A `nullif` in the query beats catching `Infinity`/`NaN` in JS.\n- **Convert units explicitly.** If the model stores a 0 to 1 fraction and you show a percent, multiply once in `build()` and comment it. Mismatched units are a silent off-by-100.\n\nLoading, empty, and error states. Handle all three; a bare `.then()` that assumes rows leaves the page blank when the query is slow or fails:\n\n```js\nconst el = document.getElementById("out");\nel.textContent = "Loading...";\nPublisher.query("subscriptions.malloy", "run: subscriptions -> plan_mix")\n  .then((rows) => {\n    if (!rows.length) { el.textContent = "No data."; return; }\n    render(rows);\n  })\n  .catch((err) => {\n    el.textContent = `Query failed (${err.status ?? ""}): ${err.response?.message ?? err.message}`;\n  });\n```\n\nRender through `<malloy-render>`. `queryFull` returns the full Malloy result envelope (the JSON form of the server\'s result, not a live result object) to hand to the component:\n\n```js\nconst el = document.querySelector("malloy-render");\nel.result = await Publisher.queryFull("subscriptions.malloy", "run: subscriptions -> plan_mix");\n```\n\nPublisher does not serve or bundle `<malloy-render>`; you must obtain a built component bundle matched to your model\'s Malloy version and vendor it into `public/` yourself, then confirm it accepts the envelope as-is. The `storefront` example draws with Chart.js and has no `<malloy-render>` element in its pages, so the component itself is not exercised there. A view tagged in the model (for example `# bar_chart`) drives how it draws.\n\nValidate every query before wiring it into render code, using whatever query tool your environment provides, or by POSTing the query to a running Publisher at `/api/v0/environments/<env>/packages/<pkg>/models/<modelPath>/query` with body `{"compactJson":true,"query":"..."}`, or by running `Publisher.query` once and logging the rows. Malloy names result columns after the `group_by` / `aggregate` field names (`group_by: plan` gives a `plan` column; `aggregate: account_count` gives an `account_count` column), so confirm those names against real output before you read them.\n\nIf you validate the rendered page in a headless browser (Playwright or Puppeteer), do not wait for network idle: `publisher.js` holds the live-reload SSE stream open, so the page never reaches it. Wait on `domcontentloaded` or `load` plus a content selector instead.\n\n## Context, auth, live reload (all automatic)\n\n- Context. A page served under `/environments/<env>/packages/<pkg>/...` infers its environment and package, so `query` needs no env or package args. Serving from elsewhere? Pass `opts.environment` and `opts.package`.\n- Auth. By default the runtime sends cookies (`credentials: include`), so a signed-in user is authenticated with no code. For a bearer token, call `Publisher.setToken(token)` first; `Publisher.setToken(null)` reverts to cookies.\n- Live reload. Under `--watch-env`, the page reloads on package changes by itself. Nothing to wire.\n\n## When the app fails\n\n| Symptom | Likely cause and fix |\n|---|---|\n| 404 or "model not found" | `modelPath` wrong. It is the file path (`"subscriptions.malloy"`), with `/` separators, not the source name. |\n| "source/view not defined" | View or source name guessed. Read the model (your environment\'s context tool, or open the `.malloy` file) and use the real names. |\n| Promise rejects, message starts `Publisher.query:` | Read `error.status` and `error.response` for the server\'s reason (compile error, missing required parameter, permission). |\n| Empty array when you expect rows | Filter value mismatch (case, spelling, type, or a non-ASCII character like `≤` or an en-dash in the literal). Copy the literal verbatim from the model, do not retype the user\'s paraphrase, and confirm it with a distinct-values query (`run: src -> { group_by: the_dimension }`). Quote strings, use `@` for dates. |\n| 400 on a given (ungated source) | An unknown given name (check spelling; names are case-sensitive), a required given left unset, or a value that doesn\'t fit the declared type. Malloy rejects it when preparing the query; supply declared givens via `opts.givens` with the right shape (see the givens type table). |\n| 403 on a query that should be allowed, when passing givens to a gated source | On a gated source, a bad given (unknown name or wrong-typed value) fails closed, so it looks like access denied rather than validation. A `#(authorize)` lock also answers 403 for a caller it simply does not admit. Check the given names and values against the model. |\n| KPI shows `undefined` | The result is an array. Read `rows[0].field` (or destructure `const [k] = ...`), not `rows.field`. |\n| A NEW file under `public/` 404s while the rest of the app serves | The server loaded the package **before** `public/` existed, and it is not watching. Without `--watch-env` the package is COPIED into `publisher_data/<env>/<pkg>/` at load and static files are served from that copy, so a file you add afterwards is never seen. Restart with `--watch-env <env>`, or mirror the file into the served copy. Verified by writing a probe file into the real package and getting a 404 while the copy served fine - and note the existing row below sends you looking under `public/`, which is exactly the wrong place for this one. |\n| Page loads in dev but is not listed or not served | The file is not under the package\'s `public/` directory. Publisher serves only `public/`; a page written anywhere else (for example `/tmp`) is never reachable at `/environments/<env>/packages/<pkg>/<file>`. |\n| Queries fail only when embedded cross-origin | Cookies are not sent cross-site. Serve same-origin, or pass a bearer token. |\n| No live reload | Watch mode is off. Start with `--watch-env <env>`; without it the events stream reports `mode: disabled` and never reloads. |'
     },
     {
       name: "malloy-html-data-apps/token-contract",
@@ -356803,6 +357084,59 @@ Three things bite on this path, and each makes a correct page look broken:
 - **Switch themes by clicking the app's own control**, not by setting an attribute on the root. Setting the attribute skips whatever re-resolves chart colours, so the charts keep their construction-time palette and you get a screenshot that looks like a real theming bug.
 - **Kill the browser when you finish** and use a port nobody else is on. A stray headless Chrome holding a profile directory is a confusing thing to debug later.
 
+## 4. Embedded, layout stability, and drawers
+
+Sections 2 and 3 prove the tiles render. They do not prove the app is polished, and every check below caught a real bug on a build that passed them. These need a live Publisher (the layout and timing are the point), a real browser, and real wheel events.
+
+**Load it embedded, not only standalone.** Two hosts, in order of effort:
+
+- **The Publisher console**, at \`http://localhost:4000/<env>/<package>/data-apps/<path>\` (for example \`.../data-apps/index.html\`). Same origin, no setup, and it sizes the frame through the same resize contract a host does.
+- **A test host page** that calls \`Publisher.embed\` inside a fixed header and a *scrolling container*, which is how real hosts lay out. Serve it from another origin (\`python3 -m http.server 4100 --bind 127.0.0.1\`) and start Publisher with \`PUBLISHER_FRAME_ANCESTORS="'self' http://127.0.0.1:4100"\`, or the browser refuses to frame the app.
+
+Then, per page, embedded and standalone:
+
+\`\`\`js
+// Layout shift: install before navigation, applies to every frame.
+await context.addInitScript(() => {
+  window.__cls = 0;
+  new PerformanceObserver((l) => l.getEntries().forEach((e) => { if (!e.hadRecentInput) window.__cls += e.value; }))
+    .observe({ type: "layout-shift", buffered: true });
+});
+// Read __cls from the APP's frame after the page settles, on a first visit and
+// again after page.reload() in the same context (the repeat visit). Target:
+// under 0.1 first, 0 repeat. Embedded, every shift on the page counts.
+
+// An auto-sized frame (the console, Publisher.embed without a height) must never
+// scroll: the document is exactly as tall as its frame. Skip this for a
+// fixed-height embed, which is meant to scroll inside its frame.
+const innerScroll = await appFrame.evaluate(() => document.documentElement.scrollHeight - innerHeight);
+if (innerScroll > 0) problems.push(\`app scrolls \${innerScroll}px inside its frame\`);
+
+// Ask once: identical (model, query) pairs on one page.
+const seen = new Set(); let dup = 0;
+page.on("request", (r) => { if (r.url().includes("/query")) { const k = r.url() + r.postData(); dup += seen.has(k); seen.add(k); } });
+\`\`\`
+
+**Drawer checks**, at two or three window sizes (1280×720, 1512×857 at 2×, 1920×1080). Scroll the host with \`page.mouse.wheel\` (not \`scrollTo\`: a real wheel is what exposes inner-frame scrolling), click a drill row that sits well down the page, and assert in **screen** coordinates (an element's rect inside the frame plus the iframe's rect in the host):
+
+| Check | Pass |
+|---|---|
+| The clicked row's screen position, sampled every frame while the drawer opens | moves 0px |
+| Host scroll position during the open | unchanged |
+| Drawer header top | equals the top of the host's visible area (below the host's own header) |
+| Drawer bottom | equals the bottom of the visible area, within a few pixels (the band moves in steps of the observer's thresholds) |
+| Drawer body \`scrollTop\` on open, and after drilling into a second subject from inside it | 0 |
+| 12 wheel turns over the drawer | the body scrolls; the host and the app move 0px |
+| 4 wheel turns over the scrim | the host and the app move 0px |
+| Host scrolled by other means (\`scrollBy\` on the host container) while open | drawer still spans the visible area |
+| Escape | drawer gone, host where it was, focus back on the clicked row |
+
+Compare screen coordinates against the host's *visible* area, not against the window: a host header or breadcrumb bar sits over the top of it. And sample the open as frames, not as one before/after pair: the page jump this catches can return to its starting point by the time a single later sample is taken.
+
+**Charts draw, everywhere they appear.** Read pixels (section 3) on every page *and inside every kind of drawer*. Run it against the full chart library first, then again after any change to how the library is built or loaded: a series type missing from a trimmed bundle mounts its canvas and draws nothing, with no error.
+
+**Wait for the warehouse, not a fixed time.** Locally a tile can take seconds; a fixed sleep then measures loading, not the app. Count \`/query\` requests in flight and treat the page as settled after about 1.5s with none, and attach those listeners *before* \`goto\`, or the first wave of queries is missed and the page "settles" at once.
+
 ## Gotchas (each cost a real debugging cycle)
 
 - **Wait out the mock's async delay before asserting.** Asserting immediately after \`load\` reads the skeleton, not the resolved tile, and reports a false "stuck skeleton." Wait until every tile shows its own resolved content (the per-tile \`waitForFunction\` above), never on \`networkidle\`, because \`publisher.js\` keeps the live-reload SSE stream open, so the page never reaches network idle.
@@ -361003,7 +361337,7 @@ For anything not covered here, call \`search_malloy_docs\` with the topic (for e
     {
       name: "malloy-reports",
       description: "Build or modify a Malloy Publisher report: a .malloy file with an ## artifact tag, written at the package root unless asked otherwise, laid out as a grid (a dashboard, scanned at a glance) or linear (a notebook or data story, read top to bottom), with filter controls rendered from givens and # drill click-through. Use when the user asks for a dashboard, a notebook, a report, a data story, a filterable view, or drill-through between views, and no code is wanted. Legacy .malloynb files are read, not authored.",
-      body: "# Publisher Reports\n\n> A `.malloy` file with an `## artifact { layout=… tiles=[…] }` tag **is** a report. It imports the model, names the views to show, binds the filtering on those views, and says how to lay them out. Publisher discovers it at package load, renders the filter controls from the givens its tiles reference, offers `# drill` click-through, and serves it at `/<env>/<pkg>/<path>`, its package path without `.malloy`. No code, no build step.\n\nWhat other tools call a dashboard and a notebook are both reports here. The **layout** is the only difference:\n\n- **`layout=grid`**: tiles across a grid behind one filter row, scanned at a glance (a dashboard). Read `reference/grid.md` before you lay one out.\n- **`layout=linear`**: tiles and prose top to bottom, read in order (a notebook, a data story). Read `reference/linear.md` before you write one.\n\nEverything else (filters, text tiles, drill, the builder, the lint, the write path) is the same for both, and switching layout later is a one-property edit.\n\n## Where the file goes\n\n- **Write a new report at the package root**, as `<slug>.malloy`, unless the author asks for another location. No directory is required, and none is a convention: a report can live anywhere in the package except `public/`, and the root `index.malloy` is never a report. Do not create a `dashboards/` or `notebooks/` directory for it.\n- **Always write `layout=grid` or `layout=linear`** in the tag. A tag without one is read by a fallback rule, and a linear report that lists tiles without `layout=linear` is read as a grid. `kind=` is no longer read: a tag that sets it makes no report (`report-kind-removed`), so replace it with `layout=`.\n- **The package path is the report's identity.** `sales/q3.malloy` is the report `sales/q3`: its URL, its `GET …/reports/{path}` address, and its `# drill` target. Two reports may share a basename in different directories.\n- **Imports are relative to the report's own location.** At the root: `import { order_items } from \"storefront.malloy\"`. In a subdirectory: `\"../storefront.malloy\"`.\n- **An untagged `.malloy` file is an ordinary model**, wherever it lives. Shared definitions several reports import go in one.\n\n## When this is the right tool\n\n| The user wants                                       | Use                                                          |\n| ---------------------------------------------------- | ------------------------------------------------------------ |\n| A recurring, at-a-glance view behind shared filters  | this skill, `layout=grid`                                    |\n| A narrative, with prose between the numbers          | this skill, `layout=linear`                                  |\n| A quick write-up of queries you already ran          | `skill:malloy-analysis-report`, which writes a linear report |\n| Custom design, branding, or interactions beyond tags | an HTML data app                                             |\n| The model itself: sources, measures, joins           | `malloy-model`                                               |\n\nInteractivity is not the axis: both layouts get filter controls, URL-addressable state, Apply batching, and `# drill`. Pick on the shape of the document: scanned at a glance is grid, read top to bottom is linear. When in doubt, linear.\n\n## Build sequence\n\nTool names below are bare (`get_context`); match each against the tools you actually have, since a host may prefix or rename them. A host names its compile and reload tools its own way. Where you have none, use the REST endpoint named beside the step.\n\n1. **READ THE MODEL FIRST.** Get the real source, view, dimension, and given names from the package: `get_context` if you have it, otherwise the REST model endpoint for `index.malloy` (it answers 404 for a file off the surface) or the `.malloy` files. Never guess a name. A guessed field in a query fails the whole package load, not just that one report; a guessed tile or suggest source is quieter, and only shows up in the package warnings. If the package root holds an `index.malloy` (every scaffolded package does), a tile reads only the sources that file exports.\n2. **PICK THE LAYOUT AND THE TILES.** Which views, in what order, and on a grid how wide each sits. A query tile is a `view:` you declare in the report, named as `\"source -> view\"`.\n3. **DECLARE THE GIVENS** the report will filter by, in the report file itself, with their control tags (see \"Filter controls\"). A report holds its own filters: the builder edits the report file and nothing else, so a filter it can add, change or remove is a declaration in that file. A given the model already declares and reads is imported by name, never declared again; if it is only a reader's filter, move it into the report instead (see \"Givens that stay in the model\").\n4. **COMPOSE THE FILE** at its path (the package root unless asked otherwise), following the template below, but do not save it yet. Name the sources you need in the import. Each tile binds its controls with a refinement, `view: t is v + { where: category ~ $CATEGORY }`, one clause per given it answers to; a `filter<...>` binds with `~`, a plain `date` or `number` given is a value and binds with `>=`, `<=` or `=`. Only the givens some tile references become controls. Then import every source or query any referenced given names in a `suggest`; **a `suggest` naming a `query=` needs that query's own source imported as well**, because an import is not transitive.\n5. **COMPILE IT** with your compile tool (`POST …/models/<path>/compile` over REST) at the path the file will have, with **`\"scope\": \"file\"`**: a report opens with an `import`, which the default `append` scope refuses, and an existing file compiled at `append` collides with itself. **`\"scope\": \"file\"` does not check tiles, drills or suggest queries.** To see those before you save, compile the same text at `\"scope\": \"package\"` with `modelPath` set to the report's path: it runs the lint step 6 reads and returns its findings with code `dashboard-lint` (or `render-tag`). Editing an untagged model several reports import also wants `\"scope\": \"package\"`, which recompiles every file as saved.\n6. **SAVE IT, RELOAD, AND READ THE MANIFEST AND THE WARNINGS.** Save by writing the file, or with `PUT …/models/<path>` over REST (omit `expectedHash` to create; it creates at any new path and replaces only a file the package already serves as a report). Then your reload tool, or `GET …/packages/<pkg>?reload=true`. A 424 means the package did not load and your edit is not live. **The `warnings` key is absent when there are none.** Then read `GET …/packages/<pkg>/reports/<path>`: its `givens` are exactly the controls that will render, and its `layout` is the layout Publisher read. See \"Read the lint\".\n7. **OPEN IT AND LOOK.** Not optional; see \"What done means\".\n\n## The form\n\n```malloy\n##! experimental.givens\n##\" One line saying what this report is for.\n##| artifact { layout=grid title=\"Storefront overview\"\n  tiles=[\n    intro { kind=text colspan=12 },\n    \"overview -> kpis\",\n    \"overview -> revenue_trend\",\n    \"overview -> revenue_by_state\"\n  ]\n} dashboard { columns=12 }\n|##\nimport { order_items, products } from \"storefront.malloy\"\n\n# label=\"Category\" control=select suggest { source=products dimension=category }\ngiven: CATEGORY :: filter<string> is f''\n# label=\"Ordered since\"\ngiven: SINCE :: date is @2023-01-01\n\n##|(markdown) intro\nRevenue and margin for the selected category.\n|##\n\nsource: overview is order_items extend {\n  # colspan=12\n  # label=\"Key figures\"\n  # big_value\n  view: kpis is key_figures + { where: category ~ $CATEGORY, where: created_at >= $SINCE }\n\n  # colspan=8\n  # break\n  # label=\"Revenue by month\"\n  view: revenue_trend is sales_by_month + { where: category ~ $CATEGORY, where: created_at >= $SINCE }\n\n  # colspan=4\n  # label=\"Revenue by state\"\n  view: revenue_by_state is sales_by_state + { where: category ~ $CATEGORY, where: created_at >= $SINCE }\n}\n```\n\nThe same file with `layout=linear` and no `dashboard { … }` or `colspan` is a linear report.\n\n- **The tag is model-level**, one line (`## artifact { … }`) or a `##|` … `|##` block with the same text inside, the form to use once the list is long: one tile per line, `}` on its own line, `|##` closing at the opener's column. A one-line `##` tag must stay on one line: wrapping it is a compile error, or worse, compiles clean and quietly stops being a report.\n- **The header** above the tag holds only `##!` flags, `//` comments and the unnamed `\"` notes that are the report's description. Keep statements and `#` tags below `## artifact`: nothing refuses one above it, but the header is where readers and the builder look.\n- **Quote every query entry.** `\"overview -> kpis\"` is a string; unquoted, the tag does not parse (`notebook-artifact-unparsed`). A bare quoted name (`\"top_products\"`) names a model-level `query:` in the file.\n- **A query tile is a thin `view:` on an extension the report declares** (`source: overview is order_items extend { … }`): the modelled view keeps its chart tag, the wrapper carries the tile's `# label`, its width on a grid, and its binding.\n- **A text tile is a `##|(markdown) name` block** listed as `name { kind=text }`. The name is one bare word on the opener line, the body starts on the next line (a heading goes inside the block), and `|##` closes it at the opener's column. A bare `intro` without `{ kind=text }` is the query-tile form for a `query:`, so the block is not shown. On a grid the entry also takes `colspan` and `break`, and nothing else.\n- **File order:** header, imports and givens, the prose blocks in tile order, then the extension that defines the tile views. That is the order the builder writes.\n- **A `run:` in a report that lists `tiles` is never shown** (`notebook-layout-run`). Define a view, list it, delete the `run:`.\n- **A tile expression is a string, so the compiler never checks it.** Rename a view and the file still compiles; the tile fails at package load, where the lint names it.\n- **Chart tags go on the view** (`# line_chart`, `# bar_chart`, `# big_value`, `# label=\"…\"`). `skill:malloy-charts` covers choosing them.\n\n## Filter controls\n\nControls come from the `given:` declarations the tiles reference. The tags on the declaration are the control contract:\n\n```malloy\n##! experimental.givens\n\n# label=\"Category\" control=select suggest { source=products dimension=category }\ngiven: CATEGORY :: filter<string> is f''\n\n# label=\"Brand\" control=multiselect suggest { query=brand_suggest dimension=brand }\ngiven: BRAND :: filter<string> is f''\n\n# label=\"Minimum line total\" range_min=0 range_max=250\ngiven: MIN_SALE :: filter<number> is f''\n\n# label=\"Ordered since\"\ngiven: SINCE :: date is @2023-01-01\n```\n\n`control=select`/`multiselect` with a `suggest` renders a picker filled from the data; `range_min`/`range_max` on a `filter<number>` renders a two-handled range slider; a `filter<date>` or `filter<timestamp>` renders a time-range control with preset windows and a custom day range; a bare `date` or `timestamp` renders a date picker; a `filter<string>` with no tag renders a text box taking filter syntax. Which controls appear is per report, decided by which givens its tiles reference.\n\n- `#(description=\"…\")` renders as helper text under the control and draws a cosmetic \"not a well-formed route\" compile diagnostic for a multi-word value; `# description=\"…\"` publishes to the API but the UI does not render it.\n- `dimension=` can name a field of a directly joined source, quoted: `suggest { source=sales dimension=\"products.department\" }`. On the `query=` form, `dimension` names a column of that query's output; match it to the query's `group_by`.\n- **A suggest's source or query has to resolve in the report file**, so import it there. Getting it wrong does not error: the control still looks like a picker and says \"Could not load the options for this control\"; the package warnings name it.\n- Two options on the artifact tag, either layout: `autorun=false` batches control changes behind an Apply button; `givens { CATEGORY=f'Outerwear' }` sets starting values (a URL parameter wins). A file-level `## autorun=false` does nothing on a `.malloy` report.\n\n### Binding, and givens that stay in the model\n\n**Binding is per declaration, not per name.** A report declaring its own `CATEGORY` over a source whose model-level `where:` reads the model's `CATEGORY` compiles, shows the control, and filters nothing. So bind on the tiles, with `+ { where: … }`. The other design, model-level scoping, still works: put a scoped source in an untagged model that imports the givens it reads, and import that model and those givens into the report. Do not mix the two on one given.\n\nA given stays in the model, declared once there, when a model source, view or measure, an `#(authorize)` or `#(access_filter)` gate, or an HTML data app reads it. The report imports it by name (`import { CATEGORY } from \"givens.malloy\"`) and never re-declares it:\n\n- **Import a name and also declare it: a compile error.** Drop the local declaration.\n- **Declare a name the model already reads, without importing it: no error at all.** The control renders and moves, and the model's own `where:` or gate never sees the value.\n\n**A model that already scopes a source by an optional filter given** (`where: Manufacturer ~ $manufacturer_filter` in the model) needs a decision:\n\n- **It is a reader's filter and you may change the model: move it.** Delete the given and its `where:` clause from the model, declare it in the report with its control tags, and bind it on each tile that should answer to it. A reader's filter is anything a person picks on the page; a given stays in the model only for the reasons `malloy-model` lists (a gate, a value every query must supply, a parameter a field is defined with, scoping meant for every consumer).\n- **The model can't change, or the given is semantic or governance: import it** as above. Say so plainly: the filter shows in the reader and in the builder, and can be set in both, but the builder cannot remove or reconfigure it. It is the model's.\n\nBefore, in the model:\n\n```malloy\n##! experimental.givens\ngiven:\n  manufacturer_filter :: filter<string> is f''\n  subject_filter :: filter<string> is f''\n  major_recall_filter :: filter<boolean> is f''\n  recall_date_filter :: filter<date> is f''\n\nsource: recalls is duckdb.table('data/auto_recalls.csv') extend {\n  where:\n    Manufacturer ~ $manufacturer_filter,\n    Subject ~ $subject_filter,\n    `Major Recall` ~ $major_recall_filter,\n    `Report Received Date` ~ $recall_date_filter\n  dimension: `Major Recall` is ifnull(`Potentially Affected`, 0) > 100000\n}\n```\n\nAfter: the model declares no givens and `recalls` has no `where:`; the report declares the four and binds each tile:\n\n```malloy\n##! experimental.givens\n##| artifact { layout=grid title=\"Recalls\"\n  tiles=[\"recalls_tiles -> recalls_by_year\", \"recalls_tiles -> recalls_by_manufacturer\"]\n} dashboard { columns=12 }\n|##\nimport { recalls } from \"auto_recalls.malloy\"\n\n# label=\"Manufacturer\" control=multiselect suggest { source=recalls dimension=Manufacturer }\ngiven: manufacturer_filter :: filter<string> is f''\n# label=\"Subject\"\ngiven: subject_filter :: filter<string> is f''\n# label=\"Major recalls only\"\ngiven: major_recall_filter :: filter<boolean> is f''\n# label=\"Filed\"\ngiven: recall_date_filter :: filter<date> is f''\n\nsource: recalls_tiles is recalls extend {\n  # colspan=6\n  view: recalls_by_year is by_year + {\n    where:\n      Manufacturer ~ $manufacturer_filter,\n      Subject ~ $subject_filter,\n      `Major Recall` ~ $major_recall_filter,\n      `Report Received Date` ~ $recall_date_filter\n  }\n  # colspan=6\n  view: recalls_by_manufacturer is by_manufacturer + {\n    where:\n      Subject ~ $subject_filter,\n      `Major Recall` ~ $major_recall_filter,\n      `Report Received Date` ~ $recall_date_filter\n  }\n}\n```\n\nA tile view takes a name of its own: `view: by_year is by_year + { … }` is \"Cannot redefine 'by_year'\". Each tile binds only the givens it should answer to: `recalls_by_manufacturer` leaves the manufacturer filter off, since it is the breakdown by manufacturer. Every given here is a `filter<…>`, so each binds with `~`; a plain `date` or `number` given binds with `>=`, `<=` or `=` (step 4).\n\nA given has to be in the report file's own scope to be bindable: declared there or imported. Never add a `#(filter)` annotation: it is deprecated, a report renders no control for it, and every use has a `given:` form (`malloy-model` covers the migration). `malloy-model` and `docs/givens.md` cover givens themselves.\n\n## Drill\n\n`# drill` goes on a model **dimension**, never on a report:\n\n```malloy\n# drill { to=[\"category\", \"self\"] given=CATEGORY }\ndimension: category is products.category\n\n# drill { to=\"regions/west\" given=REGION }\ndimension: region is regions.region\n```\n\n- **`to=<path>`** navigates to a report, of either layout, by its package path without `.malloy`, read from the package root: `to=category` is `category.malloy` at the root, `to=\"regions/west\"` is `regions/west.malloy`. Quote a path with a `/`. **Always write the path from the package root**: a bare name is a root file, never a report of that name elsewhere.\n- **`to=self`** filters in place; two or more destinations pop a menu.\n- **Always write `given=`.** Without it the given is the dimension name verbatim, so `dimension: category` seeds `category`, not `CATEGORY`. `to=self` survives that (it folds case); `to=<path>` does not, and lands on an unfiltered page with nothing erroring.\n- **The destination needs a control for the given**, declared as `filter<T>`. No lint checks that half, so click it and look.\n- **Only table cells are marked drillable.** A report meant to be drilled wants at least one untagged (table) tile, grouped by the tagged dimension. A column whose rendered header another, non-drillable tile also shows loses its marking: give the two different `# label=`s.\n\n## Read the lint\n\nPackage warnings after a reload are the report's test suite. Fix all of them, and read the text rather than the severity or the count. **\"Dashboard lint stopped early, so this list is incomplete\"** means the rest of the list is partial.\n\n| Finding                                                                                                 | Fix                                                                                                                               |\n| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `# drill … targets \"x\", which is not a report in this package`                                          | A dead click. Write the target's path                                                                                             |\n| `to=self, but no model in this package declares a given \"X\"`                                            | The clicked value has nowhere to go. Declare the given, or fix `given=`                                                           |\n| `given \"X\" suggests options from source \"y\", which this file does not define`                           | Import `y` into the report                                                                                                        |\n| `filters by given \"X\", which this file does not import`                                                 | No control is shown for it. Import the given                                                                                      |\n| A tile that does not resolve to a real view                                                             | Fix the view name, or declare the view                                                                                            |\n| `notebook-artifact-unparsed`                                                                            | The tag does not parse, usually an unquoted `source -> view` entry                                                                |\n| `notebook-layout-run`                                                                                   | A `run:` beside `tiles`. Make it a view, list it, delete the `run:`                                                               |\n| `notebook-tile-layout-ignored`                                                                          | `colspan` or `break` on a linear report. Remove them, or switch to `layout=grid`                                                  |\n| `report-kind-removed`                                                                                   | The tag sets `kind=`, which is no longer read, so the file is no report. Write the `layout=` the finding gives                    |\n| `report-cells-removed`                                                                                  | A linear tag with no `tiles`, the retired cell format, so the file is no report. List its tiles (`reference/linear.md`)           |\n| `report-on-surface`                                                                                     | A model `index.malloy` imports (or `explores` lists) is tagged, so its sources left the surface. Untag it, or move the report out |\n| `index-is-not-a-report`                                                                                 | The root `index.malloy` carries a tag. Remove it; put the report in its own file                                                  |\n| `report-name-ambiguous`                                                                                 | Two grid reports share a file name, so the deprecated by-name dashboards route answers 409 for it. Rename one of the files        |\n| `Tile … reads <source>, which index.malloy doesn't export`                                              | Add the source to the `export { ... }` in `index.malloy`. Never add an `explores` to `publisher.json`                             |\n| A grid's `columns`, `colspan`, or `dashboard_columns=` findings                                         | `reference/grid.md`                                                                                                               |\n| Prose the reader cannot place (`notebook-markdown-attached-nowhere`, `notebook-markdown-block-unnamed`) | `reference/linear.md`                                                                                                             |\n\n**Read the status the reload itself returns, not the listing.** One report that fails to compile fails the whole package load (424), and a package already serving keeps its previous version, so the listing still looks healthy. `GET /api/v0/status` still knows: a package serving an older model than its files appears in `loadErrors` with `stale: true`. If the reload is 200 and your report is not listed, discovery skipped it: usually a missing or misspelled artifact tag, or a file under `public/`.\n\n**A clean reload is not proof the tags are right.** The parse warning is syntax only and carries no position. That is why the last step is opening the page.\n\n## Template\n\n```malloy\n##! experimental.givens\n##\" [One-line description of the report.]\n##| artifact { layout=linear title=\"[Title]\"\n  tiles=[\n    intro { kind=text },\n    \"main_source_tiles -> broad_tile\",\n    \"main_source_tiles -> drill_tile\"\n  ]\n}\n|##\nimport { main_source } from \"model.malloy\"\n\n##|(markdown) intro\n[Framing question: what are we trying to understand?]\n|##\n\nsource: main_source_tiles is main_source extend {\n  view: broad_tile is [broad view]\n  view: drill_tile is [drill view]\n}\n```\n\nFor a grid, write `layout=grid`, add `dashboard { columns=12 }` after the tag's closing `}`, and give every tile view a `# colspan` (`reference/grid.md`).\n\n## Editing in the Console\n\nA person can open any report in the Console's builder (**Edit** on the report page; **+ Report** on the package page writes `<slug>.malloy` at the package root). The builder splices the file rather than regenerating it, so comments and anything it does not model survive; its layout switch rewrites `layout=` and nothing else. A file written as `run:` cells, the retired linear form, is no report and does not open (`reference/linear.md`). A save whose text declares a real `#(authorize)` or `#(access_filter)` gate outside prose is refused with a 400: gates live in a model file the report imports.\n\n## What \"done\" means\n\n- The file is at the package root (or where the author asked), and its tag says `layout=`.\n- Every source, view, and field name came from the model you read in step 1.\n- The reload returned **200**, not 424, with **zero** report warnings, and your report is in `GET …/reports`.\n- You opened the page and every tile shows real numbers: not stuck loading, not an error, not an empty state you did not intend.\n- Each control renders as the widget you intended, and changing one changes the numbers.\n- If you added a `# drill`, its `to=` is a path, and you clicked it and landed where you meant to, with the given seeded.\n- On a grid: every tile carries a colspan, each row sums to `columns`, rows end flush, nothing is clipped, and no legend or card label ends in `…`.\n\n## Reference\n\n- `reference/grid.md`: the grid recipe, its traps, and one query as the whole page.\n- `reference/linear.md`: linear reports, rewriting a retired `run:`-cell file, legacy `.malloynb`, style, and common mistakes.\n- `docs/reports.md`: the full guide this skill condenses.\n- `docs/givens.md`: the givens the controls are generated from.\n\n## Reference files over MCP\n\nThis skill's `reference/` files are served as separate prompts, one per file, fetched only when you ask for them. Where the text above says to read `reference/<name>.md`, get the prompt named `malloy-reports/<name>` instead.\n\nAvailable: grid, linear."
+      body: "# Publisher Reports\n\n> A `.malloy` file with an `## artifact { layout=… tiles=[…] }` tag **is** a report. It imports the model, names the views to show, binds the filtering on those views, and says how to lay them out. Publisher discovers it at package load, renders the filter controls from the givens its tiles reference, offers `# drill` click-through, and serves it at `/<env>/<pkg>/<path>`, its package path without `.malloy`. No code, no build step.\n\nWhat other tools call a dashboard and a notebook are both reports here. The **layout** is the only difference:\n\n- **`layout=grid`**: tiles across a grid behind one filter row, scanned at a glance (a dashboard). Read `reference/grid.md` before you lay one out.\n- **`layout=linear`**: tiles and prose top to bottom, read in order (a notebook, a data story). Read `reference/linear.md` before you write one.\n\nEverything else (filters, text tiles, drill, the builder, the lint, the write path) is the same for both, and switching layout later is a one-property edit.\n\n## Where the file goes\n\n- **Write a new report at the package root**, as `<slug>.malloy`, unless the author asks for another location. No directory is required, and none is a convention: a report can live anywhere in the package except `public/`, and the root `index.malloy` is never a report. Do not create a `dashboards/` or `notebooks/` directory for it.\n- **Always write `layout=grid` or `layout=linear`** in the tag. A tag without one is read by a fallback rule, and a linear report that lists tiles without `layout=linear` is read as a grid. `kind=` is no longer read: a tag that sets it makes no report (`report-kind-removed`), so replace it with `layout=`.\n- **The package path is the report's identity.** `sales/q3.malloy` is the report `sales/q3`: its URL, its `GET …/reports/{path}` address, and its `# drill` target. Two reports may share a basename in different directories.\n- **Imports are relative to the report's own location.** At the root: `import { order_items } from \"storefront.malloy\"`. In a subdirectory: `\"../storefront.malloy\"`.\n- **An untagged `.malloy` file is an ordinary model**, wherever it lives. Shared definitions several reports import go in one.\n\n## When this is the right tool\n\n| The user wants                                       | Use                                                          |\n| ---------------------------------------------------- | ------------------------------------------------------------ |\n| A recurring, at-a-glance view behind shared filters  | this skill, `layout=grid`                                    |\n| A narrative, with prose between the numbers          | this skill, `layout=linear`                                  |\n| A quick write-up of queries you already ran          | `skill:malloy-analysis-report`, which writes a linear report |\n| Custom design, branding, or interactions beyond tags | an HTML data app                                             |\n| The model itself: sources, measures, joins           | `malloy-model`                                               |\n\nInteractivity is not the axis: both layouts get filter controls, URL-addressable state, Apply batching, and `# drill`. Pick on the shape of the document: scanned at a glance is grid, read top to bottom is linear. When in doubt, linear.\n\n## Build sequence\n\nTool names below are bare (`get_context`); match each against the tools you actually have, since a host may prefix or rename them. A host names its compile and reload tools its own way. Where you have none, use the REST endpoint named beside the step.\n\n1. **READ THE MODEL FIRST.** Get the real source, view, dimension, and given names from the package: `get_context` if you have it, otherwise the REST model endpoint for `index.malloy` (it answers 404 for a file off the surface) or the `.malloy` files. Never guess a name. A guessed field in a query fails the whole package load, not just that one report; a guessed tile or suggest source is quieter, and only shows up in the package warnings. If the package root holds an `index.malloy` (every scaffolded package does), a tile reads only the sources that file exports.\n2. **PICK THE LAYOUT AND THE TILES.** Which views, in what order, and on a grid how wide each sits. A query tile is a `view:` you declare in the report, named as `\"source -> view\"`.\n3. **DECLARE THE GIVENS** the report will filter by, in the report file itself, with their control tags (see \"Filter controls\"). A report holds its own filters: the builder edits the report file and nothing else, so a filter it can add, change or remove is a declaration in that file. A given the model already declares and reads is imported by name, never declared again; if it is only a reader's filter, move it into the report instead (see \"Givens that stay in the model\").\n4. **COMPOSE THE FILE** at its path (the package root unless asked otherwise), following the template below, but do not save it yet. Name the sources you need in the import. Each tile binds its controls with a refinement, `view: t is v + { where: category ~ $CATEGORY }`, one clause per given it answers to; a `filter<...>` binds with `~`, a plain `date` or `number` given is a value and binds with `>=`, `<=` or `=`. Only the givens some tile references become controls. Then import every source or query any referenced given names in a `suggest`; **a `suggest` naming a `query=` needs that query's own source imported as well**, because an import is not transitive.\n5. **COMPILE IT** with your compile tool (`POST …/models/<path>/compile` over REST) at the path the file will have, with **`\"scope\": \"file\"`**: a report opens with an `import`, which the default `append` scope refuses, and an existing file compiled at `append` collides with itself. **`\"scope\": \"file\"` does not check tiles, drills or suggest queries.** To see those before you save, compile the same text at `\"scope\": \"package\"` with `modelPath` set to the report's path: it runs the lint step 6 reads and returns its findings with code `dashboard-lint` (or `render-tag`). Editing an untagged model several reports import also wants `\"scope\": \"package\"`, which recompiles every file as saved.\n6. **SAVE IT, RELOAD, AND READ THE MANIFEST AND THE WARNINGS.** Save by writing the file, or with `PUT …/models/<path>` over REST (omit `expectedHash` to create; it creates at any new path and replaces only a file the package already serves as a report). Then your reload tool, or `GET …/packages/<pkg>?reload=true`. A 424 means the package did not load and your edit is not live. **The `warnings` key is absent when there are none.** Then read `GET …/packages/<pkg>/reports/<path>`: its `givens` are exactly the controls that will render, and its `layout` is the layout Publisher read. See \"Read the lint\".\n7. **OPEN IT AND LOOK.** Not optional; see \"What done means\".\n\n## The form\n\n```malloy\n##! experimental.givens\n##\" One line saying what this report is for.\n##| artifact { layout=grid title=\"Storefront overview\"\n  tiles=[\n    intro { kind=text colspan=12 },\n    \"overview -> kpis\",\n    \"overview -> revenue_trend\",\n    \"overview -> revenue_by_state\"\n  ]\n} dashboard { columns=12 }\n|##\nimport { order_items, products } from \"storefront.malloy\"\n\n# label=\"Category\" control=select suggest { source=products dimension=category }\ngiven: CATEGORY :: filter<string> is f''\n# label=\"Ordered since\"\ngiven: SINCE :: date is @2023-01-01\n\n##|(markdown) intro\nRevenue and margin for the selected category.\n|##\n\nsource: overview is order_items extend {\n  # colspan=12\n  # label=\"Key figures\"\n  # big_value\n  view: kpis is key_figures + { where: category ~ $CATEGORY, where: created_at >= $SINCE }\n\n  # colspan=8\n  # break\n  # label=\"Revenue by month\"\n  view: revenue_trend is sales_by_month + { where: category ~ $CATEGORY, where: created_at >= $SINCE }\n\n  # colspan=4\n  # label=\"Revenue by state\"\n  view: revenue_by_state is sales_by_state + { where: category ~ $CATEGORY, where: created_at >= $SINCE }\n}\n```\n\nThe same file with `layout=linear` and no `dashboard { … }` or `colspan` is a linear report.\n\n- **The tag is model-level**, one line (`## artifact { … }`) or a `##|` … `|##` block with the same text inside, the form to use once the list is long: one tile per line, `}` on its own line, `|##` closing at the opener's column. A one-line `##` tag must stay on one line: wrapping it is a compile error, or worse, compiles clean and quietly stops being a report.\n- **The header** above the tag holds only `##!` flags, `//` comments and the unnamed `\"` notes that are the report's description. Keep statements and `#` tags below `## artifact`: nothing refuses one above it, but the header is where readers and the builder look.\n- **Quote every query entry.** `\"overview -> kpis\"` is a string; unquoted, the tag does not parse (`notebook-artifact-unparsed`). A bare quoted name (`\"top_products\"`) names a model-level `query:` in the file.\n- **A query tile is a thin `view:` on an extension the report declares** (`source: overview is order_items extend { … }`): the modelled view keeps its chart tag, the wrapper carries the tile's `# label`, its width on a grid, and its binding.\n- **A text tile is a `##|(markdown) name` block** listed as `name { kind=text }`. The name is one bare word on the opener line, the body starts on the next line (a heading goes inside the block), and `|##` closes it at the opener's column. A bare `intro` without `{ kind=text }` is the query-tile form for a `query:`, so the block is not shown. On a grid the entry also takes `colspan` and `break`, and nothing else.\n- **File order:** header, imports and givens, the prose blocks in tile order, then the extension that defines the tile views. That is the order the builder writes.\n- **A `run:` in a report that lists `tiles` is never shown** (`notebook-layout-run`). Define a view, list it, delete the `run:`.\n- **A tile expression is a string, so the compiler never checks it.** Rename a view and the file still compiles; the tile fails at package load, where the lint names it.\n- **Chart tags go on the view** (`# line_chart`, `# bar_chart`, `# big_value`, `# label=\"…\"`). `skill:malloy-charts` covers choosing them.\n\n## Filter controls\n\nControls come from the `given:` declarations the tiles reference. The tags on the declaration are the control contract:\n\n```malloy\n##! experimental.givens\n\n# label=\"Category\" control=select suggest { source=products dimension=category }\ngiven: CATEGORY :: filter<string> is f''\n\n# label=\"Brand\" control=multiselect suggest { query=brand_suggest dimension=brand }\ngiven: BRAND :: filter<string> is f''\n\n# label=\"Minimum line total\" range_min=0 range_max=250\ngiven: MIN_SALE :: filter<number> is f''\n\n# label=\"Ordered since\"\ngiven: SINCE :: date is @2023-01-01\n```\n\n`control=select`/`multiselect` with a `suggest` renders a picker filled from the data; `range_min`/`range_max` on a `filter<number>` renders a two-handled range slider; a `filter<date>` or `filter<timestamp>` renders a time-range control with preset windows and a custom day range; a bare `date` or `timestamp` renders a date picker; a `filter<string>` with no tag renders a text box taking filter syntax. Which controls appear is per report, decided by which givens its tiles reference.\n\n- `#(description=\"…\")` renders as helper text under the control and draws a cosmetic \"not a well-formed route\" compile diagnostic for a multi-word value; `# description=\"…\"` publishes to the API but the UI does not render it.\n- `dimension=` can name a field of a directly joined source, quoted: `suggest { source=sales dimension=\"products.department\" }`. On the `query=` form, `dimension` names a column of that query's output; match it to the query's `group_by`.\n- **A suggest's source or query has to resolve in the report file**, so import it there. Getting it wrong does not error: the control still looks like a picker and says \"Could not load the options for this control\"; the package warnings name it.\n- Two options on the artifact tag, either layout: `autorun=false` batches control changes behind an Apply button; `givens { CATEGORY=f'Outerwear' }` sets starting values (a URL parameter wins). A file-level `## autorun=false` does nothing on a `.malloy` report.\n\n### Binding, and givens that stay in the model\n\n**Binding is per declaration, not per name.** A report declaring its own `CATEGORY` over a source whose model-level `where:` reads the model's `CATEGORY` compiles, shows the control, and filters nothing. So bind on the tiles, with `+ { where: … }`. The other design, model-level scoping, still works: put a scoped source in an untagged model that imports the givens it reads, and import that model and those givens into the report. Do not mix the two on one given.\n\nA given stays in the model, declared once there, when a model source, view or measure, an `#(authorize)` or `#(access_filter)` gate, or an HTML data app reads it. The report imports it by name (`import { CATEGORY } from \"givens.malloy\"`) and never re-declares it:\n\n- **Import a name and also declare it: a compile error.** Drop the local declaration.\n- **Declare a name the model already reads, without importing it: no error at all.** The control renders and moves, and the model's own `where:` or gate never sees the value.\n\n**A model that already scopes a source by an optional filter given** (`where: Manufacturer ~ $manufacturer_filter` in the model) needs a decision:\n\n- **It is a reader's filter and you may change the model: move it.** Delete the given and its `where:` clause from the model, declare it in the report with its control tags, and bind it on each tile that should answer to it. A reader's filter is anything a person picks on the page; a given stays in the model only for the reasons `malloy-model` lists (a gate, a value every query must supply, a parameter a field is defined with, scoping meant for every consumer).\n- **The model can't change, or the given is semantic or governance: import it** as above. Say so plainly: the filter shows in the reader and in the builder, and can be set in both, but the builder cannot remove or reconfigure it. It is the model's.\n\nBefore, in the model:\n\n```malloy\n##! experimental.givens\ngiven:\n  manufacturer_filter :: filter<string> is f''\n  subject_filter :: filter<string> is f''\n  major_recall_filter :: filter<boolean> is f''\n  recall_date_filter :: filter<date> is f''\n\nsource: recalls is duckdb.table('data/auto_recalls.csv') extend {\n  where:\n    Manufacturer ~ $manufacturer_filter,\n    Subject ~ $subject_filter,\n    `Major Recall` ~ $major_recall_filter,\n    `Report Received Date` ~ $recall_date_filter\n  dimension: `Major Recall` is ifnull(`Potentially Affected`, 0) > 100000\n}\n```\n\nAfter: the model declares no givens and `recalls` has no `where:`; the report declares the four and binds each tile:\n\n```malloy\n##! experimental.givens\n##| artifact { layout=grid title=\"Recalls\"\n  tiles=[\"recalls_tiles -> recalls_by_year\", \"recalls_tiles -> recalls_by_manufacturer\"]\n} dashboard { columns=12 }\n|##\nimport { recalls } from \"auto_recalls.malloy\"\n\n# label=\"Manufacturer\" control=multiselect suggest { source=recalls dimension=Manufacturer }\ngiven: manufacturer_filter :: filter<string> is f''\n# label=\"Subject\"\ngiven: subject_filter :: filter<string> is f''\n# label=\"Major recalls only\"\ngiven: major_recall_filter :: filter<boolean> is f''\n# label=\"Filed\"\ngiven: recall_date_filter :: filter<date> is f''\n\nsource: recalls_tiles is recalls extend {\n  # colspan=6\n  view: recalls_by_year is by_year + {\n    where:\n      Manufacturer ~ $manufacturer_filter,\n      Subject ~ $subject_filter,\n      `Major Recall` ~ $major_recall_filter,\n      `Report Received Date` ~ $recall_date_filter\n  }\n  # colspan=6\n  view: recalls_by_manufacturer is by_manufacturer + {\n    where:\n      Subject ~ $subject_filter,\n      `Major Recall` ~ $major_recall_filter,\n      `Report Received Date` ~ $recall_date_filter\n  }\n}\n```\n\nA tile view takes a name of its own: `view: by_year is by_year + { … }` is \"Cannot redefine 'by_year'\". Each tile binds only the givens it should answer to: `recalls_by_manufacturer` leaves the manufacturer filter off, since it is the breakdown by manufacturer. Every given here is a `filter<…>`, so each binds with `~`; a plain `date` or `number` given binds with `>=`, `<=` or `=` (step 4).\n\nA given has to be in the report file's own scope to be bindable: declared there or imported. Never add a `#(filter)` annotation: it is deprecated, a report renders no control for it, and every use has a `given:` form (`malloy-model` covers the migration). `malloy-model` and `docs/givens.md` cover givens themselves.\n\n## Drill\n\n`# drill` goes on a model **dimension**, never on a report:\n\n```malloy\n# drill { to=[\"category\", \"self\"] given=CATEGORY }\ndimension: category is products.category\n\n# drill { to=\"regions/west\" given=REGION }\ndimension: region is regions.region\n```\n\n- **`to=<path>`** navigates to a report, of either layout, by its package path without `.malloy`, read from the package root: `to=category` is `category.malloy` at the root, `to=\"regions/west\"` is `regions/west.malloy`. Quote a path with a `/`. **Always write the path from the package root**: a bare name is a root file, never a report of that name elsewhere.\n- **`to=self`** filters in place; two or more destinations pop a menu.\n- **Always write `given=`.** Without it the given is the dimension name verbatim, so `dimension: category` seeds `category`, not `CATEGORY`. `to=self` survives that (it folds case); `to=<path>` does not, and lands on an unfiltered page with nothing erroring.\n- **The destination needs a control for the given**, declared as `filter<T>`. No lint checks that half, so click it and look.\n- **Only table cells are marked drillable.** A report meant to be drilled wants at least one untagged (table) tile, grouped by the tagged dimension. A column whose rendered header another, non-drillable tile also shows loses its marking: give the two different `# label=`s.\n\n## Read the lint\n\nPackage warnings after a reload are the report's test suite. Fix all of them, and read the text rather than the severity or the count. **\"Dashboard lint stopped early, so this list is incomplete\"** means the rest of the list is partial.\n\n| Finding                                                                                                 | Fix                                                                                                                               |\n| ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |\n| `# drill … targets \"x\", which is not a report in this package`                                          | A dead click. Write the target's path                                                                                             |\n| `to=self, but no model in this package declares a given \"X\"`                                            | The clicked value has nowhere to go. Declare the given, or fix `given=`                                                           |\n| `given \"X\" suggests options from source \"y\", which this file does not define`                           | Import `y` into the report                                                                                                        |\n| `filters by given \"X\", which this file does not import`                                                 | No control is shown for it. Import the given                                                                                      |\n| A tile that does not resolve to a real view                                                             | Fix the view name, or declare the view                                                                                            |\n| `notebook-artifact-unparsed`                                                                            | The tag does not parse, usually an unquoted `source -> view` entry                                                                |\n| `notebook-layout-run`                                                                                   | A `run:` beside `tiles`. Make it a view, list it, delete the `run:`                                                               |\n| `notebook-tile-layout-ignored`                                                                          | `colspan` or `break` on a linear report. Remove them, or switch to `layout=grid`                                                  |\n| `report-kind-removed`                                                                                   | The tag sets `kind=`, which is no longer read, so the file is no report. Write the `layout=` the finding gives                    |\n| `report-cells-removed`                                                                                  | A linear tag with no `tiles`, the retired cell format, so the file is no report. List its tiles (`reference/linear.md`)           |\n| `report-on-surface`                                                                                     | A model `index.malloy` imports (or `explores` lists) is tagged, so its sources left the surface. Untag it, or move the report out |\n| `index-is-not-a-report`                                                                                 | The root `index.malloy` carries a tag. Remove it; put the report in its own file                                                  |\n| `report-name-ambiguous`                                                                                 | Two grid reports share a file name, so the deprecated by-name dashboards route answers 409 for it. Rename one of the files        |\n| `Tile … reads <source>, which index.malloy doesn't export`                                              | Add the source to the `export { ... }` in `index.malloy`. Never add an `explores` to `publisher.json`                             |\n| A grid's `columns`, `colspan`, or `dashboard_columns=` findings                                         | `reference/grid.md`                                                                                                               |\n| Prose the reader cannot place (`notebook-markdown-attached-nowhere`, `notebook-markdown-block-unnamed`) | `reference/linear.md`                                                                                                             |\n\n**Read the status the reload itself returns, not the listing.** One report that fails to compile fails the whole package load (424), and a package already serving keeps its previous version, so the listing still looks healthy. `GET /api/v0/status` still knows: a package serving an older model than its files appears in `loadErrors` with `stale: true`. If the reload is 200 and your report is not listed, discovery skipped it: usually a missing or misspelled artifact tag, or a file under `public/`.\n\n**A clean reload is not proof the tags are right.** The parse warning is syntax only and carries no position. That is why the last step is opening the page.\n\n## Template\n\n```malloy\n##! experimental.givens\n##\" [One-line description of the report.]\n##| artifact { layout=linear title=\"[Title]\"\n  tiles=[\n    intro { kind=text },\n    \"main_source_tiles -> broad_tile\",\n    \"main_source_tiles -> drill_tile\"\n  ]\n}\n|##\nimport { main_source } from \"model.malloy\"\n\n##|(markdown) intro\n[Framing question: what are we trying to understand?]\n|##\n\nsource: main_source_tiles is main_source extend {\n  view: broad_tile is [broad view]\n  view: drill_tile is [drill view]\n}\n```\n\nFor a grid, write `layout=grid`, add `dashboard { columns=12 }` after the tag's closing `}`, and give every tile view a `# colspan` (`reference/grid.md`).\n\n## Editing in the Console\n\nA person can open any report in the Console's builder (**Edit** on the report page; **+ Report** on the package page writes `<slug>.malloy` at the package root). The builder splices the file rather than regenerating it, so comments and anything it does not model survive; it never rewrites `layout=`, so the layout is set in the file. A file written as `run:` cells, the retired linear form, is no report and does not open (`reference/linear.md`). A save whose text declares a real `#(authorize)` or `#(access_filter)` gate outside prose is refused with a 400: gates live in a model file the report imports.\n\n## What \"done\" means\n\n- The file is at the package root (or where the author asked), and its tag says `layout=`.\n- Every source, view, and field name came from the model you read in step 1.\n- The reload returned **200**, not 424, with **zero** report warnings, and your report is in `GET …/reports`.\n- You opened the page and every tile shows real numbers: not stuck loading, not an error, not an empty state you did not intend.\n- Each control renders as the widget you intended, and changing one changes the numbers.\n- If you added a `# drill`, its `to=` is a path, and you clicked it and landed where you meant to, with the given seeded.\n- On a grid: every tile carries a colspan, each row sums to `columns`, rows end flush, nothing is clipped, and no legend or card label ends in `…`.\n\n## Reference\n\n- `reference/grid.md`: the grid recipe, its traps, and one query as the whole page.\n- `reference/linear.md`: linear reports, rewriting a retired `run:`-cell file, legacy `.malloynb`, style, and common mistakes.\n- `docs/reports.md`: the full guide this skill condenses.\n- `docs/givens.md`: the givens the controls are generated from.\n\n## Reference files over MCP\n\nThis skill's `reference/` files are served as separate prompts, one per file, fetched only when you ask for them. Where the text above says to read `reference/<name>.md`, get the prompt named `malloy-reports/<name>` instead.\n\nAvailable: grid, linear."
     },
     {
       name: "malloy-reports/grid",
@@ -394475,7 +394809,7 @@ ${query}`);
   }
 }
 // package.json
-var version2 = "0.9.12";
+var version2 = "0.9.14";
 
 // src/version.ts
 var SERVER_VERSION = version2;
@@ -396446,6 +396780,817 @@ class MaterializationController {
   }
 }
 
+// src/controller/storage_destination.controller.ts
+init_errors();
+init_logger();
+
+// src/service/materialization_build_session.ts
+init_errors();
+init_logger();
+import { DuckDBConnection as DuckDBConnection4 } from "@malloydata/db-duckdb";
+import {
+  FixedConnectionMap as FixedConnectionMap3,
+  InMemoryURLReader as InMemoryURLReader3,
+  Runtime as Runtime4
+} from "@malloydata/malloy";
+import {
+  existsSync as existsSync3,
+  mkdirSync as mkdirSync3,
+  mkdtempSync as mkdtempSync2,
+  readdirSync as readdirSync3,
+  rmSync
+} from "node:fs";
+import os5 from "node:os";
+import path20 from "node:path";
+
+// src/service/build_query_tag.ts
+var MAX_QUERY_TAG_LENGTH = 2000;
+var BQ_MAX_LEN = 63;
+function snowflakeQueryTagValue(metadata) {
+  if (metadata === undefined || Object.keys(metadata).length === 0) {
+    return;
+  }
+  const tag = JSON.stringify(metadata);
+  return tag.length > MAX_QUERY_TAG_LENGTH ? undefined : tag;
+}
+function snowflakeSetQueryTagSQL(metadata, secretName) {
+  const tag = snowflakeQueryTagValue(metadata);
+  if (tag === undefined)
+    return;
+  const inner = `ALTER SESSION SET QUERY_TAG = '${sqlLiteral(tag, "snowflake")}'`;
+  return `SELECT * FROM snowflake_query('${inner.replace(/'/g, "''")}', '${secretName.replace(/'/g, "''")}')`;
+}
+function sanitizeBigQueryValue(value) {
+  return value.toLowerCase().replace(/[^a-z0-9_-]/g, "_").slice(0, BQ_MAX_LEN);
+}
+function sanitizeBigQueryKey(key) {
+  const sanitized = sanitizeBigQueryValue(key);
+  return /^[a-z]/.test(sanitized) ? sanitized : undefined;
+}
+function bigQueryQueryLabelValue(metadata) {
+  if (metadata === undefined)
+    return;
+  const rendered = new Map;
+  for (const [key, value] of Object.entries(metadata)) {
+    const sanitizedKey = sanitizeBigQueryKey(key);
+    if (sanitizedKey === undefined)
+      continue;
+    rendered.set(sanitizedKey, sanitizeBigQueryValue(value));
+  }
+  if (rendered.size === 0)
+    return;
+  return [...rendered].map(([key, value]) => `${key}:${value}`).join(",");
+}
+
+// src/service/build_read_cost.ts
+var SNOWFLAKE_HISTORY_LIMIT = 1e4;
+var BIGQUERY_COST_COLUMNS = `
+   total_slot_time_ms,
+   json_extract_string(statistics, '$.query.totalBytesProcessed') AS bytes_processed,
+   json_extract_string(statistics, '$.query.totalBytesBilled')    AS bytes_billed,
+   json_extract_string(statistics, '$.query.cacheHit')            AS cache_hit`;
+function bigQueryReadCost(row, jobId, parentJobId) {
+  return {
+    engine: "bigquery",
+    jobId,
+    parentJobId,
+    bytesScanned: num(row.bytes_processed),
+    bytesBilled: num(row.bytes_billed),
+    slotTimeMs: num(row.total_slot_time_ms),
+    executionTimeMs: null,
+    cacheHit: bool(row.cache_hit)
+  };
+}
+function snowflakeDatabaseQualifier(database) {
+  return typeof database === "string" && /^[A-Za-z_][A-Za-z0-9_$]*$/.test(database) ? database : "SNOWFLAKE";
+}
+function snowflakeCostSQL(queryTag, database) {
+  const qualifier = `${snowflakeDatabaseQualifier(database)}.INFORMATION_SCHEMA`;
+  return `
+      SELECT QUERY_ID       AS "job_id",
+             QUERY_TEXT     AS "query_text",
+             BYTES_SCANNED  AS "bytes_scanned",
+             EXECUTION_TIME AS "execution_time_ms",
+             ROWS_PRODUCED  AS "rows_produced"
+      FROM TABLE(${qualifier}.QUERY_HISTORY_BY_SESSION(
+                 RESULT_LIMIT => ${SNOWFLAKE_HISTORY_LIMIT}))
+      WHERE QUERY_TAG = '${sqlLiteral(queryTag, "snowflake")}'
+        AND EXECUTION_STATUS = 'SUCCESS'`;
+}
+function pickSnowflakeReadRow(rows, buildSQL) {
+  const matches = rows.filter((row) => str(col(row, "query_text"))?.trim() === buildSQL.trim());
+  return matches.length === 1 ? matches[0] : null;
+}
+function snowflakeReadCost(row) {
+  const scanned = num(col(row, "bytes_scanned"));
+  const produced = num(col(row, "rows_produced"));
+  return {
+    engine: "snowflake",
+    jobId: str(col(row, "job_id")),
+    parentJobId: null,
+    bytesScanned: scanned,
+    bytesBilled: null,
+    slotTimeMs: null,
+    executionTimeMs: num(col(row, "execution_time_ms")),
+    cacheHit: scanned === null || produced === null ? null : scanned === 0 && produced > 0
+  };
+}
+function col(row, key) {
+  if (key in row)
+    return row[key];
+  const upper = key.toUpperCase();
+  if (upper in row)
+    return row[upper];
+  const hit = Object.keys(row).find((k2) => k2.toLowerCase() === key);
+  return hit === undefined ? undefined : row[hit];
+}
+function num(value) {
+  if (value === null || value === undefined)
+    return null;
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+function str(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+function bool(value) {
+  if (typeof value === "boolean")
+    return value;
+  if (typeof value === "string") {
+    if (value === "true")
+      return true;
+    if (value === "false")
+      return false;
+  }
+  return null;
+}
+
+// src/service/materialization_build_session.ts
+var sharedGateSession;
+var PASSTHROUGH_SOURCE_TYPES = [
+  "bigquery",
+  "snowflake",
+  "postgres"
+];
+var STORAGE_DESTINATION_TYPES = ["ducklake", "duckdb"];
+var STORAGE_TARGET_DIALECT = "duckdb";
+function wrapPassthrough(sourceType, handle, innerSQL) {
+  const sql = `'${escapeSQL(innerSQL)}'`;
+  const h4 = `'${escapeSQL(handle)}'`;
+  switch (sourceType) {
+    case "bigquery":
+      return `SELECT * FROM bigquery_query(${h4}, ${sql})`;
+    case "postgres":
+      return `SELECT * FROM postgres_query(${h4}, ${sql})`;
+    case "snowflake":
+      return `SELECT * FROM snowflake_query(${sql}, ${h4})`;
+    default: {
+      const exhaustive = sourceType;
+      throw new BadRequestError(`Unsupported passthrough source type: ${String(exhaustive)}`);
+    }
+  }
+}
+function orderByPartitionColumns(selectSQL, partitionColumns, dialect) {
+  if (partitionColumns.length === 0) {
+    return selectSQL;
+  }
+  const order = partitionColumns.map((name) => quoteIdentifier(name, dialect)).join(", ");
+  const inner = selectSQL.replace(/[\s;]+$/, "");
+  return `SELECT * FROM (
+${inner}
+) AS partitioned_build ORDER BY ${order}`;
+}
+async function tagSnowflakeSession(session, sourceType, handle, queryMetadata) {
+  if (sourceType !== "snowflake")
+    return;
+  const sql = snowflakeSetQueryTagSQL(queryMetadata, handle);
+  if (sql === undefined)
+    return;
+  try {
+    await session.runSQL(sql);
+  } catch (error2) {
+    logger.warn("Could not tag the Snowflake build session", {
+      error: error2 instanceof Error ? error2.message : String(error2)
+    });
+    recordAttributionSkipped("tag_failed");
+  }
+}
+async function canSplitBigQueryRead(session, handle) {
+  try {
+    await session.runSQL(`SELECT job_id FROM bigquery_jobs('${escapeSQL(handle)}', maxResults := 1)`);
+    return true;
+  } catch (error2) {
+    logger.warn("Cannot list BigQuery jobs for this connection, so this build's " + "warehouse read will not be labelled or costed", {
+      error: error2 instanceof Error ? error2.message : String(error2)
+    });
+    recordAttributionSkipped("job_listing_unavailable");
+    return false;
+  }
+}
+
+class BilledReadNotCapturedError extends Error {
+  constructor(message, options) {
+    super(message, options);
+    this.name = "BilledReadNotCapturedError";
+  }
+}
+var BIGQUERY_LOOKUP_ATTEMPTS = 3;
+var BIGQUERY_LOOKUP_BACKOFF_MS = 250;
+async function withBigQueryLookupRetry(work, parentJobId) {
+  let lastError;
+  for (let attempt = 1;attempt <= BIGQUERY_LOOKUP_ATTEMPTS; attempt++) {
+    try {
+      return await work();
+    } catch (error2) {
+      lastError = error2;
+      if (attempt < BIGQUERY_LOOKUP_ATTEMPTS) {
+        logger.warn("Could not read the BigQuery job record for a build's read; retrying", {
+          attempt,
+          of: BIGQUERY_LOOKUP_ATTEMPTS,
+          parentJobId,
+          error: error2 instanceof Error ? error2.message : String(error2)
+        });
+        await new Promise((resolve7) => setTimeout(resolve7, BIGQUERY_LOOKUP_BACKOFF_MS * attempt));
+      }
+    }
+  }
+  throw new BilledReadNotCapturedError(`Could not read the BigQuery job record for a build's read (parent job ` + `${parentJobId}) after ${BIGQUERY_LOOKUP_ATTEMPTS} attempts, so its ` + `rows cannot be captured: ` + `${lastError instanceof Error ? lastError.message : String(lastError)}`, { cause: lastError });
+}
+async function issuePassthroughRead(session, sourceType, handle, buildSQL, queryMetadata) {
+  const label = sourceType === "bigquery" ? bigQueryQueryLabelValue(queryMetadata) : undefined;
+  if (label === undefined || !await canSplitBigQueryRead(session, handle)) {
+    return {
+      selectSQL: wrapPassthrough(sourceType, handle, buildSQL),
+      jobId: null,
+      cost: null
+    };
+  }
+  const script = `SET @@query_label = "${label}";
+${buildSQL};`;
+  const executed = await session.runSQL(`SELECT * FROM bigquery_execute('${escapeSQL(handle)}', '${escapeSQL(script)}')`);
+  const parentJobId = firstColumn(executed, "job_id");
+  if (parentJobId === null) {
+    throw new BilledReadNotCapturedError("bigquery_execute returned no job_id for the build's read, so its " + "result table cannot be located");
+  }
+  const located = await withBigQueryLookupRetry(async () => {
+    const child = await session.runSQL(`
+      SELECT job_id,
+             json_extract_string(configuration, '$.query.destinationTable.projectId') AS project,
+             json_extract_string(configuration, '$.query.destinationTable.datasetId') AS dataset,
+             json_extract_string(configuration, '$.query.destinationTable.tableId')   AS table,
+             ${BIGQUERY_COST_COLUMNS}
+      FROM (SELECT * FROM bigquery_jobs('${escapeSQL(handle)}',
+                                        parentJobId := '${escapeSQL(parentJobId)}')
+            WHERE job_type = 'QUERY')
+      ORDER BY creation_time DESC`);
+    const row = resultRows(child).find((r3) => str2(r3.dataset) && str2(r3.table));
+    if (row === undefined) {
+      throw new Error(`no child job with a result table under parent ${parentJobId}`);
+    }
+    return row;
+  }, parentJobId);
+  const path21 = [
+    str2(located.project) ?? handle,
+    str2(located.dataset),
+    str2(located.table)
+  ].join(".");
+  const jobId = str2(located.job_id);
+  return {
+    selectSQL: `SELECT * FROM bigquery_scan('${escapeSQL(path21)}')`,
+    jobId,
+    cost: bigQueryReadCost(located, jobId, parentJobId)
+  };
+}
+async function snowflakeReadCostAfterBuild(session, sourceType, handle, buildSQL, queryMetadata, database) {
+  if (sourceType !== "snowflake")
+    return null;
+  const tag = snowflakeQueryTagValue(queryMetadata);
+  if (tag === undefined)
+    return null;
+  try {
+    const costResult = await session.runSQL(passthroughSnowflake(snowflakeCostSQL(tag, database), handle));
+    const candidates = resultRows(costResult);
+    const row = pickSnowflakeReadRow(candidates, buildSQL);
+    if (row === null) {
+      recordAttributionSkipped(candidates.length === 0 ? "read_row_not_found" : "read_row_ambiguous");
+      return null;
+    }
+    return snowflakeReadCost(row);
+  } catch (error2) {
+    logger.warn("Could not read back what the Snowflake build read cost", {
+      error: error2 instanceof Error ? error2.message : String(error2)
+    });
+    recordAttributionSkipped("cost_query_failed");
+    return null;
+  }
+}
+function passthroughSnowflake(innerSQL, handle) {
+  return `SELECT * FROM snowflake_query('${escapeSQL(innerSQL)}', '${escapeSQL(handle)}')`;
+}
+function resultRows(result) {
+  if (Array.isArray(result))
+    return result;
+  const rows = result?.rows;
+  return Array.isArray(rows) ? rows : [];
+}
+function firstColumn(result, column) {
+  const rows = resultRows(result);
+  return rows.length > 0 ? str2(rows[0][column]) : null;
+}
+function str2(value) {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+async function clearSnowflakeSessionTag(session, sourceType, handle) {
+  if (sourceType !== "snowflake" || handle === undefined)
+    return;
+  try {
+    await session.runSQL(passthroughSnowflake("ALTER SESSION UNSET QUERY_TAG", handle));
+  } catch (error2) {
+    logger.warn("Could not clear the Snowflake build session's query tag", {
+      error: error2 instanceof Error ? error2.message : String(error2)
+    });
+  }
+}
+function passthroughSourceType(sourceConnection) {
+  const type = sourceConnection.type;
+  if (PASSTHROUGH_SOURCE_TYPES.includes(type ?? "")) {
+    return type;
+  }
+  throw new BadRequestError(`Cannot materialize a '${type}' source into a storage destination: the ` + `native query-passthrough build supports source connections of type ` + `${PASSTHROUGH_SOURCE_TYPES.join(", ")} only.`);
+}
+function createIsolatedBuildSession(sessionName) {
+  const workDir = mkdtempSync2(path20.join(os5.tmpdir(), "malloy-build-"));
+  let session;
+  try {
+    session = new DuckDBConnection4(sessionName, ":memory:", workDir, {
+      rowLimit: Number.MAX_SAFE_INTEGER
+    });
+  } catch (err) {
+    rmSync(workDir, { recursive: true, force: true });
+    throw err;
+  }
+  const dispose = async () => {
+    const nodeConnection = session.connection;
+    try {
+      await session.close();
+    } catch (err) {
+      logger.warn("Failed to close build session (leaked session)", {
+        sessionName,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+    try {
+      nodeConnection?.disconnectSync?.();
+    } catch (err) {
+      logger.warn("Failed to disconnect build session (leaked connection)", {
+        sessionName,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+    try {
+      rmSync(workDir, { recursive: true, force: true });
+    } catch (err) {
+      logger.warn("Failed to remove build session working directory", {
+        sessionName,
+        workDir,
+        error: err instanceof Error ? err.message : String(err)
+      });
+    }
+  };
+  return { session, dispose, workDir };
+}
+async function pinSessionToUTC(session) {
+  await session.runSQL("SET TimeZone='UTC'");
+}
+async function buildSourceIntoStorage(params) {
+  const {
+    destinationName,
+    destinationConnection,
+    sourceConnection,
+    buildSQL,
+    physicalTableName,
+    environmentPath,
+    queryMetadata
+  } = params;
+  const federate = params.deps?.federate ?? federateSourceForPassthrough;
+  const read = params.deps?.read ?? issuePassthroughRead;
+  assertSupportedDestination(destinationName, destinationConnection);
+  const sourceType = passthroughSourceType(sourceConnection);
+  const { session, dispose, workDir } = createIsolatedBuildSession(`build_${destinationName}`);
+  let federatedHandle;
+  let federatedClose;
+  try {
+    await applySessionResourceLimits(session, { tempDirectory: workDir });
+    await attachDestinationReadWrite(session, destinationName, destinationConnection, environmentPath);
+    if (destinationConnection.type === "ducklake") {
+      await session.runSQL("SET ducklake_default_data_inlining_row_limit=0");
+    }
+    await pinSessionToUTC(session);
+    const federated = await federate(session, sourceType, sourceFederationConfig(sourceConnection));
+    federatedClose = federated.close;
+    await tagSnowflakeSession(session, sourceType, federated.handle, queryMetadata);
+    const target = quoteManifestTablePath(`${destinationName}.${physicalTableName}`, STORAGE_TARGET_DIALECT);
+    if (params.incremental) {
+      const partitioned = (params.partitionColumns?.length ?? 0) > 0;
+      const flushThreshold = getPartitionedWriteFlushThreshold();
+      const boundDelta = partitioned && flushThreshold !== undefined;
+      if (boundDelta) {
+        await session.runSQL(`SET partitioned_write_flush_threshold = ${flushThreshold}`);
+        await session.runSQL("SET threads = 1");
+      }
+      let refreshed;
+      try {
+        refreshed = await params.incremental.plan({
+          session,
+          sourceType,
+          handle: federated.handle,
+          quotedTablePath: target
+        });
+      } finally {
+        if (boundDelta) {
+          try {
+            await session.runSQL("RESET threads");
+            await session.runSQL("RESET partitioned_write_flush_threshold");
+          } catch {}
+        }
+      }
+      if (refreshed) {
+        return {
+          storageDestinationName: destinationName,
+          schema: await describeTable(session, target),
+          readCost: refreshed.readCost,
+          refresh: refreshed
+        };
+      }
+    }
+    const passthrough = await read(session, sourceType, federated.handle, buildSQL, queryMetadata);
+    const schema = await createTableAndDescribe(session, target, passthrough.selectSQL, params.partitionColumns ?? [], { sourceType });
+    const seededThrough = await params.incremental?.afterSeed({
+      session,
+      quotedTablePath: target
+    });
+    return {
+      seededThrough,
+      storageDestinationName: destinationName,
+      schema,
+      readCost: passthrough.cost ?? await snowflakeReadCostAfterBuild(session, sourceType, federated.handle, buildSQL, queryMetadata, sourceConnection.snowflakeConnection?.database)
+    };
+  } finally {
+    await clearSnowflakeSessionTag(session, sourceType, federatedHandle);
+    await dispose();
+    if (federatedClose) {
+      await federatedClose().catch((e2) => logger.warn(`Failed to close the SSH proxy a storage build federated through: ${String(e2)}`));
+    }
+  }
+}
+async function buildDownstreamIntoStorage(params) {
+  const {
+    destinationName,
+    destinationConnection,
+    transientModel,
+    downstreamName,
+    virtualMap,
+    physicalTableName,
+    environmentPath
+  } = params;
+  assertSupportedDestination(destinationName, destinationConnection);
+  const { session, dispose, workDir } = createIsolatedBuildSession(`build_${destinationName}`);
+  try {
+    await applySessionResourceLimits(session, { tempDirectory: workDir });
+    await attachDestinationReadWrite(session, destinationName, destinationConnection, environmentPath);
+    if (destinationConnection.type === "ducklake") {
+      await session.runSQL("SET ducklake_default_data_inlining_row_limit=0");
+    }
+    await pinSessionToUTC(session);
+    const root = "file:///chained-build/";
+    const url3 = `${root}m.malloy`;
+    const runtime = new Runtime4({
+      urlReader: new InMemoryURLReader3(new Map([[url3, transientModel]])),
+      connections: new FixedConnectionMap3(new Map([[destinationName, session]]), destinationName)
+    });
+    let model;
+    try {
+      model = await runtime.loadModel(new URL(url3), { importBaseURL: new URL(root) }).getModel();
+    } catch (err) {
+      throw new MaterializationEligibilityError({
+        message: `Chained build model did not compile over the rebound parents: ${errMessage(err)}`
+      });
+    }
+    const plan = model.getBuildPlan();
+    let downstream;
+    for (const ps2 of Object.values(plan.sources)) {
+      if (ps2.name === downstreamName) {
+        downstream = ps2;
+        break;
+      }
+    }
+    if (!downstream) {
+      throw new MaterializationEligibilityError({
+        message: `Chained build model did not yield a persist source named ` + `'${downstreamName}' (the downstream references something the ` + `rebound parents don't provide).`
+      });
+    }
+    const sql = projectToPublicColumns(downstream, downstream.getSQL({ virtualMap }));
+    const target = quoteManifestTablePath(`${destinationName}.${physicalTableName}`, STORAGE_TARGET_DIALECT);
+    const schema = await createTableAndDescribe(session, target, sql, params.partitionColumns ?? []);
+    return {
+      storageDestinationName: destinationName,
+      schema,
+      readCost: null,
+      upstreamReuse: "reused"
+    };
+  } finally {
+    await dispose();
+  }
+}
+async function assertStorageServeShapeCompiles(params) {
+  const { destinationName, sourceName, virtualHandle, physicalTableName } = params;
+  const binding = {
+    sourceName,
+    destinationName,
+    virtualHandle,
+    tablePath: `${destinationName}.${physicalTableName}`,
+    schema: params.schema.filter((c3) => c3.name && c3.type).map((c3) => ({ name: c3.name, type: c3.type }))
+  };
+  sharedGateSession ??= createIsolatedBuildSession("gate_shared").session;
+  await applySessionResourceLimits(sharedGateSession);
+  await assertServesInDuckDB(sourceName, binding, new FixedConnectionMap3(new Map([[destinationName, sharedGateSession]]), destinationName));
+}
+function dropStorageTableSql(destinationName, physicalTableName) {
+  return `DROP TABLE IF EXISTS ${quoteManifestTablePath(`${destinationName}.${physicalTableName}`, STORAGE_TARGET_DIALECT)}`;
+}
+async function dropStorageTable(params) {
+  const {
+    destinationName,
+    destinationConnection,
+    physicalTableName,
+    environmentPath
+  } = params;
+  assertSupportedDestination(destinationName, destinationConnection);
+  const { session, dispose, workDir } = createIsolatedBuildSession(`gc_${destinationName}`);
+  try {
+    await applySessionResourceLimits(session, { tempDirectory: workDir });
+    await attachDestinationReadWrite(session, destinationName, destinationConnection, environmentPath);
+    await session.runSQL(dropStorageTableSql(destinationName, physicalTableName));
+  } finally {
+    await dispose();
+  }
+}
+async function listStorageTables(params) {
+  const {
+    destinationName,
+    destinationConnection,
+    schemaName,
+    environmentPath
+  } = params;
+  assertSupportedDestination(destinationName, destinationConnection);
+  const { session, dispose, workDir } = createIsolatedBuildSession(`list_${destinationName}`);
+  try {
+    await applySessionResourceLimits(session, { tempDirectory: workDir });
+    if (destinationConnection.type === "ducklake") {
+      const cfg = requireDuckLakeConfig(destinationName, destinationConnection);
+      await attachDuckLakeReadOnly(session, destinationName, cfg);
+    } else {
+      const destinationRoot = storageDestinationRoot(environmentPath);
+      const fileName = `${destinationName}.duckdb`;
+      if (!existsSync3(destinationRoot) || !readdirSync3(destinationRoot).includes(fileName)) {
+        return [];
+      }
+      const dbPath = path20.join(destinationRoot, fileName);
+      await session.runSQL(`ATTACH '${escapeSQL(dbPath)}' AS ${quoteIdentifier(destinationName, STORAGE_TARGET_DIALECT)} (READ_ONLY)`);
+    }
+    const rows = resultRows(await session.runSQL(`SELECT table_name FROM duckdb_tables() ` + `WHERE database_name = '${escapeSQL(destinationName)}' ` + `AND schema_name = '${escapeSQL(schemaName)}' ` + `ORDER BY table_name`));
+    return rows.map((row) => String(row.table_name));
+  } finally {
+    await dispose();
+  }
+}
+async function cleanupStorageFiles(params) {
+  const {
+    destinationName,
+    destinationConnection,
+    snapshotsOlderThan,
+    filesOlderThan
+  } = params;
+  if (destinationConnection.type !== "ducklake") {
+    throw new BadRequestError(`Storage destination '${destinationName}' is type ` + `'${destinationConnection.type ?? ""}'; file cleanup applies only to ` + `'ducklake' destinations.`);
+  }
+  const cfg = requireDuckLakeConfig(destinationName, destinationConnection);
+  const { session, dispose, workDir } = createIsolatedBuildSession(`cleanup_${destinationName}`);
+  try {
+    await applySessionResourceLimits(session, { tempDirectory: workDir });
+    await attachDuckLakeReadWrite(session, destinationName, cfg);
+    const catalog = escapeSQL(destinationName);
+    const expired = resultRows(await session.runSQL(`CALL ducklake_expire_snapshots('${catalog}', older_than => ` + `TIMESTAMPTZ '${snapshotsOlderThan.toISOString()}')`));
+    const deleted = resultRows(await session.runSQL(`CALL ducklake_cleanup_old_files('${catalog}', older_than => ` + `TIMESTAMPTZ '${filesOlderThan.toISOString()}')`));
+    return { expiredSnapshots: expired.length, deletedFiles: deleted.length };
+  } finally {
+    await dispose();
+  }
+}
+function requireDuckLakeConfig(destinationName, destinationConnection) {
+  const cfg = destinationConnection.ducklakeConnection;
+  if (!cfg) {
+    throw new BadRequestError(`Storage destination '${destinationName}' is type 'ducklake' but ` + `has no ducklakeConnection config.`);
+  }
+  return cfg;
+}
+function destinationDatabasePath(environmentPath, destinationName) {
+  return path20.join(storageDestinationRoot(environmentPath), `${destinationName}.duckdb`);
+}
+async function attachDestinationReadWrite(session, destinationName, destinationConnection, environmentPath) {
+  if (destinationConnection.type === "ducklake") {
+    const cfg = requireDuckLakeConfig(destinationName, destinationConnection);
+    await attachDuckLakeReadWrite(session, destinationName, cfg);
+    return;
+  }
+  mkdirSync3(storageDestinationRoot(environmentPath), { recursive: true });
+  const dbPath = destinationDatabasePath(environmentPath, destinationName);
+  await session.runSQL(`ATTACH '${escapeSQL(dbPath)}' AS ${quoteIdentifier(destinationName, STORAGE_TARGET_DIALECT)}`);
+}
+function assertSupportedDestination(destinationName, destinationConnection) {
+  const type = destinationConnection.type ?? "";
+  if (!STORAGE_DESTINATION_TYPES.includes(type)) {
+    throw new BadRequestError(`Storage destination '${destinationName}' is type '${type}', but ` + `'storage=' destinations must be one of ` + `${STORAGE_DESTINATION_TYPES.join(", ")}.`);
+  }
+}
+function sourceFederationConfig(sourceConnection) {
+  return {
+    name: sourceConnection.name ?? "src",
+    bigqueryConnection: sourceConnection.bigqueryConnection,
+    snowflakeConnection: sourceConnection.snowflakeConnection,
+    postgresConnection: sourceConnection.postgresConnection,
+    proxy: sourceConnection.proxy
+  };
+}
+async function createTableAndDescribe(session, quotedTablePath, selectSQL, partitionColumns = [], options = {}) {
+  if (partitionColumns.length === 0) {
+    await session.runSQL(`CREATE OR REPLACE TABLE ${quotedTablePath} AS (${selectSQL})`);
+    return await describeOrDrop(session, quotedTablePath);
+  }
+  const columns = partitionColumns.map((name) => quoteIdentifier(name, STORAGE_TARGET_DIALECT)).join(", ");
+  const flushThreshold = getPartitionedWriteFlushThreshold();
+  const bounded = options.sourceType !== undefined && flushThreshold !== undefined;
+  if (bounded) {
+    await session.runSQL(`SET partitioned_write_flush_threshold = ${flushThreshold}`);
+    await session.runSQL("SET threads = 1");
+  }
+  let schema;
+  await session.runSQL("BEGIN TRANSACTION");
+  try {
+    await session.runSQL(`CREATE OR REPLACE TABLE ${quotedTablePath} AS (${selectSQL}) WITH NO DATA`);
+    await session.runSQL(`ALTER TABLE ${quotedTablePath} SET PARTITIONED BY (${columns})`);
+    const inserted = bounded ? orderByPartitionColumns(selectSQL, partitionColumns, STORAGE_TARGET_DIALECT) : selectSQL;
+    await session.runSQL(`INSERT INTO ${quotedTablePath} (${inserted})`);
+    schema = await describeTable(session, quotedTablePath);
+    await session.runSQL("COMMIT");
+  } catch (buildErr) {
+    try {
+      await session.runSQL("ROLLBACK");
+    } catch (rollbackErr) {
+      logger.warn("Failed to roll back a partitioned storage build; the served " + "generation may have been replaced", {
+        table: quotedTablePath,
+        error: errMessage(rollbackErr),
+        cause: errMessage(buildErr)
+      });
+    }
+    throw buildErr;
+  } finally {
+    if (bounded) {
+      try {
+        await session.runSQL("RESET threads");
+      } catch {}
+    }
+  }
+  return schema;
+}
+async function describeOrDrop(session, quotedTablePath) {
+  try {
+    return await describeTable(session, quotedTablePath);
+  } catch (describeErr) {
+    await dropStranded(session, quotedTablePath, describeErr);
+    throw describeErr;
+  }
+}
+async function dropStranded(session, quotedTablePath, cause) {
+  try {
+    await session.runSQL(`DROP TABLE IF EXISTS ${quotedTablePath}`);
+  } catch (dropErr) {
+    logger.warn("Failed to drop a storage table stranded by a failed build " + "(physical leak)", {
+      table: quotedTablePath,
+      error: errMessage(dropErr),
+      cause: errMessage(cause)
+    });
+  }
+}
+async function describeTable(session, quotedTablePath) {
+  const result = await session.runSQL(`DESCRIBE ${quotedTablePath}`);
+  const rows = Array.isArray(result) ? result : result.rows ?? [];
+  const columns = [];
+  for (const row of rows) {
+    const name = row.column_name;
+    const type = row.column_type;
+    if (typeof name === "string" && typeof type === "string") {
+      columns.push({ name, type });
+    }
+  }
+  return columns;
+}
+
+// src/controller/storage_destination.controller.ts
+var IDENTIFIER = /^[a-zA-Z0-9_-]+$/;
+
+class StorageDestinationController {
+  environmentStore;
+  constructor(environmentStore) {
+    this.environmentStore = environmentStore;
+  }
+  async listTables(environmentName, destinationName, schemaName) {
+    assertIdentifier("schema", schemaName);
+    const { environment, destination } = await this.resolve(environmentName, destinationName);
+    const names = await listStorageTables({
+      destinationName,
+      destinationConnection: destination,
+      schemaName,
+      environmentPath: environment.getEnvironmentPath()
+    });
+    return names.map((name) => ({ name }));
+  }
+  async dropTable(environmentName, destinationName, schemaName, tableName) {
+    assertIdentifier("schema", schemaName);
+    assertIdentifier("table", tableName);
+    const { environment, destination } = await this.resolve(environmentName, destinationName);
+    try {
+      await dropStorageTable({
+        destinationName,
+        destinationConnection: destination,
+        physicalTableName: schemaName === "main" ? tableName : `${schemaName}.${tableName}`,
+        environmentPath: environment.getEnvironmentPath()
+      });
+    } catch (error2) {
+      recordDropTables("failure", "storage");
+      throw error2;
+    }
+    recordDropTables("success", "storage");
+    logger.info("Dropped a storage destination table", {
+      environmentName,
+      destinationName,
+      schemaName,
+      tableName
+    });
+  }
+  async createFileCleanup(environmentName, destinationName, body) {
+    const snapshotsOlderThan = requireTimestamp(body, "snapshotsOlderThan");
+    const filesOlderThan = requireTimestamp(body, "filesOlderThan");
+    const { destination } = await this.resolve(environmentName, destinationName);
+    const result = await cleanupStorageFiles({
+      destinationName,
+      destinationConnection: destination,
+      snapshotsOlderThan,
+      filesOlderThan
+    });
+    logger.info("Cleaned up a storage destination's retired files", {
+      environmentName,
+      destinationName,
+      snapshotsOlderThan: snapshotsOlderThan.toISOString(),
+      filesOlderThan: filesOlderThan.toISOString(),
+      ...result
+    });
+    return {
+      snapshotsOlderThan: snapshotsOlderThan.toISOString(),
+      filesOlderThan: filesOlderThan.toISOString(),
+      ...result
+    };
+  }
+  async resolve(environmentName, destinationName) {
+    assertIdentifier("storage destination", destinationName);
+    const environment = await this.environmentStore.getEnvironment(environmentName, false);
+    try {
+      return {
+        environment,
+        destination: environment.getStorageDestination(destinationName)
+      };
+    } catch (error2) {
+      if (error2 instanceof DestinationNotFoundError) {
+        throw new StorageDestinationNotFoundError(`Storage destination '${destinationName}' is not configured on ` + `environment '${environmentName}'.`);
+      }
+      throw error2;
+    }
+  }
+}
+function assertIdentifier(what, value) {
+  if (!IDENTIFIER.test(value)) {
+    throw new BadRequestError(`Invalid ${what} name '${value}': expected letters, digits, '_' or '-'.`);
+  }
+}
+function requireTimestamp(body, field) {
+  const raw = body?.[field];
+  const parsed = typeof raw === "string" ? new Date(raw) : undefined;
+  if (!parsed || Number.isNaN(parsed.getTime())) {
+    throw new BadRequestError(`'${field}' is required and must be an RFC 3339 date-time.`);
+  }
+  return parsed;
+}
+
 // src/controller/theme.controller.ts
 init_errors();
 class ThemeController {
@@ -396605,11 +397750,11 @@ function normalizeObjectSchema(schema) {
   }
   return;
 }
-function getDotPath(path20) {
-  if (path20.length === 0) {
+function getDotPath(path21) {
+  if (path21.length === 0) {
     return "object root";
   }
-  return path20.reduce((acc, seg, index) => {
+  return path21.reduce((acc, seg, index) => {
     if (index === 0) {
       return String(seg);
     }
@@ -401410,8 +402555,8 @@ function initializeMcpServer(environmentStore) {
 
 // src/mcp_config.ts
 import * as fs17 from "fs";
-import * as os5 from "os";
-import * as path20 from "path";
+import * as os6 from "os";
+import * as path21 from "path";
 init_logger();
 var MCP_CONFIG_FILENAME = ".mcp.json";
 function malloyServer(endpoint) {
@@ -401436,11 +402581,11 @@ function mcpEndpoint(host, port) {
   return `http://${host}:${port}/mcp`;
 }
 function findGitWorkTreeRoot(dir) {
-  let current = path20.resolve(dir);
+  let current = path21.resolve(dir);
   for (;; ) {
-    if (fs17.existsSync(path20.join(current, ".git")))
+    if (fs17.existsSync(path21.join(current, ".git")))
       return current;
-    const parent = path20.dirname(current);
+    const parent = path21.dirname(current);
     if (parent === current)
       return;
     current = parent;
@@ -401463,7 +402608,7 @@ function mcpConfigEnabled() {
 }
 function ensureMcpConfig(options) {
   const { dir, endpoint, requestedPort, boundPort, homeDir } = options;
-  const file = path20.join(dir, MCP_CONFIG_FILENAME);
+  const file = path21.join(dir, MCP_CONFIG_FILENAME);
   try {
     const existing = (() => {
       try {
@@ -401490,18 +402635,18 @@ function ensureMcpConfig(options) {
       try {
         return fs17.realpathSync(p2);
       } catch {
-        return path20.resolve(p2);
+        return path21.resolve(p2);
       }
     };
-    if (realish(dir) === realish(homeDir ?? os5.homedir())) {
+    if (realish(dir) === realish(homeDir ?? os6.homedir())) {
       return { action: "skipped-home", dir, endpoint, staleConfig };
     }
-    if (path20.resolve(dir) === path20.parse(path20.resolve(dir)).root) {
+    if (path21.resolve(dir) === path21.parse(path21.resolve(dir)).root) {
       return { action: "skipped-root", dir, endpoint, staleConfig };
     }
     const gitRoot = findGitWorkTreeRoot(dir);
     if (gitRoot !== undefined) {
-      const rootCandidate = path20.join(gitRoot, MCP_CONFIG_FILENAME);
+      const rootCandidate = path21.join(gitRoot, MCP_CONFIG_FILENAME);
       return {
         action: "skipped-git",
         dir,
@@ -402593,654 +403738,6 @@ function reportDeltaApplied(params) {
   logger.info("Applied an incremental delta", params);
 }
 
-// src/service/materialization_build_session.ts
-init_errors();
-init_logger();
-import { DuckDBConnection as DuckDBConnection4 } from "@malloydata/db-duckdb";
-import {
-  FixedConnectionMap as FixedConnectionMap3,
-  InMemoryURLReader as InMemoryURLReader3,
-  Runtime as Runtime4
-} from "@malloydata/malloy";
-import { mkdirSync as mkdirSync3, mkdtempSync as mkdtempSync2, rmSync } from "node:fs";
-import os6 from "node:os";
-import path21 from "node:path";
-
-// src/service/build_query_tag.ts
-var MAX_QUERY_TAG_LENGTH = 2000;
-var BQ_MAX_LEN = 63;
-function snowflakeQueryTagValue(metadata) {
-  if (metadata === undefined || Object.keys(metadata).length === 0) {
-    return;
-  }
-  const tag = JSON.stringify(metadata);
-  return tag.length > MAX_QUERY_TAG_LENGTH ? undefined : tag;
-}
-function snowflakeSetQueryTagSQL(metadata, secretName) {
-  const tag = snowflakeQueryTagValue(metadata);
-  if (tag === undefined)
-    return;
-  const inner = `ALTER SESSION SET QUERY_TAG = '${sqlLiteral(tag, "snowflake")}'`;
-  return `SELECT * FROM snowflake_query('${inner.replace(/'/g, "''")}', '${secretName.replace(/'/g, "''")}')`;
-}
-function sanitizeBigQueryValue(value) {
-  return value.toLowerCase().replace(/[^a-z0-9_-]/g, "_").slice(0, BQ_MAX_LEN);
-}
-function sanitizeBigQueryKey(key) {
-  const sanitized = sanitizeBigQueryValue(key);
-  return /^[a-z]/.test(sanitized) ? sanitized : undefined;
-}
-function bigQueryQueryLabelValue(metadata) {
-  if (metadata === undefined)
-    return;
-  const rendered = new Map;
-  for (const [key, value] of Object.entries(metadata)) {
-    const sanitizedKey = sanitizeBigQueryKey(key);
-    if (sanitizedKey === undefined)
-      continue;
-    rendered.set(sanitizedKey, sanitizeBigQueryValue(value));
-  }
-  if (rendered.size === 0)
-    return;
-  return [...rendered].map(([key, value]) => `${key}:${value}`).join(",");
-}
-
-// src/service/build_read_cost.ts
-var SNOWFLAKE_HISTORY_LIMIT = 1e4;
-var BIGQUERY_COST_COLUMNS = `
-   total_slot_time_ms,
-   json_extract_string(statistics, '$.query.totalBytesProcessed') AS bytes_processed,
-   json_extract_string(statistics, '$.query.totalBytesBilled')    AS bytes_billed,
-   json_extract_string(statistics, '$.query.cacheHit')            AS cache_hit`;
-function bigQueryReadCost(row, jobId, parentJobId) {
-  return {
-    engine: "bigquery",
-    jobId,
-    parentJobId,
-    bytesScanned: num(row.bytes_processed),
-    bytesBilled: num(row.bytes_billed),
-    slotTimeMs: num(row.total_slot_time_ms),
-    executionTimeMs: null,
-    cacheHit: bool(row.cache_hit)
-  };
-}
-function snowflakeDatabaseQualifier(database) {
-  return typeof database === "string" && /^[A-Za-z_][A-Za-z0-9_$]*$/.test(database) ? database : "SNOWFLAKE";
-}
-function snowflakeCostSQL(queryTag, database) {
-  const qualifier = `${snowflakeDatabaseQualifier(database)}.INFORMATION_SCHEMA`;
-  return `
-      SELECT QUERY_ID       AS "job_id",
-             QUERY_TEXT     AS "query_text",
-             BYTES_SCANNED  AS "bytes_scanned",
-             EXECUTION_TIME AS "execution_time_ms",
-             ROWS_PRODUCED  AS "rows_produced"
-      FROM TABLE(${qualifier}.QUERY_HISTORY_BY_SESSION(
-                 RESULT_LIMIT => ${SNOWFLAKE_HISTORY_LIMIT}))
-      WHERE QUERY_TAG = '${sqlLiteral(queryTag, "snowflake")}'
-        AND EXECUTION_STATUS = 'SUCCESS'`;
-}
-function pickSnowflakeReadRow(rows, buildSQL) {
-  const matches = rows.filter((row) => str(col(row, "query_text"))?.trim() === buildSQL.trim());
-  return matches.length === 1 ? matches[0] : null;
-}
-function snowflakeReadCost(row) {
-  const scanned = num(col(row, "bytes_scanned"));
-  const produced = num(col(row, "rows_produced"));
-  return {
-    engine: "snowflake",
-    jobId: str(col(row, "job_id")),
-    parentJobId: null,
-    bytesScanned: scanned,
-    bytesBilled: null,
-    slotTimeMs: null,
-    executionTimeMs: num(col(row, "execution_time_ms")),
-    cacheHit: scanned === null || produced === null ? null : scanned === 0 && produced > 0
-  };
-}
-function col(row, key) {
-  if (key in row)
-    return row[key];
-  const upper = key.toUpperCase();
-  if (upper in row)
-    return row[upper];
-  const hit = Object.keys(row).find((k2) => k2.toLowerCase() === key);
-  return hit === undefined ? undefined : row[hit];
-}
-function num(value) {
-  if (value === null || value === undefined)
-    return null;
-  const n = Number(value);
-  return Number.isFinite(n) ? n : null;
-}
-function str(value) {
-  return typeof value === "string" && value.length > 0 ? value : null;
-}
-function bool(value) {
-  if (typeof value === "boolean")
-    return value;
-  if (typeof value === "string") {
-    if (value === "true")
-      return true;
-    if (value === "false")
-      return false;
-  }
-  return null;
-}
-
-// src/service/materialization_build_session.ts
-var sharedGateSession;
-var PASSTHROUGH_SOURCE_TYPES = [
-  "bigquery",
-  "snowflake",
-  "postgres"
-];
-var STORAGE_DESTINATION_TYPES = ["ducklake", "duckdb"];
-var STORAGE_TARGET_DIALECT = "duckdb";
-function wrapPassthrough(sourceType, handle, innerSQL) {
-  const sql = `'${escapeSQL(innerSQL)}'`;
-  const h4 = `'${escapeSQL(handle)}'`;
-  switch (sourceType) {
-    case "bigquery":
-      return `SELECT * FROM bigquery_query(${h4}, ${sql})`;
-    case "postgres":
-      return `SELECT * FROM postgres_query(${h4}, ${sql})`;
-    case "snowflake":
-      return `SELECT * FROM snowflake_query(${sql}, ${h4})`;
-    default: {
-      const exhaustive = sourceType;
-      throw new BadRequestError(`Unsupported passthrough source type: ${String(exhaustive)}`);
-    }
-  }
-}
-function orderByPartitionColumns(selectSQL, partitionColumns, dialect) {
-  if (partitionColumns.length === 0) {
-    return selectSQL;
-  }
-  const order = partitionColumns.map((name) => quoteIdentifier(name, dialect)).join(", ");
-  const inner = selectSQL.replace(/[\s;]+$/, "");
-  return `SELECT * FROM (
-${inner}
-) AS partitioned_build ORDER BY ${order}`;
-}
-async function tagSnowflakeSession(session, sourceType, handle, queryMetadata) {
-  if (sourceType !== "snowflake")
-    return;
-  const sql = snowflakeSetQueryTagSQL(queryMetadata, handle);
-  if (sql === undefined)
-    return;
-  try {
-    await session.runSQL(sql);
-  } catch (error2) {
-    logger.warn("Could not tag the Snowflake build session", {
-      error: error2 instanceof Error ? error2.message : String(error2)
-    });
-    recordAttributionSkipped("tag_failed");
-  }
-}
-async function canSplitBigQueryRead(session, handle) {
-  try {
-    await session.runSQL(`SELECT job_id FROM bigquery_jobs('${escapeSQL(handle)}', maxResults := 1)`);
-    return true;
-  } catch (error2) {
-    logger.warn("Cannot list BigQuery jobs for this connection, so this build's " + "warehouse read will not be labelled or costed", {
-      error: error2 instanceof Error ? error2.message : String(error2)
-    });
-    recordAttributionSkipped("job_listing_unavailable");
-    return false;
-  }
-}
-
-class BilledReadNotCapturedError extends Error {
-  constructor(message, options) {
-    super(message, options);
-    this.name = "BilledReadNotCapturedError";
-  }
-}
-var BIGQUERY_LOOKUP_ATTEMPTS = 3;
-var BIGQUERY_LOOKUP_BACKOFF_MS = 250;
-async function withBigQueryLookupRetry(work, parentJobId) {
-  let lastError;
-  for (let attempt = 1;attempt <= BIGQUERY_LOOKUP_ATTEMPTS; attempt++) {
-    try {
-      return await work();
-    } catch (error2) {
-      lastError = error2;
-      if (attempt < BIGQUERY_LOOKUP_ATTEMPTS) {
-        logger.warn("Could not read the BigQuery job record for a build's read; retrying", {
-          attempt,
-          of: BIGQUERY_LOOKUP_ATTEMPTS,
-          parentJobId,
-          error: error2 instanceof Error ? error2.message : String(error2)
-        });
-        await new Promise((resolve8) => setTimeout(resolve8, BIGQUERY_LOOKUP_BACKOFF_MS * attempt));
-      }
-    }
-  }
-  throw new BilledReadNotCapturedError(`Could not read the BigQuery job record for a build's read (parent job ` + `${parentJobId}) after ${BIGQUERY_LOOKUP_ATTEMPTS} attempts, so its ` + `rows cannot be captured: ` + `${lastError instanceof Error ? lastError.message : String(lastError)}`, { cause: lastError });
-}
-async function issuePassthroughRead(session, sourceType, handle, buildSQL, queryMetadata) {
-  const label = sourceType === "bigquery" ? bigQueryQueryLabelValue(queryMetadata) : undefined;
-  if (label === undefined || !await canSplitBigQueryRead(session, handle)) {
-    return {
-      selectSQL: wrapPassthrough(sourceType, handle, buildSQL),
-      jobId: null,
-      cost: null
-    };
-  }
-  const script = `SET @@query_label = "${label}";
-${buildSQL};`;
-  const executed = await session.runSQL(`SELECT * FROM bigquery_execute('${escapeSQL(handle)}', '${escapeSQL(script)}')`);
-  const parentJobId = firstColumn(executed, "job_id");
-  if (parentJobId === null) {
-    throw new BilledReadNotCapturedError("bigquery_execute returned no job_id for the build's read, so its " + "result table cannot be located");
-  }
-  const located = await withBigQueryLookupRetry(async () => {
-    const child = await session.runSQL(`
-      SELECT job_id,
-             json_extract_string(configuration, '$.query.destinationTable.projectId') AS project,
-             json_extract_string(configuration, '$.query.destinationTable.datasetId') AS dataset,
-             json_extract_string(configuration, '$.query.destinationTable.tableId')   AS table,
-             ${BIGQUERY_COST_COLUMNS}
-      FROM (SELECT * FROM bigquery_jobs('${escapeSQL(handle)}',
-                                        parentJobId := '${escapeSQL(parentJobId)}')
-            WHERE job_type = 'QUERY')
-      ORDER BY creation_time DESC`);
-    const row = resultRows(child).find((r3) => str2(r3.dataset) && str2(r3.table));
-    if (row === undefined) {
-      throw new Error(`no child job with a result table under parent ${parentJobId}`);
-    }
-    return row;
-  }, parentJobId);
-  const path22 = [
-    str2(located.project) ?? handle,
-    str2(located.dataset),
-    str2(located.table)
-  ].join(".");
-  const jobId = str2(located.job_id);
-  return {
-    selectSQL: `SELECT * FROM bigquery_scan('${escapeSQL(path22)}')`,
-    jobId,
-    cost: bigQueryReadCost(located, jobId, parentJobId)
-  };
-}
-async function snowflakeReadCostAfterBuild(session, sourceType, handle, buildSQL, queryMetadata, database) {
-  if (sourceType !== "snowflake")
-    return null;
-  const tag = snowflakeQueryTagValue(queryMetadata);
-  if (tag === undefined)
-    return null;
-  try {
-    const costResult = await session.runSQL(passthroughSnowflake(snowflakeCostSQL(tag, database), handle));
-    const candidates = resultRows(costResult);
-    const row = pickSnowflakeReadRow(candidates, buildSQL);
-    if (row === null) {
-      recordAttributionSkipped(candidates.length === 0 ? "read_row_not_found" : "read_row_ambiguous");
-      return null;
-    }
-    return snowflakeReadCost(row);
-  } catch (error2) {
-    logger.warn("Could not read back what the Snowflake build read cost", {
-      error: error2 instanceof Error ? error2.message : String(error2)
-    });
-    recordAttributionSkipped("cost_query_failed");
-    return null;
-  }
-}
-function passthroughSnowflake(innerSQL, handle) {
-  return `SELECT * FROM snowflake_query('${escapeSQL(innerSQL)}', '${escapeSQL(handle)}')`;
-}
-function resultRows(result) {
-  if (Array.isArray(result))
-    return result;
-  const rows = result?.rows;
-  return Array.isArray(rows) ? rows : [];
-}
-function firstColumn(result, column) {
-  const rows = resultRows(result);
-  return rows.length > 0 ? str2(rows[0][column]) : null;
-}
-function str2(value) {
-  return typeof value === "string" && value.length > 0 ? value : null;
-}
-async function clearSnowflakeSessionTag(session, sourceType, handle) {
-  if (sourceType !== "snowflake" || handle === undefined)
-    return;
-  try {
-    await session.runSQL(passthroughSnowflake("ALTER SESSION UNSET QUERY_TAG", handle));
-  } catch (error2) {
-    logger.warn("Could not clear the Snowflake build session's query tag", {
-      error: error2 instanceof Error ? error2.message : String(error2)
-    });
-  }
-}
-function passthroughSourceType(sourceConnection) {
-  const type = sourceConnection.type;
-  if (PASSTHROUGH_SOURCE_TYPES.includes(type ?? "")) {
-    return type;
-  }
-  throw new BadRequestError(`Cannot materialize a '${type}' source into a storage destination: the ` + `native query-passthrough build supports source connections of type ` + `${PASSTHROUGH_SOURCE_TYPES.join(", ")} only.`);
-}
-function createIsolatedBuildSession(sessionName) {
-  const workDir = mkdtempSync2(path21.join(os6.tmpdir(), "malloy-build-"));
-  let session;
-  try {
-    session = new DuckDBConnection4(sessionName, ":memory:", workDir, {
-      rowLimit: Number.MAX_SAFE_INTEGER
-    });
-  } catch (err) {
-    rmSync(workDir, { recursive: true, force: true });
-    throw err;
-  }
-  const dispose = async () => {
-    const nodeConnection = session.connection;
-    try {
-      await session.close();
-    } catch (err) {
-      logger.warn("Failed to close build session (leaked session)", {
-        sessionName,
-        error: err instanceof Error ? err.message : String(err)
-      });
-    }
-    try {
-      nodeConnection?.disconnectSync?.();
-    } catch (err) {
-      logger.warn("Failed to disconnect build session (leaked connection)", {
-        sessionName,
-        error: err instanceof Error ? err.message : String(err)
-      });
-    }
-    try {
-      rmSync(workDir, { recursive: true, force: true });
-    } catch (err) {
-      logger.warn("Failed to remove build session working directory", {
-        sessionName,
-        workDir,
-        error: err instanceof Error ? err.message : String(err)
-      });
-    }
-  };
-  return { session, dispose, workDir };
-}
-async function pinSessionToUTC(session) {
-  await session.runSQL("SET TimeZone='UTC'");
-}
-async function buildSourceIntoStorage(params) {
-  const {
-    destinationName,
-    destinationConnection,
-    sourceConnection,
-    buildSQL,
-    physicalTableName,
-    environmentPath,
-    queryMetadata
-  } = params;
-  const federate = params.deps?.federate ?? federateSourceForPassthrough;
-  const read = params.deps?.read ?? issuePassthroughRead;
-  assertSupportedDestination(destinationName, destinationConnection);
-  const sourceType = passthroughSourceType(sourceConnection);
-  const { session, dispose, workDir } = createIsolatedBuildSession(`build_${destinationName}`);
-  let federatedHandle;
-  let federatedClose;
-  try {
-    await applySessionResourceLimits(session, { tempDirectory: workDir });
-    await attachDestinationReadWrite(session, destinationName, destinationConnection, environmentPath);
-    if (destinationConnection.type === "ducklake") {
-      await session.runSQL("SET ducklake_default_data_inlining_row_limit=0");
-    }
-    await pinSessionToUTC(session);
-    const federated = await federate(session, sourceType, sourceFederationConfig(sourceConnection));
-    federatedClose = federated.close;
-    await tagSnowflakeSession(session, sourceType, federated.handle, queryMetadata);
-    const target = quoteManifestTablePath(`${destinationName}.${physicalTableName}`, STORAGE_TARGET_DIALECT);
-    if (params.incremental) {
-      const partitioned = (params.partitionColumns?.length ?? 0) > 0;
-      const flushThreshold = getPartitionedWriteFlushThreshold();
-      const boundDelta = partitioned && flushThreshold !== undefined;
-      if (boundDelta) {
-        await session.runSQL(`SET partitioned_write_flush_threshold = ${flushThreshold}`);
-        await session.runSQL("SET threads = 1");
-      }
-      let refreshed;
-      try {
-        refreshed = await params.incremental.plan({
-          session,
-          sourceType,
-          handle: federated.handle,
-          quotedTablePath: target
-        });
-      } finally {
-        if (boundDelta) {
-          try {
-            await session.runSQL("RESET threads");
-            await session.runSQL("RESET partitioned_write_flush_threshold");
-          } catch {}
-        }
-      }
-      if (refreshed) {
-        return {
-          storageDestinationName: destinationName,
-          schema: await describeTable(session, target),
-          readCost: refreshed.readCost,
-          refresh: refreshed
-        };
-      }
-    }
-    const passthrough = await read(session, sourceType, federated.handle, buildSQL, queryMetadata);
-    const schema = await createTableAndDescribe(session, target, passthrough.selectSQL, params.partitionColumns ?? [], { sourceType });
-    const seededThrough = await params.incremental?.afterSeed({
-      session,
-      quotedTablePath: target
-    });
-    return {
-      seededThrough,
-      storageDestinationName: destinationName,
-      schema,
-      readCost: passthrough.cost ?? await snowflakeReadCostAfterBuild(session, sourceType, federated.handle, buildSQL, queryMetadata, sourceConnection.snowflakeConnection?.database)
-    };
-  } finally {
-    await clearSnowflakeSessionTag(session, sourceType, federatedHandle);
-    await dispose();
-    if (federatedClose) {
-      await federatedClose().catch((e2) => logger.warn(`Failed to close the SSH proxy a storage build federated through: ${String(e2)}`));
-    }
-  }
-}
-async function buildDownstreamIntoStorage(params) {
-  const {
-    destinationName,
-    destinationConnection,
-    transientModel,
-    downstreamName,
-    virtualMap,
-    physicalTableName,
-    environmentPath
-  } = params;
-  assertSupportedDestination(destinationName, destinationConnection);
-  const { session, dispose, workDir } = createIsolatedBuildSession(`build_${destinationName}`);
-  try {
-    await applySessionResourceLimits(session, { tempDirectory: workDir });
-    await attachDestinationReadWrite(session, destinationName, destinationConnection, environmentPath);
-    if (destinationConnection.type === "ducklake") {
-      await session.runSQL("SET ducklake_default_data_inlining_row_limit=0");
-    }
-    await pinSessionToUTC(session);
-    const root = "file:///chained-build/";
-    const url3 = `${root}m.malloy`;
-    const runtime = new Runtime4({
-      urlReader: new InMemoryURLReader3(new Map([[url3, transientModel]])),
-      connections: new FixedConnectionMap3(new Map([[destinationName, session]]), destinationName)
-    });
-    let model;
-    try {
-      model = await runtime.loadModel(new URL(url3), { importBaseURL: new URL(root) }).getModel();
-    } catch (err) {
-      throw new MaterializationEligibilityError({
-        message: `Chained build model did not compile over the rebound parents: ${errMessage(err)}`
-      });
-    }
-    const plan = model.getBuildPlan();
-    let downstream;
-    for (const ps2 of Object.values(plan.sources)) {
-      if (ps2.name === downstreamName) {
-        downstream = ps2;
-        break;
-      }
-    }
-    if (!downstream) {
-      throw new MaterializationEligibilityError({
-        message: `Chained build model did not yield a persist source named ` + `'${downstreamName}' (the downstream references something the ` + `rebound parents don't provide).`
-      });
-    }
-    const sql = projectToPublicColumns(downstream, downstream.getSQL({ virtualMap }));
-    const target = quoteManifestTablePath(`${destinationName}.${physicalTableName}`, STORAGE_TARGET_DIALECT);
-    const schema = await createTableAndDescribe(session, target, sql, params.partitionColumns ?? []);
-    return {
-      storageDestinationName: destinationName,
-      schema,
-      readCost: null,
-      upstreamReuse: "reused"
-    };
-  } finally {
-    await dispose();
-  }
-}
-async function assertStorageServeShapeCompiles(params) {
-  const { destinationName, sourceName, virtualHandle, physicalTableName } = params;
-  const binding = {
-    sourceName,
-    destinationName,
-    virtualHandle,
-    tablePath: `${destinationName}.${physicalTableName}`,
-    schema: params.schema.filter((c3) => c3.name && c3.type).map((c3) => ({ name: c3.name, type: c3.type }))
-  };
-  sharedGateSession ??= createIsolatedBuildSession("gate_shared").session;
-  await applySessionResourceLimits(sharedGateSession);
-  await assertServesInDuckDB(sourceName, binding, new FixedConnectionMap3(new Map([[destinationName, sharedGateSession]]), destinationName));
-}
-function dropStorageTableSql(destinationName, physicalTableName) {
-  return `DROP TABLE IF EXISTS ${quoteManifestTablePath(`${destinationName}.${physicalTableName}`, STORAGE_TARGET_DIALECT)}`;
-}
-async function dropStorageTable(params) {
-  const {
-    destinationName,
-    destinationConnection,
-    physicalTableName,
-    environmentPath
-  } = params;
-  assertSupportedDestination(destinationName, destinationConnection);
-  const { session, dispose, workDir } = createIsolatedBuildSession(`gc_${destinationName}`);
-  try {
-    await applySessionResourceLimits(session, { tempDirectory: workDir });
-    await attachDestinationReadWrite(session, destinationName, destinationConnection, environmentPath);
-    await session.runSQL(dropStorageTableSql(destinationName, physicalTableName));
-  } finally {
-    await dispose();
-  }
-}
-async function attachDestinationReadWrite(session, destinationName, destinationConnection, environmentPath) {
-  if (destinationConnection.type === "ducklake") {
-    const cfg = destinationConnection.ducklakeConnection;
-    if (!cfg) {
-      throw new BadRequestError(`Storage destination '${destinationName}' is type 'ducklake' but ` + `has no ducklakeConnection config.`);
-    }
-    await attachDuckLakeReadWrite(session, destinationName, cfg);
-    return;
-  }
-  const destinationRoot = storageDestinationRoot(environmentPath);
-  mkdirSync3(destinationRoot, { recursive: true });
-  const dbPath = path21.join(destinationRoot, `${destinationName}.duckdb`);
-  await session.runSQL(`ATTACH '${escapeSQL(dbPath)}' AS ${quoteIdentifier(destinationName, STORAGE_TARGET_DIALECT)}`);
-}
-function assertSupportedDestination(destinationName, destinationConnection) {
-  const type = destinationConnection.type ?? "";
-  if (!STORAGE_DESTINATION_TYPES.includes(type)) {
-    throw new BadRequestError(`Storage destination '${destinationName}' is type '${type}', but ` + `'storage=' destinations must be one of ` + `${STORAGE_DESTINATION_TYPES.join(", ")}.`);
-  }
-}
-function sourceFederationConfig(sourceConnection) {
-  return {
-    name: sourceConnection.name ?? "src",
-    bigqueryConnection: sourceConnection.bigqueryConnection,
-    snowflakeConnection: sourceConnection.snowflakeConnection,
-    postgresConnection: sourceConnection.postgresConnection,
-    proxy: sourceConnection.proxy
-  };
-}
-async function createTableAndDescribe(session, quotedTablePath, selectSQL, partitionColumns = [], options = {}) {
-  if (partitionColumns.length === 0) {
-    await session.runSQL(`CREATE OR REPLACE TABLE ${quotedTablePath} AS (${selectSQL})`);
-    return await describeOrDrop(session, quotedTablePath);
-  }
-  const columns = partitionColumns.map((name) => quoteIdentifier(name, STORAGE_TARGET_DIALECT)).join(", ");
-  const flushThreshold = getPartitionedWriteFlushThreshold();
-  const bounded = options.sourceType !== undefined && flushThreshold !== undefined;
-  if (bounded) {
-    await session.runSQL(`SET partitioned_write_flush_threshold = ${flushThreshold}`);
-    await session.runSQL("SET threads = 1");
-  }
-  let schema;
-  await session.runSQL("BEGIN TRANSACTION");
-  try {
-    await session.runSQL(`CREATE OR REPLACE TABLE ${quotedTablePath} AS (${selectSQL}) WITH NO DATA`);
-    await session.runSQL(`ALTER TABLE ${quotedTablePath} SET PARTITIONED BY (${columns})`);
-    const inserted = bounded ? orderByPartitionColumns(selectSQL, partitionColumns, STORAGE_TARGET_DIALECT) : selectSQL;
-    await session.runSQL(`INSERT INTO ${quotedTablePath} (${inserted})`);
-    schema = await describeTable(session, quotedTablePath);
-    await session.runSQL("COMMIT");
-  } catch (buildErr) {
-    try {
-      await session.runSQL("ROLLBACK");
-    } catch (rollbackErr) {
-      logger.warn("Failed to roll back a partitioned storage build; the served " + "generation may have been replaced", {
-        table: quotedTablePath,
-        error: errMessage(rollbackErr),
-        cause: errMessage(buildErr)
-      });
-    }
-    throw buildErr;
-  } finally {
-    if (bounded) {
-      try {
-        await session.runSQL("RESET threads");
-      } catch {}
-    }
-  }
-  return schema;
-}
-async function describeOrDrop(session, quotedTablePath) {
-  try {
-    return await describeTable(session, quotedTablePath);
-  } catch (describeErr) {
-    await dropStranded(session, quotedTablePath, describeErr);
-    throw describeErr;
-  }
-}
-async function dropStranded(session, quotedTablePath, cause) {
-  try {
-    await session.runSQL(`DROP TABLE IF EXISTS ${quotedTablePath}`);
-  } catch (dropErr) {
-    logger.warn("Failed to drop a storage table stranded by a failed build " + "(physical leak)", {
-      table: quotedTablePath,
-      error: errMessage(dropErr),
-      cause: errMessage(cause)
-    });
-  }
-}
-async function describeTable(session, quotedTablePath) {
-  const result = await session.runSQL(`DESCRIBE ${quotedTablePath}`);
-  const rows = Array.isArray(result) ? result : result.rows ?? [];
-  const columns = [];
-  for (const row of rows) {
-    const name = row.column_name;
-    const type = row.column_type;
-    if (typeof name === "string" && typeof type === "string") {
-      columns.push({ name, type });
-    }
-  }
-  return columns;
-}
-
 // src/service/incremental_storage.ts
 function storageDeltaTarget(params) {
   const {
@@ -406447,6 +406944,7 @@ var databaseController = new DatabaseController(environmentStore);
 var queryController = new QueryController(environmentStore);
 var compileController = new CompileController(environmentStore);
 var materializationService = new MaterializationService(environmentStore);
+var storageDestinationController = new StorageDestinationController(environmentStore);
 var materializationController = new MaterializationController(materializationService);
 function startMaterializationSchedulerFromEnv(store, service) {
   const config2 = getMaterializationSchedulerConfig();
@@ -407328,6 +407826,31 @@ app.delete(`${API_PREFIX2}/environments/:environmentName/packages/:packageName/m
     res.status(status).json(json2);
   }
 });
+app.get(`${API_PREFIX2}/environments/:environmentName/storageDestinations/:destinationName/schemas/:schemaName/tables`, async (req, res) => {
+  try {
+    res.status(200).json(await storageDestinationController.listTables(req.params.environmentName, req.params.destinationName, req.params.schemaName));
+  } catch (error2) {
+    const { json: json2, status } = internalErrorToHttpError(error2);
+    res.status(status).json(json2);
+  }
+});
+app.delete(`${API_PREFIX2}/environments/:environmentName/storageDestinations/:destinationName/schemas/:schemaName/tables/:tableName`, async (req, res) => {
+  try {
+    await storageDestinationController.dropTable(req.params.environmentName, req.params.destinationName, req.params.schemaName, req.params.tableName);
+    res.status(204).send();
+  } catch (error2) {
+    const { json: json2, status } = internalErrorToHttpError(error2);
+    res.status(status).json(json2);
+  }
+});
+app.post(`${API_PREFIX2}/environments/:environmentName/storageDestinations/:destinationName/fileCleanups`, async (req, res) => {
+  try {
+    res.status(201).json(await storageDestinationController.createFileCleanup(req.params.environmentName, req.params.destinationName, req.body ?? {}));
+  } catch (error2) {
+    const { json: json2, status } = internalErrorToHttpError(error2);
+    res.status(status).json(json2);
+  }
+});
 registerLegacyRoutes(app, {
   environmentStore,
   connectionController,