@malloy-publisher/server 0.10.2 → 0.10.3

package/dist/app/index.html

@@ -16,7 +16,7 @@ SPDX-License-Identifier: MIT
          href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=JetBrains+Mono:wght@400;500&display=swap"
       />
       <title>Malloy Publisher</title>
-     <script type="module" crossorigin src="/assets/index-iyvwQg3j.js"></script>
+     <script type="module" crossorigin src="/assets/index-CGKV9Dxi.js"></script>
      <link rel="stylesheet" crossorigin href="/assets/index-DUqldpo0.css">
    </head>
    <body>

package/dist/instrumentation.mjs

@@ -164831,7 +164831,7 @@ var init_telemetry = __esm(() => {
 });
 
 // package.json
-var version = "0.10.2";
+var version = "0.10.3";
 var init_package = () => {};
 
 // src/version.ts

package/dist/server.mjs

@@ -164832,7 +164832,7 @@ var init_telemetry = __esm(() => {
 });
 
 // package.json
-var version = "0.10.2";
+var version = "0.10.3";
 var init_package = () => {};
 
 // src/version.ts
@@ -296720,6 +296720,47 @@ var init_connection_public_view = __esm(() => {
   ];
 });
 
+// src/service/single_select.ts
+import { DuckDBInstance } from "@duckdb/node-api";
+async function parserInstance() {
+  if (!parser) {
+    parser = DuckDBInstance.create(":memory:", {
+      threads: "1",
+      enable_external_access: "false"
+    }).catch((error) => {
+      parser = undefined;
+      throw error;
+    });
+  }
+  return parser;
+}
+async function classifySelect(sql) {
+  const connection = await (await parserInstance()).connect();
+  try {
+    const prepared = await connection.prepare("SELECT json_serialize_sql($1::VARCHAR) AS j");
+    prepared.bindVarchar(1, sql);
+    const rows = await (await prepared.run()).getRowObjectsJson();
+    const parsed = JSON.parse(String(rows[0]?.j));
+    if (parsed.error) {
+      return { refused: parsed.error_message ?? "it could not be parsed" };
+    }
+    return { selects: parsed.statements?.length ?? 0 };
+  } finally {
+    connection.closeSync();
+  }
+}
+async function assertSingleSelect(connectionName, sql) {
+  const verdict = await classifySelect(sql);
+  if ("selects" in verdict && verdict.selects === 1)
+    return;
+  const why = "refused" in verdict ? "it is not a SELECT" : verdict.selects === 0 ? "it holds no statement" : `it holds ${verdict.selects} statements`;
+  throw new BadRequestError(`'${connectionName}' is a managed database: raw SQL on it runs only as a single SELECT, and ${why}.`);
+}
+var parser;
+var init_single_select = __esm(() => {
+  init_errors();
+});
+
 // src/service/connection_service.ts
 async function runEnvironmentConnectionUpdate(environment, fn) {
   if (environment.runConnectionUpdateExclusive) {
@@ -305614,6 +305655,15 @@ class ConnectionController {
     }
     return environment.getApiConnection(connectionName);
   }
+  isManagedConnection(environment, connectionName) {
+    try {
+      return this.getApiConnectionForLookup(environment, connectionName).managed === true;
+    } catch (error) {
+      if (error instanceof ConnectionNotFoundError)
+        return false;
+      throw error;
+    }
+  }
   async connectionQueryMetadata(environmentName, connectionName) {
     try {
       const environment = await this.environmentStore.getEnvironment(environmentName, false);
@@ -305736,6 +305786,10 @@ class ConnectionController {
     return withDatabaseAccessClassified(() => listTablesForSchema(connection, schemaName, malloyConnection, tableNames));
   }
   async getConnectionSqlSource(environmentName, connectionName, sqlStatement, packageName) {
+    const environment = await this.environmentStore.getEnvironment(environmentName, false);
+    if (this.isManagedConnection(environment, connectionName)) {
+      await assertSingleSelect(connectionName, sqlStatement);
+    }
     const malloyConnection = await this.getMalloyConnection(environmentName, connectionName, packageName);
     try {
       const schema = await malloyConnection.fetchSelectSchema({
@@ -305796,6 +305850,9 @@ class ConnectionController {
     }
     const environmentForAdmission = await this.environmentStore.getEnvironment(environmentName, false);
     environmentForAdmission.assertCanAdmitQuery();
+    if (this.isManagedConnection(environmentForAdmission, connectionName)) {
+      await assertSingleSelect(connectionName, sqlStatement);
+    }
     const malloyConnection = await this.getMalloyConnection(environmentName, connectionName, packageName);
     let runSQLOptions = {};
     if (options) {
@@ -305881,6 +305938,9 @@ class ConnectionController {
     }
     const environmentForAdmission = await this.environmentStore.getEnvironment(environmentName, false);
     environmentForAdmission.assertCanAdmitQuery();
+    if (this.isManagedConnection(environmentForAdmission, connectionName)) {
+      throw new BadRequestError(`'${connectionName}' is a managed database: raw SQL on it runs only as a single SELECT, so it cannot create a temporary table.`);
+    }
     const malloyConnection = await this.getMalloyConnection(environmentName, connectionName, packageName);
     return await runWithQueryTimeout(async (signal) => {
       try {
@@ -305993,6 +306053,7 @@ var init_connection_controller = __esm(() => {
   init_connection();
   init_connection_public_view();
   init_connection_config();
+  init_single_select();
   init_connection_service();
   init_db_utils();
   init_query_metadata();
@@ -314991,8 +315052,8 @@ var require_lunr = __commonJS((exports, module) => {
     };
     lunr.Index.prototype.search = function(queryString) {
       return this.query(function(query) {
-        var parser = new lunr.QueryParser(queryString, query);
-        parser.parse();
+        var parser2 = new lunr.QueryParser(queryString, query);
+        parser2.parse();
       });
     };
     lunr.Index.prototype.query = function(fn) {
@@ -315583,8 +315644,8 @@ var require_lunr = __commonJS((exports, module) => {
       this.query.clause(completedClause);
       this.currentClause = {};
     };
-    lunr.QueryParser.parseClause = function(parser) {
-      var lexeme = parser.peekLexeme();
+    lunr.QueryParser.parseClause = function(parser2) {
+      var lexeme = parser2.peekLexeme();
       if (lexeme == undefined) {
         return;
       }
@@ -315603,23 +315664,23 @@ var require_lunr = __commonJS((exports, module) => {
           throw new lunr.QueryParseError(errorMessage, lexeme.start, lexeme.end);
       }
     };
-    lunr.QueryParser.parsePresence = function(parser) {
-      var lexeme = parser.consumeLexeme();
+    lunr.QueryParser.parsePresence = function(parser2) {
+      var lexeme = parser2.consumeLexeme();
       if (lexeme == undefined) {
         return;
       }
       switch (lexeme.str) {
         case "-":
-          parser.currentClause.presence = lunr.Query.presence.PROHIBITED;
+          parser2.currentClause.presence = lunr.Query.presence.PROHIBITED;
           break;
         case "+":
-          parser.currentClause.presence = lunr.Query.presence.REQUIRED;
+          parser2.currentClause.presence = lunr.Query.presence.REQUIRED;
           break;
         default:
           var errorMessage = "unrecognised presence operator'" + lexeme.str + "'";
           throw new lunr.QueryParseError(errorMessage, lexeme.start, lexeme.end);
       }
-      var nextLexeme = parser.peekLexeme();
+      var nextLexeme = parser2.peekLexeme();
       if (nextLexeme == undefined) {
         var errorMessage = "expecting term or field, found nothing";
         throw new lunr.QueryParseError(errorMessage, lexeme.start, lexeme.end);
@@ -315634,19 +315695,19 @@ var require_lunr = __commonJS((exports, module) => {
           throw new lunr.QueryParseError(errorMessage, nextLexeme.start, nextLexeme.end);
       }
     };
-    lunr.QueryParser.parseField = function(parser) {
-      var lexeme = parser.consumeLexeme();
+    lunr.QueryParser.parseField = function(parser2) {
+      var lexeme = parser2.consumeLexeme();
       if (lexeme == undefined) {
         return;
       }
-      if (parser.query.allFields.indexOf(lexeme.str) == -1) {
-        var possibleFields = parser.query.allFields.map(function(f3) {
+      if (parser2.query.allFields.indexOf(lexeme.str) == -1) {
+        var possibleFields = parser2.query.allFields.map(function(f3) {
           return "'" + f3 + "'";
         }).join(", "), errorMessage = "unrecognised field '" + lexeme.str + "', possible fields: " + possibleFields;
         throw new lunr.QueryParseError(errorMessage, lexeme.start, lexeme.end);
       }
-      parser.currentClause.fields = [lexeme.str];
-      var nextLexeme = parser.peekLexeme();
+      parser2.currentClause.fields = [lexeme.str];
+      var nextLexeme = parser2.peekLexeme();
       if (nextLexeme == undefined) {
         var errorMessage = "expecting term, found nothing";
         throw new lunr.QueryParseError(errorMessage, lexeme.start, lexeme.end);
@@ -315659,41 +315720,41 @@ var require_lunr = __commonJS((exports, module) => {
           throw new lunr.QueryParseError(errorMessage, nextLexeme.start, nextLexeme.end);
       }
     };
-    lunr.QueryParser.parseTerm = function(parser) {
-      var lexeme = parser.consumeLexeme();
+    lunr.QueryParser.parseTerm = function(parser2) {
+      var lexeme = parser2.consumeLexeme();
       if (lexeme == undefined) {
         return;
       }
-      parser.currentClause.term = lexeme.str.toLowerCase();
+      parser2.currentClause.term = lexeme.str.toLowerCase();
       if (lexeme.str.indexOf("*") != -1) {
-        parser.currentClause.usePipeline = false;
+        parser2.currentClause.usePipeline = false;
       }
-      var nextLexeme = parser.peekLexeme();
+      var nextLexeme = parser2.peekLexeme();
       if (nextLexeme == undefined) {
-        parser.nextClause();
+        parser2.nextClause();
         return;
       }
       switch (nextLexeme.type) {
         case lunr.QueryLexer.TERM:
-          parser.nextClause();
+          parser2.nextClause();
           return lunr.QueryParser.parseTerm;
         case lunr.QueryLexer.FIELD:
-          parser.nextClause();
+          parser2.nextClause();
           return lunr.QueryParser.parseField;
         case lunr.QueryLexer.EDIT_DISTANCE:
           return lunr.QueryParser.parseEditDistance;
         case lunr.QueryLexer.BOOST:
           return lunr.QueryParser.parseBoost;
         case lunr.QueryLexer.PRESENCE:
-          parser.nextClause();
+          parser2.nextClause();
           return lunr.QueryParser.parsePresence;
         default:
           var errorMessage = "Unexpected lexeme type '" + nextLexeme.type + "'";
           throw new lunr.QueryParseError(errorMessage, nextLexeme.start, nextLexeme.end);
       }
     };
-    lunr.QueryParser.parseEditDistance = function(parser) {
-      var lexeme = parser.consumeLexeme();
+    lunr.QueryParser.parseEditDistance = function(parser2) {
+      var lexeme = parser2.consumeLexeme();
       if (lexeme == undefined) {
         return;
       }
@@ -315702,33 +315763,33 @@ var require_lunr = __commonJS((exports, module) => {
         var errorMessage = "edit distance must be numeric";
         throw new lunr.QueryParseError(errorMessage, lexeme.start, lexeme.end);
       }
-      parser.currentClause.editDistance = editDistance;
-      var nextLexeme = parser.peekLexeme();
+      parser2.currentClause.editDistance = editDistance;
+      var nextLexeme = parser2.peekLexeme();
       if (nextLexeme == undefined) {
-        parser.nextClause();
+        parser2.nextClause();
         return;
       }
       switch (nextLexeme.type) {
         case lunr.QueryLexer.TERM:
-          parser.nextClause();
+          parser2.nextClause();
           return lunr.QueryParser.parseTerm;
         case lunr.QueryLexer.FIELD:
-          parser.nextClause();
+          parser2.nextClause();
           return lunr.QueryParser.parseField;
         case lunr.QueryLexer.EDIT_DISTANCE:
           return lunr.QueryParser.parseEditDistance;
         case lunr.QueryLexer.BOOST:
           return lunr.QueryParser.parseBoost;
         case lunr.QueryLexer.PRESENCE:
-          parser.nextClause();
+          parser2.nextClause();
           return lunr.QueryParser.parsePresence;
         default:
           var errorMessage = "Unexpected lexeme type '" + nextLexeme.type + "'";
           throw new lunr.QueryParseError(errorMessage, nextLexeme.start, nextLexeme.end);
       }
     };
-    lunr.QueryParser.parseBoost = function(parser) {
-      var lexeme = parser.consumeLexeme();
+    lunr.QueryParser.parseBoost = function(parser2) {
+      var lexeme = parser2.consumeLexeme();
       if (lexeme == undefined) {
         return;
       }
@@ -315737,25 +315798,25 @@ var require_lunr = __commonJS((exports, module) => {
         var errorMessage = "boost must be numeric";
         throw new lunr.QueryParseError(errorMessage, lexeme.start, lexeme.end);
       }
-      parser.currentClause.boost = boost;
-      var nextLexeme = parser.peekLexeme();
+      parser2.currentClause.boost = boost;
+      var nextLexeme = parser2.peekLexeme();
       if (nextLexeme == undefined) {
-        parser.nextClause();
+        parser2.nextClause();
         return;
       }
       switch (nextLexeme.type) {
         case lunr.QueryLexer.TERM:
-          parser.nextClause();
+          parser2.nextClause();
           return lunr.QueryParser.parseTerm;
         case lunr.QueryLexer.FIELD:
-          parser.nextClause();
+          parser2.nextClause();
           return lunr.QueryParser.parseField;
         case lunr.QueryLexer.EDIT_DISTANCE:
           return lunr.QueryParser.parseEditDistance;
         case lunr.QueryLexer.BOOST:
           return lunr.QueryParser.parseBoost;
         case lunr.QueryLexer.PRESENCE:
-          parser.nextClause();
+          parser2.nextClause();
           return lunr.QueryParser.parsePresence;
         default:
           var errorMessage = "Unexpected lexeme type '" + nextLexeme.type + "'";
@@ -315902,11 +315963,11 @@ function lexProseRanges(text) {
     });
     const lexerErrors = counter2();
     const parserErrors = counter2();
-    const { tokenStream, parser } = factory2(text, {
+    const { tokenStream, parser: parser2 } = factory2(text, {
       lexerErrorListener: lexerErrors,
       parserErrorListener: parserErrors
     });
-    parser.malloyDocument();
+    parser2.malloyDocument();
     const vocabulary = tokenStream.tokenSource?.vocabulary;
     if (lexerErrors.errors > 0 || parserErrors.errors > 0 || typeof vocabulary?.getSymbolicName !== "function")
       return;
@@ -338178,7 +338239,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` and its binding. On a grid its width, row break and height can go on its entry instead, `\"overview -> kpis\" { colspan=12 rowspan=2 }`, which wins over the view's tags; `rowspan=N` is rows of 80px, and `row=N col=N` place the tile at a grid cell (a report with any `row` is placed: fixed rows, tiles where they say, empty cells allowed).\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`, `break` and `rowspan`, 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."
+        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` and its binding. On a grid its width, row break and height can go on its entry instead, `\"overview -> kpis\" { colspan=12 rowspan=2 }`, which wins over the view's tags; `rowspan=N` is rows of 80px, and `row=N col=N` place the tile at a grid cell (a report with any `row` is placed: fixed rows, tiles where they say, empty cells allowed).\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`, `break` and `rowspan`, 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.\n- **A click always opens a menu that says what it will do**, even with one entry, each entry naming the field (as its column header reads) and value: `Filter to Region: EU` (`to=self`), `Open <report title> (Region: EU)` (each `to=<path>`; the file name when the report has no title), then `Show rows (Region: EU, Month: 2025-12)` (every value of the row). A tag adds entries; it never replaces the rows.\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- **Every value offers `Show rows`**, tagged or not: the tile's source, filtered by the tile's own `where:` (its control bindings included) and every dimension of the clicked row. That works for every one-stage tile: `\"source -> view\"`, a refined view, a tile naming a `query:`, an inline query, a view grouped by a joined field, a null value. **A view of more than one stage (`{ … } -> { … }`) opens no rows**, and its cells are not marked: a later stage's dimension is an earlier output the source cannot be filtered by. Keep a table tile meant to show its rows to one stage, and put the second stage in its own tile. A source with parameters opens no rows either. Neither does an unnamed time truncation inside a view (`group_by: created_at.month`), because the result loses which truncation it was: name it (`group_by: order_month is created_at.month`) in a view meant to show its rows.\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",
@@ -342726,8 +342787,8 @@ var require_luxon = __commonJS((exports) => {
     }
   }
   function explainFromTokens(locale, input, format) {
-    const parser = new TokenParser(locale, format);
-    return parser.explainFromTokens(input);
+    const parser2 = new TokenParser(locale, format);
+    return parser2.explainFromTokens(input);
   }
   function parseFromTokens(locale, input, format) {
     const {
@@ -357449,7 +357510,7 @@ var init_health = __esm(() => {
 
 // src/storage/duckdb/DuckDBConnection.ts
 import {
-  DuckDBInstance
+  DuckDBInstance as DuckDBInstance2
 } from "@duckdb/node-api";
 import * as path15 from "path";
 function duckDBInstanceResourceOptions() {
@@ -357475,7 +357536,7 @@ class DuckDBConnection3 {
   }
   async initialize() {
     try {
-      this.instance = await DuckDBInstance.create(this.dbPath, duckDBInstanceResourceOptions());
+      this.instance = await DuckDBInstance2.create(this.dbPath, duckDBInstanceResourceOptions());
       this.connection = await this.instance.connect();
       await this.connection.run("SELECT 42 as answer");
     } catch (err) {
@@ -360127,6 +360188,62 @@ var init_json_utils = __esm(() => {
   MAX_SAFE_BIGINT = BigInt(Number.MAX_SAFE_INTEGER);
 });
 
+// src/service/drill_metadata.ts
+import { API } from "@malloydata/malloy";
+function correctDrillMetadata(result) {
+  const structs = result._queryResult?.structs;
+  const root = structs?.[structs.length - 1];
+  if (root === undefined)
+    return false;
+  if (root.resultMetadata?.sourceField === LAST_STAGE)
+    root.resultMetadata.drillable = false;
+  correctFields(root.fields ?? []);
+  return true;
+}
+function wrapWithCorrectDrillMetadata(result) {
+  const corrected = correctDrillMetadata(result);
+  const wrapped = API.util.wrapResult(result);
+  if (!corrected)
+    return wrapped;
+  wrapped.annotations = [
+    ...wrapped.annotations ?? [],
+    { value: `#(malloy) ${DRILL_METADATA_CORRECTED}
+` }
+  ];
+  return wrapped;
+}
+function correctFields(fields) {
+  for (const field of fields) {
+    if (field.fields)
+      correctFields(field.fields);
+    const meta = field.resultMetadata;
+    if (meta?.fieldKind !== "dimension")
+      continue;
+    const code = drillCode(field, meta);
+    if (code === null)
+      delete meta.fieldKind;
+    else if (code !== undefined)
+      meta.sourceExpression = code;
+  }
+}
+function drillCode(field, meta) {
+  const { sourceField, sourceExpression, drillExpression } = meta;
+  if (sourceExpression)
+    return sourceField?.includes(".") ? sourceField : undefined;
+  if (field.timeframe === undefined)
+    return;
+  const reference = drillExpression?.field_reference;
+  if (drillExpression?.kind === "time_truncation" && reference !== undefined && drillExpression.truncation !== undefined)
+    return [
+      ...reference.path ?? [],
+      reference.name,
+      drillExpression.truncation
+    ].join(".");
+  return null;
+}
+var DRILL_METADATA_CORRECTED = "drill_metadata_corrected", LAST_STAGE = "~computeLastStage~";
+var init_drill_metadata = () => {};
+
 // src/service/statement_usage.ts
 function emitStatementUsage(usage) {
   try {
@@ -360179,7 +360296,6 @@ var init_statement_usage = __esm(() => {
 
 // src/service/query_execution.ts
 import {
-  API,
   MalloyError as MalloyError4
 } from "@malloydata/malloy";
 async function prepareAndRun(runnable, options, run) {
@@ -360211,7 +360327,7 @@ async function prepareAndRunUntraced(runnable, options, run) {
 }
 function serializeWithinCaps(result, caps) {
   assertWithinModelRowLimit(result.totalRows, caps.maxRows, caps.source);
-  const wrapped = API.util.wrapResult(result);
+  const wrapped = wrapWithCorrectDrillMetadata(result);
   const serialized = stringifyQueryResponse(caps.compact ? result.data.value : wrapped, result.totalRows, caps.maxBytes, caps.source, caps.compact ? bigIntReplacer : undefined);
   assertWithinModelByteLimit(serialized, caps.maxBytes, caps.source);
   return { wrapped, serialized };
@@ -360262,6 +360378,7 @@ var init_query_execution = __esm(() => {
   init_errors();
   init_logger();
   init_json_utils();
+  init_drill_metadata();
   init_model_limits();
   init_statement_usage();
 });

package/package.json

@@ -19,7 +19,7 @@
       "snowflake"
    ],
    "homepage": "https://docs.malloydata.dev/documentation/user_guides/publishing/mcp_agents",
-   "version": "0.10.2",
+   "version": "0.10.3",
    "main": "dist/server.mjs",
    "bin": {
       "malloy-publisher": "dist/server.mjs"