@malloy-publisher/server 0.5.1 → 0.7.0

package/dist/server.mjs

@@ -175849,7 +175849,7 @@ import os from "os";
 function normalizeModelPath(p) {
   return p.replace(/\\/g, "/").replace(/^\.\//, "");
 }
-var API_PREFIX = "/api/v0", README_NAME = "README.md", PUBLISHER_CONFIG_NAME = "publisher.config.json", PACKAGE_MANIFEST_NAME = "publisher.json", MODEL_FILE_SUFFIX = ".malloy", NOTEBOOK_FILE_SUFFIX = ".malloynb", DEFAULT_QUERY_ROW_LIMIT = 1000, DEFAULT_MAX_QUERY_ROWS = 1e5, DEFAULT_MAX_RESPONSE_BYTES = 50000000, DEFAULT_QUERY_TIMEOUT_MS = 300000, DEFAULT_MAX_CONCURRENT_QUERIES = 32, TEMP_DIR_PATH, PUBLISHER_DATA_DIR = "publisher_data";
+var API_PREFIX = "/api/v0", README_NAME = "README.md", PUBLISHER_CONFIG_NAME = "publisher.config.json", PACKAGE_MANIFEST_NAME = "publisher.json", MODEL_FILE_SUFFIX = ".malloy", NOTEBOOK_FILE_SUFFIX = ".malloynb", INDEX_MODEL_NAME = "index.malloy", DEFAULT_QUERY_ROW_LIMIT = 1000, DEFAULT_MAX_QUERY_ROWS = 1e5, DEFAULT_MAX_RESPONSE_BYTES = 50000000, DEFAULT_QUERY_TIMEOUT_MS = 300000, DEFAULT_MAX_CONCURRENT_QUERIES = 32, TEMP_DIR_PATH, PUBLISHER_DATA_DIR = "publisher_data";
 var init_constants = __esm(() => {
   TEMP_DIR_PATH = os.tmpdir();
 });
@@ -232535,12 +232535,23 @@ var require_bcrypt_pbkdf = __commonJS((exports, module) => {
   };
 });
 
+// ../../node_modules/cpu-features/build/Release/cpufeatures.node
+var require_cpufeatures = __commonJS((exports, module) => {
+  module.exports = __require("./cpufeatures-1yrn0vtw.node");
+});
+
+// ../../node_modules/cpu-features/lib/index.js
+var require_lib8 = __commonJS((exports, module) => {
+  var binding = require_cpufeatures();
+  module.exports = binding.getCPUInfo;
+});
+
 // ../../node_modules/ssh2/lib/protocol/constants.js
 var require_constants42 = __commonJS((exports, module) => {
   var crypto3 = __require("crypto");
   var cpuInfo;
   try {
-    cpuInfo = (()=>{throw new Error("Cannot require module "+"cpu-features");})()();
+    cpuInfo = require_lib8()();
   } catch {}
   var { bindingAvailable, CIPHER_INFO, MAC_INFO } = require_crypto();
   var eddsaSupported = (() => {
@@ -233139,7 +233150,7 @@ var require_utils92 = __commonJS((exports, module) => {
 
 // ../../node_modules/ssh2/lib/protocol/crypto/build/Release/sshcrypto.node
 var require_sshcrypto = __commonJS((exports, module) => {
-  module.exports = __require("./sshcrypto-xqan60jb.node");
+  module.exports = __require("./sshcrypto-cqb52edz.node");
 });
 
 // ../../node_modules/ssh2/lib/protocol/crypto/poly1305.js
@@ -247183,7 +247194,7 @@ var require_keygen = __commonJS((exports, module) => {
 });
 
 // ../../node_modules/ssh2/lib/index.js
-var require_lib8 = __commonJS((exports, module) => {
+var require_lib9 = __commonJS((exports, module) => {
   var {
     AgentProtocol,
     BaseAgent,
@@ -247366,7 +247377,7 @@ function openSshProxy(ssh, target) {
 var import_ssh2, ALLOW_UNVERIFIED_SSH_HOST_KEY_ENV = "PUBLISHER_ALLOW_UNVERIFIED_SSH_HOST_KEY", TRUTHY_ENV_VALUES, SSH_CONNECT_TIMEOUT_MS = 15000, SSH_KEEPALIVE_INTERVAL_MS = 15000;
 var init_proxy = __esm(() => {
   init_logger();
-  import_ssh2 = __toESM(require_lib8(), 1);
+  import_ssh2 = __toESM(require_lib9(), 1);
   TRUTHY_ENV_VALUES = new Set(["1", "true", "yes", "on"]);
 });
 
@@ -267096,6 +267107,29 @@ var require_lunr = __commonJS((exports, module) => {
   })();
 });
 
+// src/service/authorize_routes.ts
+function canonicalAuthorizeRoute(route) {
+  switch (route) {
+    case ACCESS_FILTER_ROUTE:
+      return ACCESS_FILTER_ROUTE;
+    case AUTHORIZE_ROUTE:
+      return AUTHORIZE_ROUTE;
+    default:
+      return;
+  }
+}
+var AUTHORIZE_ROUTE = "authorize", ACCESS_FILTER_ROUTE = "access_filter", RECOGNIZED_AUTHORIZE_SPELLINGS, CANONICAL_AUTHORIZE_ROUTES;
+var init_authorize_routes = __esm(() => {
+  RECOGNIZED_AUTHORIZE_SPELLINGS = [
+    ACCESS_FILTER_ROUTE,
+    AUTHORIZE_ROUTE
+  ];
+  CANONICAL_AUTHORIZE_ROUTES = [
+    ACCESS_FILTER_ROUTE,
+    AUTHORIZE_ROUTE
+  ];
+});
+
 // src/service/authorize.ts
 import { payloadOf, routeOf } from "@malloydata/malloy";
 function noteRoute(text) {
@@ -267104,8 +267138,61 @@ function noteRoute(text) {
 function notePayload(text) {
   return payloadOf({ value: text.trimStart() }) ?? "";
 }
+function nearMissRouteNames(route) {
+  switch (route) {
+    case AUTHORIZE_ROUTE:
+      return [
+        "authorize",
+        "source_authorize",
+        "source-authorize",
+        "sourceauthorize",
+        "authorize_source",
+        "authorize-source",
+        "authorizesource"
+      ];
+    case ACCESS_FILTER_ROUTE:
+      return [
+        "access_filter",
+        "access-filter",
+        "accessfilter",
+        "filter_access",
+        "filter-access",
+        "filteraccess",
+        "row_authorize",
+        "row-authorize",
+        "rowauthorize",
+        "authorize_row",
+        "authorize-row",
+        "authorizerow"
+      ];
+    default:
+      return [route];
+  }
+}
+function nearMissWordAlternation(route) {
+  const names = nearMissRouteNames(route);
+  if (names.length === 0) {
+    throw new Error(`No near-miss spellings for authorize route \`${route}\` — an empty ` + "alternation matches every malformed-prefix note, which would " + "fail package loads over annotations nobody wrote.");
+  }
+  return names.map((name) => name.replace(REGEXP_SPECIAL, "\\$&")).join("|");
+}
+function motlyAuthorizePayloadPattern(route) {
+  return new RegExp(`^[ \\t]*[([{<][ \\t]*(?:${nearMissWordAlternation(route)})[ \\t]*[)\\]}>]`, "iu");
+}
+function malformedAuthorizeAttemptPattern(route) {
+  return new RegExp(`^##?\\|?[ \\t]*[([{<]?[ \\t]*(?:${nearMissWordAlternation(route)})`, "iu");
+}
 function authorizeNoteContent(text) {
-  return noteRoute(text) === AUTHORIZE_ROUTE ? notePayload(text) : undefined;
+  const route = canonicalAuthorizeRoute(noteRoute(text));
+  if (route === undefined)
+    return;
+  return { route, content: notePayload(text) };
+}
+function authorizeAnnotationRoute(text) {
+  return authorizeNoteContent(text)?.route;
+}
+function hasCallerAuthorizeAnnotation(callerText) {
+  return AUTHORIZE_ANNOTATION_ANYWHERE.test(callerText);
 }
 function assertNoCallerAuthorizeAnnotation(callerText) {
   if (!AUTHORIZE_ANNOTATION_ANYWHERE.test(callerText))
@@ -267115,37 +267202,59 @@ function assertNoCallerAuthorizeAnnotation(callerText) {
 function containsAuthorizeAnnotationTag(texts) {
   return texts.some((text) => authorizeNoteContent(text) !== undefined);
 }
-function collectAuthorizeNearMisses(texts) {
+function collectAuthorizeNearMisses(texts, route) {
+  const motlyPattern = motlyAuthorizePayloadPattern(route);
+  const malformedPattern = malformedAuthorizeAttemptPattern(route);
+  const nearMissNames = new Set(nearMissRouteNames(route).map((name) => name.toLowerCase()));
   const found = [];
   for (const text of texts) {
     const trimmed = text.trimStart();
-    const route = noteRoute(trimmed);
-    if (route === AUTHORIZE_ROUTE)
+    const noted = noteRoute(trimmed);
+    if (noted === route)
       continue;
-    const nearMiss = route === undefined ? MALFORMED_AUTHORIZE_ATTEMPT.test(trimmed) : route === "" ? MOTLY_AUTHORIZE_PAYLOAD.test(notePayload(trimmed)) : route.toLowerCase() === AUTHORIZE_ROUTE;
+    const nearMiss = noted === undefined ? malformedPattern.test(trimmed) : noted === "" ? motlyPattern.test(notePayload(trimmed)) : nearMissNames.has(noted.toLowerCase());
     if (!nearMiss)
       continue;
     found.push(trimmed.split(/[\r\n]/, 1)[0]);
   }
   return found;
 }
+function collectAuthorizeNearMissesAllRoutes(texts) {
+  const materialized = [...texts];
+  return RECOGNIZED_AUTHORIZE_SPELLINGS.flatMap((route) => collectAuthorizeNearMisses(materialized, route));
+}
+function guessedNearMissRoute(text) {
+  const lower = text.toLowerCase();
+  let best = ACCESS_FILTER_ROUTE;
+  let bestLength = 0;
+  for (const route of RECOGNIZED_AUTHORIZE_SPELLINGS) {
+    for (const name of nearMissRouteNames(route)) {
+      if (lower.includes(name) && name.length > bestLength) {
+        best = route;
+        bestLength = name.length;
+      }
+    }
+  }
+  return best;
+}
 function assertNoAuthorizeNearMisses(found) {
   if (found.length === 0)
     return;
   const unique = [...new Set(found)];
   throw new ModelCompilationError({
-    message: `These annotations are not \`authorize\` gates and nothing enforces ` + `them:
-${unique.map((t) => `  - \`${t}\``).join(`
+    message: `These annotations are never enforced:
+${unique.map((t) => `  - \`${t}\` (meant \`#(${guessedNearMissRoute(t)})\`?)`).join(`
 `)}
-` + `Malloy routes an annotation by its prefix, and only ` + `\`#(authorize)\` (or \`##(authorize)\`, or the block form ` + `\`#|(authorize)\`) reaches the authorize route — a space after the ` + `\`#\`, spaces inside the brackets, or anything trailing the closing ` + `bracket makes it a plain tag Malloy hands to something else. Write ` + `\`#(authorize) <expression>\` on its own line directly above the ` + `\`source:\` statement you mean to protect (unquoted — the quoted ` + `string form is retired). This is refused rather than interpreted: ` + `guessing at the ` + `intent would let publisher start enforcing a filter on a package that ` + `has been serving every row.`
+` + `Malloy routes an annotation by its prefix, and only ` + `\`#(authorize)\` and \`#(access_filter)\` reach an access-control ` + `route (in their \`##\` and ` + `block-form \`#|(...)\` spellings too). A space after the \`#\`, spaces ` + `inside the brackets, a mis-hyphenated or transposed word, or anything ` + `trailing the closing bracket makes it a plain tag Malloy hands to ` + `something else. Write the tag named above, unquoted, on its own line ` + `directly above the \`source:\` statement you mean to protect (the ` + `quoted string form is retired). This is refused rather than ` + `interpreted: guessing at the intent would let publisher start ` + `enforcing a filter on a package that has been serving every row.`
   });
 }
 function describeMisplacedAuthorizeAnnotation(f) {
-  if (f.kind === "query")
-    return `on query "${f.name}"`;
   if (f.kind === "file")
-    return "at the file level (`##(authorize)`)";
-  return `on field "${f.fieldName}" of source "${f.name}"`;
+    return `at the file level (\`##(${f.route})\`)`;
+  const tag = `\`#(${f.route})\``;
+  if (f.kind === "query")
+    return `on query "${f.name}" (${tag})`;
+  return `on field "${f.fieldName}" of source "${f.name}" (${tag})`;
 }
 function assertNoMisplacedAuthorizeAnnotations(found) {
   if (found.length === 0)
@@ -267153,9 +267262,9 @@ function assertNoMisplacedAuthorizeAnnotations(found) {
   const positions = found.map((f) => `  - ${describeMisplacedAuthorizeAnnotation(f)}`).join(`
 `);
   throw new ModelCompilationError({
-    message: `An \`#(authorize)\` annotation is never enforced at:
+    message: `An authorize annotation is never enforced at:
 ${positions}
-` + `A gate only applies where model load looks for one — a \`source:\`'s ` + `own annotation, or one it inherits from an \`extend\`/query-source ` + `base. File-level \`##(authorize)\` is deprecated and no longer ` + `enforced anywhere, so it always lands here: declare \`#(authorize)\` ` + `on each \`source:\` it was meant to protect instead. Every other ` + `position above should move to the \`source:\` statement it is meant ` + `to protect.`
+` + `A gate only applies where model load looks for one — a \`source:\`'s ` + `own annotation, or one it inherits from an \`extend\`/query-source ` + `base. A file-level annotation (\`##(authorize)\` / ` + `\`##(access_filter)\`) is deprecated and no longer enforced ` + `anywhere, so it always lands here: declare the same tag on each ` + `\`source:\` it was meant to protect instead. Every other ` + `position above should move — with the same tag named beside it — ` + `to the \`source:\` statement it is meant ` + `to protect.`
   });
 }
 function referencedGivenNames(expr) {
@@ -267192,7 +267301,7 @@ function liftProbeFilterCondition(prepared, label, filterText) {
   return lifted;
 }
 function gateFilterText(exprs) {
-  return exprs.map((e) => `(${e})`).join(" or ");
+  return exprs.map((e) => `(${e})`).join(" and ");
 }
 async function liftRowLevelCondition(compiler, sourceName, exprs) {
   const filterText = gateFilterText(exprs);
@@ -267202,7 +267311,7 @@ async function liftRowLevelCondition(compiler, sourceName, exprs) {
 async function validateAuthorizeProbes(compiler, options) {
   const ownNotesOf = options.authorizeOwnNotes ?? new Map;
   for (const [sourceName, groups] of options.authorizeMap ?? []) {
-    for (const exprs of groups) {
+    for (const { route, exprs } of groups) {
       if (exprs.length === 0)
         continue;
       let condition;
@@ -267210,17 +267319,17 @@ async function validateAuthorizeProbes(compiler, options) {
         condition = await liftRowLevelCondition(compiler, sourceName, exprs);
       } catch (err) {
         const detail = err instanceof Error ? err.message : String(err);
-        const ownNotes = ownNotesOf.get(sourceName) ?? [];
+        const ownNotes = ownNotesOf.get(sourceName)?.get(route) ?? [];
         if (ownNotes.length === 0) {
           options.onRowLevelGateRejected?.("entry_point_unexpressible");
           options.onRowLevelGateUnexpressible?.(sourceName, detail);
           continue;
         }
         throw new ModelCompilationError({
-          message: `Invalid #(authorize) annotation on source "${sourceName}" ` + `[${exprs.join(" | ")}]: ${detail}`
+          message: `Invalid #(${route}) annotation on source "${sourceName}" ` + `[${exprs.join(" and ")}]: ${detail}`
         });
       }
-      options.onOwnRowLevelConditionCompiled?.(sourceName, condition);
+      options.onOwnRowLevelConditionCompiled?.(sourceName, condition, route);
     }
   }
 }
@@ -267234,59 +267343,41 @@ function unquoteLegacyGatePayload(payload) {
   return trimmed[0] === "'" ? inner.replace(SINGLE_QUOTE_ESCAPE, "$1") : inner.replace(DOUBLE_QUOTE_ESCAPE, "$1");
 }
 function parseAuthorizeAnnotation(annotation) {
-  const content = authorizeNoteContent(annotation);
-  if (content === undefined)
+  const parsed = authorizeNoteContent(annotation);
+  if (parsed === undefined)
     return null;
-  const trimmed = content.trim();
+  const trimmed = parsed.content.trim();
   if (trimmed.length === 0) {
     throw new Error("authorize annotation has an empty expression body");
   }
-  return trimmed;
+  return { route: parsed.route, expr: trimmed };
 }
 function collectAuthorizeExprs(annotations) {
   const exprs = [];
   for (const annotation of annotations) {
-    const expr = parseAuthorizeAnnotation(annotation);
-    if (expr !== null) {
-      exprs.push(expr);
+    const parsed = parseAuthorizeAnnotation(annotation);
+    if (parsed !== null) {
+      exprs.push(parsed);
     }
   }
   return exprs;
 }
-function findMultipleAuthorizeGates(authorizeOwnNotes) {
-  const found = [];
-  for (const [sourceName, notes] of authorizeOwnNotes) {
-    if (notes.length > 1) {
-      found.push({ sourceName, texts: notes.map((note) => note.text) });
-    }
-  }
-  return found;
-}
-function assertAtMostOneAuthorizeGate(found) {
-  if (found.length === 0)
-    return;
-  const positions = found.map(({ sourceName, texts }) => `  - source "${sourceName}" declares ${texts.length}:
-` + texts.map((t) => `      \`${t.trim().split(/[\r\n]/, 1)[0]}\``).join(`
-`)).join(`
-`);
-  throw new ModelCompilationError({
-    message: `A source may declare at most one \`#(authorize)\` annotation:
-${positions}
-` + `Combine multiple conditions into one expression with \`or\` instead of ` + `repeating the annotation, e.g. ` + "`#(authorize) $ROLE = 'admin' or org_id in $GROUPS`."
-  });
+function collectAuthorizeExprsForRoute(annotations, route) {
+  return collectAuthorizeExprs(annotations).filter((e) => e.route === route).map((e) => e.expr);
 }
 function findLegacyStringGates(authorizeOwnNotes) {
   const found = [];
-  for (const [sourceName, notes] of authorizeOwnNotes) {
+  for (const [sourceName, notesByRoute] of authorizeOwnNotes) {
+    const notes = [...notesByRoute.values()].flat();
     const legacyNotes = notes.filter((note) => {
       const content = authorizeNoteContent(note.text);
-      return content !== undefined && isLegacyQuotedPayload(content);
+      return content !== undefined && isLegacyQuotedPayload(content.content);
     });
     if (legacyNotes.length === 0)
       continue;
-    const exprs = collectAuthorizeExprs(legacyNotes.map((note) => note.text));
-    if (exprs.length > 0) {
-      found.push({ sourceName, exprs });
+    const gates = legacyNotes.flatMap((note) => collectAuthorizeExprs([note.text]));
+    if (gates.length > 0) {
+      found.push({ sourceName, gates });
     }
   }
   return found;
@@ -267294,22 +267385,22 @@ function findLegacyStringGates(authorizeOwnNotes) {
 function assertNoLegacyStringGate(found) {
   if (found.length === 0)
     return;
-  const rewrites = found.flatMap(({ sourceName, exprs }) => exprs.map((expr) => `  - source "${sourceName}": replace \`#(authorize) ${expr}\`` + ` with
-      #(authorize) ${unquoteLegacyGatePayload(expr)}`)).join(`
+  const rewrites = found.flatMap(({ sourceName, gates }) => gates.map(({ route, expr }) => `  - source "${sourceName}": replace \`#(${route}) ${expr}\`` + ` with
+      #(${route}) ${unquoteLegacyGatePayload(expr)}`)).join(`
 `);
   throw new ModelCompilationError({
-    message: `The string form of \`#(authorize)\` (a Malloy-quoted expression on ` + `the \`source:\` line) is no longer accepted. Replace it with the ` + `unquoted expression, carried by an \`#(authorize)\` annotation on ` + `its own line directly above the \`source:\` line:
+    message: `The string form of an authorize gate (a Malloy-quoted expression on ` + `the \`source:\` line) is no longer accepted. Replace it with the ` + `unquoted expression, carried by the same annotation on its own line ` + `directly above the \`source:\` line:
 ${rewrites}
 ` + `Test that the rewrite gates the same rows and check the row count ` + `matches what the string form served.`
   });
 }
-var AUTHORIZE_ROUTE = "authorize", AUTHORIZE_TAG_LIKE, AUTHORIZE_ANNOTATION_ANYWHERE, MOTLY_AUTHORIZE_PAYLOAD, MALFORMED_AUTHORIZE_ATTEMPT, GIVEN_REF_PATTERN, SINGLE_QUOTE_ESCAPE, DOUBLE_QUOTE_ESCAPE, STRING_LITERAL_PATTERN, everyMemberOf = () => (...members) => members, ROW_LEVEL_GATE_REJECTION_CAUSES, WHOLE_BODY_QUOTED_STRING, WHOLE_BODY_SINGLE_QUOTED_STRING;
+var AUTHORIZE_TAG_LIKE, AUTHORIZE_ANNOTATION_ANYWHERE, REGEXP_SPECIAL, GIVEN_REF_PATTERN, SINGLE_QUOTE_ESCAPE, DOUBLE_QUOTE_ESCAPE, STRING_LITERAL_PATTERN, everyMemberOf = () => (...members) => members, ROW_LEVEL_GATE_REJECTION_CAUSES, WHOLE_BODY_QUOTED_STRING, WHOLE_BODY_SINGLE_QUOTED_STRING;
 var init_authorize = __esm(() => {
   init_errors();
-  AUTHORIZE_TAG_LIKE = String.raw`##?\|?[ \t]*[([{<]?[ \t]*authorize(?=[)\]}>]|[ \t]|$)`;
+  init_authorize_routes();
+  AUTHORIZE_TAG_LIKE = String.raw`##?\|?[ \t]*[([{<]?[ \t]*(?:(?:(?:row|source)[-_]?)?authorize|access[-_]?filter)(?=[)\]}>]|[ \t]|$)`;
   AUTHORIZE_ANNOTATION_ANYWHERE = new RegExp(AUTHORIZE_TAG_LIKE, "iu");
-  MOTLY_AUTHORIZE_PAYLOAD = /^[ \t]*[([{<][ \t]*authorize[ \t]*[)\]}>]/iu;
-  MALFORMED_AUTHORIZE_ATTEMPT = /^##?\|?[ \t]*[([{<]?[ \t]*authorize/iu;
+  REGEXP_SPECIAL = /[.*+?^${}()|[\]\\]/g;
   GIVEN_REF_PATTERN = /\$([A-Za-z_][A-Za-z0-9_]*)/g;
   SINGLE_QUOTE_ESCAPE = /\\(['\\])/g;
   DOUBLE_QUOTE_ESCAPE = /\\(["\\])/g;
@@ -267894,7 +267985,13 @@ function collectGivenRefs(value, into) {
   for (const child of Object.values(node))
     collectGivenRefs(child, into);
 }
-function suggestGivenLookup(modelDef, authorizeBySource, surfaced) {
+function gateGivenSource(sources, name) {
+  const source = sources.find((candidate) => candidate.name === name);
+  if (!source)
+    return;
+  return [...source.authorize ?? [], ...source.accessFilter ?? []];
+}
+function suggestGivenLookup(modelDef, gatesBySource, surfaced) {
   const registry = modelDef.givens ?? {};
   const bySource = new Map;
   const byQuery = new Map;
@@ -267903,7 +268000,7 @@ function suggestGivenLookup(modelDef, authorizeBySource, surfaced) {
       const name = obj.as || obj.name;
       const refs = new Set;
       collectGivenRefs(obj.filterList, refs);
-      for (const expr of authorizeBySource(name) ?? []) {
+      for (const expr of gatesBySource(name) ?? []) {
         for (const given of referencedGivenNames(expr))
           refs.add(given);
       }
@@ -268002,7 +268099,7 @@ function positiveInteger(value) {
 function normalizeTileExpression(tile) {
   return tile.split("->").map((part) => part.trim().replace(/\s+/g, " ")).join(" -> ").replace(/\s+/g, " ");
 }
-function readDashboardModelFacts(modelPath, modelDef, surfacedGivenNames, authorizeBySource) {
+function readDashboardModelFacts(modelPath, modelDef, surfacedGivenNames, gatesBySource) {
   const registry = modelDef.givens ?? {};
   const surfaced = new Set(surfacedGivenNames);
   const givens = new Map;
@@ -268072,7 +268169,7 @@ function readDashboardModelFacts(modelPath, modelDef, surfacedGivenNames, author
     viewAnnotations,
     sourceFields,
     drills,
-    suggestGivens: suggestGivenLookup(modelDef, (source) => authorizeBySource?.get(source), surfaced)
+    suggestGivens: suggestGivenLookup(modelDef, (source) => gatesBySource?.get(source), surfaced)
   };
 }
 function readTileLayout(annotations) {
@@ -270706,20 +270803,33 @@ function recordAuthorizeBypass(entryPoint) {
 }
 function recordRowLevelGateDecision(decision) {
   rowLevelDecisionCounter ??= publisherMeter().createCounter("publisher_authorize_row_level_total", {
-    description: "How a row-level `#(authorize)` gate resolved a request. Label: decision ('denied_by_gate'|'empty_after_filter'). 'denied_by_gate' is the fail-closed refusal when the gate could not be applied; 'empty_after_filter' is a successful response with zero rows after the filter matched none, which is NOT an error."
+    description: "How a row-level `#(access_filter)` gate resolved a request. Label: decision ('denied_by_gate'|'empty_after_filter'). 'denied_by_gate' is the fail-closed refusal when the gate could not be applied; 'empty_after_filter' is a successful response with zero rows after the filter matched none, which is NOT an error."
   });
   rowLevelDecisionCounter.add(1, { decision });
 }
 function recordRowLevelGateRejected(cause) {
   rowLevelRejectionCounter ??= publisherMeter().createCounter("publisher_authorize_row_level_rejected_total", {
-    description: "Row-level `#(authorize)` gates that were refused, warned about, or could not be resolved. Label: cause (" + ROW_LEVEL_GATE_REJECTION_CAUSES.map((c) => `'${c}'`).join("|") + "). Only 'legacy_string_gate' fails the whole model load. 'entry_point_unexpressible', 'source_line_gate_no_given_reference' and 'source_line_gate_negated_membership' warn at load and leave the model servable. 'unreachable_given', 'given_usage_unresolvable' and 'unclassifiable_condition' are request-time only — that entry point denies every request. Alert on any nonzero value since the last publish; the request-time causes also make this a rate signal, so see the doc above before writing an alert."
+    description: "Row-level `#(access_filter)` gates that were refused, warned about, or could not be resolved. Label: cause (" + ROW_LEVEL_GATE_REJECTION_CAUSES.map((c) => `'${c}'`).join("|") + "). Only 'legacy_string_gate' fails the whole model load. 'entry_point_unexpressible', 'source_line_gate_no_given_reference' and 'source_line_gate_negated_membership' warn at load and leave the model servable. 'unreachable_given', 'given_usage_unresolvable' and 'unclassifiable_condition' are request-time only — that entry point denies every request. Alert on any nonzero value since the last publish; the request-time causes also make this a rate signal, so see the doc above before writing an alert."
   });
   rowLevelRejectionCounter.add(1, { cause });
 }
-var guardRejectionCounter = null, bypassCounter = null, rowLevelDecisionCounter = null, rowLevelRejectionCounter = null;
+function recordAuthorizeAdmitAllGate(route) {
+  admitAllCounter ??= publisherMeter().createCounter("publisher_authorize_admit_all_total", {
+    description: "Sources declaring their OWN unconditional admit-all gate (`#(authorize) true`), counted once each at package load. Label: route (" + CANONICAL_AUTHORIZE_ROUTES.map((r) => `'${r}'`).join("|") + "). Not an error — `true` is the only spelling for an extension that deliberately re-opens a gated base — but it is the one declaration that turns a gate off, so a jump since the last publish is worth a look."
+  });
+  admitAllCounter.add(1, { route });
+}
+function recordLockDecision(decision) {
+  lockDecisionCounter ??= publisherMeter().createCounter("publisher_authorize_lock_total", {
+    description: "How a `#(authorize)` lock resolved a request. Label: decision ('admitted'|'denied_by_lock'|'denied_unresolvable'). Both denials are a 403; 'denied_by_lock' is the gate refusing a caller it does not admit (routine), 'denied_unresolvable' is the fail-closed refusal when the gate could not be decided at all."
+  });
+  lockDecisionCounter.add(1, { decision });
+}
+var guardRejectionCounter = null, bypassCounter = null, rowLevelDecisionCounter = null, rowLevelRejectionCounter = null, admitAllCounter = null, lockDecisionCounter = null;
 var init_authorize_metrics = __esm(() => {
   init_telemetry();
   init_authorize();
+  init_authorize_routes();
 });
 
 // src/materialization_metrics.ts
@@ -271918,6 +272028,317 @@ function filterFreshManifest(entries, now) {
   return { manifest, nextStaleSince };
 }
 
+// src/service/authorize_grammar.ts
+import { routeOf as routeOf2 } from "@malloydata/malloy";
+function noteRoute2(text) {
+  return routeOf2({ value: text.trimStart() });
+}
+function splitFieldPathSegments(fieldPath) {
+  const segments = [];
+  let i = 0;
+  while (i < fieldPath.length) {
+    if (fieldPath[i] === "`") {
+      const end = fieldPath.indexOf("`", i + 1);
+      segments.push(fieldPath.slice(i + 1, end));
+      i = end + 1;
+    } else {
+      const dot = fieldPath.indexOf(".", i);
+      const end = dot === -1 ? fieldPath.length : dot;
+      segments.push(fieldPath.slice(i, end));
+      i = end;
+    }
+    if (fieldPath[i] === ".")
+      i++;
+  }
+  return segments;
+}
+function rejectionMessage(sourceName, body, detail) {
+  return `Source "${sourceName}" declares an authorize gate \`${body}\`: ${detail} ` + GRAMMAR_SUMMARY;
+}
+function reject(sourceName, body, cause, detail) {
+  throw new AuthorizeGrammarError(cause, rejectionMessage(sourceName, body, detail));
+}
+function rejectCoherence(sourceName, cause, detail) {
+  throw new AuthorizeGrammarError(cause, `Source "${sourceName}" declares authorize notes whose terms ` + `conflict: ${detail} ${GRAMMAR_SUMMARY}`);
+}
+function splitTerms(body) {
+  const terms = [];
+  const compoundTokens = [];
+  let depth = 0;
+  let quote;
+  let start = 0;
+  let i = 0;
+  while (i < body.length) {
+    const ch = body[i];
+    if (quote) {
+      if (ch === "\\" && quote !== "`") {
+        i += 2;
+        continue;
+      }
+      if (ch === quote)
+        quote = undefined;
+      i++;
+      continue;
+    }
+    if (isQuote(ch)) {
+      quote = ch;
+      i++;
+      continue;
+    }
+    if (ch === "(") {
+      depth++;
+      i++;
+      continue;
+    }
+    if (ch === ")") {
+      depth = Math.max(0, depth - 1);
+      i++;
+      continue;
+    }
+    if (depth === 0) {
+      const wordMatch = /^(and|or|not)\b/i.exec(body.slice(i));
+      if (wordMatch && (i === 0 || !/[A-Za-z0-9_]/.test(body[i - 1]))) {
+        const word = wordMatch[1].toLowerCase();
+        if (word === "and") {
+          terms.push(body.slice(start, i));
+          i += wordMatch[0].length;
+          start = i;
+          continue;
+        }
+        compoundTokens.push(word);
+      }
+    }
+    i++;
+  }
+  terms.push(body.slice(start));
+  return { terms, compoundTokens };
+}
+function isQuote(ch) {
+  return ch === "'" || ch === '"' || ch === "`";
+}
+function findOperatorOutsideQuotes(s, re) {
+  let quote;
+  for (let i = 0;i < s.length; i++) {
+    const ch = s[i];
+    if (quote) {
+      if (ch === "\\" && quote !== "`") {
+        i++;
+        continue;
+      }
+      if (ch === quote)
+        quote = undefined;
+      continue;
+    }
+    if (isQuote(ch)) {
+      quote = ch;
+      continue;
+    }
+    re.lastIndex = i;
+    const m = re.exec(s);
+    if (m && m.index === i)
+      return i;
+  }
+  return -1;
+}
+function parseTerm(sourceName, body, term, givenDeclaredTypes) {
+  const trimmed2 = term.trim();
+  if (findOperatorOutsideQuotes(trimmed2, NEGATED_OPERATOR_RE) !== -1) {
+    reject(sourceName, body, "negated_operator", "`!=` is not allowed.");
+  }
+  if (findOperatorOutsideQuotes(trimmed2, COMPARISON_OPERATOR_RE) !== -1) {
+    reject(sourceName, body, "comparison_operator", "only `=` and `in` are allowed, not `<`/`>`/`<=`/`>=`.");
+  }
+  const inIdx = findOperatorOutsideQuotes(trimmed2, IN_OPERATOR_RE);
+  const eqIdx = findOperatorOutsideQuotes(trimmed2, EQ_OPERATOR_RE);
+  let operator;
+  let opIdx;
+  let opLen;
+  if (inIdx !== -1 && (eqIdx === -1 || inIdx < eqIdx)) {
+    operator = "in";
+    opIdx = inIdx;
+    opLen = 2;
+  } else if (eqIdx !== -1) {
+    operator = "=";
+    opIdx = eqIdx;
+    opLen = 1;
+  } else {
+    reject(sourceName, body, "malformed_body", "no `=` or `in` operator was found.");
+  }
+  let left = trimmed2.slice(0, opIdx).trim();
+  let right = trimmed2.slice(opIdx + opLen).trim();
+  if (GIVEN_REF_RE.test(left) && STRING_LITERAL_RE.test(right)) {
+    if (operator === "in") {
+      reject(sourceName, body, "reversed_in_operands", `\`${left} in ${right}\` reads $GIVEN in 'literal', which Malloy ` + `rejects as array-in-string membership. Write the literal ` + `first: \`${right} in ${left}\`.`);
+    }
+    [left, right] = [right, left];
+  }
+  const leftIsFieldPath = FIELD_PATH_RE.test(left);
+  const leftIsLiteral = STRING_LITERAL_RE.test(left);
+  if (!leftIsFieldPath && !leftIsLiteral) {
+    reject(sourceName, body, "left_not_field_path", `\`${left}\` is neither a field path nor a string literal — one ` + "side must be a single column, a dotted join path, or a quoted " + "literal, and the other a `$GIVEN`.");
+  }
+  const givenMatch = GIVEN_REF_RE.exec(right);
+  if (!givenMatch) {
+    reject(sourceName, body, "missing_given_reference", `\`${right}\` is not a given reference — a term compares against ` + "`$NAME`.");
+  }
+  const given = givenMatch[1];
+  const declaredType = givenDeclaredTypes.get(given);
+  if (declaredType !== undefined) {
+    const isListType = declaredType === "array" || declaredType.endsWith("[]");
+    if (operator === "=" && isListType) {
+      reject(sourceName, body, "operator_arity_mismatch", `\`$${given}\` is a list-typed given — use \`in\`, not \`=\`.`);
+    }
+    if (operator === "in" && !isListType) {
+      reject(sourceName, body, "operator_arity_mismatch", `\`$${given}\` is a scalar given — use \`=\`, not \`in\`.`);
+    }
+  }
+  if (leftIsLiteral) {
+    return { scope: "source_level", literal: left, given };
+  }
+  return {
+    scope: "row_level",
+    fieldPath: left,
+    fieldPathSegments: splitFieldPathSegments(left),
+    given,
+    operator
+  };
+}
+function assertAuthorizeGrammarTermsCoherent(sourceName, terms) {
+  if (terms.length > 1 && terms.some(({ term }) => term.scope === "deny_all")) {
+    rejectCoherence(sourceName, "deny_all_with_sibling", "an unconditional `false` deny-all cannot be combined with any " + "other authorize note — a deny-all admits nothing, so a " + "sibling note can never change what is served and its " + "presence is very likely a mistake.");
+  }
+  const byRoute = new Map;
+  for (const { term, route } of terms) {
+    if (term.scope === "deny_all")
+      continue;
+    const list = byRoute.get(route);
+    if (list)
+      list.push(term);
+    else
+      byRoute.set(route, [term]);
+  }
+  for (const allRouteTerms of byRoute.values()) {
+    if (allRouteTerms.length > 1 && allRouteTerms.some((t) => t.scope === "admit_all")) {
+      rejectCoherence(sourceName, "admit_all_with_sibling", "an unconditional `true` admit-all cannot be combined with " + "another `#(authorize)` note — the lock's notes AND " + "together, so `true and x` reduces to `x` and the admit-all " + "is dead text. To unlock a base while its rows stay " + "filtered, pair the `true` with `#(access_filter)` instead.");
+    }
+    const routeTerms = allRouteTerms.filter((t) => t.scope !== "admit_all" && t.scope !== "deny_all");
+    const seenGivens = new Set;
+    const seenFieldPaths = new Set;
+    for (const t of routeTerms) {
+      if (seenGivens.has(t.given)) {
+        rejectCoherence(sourceName, "duplicate_given", `\`$${t.given}\` is used by more than one term — a given ` + "can back at most one term per route.");
+      }
+      seenGivens.add(t.given);
+      if (t.scope === "row_level") {
+        const canonicalPath = JSON.stringify(t.fieldPathSegments);
+        if (seenFieldPaths.has(canonicalPath)) {
+          rejectCoherence(sourceName, "duplicate_field_path", `\`${t.fieldPath}\` is used by more than one term.`);
+        }
+        seenFieldPaths.add(canonicalPath);
+      }
+    }
+  }
+}
+function parseAuthorizeGrammarBody(sourceName, body, givenDeclaredTypes, route) {
+  const trimmedBody = body.trim();
+  if (trimmedBody.length === 0) {
+    reject(sourceName, trimmedBody, "empty_body", "the expression body is empty.");
+  }
+  const sentinel = trimmedBody.toLowerCase();
+  if (sentinel === "false" || sentinel === "true") {
+    if (route !== AUTHORIZE_ROUTE) {
+      reject(sourceName, trimmedBody, "sentinel_in_access_filter", `a bare \`${sentinel}\` is not allowed in \`#(access_filter)\` — ` + (sentinel === "false" ? "write `#(authorize) false`, which refuses the caller " + "rather than serving them zero rows." : "it filters nothing; delete the annotation, or write " + "`#(authorize) true` to re-open a locked base."));
+    }
+    return [{ scope: sentinel === "false" ? "deny_all" : "admit_all" }];
+  }
+  const { terms: rawTerms, compoundTokens } = splitTerms(trimmedBody);
+  if (compoundTokens.length > 0) {
+    reject(sourceName, trimmedBody, "compound_boolean", `a compound boolean (\`${compoundTokens[0]}\`) is not allowed — ` + "join terms with `and` only.");
+  }
+  const parsed = rawTerms.map((term) => parseTerm(sourceName, trimmedBody, term, givenDeclaredTypes));
+  const ADMITTED_SCOPE = {
+    [AUTHORIZE_ROUTE]: "source_level",
+    [ACCESS_FILTER_ROUTE]: "row_level"
+  };
+  const admitted = ADMITTED_SCOPE[route];
+  const offending = parsed.find((t) => t.scope !== admitted);
+  if (offending) {
+    const inLock = route === AUTHORIZE_ROUTE;
+    reject(sourceName, trimmedBody, inLock ? "row_level_term_in_authorize" : "source_level_term_in_access_filter", inLock ? "a row-level term (field on the left) is not allowed in " + "`#(authorize)`, which decides whether the caller may reach " + "the source at all — move the term to `#(access_filter)`." : "a source-level term (literal on the left) is not allowed in " + "`#(access_filter)`, which decides which rows a caller may " + "see — move the term to `#(authorize)`, which refuses a " + "caller it does not admit rather than serving them zero rows.");
+  }
+  assertAuthorizeGrammarTermsCoherent(sourceName, parsed.map((term) => ({ term, route })));
+  return parsed;
+}
+function containsRetiredRouteTag(texts) {
+  for (const text of texts) {
+    const route = noteRoute2(text);
+    if (route !== undefined && RETIRED_ROUTES.includes(route)) {
+      return route;
+    }
+  }
+  return;
+}
+function reachesRetiredRouteTagBelow(node, seen = new WeakSet, depth = 0) {
+  if (depth > MAX_RETIRED_ROUTE_WALK_DEPTH) {
+    throw new Error("retired-route IR walk exceeded max depth");
+  }
+  if (node === null || typeof node !== "object")
+    return;
+  if (seen.has(node))
+    return;
+  seen.add(node);
+  if (Array.isArray(node)) {
+    for (const item of node) {
+      const found = reachesRetiredRouteTagBelow(item, seen, depth + 1);
+      if (found)
+        return found;
+    }
+    return;
+  }
+  const record = node;
+  if (depth > 0) {
+    for (const key of ["blockNotes", "notes"]) {
+      const arr = record[key];
+      if (!Array.isArray(arr))
+        continue;
+      const texts = arr.map((n) => typeof n === "string" ? n : n && typeof n === "object" && typeof n.text === "string" ? n.text : undefined).filter((text) => text !== undefined);
+      const found = containsRetiredRouteTag(texts);
+      if (found)
+        return found;
+    }
+  }
+  for (const [key, value] of Object.entries(record)) {
+    if (depth === 0 && key === "annotations")
+      continue;
+    const found = reachesRetiredRouteTagBelow(value, seen, depth + 1);
+    if (found)
+      return found;
+  }
+  return;
+}
+var AuthorizeGrammarError, IDENT = "[A-Za-z_][A-Za-z0-9_]*", QUOTED_IDENT = "`[^`]+`", SEGMENT, FIELD_PATH_RE, GIVEN_REF_RE, STRING_LITERAL_RE, NEGATED_OPERATOR_RE, COMPARISON_OPERATOR_RE, GRAMMAR_SUMMARY, IN_OPERATOR_RE, EQ_OPERATOR_RE, RETIRED_ROUTES, MAX_RETIRED_ROUTE_WALK_DEPTH = 200;
+var init_authorize_grammar = __esm(() => {
+  init_errors();
+  init_authorize_routes();
+  AuthorizeGrammarError = class AuthorizeGrammarError extends ModelCompilationError {
+    rejectionCause;
+    constructor(rejectionCause, message) {
+      super({ message });
+      this.rejectionCause = rejectionCause;
+    }
+  };
+  SEGMENT = `(?:${IDENT}|${QUOTED_IDENT})`;
+  FIELD_PATH_RE = new RegExp(`^${SEGMENT}(?:\\.${SEGMENT})*$`);
+  GIVEN_REF_RE = new RegExp(`^\\$(${IDENT})$`);
+  STRING_LITERAL_RE = /^(?:'(?:\\.|[^'\\])*'|"(?:\\.|[^"\\])*")$/;
+  NEGATED_OPERATOR_RE = /!=/gu;
+  COMPARISON_OPERATOR_RE = /(?:>=|<=|>|<)/gu;
+  GRAMMAR_SUMMARY = "An authorize gate only accepts one or more `and`-joined terms, each " + "either `<column> <op> $GIVEN` (a single field or a dotted join " + "path on the left) or `'<literal>' in $GIVEN` (a literal on the " + "left), where <op> is fixed by the given's own arity: `in` for a " + "list-typed given, `=` for a scalar one.";
+  IN_OPERATOR_RE = /\bin\b/giu;
+  EQ_OPERATOR_RE = /=/gu;
+  RETIRED_ROUTES = ["partition"];
+});
+
 // src/service/gate_dimension.ts
 import {
   isJoined,
@@ -271982,11 +272403,12 @@ function containsNegatedMembership(node, depth = 0) {
     return containsNegatedMembership(n.e, depth + 1);
   return false;
 }
-function validateSourceLineGateGivenUsage(sourceName, struct, refSummary, conditionExpr, modelDef, onWarning) {
+function validateSourceLineGateGivenUsage(sourceName, route, struct, refSummary, conditionExpr, modelDef, onWarning) {
+  const gate = `#(${route}) gate`;
   const expansion = expandRefSummaryGivenIds(struct, refSummary);
   if (!expansion.ok) {
     throw new ModelCompilationError({
-      message: `#(authorize) on source "${sourceName}" references ` + `"${expansion.unresolvedPath}", which could not be resolved to a ` + `field this model can reach. An unresolvable reference is refused, ` + `not treated as referencing no given`
+      message: `The ${gate} on source "${sourceName}" references ` + `"${expansion.unresolvedPath}", which could not be resolved to a ` + `field this model can reach. An unresolvable reference is refused, ` + `not treated as referencing no given`
     });
   }
   const givenIds = expansion.givenIds;
@@ -271994,15 +272416,15 @@ function validateSourceLineGateGivenUsage(sourceName, struct, refSummary, condit
     const given = modelDef.givens?.[id];
     if (given && (given.default !== undefined || given.defaultText !== undefined)) {
       throw new ModelCompilationError({
-        message: `#(authorize) on source "${sourceName}" references ` + `\`$${given.name}\`, which is declared with a default. A ` + `caller who supplies no value for \`$${given.name}\` gets ` + `that default, which can admit rows the gate was meant to ` + `exclude. Declare \`$${given.name}\` with no default`
+        message: `The ${gate} on source "${sourceName}" references ` + `\`$${given.name}\`, which is declared with a default. A ` + `caller who supplies no value for \`$${given.name}\` gets ` + `that default, which can admit what the gate was meant to ` + `exclude. Declare \`$${given.name}\` with no default`
       });
     }
   }
   if (givenIds.size === 0) {
-    onWarning?.("source_line_gate_no_given_reference", `#(authorize) on source "${sourceName}" references no given; it is ` + `a fixed predicate, not an access rule keyed on the caller`);
+    onWarning?.("source_line_gate_no_given_reference", `The ${gate} on source "${sourceName}" references no given; it is ` + `a fixed predicate, not an access rule keyed on the caller`);
   }
   if (containsNegatedMembership(conditionExpr)) {
-    onWarning?.("source_line_gate_negated_membership", `#(authorize) on source "${sourceName}" negates a membership test; ` + `an empty given then matches every row instead of none`);
+    onWarning?.("source_line_gate_negated_membership", `The ${gate} on source "${sourceName}" negates a membership test; ` + `an empty given then matches everything instead of nothing`);
   }
 }
 var init_gate_dimension = __esm(() => {
@@ -272030,10 +272452,10 @@ function resolveDeclaredSource(struct, modelDef) {
   }
   return sawBrokenEntry ? { kind: "unresolvable" } : { kind: "none" };
 }
-function ancestorGateExprs(struct, modelDef, seen = new Set) {
+function ancestorGateExprs(struct, modelDef, route, seen = new Set) {
   let inherited = struct.annotations?.inherits;
   for (let depth = 0;inherited && depth < ANCESTOR_WALK_MAX_DEPTH; depth++) {
-    const exprs2 = collectAuthorizeExprs(ownLevelNoteTexts(inherited));
+    const exprs2 = collectAuthorizeExprsForRoute(ownLevelNoteTexts(inherited), route);
     if (exprs2.length > 0)
       return exprs2;
     inherited = inherited.inherits;
@@ -272041,15 +272463,17 @@ function ancestorGateExprs(struct, modelDef, seen = new Set) {
   if (inherited)
     return ["false"];
   seen.add(struct);
-  if (seen.size > ANCESTOR_WALK_MAX_DEPTH)
+  if (seen.size > ANCESTOR_WALK_MAX_DEPTH) {
     return ["false"];
+  }
   const declared = resolveDeclaredSource(struct, modelDef);
-  if (declared.kind === "unresolvable")
+  if (declared.kind === "unresolvable") {
     return ["false"];
+  }
   if (declared.kind === "none" || seen.has(declared.source))
     return [];
-  const exprs = collectAuthorizeExprs(ownLevelNoteTexts(declared.source.annotations));
-  return exprs.length > 0 ? exprs : ancestorGateExprs(declared.source, modelDef, seen);
+  const exprs = collectAuthorizeExprsForRoute(ownLevelNoteTexts(declared.source.annotations), route);
+  return exprs.length > 0 ? exprs : ancestorGateExprs(declared.source, modelDef, route, seen);
 }
 function resolveQuerySourceBase(struct, modelDef) {
   const duck = struct;
@@ -272063,8 +272487,8 @@ function resolveCompositeResolvedBase(struct) {
   const duck = struct;
   return duck.type === "query_source" ? duck.query?.compositeResolvedSourceDef : undefined;
 }
-function effectiveAncestorGateExprs(struct, modelDef, seen = new Set) {
-  const direct = ancestorGateExprs(struct, modelDef, new Set(seen));
+function effectiveAncestorGateExprs(struct, modelDef, route, seen = new Set) {
+  const direct = ancestorGateExprs(struct, modelDef, route, new Set(seen));
   if (direct.length > 0)
     return [direct];
   if (seen.has(struct))
@@ -272074,18 +272498,19 @@ function effectiveAncestorGateExprs(struct, modelDef, seen = new Set) {
   const base = resolveQuerySourceBase(struct, modelDef);
   if (!base) {
     const duck = struct;
-    if (duck.type === "query_source")
+    if (duck.type === "query_source") {
       groups.push(["false"]);
+    }
   } else if (!seen.has(base)) {
-    const ownExprs = collectAuthorizeExprs(ownLevelNoteTexts(base.annotations));
-    groups.push(...ownExprs.length > 0 ? [ownExprs] : effectiveAncestorGateExprs(base, modelDef, seen));
+    const ownExprs = collectAuthorizeExprsForRoute(ownLevelNoteTexts(base.annotations), route);
+    groups.push(...ownExprs.length > 0 ? [ownExprs] : effectiveAncestorGateExprs(base, modelDef, route, seen));
   }
   const composite = resolveCompositeResolvedBase(struct);
   if (composite && !seen.has(composite)) {
     const parentOwnNotes = base ? ownLevelNotes(base.annotations) : [];
     const compositeOwnNotes = ownLevelNotes(composite.annotations).filter((note) => !parentOwnNotes.includes(note));
-    const compositeOwn = collectAuthorizeExprs(compositeOwnNotes.map((note) => note.text));
-    groups.push(...compositeOwn.length > 0 ? [compositeOwn] : effectiveAncestorGateExprs(composite, modelDef, seen));
+    const compositeOwn = collectAuthorizeExprsForRoute(compositeOwnNotes.map((note) => note.text), route);
+    groups.push(...compositeOwn.length > 0 ? [compositeOwn] : effectiveAncestorGateExprs(composite, modelDef, route, seen));
   }
   return groups;
 }
@@ -272114,120 +272539,9 @@ var init_gate_registry_walk = __esm(() => {
   init_authorize();
 });
 
-// src/service/partition_annotation.ts
-import { payloadOf as payloadOf2, routeOf as routeOf2 } from "@malloydata/malloy";
-function noteRoute2(text) {
-  return routeOf2({ value: text.trimStart() });
-}
-function containsPartitionAnnotationTag(texts) {
-  return texts.some((text) => noteRoute2(text) === PARTITION_ROUTE);
-}
-function reachesPartitionTagBelow(node, seen = new WeakSet, depth = 0) {
-  if (depth > MAX_PARTITION_IR_WALK_DEPTH) {
-    throw new Error("partition-marker IR walk exceeded max depth");
-  }
-  if (node === null || typeof node !== "object")
-    return false;
-  if (seen.has(node))
-    return false;
-  seen.add(node);
-  if (Array.isArray(node)) {
-    return node.some((item) => reachesPartitionTagBelow(item, seen, depth + 1));
-  }
-  const record = node;
-  if (depth > 0 && record.join !== undefined)
-    return false;
-  if (depth > 0) {
-    for (const key of ["blockNotes", "notes"]) {
-      const arr = record[key];
-      if (!Array.isArray(arr))
-        continue;
-      const texts = arr.map((n) => typeof n === "string" ? n : n && typeof n === "object" && typeof n.text === "string" ? n.text : undefined).filter((text) => text !== undefined);
-      if (containsPartitionAnnotationTag(texts))
-        return true;
-    }
-  }
-  return Object.entries(record).some(([key, value]) => depth === 0 && key === "annotations" ? false : reachesPartitionTagBelow(value, seen, depth + 1));
-}
-function notePayload2(text) {
-  return payloadOf2({ value: text.trimStart() }) ?? "";
-}
-function rejectionMessage(sourceName, body, detail) {
-  return `Source "${sourceName}" declares \`#(partition) ${body}\`: ${detail} ` + `#(partition) only accepts \`<column> = $GIVEN\`, where <column> is a ` + `single field or a dotted join path.`;
-}
-function reject(sourceName, body, cause, detail) {
-  throw new PartitionAnnotationError(cause, rejectionMessage(sourceName, body, detail));
-}
-function parsePartitionAnnotation(sourceName, annotationText) {
-  if (noteRoute2(annotationText) !== PARTITION_ROUTE)
-    return null;
-  const body = notePayload2(annotationText).trim();
-  if (body.length === 0) {
-    reject(sourceName, body, "empty_body", "the expression body is empty.");
-  }
-  if (COMPOUND_BOOLEAN_RE.test(body)) {
-    reject(sourceName, body, "compound_boolean", "a compound boolean (`and`/`or`/`not`) is not allowed — declare one " + "`#(partition)` marker per column.");
-  }
-  if (IN_OPERATOR_RE.test(body)) {
-    reject(sourceName, body, "in_operator", "the `in` operator is not allowed.");
-  }
-  if (NEGATED_OPERATOR_RE.test(body)) {
-    reject(sourceName, body, "negated_operator", "`!=` is not allowed.");
-  }
-  if (COMPARISON_OPERATOR_RE.test(body)) {
-    reject(sourceName, body, "comparison_operator", "only `=` is allowed, not `<`/`>`/`<=`/`>=`.");
-  }
-  const eq = body.indexOf("=");
-  if (eq === -1) {
-    reject(sourceName, body, "malformed_body", "no `=` was found.");
-  }
-  const left = body.slice(0, eq).trim();
-  const right = body.slice(eq + 1).trim();
-  if (!FIELD_PATH_RE.test(left)) {
-    reject(sourceName, body, "left_not_field_path", `\`${left}\` is not a field path — the left side must be a single ` + "column or a dotted join path, not an expression.");
-  }
-  const givenMatch = GIVEN_REF_RE.exec(right);
-  if (!givenMatch) {
-    reject(sourceName, body, "missing_given_reference", `\`${right}\` is not a given reference — the right side must be ` + "`$NAME`.");
-  }
-  return { column: left, given: givenMatch[1] };
-}
-function collectPartitionPairs(sourceName, annotationTexts2) {
-  const pairs = [];
-  const seenGivens = new Map;
-  for (const text of annotationTexts2) {
-    const pair = parsePartitionAnnotation(sourceName, text);
-    if (pair === null)
-      continue;
-    const priorColumn = seenGivens.get(pair.given);
-    if (priorColumn !== undefined) {
-      throw new PartitionAnnotationError("duplicate_given", `Source "${sourceName}" declares \`#(partition)\` on both ` + `\`${priorColumn}\` and \`${pair.column}\` for the same given ` + `\`$${pair.given}\` — a given can back at most one partition ` + `column per source.`);
-    }
-    seenGivens.set(pair.given, pair.column);
-    pairs.push(pair);
-  }
-  return pairs;
-}
-var PARTITION_ROUTE = "partition", MAX_PARTITION_IR_WALK_DEPTH = 200, PartitionAnnotationError, IDENT = "[A-Za-z_][A-Za-z0-9_]*", FIELD_PATH_RE, GIVEN_REF_RE, COMPOUND_BOOLEAN_RE, IN_OPERATOR_RE, NEGATED_OPERATOR_RE, COMPARISON_OPERATOR_RE;
-var init_partition_annotation = __esm(() => {
-  init_errors();
-  PartitionAnnotationError = class PartitionAnnotationError extends ModelCompilationError {
-    rejectionCause;
-    constructor(rejectionCause, message) {
-      super({ message });
-      this.rejectionCause = rejectionCause;
-    }
-  };
-  FIELD_PATH_RE = new RegExp(`^${IDENT}(?:\\.${IDENT})*$`);
-  GIVEN_REF_RE = new RegExp(`^\\$(${IDENT})$`);
-  COMPOUND_BOOLEAN_RE = /\b(and|or|not)\b/i;
-  IN_OPERATOR_RE = /\bin\b/i;
-  NEGATED_OPERATOR_RE = /!=/;
-  COMPARISON_OPERATOR_RE = /(>=|<=|>|<)/;
-});
-
 // src/service/gate_classification.ts
 import {
+  isJoined as isJoined2,
   isSourceDef as isSourceDef5
 } from "@malloydata/malloy";
 function createGateClassificationDeps(givens, modelPath) {
@@ -272237,30 +272551,41 @@ function createGateClassificationDeps(givens, modelPath) {
     modelPath
   };
 }
-function gateExprsForOwnAnnotations(struct, modelDef, excludeNotes = []) {
+function gateExprsForOwnAnnotations(struct, route, modelDef, excludeNotes = []) {
   const ownNotes = ownLevelNotes(struct.annotations).filter((note) => !excludeNotes.includes(note));
   try {
-    const own = collectAuthorizeExprs(ownNotes.map((note) => note.text));
+    const own = collectAuthorizeExprsForRoute(ownNotes.map((note) => note.text), route);
     if (own.length > 0) {
       return { exprs: own, fromAncestor: false };
     }
-    const ancestor = ancestorGateExprs(struct, modelDef);
+    const ancestor = ancestorGateExprs(struct, modelDef, route);
     return { exprs: ancestor, fromAncestor: ancestor.length > 0 };
   } catch {
-    return { exprs: ["false"], fromAncestor: false };
+    return {
+      exprs: ["false"],
+      fromAncestor: false
+    };
   }
 }
 function collectEntryPointGates(struct, modelDef, seen = new Set, treatAsOwnGate = false, entryPointStruct = struct, excludeNotes = []) {
+  const results = [];
+  for (const route of CANONICAL_AUTHORIZE_ROUTES) {
+    results.push(...collectEntryPointGatesForRoute(struct, modelDef, route, new Set(seen), treatAsOwnGate, entryPointStruct, excludeNotes));
+  }
+  return results;
+}
+function collectEntryPointGatesForRoute(struct, modelDef, route, seen, treatAsOwnGate, entryPointStruct, excludeNotes) {
   if (!struct || !modelDef || seen.has(struct))
     return [];
   seen.add(struct);
   const results = [];
   const label = struct.as ?? struct.name;
-  const { exprs: ownExprs, fromAncestor } = gateExprsForOwnAnnotations(struct, modelDef, excludeNotes);
+  const { exprs: ownExprs, fromAncestor } = gateExprsForOwnAnnotations(struct, route, modelDef, excludeNotes);
   if (ownExprs.length > 0) {
     results.push({
       label,
       exprs: ownExprs,
+      route,
       selfContained: fromAncestor || !treatAsOwnGate,
       struct: entryPointStruct
     });
@@ -272269,17 +272594,18 @@ function collectEntryPointGates(struct, modelDef, seen = new Set, treatAsOwnGate
   if (duck.type === "query_source") {
     const base = resolveQuerySourceBase(struct, modelDef);
     if (base) {
-      results.push(...collectEntryPointGates(base, modelDef, seen, false, entryPointStruct));
+      results.push(...collectEntryPointGatesForRoute(base, modelDef, route, seen, false, entryPointStruct, []));
     } else {
       results.push({
         label,
         exprs: ["false"],
+        route,
         selfContained: true
       });
     }
     const resolved = duck.query?.compositeResolvedSourceDef;
     if (resolved) {
-      results.push(...collectEntryPointGates(resolved, modelDef, seen, false, entryPointStruct, base ? ownLevelNotes(base.annotations) : []));
+      results.push(...collectEntryPointGatesForRoute(resolved, modelDef, route, seen, false, entryPointStruct, base ? ownLevelNotes(base.annotations) : []));
     }
   }
   return results;
@@ -272296,7 +272622,7 @@ async function resolveGateShape(entry, originModelDef, graftScope, deps) {
     return { shape: "rejected" };
   }
   const filterText = gateFilterText(entry.exprs);
-  const cacheKey = `${graftScope.cacheScope}\x00${graftTarget}\x00${filterText}`;
+  const cacheKey = `${graftScope.cacheScope}\x00${entry.route}\x00${graftTarget}\x00${filterText}`;
   let cached2 = deps.gateShapeCache.get(cacheKey);
   if (!cached2) {
     let condition;
@@ -272319,7 +272645,11 @@ async function resolveGateShape(entry, originModelDef, graftScope, deps) {
         detail: "this entry's lifted condition carries no usable expression"
       };
     } else if (isBareFalseLiteral(condition.e)) {
-      classification = { shape: "row_level", givenNames: [] };
+      classification = {
+        shape: "row_level",
+        givenNames: [],
+        givenNamesById: new Map
+      };
     } else {
       const targetStruct = graftScope.modelDef.contents[graftTarget];
       if (!isSourceDef5(targetStruct)) {
@@ -272337,7 +272667,13 @@ async function resolveGateShape(entry, originModelDef, graftScope, deps) {
             detail: `this gate references \`${expansion.unresolvedPath}\`, which could not be resolved on the graft target`
           };
         } else {
-          const givenNames = Array.from(expansion.givenIds).map((id) => graftScope.modelDef.givens?.[id]?.name).filter((name) => !!name);
+          const givenNamesById = new Map;
+          for (const id of expansion.givenIds) {
+            const name = graftScope.modelDef.givens?.[id]?.name;
+            if (name)
+              givenNamesById.set(id, name);
+          }
+          const givenNames = Array.from(givenNamesById.values());
           const literalNames = referencedGivenNames(filterText);
           const accountedFor = new Set(givenNames);
           const unaccounted = literalNames.filter((name) => !accountedFor.has(name));
@@ -272348,7 +272684,11 @@ async function resolveGateShape(entry, originModelDef, graftScope, deps) {
               detail: "this gate references a given id that does not resolve to a name on this model"
             };
           } else {
-            classification = { shape: "row_level", givenNames };
+            classification = {
+              shape: "row_level",
+              givenNames,
+              givenNamesById
+            };
           }
         }
       }
@@ -272374,6 +272714,14 @@ async function resolveGateShape(entry, originModelDef, graftScope, deps) {
   if (cached2.classification.shape === "rejected") {
     return { shape: "rejected", cause: cached2.classification.cause };
   }
+  if (entry.route === AUTHORIZE_ROUTE) {
+    return {
+      shape: "lock",
+      condition: cached2.condition,
+      givenNames: cached2.classification.givenNames,
+      givenNamesById: cached2.classification.givenNamesById
+    };
+  }
   return {
     shape: "row_level",
     graftTarget,
@@ -272456,142 +272804,120 @@ function isBareFalseLiteral(expr) {
 function computeGivenDeclaredTypes(givens) {
   return new Map((givens ?? []).filter((g) => g.name != null && g.type != null).map((g) => [g.name, g.type]));
 }
-function resolveEntryPointPartitions(struct, modelDef, seen = new Set) {
-  if (!struct || !modelDef || seen.has(struct))
-    return [];
-  seen.add(struct);
-  const label = struct.as ?? struct.name;
-  const own = collectPartitionPairs(label, ownLevelNotes(struct.annotations).map((note) => note.text));
-  if (own.length > 0)
-    return own;
-  let inherited = struct.annotations?.inherits;
-  for (let depth = 0;inherited && depth < ANCESTOR_WALK_MAX_DEPTH; depth++) {
-    const pairs = collectPartitionPairs(label, ownLevelNoteTexts(inherited));
-    if (pairs.length > 0)
-      return pairs;
-    inherited = inherited.inherits;
-  }
-  if (inherited)
-    throw unresolvableAncestry(label);
-  const declared = resolveDeclaredSource(struct, modelDef);
-  if (declared.kind === "unresolvable")
-    throw unresolvableAncestry(label);
-  if (declared.kind === "resolved") {
-    const pairs = resolveEntryPointPartitions(declared.source, modelDef, seen);
-    if (pairs.length > 0)
-      return pairs;
-  }
-  const queryBase = resolveQuerySourceBase(struct, modelDef);
-  if (queryBase)
-    return resolveEntryPointPartitions(queryBase, modelDef, seen);
-  return [];
-}
-function unresolvableAncestry(label) {
-  return new PartitionAnnotationError("ancestry_unresolvable", `Could not resolve whether source "${label}" carries a ` + `\`#(partition)\` marker: the derivation chain it inherits from ` + `could not be read. Denying rather than serving unfiltered.`);
-}
-function assertPartitionAnnotationsValid(modelDef) {
+function assertAuthorizeGrammarValid(modelDef, authorizeMap, authorizeOwnNotes, givenDeclaredTypes, onAdmitAllGate, attributedAuthorizeOwnNotes) {
   if (!modelDef)
     return;
-  for (const [key, obj] of Object.entries(modelDef.contents)) {
-    if (!isSourceDef5(obj))
-      continue;
-    const label = obj.as ?? obj.name ?? key;
-    if (obj.type !== "composite") {
-      let resolved = [];
-      try {
-        resolved = resolveEntryPointPartitions(obj, modelDef);
-      } catch (err) {
-        if (!(err instanceof PartitionAnnotationError) || err.rejectionCause !== "ancestry_unresolvable") {
-          throw err;
+  for (const [sourceName, groups] of authorizeMap) {
+    const struct = modelDef.contents[sourceName];
+    const ownGroupTerms = [];
+    const declaredAdmitAllRoutes = [];
+    for (const { route, exprs } of groups) {
+      const isOwn = (authorizeOwnNotes.get(sourceName)?.get(route)?.length ?? 0) > 0;
+      const filteredExprs = exprs.filter((expr) => (isOwn || expr !== "false") && !isLegacyQuotedPayload(expr));
+      const groupTerms = [];
+      for (const expr of filteredExprs) {
+        const terms = parseAuthorizeGrammarBody(sourceName, expr, givenDeclaredTypes, route);
+        for (const term of terms) {
+          groupTerms.push({ term, route });
+          if (term.scope === "admit_all" && (attributedAuthorizeOwnNotes?.get(sourceName)?.get(route)?.length ?? 0) > 0) {
+            declaredAdmitAllRoutes.push(route);
+          }
+          if (term.scope === "row_level" && isSourceDef5(struct)) {
+            assertNoFanoutFieldPath(sourceName, struct, term.fieldPath, term.fieldPathSegments);
+          }
         }
-        continue;
       }
-      assertNoUnreachableMarker(obj, label, resolved);
-      continue;
+      if (isOwn) {
+        ownGroupTerms.push(...groupTerms);
+      } else {
+        assertAuthorizeGrammarTermsCoherent(sourceName, groupTerms);
+      }
     }
-    if (resolveEntryPointPartitions(obj, modelDef).length > 0) {
-      throw new PartitionAnnotationError("partitioned_composite", `Source "${label}" is a composite source (\`compose(...)\`) and ` + `also declares \`#(partition)\` (on itself or an ancestor it ` + `derives from). A composite run target compiles each query ` + `against one resolved member branch, which a partition filter ` + `cannot attach to — declare \`#(partition)\` on a non-composite ` + `source instead.`);
+    if (ownGroupTerms.length > 0) {
+      assertAuthorizeGrammarTermsCoherent(sourceName, ownGroupTerms);
     }
-    const marked = partitionedMemberLabel(obj, modelDef);
-    if (marked !== undefined) {
-      throw new PartitionAnnotationError("partitioned_composite", `Source "${label}" is a composite source (\`compose(...)\`) with ` + `member "${marked}", which declares \`#(partition)\`. MEASURED: ` + `querying the composite reads EVERY partition of that member — ` + `the graft lands on the composite's own struct, not the ` + `resolved member branch, so no filter reaches the executed ` + `query. Remove the composite, or drop \`#(partition)\` from ` + `"${marked}" and expose it as its own source.`);
+    for (const route of declaredAdmitAllRoutes) {
+      onAdmitAllGate?.(sourceName, route);
     }
   }
 }
-function assertNoUnreachableMarker(struct, label, resolved) {
-  if (resolved.length > 0)
-    return;
-  let reachesBelow;
-  try {
-    reachesBelow = reachesPartitionTagBelow(struct);
-  } catch {
-    reachesBelow = true;
-  }
-  if (!reachesBelow)
-    return;
-  throw new PartitionAnnotationError("marker_unreachable", `Source "${label}" carries a \`#(partition)\` marker that is not ` + `declared on the source itself — it sits on a field, a view, or an ` + `inline \`compose(...)\` inside it. Nothing would filter this ` + `source: every caller would read every partition. Move the marker ` + `onto the \`source:\` declaration.`);
-}
-function partitionedMemberLabel(composite, modelDef, seen = new Set) {
-  if (seen.has(composite))
-    return;
-  seen.add(composite);
-  for (const member of composite.sources ?? []) {
-    const label = member.as ?? member.name;
-    if (resolveEntryPointPartitions(member, modelDef).length > 0) {
-      return label;
+function fanoutSegment(struct, path9) {
+  let current = struct;
+  for (let i = 0;i < path9.length - 1; i++) {
+    const seg = path9[i];
+    const field = (current.fields ?? []).find((f) => (f.as ?? f.name) === seg);
+    if (!field)
+      return { segment: seg, reason: "unresolved" };
+    if (isJoined2(field) && field.join !== "one") {
+      return { segment: seg, reason: "fanout" };
     }
-    if (member.type === "composite") {
-      const nested = partitionedMemberLabel(member, modelDef, seen);
-      if (nested !== undefined)
-        return nested;
+    if (!isSourceDef5(field) && field.type !== "record" && field.type !== "array") {
+      return { segment: seg, reason: "unresolved" };
     }
+    current = field;
   }
   return;
 }
-async function resolvePartitionGraftEntries(struct, originModelDef, graftScope, deps) {
-  if (!struct || !originModelDef)
-    return [];
-  const pairs = resolveEntryPointPartitions(struct, originModelDef);
-  if (pairs.length === 0)
-    return [];
-  const label = struct.as ?? struct.name;
-  if (!graftScope) {
-    logger.debug("Partition filter has no graft scope to attach to; denying", { modelPath: deps.modelPath, label });
-    throw new Error(`partition on "${label}" has no graft scope`);
-  }
-  const graftTarget = resolveGraftTarget(struct, originModelDef, graftScope.modelDef);
-  if (!graftTarget) {
-    logger.debug("Partition filter resolved to no graft target; denying", {
-      modelPath: deps.modelPath,
-      label
-    });
-    throw new Error(`partition on "${label}" resolved to no graft target`);
+function assertNoFanoutFieldPath(sourceName, struct, fieldPath, fieldPathSegments) {
+  const finding = fanoutSegment(struct, fieldPathSegments);
+  if (finding === undefined)
+    return;
+  const detail = finding.reason === "fanout" ? `which reaches through \`${finding.segment}\`, a fan-out join ` + `(\`join_many\`/\`join_cross\`, or a repeated record) — the ` + `entry row has many values for what follows, so there is no ` + `single key to compare against a given. Gate on a field reached ` + `only through \`join_one\` joins.` : `whose segment \`${finding.segment}\` does not resolve against ` + `this source — refused rather than assumed safe.`;
+  throw new AuthorizeGrammarError("fanout_path", `Source "${sourceName}" declares an authorize gate on \`${fieldPath}\`, ${detail}`);
+}
+function collectRetiredRouteMarkers(modelDef) {
+  const found = [];
+  if (!modelDef)
+    return found;
+  const fileMatch = containsRetiredRouteTag(ownLevelNoteTexts(modelAnnotations(modelDef)));
+  if (fileMatch) {
+    found.push(`the model itself declares a retired \`##(${fileMatch})\` annotation`);
   }
-  const entries = [];
-  for (const pair of pairs) {
-    if (!deps.givenDeclaredTypes.has(pair.given)) {
-      logger.warn("Partition references a given off the model surface; denying", { modelPath: deps.modelPath, graftTarget, givenName: pair.given });
-      throw new Error(`partition on "${label}" references \`$${pair.given}\`, which is not on this model's given surface`);
+  for (const [key, obj] of Object.entries(modelDef.contents)) {
+    const isQuery = obj.type === "query";
+    if (!isSourceDef5(obj) && !isQuery)
+      continue;
+    const label = obj.as ?? obj.name ?? key;
+    const noun = isQuery ? "query" : "source";
+    const ownMatch = containsRetiredRouteTag(annotationTexts(obj.annotations) ?? []);
+    if (ownMatch) {
+      found.push(`${noun} "${label}" declares a retired \`#(${ownMatch})\` annotation`);
+      continue;
+    }
+    if (isQuery) {
+      continue;
+    }
+    let belowMatch;
+    try {
+      belowMatch = reachesRetiredRouteTagBelow(obj);
+    } catch {
+      belowMatch = RETIRED_ROUTES[0];
+    }
+    if (belowMatch) {
+      found.push(`source "${label}" carries a retired \`#(${belowMatch})\` ` + `annotation somewhere in its IR (not on the source line itself)`);
     }
-    const filterText = `${pair.column} = $${pair.given}`;
-    const condition = await liftGateCondition(graftTarget, filterText, graftScope.materializer);
-    entries.push({
-      label,
-      graftTarget,
-      filterText,
-      condition,
-      givenNames: [pair.given]
-    });
   }
-  return entries;
+  return found;
+}
+function assertNoRetiredRouteMarkers(found) {
+  if (found.length === 0)
+    return;
+  throw new ModelCompilationError({
+    message: `These sources carry a marker from a retired annotation route:
+` + `${found.map((f) => `  - ${f}`).join(`
+`)}
+` + `The route is no longer enforced by anything, so Malloy would ` + `otherwise parse it, load the model clean, and serve every row as ` + `if the marker were never written. Remove the annotation.`
+  });
 }
 var init_gate_classification = __esm(() => {
+  init_errors();
   init_logger();
   init_annotations();
   init_authorize();
+  init_authorize_grammar();
+  init_authorize_routes();
   init_gate_dimension();
   init_gate_registry_walk();
-  init_partition_annotation();
 });
 
 // src/service/persist_dynamic_terms.ts
@@ -273061,14 +273387,7 @@ function assertMaterializationEligible(persistSource, annotationFields) {
     recordEligibilityRefused("authorize");
     throw new MaterializationEligibilityError({
       reason: "authorize",
-      message: `Source '${sourceName}' cannot be materialized into a storage ` + `destination: it is protected by an #(authorize) gate (its own or a ` + `joined source's). An authorize expression is evaluated per request; ` + `a materialized-once table served frozen carries no gate, so it would ` + `be served to everyone, bypassing authorization. This is refused for ` + `safety. Serve this source live (drop 'storage=').`
-    });
-  }
-  if (referencesPartition(persistSource)) {
-    recordEligibilityRefused("partition");
-    throw new MaterializationEligibilityError({
-      reason: "partition",
-      message: `Source '${sourceName}' cannot be materialized into a storage ` + `destination: it declares a #(partition) marker. A partition ` + `filter binds a given at query time (the same mechanism as ` + `row-level access control), so a materialized-once table served ` + `frozen would leak every partition's rows to every caller. This ` + `is refused for safety. Serve this source live (drop 'storage=').`
+      message: `Source '${sourceName}' cannot be materialized into a storage ` + `destination: it is protected by a gate — #(authorize) or ` + `#(access_filter), its own or a joined source's. Both are evaluated ` + `per request; a materialized-once table served frozen carries no ` + `gate, so it would be served to everyone, bypassing authorization. ` + `This is refused for safety. Serve this source live (drop ` + `'storage=').`
     });
   }
   const partition = resolvePartitionColumns(persistSource, annotationFields);
@@ -273104,15 +273423,6 @@ function assertColocatedPersistNotAuthorizeGated(persistSource, sourceName = per
       message: `${what2} cannot be materialized (colocated '#@ persist'): ` + `${partition.detail}.`
     });
   }
-  if (referencesPartition(persistSource)) {
-    recordEligibilityRefused("partition");
-    const what2 = origin2 === "preaggregate" ? `Pre-aggregation rollup '${sourceName}'` : `Source '${sourceName}'`;
-    const gated2 = origin2 === "preaggregate" ? `the source '${sourceName}' rolls up declares` : `it declares`;
-    throw new MaterializationEligibilityError({
-      reason: "partition",
-      message: `${what2} cannot be materialized (colocated '#@ persist'): ` + `${gated2} a #(partition) marker. A partition filter binds a ` + `given at query time; this pass cannot prove the persisted ` + `artifact's read path still applies it, so this is refused for ` + `safety. Move the marker to a source that is not materialized, ` + `or stop persisting this one.`
-    });
-  }
   if (buildSubstitutesAGiven(persistSource)) {
     if (origin2 === "preaggregate") {
       recordEligibilityRefused("preaggregate_over_dynamic_source");
@@ -273163,44 +273473,6 @@ function unboundParameterNames(persistSource) {
   }
   return unbound;
 }
-function referencesPartition(persistSource) {
-  try {
-    return walkForPartition(persistSource._sourceDef, new WeakSet, 0);
-  } catch {
-    return true;
-  }
-}
-function walkForPartition(node, seen, depth) {
-  if (depth > MAX_GIVEN_WALK_DEPTH) {
-    throw new Error("partition-usage walk exceeded max depth");
-  }
-  if (node === null || typeof node !== "object")
-    return false;
-  if (seen.has(node))
-    return false;
-  seen.add(node);
-  if (Array.isArray(node)) {
-    for (const item of node) {
-      if (walkForPartition(item, seen, depth + 1))
-        return true;
-    }
-    return false;
-  }
-  const record = node;
-  for (const key of ["blockNotes", "notes"]) {
-    const arr = record[key];
-    if (!Array.isArray(arr))
-      continue;
-    const texts = arr.map((n) => typeof n === "string" ? n : n && typeof n === "object" && typeof n.text === "string" ? n.text : undefined).filter((text) => text !== undefined);
-    if (containsPartitionAnnotationTag(texts))
-      return true;
-  }
-  for (const value of Object.values(record)) {
-    if (walkForPartition(value, seen, depth + 1))
-      return true;
-  }
-  return false;
-}
 function referencesAuthorize(persistSource) {
   try {
     return walkForAuthorize(persistSource._sourceDef, new WeakSet, 0);
@@ -273302,7 +273574,6 @@ var init_materialization_eligibility = __esm(() => {
   init_materialization_metrics();
   init_authorize();
   init_build_plan();
-  init_partition_annotation();
   init_persist_dynamic_terms();
 });
 
@@ -274165,9 +274436,11 @@ function extractRunTargetSourceName(query) {
 }
 function buildSourceAliasMap(query) {
   const aliasOf = new Map;
-  const declRe = /source\s*:\s*(?:`([^`]+)`|(\w+))\s+is\s+(?:`([^`]+)`|(\w+))/g;
+  const text = stripMalloyCommentsAndLiterals(query);
+  const ident = String.raw`(?:\x60([^\x60]+)\x60|([\p{L}\p{N}_]+))`;
+  const declRe = new RegExp(String.raw`source\s*:\s*${ident}(?:\s*\([^)]*\))?\s+is\s*\(?\s*${ident}`, "gu");
   let match;
-  while ((match = declRe.exec(query)) !== null) {
+  while ((match = declRe.exec(text)) !== null) {
     aliasOf.set(match[1] ?? match[2], match[3] ?? match[4]);
   }
   return aliasOf;
@@ -274218,8 +274491,9 @@ function stripMalloyCommentsAndLiterals(text) {
   }
   return out.join("");
 }
-function buildDerivationBaseMap(text) {
+function buildDerivationBaseMap(query) {
   const basesOf = new Map;
+  const text = stripMalloyCommentsAndLiterals(query);
   const ident = String.raw`(?:\x60([^\x60]+)\x60|([\p{L}\p{N}_]+))`;
   const declRe = new RegExp(String.raw`(?:source|query)\s*:\s*${ident}(?:\s*\([^)]*\))?\s+is\s*\(?\s*${ident}`, "gu");
   let match;
@@ -274237,7 +274511,7 @@ function buildDerivationBaseMap(text) {
 import {
   expressionIsAggregate,
   expressionIsAnalytic,
-  isJoined as isJoined2
+  isJoined as isJoined3
 } from "@malloydata/malloy";
 function isAccessRestricted2(f) {
   return f.accessModifier != null && f.accessModifier !== "public";
@@ -274249,13 +274523,13 @@ function isView(f) {
   return f.type === "turtle";
 }
 function isFanoutJoin(f) {
-  return isJoined2(f) && f.join !== "one";
+  return isJoined3(f) && f.join !== "one";
 }
 function isMeasure(f) {
   return expressionIsAggregate(f.expressionType) && !expressionIsAnalytic(f.expressionType);
 }
 function isGroupableDimension(f) {
-  if (isJoined2(f) || isView(f))
+  if (isJoined3(f) || isView(f))
     return false;
   if (f.expressionType === undefined)
     return true;
@@ -274275,7 +274549,7 @@ function validateGrainDimension(sourceName, measure, source, grainDimension) {
   if (!field) {
     return violation("unknown_grain_dimension", `Measure \`${measure}\` declares \`#@ preaggregate\` at a grain naming \`${grainDimension}\`, but \`${head}\` is not a field of \`${sourceName}\`. Use a dimension that exists on the source; a rollup can only group by the source's own dimensions.`);
   }
-  if (isJoined2(field)) {
+  if (isJoined3(field)) {
     return violation("grain_path_through_join", `Measure \`${measure}\` declares a grain of \`${grainDimension}\`, which reaches through the join \`${head}\`. Pre-aggregating across a join is not supported in this version; copy the value into a dimension on \`${sourceName}\` and group by that instead.`);
   }
   if (parts.length > 1) {
@@ -274324,7 +274598,7 @@ function validateSourcePreaggregation(sourceName, source) {
     if (!declaration.declared)
       continue;
     declaredFields.push(field);
-    if (isJoined2(field)) {
+    if (isJoined3(field)) {
       violations.push({
         code: "misplaced_on_join",
         sourceName,
@@ -274467,7 +274741,7 @@ var init_preaggregation_validation = __esm(() => {
 
 // src/service/source_extraction.ts
 import {
-  isJoined as isJoined3,
+  isJoined as isJoined4,
   isSourceDef as isSourceDef6,
   modelDefToModelInfo
 } from "@malloydata/malloy";
@@ -274521,7 +274795,7 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
         considerNoteOwner(authorizeNoteDeclaredBy, note, struct);
       }
     }
-    nearMissAuthorize.push(...collectAuthorizeNearMisses([
+    nearMissAuthorize.push(...collectAuthorizeNearMissesAllRoutes([
       ...ownLevelNotes(struct.annotations),
       ...struct.fields.flatMap((field) => ownLevelNotes(field.annotations))
     ].map((note) => note.text)));
@@ -274539,23 +274813,29 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
         considerNoteOwner(authorizeNoteDeclaredBy, note, entry);
       }
     }
-    nearMissAuthorize.push(...collectAuthorizeNearMisses(ownLevelNotes(entry.annotations).map((note) => note.text)));
+    nearMissAuthorize.push(...collectAuthorizeNearMissesAllRoutes(ownLevelNotes(entry.annotations).map((note) => note.text)));
   }
   for (const struct of derivedStructsReachable(sweptStructs, modelDef)) {
-    nearMissAuthorize.push(...collectAuthorizeNearMisses([
+    nearMissAuthorize.push(...collectAuthorizeNearMissesAllRoutes([
       ...ownLevelNotes(struct.annotations),
       ...struct.fields.flatMap((field) => ownLevelNotes(field.annotations))
     ].map((note) => note.text)));
   }
   {
     const folded = modelAnnotations(modelDef);
-    nearMissAuthorize.push(...collectAuthorizeNearMisses([...folded.notes ?? [], ...folded.blockNotes ?? []].map((note) => note.text)));
+    nearMissAuthorize.push(...collectAuthorizeNearMissesAllRoutes([...folded.notes ?? [], ...folded.blockNotes ?? []].map((note) => note.text)));
   }
   assertNoAuthorizeNearMisses(nearMissAuthorize);
   const authorizeOwnNotes = new Map;
   const attributedAuthorizeOwnNotes = new Map;
-  if (containsAuthorizeAnnotationTag((modelAnnotations(modelDef).notes ?? []).map((note) => note.text))) {
-    misplacedAuthorize.push({ kind: "file" });
+  {
+    const fileNoteTexts = ownLevelNoteTexts(modelAnnotations(modelDef));
+    if (containsAuthorizeAnnotationTag(fileNoteTexts)) {
+      misplacedAuthorize.push({
+        kind: "file",
+        route: fileNoteTexts.map((text) => authorizeAnnotationRoute(text)).find((r) => r !== undefined) ?? ACCESS_FILTER_ROUTE
+      });
+    }
   }
   const sources = Object.values(modelDef.contents).filter((obj) => isSourceDef6(obj)).map((sourceObj) => {
     const struct = sourceObj;
@@ -274594,17 +274874,32 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
       }
     }
     const ownNotes = ownLevelNoteTexts(struct.annotations);
-    const ownGates = collectAuthorizeExprs(ownNotes);
     const ownAuthorizeNotes = ownLevelNotes(struct.annotations).filter((note) => containsAuthorizeAnnotationTag([note.text]));
-    authorizeOwnNotes.set(sourceName, ownAuthorizeNotes);
-    attributedAuthorizeOwnNotes.set(sourceName, ownAuthorizeNotes.filter((note) => authorizeNoteDeclaredBy.get(note) === struct));
-    const inheritedGroups = ownGates.length === 0 ? effectiveAncestorGateExprs(struct, modelDef) : [];
-    const effectiveGroups = ownGates.length > 0 ? [ownGates] : inheritedGroups;
-    let authorize;
-    if (effectiveGroups.length > 0) {
-      authorizeMap.set(sourceName, effectiveGroups);
-      authorize = effectiveGroups.flat();
-    }
+    const ownNotesByRoute = new Map;
+    const attributedOwnNotesByRoute = new Map;
+    for (const route of CANONICAL_AUTHORIZE_ROUTES) {
+      const notesForRoute = ownAuthorizeNotes.filter((note) => authorizeAnnotationRoute(note.text) === route);
+      ownNotesByRoute.set(route, notesForRoute);
+      attributedOwnNotesByRoute.set(route, notesForRoute.filter((note) => authorizeNoteDeclaredBy.get(note) === struct));
+    }
+    authorizeOwnNotes.set(sourceName, ownNotesByRoute);
+    attributedAuthorizeOwnNotes.set(sourceName, attributedOwnNotesByRoute);
+    const groupsForSource = [];
+    const routeGroupsByRoute = new Map;
+    for (const route of CANONICAL_AUTHORIZE_ROUTES) {
+      const ownExprsForRoute = collectAuthorizeExprsForRoute(ownNotes, route);
+      const groupsForRoute = ownExprsForRoute.length > 0 ? [ownExprsForRoute] : effectiveAncestorGateExprs(struct, modelDef, route);
+      for (const exprs of groupsForRoute) {
+        groupsForSource.push({ route, exprs });
+      }
+      routeGroupsByRoute.set(route, groupsForRoute);
+    }
+    if (groupsForSource.length > 0) {
+      authorizeMap.set(sourceName, groupsForSource);
+    }
+    const routeGroupsToFlatWire = (groups) => groups && groups.length > 0 ? groups.flat() : undefined;
+    const authorize = routeGroupsToFlatWire(routeGroupsByRoute.get(AUTHORIZE_ROUTE));
+    const accessFilter = routeGroupsToFlatWire(routeGroupsByRoute.get(ACCESS_FILTER_ROUTE));
     const views = struct.fields.filter((field) => field.type === "turtle").filter((turtle) => turtle.pipeline.map((stage) => stage.type).every((type) => type === "reduce")).map((turtle) => ({
       name: turtle.as || turtle.name,
       annotations: annotationTexts(turtle.annotations)
@@ -274617,7 +274912,7 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
         continue;
       }
       const fieldName2 = field.as || field.name;
-      if (isJoined3(field) && isSourceDef6(field)) {
+      if (isJoined4(field) && isSourceDef6(field)) {
         const joinedStruct = field;
         if (joinFieldNamesUnresolvableDeclaration(joinedStruct, modelDef)) {
           continue;
@@ -274625,14 +274920,16 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
         misplacedAuthorize.push({
           kind: "field",
           name: sourceName,
-          fieldName: fieldName2
+          fieldName: fieldName2,
+          route: fieldAuthorizeNotes.map((note) => authorizeAnnotationRoute(note.text)).find((r) => r !== undefined) ?? ACCESS_FILTER_ROUTE
         });
         continue;
       }
       misplacedAuthorize.push({
         kind: "field",
         name: sourceName,
-        fieldName: fieldName2
+        fieldName: fieldName2,
+        route: fieldAuthorizeNotes.map((note) => authorizeAnnotationRoute(note.text)).find((r) => r !== undefined) ?? ACCESS_FILTER_ROUTE
       });
     }
     return {
@@ -274641,7 +274938,8 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
       views,
       filters,
       givens,
-      authorize
+      authorize,
+      accessFilter
     };
   });
   return {
@@ -274658,7 +274956,8 @@ function extractQueriesFromModelDef(modelDef) {
   const namedQueries = Object.values(modelDef.contents).filter(isNamedQuery);
   const misplacedAuthorize = namedQueries.filter((queryObj) => containsAuthorizeAnnotationTag(ownLevelNoteTexts(queryObj.annotations))).map((queryObj) => ({
     kind: "query",
-    name: queryObj.as || queryObj.name
+    name: queryObj.as || queryObj.name,
+    route: ownLevelNoteTexts(queryObj.annotations).map((text) => authorizeAnnotationRoute(text)).find((r) => r !== undefined) ?? ACCESS_FILTER_ROUTE
   }));
   const queries = namedQueries.map((queryObj) => ({
     name: queryObj.as || queryObj.name,
@@ -274670,10 +274969,113 @@ function extractQueriesFromModelDef(modelDef) {
 var init_source_extraction = __esm(() => {
   init_annotations();
   init_authorize();
+  init_authorize_routes();
   init_filter();
   init_gate_registry_walk();
 });
 
+// src/service/authorize_lock.ts
+function decideLock(conditionExpr, givenNameOf, givens) {
+  const ctx = { givenNameOf, givens, unresolvable: false };
+  try {
+    if (admits(conditionExpr, ctx, 0))
+      return "admit";
+  } catch {
+    ctx.unresolvable = true;
+  }
+  return ctx.unresolvable ? "unresolvable" : "deny";
+}
+function admits(node, ctx, depth) {
+  if (depth > 64 || node === null || typeof node !== "object") {
+    ctx.unresolvable = true;
+    return false;
+  }
+  const n = node;
+  switch (n.node) {
+    case "()":
+      return admits(n.e, ctx, depth + 1);
+    case "true":
+      return true;
+    case "false":
+      return false;
+    case "and": {
+      const left = admits(n.kids?.left, ctx, depth + 1);
+      const right = admits(n.kids?.right, ctx, depth + 1);
+      return left && right;
+    }
+    case "=": {
+      const { left, right } = n.kids ?? {};
+      const pair = givenAndLiteral(left, right) ?? givenAndLiteral(right, left);
+      if (!pair) {
+        ctx.unresolvable = true;
+        return false;
+      }
+      const value = resolve4(pair.given, ctx);
+      if (typeof value !== "string") {
+        ctx.unresolvable = true;
+        return false;
+      }
+      return value === pair.literal;
+    }
+    case "inGiven": {
+      if (n.not === true)
+        return false;
+      const given = asGiven(n.givenRef);
+      const literal = asStringLiteral(n.e);
+      if (!given || literal === undefined) {
+        ctx.unresolvable = true;
+        return false;
+      }
+      const value = resolve4(given, ctx);
+      if (!Array.isArray(value)) {
+        ctx.unresolvable = true;
+        return false;
+      }
+      return value.some((item) => item === literal);
+    }
+    default:
+      ctx.unresolvable = true;
+      return false;
+  }
+}
+function givenAndLiteral(a, b) {
+  const given = asGiven(a);
+  const literal = asStringLiteral(b);
+  if (!given || literal === undefined)
+    return;
+  return { given, literal };
+}
+function asGiven(node) {
+  if (node === null || typeof node !== "object")
+    return;
+  const n = node;
+  return n.node === "given" ? n : undefined;
+}
+function asStringLiteral(node) {
+  if (node === null || typeof node !== "object")
+    return;
+  const n = node;
+  if (n.node !== "stringLiteral")
+    return;
+  return typeof n.literal === "string" ? n.literal : undefined;
+}
+function resolve4(given, ctx) {
+  if (typeof given.id !== "string") {
+    ctx.unresolvable = true;
+    return;
+  }
+  const name = ctx.givenNameOf(given.id);
+  if (name === undefined) {
+    ctx.unresolvable = true;
+    return;
+  }
+  if (!Object.prototype.hasOwnProperty.call(ctx.givens, name)) {
+    ctx.unresolvable = true;
+    return;
+  }
+  return ctx.givens[name];
+}
+
 // src/service/model.ts
 import {
   API,
@@ -274695,6 +275097,22 @@ import { readFileSync as readFileSync2 } from "fs";
 import { createRequire as createRequire2 } from "module";
 import * as path10 from "path";
 import { fileURLToPath as fileURLToPath6 } from "url";
+function denyUnlessAdmitted(resolution, givens, label) {
+  if (resolution.shape === "lock") {
+    const outcome = decideLock(resolution.condition.e, (id) => resolution.givenNamesById.get(id), givens);
+    if (outcome === "admit") {
+      recordLockDecision("admitted");
+      return;
+    }
+    recordLockDecision(outcome === "unresolvable" ? "denied_unresolvable" : "denied_by_lock");
+    throw new AccessDeniedError(`Access denied for source "${label}".`);
+  }
+  recordLockDecision("denied_unresolvable");
+  recordRowLevelGateDecision("denied_by_gate");
+  if (resolution.cause)
+    recordRowLevelGateRejected(resolution.cause);
+  throw new AccessDeniedError(`Access denied for source "${label}".`);
+}
 function quoteMalloyIdentifier2(name) {
   return "`" + (name ?? "").replace(/\\/g, "\\\\").replace(/`/g, "\\`") + "`";
 }
@@ -274782,6 +275200,7 @@ var init_model = __esm(() => {
   init_annotations();
   init_build_plan();
   init_authorize();
+  init_authorize_routes();
   init_dashboard();
   init_gate_dimension();
   init_filter();
@@ -274793,7 +275212,6 @@ var init_model = __esm(() => {
   init_query_metadata();
   init_preaggregation_validation();
   init_gate_registry_walk();
-  init_partition_annotation();
   init_gate_classification();
   init_source_extraction();
   init_authorize_metrics();
@@ -274867,9 +275285,17 @@ var init_model = __esm(() => {
       for (const source of this.sources ?? []) {
         if (!source.name)
           continue;
-        const exprs = this.entryPointGatesBySource.get(source.name)?.flatMap((g) => g.exprs);
-        if (exprs && exprs.length > 0)
-          source.authorize = exprs;
+        const gates = this.entryPointGatesBySource.get(source.name);
+        const exprsForRoute = (route) => {
+          const exprs = gates?.filter((g) => g.route === route).flatMap((g) => g.exprs);
+          return exprs && exprs.length > 0 ? exprs : undefined;
+        };
+        const lockExprs = exprsForRoute(AUTHORIZE_ROUTE);
+        if (lockExprs)
+          source.authorize = lockExprs;
+        const filterExprs = exprsForRoute(ACCESS_FILTER_ROUTE);
+        if (filterExprs)
+          source.accessFilter = filterExprs;
       }
       try {
         this.authorizeReferencedGivenNames = this.computeAuthorizeReferencedGivenNames();
@@ -274940,6 +275366,9 @@ var init_model = __esm(() => {
     getAuthorize(sourceName) {
       return this.sources?.find((source) => source.name === sourceName)?.authorize ?? [];
     }
+    getAccessFilter(sourceName) {
+      return this.sources?.find((source) => source.name === sourceName)?.accessFilter ?? [];
+    }
     filterGivensToModelSurface(givens) {
       if (!givens)
         return givens;
@@ -275025,28 +275454,7 @@ var init_model = __esm(() => {
       structs.push(...derivedStructsReachable(structs, modelDef));
       return structs;
     }
-    anyPartitionNote;
-    hasAnyPartitionNote() {
-      if (this.anyPartitionNote !== undefined)
-        return this.anyPartitionNote;
-      this.anyPartitionNote = (() => {
-        const modelDef = this.modelDef;
-        if (!modelDef)
-          return false;
-        try {
-          for (const struct of this.reachableStructsForNoteSweep(modelDef)) {
-            if (containsPartitionAnnotationTag(annotationTexts(struct.annotations) ?? [])) {
-              return true;
-            }
-          }
-          return false;
-        } catch {
-          return true;
-        }
-      })();
-      return this.anyPartitionNote;
-    }
-    async assertAuthorized(sourceName, _givens, bypassAuthorize = false, graftScope = this.defaultGraftScope()) {
+    async assertAuthorized(sourceName, givens, bypassAuthorize = false, graftScope = this.defaultGraftScope()) {
       if (bypassAuthorize) {
         this.noteAuthorizeBypass("source", sourceName);
         return;
@@ -275057,10 +275465,7 @@ var init_model = __esm(() => {
           const resolution = this.modelDef ? await this.resolveGateShape(entry, this.modelDef, graftScope) : { shape: "rejected", cause: undefined };
           if (resolution.shape === "row_level")
             continue;
-          recordRowLevelGateDecision("denied_by_gate");
-          if (resolution.cause)
-            recordRowLevelGateRejected(resolution.cause);
-          throw new AccessDeniedError(`Access denied for source "${entry.label}".`);
+          denyUnlessAdmitted(resolution, givens, entry.label);
         }
         return;
       }
@@ -275095,7 +275500,7 @@ var init_model = __esm(() => {
         const onDiskGates = this.entryPointGatesBySource.get(ownSourceName);
         if (onDiskGates) {
           const SEP = "\x1F";
-          const keyOf = (entry) => `${entry.label}${SEP}${entry.exprs.join(SEP)}${SEP}${entry.selfContained}`;
+          const keyOf = (entry) => `${entry.label}${SEP}${entry.route}${SEP}${entry.exprs.join(SEP)}${SEP}${entry.selfContained}`;
           const byKey = new Map(entryPointGates.map((entry) => [keyOf(entry), entry]));
           for (const entry of onDiskGates) {
             byKey.set(keyOf(entry), entry);
@@ -275115,7 +275520,7 @@ var init_model = __esm(() => {
       return this.rowLevelFilteredRunnables.has(runnable);
     }
     async probeEntryPointGates(runnable, givens, graftScope, skipOwnSourceGate = false) {
-      const { entryPointGates, modelDef, struct } = await this.collectAuthorizeEntryPointGates(runnable, givens, graftScope, skipOwnSourceGate);
+      const { entryPointGates, modelDef } = await this.collectAuthorizeEntryPointGates(runnable, givens, graftScope, skipOwnSourceGate);
       const rowLevel = [];
       for (const entry of entryPointGates) {
         const resolution = modelDef ? await this.resolveGateShape(entry, modelDef, graftScope) : { shape: "rejected", cause: undefined };
@@ -275129,20 +275534,7 @@ var init_model = __esm(() => {
           });
           continue;
         }
-        recordRowLevelGateDecision("denied_by_gate");
-        if (resolution.cause)
-          recordRowLevelGateRejected(resolution.cause);
-        throw new AccessDeniedError(`Access denied for source "${entry.label}".`);
-      }
-      try {
-        rowLevel.push(...await resolvePartitionGraftEntries(struct, modelDef, graftScope, this.gateClassificationDeps()));
-      } catch (err) {
-        recordRowLevelGateDecision("denied_by_gate");
-        logger.debug("Partition filter could not be resolved; denying", {
-          modelPath: this.modelPath,
-          error: err instanceof Error ? err.message : String(err)
-        });
-        throw new AccessDeniedError(`Access denied for source "${struct?.as ?? struct?.name ?? "unknown"}".`);
+        denyUnlessAdmitted(resolution, givens, entry.label);
       }
       return rowLevel;
     }
@@ -275156,12 +275548,12 @@ var init_model = __esm(() => {
         if (compositeResolvedSourceDef) {
           gates.push(...this.collectEntryPointGates(compositeResolvedSourceDef, modelDef, seen, true, undefined, struct ? ownLevelNotes(struct.annotations) : []));
         }
-        return gates.length > 0 || resolveEntryPointPartitions(struct, modelDef).length > 0;
+        return gates.length > 0;
       } catch {
         return true;
       }
     }
-    async assertRequestDeclaredEntryPointIsNotLaundered(runnable, query) {
+    async assertRequestDeclaredEntryPointIsNotLaundered(runnable, query, givens, graftScope) {
       if (!this.declaresAnyGate())
         return;
       const entryPoint = await this.resolveAuthorizeSourceFromRunnable(runnable);
@@ -275170,15 +275562,51 @@ var init_model = __esm(() => {
       if (this.entryPointGatesBySource.has(entryPoint))
         return;
       const proof = this.requestChainProvesUngated(entryPoint, buildDerivationBaseMap(stripMalloyCommentsAndLiterals(query)));
-      if (proof.proven)
+      if (proof.proven) {
+        for (const base of proof.gatedBases) {
+          for (const entry of this.entryPointGatesBySource.get(base) ?? []) {
+            const resolution = this.modelDef ? await this.resolveGateShape(entry, this.modelDef, graftScope) : { shape: "rejected", cause: undefined };
+            if (resolution.shape === "row_level") {
+              this.denyLaunderedEntryPoint(entryPoint, "row_filter_not_graftable", base);
+            }
+            denyUnlessAdmitted(resolution, givens, entryPoint);
+          }
+        }
         return;
+      }
+      this.denyLaunderedEntryPoint(entryPoint, proof.reason, proof.at);
+    }
+    async assertLocksOnRequestDeclaredBases(entryPoint, query, givens, bypassAuthorize) {
+      if (!this.declaresAnyGate())
+        return;
+      const basesOf = buildDerivationBaseMap(stripMalloyCommentsAndLiterals(query));
+      const seen = new Set;
+      const worklist = entryPoint ? [entryPoint] : [...basesOf.keys()];
+      for (let i = 0;i < worklist.length; i++) {
+        const name = worklist[i];
+        if (seen.has(name))
+          continue;
+        seen.add(name);
+        if (seen.size > REQUEST_CHAIN_MAX_NAMES)
+          return;
+        if (this.entryPointGatesBySource.has(name)) {
+          try {
+            await this.assertAuthorized(name, givens, bypassAuthorize);
+          } catch (error) {
+            if (error instanceof AccessDeniedError) {
+              this.assertQueryBoundaryEarly(name, undefined, undefined);
+            }
+            throw error;
+          }
+          continue;
+        }
+        for (const base of basesOf.get(name) ?? [])
+          worklist.push(base);
+      }
+    }
+    denyLaunderedEntryPoint(entryPoint, reason, at) {
       recordRowLevelGateDecision("denied_by_gate");
-      logger.debug("Request-declared entry point in a gated model is not provably ungated; denying", {
-        modelPath: this.modelPath,
-        entryPoint,
-        reason: proof.reason,
-        at: proof.at
-      });
+      logger.debug("Request-declared entry point in a gated model is not provably ungated; denying", { modelPath: this.modelPath, entryPoint, reason, at });
       throw new AccessDeniedError(`Access denied for source "${entryPoint}".`);
     }
     declaresAnyGateMemo;
@@ -275188,6 +275616,7 @@ var init_model = __esm(() => {
     }
     requestChainProvesUngated(entryPoint, basesOf) {
       const seen = new Set;
+      const gatedBases = [];
       const worklist = [entryPoint];
       for (let i = 0;i < worklist.length; i++) {
         const name = worklist[i];
@@ -275199,13 +275628,8 @@ var init_model = __esm(() => {
         }
         const modelGates = this.entryPointGatesBySource.get(name);
         if (modelGates !== undefined) {
-          if (modelGates.length > 0) {
-            return {
-              proven: false,
-              reason: "reaches_gated_source",
-              at: name
-            };
-          }
+          if (modelGates.length > 0)
+            gatedBases.push(name);
           continue;
         }
         const bases = basesOf.get(name);
@@ -275215,7 +275639,7 @@ var init_model = __esm(() => {
         for (const base of bases)
           worklist.push(base);
       }
-      return { proven: true };
+      return { proven: true, gatedBases };
     }
     async authorizeAndBindRunnable(runnable, givens, options) {
       if (options?.bypassAuthorize) {
@@ -275226,7 +275650,7 @@ var init_model = __esm(() => {
       const rowLevel = await this.probeEntryPointGates(runnable, givens, graftScope, options?.skipOwnSourceGate ?? false);
       if (rowLevel.length === 0) {
         if (options?.callerQueryText && !options?.skipOwnSourceGate) {
-          await this.assertRequestDeclaredEntryPointIsNotLaundered(runnable, options.callerQueryText);
+          await this.assertRequestDeclaredEntryPointIsNotLaundered(runnable, options.callerQueryText, givens, graftScope);
         }
         return runnable;
       }
@@ -275291,7 +275715,7 @@ var init_model = __esm(() => {
     }
     async resolveGateShape(entry, originModelDef, graftScope) {
       const result = await resolveGateShape(entry, originModelDef, graftScope, this.gateClassificationDeps());
-      if (result.shape === "row_level") {
+      if (result.shape !== "rejected") {
         for (const name of result.givenNames) {
           this.authorizeReferencedGivenNames.add(name);
         }
@@ -275432,7 +275856,11 @@ var init_model = __esm(() => {
       return false;
     }
     async assertAuthorizedForText(text, givens) {
-      await this.assertAuthorized(extractRunTargetSourceName(text), givens);
+      const target = extractRunTargetSourceName(text);
+      await this.assertAuthorized(target, givens);
+      if (!hasCallerAuthorizeAnnotation(text)) {
+        await this.assertLocksOnRequestDeclaredBases(target ?? "", text, givens);
+      }
     }
     async assertAuthorizedForRunnable(runnable, givens) {
       await this.assertAuthorizedForAllSources(runnable, givens, false, {
@@ -275490,7 +275918,7 @@ var init_model = __esm(() => {
           filterMap = sourceResult.filterMap;
           const queryResult = Model.getQueries(modelDef);
           queries = queryResult.queries;
-          assertPartitionAnnotationsValid(modelDef);
+          assertNoRetiredRouteMarkers(collectRetiredRouteMarkers(modelDef));
           assertNoMisplacedAuthorizeAnnotations([
             ...sourceResult.misplacedAuthorize,
             ...queryResult.misplacedAuthorize
@@ -275498,20 +275926,20 @@ var init_model = __esm(() => {
           const legacyStringGates = findLegacyStringGates(sourceResult.authorizeOwnNotes);
           legacyStringGates.forEach(() => recordRowLevelGateRejected("legacy_string_gate"));
           assertNoLegacyStringGate(legacyStringGates);
-          assertAtMostOneAuthorizeGate(findMultipleAuthorizeGates(sourceResult.authorizeOwnNotes));
+          assertAuthorizeGrammarValid(modelDef, sourceResult.authorizeMap, sourceResult.authorizeOwnNotes, computeGivenDeclaredTypes(givens), (_sourceName, route) => recordAuthorizeAdmitAllGate(route), sourceResult.attributedAuthorizeOwnNotes);
           const compiledModelDef = modelDef;
           await validateAuthorizeProbes(modelMaterializer, {
             authorizeMap: sourceResult.authorizeMap,
             authorizeOwnNotes: sourceResult.attributedAuthorizeOwnNotes,
             onRowLevelGateRejected: recordRowLevelGateRejected,
-            onRowLevelGateUnexpressible: (sourceName, detail) => logger.warn("Row-level #(authorize) gate not expressible at this entry point; every query against it will be denied", { packageName, modelPath, sourceName, detail }),
-            onOwnRowLevelConditionCompiled: (sourceName, condition) => {
+            onRowLevelGateUnexpressible: (sourceName, detail) => logger.warn("Row-level #(access_filter) gate not expressible at this entry point; every query against it will be denied", { packageName, modelPath, sourceName, detail }),
+            onOwnRowLevelConditionCompiled: (sourceName, condition, route) => {
               const struct = compiledModelDef.contents[sourceName];
               if (!struct || !isSourceDef7(struct))
                 return;
-              validateSourceLineGateGivenUsage(sourceName, struct, condition.refSummary, condition.e, compiledModelDef, (cause, detail) => {
+              validateSourceLineGateGivenUsage(sourceName, route, struct, condition.refSummary, condition.e, compiledModelDef, (cause, detail) => {
                 recordRowLevelGateRejected(cause);
-                logger.warn("Row-level #(authorize) gate warning", {
+                logger.warn(`#(${route}) gate warning`, {
                   packageName,
                   modelPath,
                   sourceName,
@@ -275647,7 +276075,12 @@ var init_model = __esm(() => {
     getDashboardModelFacts() {
       if (!this.modelDef)
         return;
-      return readDashboardModelFacts(this.modelPath, this.modelDef, (this.givens ?? []).map((given) => given.name).filter((name) => name !== undefined), new Map((this.sources ?? []).flatMap((source) => source.name ? [[source.name, source.authorize ?? []]] : [])));
+      return readDashboardModelFacts(this.modelPath, this.modelDef, (this.givens ?? []).map((given) => given.name).filter((name) => name !== undefined), new Map((this.sources ?? []).flatMap((source) => source.name ? [
+        [
+          source.name,
+          gateGivenSource(this.sources ?? [], source.name) ?? []
+        ]
+      ] : [])));
     }
     hasEmptyDiscoverySurface() {
       if (!this.discoveryCurationEnabled)
@@ -275682,17 +276115,15 @@ var init_model = __esm(() => {
       return this.admittedByPackage(name, this.queryBoundary.packageCuratedSources);
     }
     isCuratedQuery(name) {
-      if ((this.getQueries() ?? []).some((q) => q.name === name))
+      if (!this.isNotebook() && (this.getQueries() ?? []).some((q) => q.name === name))
         return true;
       return this.admittedByPackage(name, this.queryBoundary.packageCuratedQueries);
     }
     assertQueryBoundaryEarly(sourceName, queryName, query) {
-      if (this.modelPath.endsWith(NOTEBOOK_FILE_SUFFIX))
-        return "cleared";
       const { mode, exploresDeclared, isQueryEntryPoint } = this.queryBoundary;
       if (mode === "all" || !exploresDeclared)
         return "cleared";
-      if (!isQueryEntryPoint) {
+      if (!isQueryEntryPoint && !this.isNotebook()) {
         throw new NotQueryableError(`No queryable model "${this.modelPath}".`);
       }
       if (queryName && !query) {
@@ -275710,18 +276141,16 @@ var init_model = __esm(() => {
       if (query) {
         const target = extractRunTargetSourceName(query);
         if (target && !this.isCuratedSource(target) && !this.derivesFromCurated(target, query) && this.sources?.some((s) => s.name === target)) {
-          throw new NotQueryableError(`No queryable source "${target}".`);
+          throw new NotQueryableError("Query target is not queryable.");
         }
       }
       return "deferred";
     }
     assertQueryBoundaryCompiled(compiledSource, query) {
-      if (this.modelPath.endsWith(NOTEBOOK_FILE_SUFFIX))
-        return;
       const { mode, exploresDeclared, isQueryEntryPoint } = this.queryBoundary;
       if (mode === "all" || !exploresDeclared)
         return;
-      if (!isQueryEntryPoint) {
+      if (!isQueryEntryPoint && !this.isNotebook()) {
         throw new NotQueryableError(`No queryable model "${this.modelPath}".`);
       }
       if (compiledSource) {
@@ -275738,7 +276167,12 @@ var init_model = __esm(() => {
         return;
       this.assertQueryBoundaryCompiled(await this.resolveAuthorizeSourceFromRunnable(runnable), query);
     }
+    isNotebook() {
+      return this.modelPath.endsWith(NOTEBOOK_FILE_SUFFIX);
+    }
     ownCuratedSourceNames() {
+      if (this.isNotebook())
+        return new Set;
       return new Set((this.getSources() ?? []).map((s) => s.name).filter((n) => n !== undefined));
     }
     derivesFromCurated(name, query) {
@@ -276127,6 +276561,9 @@ var init_model = __esm(() => {
       const earlySource = sourceName || (queryName ? this.queries?.find((q) => q.name === queryName)?.sourceName : undefined) || (surfaceName && !this.sources?.some((s) => s.name === surfaceName) ? this.queries?.find((q) => q.name === surfaceName)?.sourceName : undefined) || surfaceName;
       if (earlySource) {
         await this.assertAuthorized(earlySource, givens ?? {}, bypassAuthorize);
+        if (query && !hasCallerAuthorizeAnnotation(query) && !this.entryPointGatesBySource.has(earlySource)) {
+          await this.assertLocksOnRequestDeclaredBases(earlySource, query, givens ?? {}, bypassAuthorize);
+        }
       }
       try {
         for (const [field, callerText] of [
@@ -276175,7 +276612,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         liveRunnable = runnable;
         const storageRoutingPossible = getPersistStorageMode() === "on" && this.serveBindings.length > 0 && !!this.serveDestinationConfig;
         const preaggServeMaterializer = this.preaggregateServeMaterializer;
-        const routingBlockedByRowLevelGate = (storageRoutingPossible || !!preaggServeMaterializer) && !bypassAuthorize && (this.hasAnyAuthorizeNote() || this.hasAnyPartitionNote()) && await this.queryEntryPointHasRowLevelGate(runnable);
+        const routingBlockedByRowLevelGate = (storageRoutingPossible || !!preaggServeMaterializer) && !bypassAuthorize && this.hasAnyAuthorizeNote() && await this.queryEntryPointHasRowLevelGate(runnable);
         if (routingBlockedByRowLevelGate) {
           recordStorageServeRouting("blocked_by_row_level_gate");
         }
@@ -277659,12 +278096,12 @@ var require_recursive_readdir = __commonJS((exports, module) => {
       ignores = [];
     }
     if (!callback) {
-      return new Promise(function(resolve4, reject2) {
+      return new Promise(function(resolve5, reject2) {
         readdir3(path11, ignores || [], function(err, data) {
           if (err) {
             reject2(err);
           } else {
-            resolve4(data);
+            resolve5(data);
           }
         });
       });
@@ -284918,7 +285355,7 @@ var require_uri_all = __commonJS((exports, module) => {
       target.fragment = relative5.fragment;
       return target;
     }
-    function resolve5(baseURI, relativeURI, options) {
+    function resolve6(baseURI, relativeURI, options) {
       var schemelessOptions = assign({ scheme: "null" }, options);
       return serialize(resolveComponents(parse(baseURI, schemelessOptions), parse(relativeURI, schemelessOptions), schemelessOptions, true), schemelessOptions);
     }
@@ -285186,7 +285623,7 @@ var require_uri_all = __commonJS((exports, module) => {
     exports2.removeDotSegments = removeDotSegments;
     exports2.serialize = serialize;
     exports2.resolveComponents = resolveComponents;
-    exports2.resolve = resolve5;
+    exports2.resolve = resolve6;
     exports2.normalize = normalize2;
     exports2.equal = equal;
     exports2.escapeComponent = escapeComponent;
@@ -285552,20 +285989,20 @@ var require_resolve2 = __commonJS((exports, module) => {
   var util5 = require_util12();
   var SchemaObject = require_schema_obj();
   var traverse = require_json_schema_traverse();
-  module.exports = resolve5;
-  resolve5.normalizeId = normalizeId;
-  resolve5.fullPath = getFullPath;
-  resolve5.url = resolveUrl;
-  resolve5.ids = resolveIds;
-  resolve5.inlineRef = inlineRef;
-  resolve5.schema = resolveSchema;
-  function resolve5(compile, root, ref) {
+  module.exports = resolve6;
+  resolve6.normalizeId = normalizeId;
+  resolve6.fullPath = getFullPath;
+  resolve6.url = resolveUrl;
+  resolve6.ids = resolveIds;
+  resolve6.inlineRef = inlineRef;
+  resolve6.schema = resolveSchema;
+  function resolve6(compile, root, ref) {
     var refVal = this._refs[ref];
     if (typeof refVal == "string") {
       if (this._refs[refVal])
         refVal = this._refs[refVal];
       else
-        return resolve5.call(this, compile, root, refVal);
+        return resolve6.call(this, compile, root, refVal);
     }
     refVal = refVal || this._schemas[ref];
     if (refVal instanceof SchemaObject) {
@@ -285788,7 +286225,7 @@ var require_resolve2 = __commonJS((exports, module) => {
 
 // ../../node_modules/@modelcontextprotocol/sdk/node_modules/ajv/lib/compile/error_classes.js
 var require_error_classes = __commonJS((exports, module) => {
-  var resolve5 = require_resolve2();
+  var resolve6 = require_resolve2();
   module.exports = {
     Validation: errorSubclass(ValidationError),
     MissingRef: errorSubclass(MissingRefError)
@@ -285803,8 +286240,8 @@ var require_error_classes = __commonJS((exports, module) => {
   };
   function MissingRefError(baseId, ref, message) {
     this.message = message || MissingRefError.message(baseId, ref);
-    this.missingRef = resolve5.url(baseId, ref);
-    this.missingSchema = resolve5.normalizeId(resolve5.fullPath(this.missingRef));
+    this.missingRef = resolve6.url(baseId, ref);
+    this.missingSchema = resolve6.normalizeId(resolve6.fullPath(this.missingRef));
   }
   function errorSubclass(Subclass) {
     Subclass.prototype = Object.create(Error.prototype);
@@ -286346,7 +286783,7 @@ var require_validate4 = __commonJS((exports, module) => {
 
 // ../../node_modules/@modelcontextprotocol/sdk/node_modules/ajv/lib/compile/index.js
 var require_compile2 = __commonJS((exports, module) => {
-  var resolve5 = require_resolve2();
+  var resolve6 = require_resolve2();
   var util5 = require_util12();
   var errorClasses = require_error_classes();
   var stableStringify = require_fast_json_stable_stringify();
@@ -286406,7 +286843,7 @@ var require_compile2 = __commonJS((exports, module) => {
         RULES,
         validate: validateGenerator,
         util: util5,
-        resolve: resolve5,
+        resolve: resolve6,
         resolveRef,
         usePattern,
         useDefault,
@@ -286445,7 +286882,7 @@ var require_compile2 = __commonJS((exports, module) => {
       return validate;
     }
     function resolveRef(baseId2, ref, isRoot) {
-      ref = resolve5.url(baseId2, ref);
+      ref = resolve6.url(baseId2, ref);
       var refIndex = refs[ref];
       var _refVal, refCode;
       if (refIndex !== undefined) {
@@ -286462,11 +286899,11 @@ var require_compile2 = __commonJS((exports, module) => {
         }
       }
       refCode = addLocalRef(ref);
-      var v2 = resolve5.call(self2, localCompile, root, ref);
+      var v2 = resolve6.call(self2, localCompile, root, ref);
       if (v2 === undefined) {
         var localSchema = localRefs && localRefs[ref];
         if (localSchema) {
-          v2 = resolve5.inlineRef(localSchema, opts.inlineRefs) ? localSchema : compile.call(self2, localSchema, root, localRefs, baseId2);
+          v2 = resolve6.inlineRef(localSchema, opts.inlineRefs) ? localSchema : compile.call(self2, localSchema, root, localRefs, baseId2);
         }
       }
       if (v2 === undefined) {
@@ -289983,7 +290420,7 @@ var require_data2 = __commonJS((exports, module) => {
 // ../../node_modules/@modelcontextprotocol/sdk/node_modules/ajv/lib/ajv.js
 var require_ajv = __commonJS((exports, module) => {
   var compileSchema = require_compile2();
-  var resolve5 = require_resolve2();
+  var resolve6 = require_resolve2();
   var Cache = require_cache();
   var SchemaObject = require_schema_obj();
   var stableStringify = require_fast_json_stable_stringify();
@@ -290075,7 +290512,7 @@ var require_ajv = __commonJS((exports, module) => {
     var id = this._getId(schema);
     if (id !== undefined && typeof id != "string")
       throw new Error("schema id must be string");
-    key = resolve5.normalizeId(key || id);
+    key = resolve6.normalizeId(key || id);
     checkUnique(this, key);
     this._schemas[key] = this._addSchema(schema, _skipValidation, _meta, true);
     return this;
@@ -290121,7 +290558,7 @@ var require_ajv = __commonJS((exports, module) => {
     }
   }
   function _getSchemaFragment(self2, ref) {
-    var res = resolve5.schema.call(self2, { schema: {} }, ref);
+    var res = resolve6.schema.call(self2, { schema: {} }, ref);
     if (res) {
       var { schema, root, baseId } = res;
       var v = compileSchema.call(self2, schema, root, undefined, baseId);
@@ -290137,7 +290574,7 @@ var require_ajv = __commonJS((exports, module) => {
     }
   }
   function _getSchemaObj(self2, keyRef) {
-    keyRef = resolve5.normalizeId(keyRef);
+    keyRef = resolve6.normalizeId(keyRef);
     return self2._schemas[keyRef] || self2._refs[keyRef] || self2._fragments[keyRef];
   }
   function removeSchema(schemaKeyRef) {
@@ -290165,7 +290602,7 @@ var require_ajv = __commonJS((exports, module) => {
         this._cache.del(cacheKey);
         var id = this._getId(schemaKeyRef);
         if (id) {
-          id = resolve5.normalizeId(id);
+          id = resolve6.normalizeId(id);
           delete this._schemas[id];
           delete this._refs[id];
         }
@@ -290190,14 +290627,14 @@ var require_ajv = __commonJS((exports, module) => {
     if (cached2)
       return cached2;
     shouldAddSchema = shouldAddSchema || this._opts.addUsedSchema !== false;
-    var id = resolve5.normalizeId(this._getId(schema));
+    var id = resolve6.normalizeId(this._getId(schema));
     if (id && shouldAddSchema)
       checkUnique(this, id);
     var willValidate = this._opts.validateSchema !== false && !skipValidation;
     var recursiveMeta;
-    if (willValidate && !(recursiveMeta = id && id == resolve5.normalizeId(schema.$schema)))
+    if (willValidate && !(recursiveMeta = id && id == resolve6.normalizeId(schema.$schema)))
       this.validateSchema(schema, true);
-    var localRefs = resolve5.ids.call(this, schema);
+    var localRefs = resolve6.ids.call(this, schema);
     var schemaObj = new SchemaObject({
       id,
       schema,
@@ -299430,7 +299867,7 @@ function getMalloyErrorDetails(operation, modelIdentifier, error) {
       refined = true;
       const [, sourceName] = accessDeniedMatch;
       suggestions = [
-        `Suggestion: Access to source '${sourceName}' is restricted by an #(authorize) gate. Supply the givens its authorize expression requires (e.g. a role/region given) and retry. This is an authorization denial, not a syntax error.`
+        `Suggestion: Access to source '${sourceName}' is restricted by an authorize gate. Supply the givens its authorize expression requires (e.g. a role/region given) and retry. This is an authorization denial, not a syntax error.`
       ];
     } else if (viewNotFoundMatch) {
       refined = true;
@@ -300544,12 +300981,15 @@ var REASON_BY_UNAVAILABLE = {
   "too-many-entities": "too-many-entities",
   error: "provider-error"
 };
-function toSourceResults(results, sourceContext, environmentName, packageName, searchTexts = new Map, includeCode = false) {
+function toSourceResults(results, sourceContext, environmentName, packageName, searchTexts = new Map, includeCode = false, droppedSources = new Set) {
   const bySource = new Map;
   const cardFor = (name, modelPathFallback) => {
     if (!name)
       return;
     const key = sourceContextKey(modelPathFallback, name);
+    if (droppedSources.has(key)) {
+      return;
+    }
     let entry = bySource.get(key);
     if (!entry) {
       const ctx = sourceContext.get(key);
@@ -300564,6 +301004,7 @@ function toSourceResults(results, sourceContext, environmentName, packageName, s
           ...ctx?.oneLineSummary ? { one_line_summary: ctx.oneLineSummary } : {},
           ...ctx?.doc ? { docs: ctx.doc } : {},
           ...ctx?.givens ? { givens: ctx.givens } : {},
+          ...ctx?.accessFilter ? { accessFilter: ctx.accessFilter } : {},
           ...ctx?.authorize ? { authorize: ctx.authorize } : {},
           ...ctx?.filters ? { filter_params: ctx.filters } : {},
           joins: ctx?.joins ?? []
@@ -300684,7 +301125,7 @@ function projectEntity(e, environmentName, packageName) {
 }
 function finishRanked(args) {
   const windowed = windowBySource(args.rows, args.max);
-  const sources = toSourceResults(windowed.rows, args.sourceContext, args.environmentName, args.packageName, args.searchTexts, args.includeCode);
+  const sources = toSourceResults(windowed.rows, args.sourceContext, args.environmentName, args.packageName, args.searchTexts, args.includeCode, args.droppedSources);
   return {
     sources,
     totalSources: windowed.totalSources,
@@ -300931,10 +301372,15 @@ function collectJoinedFields(args) {
     });
   }
 }
+function isUnconditionalDenyAuthorize(apiSource) {
+  const isDeny = (expr) => expr.trim().toLowerCase() === "false";
+  return (apiSource.accessFilter ?? []).some(isDeny) || (apiSource.authorize ?? []).some(isDeny);
+}
 async function collectEntities(pkg) {
   const models = [...await pkg.listModels()].sort((a, b) => comparePaths(a.path ?? "", b.path ?? ""));
   const entities = [];
   const governance = new Map;
+  const droppedSources = new Set;
   const sourceTextFor = makeSourceTextReader(pkg);
   let n = 0;
   for (const apiModel of models) {
@@ -300948,10 +301394,18 @@ async function collectEntities(pkg) {
     const queries = model.getQueries() ?? [];
     const apiSources = model.getSources?.() ?? [];
     const modelDef = model.getModelDef?.();
+    for (const apiSource of apiSources) {
+      if (apiSource.name && isUnconditionalDenyAuthorize(apiSource)) {
+        droppedSources.add(sourceContextKey(modelPath, apiSource.name));
+      }
+    }
     for (const sourceInfo of sourceInfos) {
       const sourceName = sourceInfo.name;
-      const provenance = readFieldProvenance(modelDef, sourceName, sourceTextFor);
       const governanceKey = sourceContextKey(modelPath, sourceName);
+      if (droppedSources.has(governanceKey)) {
+        continue;
+      }
+      const provenance = readFieldProvenance(modelDef, sourceName, sourceTextFor);
       if (!governance.has(governanceKey)) {
         const apiSource = apiSources.find((c) => c.name === sourceName);
         if (apiSource) {
@@ -300964,6 +301418,10 @@ async function collectEntities(pkg) {
                 ...given.default !== undefined ? { default: given.default } : {}
               }
             ] : []),
+            accessFilter: (apiSource.accessFilter ?? []).map((expression) => ({
+              expression,
+              given_names: referencedGivenNames(expression)
+            })),
             authorize: (apiSource.authorize ?? []).map((expression) => ({
               expression,
               given_names: referencedGivenNames(expression)
@@ -301038,6 +301496,9 @@ async function collectEntities(pkg) {
         continue;
       if (!query.sourceName)
         continue;
+      if (droppedSources.has(sourceContextKey(modelPath, query.sourceName))) {
+        continue;
+      }
       entities.push({
         id: String(n++),
         kind: "query",
@@ -301057,7 +301518,7 @@ async function collectEntities(pkg) {
     seen.add(key);
     return true;
   });
-  return { entities: collapseAliases(deduped), governance };
+  return { entities: collapseAliases(deduped), governance, droppedSources };
 }
 function malloyType(field) {
   const kind = field.type?.kind;
@@ -301160,6 +301621,7 @@ function buildSourceContext(collected) {
       joins: [],
       ...summary ? { oneLineSummary: summary } : {},
       ...gates?.givens.length ? { givens: gates.givens } : {},
+      ...gates?.accessFilter.length ? { accessFilter: gates.accessFilter } : {},
       ...gates?.authorize.length ? { authorize: gates.authorize } : {},
       ...gates?.filters.length ? { filters: gates.filters } : {}
     });
@@ -301207,7 +301669,8 @@ async function getPackageIndex(environmentStore, environmentName, packageName) {
     byId,
     index,
     entityCount: entities.length,
-    sourceContext: buildSourceContext(collected)
+    sourceContext: buildSourceContext(collected),
+    droppedSources: collected.droppedSources
   };
   indexCache.set(pkg, built);
   logger.debug("[MCP Tool getContext] Built and cached entity index", {
@@ -301225,13 +301688,13 @@ var GET_CONTEXT_DESCRIPTION = `Retrieve the entities in a Malloy package most re
 - Read warnings and any error/stale field before trusting a number.
 - A source's joins list is complete: empty means it declares none, so write that relationship inline.
 - Read a source's doc before querying: it carries grain and population rules its fields do not.
-- authorize means gated: supply the givens it names or the query is denied.
+- accessFilter/authorize mean gated; a deny-all source never appears here.
 
 ## Parameters
 search_targets: one per concept, {target_type, search_text}; target_type is source|dimension|measure|view|join|dimensional_value, omitting search_text enumerates that type. scopes: {environment, package} + optional model_path, source, entity_name. limit caps sources (max 150, counted as cards). offset pages a listing. user_prompt: the question asked. include_code or a pinned entity_name returns code.
 
 ## Response
-sources[], best first; a source repeats once per model_path resolving it, query any. source_info: resource_id (environment/package/model_path/source) -> execute_query's environmentName/packageName/modelPath/sourceName; docs (… = truncated), one_line_summary, complete joins, givens, authorize (report-only), filter_params. entities[] nest under it: name, entity_type, description, data_type, relationship (fan-out), join_path, aliases, relevance, entity_id. A joined field's name IS its dotted path; use it verbatim.
+sources[], best first; a source repeats once per model_path resolving it, query any. source_info: resource_id (environment/package/model_path/source) -> execute_query's environmentName/packageName/modelPath/sourceName; docs (… = truncated), one_line_summary, complete joins, givens, accessFilter/authorize, filter_params. entities[] nest under it: name, entity_type, description, data_type, relationship (fan-out), join_path, aliases, relevance, entity_id. A joined field's name IS its dotted path; use it verbatim.
 ranking, returned of total_available sources, next_offset on a listing, warnings[].
 Semantic fills relevance: no sources = nothing cleared the floor; below_cutoff_count of total_entities rejected. "lexical" adds retrieval_reason; only "indexing" is worth a retry.
 
@@ -301266,7 +301729,7 @@ async function runContextQuery(request, environmentStore, extraWarnings = []) {
     });
     return contextError(buildMalloyUri({ environment: environmentName, package: packageName }, "get-context"), `${environmentName}/${packageName}`, error);
   }
-  const { byId, index, sourceContext } = pkgIndex;
+  const { byId, index, sourceContext, droppedSources } = pkgIndex;
   const uri = buildMalloyUri({ environment: environmentName, package: packageName }, "get-context");
   let staleNote;
   try {
@@ -301304,7 +301767,7 @@ async function runContextQuery(request, environmentStore, extraWarnings = []) {
     });
     const spendable = (rows) => sourceName ? rows.filter((e) => e.kind !== "source").length : rows.length;
     const cappable = spendable(inScope);
-    const sources2 = toSourceResults(capped.map((e) => projectEntity(e, environmentName, packageName)), sourceContext, environmentName, packageName, new Map, request.includeCode);
+    const sources2 = toSourceResults(capped.map((e) => projectEntity(e, environmentName, packageName)), sourceContext, environmentName, packageName, new Map, request.includeCode, droppedSources);
     const consumed = request.offset + sources2.length;
     const cardsInScope = sourceName ? new Set(inScope.map((e) => sourceContextKey(e.modelPath, e.source ?? ""))).size : inScope.length;
     const listingEnvelope = {
@@ -301420,7 +301883,8 @@ async function runContextQuery(request, environmentStore, extraWarnings = []) {
       environmentName,
       packageName,
       searchTexts: searchTextsByIndex,
-      includeCode: request.includeCode
+      includeCode: request.includeCode,
+      droppedSources
     });
     return jsonResource(uri, {
       sources: sources2,
@@ -301481,7 +301945,8 @@ async function runContextQuery(request, environmentStore, extraWarnings = []) {
     environmentName,
     packageName,
     searchTexts: searchTextsByIndex,
-    includeCode: request.includeCode
+    includeCode: request.includeCode,
+    droppedSources
   });
   const envelope = {
     sources,
@@ -301747,7 +302212,7 @@ class QueryController {
     const p = await environment.getPackage(packageName, false);
     const model = p.getModel(modelPath);
     if (!model) {
-      throw new ModelNotFoundError(`${modelPath} does not exist`);
+      throw new ModelNotFoundError(`No queryable model "${modelPath}".`);
     } else {
       const {
         result,
@@ -309865,6 +310330,23 @@ class Package {
     const explores = this.packageMetadata.explores;
     return !!(explores && explores.length > 0);
   }
+  surfaceWidenedWarning;
+  noteSurfaceChangeFrom(previousSurface) {
+    this.surfaceWidenedWarning = undefined;
+    if (!previousSurface || previousSurface.length === 0 || this.packageMetadata.explores !== undefined) {
+      return;
+    }
+    const message = `This package published "${previousSurface.join('", "')}" before the last ` + `reload and publishes no surface now, so every model in it is listed ` + `and queryable by name again, including the sources that surface was ` + `withholding. A surface file that was deleted or renamed is the usual ` + `cause. If that was intended, nothing to do. If not, restore the file ` + `(under its original name -- the name IS the surface), or declare an ` + `"explores" in publisher.json naming what this package should ` + `publish. To keep the package open deliberately, write ` + `"explores": [], which says so and stops this notice.`;
+    this.surfaceWidenedWarning = message;
+    logger.warn(`Package ${this.packageName} no longer publishes a surface`, {
+      packageName: this.packageName,
+      detail: message
+    });
+  }
+  surfaceIsIndexModel() {
+    const explores = this.packageMetadata.explores;
+    return this.models.has(INDEX_MODEL_NAME) && explores?.length === 1 && explores[0] === INDEX_MODEL_NAME;
+  }
   exploreSet() {
     const explores = this.packageMetadata.explores;
     return explores && explores.length > 0 ? new Set(explores) : null;
@@ -310204,6 +310686,8 @@ class Package {
       ...this.droppedPersistWarnings(),
       ...this.persistRefusalWarnings(),
       ...this.emptyDiscoveryWarnings(),
+      ...this.brokenSurfaceWarnings(),
+      ...this.surfaceWidenedWarning !== undefined ? [{ message: this.surfaceWidenedWarning }] : [],
       ...this.persistenceCollisionWarnings().map((message) => ({ message })),
       ...this.preaggregateAccessWarnings(),
       ...incrementalPolicyAdvisories(this.incrementalPolicySources),
@@ -310364,7 +310848,7 @@ class Package {
       if (entry.endsWith(NOTEBOOK_FILE_SUFFIX)) {
         problems.push({
           entry,
-          reason: `notebooks are always public and cannot be explores. ` + `Fix: remove it, and list a ${MODEL_FILE_SUFFIX} model file instead.`
+          reason: `notebooks are always listed and cannot be explores. ` + `Fix: remove it, and list a ${MODEL_FILE_SUFFIX} model file instead.`
         });
       } else if (!malloyModels.has(entry)) {
         problems.push({
@@ -310535,13 +311019,39 @@ class Package {
       if (model.hasEmptyDiscoverySurface()) {
         warnings.push({
           model: modelPath,
-          message: `Model "${modelPath}" is listed in explores but exposes ` + `nothing: its export closure surfaces no sources or named ` + `queries (typically an import-only file, or an export {} ` + `that filters everything out). Add e.g. ` + `'export { source_name }' to surface sources on this ` + `model, or remove it from explores.`
+          message: `Model "${modelPath}" is on this package's discovery ` + `surface but exposes nothing: its export closure surfaces ` + `no sources or named queries (typically an import-only ` + `file, or an export {} that filters everything out). Add ` + `e.g. 'export { source_name }' to surface sources on this ` + `model, or ` + (this.surfaceIsIndexModel() ? `delete the file AND any "explores" entry naming it. ` + `Deleting the file alone returns the package to ` + `listing every model only when no "explores" was ` + `written; where one was, it would be left naming a ` + `model that no longer exists and the package would ` + `list nothing.` : `remove it from explores.`)
         });
       }
     }
     return warnings;
   }
+  brokenSurfaceWarnings() {
+    const exploreSet = this.exploreSet();
+    if (!exploreSet || exploreSet.size === 0)
+      return [];
+    const surface = Array.from(this.models.entries()).filter(([modelPath]) => modelPath.endsWith(MODEL_FILE_SUFFIX) && exploreSet.has(modelPath));
+    if (surface.length === 0)
+      return [];
+    if (!surface.every(([, model]) => !!model.getCompilationError())) {
+      return [];
+    }
+    const collateral = Array.from(this.models.entries()).filter(([modelPath, model]) => modelPath.endsWith(MODEL_FILE_SUFFIX) && !exploreSet.has(modelPath) && !model.getCompilationError()).length;
+    const [firstPath] = surface[0];
+    const subject = surface.length === 1 ? `Model "${firstPath}" is this package's whole discovery surface ` + `and failed to compile` : `Every model on this package's discovery surface ` + `(${surface.map(([p]) => `"${p}"`).join(", ")}) failed to ` + `compile`;
+    return [
+      {
+        model: firstPath,
+        message: `${subject}, so the package exposes nothing: every model in ` + `it, including the ${collateral} that compiled, is now refused ` + `by name with a 404 that reads as "does not exist". Fix the ` + `compile error${surface.length === 1 ? "" : "s"} to restore ` + `them -- ` + surface.map(([modelPath, model]) => `${modelPath}: ` + `${model.getCompilationError()?.message ?? "unknown error"}`).join("; ")
+      }
+    ];
+  }
   logEmptyDiscoveryWarnings() {
+    for (const warning of this.brokenSurfaceWarnings()) {
+      logger.warn(`Package ${this.packageName} has a broken discovery surface`, {
+        packageName: this.packageName,
+        detail: warning.message
+      });
+    }
     for (const warning of this.emptyDiscoveryWarnings()) {
       logger.warn(`Package ${this.packageName} has a blank-looking model`, {
         packageName: this.packageName,
@@ -310659,7 +311169,9 @@ class Package {
     await this.pushPreaggregateServeModels();
     this.renderTagWarnings = renderTagWarnings;
     this.manifestWarnings = outcome.packageMetadata.manifestWarnings ?? [];
+    const previousSurface = this.packageMetadata.explores;
     this.packageMetadata.explores = outcome.packageMetadata.explores;
+    this.noteSurfaceChangeFrom(previousSurface);
     this.packageMetadata.queryableSources = outcome.packageMetadata.queryableSources;
     this.packageMetadata.manifestLocation = outcome.packageMetadata.manifestLocation ?? null;
     this.applyDiscoveryPolicyToModels();
@@ -310821,6 +311333,29 @@ class Package {
       });
     }
   }
+  lintTilesAgainstSurface(modelPath, manifest) {
+    const model = this.models.get(modelPath);
+    if (!model || !manifest.tiles)
+      return [];
+    const listedModel = (this.packageMetadata.explores ?? []).find((entry) => entry.endsWith(MODEL_FILE_SUFFIX) && !isDashboardModelPath(entry));
+    const importInto = listedModel ? `a listed file such as "${listedModel}"` : `a file you list there`;
+    const findings = [];
+    for (const tile of manifest.tiles) {
+      try {
+        model.assertQueryBoundaryEarly(undefined, undefined, `run: ${tile.query}`);
+      } catch (error) {
+        if (!(error instanceof NotQueryableError))
+          throw error;
+        findings.push({
+          model: modelPath,
+          subject: manifest.name,
+          message: `tile "${tile.query}" reads a source this package's surface ` + `does not publish, so the tile answers 404 once served, ` + `although the file compiles. Listing a file publishes what ` + `it declares, not what it imports. Fix: add the file that ` + `declares the source to 'explores', keeping the entries ` + `already there, or import it into ${importInto} and add ` + `it to that file's export { … }.`,
+          severity: "error"
+        });
+      }
+    }
+    return findings;
+  }
   async lintDashboards(factsByPath, allFacts, heldBack, unconventionalSlugs, knownSlugs, droppedByError) {
     const warnings = [];
     const withheldDrills = new Map;
@@ -310854,10 +311389,11 @@ class Package {
             });
           }
         }
+        const remedy = this.surfaceIsIndexModel() ? `This package's surface is "${INDEX_MODEL_NAME}", and a ` + `dashboard file cannot be exported from it -- dashboards are ` + `files, not sources. To serve this one, declare (or extend) ` + `an 'explores' in publisher.json listing both ` + `"${INDEX_MODEL_NAME}" and "${modelPath}"; an explicit key ` + `overrides the convention. Or set ` + `queryableSources: "all" to keep the curated surface for ` + `discovery only.` : `Add it to 'explores', or set queryableSources: "all" to ` + `keep the curated surface for discovery only.`;
         warnings.push({
           model: modelPath,
           subject: name,
-          message: `is a dashboard, but "${modelPath}" is not listed in ` + `'explores' and this package sets ` + `queryableSources: "declared", so its query would be ` + `refused. It is not served. Add it to 'explores', or set ` + `queryableSources: "all" to keep the curated surface for ` + `discovery only. Listing it is not always sufficient on its ` + `own: the queryable sources are the union of every listed ` + `file's export closure, so a tile reading a source that only ` + `an UNLISTED file exports is still refused. List that file ` + `too, or re-export the source from one already listed.`,
+          message: `is a dashboard, but "${modelPath}" is not part of this ` + `package's discovery surface and this package sets ` + `queryableSources: "declared", so its query would be ` + `refused. It is not served. ${remedy} Listing it is not ` + `always sufficient on its own: the queryable sources are ` + `the union of every listed file's export closure, so a tile ` + `reading a source that only an UNLISTED file exports is ` + `still refused. List that file too, or re-export the source ` + `from one already listed.`,
           severity: "warn"
         });
       }
@@ -310867,6 +311403,11 @@ class Package {
         for (const finding of findings) {
           warnings.push({ model: modelPath, ...finding });
         }
+        if (manifest) {
+          for (const finding of this.lintTilesAgainstSurface(modelPath, manifest)) {
+            warnings.push(finding);
+          }
+        }
       }
       const drillFacts = Array.from(allFacts.values());
       for (const finding of withheldDrills.values()) {
@@ -311741,6 +312282,7 @@ ${source}` : source ?? "";
       await this.rebindServeBindingsFromLocalStore(_package);
       if (existingPackage !== undefined && reload) {
         this.retireConnectionGeneration(`package ${packageName}`, () => existingPackage.getMalloyConfig().shutdown("close"));
+        _package.noteSurfaceChangeFrom(existingPackage.getPackageMetadata().explores);
       }
       this.packages.set(packageName, _package);
       this.setPackageStatus(packageName, "serving" /* SERVING */);
@@ -312044,11 +312586,12 @@ ${source}` : source ?? "";
       const materializationBase = metadata.materialization !== undefined ? { ...metadata.materialization, ...preservedQueryMetadata } : onDiskMaterialization !== undefined ? { ...onDiskMaterialization } : undefined;
       const materializationBlock = resolvedScope !== undefined ? { ...materializationBase ?? {}, scope: resolvedScope } : materializationBase;
       const resolvedQueryMetadata = metadata.queryMetadata ?? materializationBlock?.queryMetadata ?? existingManifest.queryMetadata;
+      const echoesDerivedSurface = existingManifest.explores === undefined && Array.isArray(metadata.explores) && metadata.explores.length === 1 && metadata.explores[0] === INDEX_MODEL_NAME;
       const updatedManifest = {
         ...existingManifest,
         name: metadata.name,
         description: metadata.description,
-        ...metadata.explores !== undefined ? { explores: metadata.explores } : {},
+        ...metadata.explores !== undefined && !echoesDerivedSurface ? { explores: metadata.explores } : {},
         ...metadata.queryableSources !== undefined ? { queryableSources: metadata.queryableSources } : {},
         ...metadata.manifestLocation !== undefined ? { manifestLocation: metadata.manifestLocation } : {},
         ...resolvedScope !== undefined ? { scope: resolvedScope } : {},
@@ -313578,9 +314121,9 @@ class EnvironmentStore {
       }
       const file = fs9.createWriteStream(zipFilePath);
       item.Body.transformToWebStream().pipeTo(Writable.toWeb(file));
-      await new Promise((resolve5, reject2) => {
+      await new Promise((resolve6, reject2) => {
         file.on("error", reject2);
-        file.on("finish", resolve5);
+        file.on("finish", resolve6);
       });
       await this.unzipEnvironment(zipFilePath);
       logger.info(`Downloaded S3 zip file ${s3Path} to ${absoluteDirPath}`);
@@ -313618,9 +314161,9 @@ class EnvironmentStore {
       }
       const file = fs9.createWriteStream(absoluteFilePath);
       item.Body.transformToWebStream().pipeTo(Writable.toWeb(file));
-      await new Promise((resolve5, reject2) => {
+      await new Promise((resolve6, reject2) => {
         file.on("error", reject2);
-        file.on("finish", resolve5);
+        file.on("finish", resolve6);
       });
     }));
     logger.info(`Downloaded S3 directory ${s3Path} to ${absoluteDirPath}`);
@@ -313640,7 +314183,7 @@ class EnvironmentStore {
     await fs9.promises.mkdir(absoluteDirPath, { recursive: true });
     const repoUrl = `https://github.com/${owner}/${repoName}`;
     const reporter = new CloneProgressReporter(cloneProgressLabel(`${owner}/${repoName}`, progressContext));
-    await new Promise((resolve5, reject2) => {
+    await new Promise((resolve6, reject2) => {
       esm_default2({
         progress: (event) => reporter.onProgress(event)
       }).clone(repoUrl, absoluteDirPath, GIT_CLONE_OPTIONS, (err) => {
@@ -313655,7 +314198,7 @@ class EnvironmentStore {
           reject2(err);
           return;
         }
-        resolve5();
+        resolve6();
       });
     });
     if (!cleanPackagePath) {
@@ -314445,7 +314988,7 @@ class Protocol {
   }
   request(request, resultSchema, options) {
     const { relatedRequestId, resumptionToken, onresumptiontoken } = options !== null && options !== undefined ? options : {};
-    return new Promise((resolve5, reject2) => {
+    return new Promise((resolve6, reject2) => {
       var _a2, _b, _c, _d, _e, _f;
       if (!this._transport) {
         reject2(new Error("Not connected"));
@@ -314496,7 +315039,7 @@ class Protocol {
         }
         try {
           const result = resultSchema.parse(response.result);
-          resolve5(result);
+          resolve6(result);
         } catch (error) {
           reject2(error);
         }
@@ -316647,17 +317190,17 @@ var compileShape = {
   source: exports_external.string().optional().describe("The Malloy source to validate; never executed. Required at scope append/file; optional at scope package (a what-if replacement for modelPath)."),
   scope: exports_external.enum(["append", "file", "package"]).optional().describe(`What source means. "append" (default): append to modelPath. "file": compile AS modelPath to validate an edit. "package": run reload's worker compiler over all .malloy/.malloynb files without serving the result; an optional source replaces modelPath.`),
   includeSql: exports_external.boolean().optional().describe("When true and the source ends in a runnable query, also return the generated SQL for inspection. The query is still not run."),
-  givens: exports_external.record(exports_external.unknown()).optional().describe("Given values for the model's given: block. Also required to satisfy any #(authorize) gate on the target model, whether or not includeSql is set.")
+  givens: exports_external.record(exports_external.unknown()).optional().describe("Given values for the model's given: block. Also required to satisfy any authorize gate on the target model, whether or not includeSql is set.")
 };
 var COMPILE_DESCRIPTION = `Compile-check Malloy without running a query. Use this while authoring instead of a throwaway execute_query.
 
 ## Scopes (the scope parameter)
 - "append" (default): append source to modelPath. Use for NEW definitions; existing definitions report "Cannot redefine". Positions refer to the concatenated file.
 - "file": compile source AS modelPath. Use to validate an EDIT before saving; positions match the submitted file.
-- "package": run reload's worker compiler over all .malloy/.malloynb files without changing the served package. Optional source replaces modelPath so importers see the edit. Diagnostics may name files hidden from discovery; no rows or SQL are returned, and #(authorize) still gates caller text. A missing exact path is warned and treated as a new file. Save and call reload_package to serve a clean edit.
+- "package": run reload's worker compiler over all .malloy/.malloynb files without changing the served package. Optional source replaces modelPath so importers see the edit. Diagnostics may name files hidden from discovery; no rows or SQL are returned, and authorize gates still apply to caller text. A missing exact path is warned and treated as a new file. Save and call reload_package to serve a clean edit.
 
 ## Parameters
-- environmentName, packageName, modelPath: required. source: required at append/file, optional at package. includeSql: append/file only. givens: model givens and #(authorize) values. Caller source may not declare #(authorize).
+- environmentName, packageName, modelPath: required. source: required at append/file, optional at package. includeSql: append/file only. givens: model givens and authorize-gate values. Caller source may not declare an access-control gate — neither #(authorize) nor #(access_filter).
 
 ## Response
 { status: "success"|"error", diagnostics: [{ severity, message, code, model, line, character, endLine, endCharacter, replacement }], sql? }. Positions are 0-based; model is the package-relative file the diagnostic points at (which can be pre-existing content, not your source). status is "error" only when an error-severity diagnostic exists; errors are also stated in a plain text block.`;
@@ -318746,6 +319289,21 @@ If the agent could not reasonably have known to ask, that is a model gap.
 | \`GUIDANCE-NOT-RETRIEVED\` | entities came back, governing guidance did not | model: put guidance on the entities agents search for |
 | \`GUIDANCE-DECLINED\` | guidance was retrieved and judged inapplicable | model: state the business default, not a caveat |
 
+**Before diagnosing a \`NOT-RETURNED\`, check the call actually returned
+nothing.** The \`tool_call\` event carries \`retrieval_mode\` and \`rankedSummary\`.
+A \`rankedSummary\` of \`null\` means the response could not be read, not that it
+was empty -- a body too large for the model's context is written to a file, and
+the run records no summary for it. There is nothing to diagnose there: say the
+call was not measured.
+
+And **never attribute a miss to the embedding index unless \`retrieval_mode\`
+says \`lexical\`.** The mode is recorded per call precisely so this is checkable.
+A diagnosis once explained a phantom empty result with "the index was not ready
+yet" on a run whose index was ready before the first question and whose
+response did hold results; the empty list was a parsing bug in the harness. An
+unverifiable cause that sounds right is worse than \`needs_human\`, because it
+closes the finding.
+
 A missing join is coverage, not an agent-call miss. The model has to volunteer
 relationships. A declared join is not a retrieval entity; do not look for it in
 \`get_context\` results.
@@ -319791,6 +320349,27 @@ Output, exactly this shape:
    reading that produced it, that is \`no_match\`. Use \`near_match\` only when you
    can name the rubric clause that makes the difference defensible.
 
+   **A rubric clause cannot make a wrong VALUE defensible, and a clause that
+   tries is a defect in the rubric rather than a licence to you.** \`near_match\`
+   turns on the answer being right under a reading the QUESTION allows -- a tie
+   broken the other way, a grain the question left open, a basis the question
+   never fixed. It does not turn on the answer being transparent about how it
+   got a figure the question did not ask for. Those two look alike in a rubric
+   and are opposites in a report: one is a number a reader can act on, the
+   other is a number a reader would act on wrongly. Naming the method makes a
+   wrong figure DIAGNOSABLE, which is worth having, and it is not partial
+   credit.
+
+   The test, before you write \`near_match\` on a case with a value: would a
+   reader who acted on this figure be wrong? If yes, it is \`no_match\` however
+   plainly the answer explained itself, and however the rubric is worded. Say
+   in \`why\` that you are overriding a rubric clause, so the clause gets fixed.
+   This rule exists because a set shipped one: a question asked for sales over
+   the company's season, the answer gave the meteorological window 25% lower
+   and said which window it used, and a clause granting \`near_match\` for a
+   stated window kept a materially wrong answer out of the pass rate
+   entirely -- the arm reported 100%.
+
    It is a third outcome because as a pass it was a large share of the measured
    noise: the same unchanged answer reads \`match\` in one run and \`near_match\`
    in the next, and the pass rate moves although nothing did. A verdict whose
@@ -320454,11 +321033,19 @@ the run measure something other than what it names:
    first time somebody tidies up; the set, the run directory and the write-up
    belong in git beside the model.
 
-2. The server must be up with retrieval tracing on, so a call's ranked results
-   can be recovered afterwards (open-source Publisher: \`PUBLISHER_MCP_TRACE=retrieval\`).
-   Confirm a trace lookup is available (absent means tracing is off).
-   Refuse to start a scored run without it: failures without traces cannot be
-   attributed.
+2. The server must be up. Where your host offers retrieval tracing, turn it on
+   and confirm a trace lookup answers, so a call's ranked results can be
+   recovered afterwards.
+
+   **Open-source Publisher has none.** \`PUBLISHER_MCP_TRACE=retrieval\` is set by
+   \`serve.py\` and read by nothing: the trace store was written and never merged,
+   so there is no trace tool and \`traceId\` is null on every local attempt. This
+   does not block a scored run, because attribution never depended on it:
+   \`rankedSummary\` is copied onto the \`tool_call\` event at capture, precisely so
+   the evidence survives without a store. So do not refuse a local run for want
+   of tracing -- an earlier version of this rule did, and it refused every local
+   run there has ever been. Refuse one whose \`tool_call\` events carry no
+   \`rankedSummary\`, which is what attribution actually reads.
 
 3. Health-check: your host's status check until it reports serving, and inspect
    \`loadErrors\`. A dead database that still answers HTTP is an environment
@@ -320626,6 +321213,13 @@ conductor. Do not:
 
 - The model is the only thing improve edits. No question text, qids, or
   expected values in any name, doc, or comment.
+- **You are measuring a model, not reviewing this harness.** Read a script when
+  a number you have to report cannot be explained otherwise, and stop there. Do
+  not audit the scripts, propose fixes to them, or hand back tooling critique
+  in place of a result -- a run that ends in harness feedback has not answered
+  the question it was asked. A defect that changed a number gets one sentence
+  in the report; a defect that changed nothing gets one line in chat, once.
+  Fixing it is a different task, and the user starts it.
 - When the environment misbehaves, stop. Never diagnose a sick system. The
   harness is part of the environment: a known-broken measurement does not
   become quotable by being finished. Measured against this directive, an arm
@@ -321586,6 +322180,30 @@ one exception is anything that qualifies THIS run's number -- a truncated
 attempt, a contaminated one, an unestablished answer key -- which the "Eval
 failures" section exists for.
 
+**Do not audit the harness. You were asked to measure a model.** This is the
+most common way this job goes wrong, and it does not look like going wrong: a
+run turns up something odd in a script, the odd thing is genuinely a bug, and
+the reply comes back as a critique of the tooling with the model's score
+somewhere underneath. The reader asked what their model scored. Answer that.
+
+So, unless the user asked you to work on the harness:
+
+- Do not read harness source to satisfy your own curiosity about a number.
+  Read it when a number you must report cannot be explained any other way, and
+  stop when it can.
+- Do not propose harness fixes, refactors, flags or "while I was in there"
+  improvements. Not in the report, not in the chat reply.
+- When a harness defect DID change this run's number, the report gets one
+  sentence: what the number should be and why. Not the mechanism, not the
+  file, not the fix.
+- Keep a defect that changed nothing out of the report entirely. Mention it
+  once in chat, in a line, and let the user decide whether they want it
+  chased.
+
+A harness bug you found and did not chase is not a loose end. It is the job
+being done. If the user wants it fixed they will say so, and then it is a
+different task with its own turn.
+
 ## Step 1: build the artifacts, before writing a word
 
 \`\`\`bash
@@ -321624,6 +322242,29 @@ not in \`~/Downloads\`, both of which have lost a findings document before.
 from the console.** A figure retyped from scrollback is a figure nobody can
 check, and the console rounds.
 
+### Keep it under a page and a half
+
+**Budget: about 80 lines, and 120 is the ceiling for a run with several
+distinct failures.** Reports have shipped at 200 and the length is not
+thoroughness -- it is the artifact links restated as prose, the cascade
+explained twice, and a paragraph apologising for a figure nobody disputed.
+A reader who wants the detail opens the case matrix, which is why step 1 builds
+it. What cannot be recovered from the artifacts is your judgement: what broke,
+why, and what to do. Spend the lines there.
+
+What earns its place: the headline, one row per case, one short entry per
+failure, the retrieval numbers, and the next steps. What does not: restating a
+number you already gave, explaining what a cascade is before showing it,
+defending a decision nobody questioned, or any section whose content is that
+nothing happened -- except "Eval failures", where "None." is the point.
+
+**Being brief is not being terse with the vocabulary.** The reader does not
+know what \`near_match\`, a cluster, recall or a holdout is, so the first time
+one appears, say what it means in the same sentence -- "\`near_match\`, which is
+excluded from the pass rate" -- and then use it. Cutting the explanations is
+how a short report becomes an unreadable one; cutting the restatements is how
+it becomes a good one.
+
 ### The template
 
 \`\`\`markdown
@@ -321637,7 +322278,7 @@ check, and the console rounds.
 - Target \`<env>/<package>\`, model \`<modelPath>\`, pinned \`<modelSha or targetVersion>\`
 - Answerer \`<model>\`, judge \`<model>\`, cap \`<maxTurns>\` turns
 - Steps run: scrape/run, eval<, diagnose><, improve>
-- Cost $X answerer + $Y judge
+- Cost $X answerer + $Y judge, N turns median / N p90, N entities delivered per answer
 
 ## The result
 
@@ -321648,9 +322289,15 @@ check, and the console rounds.
 
 [case matrix](<url>) - [aggregate tables](<url>)
 
-## Retrieval and coverage
+## Coverage, retrieval, accuracy, cost
 
-Covered? -> Retrieved? -> Correct?, with the per-arm numbers under each.
+**Coverage N of M** -- how many questions the model can express an answer to at
+all. **Entity recall N%** -- one number, first, before the cascade. It is the share
+of the entities an answer needed that retrieval actually handed the agent, and
+it is the headline of this section for the same reason the pass rate is the
+headline of the last one. Then the cascade: Covered? -> Retrieved? -> Correct?,
+with the per-arm numbers under each. Say in one clause what recall counts, then
+give the number.
 
 ## Model failures
 
@@ -321679,10 +322326,10 @@ these in order and put every one that fires into the list, with its command:
 
 | If the run shows | Then the next step is |
 |---|---|
-| \`coverage: unmeasured\` | run \`check_coverage.py --set <set> --model <pkg> --out coverage.json\`, then re-run with \`--coverage\` so it charges the failures |
+| \`coverage: unmeasured\` | the run was given \`--no-coverage\`, or the measurement failed and said so. It is measured by default, so say in "Eval failures" that this score cannot tell a model gap from a bad answer, and re-run without the flag |
 | \`goldenCheck: skipped\` or the set names no \`truthPackage\` | build one with \`init_truth_package.py\`; until then the goldens were derived through the model under test and certify themselves |
 | any golden still \`provisional\` | re-derive and \`verify_goldens.py --promote\` |
-| a stale entity name warning | fix \`expectedEntities\`; it scores as a retrieval miss on every run until you do |
+| a stale entity name warning | fix \`expectedEntities\`; it scores as a retrieval miss on every run until you do. A next step, not a section: it goes in this list and nowhere else in the report |
 | a passing case with recall below 1.0 | check whether \`required\` over-specifies one path |
 | \`truncated\` non-empty | re-run those cases at a higher cap with \`--from\` |
 | diagnose did not run | run it, or say the failures have no owner yet |
@@ -321725,8 +322372,23 @@ wrong answer. One entry each: what the answer said, what was right, and the
 mechanism in one sentence. Do not write a cluster id here; write what it got
 wrong.
 
-**Eval failures** are everything that stopped the run measuring the model.
-Report every one that occurred, with its count and its qids, and say plainly
+**Eval failures** are the things that stopped the run measuring the model, and
+**only** those. The test is one question: *did this cost a verdict, or make one
+untrustworthy?* If no, it does not appear in the report at any length.
+
+That rules out most of what is tempting to put here, and all of it has been put
+here on a real run: a \`-dirty\` model pin, a stale-entity-name warning that cost
+no case, a defect you hit in the harness and worked around, a setup step that
+took two tries, anything you would open with "worth knowing, though it changes
+no verdict". A reader wants to know what their model scored. Harness defects are
+real and belong in a harness issue, filed against the harness -- that is the
+skill's opening rule, and this section is where it gets broken.
+
+The section is usually two words. "**None.**" is a complete and good answer, and
+a reader who sees it learns exactly what they need to. Do not pad it into a
+paragraph explaining the absence.
+
+Report every one that DID occur, with its count and its qids, and say plainly
 that these are NOT evidence about the model:
 
 | What happened | How it reads in the ledger | Who fixes it |
@@ -321745,11 +322407,32 @@ harness prints \`INCOMPLETE\` and withholds the percentage; the report does the
 same. Give the counts and the re-run command instead of a number with a caveat,
 because the number is what gets repeated and the caveat is what gets dropped.
 
-## Retrieval and coverage belong in every report
+## The four measurements, and why a report carries all of them
+
+A pass rate says an answer was wrong. It does not say where, and on its own it
+makes every failure look like the model's. A run measures four things, in this
+order, and each one tells you whether the next is even a fair question:
+
+| | Measures | A failure here means |
+|---|---|---|
+| **a. Coverage** | can the data and the model express an answer at all | nothing downstream was winnable. Fix the model |
+| **b. Retrieval** | did \`get_context\` hand the agent the entities it needed | the model has it and the agent never saw it: the docs, or the search wording |
+| **c. Accuracy** | did the agent get the answer right | it had what it needed and still missed: the agent, or a doc that misleads |
+| **d. Cost** | dollars, turns, wall-clock, entities per answer | it works and cannot be afforded, which is its own kind of not working |
 
-A pass rate says an answer was wrong. It does not say WHERE, and the three
-metrics that do are already in the run summary and the notebook. Report them,
-because a report that omits them makes every failure look like the model's:
+**Coverage first, and a report without it is incomplete.** A model that cannot
+express an answer can never succeed at that question, so a pass rate quoted
+without coverage cannot distinguish a bad model from an unanswerable set.
+\`run_baseline.py\` measures it by default; if a run skipped it, say so in
+"Eval failures" and treat the score as provisional.
+
+**Cost is a result, not an aside.** Report dollars, the turn and call counts,
+and the entity payload per answer. An agent that answers correctly in 40 turns
+and 75 delivered entities per question is a different product from one that
+does it in 8 and 5, and only the report says which you have.
+
+Report them all, because a report that omits them makes every failure look
+like the model's:
 
 **Copy the cascade the run printed. Do not re-derive it.** \`cascade_lines()\`
 in \`run_baseline.py\` already renders every rung, and it carries one field a
@@ -321965,6 +322648,7 @@ This table is a catalogue of what exists, not of what is loaded. A host that ins
 | \`skill:malloy-notebooks\` | Building Malloy notebooks (.malloynb) |
 | \`skill:malloy-analysis-report\` | Combining validated queries into a notebook report or dashboard |
 | \`skill:malloy-analysis-pitfalls\` | Checking a query and its results before presenting an answer |
+| \`skill:malloy-source-unreachable\` | A source is missing from discovery, or a query was refused with a 404 or 403 |
 | \`malloy-notebook-chat\` | The chat is bound to a notebook or saved report; answer from its cells. Ships in \`analysis\`. |
 | \`skill:malloy-phrase-detection\` | Turning a plain-English question into search targets for the context tool |
 
@@ -322021,7 +322705,7 @@ Call \`search_malloy_docs\` with your question. Use \`skill:malloy-patterns\` to
     },
     {
       name: "malloy-analysis",
-      description: "The workflow for answering a data question over a Malloy semantic model - a metric, breakdown, trend or chart - from get_context discovery through execute_query to verified delivery.",
+      description: "Read before your first get_context call on any business or data question. The required workflow, not background: which source, which rows, how to verify. Skipping it causes confident wrong answers.",
       body: `# Malloy analysis workflow
 
 > **Tool names** are written bare here - \`get_context\`, \`execute_query\`, \`search_malloy_docs\`. The exact prefixed name depends on the host surface; match each against the tools you actually have.
@@ -322131,7 +322815,7 @@ End with a short **Next steps**: one or two specific deeper analyses the data co
     {
       name: "malloy-analysis-pitfalls",
       description: "Checks to run on a query and its numbers before a result is presented - wrong grain, fan-out, invented field names, mismatched filters, count vs distinct. The common data-analysis pitfalls.",
-      body: "# Data Analysis Pitfalls\n\nWatch for these common mistakes throughout the analysis workflow. When you encounter one, fix it before presenting results.\n\n> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.\n\n## Query Construction\n\n### Wrong grain / fan-out\nUsing dimensions or measures from a joined source that has a finer grain than the base source can silently multiply rows, inflating aggregates. For example, aggregating revenue while grouping by a line-item field may double- or triple-count totals. If your query touches fields from a joined source, compare `count(key_field)` to `count()`: if the row count is significantly higher than the distinct key count, you likely have fan-out.\n\nThat check reads in ONE direction only. `count(joined.field)` is a distinct count evaluated at the joined source's grain, so for an ordinary many-to-one join it is much SMALLER than `count()`, and that is the expected, correct result -- not missing data. Ten thousand flights joined to four hundred aircraft give `count(aircraft.tail_num)` of 400, and nothing is wrong. Do not read a low value as a coverage problem and do not abandon the answer over it. **Coverage is measured at the base grain**, by counting base rows whose joined value is null:\n\n```malloy\nrun: flights -> {\n  aggregate:\n    all_rows is count()\n    missing is count() { where: aircraft.aircraft_models.seats = null }\n}\n```\n\nAn agent once refused a correct answer it had already computed because `count(aircraft.tail_num)` returned 36 against 17,875 flights; measured at the base grain, zero flights were missing a seat value.\n\n### Invented entity names\nNever guess field names. Use only the exact field paths defined in the model (find them with `get_context`). A plausible-sounding name that does not exist in the model will produce an error, or worse, silently reference the wrong field.\n\n### Mismatched filter values\nDimensional values are case-sensitive and format-specific. Common mismatches include case differences (\"Nike\" vs \"NIKE\" vs \"nike, inc.\"), partial matches (\"New York\" when the data has \"New York City\"), and aliased values (\"USA\" vs \"United States\"). A filter on a value that doesn't exist in the data silently returns zero rows without erroring. Always use the exact dimensional values from retrieval results, and if in doubt, run a distinct-values query on the dimension to confirm.\n\n### Filtering on the wrong field\nIf the user asks to filter by \"brand\", confirm which dimension corresponds to \"brand\" in the model. There may be multiple fields with similar names at different levels of the hierarchy.\n\n### Missing filters\nIf the user asks about \"last quarter\" but you don't apply a time filter, you are returning all-time data. Always check whether the question implies filters you have not yet applied.\n\n### Misinterpreted entities\nA field can exist in the model and still be the wrong choice. For example, using `revenue` (which may be gross) when the question asks about profit, or treating a count measure as if it were a sum. Cross-reference the field definitions and `#(doc)` descriptions in the model to confirm a field means what you think it means.\n\n### Semantic ambiguity\nField names or descriptions sometimes suggest one interpretation while the actual values tell a different story, for example, a field labeled \"annual ridership\" containing values that look like average weekday traffic, or a field named `revenue` that appears to represent net revenue in practice. When values don't match expectations, note whether the ambiguity affects the answer and call it out.\n\n### Fragile ad-hoc definitions\nWhen defining a new measure or dimension inline, common mistakes include assuming a field is numeric when it's actually a string, ignoring nulls in arithmetic (e.g., `a - b` yields null if either is null), and building logic around values that only cover a subset of the data.\n\nPay special attention to value coverage when defining a dimension that categorizes or subsets data. It's easy to capture too few values (missing categories that should be included) or too many (grouping in values that don't belong). For example, a `pick` expression that maps tier names to \"Premium\" and \"Standard\" might miss a tier that should be Premium, or a filter meant to isolate one product line might inadvertently include related but distinct products. Before relying on such a definition, run a distinct-values query on the underlying field to see the full set of values and confirm your logic handles them all correctly. This applies equally whether you define the logic as a new dimension or apply it directly as a `where` clause: the risk of incomplete value coverage is the same either way.\n\n### Hidden filters in views\nViews can have built-in `where` clauses that pre-filter the data. A view named `recent_orders` might only include the last 90 days, or `active_customers` might exclude certain statuses. If the view's definition is available, read it to understand what filters are baked in; they may conflict with what the user is asking for. When in doubt, query the base source directly and apply filters explicitly.\n\n## Result Interpretation\n\n### Implausible magnitudes\nIf a \"total\" is suspiciously small or large, question it. Common causes: missing filters (too large), over-filtering (too small), wrong unit (dollars vs. cents), or fan-out from joins (inflated).\n\n### Nulls distorting aggregations\nNull values are silently excluded from `avg()` and can make `sum()` results lower than expected. If a significant portion of a field's data is null, aggregations over that field may be misleading. When results seem off, compare total row count to a count of non-null values for the key field to gauge how much data is missing.\n\n### Confusing count vs. count distinct\n`count()` counts rows while measures defined with `count(field)` count distinct values of that field. Using a row count when you need distinct values (or vice versa) is a frequent source of inflated or deflated numbers, especially when the query touches joined sources.\n\n### Percentage of what?\nWhen computing percentages or shares, be explicit about the denominator. \"30% of revenue\" means nothing if you don't confirm what the total revenue is and whether it's filtered the same way.\n\n### Time period mismatches\nComparing metrics across different time periods without normalizing (e.g., comparing a full year to a partial quarter) produces misleading conclusions.\n\n### Extremes of a rate on a tiny denominator\n\"Which one is worst\" ranked on a ratio hands the top spot to whichever group has the fewest rows: one failure out of three is a 33% failure rate, and it will outrank a group with thousands. Before reporting an extreme of any rate, look at what is underneath it. Apply the model's documented minimum volume if it has one; if it has none, pick a floor, say which floor you picked, and print the denominator next to the rate rather than the rate alone.\n\n## Verification Signals\n\n### Parts don't sum to the whole\nIf you break down a total by category, the categories should sum to the total (or close to it, accounting for nulls). If they don't, something is wrong with the grain or filters.\n\n### A total the model tells you not to take\nThe check above assumes the parts are additive. Sometimes they are not, and the model says so: a doc noting that one event can be logged on two layers, or that a measure is non-additive, is telling you the sum across that dimension double-counts. Do not print a total row across such a dimension, and least of all one the user did not ask for. If a total is genuinely wanted, say why the model does not support it and give the per-category figures.\n\n### Row count surprises\nBefore interpreting results, check whether the row count makes sense. An unexpectedly high row count often indicates fan-out from a join. An unexpectedly low count may mean an overly restrictive filter.\n\n### Zero or empty results\nIf a query returns no rows, don't report \"there is no data.\" First verify that your filters are correct and the field names are right. The absence of results is usually a query problem, not a data problem."
+      body: "# Data Analysis Pitfalls\n\nWatch for these common mistakes throughout the analysis workflow. When you encounter one, fix it before presenting results.\n\n> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.\n\n## Query Construction\n\n### Wrong grain / fan-out\nUsing dimensions or measures from a joined source that has a finer grain than the base source can silently multiply rows, inflating aggregates. For example, aggregating revenue while grouping by a line-item field may double- or triple-count totals. If your query touches fields from a joined source, compare `count(key_field)` to `count()`: if the row count is significantly higher than the distinct key count, you likely have fan-out.\n\nThat check reads in ONE direction only. `count(joined.field)` is a distinct count evaluated at the joined source's grain, so for an ordinary many-to-one join it is much SMALLER than `count()`, and that is the expected, correct result -- not missing data. Ten thousand flights joined to four hundred aircraft give `count(aircraft.tail_num)` of 400, and nothing is wrong. Do not read a low value as a coverage problem and do not abandon the answer over it. **Coverage is measured at the base grain**, by counting base rows whose joined value is null:\n\n```malloy\nrun: flights -> {\n  aggregate:\n    all_rows is count()\n    missing is count() { where: aircraft.aircraft_models.seats is null }\n}\n```\n\nAn agent once refused a correct answer it had already computed because `count(aircraft.tail_num)` returned 36 against 17,875 flights; measured at the base grain, zero flights were missing a seat value.\n\n### Invented entity names\nNever guess field names. Use only the exact field paths defined in the model (find them with `get_context`). A plausible-sounding name that does not exist in the model will produce an error, or worse, silently reference the wrong field.\n\n### Mismatched filter values\nDimensional values are case-sensitive and format-specific. Common mismatches include case differences (\"Nike\" vs \"NIKE\" vs \"nike, inc.\"), partial matches (\"New York\" when the data has \"New York City\"), and aliased values (\"USA\" vs \"United States\"). A filter on a value that doesn't exist in the data silently returns zero rows without erroring. Always use the exact dimensional values from retrieval results, and if in doubt, run a distinct-values query on the dimension to confirm.\n\n### Filtering on the wrong field\nIf the user asks to filter by \"brand\", confirm which dimension corresponds to \"brand\" in the model. There may be multiple fields with similar names at different levels of the hierarchy.\n\n### Missing filters\nIf the user asks about \"last quarter\" but you don't apply a time filter, you are returning all-time data. Always check whether the question implies filters you have not yet applied.\n\n### Misinterpreted entities\nA field can exist in the model and still be the wrong choice. For example, using `revenue` (which may be gross) when the question asks about profit, or treating a count measure as if it were a sum. Cross-reference the field definitions and `#(doc)` descriptions in the model to confirm a field means what you think it means.\n\n### Semantic ambiguity\nField names or descriptions sometimes suggest one interpretation while the actual values tell a different story, for example, a field labeled \"annual ridership\" containing values that look like average weekday traffic, or a field named `revenue` that appears to represent net revenue in practice. When values don't match expectations, note whether the ambiguity affects the answer and call it out.\n\n### Fragile ad-hoc definitions\nWhen defining a new measure or dimension inline, common mistakes include assuming a field is numeric when it's actually a string, ignoring nulls in arithmetic (e.g., `a - b` yields null if either is null), and building logic around values that only cover a subset of the data.\n\nPay special attention to value coverage when defining a dimension that categorizes or subsets data. It's easy to capture too few values (missing categories that should be included) or too many (grouping in values that don't belong). For example, a `pick` expression that maps tier names to \"Premium\" and \"Standard\" might miss a tier that should be Premium, or a filter meant to isolate one product line might inadvertently include related but distinct products. Before relying on such a definition, run a distinct-values query on the underlying field to see the full set of values and confirm your logic handles them all correctly. This applies equally whether you define the logic as a new dimension or apply it directly as a `where` clause: the risk of incomplete value coverage is the same either way.\n\n### Hidden filters in views\nViews can have built-in `where` clauses that pre-filter the data. A view named `recent_orders` might only include the last 90 days, or `active_customers` might exclude certain statuses. If the view's definition is available, read it to understand what filters are baked in; they may conflict with what the user is asking for. When in doubt, query the base source directly and apply filters explicitly.\n\n## Result Interpretation\n\n### Implausible magnitudes\nIf a \"total\" is suspiciously small or large, question it. Common causes: missing filters (too large), over-filtering (too small), wrong unit (dollars vs. cents), or fan-out from joins (inflated).\n\n### Nulls distorting aggregations\nNull values are silently excluded from `avg()` and can make `sum()` results lower than expected. If a significant portion of a field's data is null, aggregations over that field may be misleading. When results seem off, compare total row count to a count of non-null values for the key field to gauge how much data is missing.\n\n### Confusing count vs. count distinct\n`count()` counts rows while measures defined with `count(field)` count distinct values of that field. Using a row count when you need distinct values (or vice versa) is a frequent source of inflated or deflated numbers, especially when the query touches joined sources.\n\n### Percentage of what?\nWhen computing percentages or shares, be explicit about the denominator. \"30% of revenue\" means nothing if you don't confirm what the total revenue is and whether it's filtered the same way.\n\n### Time period mismatches\nComparing metrics across different time periods without normalizing (e.g., comparing a full year to a partial quarter) produces misleading conclusions.\n\n### Extremes of a rate on a tiny denominator\n\"Which one is worst\" ranked on a ratio hands the top spot to whichever group has the fewest rows: one failure out of three is a 33% failure rate, and it will outrank a group with thousands. Before reporting an extreme of any rate, look at what is underneath it. Apply the model's documented minimum volume if it has one; if it has none, pick a floor, say which floor you picked, and print the denominator next to the rate rather than the rate alone.\n\n## Verification Signals\n\n### Parts don't sum to the whole\nIf you break down a total by category, the categories should sum to the total (or close to it, accounting for nulls). If they don't, something is wrong with the grain or filters.\n\n### A total the model tells you not to take\nThe check above assumes the parts are additive. Sometimes they are not, and the model says so: a doc noting that one event can be logged on two layers, or that a measure is non-additive, is telling you the sum across that dimension double-counts. Do not print a total row across such a dimension, and least of all one the user did not ask for. If a total is genuinely wanted, say why the model does not support it and give the per-category figures.\n\n### Row count surprises\nBefore interpreting results, check whether the row count makes sense. An unexpectedly high row count often indicates fan-out from a join. An unexpectedly low count may mean an overly restrictive filter.\n\n### Zero or empty results\nIf a query returns no rows, don't report \"there is no data.\" First verify that your filters are correct and the field names are right. The absence of results is usually a query problem, not a data problem."
     },
     {
       name: "malloy-analysis-report",
@@ -322430,6 +323114,13 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
 
 ## Build sequence
 
+0. **CHECK THE PACKAGE CAN SERVE A DASHBOARD AT ALL.** If its root holds an \`index.malloy\`, that
+   file is the package's surface, and a dashboard's file is not something it can \`export\`, so the
+   dashboard you are about to write will compile and then be withheld. Every package made by the
+   scaffolder has that file, so this is the common case, not the corner one. Serving dashboards
+   there means declaring an \`explores\` in \`publisher.json\` naming \`index.malloy\` and every dashboard
+   file, which overrides the convention. Settle that first: it is a different curation shape for the
+   package, not a line to add at the end. See "Read the lint" for the warning it produces otherwise.
 1. **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 or the \`.malloy\` files.
    Never guess a name. A guessed field in a query fails the whole package load, not just that one
@@ -322840,8 +323531,8 @@ Package warnings after a reload are the dashboard's test suite. Fix all of them:
 Findings carry a \`severity\`, but \`warn\` is the ordinary default and tells you nothing about how bad
 one is. Read the text, not the severity and not the count. One message is worth recognising because
 it changes what the rest of the list means: **"Dashboard lint stopped early, so this list is
-incomplete"**. A dashboard withheld from \`explores\` also loses its own findings, so a short list for a
-withheld file is not a clean bill of health.
+incomplete"**. A dashboard withheld from the package's surface also loses its own findings, so a
+short list for a withheld file is not a clean bill of health.
 
 **Read the status the reload itself returns, not the listing.** One dashboard that fails to compile
 fails the whole package load, and the reload answers **424** with the compile error. A package that
@@ -322856,11 +323547,22 @@ at all appears there too, without \`stale\`, and is absent from the listing enti
 
 If the reload is 200 and the others are listed but yours is not, discovery skipped the file instead,
 usually a missing or misspelled \`# artifact\` tag, which is the same mechanism that deliberately skips
-an untagged shared include. There is a second cause if the package's \`publisher.json\` carries an
-\`explores\` list: a dashboard whose file is missing from it is withheld rather than served, and the
-warning says so and names the fix. The list is what matters, not the \`queryableSources\` setting, which
-is \`declared\` by default; a package with no \`explores\` list withholds nothing. Where there is one, a
-\`suggest\` source has to be queryable as well as resolvable, so it needs to be on the list too.
+an untagged shared include. There is a second cause whenever the package has a curated surface: a
+dashboard whose file is off it is withheld rather than served, and the warning says so and names the
+fix. A package has a surface in two ways, and the second is easy to miss because no manifest field
+records it:
+
+- the package's \`publisher.json\` carries an \`explores\` list, and the dashboard's file is not on it;
+- the package root holds an **\`index.malloy\`**, which IS the surface. This bites in both
+  directions, and a dashboard's file is not something an \`index.malloy\` exports either way: adding
+  that file to a package that has dashboards withholds every one of them, and adding a dashboard to
+  a package that already has one (every scaffolded package does) means it is never served. The fix
+  is the same in both directions, and it is not an edit to \`index.malloy\`: declare an \`explores\` in
+  \`publisher.json\` naming \`index.malloy\` and every dashboard file.
+
+Either way the surface is what matters, not the \`queryableSources\` setting, which is \`declared\` by
+default; a package with neither withholds nothing. Where there is a surface, a \`suggest\` source has
+to be queryable as well as resolvable, so it needs to be reachable through it too.
 
 **A clean reload is not proof the tags are right.** The checks above read names and resolve them; the
 separate warning for a tag that does not _parse_ is syntax only: it carries no
@@ -323229,7 +323931,7 @@ A confirmed source architecture and a confirmed set of field definitions (rename
     {
       name: "malloy-gotchas-queries",
       description: "Common Malloy query and view mistakes, for writing views, queries or notebooks - chart constraints, aggregate filters, joined field aliasing, method syntax, time truncation vs extraction.",
-      body: "# Query & View Gotchas\n\n> **Read this before writing views or queries.** These patterns cause most query errors.\n\n## Charts: ONE Aggregate Per View\n\nCharts render only the **first** aggregate. Use exactly one aggregate per `# bar_chart` / `# line_chart` view.\n\n```malloy\n// WRONG: revenue is ignored\n# bar_chart\nview: x is { group_by: status, aggregate: order_count, revenue }\n// RIGHT: single aggregate\n# bar_chart\nview: x is { group_by: status, aggregate: revenue }\n```\n\nFor multiple metrics: nest separate chart views in a `# dashboard`, or use `y=['revenue','cost']` for multi-measure series.\n\n## Joined Fields in `order_by`: Must Alias First\n\n```malloy\n// WRONG: compile error\nview: x is { group_by: races.season_year, aggregate: pts, order_by: races.season_year }\n// RIGHT: alias then reference\nview: x is { group_by: yr is races.season_year, aggregate: pts, order_by: yr }\n```\n\nAny time you `group_by` a joined field, create an alias and use it in `order_by`.\n\n## `having:` vs `where:`: Aggregate Filters\n\n```malloy\n// WRONG: \"Aggregate expressions not allowed in where\"\nview: x is { group_by: cat, aggregate: n is count(), where: n > 10 }\n// RIGHT\nview: x is { group_by: cat, aggregate: n is count(), having: n > 10 }\n```\n\n- `where:` filters rows BEFORE aggregation (dimensions/raw columns)\n- `having:` filters AFTER aggregation (measures)\n\n## Aggregating Joined Fields: Method Syntax\n\n```malloy\n// WRONG: compile error: \"Join path is required for this calculation; use 'inventory_items.item_cost.sum()'\"\nmeasure: cogs is sum(inventory_items.item_cost)\n// RIGHT: method syntax\nmeasure: cogs is inventory_items.item_cost.sum()\n```\n\n`sum`, `avg`, `min`, and `max` over a dotted joined path all produce that compile error; the diagnostic message even tells you the exact fix. Don't worry about catching this in code review; the compiler does it for you.\n\n**Method syntax is for aggregates over a path. Scalar functions never take it.**\n\n```malloy\n// WRONG: \"something is missing before 'round'\"\naggregate: avg_price_r is avg(price).round(2)\naggregate: avg_price_r is price.avg().round(2)\n// WRONG: \"Cannot call function round(number, number) with source\"\naggregate: avg_price_r is avg_price.round(2)\ndimension: rounded is price.round(2)\n// RIGHT: scalar functions are always call form\naggregate: avg_price_r is round(avg(price), 2)\ndimension: rounded is round(price, 2)\n```\n\nTwo separate rules produce those errors:\n\n- **No method call chains onto the result of a function call.** `avg(price).round(2)` and `price.avg().round(2)` are both parse errors. The message names `round` without saying it is unsupported in that position, so it reads like a typo somewhere else. `.floor()` and `.ceil()` fail identically.\n- **Scalar functions have no method form.** `round`, `floor`, and `ceil` are always `round(x, 2)`, never `x.round(2)`, whether `x` is a named measure or a plain column.\n\n`price.avg()` and `inventory_items.item_cost.sum()` are correct because `avg` and `sum` are aggregate functions over a field path, which is exactly what method syntax is for.\n\n**Exception: `count(joined.field)` is correct, not a bug.** `count(joined.field)` is the **canonical Malloy idiom** for distinct-count through a join. Keep it as-is even when nearby `sum`/`avg`/`min`/`max` calls have to use method syntax. The closest method-syntax form `joined.count()` counts *rows* in the joined source (different semantics, differs from the distinct count when the joined field has duplicates within the joined table). The Malloy docs example `joined.count(field)` does NOT compile against current Malloy (error: `Expression illegal inside path.count()`); it only works for double-nested paths like `aircraft.count(aircraft_models.code)`.\n\n## `sum`/`avg` Need a Numeric Field\n\n```malloy\n// WRONG: \"Can't use type string\" - status is a string column\naggregate: avg_status is avg(status)\n// RIGHT: aggregate a numeric field; count a string one\naggregate: avg_price is avg(price), statuses is count(status)\n```\n\nCheck the field's type in the `get_context` result before aggregating it. A name that reads numeric (`order_number`, `zip`, `account_id`) is very often typed string.\n\n## Dotted Paths Must Name a Declared Join\n\n```malloy\n// WRONG: the source declares the join as `carrier`, so this fails with\n//   \"'carriers.name' is not a source or join\"\nrun: flights -> { group_by: carriers.name }\n// RIGHT: use the join name the source actually declares\nrun: flights -> { group_by: carrier.nickname }\n```\n\nA dotted path resolves only against a join declared on the source you are running. Confirm both the join name and the field under it in a `get_context` result; do not infer either from a table name or a plural/singular guess.\n\n## `order_by:` Can Only Name an Output Column\n\n```malloy\n// WRONG: \"Unknown field total in output space\" - total is never emitted\nrun: orders -> { group_by: state, aggregate: revenue is sum(total), order_by: total }\n// RIGHT: order by a column the query actually outputs\nrun: orders -> { group_by: state, aggregate: revenue is sum(total), order_by: revenue }\n```\n\n`order_by:` resolves against the query's *output* columns, not the source's fields. To order by something, `group_by` or `aggregate` it first - and if it comes through a join, alias it (see above).\n\n## Chart Annotation Placement\n\nPlace `# bar_chart` / `# line_chart` on the **nested view definition**, not on `nest:` itself. Putting it on `nest:` causes \"not a repeated record\" errors.\n\n## DRY: Define in Source, Reference in View\n\n```malloy\n// WRONG: inline in view\nview: summary is { aggregate: revenue is sum(total) }\n// RIGHT: reference existing measure\nview: summary is { aggregate: revenue }\n```\n\n## Time Truncation vs Extraction\n\n| Syntax | What it does | Returns |\n|--------|--------------|---------|\n| `ts.month` | Truncates to start of month | Timestamp (`@2024-03-01`) |\n| `month(ts)` | Extracts month number | Integer (1-12) |\n| `ts.year` | Truncates to start of year | Timestamp (`@2024-01-01`) |\n| `year(ts)` | Extracts year number | Integer (2024) |\n\nUse `.month` for time series charts (proper date ordering). Use `month()` for cross-year comparison.\n\n**Year integers render with commas.** `year(ts)` displays as `2,018`. Tag with `# number=id` to suppress commas. Same for zip codes, IDs.\n\n## `?` Alternation: Use Commas to Combine Filters\n\nThe `?` operator is Malloy's **alternation operator**: a shorthand for \"match any of these values.\" `party ? 'Democrat' | 'Republican'` means `party = 'Democrat' OR party = 'Republican'`. The `|` separates the alternatives.\n\nWhen combining an alternation filter with other filters, **use a comma**:\n\n```malloy\n// CANONICAL: commas separate independent filter conditions\nwhere: is_us = true, party ? 'Democrat' | 'Republican'\n```\n\n`and` works in some arrangements (when the alternation is the second operand) but produces a confusing `'logical operator' Can't use type string` compile error when the alternation comes first. The comma form is unambiguous in every position, so just use it.\n\n## Query Clauses Are Newline-Separated\n\nDo not use trailing commas between query clauses. Each clause goes on its own line.\n\n```malloy\n// WRONG: trailing comma before limit\nrun: source -> { group_by: status, aggregate: n is count(), limit: 10 }\n// RIGHT: newline-separated\nrun: source -> {\n  group_by: status\n  aggregate: n is count()\n  limit: 10\n}\n```\n\nClauses: `group_by:`, `aggregate:`, `nest:`, `order_by:`, `limit:`, `where:`, `having:`, `select:`, `calculate:`\n\n## Fields Within a Clause: Commas or Newlines, Never Semicolons\n\nSemicolons are not a separator anywhere in Malloy. Multiple fields under one `aggregate:` / `group_by:` are separated by commas (inline) or newlines (one per line); a `;` fails with `no viable alternative at input '<next-field>'` pointing at the field right after it.\n\n```malloy\n// WRONG: semicolons between fields\nrun: schools -> { aggregate: total is count(); charters is count() { where: is_charter } }\n// RIGHT: commas inline...\nrun: schools -> { aggregate: total is count(), charters is count() { where: is_charter } }\n// ...or newlines\nrun: schools -> {\n  aggregate:\n    total is count()\n    charters is count() { where: is_charter }\n}\n```"
+      body: "# Query & View Gotchas\n\n> **Read this before writing views or queries.** These patterns cause most query errors.\n\n## Charts: ONE Aggregate Per View\n\nCharts render only the **first** aggregate. Use exactly one aggregate per `# bar_chart` / `# line_chart` view.\n\n```malloy\n// WRONG: revenue is ignored\n# bar_chart\nview: x is { group_by: status, aggregate: order_count, revenue }\n// RIGHT: single aggregate\n# bar_chart\nview: x is { group_by: status, aggregate: revenue }\n```\n\nFor multiple metrics: nest separate chart views in a `# dashboard`, or use `y=['revenue','cost']` for multi-measure series.\n\n## Joined Fields in `order_by`: Must Alias First\n\n```malloy\n// WRONG: compile error\nview: x is { group_by: races.season_year, aggregate: pts, order_by: races.season_year }\n// RIGHT: alias then reference\nview: x is { group_by: yr is races.season_year, aggregate: pts, order_by: yr }\n```\n\nAny time you `group_by` a joined field, create an alias and use it in `order_by`.\n\n## `having:` vs `where:`: Aggregate Filters\n\n```malloy\n// WRONG: \"Aggregate expressions not allowed in where\"\nview: x is { group_by: cat, aggregate: n is count(), where: n > 10 }\n// RIGHT\nview: x is { group_by: cat, aggregate: n is count(), having: n > 10 }\n```\n\n- `where:` filters rows BEFORE aggregation (dimensions/raw columns)\n- `having:` filters AFTER aggregation (measures)\n\n## Aggregating Joined Fields: Method Syntax\n\n```malloy\n// WRONG: compile error: \"Join path is required for this calculation; use 'inventory_items.item_cost.sum()'\"\nmeasure: cogs is sum(inventory_items.item_cost)\n// RIGHT: method syntax\nmeasure: cogs is inventory_items.item_cost.sum()\n```\n\n`sum`, `avg`, `min`, and `max` over a dotted joined path all produce that compile error; the diagnostic message even tells you the exact fix. Don't worry about catching this in code review; the compiler does it for you.\n\n**Method syntax is for aggregates over a path. Scalar functions never take it.**\n\n```malloy\n// WRONG: \"something is missing before 'round'\"\naggregate: avg_price_r is avg(price).round(2)\naggregate: avg_price_r is price.avg().round(2)\n// WRONG: \"Cannot call function round(number, number) with source\"\naggregate: avg_price_r is avg_price.round(2)\ndimension: rounded is price.round(2)\n// RIGHT: scalar functions are always call form\naggregate: avg_price_r is round(avg(price), 2)\ndimension: rounded is round(price, 2)\n```\n\nTwo separate rules produce those errors:\n\n- **No method call chains onto the result of a function call.** `avg(price).round(2)` and `price.avg().round(2)` are both parse errors. The message names `round` without saying it is unsupported in that position, so it reads like a typo somewhere else. `.floor()` and `.ceil()` fail identically.\n- **Scalar functions have no method form.** `round`, `floor`, and `ceil` are always `round(x, 2)`, never `x.round(2)`, whether `x` is a named measure or a plain column.\n\n`price.avg()` and `inventory_items.item_cost.sum()` are correct because `avg` and `sum` are aggregate functions over a field path, which is exactly what method syntax is for.\n\n**Exception: `count(joined.field)` is correct, not a bug.** `count(joined.field)` is the **canonical Malloy idiom** for distinct-count through a join. Keep it as-is even when nearby `sum`/`avg`/`min`/`max` calls have to use method syntax. The closest method-syntax form `joined.count()` counts *rows* in the joined source (different semantics, differs from the distinct count when the joined field has duplicates within the joined table). The Malloy docs example `joined.count(field)` does NOT compile against current Malloy (error: `Expression illegal inside path.count()`); it only works for double-nested paths like `aircraft.count(aircraft_models.code)`.\n\n## `sum`/`avg` Need a Numeric Field\n\n```malloy\n// WRONG: \"Can't use type string\" - status is a string column\naggregate: avg_status is avg(status)\n// RIGHT: aggregate a numeric field; count a string one\naggregate: avg_price is avg(price), statuses is count(status)\n```\n\nCheck the field's type in the `get_context` result before aggregating it. A name that reads numeric (`order_number`, `zip`, `account_id`) is very often typed string.\n\n## A Measure Is Already an Aggregate\n\n```malloy\n// WRONG: \"Aggregate expression cannot be aggregate\" - flight_count is a measure\nrun: flights -> { aggregate: busiest is max(flight_count) }\n// RIGHT: aggregate per group, then take the max in a second stage\nrun: flights -> { group_by: carrier, aggregate: n is flight_count } -> { aggregate: busiest is max(n) }\n```\n\nThe message does not name the field. When it appears, look for a model measure you wrapped in another aggregate. If you only need the top row, skip the second stage: `order_by: n desc` with `limit: 1`.\n\n## Window Braces Bind to the Function\n\n```malloy\n// WRONG: \"`partition_by` is not supported for this kind of expression\"\ncalculate: share is sum_cumulative(n) / region_total { partition_by: region, order_by: n desc }\n// RIGHT: the brace goes directly after the window function call\ncalculate: share is sum_cumulative(n) { partition_by: region, order_by: n desc } / region_total\n```\n\nFor a within-group share, compute the denominator in `aggregate:` (`region_total is all(count(), region)`). A window's `{ partition_by }` does not apply to `all()`.\n\n## Dotted Paths Must Name a Declared Join\n\n```malloy\n// WRONG: the source declares the join as `carrier`, so this fails with\n//   \"'carriers.name' is not a source or join\"\nrun: flights -> { group_by: carriers.name }\n// RIGHT: use the join name the source actually declares\nrun: flights -> { group_by: carrier.nickname }\n```\n\nA dotted path resolves only against a join declared on the source you are running. Confirm both the join name and the field under it in a `get_context` result; do not infer either from a table name or a plural/singular guess.\n\n## `order_by:` Can Only Name an Output Column\n\n```malloy\n// WRONG: \"Unknown field total in output space\" - total is never emitted\nrun: orders -> { group_by: state, aggregate: revenue is sum(total), order_by: total }\n// RIGHT: order by a column the query actually outputs\nrun: orders -> { group_by: state, aggregate: revenue is sum(total), order_by: revenue }\n```\n\n`order_by:` resolves against the query's *output* columns, not the source's fields. To order by something, `group_by` or `aggregate` it first - and if it comes through a join, alias it (see above).\n\n## Chart Annotation Placement\n\nPlace `# bar_chart` / `# line_chart` on the **nested view definition**, not on `nest:` itself. Putting it on `nest:` causes \"not a repeated record\" errors.\n\n## DRY: Define in Source, Reference in View\n\n```malloy\n// WRONG: inline in view\nview: summary is { aggregate: revenue is sum(total) }\n// RIGHT: reference existing measure\nview: summary is { aggregate: revenue }\n```\n\n## Time Truncation vs Extraction\n\n| Syntax | What it does | Returns |\n|--------|--------------|---------|\n| `ts.month` | Truncates to start of month | Timestamp (`@2024-03-01`) |\n| `month(ts)` | Extracts month number | Integer (1-12) |\n| `ts.year` | Truncates to start of year | Timestamp (`@2024-01-01`) |\n| `year(ts)` | Extracts year number | Integer (2024) |\n\nUse `.month` for time series charts (proper date ordering). Use `month()` for cross-year comparison.\n\n**Year integers render with commas.** `year(ts)` displays as `2,018`. Tag with `# number=id` to suppress commas. Same for zip codes, IDs.\n\n## `?` Alternation: Use Commas to Combine Filters\n\nThe `?` operator is Malloy's **alternation operator**: a shorthand for \"match any of these values.\" `party ? 'Democrat' | 'Republican'` means `party = 'Democrat' OR party = 'Republican'`. The `|` separates the alternatives.\n\nWhen combining an alternation filter with other filters, **use a comma**:\n\n```malloy\n// CANONICAL: commas separate independent filter conditions\nwhere: is_us = true, party ? 'Democrat' | 'Republican'\n```\n\n`and` works in some arrangements (when the alternation is the second operand) but produces a confusing `'logical operator' Can't use type string` compile error when the alternation comes first. The comma form is unambiguous in every position, so just use it.\n\n## Strings: Apostrophes and Concatenation\n\n```malloy\n// WRONG: \"no viable alternative at input 's'\" - the apostrophe ends the literal\nwhere: name = 'Mac's Diner'\n// RIGHT\nwhere: name = \"Mac's Diner\"\n\n// WRONG: \"unexpected '+'\" / \"no viable alternative at input '||'\"\ngroup_by: route is origin ++ '-' ++ destination\n// RIGHT: there is no concatenation operator\ngroup_by: route is concat(origin, '-', destination)\n```\n\n## A Semicolon Inside a Clause Ends It\n\nBetween clauses a newline, comma or `;` all work. Within one clause, separate fields with commas or newlines: a `;` closes the clause, and the next field is orphaned.\n\n```malloy\n// WRONG: \"no viable alternative at input 'charters'\"\nrun: schools -> { aggregate: total is count(); charters is count() { where: is_charter } }\n// RIGHT\nrun: schools -> { aggregate: total is count(), charters is count() { where: is_charter } }\n```\n\nThe same message appears for an unnamed aggregate after the first: `aggregate: n, max(x)` fails at `max`. Name every entry.\n\n## Compiles, Then Refused by the Warehouse\n\n`Query execution failed: ...` means the Malloy compiled and the warehouse rejected the SQL, often over a type. The position it quotes is in the generated SQL, not in your query. BigQuery, for example, will not partition a window function on a FLOAT64 column. `partition_by:` takes only a field name, so cast in `group_by:` (`season_key is season::string`) and partition on `season_key`, or fix the type in the model."
     },
     {
       name: "malloy-gotchas-rendering",
@@ -323362,7 +324064,7 @@ view: overview is {
     {
       name: "malloy-html-data-app-runtime",
       description: "The JavaScript that drives an in-package HTML data app - calling Publisher.query, building queries from filter state, handling results and errors. For writing the page's data code.",
-      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 source with `#(authorize)`, a bad given (unknown name or wrong-typed value) fails closed in the authorize check, so it looks like access denied rather than validation. 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| 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: 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| 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",
@@ -324006,7 +324708,7 @@ LookML flattens nested field names with double underscores: \`project__id\`, \`l
     {
       name: "malloy-lookml-review/curate-visibility",
       description: "LookML Visibility → Malloy Access Modifiers (Step 8). Reference detail for the malloy-lookml-review skill.",
-      body: "# LookML Visibility → Malloy Access Modifiers (Step 8)\n\n> Classify LookML visibility mechanisms and map them to Malloy access modifiers. This runs during Step 8 (CURATE) when the prior-art notes have a Visibility Seeds section.\n\n## LookML Visibility Mechanisms\n\n| LookML Mechanism | Semantics | Strength |\n|---|---|---|\n| `hidden: yes` | Hidden from Explore field picker, but still queryable via URL/API | Cosmetic: UI decluttering |\n| `fields` (explore-level) | Excluded from an explore's available field pool. Not queryable. Can use `ALL_FIELDS*` with `-field` exclusions. | Structural: field genuinely inaccessible |\n| `fields` (join-level) | Restricts which fields from a joined view enter the explore. Include-list only. | Structural: field never enters the pool |\n| `fields_hidden_by_default: yes` | All view fields hidden unless individually opted in with `hidden: no` | Cosmetic: bulk hide |\n| `required_access_grants` | User-attribute-based restriction. True security mechanism. | Security: access controlled |\n\n## Classification → Malloy Treatment\n\nFor each hidden/excluded field, determine the **reason** and map to the correct Malloy treatment:\n\n| Classification | LookML Signal | Malloy Treatment |\n|---|---|---|\n| **Intermediate calculation** | `hidden: yes` + referenced by other fields via `${field}` | `# hidden` tag: keep accessible, hide from display |\n| **Join key / FK** | `hidden: yes` + used in `sql_on:` conditions | Keep public, no `#(doc)`: needed for joins |\n| **UI clutter** | `hidden: yes` + not referenced elsewhere | Assess: if truly unused, `internal:` candidate; if just verbose, `# hidden` |\n| **Explore-scoped exclusion** | Excluded via `fields` parameter | `internal:` candidate: field was structurally inaccessible |\n| **Bulk hidden** | `fields_hidden_by_default: yes` on view | Treat each field individually based on its role |\n| **Access-restricted** | `required_access_grants` | `private:` candidate: flag for user decision |\n| **Not hidden** | No visibility restriction | Public + `#(doc)` candidate |\n\n## Key Distinction\n\nLookML `hidden: yes` ≈ Malloy `# hidden` (cosmetic). LookML `fields` exclusion ≈ Malloy `internal:` (structural).\n\n**Do NOT map `hidden: yes` directly to `internal:`.** That over-restricts fields that may be needed as intermediate calculations or join keys.\n\n## Pattern: Restricted-field masking (`include { private: } + pick`)\n\nWhen a sensitive field should be *present in a redacted/bucketed form* rather than dropped, don't reach for an access modifier alone: modifiers hide or expose, they don't transform. Keep the raw column **`private:`** and derive a masked dimension from it in the source's immediate `extend {}`: a `private:` field is referenceable from the immediate extension, so the raw value stays out of the queryable surface while the mask is public. The mask must key on **data the model can see**, a row-level column or a source `parameter`, not on the viewer:\n\n```malloy\n##! experimental.access_modifiers\nsource: revenue is conn.table('…') include {\n  private: raw_amount              // raw stays out of the queryable surface…\n} extend {\n  dimension: amount is             // …but is referenceable here, in the immediate extension\n    pick null when is_confidential          // is_confidential is a ROW column, not the viewer\n    else raw_amount\n  // or bucket instead of null-out:\n  //   pick 'under 50k' when raw_amount < 50000\n  //   pick '50k–100k'  when raw_amount < 100000\n  //   else '100k+'\n}\n```\n\nGive the mask a **different name** from the private raw column (`amount` vs `raw_amount`), reusing the name is a redefinition. If the mask must carry the raw column's *exact* original name, that forces a `rename:`, which pushes you onto the `extend { rename }` path. That path composes with `include {}`, but only in one order (the `extend { rename: }` first, then `include {}` naming the post-rename field; see `skill:malloy-gotchas-modeling`), and you still have to move the raw column out of the way before the mask can take its name. Prefer a distinct mask name and keep the raw `private:` unless the exact original name is required.\n\n**This is NOT per-viewer access control.** LookML `required_access_grants` gates on the *viewing user's* attributes; Malloy models have no per-viewer context, so a model-layer `pick` can only redact based on row data or a parameter. To gate a field by *caller identity/role* (the real `required_access_grants` equivalent), use `#(authorize)` on the source, driven by trusted attributes in Malloy Publisher (see `skill:malloy-model` § Access Control). Masking and `#(authorize)` are independent layers; use the mask for \"everyone sees a coarsened value,\" `#(authorize)` for \"only some callers see the field at all.\"\n\n## Pattern: Long→wide custom-field pivot\n\nSee `build-derived-tables.md` → \"Long→wide entity-values pivot\" for turning an entity-attribute-value (EAV) custom-field table into wide columns with **filtered aggregates**, the right move when LookML modeled N per-attribute joins.\n\n## Process\n\n1. Read the Visibility Seeds notes captured during discovery\n2. For each field, apply the classification rules above\n3. Present the classified list to the user for confirmation before applying access modifiers"
+      body: "# LookML Visibility → Malloy Access Modifiers (Step 8)\n\n> Classify LookML visibility mechanisms and map them to Malloy access modifiers. This runs during Step 8 (CURATE) when the prior-art notes have a Visibility Seeds section.\n\n## LookML Visibility Mechanisms\n\n| LookML Mechanism | Semantics | Strength |\n|---|---|---|\n| `hidden: yes` | Hidden from Explore field picker, but still queryable via URL/API | Cosmetic: UI decluttering |\n| `fields` (explore-level) | Excluded from an explore's available field pool. Not queryable. Can use `ALL_FIELDS*` with `-field` exclusions. | Structural: field genuinely inaccessible |\n| `fields` (join-level) | Restricts which fields from a joined view enter the explore. Include-list only. | Structural: field never enters the pool |\n| `fields_hidden_by_default: yes` | All view fields hidden unless individually opted in with `hidden: no` | Cosmetic: bulk hide |\n| `required_access_grants` | User-attribute-based restriction. True security mechanism. | Security: access controlled |\n\n## Classification → Malloy Treatment\n\nFor each hidden/excluded field, determine the **reason** and map to the correct Malloy treatment:\n\n| Classification | LookML Signal | Malloy Treatment |\n|---|---|---|\n| **Intermediate calculation** | `hidden: yes` + referenced by other fields via `${field}` | `# hidden` tag: keep accessible, hide from display |\n| **Join key / FK** | `hidden: yes` + used in `sql_on:` conditions | Keep public, no `#(doc)`: needed for joins |\n| **UI clutter** | `hidden: yes` + not referenced elsewhere | Assess: if truly unused, `internal:` candidate; if just verbose, `# hidden` |\n| **Explore-scoped exclusion** | Excluded via `fields` parameter | `internal:` candidate: field was structurally inaccessible |\n| **Bulk hidden** | `fields_hidden_by_default: yes` on view | Treat each field individually based on its role |\n| **Access-restricted** | `required_access_grants` | `private:` candidate: flag for user decision |\n| **Not hidden** | No visibility restriction | Public + `#(doc)` candidate |\n\n## Key Distinction\n\nLookML `hidden: yes` ≈ Malloy `# hidden` (cosmetic). LookML `fields` exclusion ≈ Malloy `internal:` (structural).\n\n**Do NOT map `hidden: yes` directly to `internal:`.** That over-restricts fields that may be needed as intermediate calculations or join keys.\n\n## Pattern: Restricted-field masking (`include { private: } + pick`)\n\nWhen a sensitive field should be *present in a redacted/bucketed form* rather than dropped, don't reach for an access modifier alone: modifiers hide or expose, they don't transform. Keep the raw column **`private:`** and derive a masked dimension from it in the source's immediate `extend {}`: a `private:` field is referenceable from the immediate extension, so the raw value stays out of the queryable surface while the mask is public. The mask must key on **data the model can see**, a row-level column or a source `parameter`, not on the viewer:\n\n```malloy\n##! experimental.access_modifiers\nsource: revenue is conn.table('…') include {\n  private: raw_amount              // raw stays out of the queryable surface…\n} extend {\n  dimension: amount is             // …but is referenceable here, in the immediate extension\n    pick null when is_confidential          // is_confidential is a ROW column, not the viewer\n    else raw_amount\n  // or bucket instead of null-out:\n  //   pick 'under 50k' when raw_amount < 50000\n  //   pick '50k–100k'  when raw_amount < 100000\n  //   else '100k+'\n}\n```\n\nGive the mask a **different name** from the private raw column (`amount` vs `raw_amount`), reusing the name is a redefinition. If the mask must carry the raw column's *exact* original name, that forces a `rename:`, which pushes you onto the `extend { rename }` path. That path composes with `include {}`, but only in one order (the `extend { rename: }` first, then `include {}` naming the post-rename field; see `skill:malloy-gotchas-modeling`), and you still have to move the raw column out of the way before the mask can take its name. Prefer a distinct mask name and keep the raw `private:` unless the exact original name is required.\n\n**This is NOT per-viewer access control.** LookML `required_access_grants` gates on the *viewing user's* attributes; Malloy models have no per-viewer context, so a model-layer `pick` can only redact based on row data or a parameter. To gate a field by *caller identity/role* (the real `required_access_grants` equivalent), use `#(authorize)` on the source, driven by trusted attributes in Malloy Publisher (see `skill:malloy-model` § Access Control). `#(authorize)` refuses a caller it does not admit with a 403; `#(access_filter)` is the row-scoping sibling. Masking and these gates are independent layers; use the mask for \"everyone sees a coarsened value,\" a gate for \"only some callers see the field at all.\"\n\n## Pattern: Long→wide custom-field pivot\n\nSee `build-derived-tables.md` → \"Long→wide entity-values pivot\" for turning an entity-attribute-value (EAV) custom-field table into wide columns with **filtered aggregates**, the right move when LookML modeled N per-attribute joins.\n\n## Process\n\n1. Read the Visibility Seeds notes captured during discovery\n2. For each field, apply the classification rules above\n3. Present the classified list to the user for confirmation before applying access modifiers"
     },
     {
       name: "malloy-lookml-review/discover",
@@ -324234,12 +324936,12 @@ Present coverage in this order:
     {
       name: "malloy-materialization",
       description: "Add and debug Malloy Persistence materializations in a package - persist an expensive source so queries read a pre-built table. Read this whenever the user wants to materialize a source, add a persist annotation, speed up a slow source, or asks why a persist source isn't building.",
-      body: "# Materialization (Malloy Persistence)\n\nMaterialize an expensive source once so queries read a **pre-built warehouse table** instead of recomputing it every time. You tag a source `#@ persist`, a materialization run builds it into a physical table, and queries against it are rewritten to read that table.\n\n> **The #1 gotcha, up front:** if a persist source isn't materializing, it is almost always one of two things - a `.malloy` file in the package missing the `##! experimental.persistence` flag (which aborts the *whole* package's build plan), or no build ever ran (a standalone Publisher does not build on publish - see **Building and refreshing**). Jump to **Debugging a no-op build**.\n\n## The recipe (get this right and it just works)\n\n1. **`##! experimental.persistence` on EVERY `.malloy` file in the package** - not only the file that declares the persist source. Either form enables it:\n   - `##! experimental.persistence`, or\n   - `##! experimental { access_modifiers, sql_functions, persistence }` (add `persistence` to the existing list).\n\n   **Why every file:** the build plan is computed by asking *every* `.malloy` file in the package for its persist sources, and that call **throws on any file whose model lacks the flag** (`Model must have ##! experimental.persistence`). One unflagged helper or import file, even one with no persist source of its own, aborts the whole package's build plan, so *every* persist source in the package drops out. This is the most common cause of a no-op build.\n\n2. **`#@ persist name=\"...\"` on a query-based source, with the name quoted:**\n   ```malloy\n   #@ persist name=\"my_dataset.my_table\"\n   source: my_rollup is some_source -> { group_by: ...; aggregate: ... }\n   ```\n   - **Only `query_source` and `sql_select` sources are persistable** - a source whose definition has a `-> { ... }` pipeline or a `conn.sql(\"...\")`. This **includes** one refined by a trailing `extend { ... }`. What is **not** persistable is a *plain* `extend` over a bare `conn.table(...)`; a `#@ persist` on such a source is **silently ignored** (its annotation is never read) - that one source just won't materialize, and the rest of the package still builds.\n   - **Quote the name.** `name=\"my_table\"` (or a path `name=\"dataset.table\"` / `name=\"project.dataset.table\"`) is required. A **bare** `name=my_table` **always fails the build/publish** with `persist annotation name must be quoted` (a raw-source scan that hard-stops); it never silently no-ops.\n   - `name=` is the target table name. In a standalone Publisher this **is** the physical table (rebuilt in place); a hosted (control-plane) deployment builds it under a content-addressed generation name. In both, the source's identity for reuse is a content address of its connection and canonical SQL (its `sourceEntityId`), so **republishing unchanged persist logic reuses the existing table** and changing the logic builds fresh.\n\n3. **Package persistence policy in `publisher.json`** (all optional):\n   ```jsonc\n   {\n     \"name\": \"my-package\",\n     \"materialization\": {\n       \"scope\": \"package\",  // default; \"version\" = each published version owns its own tables\n       \"freshness\": { \"window\": \"24h\", \"fallback\": \"live\" },\n       \"queryMetadata\": { \"team\": \"finance\" }  // tags the build's backend statements\n     }\n   }\n   ```\n   Enforced at publish (strict), on edits (strict), at load (warn, still serves), and by the scheduler (an offending package is skipped):\n   - **`scope`**: `package` (default; artifacts reused across published versions) or `version` (each artifact owned by one version). Package-level only; there is no per-source scope. A root-level `scope` is the deprecated home and still works, with a warning; declaring both homes with different values is rejected.\n   - **`materialization.freshness`** (`window` + `fallback` of `live`/`stale_ok`/`fail`) is the objective a **hosted control plane** enforces by refreshing the table to meet it (`fallback: \"live\"` serves live compute while stale/absent). A **standalone** Publisher does **not** act on `freshness` for refresh - see **Building and refreshing**.\n   - **`materialization.queryMetadata`** is a bag of string properties attached to every statement the build issues, for the backend's own cost attribution (Snowflake `QUERY_TAG`, BigQuery job labels, a leading SQL comment elsewhere). Overridable per source with `#@ persist queryMetadata.<name>=\"<value>\"`. Observability only: it never changes what gets built. See `docs/query-metadata.md`.\n   - **`materialization.schedule`** is a 5-field UTC cron (`min hour dom mon dow`; `L`/`W`/`#`/`?` rejected). It **requires `scope: \"version\"`** and is **mutually exclusive with `freshness`**. This is how a standalone Publisher refreshes on a cadence.\n\n4. **Reads vs writes.** The persist source can *read* any dataset the connection can read; the persist *target* (`name=`'s dataset) must be a dataset the connection can **write** (typically a scratch dataset).\n\n## Building and refreshing (standalone vs. hosted)\n\nA `#@ persist` tag declares *what* to materialize; it does not by itself build anything.\n\n- **Standalone Publisher:** publishing or loading a package only computes its build plan - **no table is built until a materialization run executes.** Trigger one explicitly (`malloy-pub materialize --package <pkg> --wait`, or the materialization API), or turn on the opt-in local scheduler (off unless `PUBLISHER_LOCAL_MATERIALIZATION_SCHEDULER` is set) to fire the package's `schedule` cron. Refresh is a re-run or that cron; `freshness` is not a refresh trigger here, so a freshness-only standalone package builds once and is not auto-refreshed.\n- **Hosted (control-plane) deployment:** the build runs automatically on publish, best-effort - a build failure does **not** fail the publish (which is why a broken persist can look like a silent no-op), and the control plane drives refresh to meet the `freshness` objective.\n\nEither way, a successful publish alone does not prove a table exists - confirm the build separately.\n\n## Serve-time routing is `query_source`-only (today)\n\nBoth persistable types *build* a table, but only a **`query_source`** (a `-> { ... }` pipeline) is rewritten to *read* it at query time. A raw **`sql_select`** (`conn.sql(\"...\")`, including `conn.sql(\"...\") extend { ... }`) builds its table and then the query path re-inlines its SQL, so the table is built and never read, and queries are no faster. If you have raw SQL you want served from a table, wrap it in a thin `query_source` and persist that:\n\n```malloy\nsource: x_raw is my_conn.sql(\"select ...\")\n#@ persist name=\"scratch_dataset.x\"\nsource: x is x_raw -> { select: * }\n```\n\n## Confirming it worked\n\nAfter a build runs, re-run one of the source's queries - a persisted `query_source` should return quickly, reading the pre-built table instead of recomputing the upstream. Your host also reports each persisted source as **ready** with its physical table name (a materialization run detail, CLI listing, or materialization view, depending on the host); if nothing is listed, either no build ran (standalone) or the build plan was empty - see **Debugging a no-op build**.\n\n## Debugging a no-op build\n\nSymptom: no table was built and the source still recomputes on every query. Check, in order:\n\n0. **Did a build actually run?** On a standalone Publisher, publish/load does **not** build - run `malloy-pub materialize` (or enable the scheduler). \"Publishes fine, no table\" is the *expected* standalone state, not a model bug. On a hosted deployment the build is automatic but best-effort, so a failure is silent - look for a `FAILED` run.\n1. **A `.malloy` file missing the persistence flag** (the most common real bug). Every model file's `##!` line needs `persistence`, including pure helper/import files with no persist source - one unflagged file aborts the whole package's build plan.\n2. **An unquoted persist name** - a bare `name=foo` **always** hard-stops the build/publish with `persist annotation name must be quoted`; use `name=\"foo\"`. (If you got *no* error at all, it isn't this.)\n3. **A `#@ persist` on a non-persistable source** - a bare `extend` over `conn.table(...)` is silently ignored, so *that* source won't materialize (the rest of the package is unaffected). Tag a `query_source` / `sql_select` instead.\n4. **A persisted raw `sql_select` that builds but is never read** - if the table exists yet queries are no faster, it's the serve-routing gap above; wrap the `sql_select` in a `query_source`.\n\n**Isolation test** - add a trivial, self-contained persist source in its own file and rebuild:\n```malloy\n##! experimental.persistence\nsource: smoke_raw is my_conn.table('some_dataset.some_table')\n#@ persist name=\"scratch_dataset.persist_smoke_test\"\nsource: persist_smoke is smoke_raw -> { aggregate: n is count() }\n```\n- If **even this** doesn't build (after a real materialization run), the whole package's plan is aborting - a sibling `.malloy` file is missing the flag. Fix rule 1 across the package.\n- If the smoke source **does** build but your real one doesn't, your real source is the problem - a non-persistable type (a bare `extend`), or its own file's flag.\n\nDelete the smoke file and drop its table afterward.\n\n## Persisting an `#(authorize)`-gated source\n\nA gated source **can** be persisted, but only on one tier and only in one shape, and the thing to be\ncareful about is not refused by anything - you have to decide it.\n\n- **`storage=` and `#@ preaggregate` always refuse a gated source**, with a 422 at build time naming the\n  source. (`#@ persist storage=<name>` is the tier that materializes into a separate registered storage\n  destination and serves from there, rather than building in the source's own connection; `#@ preaggregate`\n  stores a rollup Publisher derives from a measure you annotated with a grain, rather than a source you\n  wrote.) A rollup also groups *across* the gated column, so it could not be row-filtered afterwards even\n  in principle.\n- **A colocated `#@ persist` (no `storage=`) is admitted** when the gate is provably the entry point's\n  **own row filter**. It is refused when the gate is reached only through a join, inherited from a base\n  the compiler cannot attribute cleanly, or does not classify as a row filter at all. The gate is found\n  through the import -> rename -> `query_source` chain, so a gate the persisted source did not declare\n  itself still counts.\n\n**What to be wary of.** Persisting does not weaken the gate: it changes only where rows are read FROM, and\nthe gate still runs live on every query as that query's own `WHERE`, so filtered rows come back filtered.\nWhat freezes is the **column the gate filters on**. A row whose access decision changes - it changes\nowner, say - keeps being served under its OLD decision until the next rebuild. That is a stale *access\ndecision*, not merely stale data, and nothing raises an error.\n\n**None of this is needed for the gate to work.** It is enforced live on every query either way; what\nneeds a bound is how long a *stale* decision can survive. Of the three controls that look like that\nbound, only the first is:\n\n- **`materialization.freshness` `{ \"window\": \"24h\", \"fallback\": \"live\" }` is the bound.** The serve path\n  re-checks freshness per query, so once the artifact ages past the window it drops out of the serving set\n  and the query recomputes live, correctly filtered - whether or not a rebuild ever lands. Three details\n  decide whether you actually get that. **`fallback` must be `live`**: under `stale_ok` a stale artifact\n  keeps being served, which voids the bound, and window and fallback resolve *independently* per layer,\n  so a package-level `stale_ok` silently defeats a window you set on the source. That is a statement about\n  **layers**, which do not combine - not about siblings, below. Prefer the\n  **per-source** spelling `#@ persist name=\"...\" freshness.window=\"24h\" freshness.fallback=\"live\"` over\n  the package-wide `materialization.freshness` key: the gated source is what needs the bound, and setting\n  it package-wide forces every other persisted source to recompute once stale too. And **a\n  content-identical sibling shares the artifact, so it shares the window**: reuse is keyed on the\n  content-addressed `sourceEntityId`, which folds the connection and the SQL but *not* the source name, so\n  two persist sources whose bodies compute the same SQL resolve to one table carrying one freshness\n  policy. The tightest window any of them declares governs all of them - a sibling declaring nothing\n  cannot loosen yours, and yours pulls that sibling's reads off the table once it lapses. A sibling's\n  `stale_ok` cannot void your bound either: the fold keeps whichever fallback bounds staleness, so the\n  layer rule above does not carry over here. If two sources need genuinely different windows, give them\n  genuinely different SQL.\n\n  Both of those are properties of the **host** that assembles the manifest, not of the annotation. Where\n  the host does not fold, which sibling's policy reaches the wire is unspecified; and a host that folds at\n  manifest-assembly time typically applies it when a version's manifest is next published rather than\n  retroactively to manifests already distributed - so you can declare the window correctly and not have it\n  in force yet.\n- **A cron alone is not a bound.** A failed build or a stopped scheduler leaves the source serving its old\n  decisions indefinitely. `freshness` and `schedule` are mutually exclusive; for a gated source, take the\n  window.\n- **`refresh=\"incremental\"` does not bound revocation.** The delta only re-reads rows in\n  `[covered_through, frontier)`, so a row that changes owner *without its watermark advancing* is never\n  re-read - while the entry still reports an advancing `coveredThrough` and reads as healthy. Only a full\n  rebuild recomputes the gating column.\n\n**And the window only binds where the serving manifest carries it.** Freshness is enforced from fields a\ncontrol plane stamps onto the manifest it distributes; a Publisher that serves what it just built binds the\ntable with no `dataAsOf` and no window, and an entry carrying no window never ages out. So on a standalone\ndeployment the declared window is inert and the artifact serves until the next full rebuild - which leaves a\nrebuild cadence you actually verify as the only bound, and makes leaving a revocation-sensitive source\nunpersisted the safer call.\n\nWhen recommending `#@ persist` on a gated source, pair it with a freshness window and say out loud what\nstaleness the author is accepting. A gated source with neither a window nor a full-rebuild cadence has no\nbound on how long a revoked row keeps being served.\n\n## Gotchas\n\n- **Every `.malloy` file needs the persistence flag** - one unflagged file aborts the whole package's build plan. (A `#@ persist` on a *non*-persistable source, by contrast, is silently ignored and does not affect other sources.)\n- **A tag doesn't build** - a standalone Publisher materializes only on an explicit run or its scheduler; only a hosted control plane builds on publish.\n- **Serve-time routing is `query_source`-only** - a raw `sql_select` builds a table the query path doesn't read; wrap it in a `query_source`.\n- **Quote the name** - a bare `name=` always hard-stops the build.\n- **Republishing unchanged persist logic reuses the table** - reuse is keyed on the content-addressed `sourceEntityId`, not the `name=`.\n- **Removing a persist source (or a smoke test) does not drop its table** - physical-table cleanup is the caller's responsibility; drop it yourself.\n- **An `#(authorize)`-gated source freezes its gating column when persisted** - the gate still runs live, but a revoked row keeps being served under its old access decision until the next rebuild. `storage=` and `#@ preaggregate` refuse a gated source outright. See **Persisting an `#(authorize)`-gated source**."
+      body: "# Materialization (Malloy Persistence)\n\nMaterialize an expensive source once so queries read a **pre-built warehouse table** instead of recomputing it every time. You tag a source `#@ persist`, a materialization run builds it into a physical table, and queries against it are rewritten to read that table.\n\n> **The #1 gotcha, up front:** if a persist source isn't materializing, it is almost always one of two things - a `.malloy` file in the package missing the `##! experimental.persistence` flag (which aborts the *whole* package's build plan), or no build ever ran (a standalone Publisher does not build on publish - see **Building and refreshing**). Jump to **Debugging a no-op build**.\n\n## The recipe (get this right and it just works)\n\n1. **`##! experimental.persistence` on EVERY `.malloy` file in the package** - not only the file that declares the persist source. Either form enables it:\n   - `##! experimental.persistence`, or\n   - `##! experimental { access_modifiers, sql_functions, persistence }` (add `persistence` to the existing list).\n\n   **Why every file:** the build plan is computed by asking *every* `.malloy` file in the package for its persist sources, and that call **throws on any file whose model lacks the flag** (`Model must have ##! experimental.persistence`). One unflagged helper or import file, even one with no persist source of its own, aborts the whole package's build plan, so *every* persist source in the package drops out. This is the most common cause of a no-op build.\n\n2. **`#@ persist name=\"...\"` on a query-based source, with the name quoted:**\n   ```malloy\n   #@ persist name=\"my_dataset.my_table\"\n   source: my_rollup is some_source -> { group_by: ...; aggregate: ... }\n   ```\n   - **Only `query_source` and `sql_select` sources are persistable** - a source whose definition has a `-> { ... }` pipeline or a `conn.sql(\"...\")`. This **includes** one refined by a trailing `extend { ... }`. What is **not** persistable is a *plain* `extend` over a bare `conn.table(...)`; a `#@ persist` on such a source is **silently ignored** (its annotation is never read) - that one source just won't materialize, and the rest of the package still builds.\n   - **Quote the name.** `name=\"my_table\"` (or a path `name=\"dataset.table\"` / `name=\"project.dataset.table\"`) is required. A **bare** `name=my_table` **always fails the build/publish** with `persist annotation name must be quoted` (a raw-source scan that hard-stops); it never silently no-ops.\n   - `name=` is the target table name. In a standalone Publisher this **is** the physical table (rebuilt in place); a hosted (control-plane) deployment builds it under a content-addressed generation name. In both, the source's identity for reuse is a content address of its connection and canonical SQL (its `sourceEntityId`), so **republishing unchanged persist logic reuses the existing table** and changing the logic builds fresh.\n\n3. **Package persistence policy in `publisher.json`** (all optional):\n   ```jsonc\n   {\n     \"name\": \"my-package\",\n     \"materialization\": {\n       \"scope\": \"package\",  // default; \"version\" = each published version owns its own tables\n       \"freshness\": { \"window\": \"24h\", \"fallback\": \"live\" },\n       \"queryMetadata\": { \"team\": \"finance\" }  // tags the build's backend statements\n     }\n   }\n   ```\n   Enforced at publish (strict), on edits (strict), at load (warn, still serves), and by the scheduler (an offending package is skipped):\n   - **`scope`**: `package` (default; artifacts reused across published versions) or `version` (each artifact owned by one version). Package-level only; there is no per-source scope. A root-level `scope` is the deprecated home and still works, with a warning; declaring both homes with different values is rejected.\n   - **`materialization.freshness`** (`window` + `fallback` of `live`/`stale_ok`/`fail`) is the objective a **hosted control plane** enforces by refreshing the table to meet it (`fallback: \"live\"` serves live compute while stale/absent). A **standalone** Publisher does **not** act on `freshness` for refresh - see **Building and refreshing**.\n   - **`materialization.queryMetadata`** is a bag of string properties attached to every statement the build issues, for the backend's own cost attribution (Snowflake `QUERY_TAG`, BigQuery job labels, a leading SQL comment elsewhere). Overridable per source with `#@ persist queryMetadata.<name>=\"<value>\"`. Observability only: it never changes what gets built. See `docs/query-metadata.md`.\n   - **`materialization.schedule`** is a 5-field UTC cron (`min hour dom mon dow`; `L`/`W`/`#`/`?` rejected). It **requires `scope: \"version\"`** and is **mutually exclusive with `freshness`**. This is how a standalone Publisher refreshes on a cadence.\n\n4. **Reads vs writes.** The persist source can *read* any dataset the connection can read; the persist *target* (`name=`'s dataset) must be a dataset the connection can **write** (typically a scratch dataset).\n\n## Building and refreshing (standalone vs. hosted)\n\nA `#@ persist` tag declares *what* to materialize; it does not by itself build anything.\n\n- **Standalone Publisher:** publishing or loading a package only computes its build plan - **no table is built until a materialization run executes.** Trigger one explicitly (`malloy-pub materialize --package <pkg> --wait`, or the materialization API), or turn on the opt-in local scheduler (off unless `PUBLISHER_LOCAL_MATERIALIZATION_SCHEDULER` is set) to fire the package's `schedule` cron. Refresh is a re-run or that cron; `freshness` is not a refresh trigger here, so a freshness-only standalone package builds once and is not auto-refreshed.\n- **Hosted (control-plane) deployment:** the build runs automatically on publish, best-effort - a build failure does **not** fail the publish (which is why a broken persist can look like a silent no-op), and the control plane drives refresh to meet the `freshness` objective.\n\nEither way, a successful publish alone does not prove a table exists - confirm the build separately.\n\n## Serve-time routing is `query_source`-only (today)\n\nBoth persistable types *build* a table, but only a **`query_source`** (a `-> { ... }` pipeline) is rewritten to *read* it at query time. A raw **`sql_select`** (`conn.sql(\"...\")`, including `conn.sql(\"...\") extend { ... }`) builds its table and then the query path re-inlines its SQL, so the table is built and never read, and queries are no faster. If you have raw SQL you want served from a table, wrap it in a thin `query_source` and persist that:\n\n```malloy\nsource: x_raw is my_conn.sql(\"select ...\")\n#@ persist name=\"scratch_dataset.x\"\nsource: x is x_raw -> { select: * }\n```\n\n## Confirming it worked\n\nAfter a build runs, re-run one of the source's queries - a persisted `query_source` should return quickly, reading the pre-built table instead of recomputing the upstream. Your host also reports each persisted source as **ready** with its physical table name (a materialization run detail, CLI listing, or materialization view, depending on the host); if nothing is listed, either no build ran (standalone) or the build plan was empty - see **Debugging a no-op build**.\n\n## Debugging a no-op build\n\nSymptom: no table was built and the source still recomputes on every query. Check, in order:\n\n0. **Did a build actually run?** On a standalone Publisher, publish/load does **not** build - run `malloy-pub materialize` (or enable the scheduler). \"Publishes fine, no table\" is the *expected* standalone state, not a model bug. On a hosted deployment the build is automatic but best-effort, so a failure is silent - look for a `FAILED` run.\n1. **A `.malloy` file missing the persistence flag** (the most common real bug). Every model file's `##!` line needs `persistence`, including pure helper/import files with no persist source - one unflagged file aborts the whole package's build plan.\n2. **An unquoted persist name** - a bare `name=foo` **always** hard-stops the build/publish with `persist annotation name must be quoted`; use `name=\"foo\"`. (If you got *no* error at all, it isn't this.)\n3. **A `#@ persist` on a non-persistable source** - a bare `extend` over `conn.table(...)` is silently ignored, so *that* source won't materialize (the rest of the package is unaffected). Tag a `query_source` / `sql_select` instead.\n4. **A persisted raw `sql_select` that builds but is never read** - if the table exists yet queries are no faster, it's the serve-routing gap above; wrap the `sql_select` in a `query_source`.\n\n**Isolation test** - add a trivial, self-contained persist source in its own file and rebuild:\n```malloy\n##! experimental.persistence\nsource: smoke_raw is my_conn.table('some_dataset.some_table')\n#@ persist name=\"scratch_dataset.persist_smoke_test\"\nsource: persist_smoke is smoke_raw -> { aggregate: n is count() }\n```\n- If **even this** doesn't build (after a real materialization run), the whole package's plan is aborting - a sibling `.malloy` file is missing the flag. Fix rule 1 across the package.\n- If the smoke source **does** build but your real one doesn't, your real source is the problem - a non-persistable type (a bare `extend`), or its own file's flag.\n\nDelete the smoke file and drop its table afterward.\n\n## Persisting a `#(access_filter)`-gated source\n\nA gated source **can** be persisted, but only on one tier and only in one shape, and the thing to be\ncareful about is not refused by anything - you have to decide it.\n\n- **`storage=` and `#@ preaggregate` always refuse a gated source**, with a 422 at build time naming the\n  source. (`#@ persist storage=<name>` is the tier that materializes into a separate registered storage\n  destination and serves from there, rather than building in the source's own connection; `#@ preaggregate`\n  stores a rollup Publisher derives from a measure you annotated with a grain, rather than a source you\n  wrote.) A rollup also groups *across* the gated column, so it could not be row-filtered afterwards even\n  in principle.\n- **A colocated `#@ persist` (no `storage=`) is admitted** when the gate is provably the entry point's\n  **own row filter**. It is refused when the gate is reached only through a join, inherited from a base\n  the compiler cannot attribute cleanly, or does not classify as a row filter at all. The gate is found\n  through the import -> rename -> `query_source` chain, so a gate the persisted source did not declare\n  itself still counts.\n\n**What to be wary of.** Persisting does not weaken the gate: it changes only where rows are read FROM, and\nthe gate still runs live on every query as that query's own `WHERE`, so filtered rows come back filtered.\nWhat freezes is the **column the gate filters on**. A row whose access decision changes - it changes\nowner, say - keeps being served under its OLD decision until the next rebuild. That is a stale *access\ndecision*, not merely stale data, and nothing raises an error.\n\n**None of this is needed for the gate to work.** It is enforced live on every query either way; what\nneeds a bound is how long a *stale* decision can survive. Of the three controls that look like that\nbound, only the first is:\n\n- **`materialization.freshness` `{ \"window\": \"24h\", \"fallback\": \"live\" }` is the bound.** The serve path\n  re-checks freshness per query, so once the artifact ages past the window it drops out of the serving set\n  and the query recomputes live, correctly filtered - whether or not a rebuild ever lands. Three details\n  decide whether you actually get that. **`fallback` must be `live`**: under `stale_ok` a stale artifact\n  keeps being served, which voids the bound, and window and fallback resolve *independently* per layer,\n  so a package-level `stale_ok` silently defeats a window you set on the source. That is a statement about\n  **layers**, which do not combine - not about siblings, below. Prefer the\n  **per-source** spelling `#@ persist name=\"...\" freshness.window=\"24h\" freshness.fallback=\"live\"` over\n  the package-wide `materialization.freshness` key: the gated source is what needs the bound, and setting\n  it package-wide forces every other persisted source to recompute once stale too. And **a\n  content-identical sibling shares the artifact, so it shares the window**: reuse is keyed on the\n  content-addressed `sourceEntityId`, which folds the connection and the SQL but *not* the source name, so\n  two persist sources whose bodies compute the same SQL resolve to one table carrying one freshness\n  policy. The tightest window any of them declares governs all of them - a sibling declaring nothing\n  cannot loosen yours, and yours pulls that sibling's reads off the table once it lapses. A sibling's\n  `stale_ok` cannot void your bound either: the fold keeps whichever fallback bounds staleness, so the\n  layer rule above does not carry over here. If two sources need genuinely different windows, give them\n  genuinely different SQL.\n\n  Both of those are properties of the **host** that assembles the manifest, not of the annotation. Where\n  the host does not fold, which sibling's policy reaches the wire is unspecified; and a host that folds at\n  manifest-assembly time typically applies it when a version's manifest is next published rather than\n  retroactively to manifests already distributed - so you can declare the window correctly and not have it\n  in force yet.\n- **A cron alone is not a bound.** A failed build or a stopped scheduler leaves the source serving its old\n  decisions indefinitely. `freshness` and `schedule` are mutually exclusive; for a gated source, take the\n  window.\n- **`refresh=\"incremental\"` does not bound revocation.** The delta only re-reads rows in\n  `[covered_through, frontier)`, so a row that changes owner *without its watermark advancing* is never\n  re-read - while the entry still reports an advancing `coveredThrough` and reads as healthy. Only a full\n  rebuild recomputes the gating column.\n\n**And the window only binds where the serving manifest carries it.** Freshness is enforced from fields a\ncontrol plane stamps onto the manifest it distributes; a Publisher that serves what it just built binds the\ntable with no `dataAsOf` and no window, and an entry carrying no window never ages out. So on a standalone\ndeployment the declared window is inert and the artifact serves until the next full rebuild - which leaves a\nrebuild cadence you actually verify as the only bound, and makes leaving a revocation-sensitive source\nunpersisted the safer call.\n\nWhen recommending `#@ persist` on a gated source, pair it with a freshness window and say out loud what\nstaleness the author is accepting. A gated source with neither a window nor a full-rebuild cadence has no\nbound on how long a revoked row keeps being served.\n\n## Gotchas\n\n- **Every `.malloy` file needs the persistence flag** - one unflagged file aborts the whole package's build plan. (A `#@ persist` on a *non*-persistable source, by contrast, is silently ignored and does not affect other sources.)\n- **A tag doesn't build** - a standalone Publisher materializes only on an explicit run or its scheduler; only a hosted control plane builds on publish.\n- **Serve-time routing is `query_source`-only** - a raw `sql_select` builds a table the query path doesn't read; wrap it in a `query_source`.\n- **Quote the name** - a bare `name=` always hard-stops the build.\n- **Republishing unchanged persist logic reuses the table** - reuse is keyed on the content-addressed `sourceEntityId`, not the `name=`.\n- **Removing a persist source (or a smoke test) does not drop its table** - physical-table cleanup is the caller's responsibility; drop it yourself.\n- **A `#(access_filter)`-gated source freezes its gating column when persisted** - the gate still runs live, but a revoked row keeps being served under its old access decision until the next rebuild. `storage=` and `#@ preaggregate` refuse a gated source outright. See **Persisting a `#(access_filter)`-gated source**."
     },
     {
       name: "malloy-materialization-tuning",
       description: "Optimize a package's Malloy Persistence materializations for cost and performance using the malloy-pub CLI and the materialization history. Recommend what to persist, what to stop persisting, and how to schedule/scope it. Use when the user asks to make a package cheaper or faster, tune persistence, decide what to materialize, or review persist/schedule choices.",
-      body: "# Tuning materializations for cost and performance\n\nThis skill turns the signals the open-source Publisher already records (the materialization history, per-run timings, and which sources were built vs reused) into concrete, **recommendations-only** advice: which sources to persist, which to stop persisting, and how to schedule and scope them. It is the local counterpart to the platform's usage-driven optimization: the Publisher has the raw signals, and you read them with the `malloy-pub` CLI.\n\n> **Recommendations only. Never change a model, schedule, or scope without the user's explicit go-ahead.** Present the findings and the proposed edits, then apply them only when asked. Persisting the wrong source wastes storage and rebuild time; unpersisting a hot one makes queries slow. Let the user decide.\n\nAssumes the `malloy-pub` CLI is on PATH and points at the server (`--url` or `MALLOY_PUBLISHER_URL`, default `http://localhost:4000`). Substitute the real environment and package for `<env>` / `<pkg>`.\n\n## Step 1: Take inventory\n\nEstablish what the package persists today and how it is governed.\n\n- **Persist sources:** the sources annotated `#@ persist name=\"…\"` in the package's `.malloy` files. Read the models (or `get_context` the package) to list them.\n- **Schedule + scope:**\n\n  ```bash\n  malloy-pub schedule view --environment <env> --package <pkg>\n  ```\n\n  This prints the cron (or `none`, meaning publish / on-demand only), the persist **scope** (`package` = artifacts reused across versions; `version` = per published version), and whether a freshness policy is set. A control-plane-managed package (manifestLocation set) is refreshed by the control plane, not the standalone scheduler, so leave its cadence alone.\n\n## Step 2: Read the materialization history\n\nThe history is where cost lives. Each run records its trigger, timing, and how many sources were built vs reused.\n\n- **For one package** (newest first). A materialization is a run of one package's persist sources, so this is the listing; to review a whole environment, read each package in turn (`malloy-pub list package --environment <env>` names them):\n\n  ```bash\n  malloy-pub list materialization --environment <env> --package <pkg>\n  ```\n\n  Columns: ID, Status, **Trigger** (`SCHEDULER` vs `ON_DEMAND`), Started, Completed, Error.\n\n- **A single run's detail** (the cost signals):\n\n  ```bash\n  malloy-pub get materialization <id> --environment <env> --package <pkg>\n  ```\n\n  In the JSON, read:\n  - `metadata.durationMs`: how long the build took.\n  - `metadata.sourcesBuilt` vs `metadata.sourcesReused`: how much work each run actually did. A run that is nearly all _reused_ is cheap; one that is nearly all _built_ every time is where cost accumulates.\n  - `metadata.trigger`: `SCHEDULER` (a cron fired it) or `ON_DEMAND`.\n  - `manifest.entries[*]`: the persisted sources: `sourceName`, `physicalTableName`, `realization`.\n\nLook across several runs, not one: the pattern over the recent history (how often it rebuilds, how much it reuses, how long it takes) is the signal.\n\n## Step 3: Analyze and recommend\n\nWeigh rebuild cost against query benefit. Common findings:\n\n- **Persist candidate:** an expensive, frequently-queried source that is _not_ persisted (recomputed on every query). Recommend adding `#@ persist name=\"…\"`. Strongest when the source is a heavy aggregate/join reused by many queries and its inputs change slowly. If the source carries an `#(authorize)` gate, check which case it is first. A gate reached only through a `join_*`, or inherited from a base it cannot be attributed to, makes the colocated persist **refuse with a 422** - so do not recommend persisting it at all. Where the gate is provably the source's own row filter the persist is admitted, and then only recommend it alongside a freshness window (`freshness.fallback=\"live\"`): the gating column freezes at build time, so without one a revoked row can be served under its old access decision indefinitely (see `skill:malloy-materialization`, which also covers where that window does and does not bind).\n- **Removal candidate:** a persisted source that is cheap to compute, rarely queried, or rebuilt far more often than it is read. Recommend dropping the `#@ persist` annotation (and its table): the storage + rebuild cost is not buying anything.\n- **Cadence mismatch:** a `SCHEDULER` cadence out of step with how fast the data changes or how long a build takes. If most scheduled runs are all-reused (nothing changed), the cron is too frequent, so loosen it. If queries routinely read stale data, tighten it. If the build's `durationMs` approaches the interval, the cadence is too aggressive.\n- **Scope mismatch:** `scope: version` re-materializes per published version (right when versions must be isolated, e.g. a schedule); `scope: package` reuses one lineage across versions (cheaper when versions can share). A schedule _requires_ `version`. If a package carries a schedule it does not need, clearing the schedule frees it to use the cheaper package scope.\n\nFrame each recommendation with the evidence from Step 2 (the run IDs, timings, built/reused counts) so the user can judge it.\n\n## Step 4: Apply (only once approved)\n\n- **Add a persist source:** add the `#@ persist` annotation in the `.malloy` file (use the modeling workflow to validate and reload), then rebuild so it is materialized:\n\n  ```bash\n  malloy-pub materialize --environment <env> --package <pkg> --wait\n  ```\n\n- **Remove a persist source:** delete the `#@ persist` annotation, then drop the old run's tables **before** rebuilding what remains:\n\n  ```bash\n  malloy-pub delete materialization <id> --environment <env> --package <pkg> --drop-tables\n  malloy-pub materialize --environment <env> --package <pkg> --wait\n  ```\n\n  > `--drop-tables` drops **every** physical table in that run's manifest, not just the removed source's: auto-run assigns stable table names and carries unchanged sources forward, so an old run's manifest names tables a newer manifest still serves. Do the drop **first, then rebuild**: `materialize --wait` re-creates every source that is still persisted, ending in the desired state. Dropping a run whose tables the current serving manifest depends on, without an immediate rebuild, breaks queries (`Table ... does not exist`).\n\n- **Change the schedule / cadence:**\n\n  ```bash\n  malloy-pub schedule set \"0 6 * * *\" --environment <env> --package <pkg>   # 5-field UTC cron\n  malloy-pub schedule clear --environment <env> --package <pkg>\n  ```\n\n  `set` also sets `scope: version` (a schedule requires it); the server rejects an invalid cron or an illegal scope/freshness combination, so a rejection means the change was unsafe.\n\n- **Change the scope:** `scope` is declared in the package's `publisher.json` under `materialization` (`\"scope\": \"package\"` or `\"version\"`; the root-level form is deprecated but still read). Edit it there, then reload/republish the package. Remember a schedule pins scope to `version`, so clear the schedule first if moving to `package`.\n\nAfter applying, re-run Step 2 on the next few builds to confirm the change did what you predicted (more reuse, shorter builds, or a table that is actually read).\n\n## What this skill does not do\n\n- It does not decide for the user or apply changes silently; every edit needs an explicit go-ahead.\n- It cannot see per-query read counts (the open-source Publisher records build history, not query-level table usage), so \"rarely queried\" is a judgment from the model and the user's knowledge, not a measured metric. Say so when it matters."
+      body: "# Tuning materializations for cost and performance\n\nThis skill turns the signals the open-source Publisher already records (the materialization history, per-run timings, and which sources were built vs reused) into concrete, **recommendations-only** advice: which sources to persist, which to stop persisting, and how to schedule and scope them. It is the local counterpart to the platform's usage-driven optimization: the Publisher has the raw signals, and you read them with the `malloy-pub` CLI.\n\n> **Recommendations only. Never change a model, schedule, or scope without the user's explicit go-ahead.** Present the findings and the proposed edits, then apply them only when asked. Persisting the wrong source wastes storage and rebuild time; unpersisting a hot one makes queries slow. Let the user decide.\n\nAssumes the `malloy-pub` CLI is on PATH and points at the server (`--url` or `MALLOY_PUBLISHER_URL`, default `http://localhost:4000`). Substitute the real environment and package for `<env>` / `<pkg>`.\n\n## Step 1: Take inventory\n\nEstablish what the package persists today and how it is governed.\n\n- **Persist sources:** the sources annotated `#@ persist name=\"…\"` in the package's `.malloy` files. Read the models (or `get_context` the package) to list them.\n- **Schedule + scope:**\n\n  ```bash\n  malloy-pub schedule view --environment <env> --package <pkg>\n  ```\n\n  This prints the cron (or `none`, meaning publish / on-demand only), the persist **scope** (`package` = artifacts reused across versions; `version` = per published version), and whether a freshness policy is set. A control-plane-managed package (manifestLocation set) is refreshed by the control plane, not the standalone scheduler, so leave its cadence alone.\n\n## Step 2: Read the materialization history\n\nThe history is where cost lives. Each run records its trigger, timing, and how many sources were built vs reused.\n\n- **For one package** (newest first). A materialization is a run of one package's persist sources, so this is the listing; to review a whole environment, read each package in turn (`malloy-pub list package --environment <env>` names them):\n\n  ```bash\n  malloy-pub list materialization --environment <env> --package <pkg>\n  ```\n\n  Columns: ID, Status, **Trigger** (`SCHEDULER` vs `ON_DEMAND`), Started, Completed, Error.\n\n- **A single run's detail** (the cost signals):\n\n  ```bash\n  malloy-pub get materialization <id> --environment <env> --package <pkg>\n  ```\n\n  In the JSON, read:\n  - `metadata.durationMs`: how long the build took.\n  - `metadata.sourcesBuilt` vs `metadata.sourcesReused`: how much work each run actually did. A run that is nearly all _reused_ is cheap; one that is nearly all _built_ every time is where cost accumulates.\n  - `metadata.trigger`: `SCHEDULER` (a cron fired it) or `ON_DEMAND`.\n  - `manifest.entries[*]`: the persisted sources: `sourceName`, `physicalTableName`, `realization`.\n\nLook across several runs, not one: the pattern over the recent history (how often it rebuilds, how much it reuses, how long it takes) is the signal.\n\n## Step 3: Analyze and recommend\n\nWeigh rebuild cost against query benefit. Common findings:\n\n- **Persist candidate:** an expensive, frequently-queried source that is _not_ persisted (recomputed on every query). Recommend adding `#@ persist name=\"…\"`. Strongest when the source is a heavy aggregate/join reused by many queries and its inputs change slowly. If the source carries a `#(access_filter)` gate, check which case it is first. A gate reached only through a `join_*`, or inherited from a base it cannot be attributed to, makes the colocated persist **refuse with a 422** - so do not recommend persisting it at all. Where the gate is provably the source's own row filter the persist is admitted, and then only recommend it alongside a freshness window (`freshness.fallback=\"live\"`): the gating column freezes at build time, so without one a revoked row can be served under its old access decision indefinitely (see `skill:malloy-materialization`, which also covers where that window does and does not bind).\n- **Removal candidate:** a persisted source that is cheap to compute, rarely queried, or rebuilt far more often than it is read. Recommend dropping the `#@ persist` annotation (and its table): the storage + rebuild cost is not buying anything.\n- **Cadence mismatch:** a `SCHEDULER` cadence out of step with how fast the data changes or how long a build takes. If most scheduled runs are all-reused (nothing changed), the cron is too frequent, so loosen it. If queries routinely read stale data, tighten it. If the build's `durationMs` approaches the interval, the cadence is too aggressive.\n- **Scope mismatch:** `scope: version` re-materializes per published version (right when versions must be isolated, e.g. a schedule); `scope: package` reuses one lineage across versions (cheaper when versions can share). A schedule _requires_ `version`. If a package carries a schedule it does not need, clearing the schedule frees it to use the cheaper package scope.\n\nFrame each recommendation with the evidence from Step 2 (the run IDs, timings, built/reused counts) so the user can judge it.\n\n## Step 4: Apply (only once approved)\n\n- **Add a persist source:** add the `#@ persist` annotation in the `.malloy` file (use the modeling workflow to validate and reload), then rebuild so it is materialized:\n\n  ```bash\n  malloy-pub materialize --environment <env> --package <pkg> --wait\n  ```\n\n- **Remove a persist source:** delete the `#@ persist` annotation, then drop the old run's tables **before** rebuilding what remains:\n\n  ```bash\n  malloy-pub delete materialization <id> --environment <env> --package <pkg> --drop-tables\n  malloy-pub materialize --environment <env> --package <pkg> --wait\n  ```\n\n  > `--drop-tables` drops **every** physical table in that run's manifest, not just the removed source's: auto-run assigns stable table names and carries unchanged sources forward, so an old run's manifest names tables a newer manifest still serves. Do the drop **first, then rebuild**: `materialize --wait` re-creates every source that is still persisted, ending in the desired state. Dropping a run whose tables the current serving manifest depends on, without an immediate rebuild, breaks queries (`Table ... does not exist`).\n\n- **Change the schedule / cadence:**\n\n  ```bash\n  malloy-pub schedule set \"0 6 * * *\" --environment <env> --package <pkg>   # 5-field UTC cron\n  malloy-pub schedule clear --environment <env> --package <pkg>\n  ```\n\n  `set` also sets `scope: version` (a schedule requires it); the server rejects an invalid cron or an illegal scope/freshness combination, so a rejection means the change was unsafe.\n\n- **Change the scope:** `scope` is declared in the package's `publisher.json` under `materialization` (`\"scope\": \"package\"` or `\"version\"`; the root-level form is deprecated but still read). Edit it there, then reload/republish the package. Remember a schedule pins scope to `version`, so clear the schedule first if moving to `package`.\n\nAfter applying, re-run Step 2 on the next few builds to confirm the change did what you predicted (more reuse, shorter builds, or a table that is actually read).\n\n## What this skill does not do\n\n- It does not decide for the user or apply changes silently; every edit needs an explicit go-ahead.\n- It cannot see per-query read counts (the open-source Publisher records build history, not query-level table usage), so \"rarely queried\" is a judgment from the model and the user's knowledge, not a measured metric. Say so when it matters."
     },
     {
       name: "malloy-model",
@@ -324461,7 +325163,7 @@ A given is **declared bare** but **referenced with a \`$\` sigil** in expression
 - **Givens don't auto-inject a \`where:\`.** Unlike \`#(filter)\`, you write the filter expression that references the given yourself (e.g. \`where: dimension ~ $given_name\`).
 - **Not every filter maps cleanly.** A filter with no neutral match-all literal default - e.g. a scalar date/number range like \`> @2020-01-01\` - is not a good \`given:\`; keep those on \`#(filter)\`. Two more cases keep using \`#(filter)\`: mandatory scoping filters (\`required\`) and system-injected row-level filters (\`implicit\`), both below.
 
-Givens are also the substrate for access control - see "Access Control: Source Gating with \`#(authorize)\`" below.
+Givens are also the substrate for access control - see "Access Control: \`#(authorize)\` and \`#(access_filter)\`" below.
 
 ## Legacy: Parameterizable Filters with \`#(filter)\`
 
@@ -324532,38 +325234,72 @@ Publisher formats values based on the dimension's data type, \`string\` → \`'v
 
 Pass \`bypass_filters=true\` (REST) or \`bypassFilters: true\` (POST body) to skip filter injection entirely. Use sparingly, required-filter governance only works if bypass is restricted to trusted callers.
 
-## Access Control: Source Gating with \`#(authorize)\`
+## Access Control: \`#(authorize)\` and \`#(access_filter)\`
+
+Gate query access to a source over declared \`given:\` values (\`given:\` is Malloy's native runtime-parameter mechanism, the going-forward replacement for \`#(filter)\`). **Two annotations, one question each, and the name tells you which:**
+
+| Annotation | The question | Body it takes | A denial is |
+| --- | --- | --- | --- |
+| \`#(authorize)\` | may this caller reach this source at all? | \`'literal' <op> $GIVEN\`, plus the \`true\`/\`false\` sentinels | **403** |
+| \`#(access_filter)\` | which rows may they see, once they may? | \`field_path <op> $GIVEN\` | **200**, with their rows |
 
-Gate query access to a source with \`#(authorize)\` over declared \`given:\` values (\`given:\` is Malloy's native runtime-parameter mechanism, the going-forward replacement for \`#(filter)\`). A gate is an \`#(authorize)\` annotation on its own line directly above the \`source:\` line, carrying an **unquoted, ordinary Malloy boolean expression**; Publisher grafts that expression onto the source as a row filter before running the query, so a caller it admits nowhere gets **200 with zero rows**, not a 403. A **403** means only that the gate could not be attached at all. A source with no \`#(authorize)\` annotation of its own or inherited is unrestricted.
+Either is an annotation on its own line directly above the \`source:\` line, carrying a **narrow grammar publisher parses itself, not an arbitrary Malloy expression**: one or more terms joined only by \`and\`, with \`<op>\` fixed by the given's declared arity (\`in\` for a list, \`=\` for a scalar).
+
+**Nothing is inferred from the body.** The annotation you write declares which question you are answering, and a body that does not fit is refused at load naming the other annotation. A source with no annotation of either kind, own or inherited, is unrestricted.
+
+The lock is DECIDED, before the caller's query compiles: a caller it does not admit gets a 403, never a row count or a \`NULL\` aggregate over data they were refused. The filter is GRAFTED onto the query as a \`where:\`, so a caller it matches nowhere gets a 200 with an empty result. The lock runs first; a caller it refuses never reaches the filter. A 403 also covers either gate failing to apply at all (a field the entry point dropped, a given nobody supplied).
 
 \`\`\`malloy
 ##! experimental.givens
 
 given:
   ROLE :: string
+  ORG_IDS :: string[]
 
-#(authorize) $ROLE = 'analyst'
+#(authorize) 'analyst' = $ROLE
+#(access_filter) org_id in $ORG_IDS
 source: orders is duckdb.table('orders.parquet') extend {
   measure: order_count is count()
 }
 \`\`\`
 
-- **Any legal Malloy boolean expression is a legal gate**, over givens, row fields (including through a join), literals, functions and operators: \`org_id in $GROUPS\`, \`upper(region) = $REGION\`, \`\` \`cost center\` in $GROUPS \`\`, \`(org_id in $GROUPS or region = $REGION) and amount > $AMOUNTMIN\`. There is no allowlist of accepted comparison shapes.
-- **A source may declare at most one \`#(authorize)\` annotation.** Declaring a second on the same source fails the load naming both. Spell OR inside the expression rather than stacking annotations. For a condition too long to read on one line, point the gate at an ordinary boolean dimension instead: \`#(authorize) authorized\` above the source, over \`dimension: authorized is org_id in $GROUPS\` inside it; validation follows the reference through.
-- **\`#(authorize)\` only gates from the \`source:\` line.** The same annotation on a \`dimension:\`/\`measure:\`/\`join_*:\`/\`view:\` line, or on a top-level \`query:\`, is refused at load naming the position rather than silently protecting nothing.
-- **Every given the gate references must be declared on the entry model's own surface, and must carry no default.** A given the model cannot resolve is refused at load. So is a referenced given declared *with* a default: a caller who supplies nothing would get that default and be admitted or excluded by a value the gate's own line never shows, so it is refused rather than reasoned about case by case. This follows a bare reference through, so a given reached one hop away via \`#(authorize) authorized\` is checked too.
-- **Two shapes load with a warning rather than a refusal.** A gate that references **no given** at all is a fixed predicate, not an access rule keyed on the caller. A gate that **negates a membership test** (\`not (org_id in $GROUPS)\`) matches every row for an *empty* given instead of none. Both warn and still load, so read the load warnings.
-- **Entry point only: not joined, but inherited through \`extend\`.** The gate applies to the source a query enters through. A gate on a source reached only via \`join_*\` **never fires**, at any depth, so anything ungated that joins a locked base hands the base's rows to every caller. A source that \`extend\`s a locked base and declares no gate of its own **does** carry the base's gate; declaring its own annotation replaces it. A source derived from a locked base via a query (\`source: z is locked -> { … }\`) instead **always carries the base's gate in addition to its own**: the derivation recurses into the base unconditionally, so an own gate does not replace it, and the two combine as separate AND'd entries. Pair a locked base (\`#(authorize) false\`) with curated extension sources, using access modifiers (\`include { public: …, private: * }\`), so an extension re-exposes only a curated column surface, and keep sensitive sources out of ungated joins.
-- **A derivation that drops a column the gate reads fails CLOSED.** \`extend { except: org_id }\`, or an \`accept:\` that omits it, leaves the grafted filter unable to compile, so the request is denied rather than served ungated. The one hole to know: dropping the gated column and then \`rename:\`-ing a *different* column onto that exact name grafts successfully and binds the gate to the wrong column. Narrow, but real, so don't recycle a gated column's name.
-- Comparing a row field to an array-typed given with \`=\`/\`!=\` (\`org_id = $GROUPS\`) compiles and loads cleanly, then fails at query execution with a warehouse conversion error. Use \`in\` for an array-typed given, not \`=\`.
-- **The quoted-string and file-level forms are refused at load and no longer exist.** \`#(authorize) "<expr>"\` on the \`source:\` line, in either quote (\`'...'\` is refused the same way), a file-level \`##(authorize) "<expr>"\` applying to every source in the file, and the earlier \`internal dimension: authorized is <expr>\` form are all retired; the load names the rewrite. Every \`.malloy\` file in a package compiles at load and any failure aborts the package, so a retired-form gate anywhere in the package is refused. Only a declaring file *outside* the package escapes that: it loads and denies every request instead, with no compile-time hint. See your deployment's reference documentation.
+- **Nothing outside the two term shapes above parses.** No \`or\`, \`not\`, \`!=\`, \`<\`/\`>\`/\`<=\`/\`>=\`, function calls, bare field/boolean references, or a literal on the right of a row-level term. \`org_id in $GROUPS\` and \`region = $REGION and org_id in $GROUPS\` are legal; \`upper(region) = $REGION\`, \`(org_id in $GROUPS or region = $REGION)\`, and a bare \`#(access_filter) authorized\` are all refused at load with a named cause (see your deployment's reference documentation for the full list).
+- **Writing a term on the wrong annotation is refused, both ways.** \`#(authorize) org_id in $GROUPS\` is refused naming \`#(access_filter)\`; \`#(access_filter) 'finance' in $GROUPS\` is refused naming \`#(authorize)\`. The second matters: a constant predicate grafted as a row filter would serve a refused caller 200 with zero rows, which is the answer the lock exists to replace.
+- **A source may declare more than one note on a route: repeats AND together.** \`#(access_filter) region = $REGION\` stacked with a second \`#(access_filter) org_id in $GROUPS\` both apply, and a caller must satisfy every term across every note. \`or\` is still refused wherever it appears, so there is no way to spell "admit if either" inside one gate or across a source's gates; use two extension sources instead, one per admitted population (see the admin pattern below).
+- **Two exceptions to "every term references a given", and both live on the lock.** \`#(authorize) false\` is a deny-all: that is how you lock a base. \`#(authorize) true\` is an admit-all, and it is what an extension of a locked base needs in order to be open: a source declaring no gate of its own **inherits** its ancestor's, so leaving the annotation off an extension of a \`false\` base inherits the lock rather than lifting it. Neither sentinel is legal on \`#(access_filter)\`. \`false\` may not share a source with another note at all; \`true\` may not share the lock route with one, but is live beside an \`#(access_filter)\` (\`#(authorize) true\` with \`#(access_filter) org_id in $GROUPS\` re-opens a locked base while still scoping the rows). Neither is a term: \`true and org_id in $GROUPS\` is read as an ordinary two-term body whose first term is malformed.
+- **Inheritance is per route.** Both inherit through \`extend\` the same way, own wins over ancestor on that route only, so a source can be "own" for one and "inherited" for the other. The API reports them separately, each under the field named for its own annotation: \`Source.authorize\` and \`Source.accessFilter\`.
+- **Generate the admin escape hatch as another extension over the locked base, never as a bypass.** When a model needs an ordinary population plus a wider one, add a second extension whose rule is a lock on the caller:
+
+\`\`\`malloy
+given:
+  ORG_IDS :: string[]
+  GROUPS  :: string[]
+
+#(authorize) false
+source: orders_base is duckdb.table('orders.parquet') extend {}
+
+#(authorize) true
+#(access_filter) org_id in $ORG_IDS
+source: orders is orders_base extend {}
+
+#(authorize) 'admin' in $GROUPS
+source: orders_admin is orders_base extend {}
+\`\`\`
+
+  Each extension replaces the base's \`false\` on the lock route with its own rule. \`orders\` is open to everyone and scoped per row; \`orders_admin\` is locked to the admin group and, carrying no filter, serves every row to whoever passes. This is the shape to generate whenever an author wants a role to see everything: another extension source, not a flag that skips the gate.
+- **Both only gate from the \`source:\` line.** The same annotation on a \`dimension:\`/\`measure:\`/\`join_*:\`/\`view:\` line, or on a top-level \`query:\`, is refused at load naming the position rather than silently protecting nothing.
+- **Every given the gate references must be declared on the entry model's own surface, and must carry no default.** A given the model cannot resolve is refused at load. So is a referenced given declared *with* a default: a caller who supplies nothing would get that default and be admitted or excluded by a value the gate's own line never shows, so it is refused rather than reasoned about case by case.
+- **A scalar/array mismatch between the operator and the given's declared type is a load-time refusal**, not a request-time warehouse error: \`org_id in $GROUPS\` requires \`GROUPS\` to be array-typed, \`region = $REGION\` requires \`REGION\` scalar. Negation is likewise refused outright, so there is no empty-given inversion surprise to warn about.
+- **Entry point only: not joined, but inherited through \`extend\`.** The gate applies to the source a query enters through. A gate on a source reached only via \`join_*\` **never fires**, at any depth, so anything ungated that joins a locked base hands the base's rows to every caller. A source that \`extend\`s a locked base and declares no gate of its own **does** carry the base's gate; declaring its own annotation replaces it. A source derived from a locked base via a query (\`source: z is locked -> { … }\`) instead **always carries the base's gate in addition to its own**: the derivation recurses into the base unconditionally, so an own gate does not replace it, and the two combine as separate AND'd entries. Pair a locked base with curated extension sources, using access modifiers (\`include { public: …, private: * }\`), so an extension re-exposes only a curated column surface, and keep sensitive sources out of ungated joins.
+- **A derivation that drops a column the gate reads fails CLOSED.** \`extend { except: org_id }\`, or an \`accept:\` that omits it, leaves the grafted filter unable to compile, so the request is denied rather than served ungated. The one hole to know: dropping the gated column and then \`rename:\`-ing a *different* column onto that exact name grafts successfully and binds the gate to the wrong column. Narrow, but real, so don't recycle a gated column's name. If a derivation's own projection needs to drop the column a row-level term would read, use a source-level term (\`'literal' in/= $GIVEN\`) instead, since it never depends on any projected column.
+- **The quoted-string and file-level forms are refused at load and no longer exist.** A quoted expression on the \`source:\` line, in either quote, a file-level \`##(…) "<expr>"\` applying to every source in the file, and the earlier \`internal dimension: authorized is <expr>\` form are all retired; the load names the rewrite. Every \`.malloy\` file in a package compiles at load and any failure aborts the package, so a retired-form gate anywhere in the package is refused. Only a declaring file *outside* the package escapes that: it loads and denies every request instead, with no compile-time hint. See your deployment's reference documentation.
 - **A gated source can be persisted, but the gating column freezes.** \`storage=\` and \`#@ preaggregate\` refuse a gated source outright; a colocated \`#@ persist\` is admitted when the gate is provably the entry point's own row filter. The gate still runs live on every query, so rows come back filtered - but the column it filters ON is frozen at build time, so a row whose access decision changes keeps being served under the old decision until the next rebuild. Pair \`#@ persist\` on a gated source with a freshness window (\`fallback="live"\`), which is the only control that bounds that - and read \`skill:malloy-materialization\` for where that window binds, because on a standalone Publisher it does not.
 
-> **Trust caveat.** Givens are **caller-asserted**, anyone who can reach the query API can claim a favorable given, e.g. \`{"ROLE":"admin"}\`. \`#(authorize)\` is only a real boundary when it sits behind a trusted tier that sets givens from its own verified context, never directly from an untrusted caller. It is not, on its own, end-user authentication.
+> **Trust caveat.** Givens are **caller-asserted**, anyone who can reach the query API can claim a favorable given, e.g. \`{"ROLE":"admin"}\`. Neither annotation is a real boundary unless it sits behind a trusted tier that sets givens from its own verified context, never directly from an untrusted caller. Neither is, on its own, end-user authentication.
 >
-> **Forward direction.** Givens are how access control is built here, and the planned next step is **identity-bound ("secure") givens** - reserved values a trusted tier populates from a verified token or proxy header, which the caller cannot override - turning \`#(authorize)\` into a standalone boundary. Model access on \`given:\` + \`#(authorize)\` now; it is the surface that carries forward.
+> **Forward direction.** Givens are how access control is built here, and the planned next step is **identity-bound ("secure") givens** - reserved values a trusted tier populates from a verified token or proxy header, which the caller cannot override - turning these gates into a standalone boundary. Model access on \`given:\` + these two annotations now; it is the surface that carries forward.
 
-Full syntax, inheritance rules, validation, and the error contract are covered in your deployment's \`#(authorize)\` reference documentation.
+Full syntax, inheritance rules, validation, and the error contract are covered in your deployment's authorize reference documentation.
 
 ## Join Syntax
 
@@ -325192,7 +325928,7 @@ source: first_touch is conn.table('events') -> {
     {
       name: "malloy-modeling",
       description: "Build semantic models with Malloy for the Malloy Publisher. Read this skill whenever the user asks about modeling data or specifically mentions Malloy.",
-      body: "# STOP - READ BEFORE WRITING ANY MALLOY CODE\n\n> **AI AGENTS: You MUST review this file before writing Malloy code.** Cross-skill references below use logical `skill:` names; load the referenced skill before acting. Before writing code, also read the gotcha skills: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering`.\n\n## Pre-Flight Checklist\n\n1. **Discover first**: ground yourself before writing ANY code, with the tool that matches what you are modelling.\n   - Modelling data **already in a package**: `get_context` returns that package's sources, views, and fields (with their docs).\n   - Modelling **a database with no package yet**: `get_context` has nothing to return, so use `search_database_schema` instead. It walks the connection's schemas and tables, ranks them against a plain-English description, and gives you each table's columns plus the `source:` line to start from. Take those names verbatim into step 5.\n   Never guess field names either way.\n2. **Search docs proactively**: call `search_malloy_docs` BEFORE writing unfamiliar patterns (window functions, query-based sources, pipelines). Don't guess. Malloy syntax is specific and SQL intuition is often wrong.\n3. **Use `skill:malloy-patterns`** to discover available doc topics (YoY, cohorts, rendering, window functions).\n4. **Check diagnostics** after writing: fix the FIRST error first, errors cascade.\n5. **Read the gotcha skills**: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering` prevent the most common mistakes.\n\n**Quick syntax reminders:**\n1. **Backtick reserved words:** `` `Date` ``, `` `Hour` ``, `` `Timestamp` ``, `` `Type` ``, `` `number` ``, `` `source` ``\n2. **Use `having:` for aggregate filters**: not `where:` on measures\n3. **Alias joined fields in `group_by`** if using them in `order_by`\n4. **`count()` counts rows; `count(x)` counts distinct values of `x`**: `count(distinct x)` is deprecated, write `count(x)`\n5. **One tag per line**: `# label=\"Revenue\"` and `# currency` on separate lines\n6. **No fixed scale on measures**: use `# currency` not `# currency=usd0m`\n7. **Cast strings for aggregates:** `avg(score::number)` not `avg(score)`\n8. **Boolean columns:** use `= true` not `= 'true'` (no quotes!)\n9. **Read data files in place:** `.csv`, `.parquet`, `.json`, `.ndjson`, and `.xlsx` all work as-is through `duckdb.table('data/file.ext')`. Never convert a file to another format first, and never read one with python or jq to \"have a look\" first: query it. For `.xlsx`, check the row count before trusting it: a workbook with a title row or a blank spacer reads short and reports no error. (Per-format quirks: `skill:malloy-gotchas-modeling`)\n\n## Planning and `modeling-notes.md`\n\nIf the IDE has a native plan mode, use it for the high-level approach: do data exploration during planning, then present a concrete plan for user approval before writing any files.\n\n`modeling-notes.md` is an expected output of the workflow, not an optional extra. Start it at step 2 (Propose Scope) and grow it as you work: it persists alongside the model, and its value is as the thing the user argues with at step 3, before source files exist; written after the build it can only document decisions already baked in. Record findings and problems as they are found during discovery (`skill:malloy-discover`), and every unconfirmed decision as an open item. Only when there is no writable workspace do the notes live in the conversation instead.\n\nKeep it compact, with these sections:\n\n```markdown\n# Modeling notes - <package>\n## Scope           what was confirmed, what the model is FOR, skip list with reasons\n## Grain and keys  proven by query, not by column name\n## Coverage        coverage cliffs; columns excluded for nullity\n## Decisions       each with its evidence\n## Open decisions  ASSUMPTIONS, NOT CONFIRMED: every threshold or definition the user\n                   has not settled, one entry each, mirrored by a hedge in its #(doc)\n## Validation      reconciliation checks performed, and their results\n```\n\n## 8-Step Modeling Workflow\n\nThe agent orchestrates all steps. Steps marked **(user)** pause for input. Each step has a dedicated skill with full instructions. Read each step's skill **before starting that step**, including the decision skills for steps 1–4 (`skill:malloy-discover`, `skill:malloy-scope`, `skill:malloy-define`). They govern what the model says; skipping them to reach the build skills is how unreviewed business logic ships.\n\n**A field is not complete until it has its definition, `#(doc)` tag, and rendering tags, and any threshold or business convention in it is user-confirmed, distribution-derived, or explicitly flagged in its `#(doc)`** (see `skill:malloy-document` § Mark conventions as conventions). Documentation is part of defining a field, not a separate activity. Read `skill:malloy-document` for full documentation standards (doc string writing, tag ordering).\n\n```\nDISCOVER → SCOPE → SOURCES → DEFINITIONS → BUILD BASE → BUILD JOINED → REVIEW → CURATE\n (silent)  (user)   (user)      (user)       (agent)      (agent)      (user)   (user)\n```\n\n| Step | Skill | What Happens |\n|------|-------|-------------|\n| 1. Discover | `skill:malloy-discover` | Read the model and data; scan sources, fields, distributions; detect prior art. With no package yet, start from `search_database_schema` to find the tables in the connection |\n| 2. Propose Scope | `skill:malloy-scope` | Present findings, user selects focus |\n| 3. Propose Sources | `skill:malloy-define` | Propose source plan, user confirms architecture |\n| 4. Propose Definitions | `skill:malloy-define` | Propose fields per base source, user confirms logic |\n| 5. Build Base Sources | `skill:malloy-model` | Write fully documented base source files (one per table), check diagnostics. Read `skill:malloy-document` for doc standards. |\n| 6. Build Joined Sources | `skill:malloy-model` | Write fully documented joined source files, validate. Read `skill:malloy-document` for doc standards. |\n| 7. Review | (none) | Present the review checklist below; user confirms or corrects |\n| 8. Curate | `skill:malloy-model` | Propose access controls (`explores`, `queryableSources`, access modifiers); always propose, the user decides whether to apply |\n\n### The pauses are the point\n\nThese are governed semantic models: the business decisions in them must be confirmed by a human subject-matter expert, and the **(user)** steps exist to collect that confirmation. They are real stops, not progress reports. A model can be complete, compiling, and fully documented and still be wrong everywhere it guessed; a capable agent can build the whole thing without pausing once, which is exactly the failure mode this workflow exists to prevent.\n\nWhen a decision goes unanswered (the user explicitly declines to decide, or nobody is there to ask), do not silently proceed as if it were settled. Take your best-supported position, label it an assumption in the field's own `#(doc)` (see `skill:malloy-document` § Mark conventions as conventions), record it under \"Open decisions\" in `modeling-notes.md`, and raise it again at Review. An unlabeled assumption is indistinguishable from a confirmed fact, and misleads everyone downstream.\n\n### Step 7 Review is a checklist, not a summary\n\nPresent these to the user, with answers:\n\n- **Which definitions did the user actually confirm?** List them; everything else is an assumption.\n- **Which thresholds and bucket boundaries did you choose?** For each: the evidence (distribution query, metadata, prior art) and the `#(doc)` hedge that marks it.\n- **Which questions were left unanswered?** Each must already carry a labeled assumption and an \"Open decisions\" entry.\n- **Does the headline metric have more than one defensible definition?** If yes, that is a blocking question: put the candidate definitions to the user with their counts side by side, not in a footnote.\n\nThe user confirming this checklist is what makes the model governed. A summary of what you built is not a checkpoint.\n\nPublishing is out of scope for open-source v1. Self-hosters move a finished model into a served package via git and the host's publish path; see `skill:malloy-publish` for the local-to-served handoff.\n\n**Two paths to a model: both produce the same fully documented result:**\n- **Schema-first:** \"Model my data\" → 8-step workflow above using the relevant skills\n- **Analysis-first:** a data question arrives before any model exists → `skill:malloy-model-as-you-go`. It answers the question with `skill:malloy-analysis`, then codifies what the answer assumed into the model, one question at a time, confirming binding decisions first. The model exists by the end; there is no separate formalize step.\n- **Open-ended exploration** with no intent to keep anything: `skill:malloy-analyze`. If it turns into something worth keeping, formalize via `skill:malloy-model` (`reference/analysis-to-model.md`).\n\n## Agent Behavior\n\n**Research before asking.** Present proposals with evidence. Never ask open-ended questions: propose with data and let the user confirm.\n\n**Use business language.** Say \"I simplified the column name\" not \"reserved word replaced.\" Don't expose Malloy internals unless the user asks.\n\n**Describe what you're doing, not which step you're on.** The user doesn't have the skill files open. Say \"I'll propose which tables to include and how they relate\" not \"Steps 3 and 4.\" Say \"Now I'll write the source files\" not \"Moving to Step 5.\" Explain the purpose of each phase in plain language before doing it.\n\n**Present choices as A/B/C.** When asking the user to choose, use lettered options with one-line descriptions. Mark your recommendation.\n\n**Complete all workflow steps.** Once modeling begins, complete through Review and propose Curate. A field without documentation is not finished. If you lose track, re-read the model and your notes. Suggest notebooks at the end.\n\n## Route by Intent\n\n| User says... | Route to |\n|-------------|----------|\n| \"Model my data\", \"create a model\" | 8-step workflow (`skill:malloy-discover`) |\n| \"Model from LookML\" | 8-step with prior art via `skill:malloy-lookml-review` |\n| \"Explore this data\", \"what's interesting?\", \"show me the top X\" | `skill:malloy-analyze` (EDA) |\n| \"Build a dashboard\", \"create views\" on existing model | `skill:malloy-analyze` (views), plus `skill:malloy-charts` or `skill:malloy-notebooks` as needed |\n| \"Build a model but not sure what metrics\" | `skill:malloy-model-as-you-go`: answer their first real question, codify what it assumed, repeat |\n\n**If the user's first message is a data question** (not \"build me a model\"), route to `skill:malloy-model-as-you-go`. It answers with `skill:malloy-analysis` and grows the model from what each answer assumed, so there is nothing to formalize afterwards.\n\n## Additional Support Skills\n\nThese supplemental skills may also be loaded as needed:\n\n- **`skill:malloy`**: Index of Malloy skills and routing guide\n- **`skill:malloy-debug`**: Fix compile errors and interpret diagnostics\n\n## Publisher MCP Tools\n\nEnsure the Publisher MCP tools are configured before modeling. No server yet? `skill:malloy-getting-started` covers setup, including the one-command scaffolder (`npm create @malloy-publisher/malloy-package@latest <name>`) and why local authoring needs `--watch-env <env>`: start the server without it and your saved edits are never read.\n\n| Tool | Purpose |\n|------|---------|\n| `get_context` | Ground yourself in a package: its sources, views, and fields |\n| `execute_query` | Run ad-hoc queries for validation |\n| `compile_model` | Compile-check a change and get diagnostics back without running a query |\n| `reload_package` | Recompile a package from disk so a saved edit becomes queryable by name |\n| `search_malloy_docs` | Search Malloy docs (call BEFORE unfamiliar patterns) |\n| `search_database_schema` | Find the tables in a database connection by plain-English description, when modelling data that is not in a package yet. Returns each table's columns and the `source:` line to start from. Names and types only: no row value is returned |\n\nNever guess field names. Ground yourself with `get_context` to see the sources and fields a package defines.\n\n### The edit-and-run loop\n\nPublisher compiles each configured package at boot and serves that cached model, so a source or view you add afterwards is not queryable by name until you reload the package. The loop is:\n\n1. **Validate** the change with `compile_model`, picking the scope that matches what you are doing:\n   - Adding a new definition or query: the default (`scope: \"append\"`) compiles your text in the model's namespace. Note its diagnostic positions land in the model-plus-your-text concatenation.\n   - **Editing an existing definition: `scope: \"file\"`**, with the whole edited file as `source`. It compiles your text AS the file (append would collide with \"Cannot redefine\"), and diagnostics land at the true line numbers of your text.\n   - Before saving a change other files import: `scope: \"package\"` with the edited file as `source` runs reload's worker compiler over every `.malloy` and `.malloynb` file against your edit, so a rename that breaks an importer surfaces now instead of at reload. Each diagnostic carries `model`, the file it points at; files hidden from discovery can appear. If `modelPath` does not exactly match an existing file, a warning says the source was treated as new.\n2. **Save** it to the package's model file.\n3. **Reload** with `reload_package`.\n4. **Run** the new view with `execute_query`.\n\nA reload that fails to compile is safe: your files are left alone and the previously compiled model keeps serving, with the compile errors returned to you. Compile first anyway for faster feedback, and a `scope: \"package\"` dry-run with no `source` uses reload's compiler and file selection (imports across files, every `.malloy` and `.malloynb` file as saved) without touching the served model. Keep the source of truth outside `publisher_data/`, which is not version-controlled and is wiped by a `--init` restart. If these tools are missing, the Publisher you are connected to predates them; fall back to validating with a throwaway `execute_query`. An older Publisher that has `compile_model` but rejects `scope` supports only the append behavior.\n\n## SQL-to-Malloy Quick Reference\n\n| SQL | Malloy |\n|-----|--------|\n| `COUNT(*)` | `count()` |\n| `COUNT(DISTINCT x)` | `count(x)` |\n| `NOW()` | `now` |\n| `CASE WHEN...END` | `pick...when...else` |\n| `col IN ('a','b')` | `col ? 'a' \\| 'b'` |\n| `COALESCE(a,b)` | `a ?? b` |\n| `CAST(x AS type)` | `x::type` |\n| `DATEDIFF(day, a, b)` | `days(a to b)` |\n| `CONCAT(a, b)` or `a \\|\\| b` | `concat(a, b)` |\n| `TIMESTAMP_DIFF(a, b, SECOND)` | `seconds(b to a)` |\n\n## Critical Rules\n\n1. **All keywords require colons**: `source:`, `dimension:`, `measure:`, `view:`\n2. **Use `is` not `as`**: `dimension: name is expression`\n3. **Arrow operator required**: `run: source -> { operations }`\n4. **Specify join type**: `join_one:`, `join_many:`, `join_cross:`\n5. **Safe division**: `revenue / nullif(count, 0)`\n6. **Group definitions under one keyword**: `measure:` then indent fields beneath\n\n## Common Anti-Patterns\n\n```\nWRONG: source flights is ...           RIGHT: source: flights is ...\nWRONG: dimension: x as y               RIGHT: dimension: y is x\nWRONG: count(*)                        RIGHT: count()\nWRONG: count(distinct x)               RIGHT: count(x)\nWRONG: revenue / order_count           RIGHT: revenue / nullif(order_count, 0)\nWRONG: run: src { ... }                RIGHT: run: src -> { ... }\n```\n\n## Reserved Words: Scan Schema First\n\n**Malloy has many reserved words. When in doubt, backtick it.** Most likely to appear as column names:\n\n```\ndate, time, day, month, year, quarter, week, hour, minute, second,\nnumber, string, boolean, type, table, source, index, count, sum, avg, min, max,\ntrue, false, null, is, on, with, all, from, by, in, to, for, select, order_by,\ntop, bottom, desc, asc, row, range, current, window, rank\n```\n\n- `number`: only the bare word needs backticking; `account_number` is fine\n- `source`: reserved; use a different alias like `traffic_source`\n- `string`, `boolean`, `true`, `false`: backtick any column with these exact names\n\n## Gotcha Skills: Read Before Writing Code\n\nThe following skills contain detailed WRONG/RIGHT patterns that prevent the most common Malloy errors. **Read them before writing code:**\n\n- **`skill:malloy-gotchas-modeling`**: Reserved words, NULL checks, date functions, type casts, rename pitfalls, query-based source gotchas, `conn.sql()` anti-pattern\n- **`skill:malloy-gotchas-queries`**: Chart constraints, aggregate filters, joined field aliasing, time truncation vs extraction\n- **`skill:malloy-gotchas-rendering`**: Tag syntax, scale rules, sparkline setup, big_value patterns"
+      body: "# STOP - READ BEFORE WRITING ANY MALLOY CODE\n\n> **AI AGENTS: You MUST review this file before writing Malloy code.** Cross-skill references below use logical `skill:` names; load the referenced skill before acting. Before writing code, also read the gotcha skills: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering`.\n\n## Pre-Flight Checklist\n\n1. **Discover first**: ground yourself before writing ANY code, with the tool that matches what you are modelling.\n   - Modelling data **already in a package**: `get_context` returns that package's sources, views, and fields (with their docs).\n   - Modelling **a database with no package yet**: `get_context` has nothing to return, so use `search_database_schema` instead. It walks the connection's schemas and tables, ranks them against a plain-English description, and gives you each table's columns plus the `source:` line to start from. Take those names verbatim into step 5.\n   Never guess field names either way.\n2. **Search docs proactively**: call `search_malloy_docs` BEFORE writing unfamiliar patterns (window functions, query-based sources, pipelines). Don't guess. Malloy syntax is specific and SQL intuition is often wrong.\n3. **Use `skill:malloy-patterns`** to discover available doc topics (YoY, cohorts, rendering, window functions).\n4. **Check diagnostics** after writing: fix the FIRST error first, errors cascade.\n5. **Read the gotcha skills**: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering` prevent the most common mistakes.\n\n**Quick syntax reminders:**\n1. **Backtick reserved words:** `` `Date` ``, `` `Hour` ``, `` `Timestamp` ``, `` `Type` ``, `` `number` ``, `` `source` ``\n2. **Use `having:` for aggregate filters**: not `where:` on measures\n3. **Alias joined fields in `group_by`** if using them in `order_by`\n4. **`count()` counts rows; `count(x)` counts distinct values of `x`**: `count(distinct x)` is deprecated, write `count(x)`\n5. **One tag per line**: `# label=\"Revenue\"` and `# currency` on separate lines\n6. **No fixed scale on measures**: use `# currency` not `# currency=usd0m`\n7. **Cast strings for aggregates:** `avg(score::number)` not `avg(score)`\n8. **Boolean columns:** use `= true` not `= 'true'` (no quotes!)\n9. **Read data files in place:** `.csv`, `.parquet`, `.json`, `.ndjson`, and `.xlsx` all work as-is through `duckdb.table('data/file.ext')`. Never convert a file to another format first, and never read one with python or jq to \"have a look\" first: query it. For `.xlsx`, check the row count before trusting it: a workbook with a title row or a blank spacer reads short and reports no error. (Per-format quirks: `skill:malloy-gotchas-modeling`)\n\n## Planning and `modeling-notes.md`\n\nIf the IDE has a native plan mode, use it for the high-level approach: do data exploration during planning, then present a concrete plan for user approval before writing any files.\n\n`modeling-notes.md` is an expected output of the workflow, not an optional extra. Start it at step 2 (Propose Scope) and grow it as you work: it persists alongside the model, and its value is as the thing the user argues with at step 3, before source files exist; written after the build it can only document decisions already baked in. Record findings and problems as they are found during discovery (`skill:malloy-discover`), and every unconfirmed decision as an open item. Only when there is no writable workspace do the notes live in the conversation instead.\n\nKeep it compact, with these sections:\n\n```markdown\n# Modeling notes - <package>\n## Scope           what was confirmed, what the model is FOR, skip list with reasons\n## Grain and keys  proven by query, not by column name\n## Coverage        coverage cliffs; columns excluded for nullity\n## Decisions       each with its evidence\n## Open decisions  ASSUMPTIONS, NOT CONFIRMED: every threshold or definition the user\n                   has not settled, one entry each, mirrored by a hedge in its #(doc)\n## Validation      reconciliation checks performed, and their results\n```\n\n## 8-Step Modeling Workflow\n\nThe agent orchestrates all steps. Steps marked **(user)** pause for input. Each step has a dedicated skill with full instructions. Read each step's skill **before starting that step**, including the decision skills for steps 1–4 (`skill:malloy-discover`, `skill:malloy-scope`, `skill:malloy-define`). They govern what the model says; skipping them to reach the build skills is how unreviewed business logic ships.\n\n**A field is not complete until it has its definition, `#(doc)` tag, and rendering tags, and any threshold or business convention in it is user-confirmed, distribution-derived, or explicitly flagged in its `#(doc)`** (see `skill:malloy-document` § Mark conventions as conventions). Documentation is part of defining a field, not a separate activity. Read `skill:malloy-document` for full documentation standards (doc string writing, tag ordering).\n\n```\nDISCOVER → SCOPE → SOURCES → DEFINITIONS → BUILD BASE → BUILD JOINED → REVIEW → CURATE\n (silent)  (user)   (user)      (user)       (agent)      (agent)      (user)   (user)\n```\n\n| Step | Skill | What Happens |\n|------|-------|-------------|\n| 1. Discover | `skill:malloy-discover` | Read the model and data; scan sources, fields, distributions; detect prior art. With no package yet, start from `search_database_schema` to find the tables in the connection |\n| 2. Propose Scope | `skill:malloy-scope` | Present findings, user selects focus |\n| 3. Propose Sources | `skill:malloy-define` | Propose source plan, user confirms architecture |\n| 4. Propose Definitions | `skill:malloy-define` | Propose fields per base source, user confirms logic |\n| 5. Build Base Sources | `skill:malloy-model` | Write fully documented base source files (one per table), check diagnostics. Read `skill:malloy-document` for doc standards. |\n| 6. Build Joined Sources | `skill:malloy-model` | Write fully documented joined source files, validate. Read `skill:malloy-document` for doc standards. |\n| 7. Review | (none) | Present the review checklist below; user confirms or corrects |\n| 8. Curate | `skill:malloy-model` | Propose the published surface (an `index.malloy` with `export { ... }`) and access controls (access modifiers, gates); always propose, the user decides whether to apply |\n\n### The pauses are the point\n\nThese are governed semantic models: the business decisions in them must be confirmed by a human subject-matter expert, and the **(user)** steps exist to collect that confirmation. They are real stops, not progress reports. A model can be complete, compiling, and fully documented and still be wrong everywhere it guessed; a capable agent can build the whole thing without pausing once, which is exactly the failure mode this workflow exists to prevent.\n\nWhen a decision goes unanswered (the user explicitly declines to decide, or nobody is there to ask), do not silently proceed as if it were settled. Take your best-supported position, label it an assumption in the field's own `#(doc)` (see `skill:malloy-document` § Mark conventions as conventions), record it under \"Open decisions\" in `modeling-notes.md`, and raise it again at Review. An unlabeled assumption is indistinguishable from a confirmed fact, and misleads everyone downstream.\n\n### Step 7 Review is a checklist, not a summary\n\nPresent these to the user, with answers:\n\n- **Which definitions did the user actually confirm?** List them; everything else is an assumption.\n- **Which thresholds and bucket boundaries did you choose?** For each: the evidence (distribution query, metadata, prior art) and the `#(doc)` hedge that marks it.\n- **Which questions were left unanswered?** Each must already carry a labeled assumption and an \"Open decisions\" entry.\n- **Does the headline metric have more than one defensible definition?** If yes, that is a blocking question: put the candidate definitions to the user with their counts side by side, not in a footnote.\n\nThe user confirming this checklist is what makes the model governed. A summary of what you built is not a checkpoint.\n\nPublishing is out of scope for open-source v1. Self-hosters move a finished model into a served package via git and the host's publish path; see `skill:malloy-publish` for the local-to-served handoff.\n\n**Two paths to a model: both produce the same fully documented result:**\n- **Schema-first:** \"Model my data\" → 8-step workflow above using the relevant skills\n- **Analysis-first:** a data question arrives before any model exists → `skill:malloy-model-as-you-go`. It answers the question with `skill:malloy-analysis`, then codifies what the answer assumed into the model, one question at a time, confirming binding decisions first. The model exists by the end; there is no separate formalize step.\n- **Open-ended exploration** with no intent to keep anything: `skill:malloy-analyze`. If it turns into something worth keeping, formalize via `skill:malloy-model` (`reference/analysis-to-model.md`).\n\n## Agent Behavior\n\n**Research before asking.** Present proposals with evidence. Never ask open-ended questions: propose with data and let the user confirm.\n\n**Use business language.** Say \"I simplified the column name\" not \"reserved word replaced.\" Don't expose Malloy internals unless the user asks.\n\n**Describe what you're doing, not which step you're on.** The user doesn't have the skill files open. Say \"I'll propose which tables to include and how they relate\" not \"Steps 3 and 4.\" Say \"Now I'll write the source files\" not \"Moving to Step 5.\" Explain the purpose of each phase in plain language before doing it.\n\n**Present choices as A/B/C.** When asking the user to choose, use lettered options with one-line descriptions. Mark your recommendation.\n\n**Complete all workflow steps.** Once modeling begins, complete through Review and propose Curate. A field without documentation is not finished. If you lose track, re-read the model and your notes. Suggest notebooks at the end.\n\n## Route by Intent\n\n| User says... | Route to |\n|-------------|----------|\n| \"Model my data\", \"create a model\" | 8-step workflow (`skill:malloy-discover`) |\n| \"Model from LookML\" | 8-step with prior art via `skill:malloy-lookml-review` |\n| \"Explore this data\", \"what's interesting?\", \"show me the top X\" | `skill:malloy-analyze` (EDA) |\n| \"Build a dashboard\", \"create views\" on existing model | `skill:malloy-analyze` (views), plus `skill:malloy-charts` or `skill:malloy-notebooks` as needed |\n| \"Build a model but not sure what metrics\" | `skill:malloy-model-as-you-go`: answer their first real question, codify what it assumed, repeat |\n\n**If the user's first message is a data question** (not \"build me a model\"), route to `skill:malloy-model-as-you-go`. It answers with `skill:malloy-analysis` and grows the model from what each answer assumed, so there is nothing to formalize afterwards.\n\n## Additional Support Skills\n\nThese supplemental skills may also be loaded as needed:\n\n- **`skill:malloy`**: Index of Malloy skills and routing guide\n- **`skill:malloy-debug`**: Fix compile errors and interpret diagnostics\n\n## Publisher MCP Tools\n\nEnsure the Publisher MCP tools are configured before modeling. No server yet? `skill:malloy-getting-started` covers setup, including the one-command scaffolder (`npm create @malloy-publisher/malloy-package@latest <name>`) and why local authoring needs `--watch-env <env>`: start the server without it and your saved edits are never read.\n\n| Tool | Purpose |\n|------|---------|\n| `get_context` | Ground yourself in a package: its sources, views, and fields |\n| `execute_query` | Run ad-hoc queries for validation |\n| `compile_model` | Compile-check a change and get diagnostics back without running a query |\n| `reload_package` | Recompile a package from disk so a saved edit becomes queryable by name |\n| `search_malloy_docs` | Search Malloy docs (call BEFORE unfamiliar patterns) |\n| `search_database_schema` | Find the tables in a database connection by plain-English description, when modelling data that is not in a package yet. Returns each table's columns and the `source:` line to start from. Names and types only: no row value is returned |\n\nNever guess field names. Ground yourself with `get_context` to see the sources and fields a package defines.\n\n### The edit-and-run loop\n\nPublisher compiles each configured package at boot and serves that cached model, so a source or view you add afterwards is not queryable by name until you reload the package. The loop is:\n\n1. **Validate** the change with `compile_model`, picking the scope that matches what you are doing:\n   - Adding a new definition or query: the default (`scope: \"append\"`) compiles your text in the model's namespace. Note its diagnostic positions land in the model-plus-your-text concatenation.\n   - **Editing an existing definition: `scope: \"file\"`**, with the whole edited file as `source`. It compiles your text AS the file (append would collide with \"Cannot redefine\"), and diagnostics land at the true line numbers of your text.\n   - Before saving a change other files import: `scope: \"package\"` with the edited file as `source` runs reload's worker compiler over every `.malloy` and `.malloynb` file against your edit, so a rename that breaks an importer surfaces now instead of at reload. Each diagnostic carries `model`, the file it points at; files hidden from discovery can appear. If `modelPath` does not exactly match an existing file, a warning says the source was treated as new.\n2. **Save** it to the package's model file.\n3. **Reload** with `reload_package`.\n4. **Run** the new view with `execute_query`.\n\nA reload that fails to compile is safe: your files are left alone and the previously compiled model keeps serving, with the compile errors returned to you. Compile first anyway for faster feedback, and a `scope: \"package\"` dry-run with no `source` uses reload's compiler and file selection (imports across files, every `.malloy` and `.malloynb` file as saved) without touching the served model. Keep the source of truth outside `publisher_data/`, which is not version-controlled and is wiped by a `--init` restart. If these tools are missing, the Publisher you are connected to predates them; fall back to validating with a throwaway `execute_query`. An older Publisher that has `compile_model` but rejects `scope` supports only the append behavior.\n\n## SQL-to-Malloy Quick Reference\n\n| SQL | Malloy |\n|-----|--------|\n| `COUNT(*)` | `count()` |\n| `COUNT(DISTINCT x)` | `count(x)` |\n| `NOW()` | `now` |\n| `CASE WHEN...END` | `pick...when...else` |\n| `col IN ('a','b')` | `col ? 'a' \\| 'b'` |\n| `COALESCE(a,b)` | `a ?? b` |\n| `CAST(x AS type)` | `x::type` |\n| `DATEDIFF(day, a, b)` | `days(a to b)` |\n| `CONCAT(a, b)` or `a \\|\\| b` | `concat(a, b)` |\n| `TIMESTAMP_DIFF(a, b, SECOND)` | `seconds(b to a)` |\n\n## Critical Rules\n\n1. **All keywords require colons**: `source:`, `dimension:`, `measure:`, `view:`\n2. **Use `is` not `as`**: `dimension: name is expression`\n3. **Arrow operator required**: `run: source -> { operations }`\n4. **Specify join type**: `join_one:`, `join_many:`, `join_cross:`\n5. **Safe division**: `revenue / nullif(count, 0)`\n6. **Group definitions under one keyword**: `measure:` then indent fields beneath\n\n## Common Anti-Patterns\n\n```\nWRONG: source flights is ...           RIGHT: source: flights is ...\nWRONG: dimension: x as y               RIGHT: dimension: y is x\nWRONG: count(*)                        RIGHT: count()\nWRONG: count(distinct x)               RIGHT: count(x)\nWRONG: revenue / order_count           RIGHT: revenue / nullif(order_count, 0)\nWRONG: run: src { ... }                RIGHT: run: src -> { ... }\n```\n\n## Reserved Words: Scan Schema First\n\n**Malloy has many reserved words. When in doubt, backtick it.** Most likely to appear as column names:\n\n```\ndate, time, day, month, year, quarter, week, hour, minute, second,\nnumber, string, boolean, type, table, source, index, count, sum, avg, min, max,\ntrue, false, null, is, on, with, all, from, by, in, to, for, select, order_by,\ntop, bottom, desc, asc, row, range, current, window, rank\n```\n\n- `number`: only the bare word needs backticking; `account_number` is fine\n- `source`: reserved; use a different alias like `traffic_source`\n- `string`, `boolean`, `true`, `false`: backtick any column with these exact names\n\n## Gotcha Skills: Read Before Writing Code\n\nThe following skills contain detailed WRONG/RIGHT patterns that prevent the most common Malloy errors. **Read them before writing code:**\n\n- **`skill:malloy-gotchas-modeling`**: Reserved words, NULL checks, date functions, type casts, rename pitfalls, query-based source gotchas, `conn.sql()` anti-pattern\n- **`skill:malloy-gotchas-queries`**: Chart constraints, aggregate filters, joined field aliasing, time truncation vs extraction\n- **`skill:malloy-gotchas-rendering`**: Tag syntax, scale rules, sparkline setup, big_value patterns"
     },
     {
       name: "malloy-notebook-chat",
@@ -325216,7 +325952,7 @@ Steps to follow when the user asks a question:
     {
       name: "malloy-notebooks",
       description: 'Create Malloy notebooks (.malloynb) for interactive dashboards and data stories. Use when user asks to "create a notebook", "make a dashboard notebook", "write a malloynb", "data story", or needs to build reports/visualizations.',
-      body: "# Malloy Notebooks\n\nFiles: `.malloynb`\n\n## Scope: when to use this skill vs `skill:malloy-analysis-report`\n\nThis skill is for **curated `.malloynb` notebooks**. Interactive parameter widgets render automatically from the `given:` declarations on the models it imports (or, in older models, from deprecated `#(filter)` annotations). The notebook itself never declares parameters or filters.\n\nFor **ad-hoc reports** generated by an analysis agent, combining queries into a quick narrative artifact, use `skill:malloy-analysis-report` instead. Ad-hoc reports also inherit whatever the source declares.\n\n## Important Limitations\n\n**Compile errors in `.malloynb` files are NOT shown in the IDE linter.** You will only see errors when cells are executed. Be extra careful with syntax and test queries in the model first if unsure.\n\n## Multiple Models & Cross-Model Joins\n\nA published `.malloynb` runs each `run:` cell against the whole notebook, which compiles with **all** its `import`s in scope. So a notebook can import several `.malloy` models, and a single cell can reference, and **join**, sources from different imported files. Import each model you need in a setup cell at the top; no \"re-export\" wrapper model is required.\n\n```\n>>>malloy\nimport \"flights.malloy\"\nimport \"carriers.malloy\"\n\n>>>malloy\n// joins `flights` (from flights.malloy) to `carriers` (from carriers.malloy)\nrun: flights extend {\n  join_one: carriers on carrier = carriers.code\n} -> {\n  group_by: carriers.nickname\n  aggregate: flight_count\n}\n```\n\nTwo things still hold:\n\n- **Imports are notebook-wide, declare them at the top, never inside a `run:` cell.** A cell's query runs as a *restricted query* against the already-compiled notebook, so its imports must already be in place. You can't `import` a model inside a query cell to scope it there; an in-query import is rejected (`file imports are not permitted in a restricted query`).\n- **Compile errors surface only at publish/render, not in the IDE linter** (see above). Verify a multi-model notebook by publishing to a scratch environment and loading it, rather than relying only on single-model query checks.\n\n## No Data-Specific Insights in Markdown\n\n**Notebooks must NOT contain findings about current data values.** Data refreshes will make these stale. Use markdown for framing questions and structural narrative, not for stating results.\n\n```\n>>>markdown\n## WRONG: will become stale when data refreshes\nRevenue spiked 23% in March. Electronics drove 60% of the spike.\n\n>>>markdown\n## RIGHT: frames the question, lets the query answer it\nHow is revenue trending? Which categories are driving changes?\n```\n\n## Cell Syntax\n\nCells delimited by `>>>markdown` or `>>>malloy`:\n\n```\n>>>markdown\n# Sales Analysis\nOverview of sales trends.\n\n>>>malloy\nimport \"sales_model.malloy\"\n\n>>>markdown\n## Summary\n\n>>>malloy\nrun: orders -> summary\n\n>>>markdown\n## Monthly Trend\n\n>>>malloy\n# line_chart\nrun: orders -> by_month\n```\n\n**NEVER create `>>>malloysql` cells.** Only use `>>>malloy` and `>>>markdown`.\n\n## Interactive Parameters (`given:`)\n\nInteractive parameters are common and important. Add them to most notebooks. **Use `given:` for anything new.** The older `#(filter)` mechanism still works and is documented below, but it is deprecated: do not reach for it just because you saw it in an existing model.\n\nA notebook's parameter surface comes from the `given:` declarations on the models it imports, not from anything declared in the `.malloynb` itself. When an imported model declares givens, Publisher's notebook UI automatically renders a Parameters panel above the notebook: declared givens become parameter inputs, the values a user sets are forwarded to Malloy's runtime, and every cell re-executes against the model with those values applied.\n\nThe widget for each parameter follows the given's declared Malloy type (`string`, `string[]`, `number`, `boolean`, `date`/`timestamp`, `filter<T>`); see `docs/givens.md` for the full type table. A `#(description=\"...\")` annotation on the given renders as helper text under its input.\n\n```malloy\n##! experimental.givens\n\n#(description=\"Two-letter IATA carrier code to spotlight\")\ngiven: carrier :: string is 'WN'\n\nsource: spotlight_carrier is duckdb.table('data/carriers.parquet') extend {\n  view: by_name is {\n    where: code = $carrier\n    select: code, name, nickname\n    limit: 1\n  }\n}\n```\n\nDeclare givens at the **top of the model file**, before the source that uses them, not in the notebook. `malloy-model` § Access Control covers the syntax and the `#(authorize)` gating story built on top of givens.\n\n## Legacy: `#(filter)` annotations\n\n> **Deprecated. Read this before copying the example below.** `#(filter)` is server-side `where:` injection, superseded by native Malloy `given:` above. Do NOT add new `#(filter)` annotations; declare runtime parameters as givens instead. `docs/givens.md` has the migration recipes. What follows is here so you can read and maintain models that already use it.\n\nFilters are declared **once, on the model's source**. The notebook itself does not declare or list filters. Publisher reads the source's filter metadata and renders the widgets above the notebook automatically, then injects `where:` clauses server-side on every cell.\n\nDeclarations live in the `.malloy` model file, above the source, using key=value parameters. The full reference (syntax, filter types, `required` / `implicit` flags) lives with the `#(filter)` guidance in the `malloy-model` skill's Parameterizable Filters section. Short example:\n\n```malloy\n#(filter) name=Manufacturer dimension=Manufacturer type=in\n#(filter) name=OrderStatus dimension=order_status type=in\n#(filter) name=Recall_After dimension=\"Report Received Date\" type=greater_than\n#(filter) name=Recall_Before dimension=\"Report Received Date\" type=less_than\nsource: recalls is duckdb.table('data/auto_recalls.csv') extend {\n  measure:\n    recall_count is count()\n}\n```\n\n`#(filter)` lines go **above** the `source:` declaration and reference dimensions by name (use `dimension=`). `name` defaults to the dimension name and only needs to be set when two filters target the same dimension (e.g. a date range). `type` is the comparator: `equal`, `in`, `like`, `greater_than`, `less_than`.\n\n## Notebook Style: Iterative Analysis (Default)\n\n**Build a story.** Each query should reveal something that motivates the next query. Start broad, then drill into what's interesting. Frame questions in markdown, let queries answer them.\n\n**Pattern:** Question, Query, Next Question, Drill\n\n```\n>>>markdown\n## How is revenue trending?\n\n>>>malloy\n# line_chart\nrun: orders -> { group_by: order_month; aggregate: revenue }\n\n>>>markdown\n## What's driving the biggest changes?\n\n>>>malloy\n# bar_chart\nrun: orders -> { group_by: category; aggregate: revenue; order_by: revenue desc; limit: 10 }\n\n>>>markdown\n## How does the top category break down?\n\n>>>malloy\nrun: orders -> { aggregate: order_count, avg_order_value; where: category = 'Electronics' }\n```\n\n**When to use other styles:**\n- **Dashboard with filters:** User asks for \"filterable dashboard\". Show key KPIs and breakdowns with interactive filters.\n- **EDA/summary:** User asks for \"overview\". Run views like `summary`, `by_month`, `by_category` in sequence.\n\n## View Refinement\n\nTo add `limit`, `where`, or other options to an existing view, use `+`:\n\n```malloy\nrun: source -> my_view + { limit: 15 }\nrun: source -> my_view + { where: status = 'active', limit: 10 }\n```\n\n## Template\n\n```\n>>>markdown\n# [Title]\n[Framing question: what are we trying to understand?]\n\n>>>malloy\nimport \"model.malloy\"\n\n>>>markdown\n## [First question: start broad]\n\n>>>malloy\nrun: main_source -> [broad query]\n\n>>>markdown\n## [Next question: motivated by what the first query reveals]\n\n>>>malloy\nrun: main_source -> [drill into finding]\n\n>>>markdown\n## [Deeper question]\n\n>>>malloy\nrun: main_source -> [further breakdown]\n```\n\n## Common Mistakes\n\n| Mistake | Fix |\n|---------|-----|\n| `view_name { limit: 10 }` | Use `+`: `view_name + { limit: 10 }` |\n| `# currency` on non-money | Only use `# currency` for monetary values |\n| `#(filter) {\"type\": \"Star\"}` (JSON-blob form, on a dimension) | Unsupported legacy syntax. `#(filter)` goes **above the source** with key=value parameters (`name=`, `dimension=`, `type=`). See the `malloy-model` skill's Parameterizable Filters section. |\n| `##(filters) [...]` annotation in the notebook | Unsupported. The notebook does not declare or list filters. Publisher renders widgets automatically from the source's `#(filter)` annotations. |\n| Creating MalloySQL cells | **NEVER use `>>>malloysql`**, only `>>>malloy` and `>>>markdown` |\n| Data-specific insights in markdown | Don't write \"Revenue grew 23%.\" Frame questions instead. Data refreshes will make findings stale. |\n| `import` inside a `run:` cell (to scope a model to that cell) | Imports are notebook-wide, put them in a setup cell at the top. An in-query import is rejected: `file imports are not permitted in a restricted query` (see Multiple Models & Cross-Model Joins). |\n| Cross-model join inside a single ad-hoc report cell | A `skill:malloy-analysis-report` cell renders against a single model, so a cross-model join there won't render. Build a published `.malloynb` (which runs against the whole notebook) for a cross-model join. |\n\n## Best Practices\n\n1. Start with markdown framing the question\n2. Import each model the notebook needs in a setup cell at the top, cells can reference and join sources across all imports (see Multiple Models & Cross-Model Joins); verify a multi-model notebook by publishing to a scratch environment\n3. Each query should follow from what the previous one could reveal\n4. One query per cell\n5. Charts render only the FIRST aggregate\n6. Add interactive filters to most notebooks by declaring `#(filter)` on the model's source (see Interactive Filters), or prefer `given:` runtime parameters for new models (see Runtime Parameters)\n7. Never include data-specific findings in markdown. Frame questions, let queries answer\n\n## Done\n\nStep complete. Output: `.malloynb` notebook file."
+      body: "# Malloy Notebooks\n\nFiles: `.malloynb`\n\n## Scope: when to use this skill vs `skill:malloy-analysis-report`\n\nThis skill is for **curated `.malloynb` notebooks**. Interactive parameter widgets render automatically from the `given:` declarations on the models it imports (or, in older models, from deprecated `#(filter)` annotations). The notebook itself never declares parameters or filters.\n\nFor **ad-hoc reports** generated by an analysis agent, combining queries into a quick narrative artifact, use `skill:malloy-analysis-report` instead. Ad-hoc reports also inherit whatever the source declares.\n\n## Important Limitations\n\n**Compile errors in `.malloynb` files are NOT shown in the IDE linter.** You will only see errors when cells are executed. Be extra careful with syntax and test queries in the model first if unsure.\n\n## Multiple Models & Cross-Model Joins\n\nA published `.malloynb` runs each `run:` cell against the whole notebook, which compiles with **all** its `import`s in scope. So a notebook can import several `.malloy` models, and a single cell can reference, and **join**, sources from different imported files. Import each model you need in a setup cell at the top; no \"re-export\" wrapper model is required.\n\n```\n>>>malloy\nimport \"flights.malloy\"\nimport \"carriers.malloy\"\n\n>>>malloy\n// joins `flights` (from flights.malloy) to `carriers` (from carriers.malloy)\nrun: flights extend {\n  join_one: carriers on carrier = carriers.code\n} -> {\n  group_by: carriers.nickname\n  aggregate: flight_count\n}\n```\n\nTwo things still hold:\n\n- **Imports are notebook-wide, declare them at the top, never inside a `run:` cell.** A cell's query runs as a *restricted query* against the already-compiled notebook, so its imports must already be in place. You can't `import` a model inside a query cell to scope it there; an in-query import is rejected (`file imports are not permitted in a restricted query`).\n- **Compile errors surface only at publish/render, not in the IDE linter** (see above). Verify a multi-model notebook by publishing to a scratch environment and loading it, rather than relying only on single-model query checks.\n\n## No Data-Specific Insights in Markdown\n\n**Notebooks must NOT contain findings about current data values.** Data refreshes will make these stale. Use markdown for framing questions and structural narrative, not for stating results.\n\n```\n>>>markdown\n## WRONG: will become stale when data refreshes\nRevenue spiked 23% in March. Electronics drove 60% of the spike.\n\n>>>markdown\n## RIGHT: frames the question, lets the query answer it\nHow is revenue trending? Which categories are driving changes?\n```\n\n## Cell Syntax\n\nCells delimited by `>>>markdown` or `>>>malloy`:\n\n```\n>>>markdown\n# Sales Analysis\nOverview of sales trends.\n\n>>>malloy\nimport \"sales_model.malloy\"\n\n>>>markdown\n## Summary\n\n>>>malloy\nrun: orders -> summary\n\n>>>markdown\n## Monthly Trend\n\n>>>malloy\n# line_chart\nrun: orders -> by_month\n```\n\n**NEVER create `>>>malloysql` cells.** Only use `>>>malloy` and `>>>markdown`.\n\n## Interactive Parameters (`given:`)\n\nInteractive parameters are common and important. Add them to most notebooks. **Use `given:` for anything new.** The older `#(filter)` mechanism still works and is documented below, but it is deprecated: do not reach for it just because you saw it in an existing model.\n\nA notebook's parameter surface comes from the `given:` declarations on the models it imports, not from anything declared in the `.malloynb` itself. When an imported model declares givens, Publisher's notebook UI automatically renders a Parameters panel above the notebook: declared givens become parameter inputs, the values a user sets are forwarded to Malloy's runtime, and every cell re-executes against the model with those values applied.\n\nThe widget for each parameter follows the given's declared Malloy type (`string`, `string[]`, `number`, `boolean`, `date`/`timestamp`, `filter<T>`); see `docs/givens.md` for the full type table. A `#(description=\"...\")` annotation on the given renders as helper text under its input.\n\n```malloy\n##! experimental.givens\n\n#(description=\"Two-letter IATA carrier code to spotlight\")\ngiven: carrier :: string is 'WN'\n\nsource: spotlight_carrier is duckdb.table('data/carriers.parquet') extend {\n  view: by_name is {\n    where: code = $carrier\n    select: code, name, nickname\n    limit: 1\n  }\n}\n```\n\nDeclare givens at the **top of the model file**, before the source that uses them, not in the notebook. `malloy-model` § Access Control covers the syntax and the `#(authorize)`/`#(access_filter)` gating story built on top of givens.\n\n## Legacy: `#(filter)` annotations\n\n> **Deprecated. Read this before copying the example below.** `#(filter)` is server-side `where:` injection, superseded by native Malloy `given:` above. Do NOT add new `#(filter)` annotations; declare runtime parameters as givens instead. `docs/givens.md` has the migration recipes. What follows is here so you can read and maintain models that already use it.\n\nFilters are declared **once, on the model's source**. The notebook itself does not declare or list filters. Publisher reads the source's filter metadata and renders the widgets above the notebook automatically, then injects `where:` clauses server-side on every cell.\n\nDeclarations live in the `.malloy` model file, above the source, using key=value parameters. The full reference (syntax, filter types, `required` / `implicit` flags) lives with the `#(filter)` guidance in the `malloy-model` skill's Parameterizable Filters section. Short example:\n\n```malloy\n#(filter) name=Manufacturer dimension=Manufacturer type=in\n#(filter) name=OrderStatus dimension=order_status type=in\n#(filter) name=Recall_After dimension=\"Report Received Date\" type=greater_than\n#(filter) name=Recall_Before dimension=\"Report Received Date\" type=less_than\nsource: recalls is duckdb.table('data/auto_recalls.csv') extend {\n  measure:\n    recall_count is count()\n}\n```\n\n`#(filter)` lines go **above** the `source:` declaration and reference dimensions by name (use `dimension=`). `name` defaults to the dimension name and only needs to be set when two filters target the same dimension (e.g. a date range). `type` is the comparator: `equal`, `in`, `like`, `greater_than`, `less_than`.\n\n## Notebook Style: Iterative Analysis (Default)\n\n**Build a story.** Each query should reveal something that motivates the next query. Start broad, then drill into what's interesting. Frame questions in markdown, let queries answer them.\n\n**Pattern:** Question, Query, Next Question, Drill\n\n```\n>>>markdown\n## How is revenue trending?\n\n>>>malloy\n# line_chart\nrun: orders -> { group_by: order_month; aggregate: revenue }\n\n>>>markdown\n## What's driving the biggest changes?\n\n>>>malloy\n# bar_chart\nrun: orders -> { group_by: category; aggregate: revenue; order_by: revenue desc; limit: 10 }\n\n>>>markdown\n## How does the top category break down?\n\n>>>malloy\nrun: orders -> { aggregate: order_count, avg_order_value; where: category = 'Electronics' }\n```\n\n**When to use other styles:**\n- **Dashboard with filters:** User asks for \"filterable dashboard\". Show key KPIs and breakdowns with interactive filters.\n- **EDA/summary:** User asks for \"overview\". Run views like `summary`, `by_month`, `by_category` in sequence.\n\n## View Refinement\n\nTo add `limit`, `where`, or other options to an existing view, use `+`:\n\n```malloy\nrun: source -> my_view + { limit: 15 }\nrun: source -> my_view + { where: status = 'active', limit: 10 }\n```\n\n## Template\n\n```\n>>>markdown\n# [Title]\n[Framing question: what are we trying to understand?]\n\n>>>malloy\nimport \"model.malloy\"\n\n>>>markdown\n## [First question: start broad]\n\n>>>malloy\nrun: main_source -> [broad query]\n\n>>>markdown\n## [Next question: motivated by what the first query reveals]\n\n>>>malloy\nrun: main_source -> [drill into finding]\n\n>>>markdown\n## [Deeper question]\n\n>>>malloy\nrun: main_source -> [further breakdown]\n```\n\n## Common Mistakes\n\n| Mistake | Fix |\n|---------|-----|\n| `view_name { limit: 10 }` | Use `+`: `view_name + { limit: 10 }` |\n| `# currency` on non-money | Only use `# currency` for monetary values |\n| `#(filter) {\"type\": \"Star\"}` (JSON-blob form, on a dimension) | Unsupported legacy syntax. `#(filter)` goes **above the source** with key=value parameters (`name=`, `dimension=`, `type=`). See the `malloy-model` skill's Parameterizable Filters section. |\n| `##(filters) [...]` annotation in the notebook | Unsupported. The notebook does not declare or list filters. Publisher renders widgets automatically from the source's `#(filter)` annotations. |\n| Creating MalloySQL cells | **NEVER use `>>>malloysql`**, only `>>>malloy` and `>>>markdown` |\n| Data-specific insights in markdown | Don't write \"Revenue grew 23%.\" Frame questions instead. Data refreshes will make findings stale. |\n| `import` inside a `run:` cell (to scope a model to that cell) | Imports are notebook-wide, put them in a setup cell at the top. An in-query import is rejected: `file imports are not permitted in a restricted query` (see Multiple Models & Cross-Model Joins). |\n| Cross-model join inside a single ad-hoc report cell | A `skill:malloy-analysis-report` cell renders against a single model, so a cross-model join there won't render. Build a published `.malloynb` (which runs against the whole notebook) for a cross-model join. |\n\n## Best Practices\n\n1. Start with markdown framing the question\n2. Import each model the notebook needs in a setup cell at the top, cells can reference and join sources across all imports (see Multiple Models & Cross-Model Joins); verify a multi-model notebook by publishing to a scratch environment\n3. Each query should follow from what the previous one could reveal\n4. One query per cell\n5. Charts render only the FIRST aggregate\n6. Add interactive filters to most notebooks by declaring `#(filter)` on the model's source (see Interactive Filters), or prefer `given:` runtime parameters for new models (see Runtime Parameters)\n7. Never include data-specific findings in markdown. Frame questions, let queries answer\n\n## Done\n\nStep complete. Output: `.malloynb` notebook file."
     },
     {
       name: "malloy-patterns",
@@ -325226,7 +325962,7 @@ Steps to follow when the user asks a question:
     {
       name: "malloy-phrase-detection",
       description: "How to phrase search_text on a get_context call so retrieval returns the fields you need instead of a truncated catalog. Covers target-type classification and decomposition patterns.",
-      body: "# Search Target Construction for `get_context`\n\nThe `get_context` tool description defines each field and what a call returns. This skill focuses on the parts you won't get right by default: classifying concepts into target types and splitting ambiguous phrases.\n\n> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.\n\n**Scope of this skill:** the patterns below build `dimension` / `measure` / `view` targets. Phrasing for `source` targets is covered at the end.\n\n**A note on matching:** `get_context` searches over the model (sources, fields, views, and their descriptions), not the distinct categorical *values* stored in the data. To find which literal values a categorical dimension holds, target the dimension, then query its distinct values with `execute_query` (see the patterns below).\n\n## Always send `search_text`\n\n**Do not enumerate.** Omitting `search_text` lists a catalog rather than searching it. Knowing the package narrows *where* to look; it does not substitute for saying *what* you need: if you know the package, that is a reason to scope, not a reason to skip `search_text`. Enumerated listings are capped per source and per entity type, and with no relevance signal the cap drops the fields your question is about while keeping join-path noise.\n\nA bare listing has two legitimate uses. The first is answering \"what data is here?\" when the user has named no subject at all. The second is reading a specific entity you already have the exact name of: scope to its source, set `entity_name`, and pass `search_text: null`, which returns that entity's docstring and Malloy code without spending a search. Every other call carries `search_text` on every target.\n\n## Authoring `search_text` for entity targets\n\nWrite `search_text` as a brief semantic **description** of what you're looking for, not an echo of the user's word. This applies even when you already know the entity name from a prior result: still describe it, don't just repeat the name. That is a rule about how to *phrase* a search, and it does not conflict with the exact-entity lookup above: if you want that one entity's code and docstring rather than a ranked set, pin it with `entity_name` and skip the search entirely. Sending its name back as `search_text` is the move this rule forbids, because it searches for a name instead of either describing a concept or asking for the entity.\n\nOne target per concept is enough: the tool handles phrasing variants internally. Don't pile up dimension targets that point at the same field. Use multiple targets only when they describe genuinely distinct concepts (see \"Non-obvious decomposition patterns\" below).\n\n## Target-type decision guide\n\n- **`dimension`**: categorical attribute to group, filter, or join on. Also used for time and numeric fields.\n  - \"region\" becomes `\"the geographic region\"`\n- **`measure`**: aggregation metric (count, sum, average, rate).\n  - \"total revenue\" becomes `\"the total revenue or sales amount\"`\n- **`view`**: pre-built analysis. Include one whenever the question sounds like a canned report (summary, breakdown, top-N, trend).\n  - \"sales summary\" becomes `\"a summary of sales metrics\"`\n- **`source`**: data domain, for a question that names a subject area rather than fields (phrasing below).\n\n**Resolving categorical values (no value-search target in v1).** When the user names a literal value like \"premium\" or \"New York City\", target the *dimension* it lives on (`\"the subscription tier\"`, `\"the city where the subscriber lives\"`). Then confirm the exact stored string by querying that dimension's distinct values with `execute_query` before you filter on it. The data may store `\"Premium\"`, `\"PREMIUM\"`, `\"NYC\"`, or `\"New York\"`, and only the data tells you which.\n\n## Non-obvious decomposition patterns\n\nThese are the rules you won't apply correctly by default:\n\n1. **Adjective + noun, split.** \"active users\" becomes two dimension targets: one for the attribute (`\"the status of the user account\"`) and one for the noun (`\"the user or account holder\"`). Resolve the modifier (\"active\") to the exact stored value by querying the status dimension's distinct values with `execute_query`.\n2. **Ambiguous concept, cover both types.** \"rating\", \"duration\", and the like could be either a dimension or a measure: create one target of each type.\n3. **Time references are dimensions.** \"last year\" becomes a dimension target for the relevant date field (`\"the date the event occurred\"`).\n4. **Numeric ranges are dimensions.** \"aged 50\", \"revenue over $1M\" become dimension targets; the comparison is applied in the query, not matched as text.\n5. **Categorical strings that look numeric are still dimensions.** \"18-30\", \"<5 days\", \"tier 2\" are stored as literal strings on a dimension. Target that dimension, then confirm the exact string with `execute_query`.\n6. **\"Top N\" without a named measure, add a ranking measure.** \"top 6 products\" becomes a measure for the ranking concept (`\"the performance metric for a product\"`) plus a dimension for the entity. If the measure is explicit (\"top products by total sales\"), use it directly and skip the generic ranking measure.\n7. **Multiple values for one concept, one dimension target.** Several values (\"premium and basic\") still map to a single dimension target for the parent field; enumerate the exact stored values with `execute_query`.\n8. **The quantity asked for is a measure, even when nothing names it.** \"How many titles were released in 2019?\" is asking for a count, but no noun in it is the count: the visible phrases are the subject (\"titles\") and the filter (\"2019\"), and mapping only those yields a `source` and a `dimension` target with no way to answer. Always add a measure target for the quantity itself (`\"the number of titles\"`). This holds for every interrogative that IS the aggregation -- \"how many\", \"how much\", \"how often\" -- and it is the pattern most easily lost when a filter or grouping is the loud part of the sentence. Measured: an answerer got this right on \"How many titles are in the dataset?\" and dropped it on \"How many titles were released in 2019?\", where the year took the attention.\n9. **A population qualifier is a target, and so is the one the question omits.** Words like \"real\", \"actual\", \"genuine\", \"live\" or \"production\" are not filler: they name rows the model marks for exclusion. Target the flag itself (`\"the flag marking synthetic, test or monitoring traffic\"`), not just the noun they modify. Add one such target even when the question carries no qualifier at all, because a table of events, requests, sessions or logs usually holds test, internal or cancelled rows and nothing in the wording will say so. Resolve it to the model's own flag rather than inventing a filter on an id or a name; a hand-rolled exclusion and the documented one rarely select the same rows.\n\n## Worked example\n\n**User:** \"Customer churn in NYC over the last year for premium and basic subscribers\"\n\nThe targets for this question:\n\n| target_type | search_text |\n|---|---|\n| `measure` | `\"the rate at which customers leave the service\"` |\n| `dimension` | `\"the city where the subscriber lives\"` |\n| `dimension` | `\"the date the subscription was canceled\"` |\n| `dimension` | `\"the tier of the subscription\"` |\n| `view` | `\"subscriber churn or retention analysis\"` |\n\nKey moves: time (\"last year\") becomes a dimension on the cancellation date; \"NYC\" and \"premium/basic subscribers\" do not get their own value targets, they resolve to the city and tier dimensions. One `view` target is included to surface any canned churn analysis.\n\nThe response returns the source these fields live on (here `subscriptions`) with the matched fields on its card. Then run `execute_query` to read the city and tier dimensions' distinct values and confirm the exact strings to filter on (\"New York City\" vs \"NYC\", \"premium\" vs \"Premium\").\n\n## Authoring `search_text` for `source` targets\n\nAim for **3-8 words that name the entity and its business process**. Don't include filter values, time ranges, or aggregations: those belong in entity targets.\n\n| Too vague | Over-specific (entity-shaped) | Good |\n|---|---|---|\n| `\"orders\"` | `\"total order revenue by customer last year\"` | `\"customer order history and line items\"` |\n| `\"customer data\"` | `\"premium subscribers who churned in NYC\"` | `\"subscriber accounts and churn\"` |\n| `\"metrics\"` | `\"monthly revenue variance by account\"` | `\"sales pipeline and revenue forecasts\"` |\n\nHeuristics:\n\n1. **Translate, don't echo.** \"How did sales go last month?\" becomes `\"sales order revenue\"`, not `\"sales last month\"`.\n2. **Differentiate by data shape or business process, not by the user's industry, brand, or product category.** Prefer `\"order fulfillment and shipping\"` over `\"ecommerce data\"` when multiple commerce-ish packages exist. Do NOT add words like `\"eyewear\"`, `\"subscription box\"`, `\"Acme Corp\"`, or the user's specific vertical/brand. Source summaries describe data structure, not the customer's vertical, so those words add noise and can hurt matching.\n3. **Retry with alternative phrasings** if the right source isn't in the results before concluding it's missing."
+      body: "# Search Target Construction for `get_context`\n\nThe `get_context` tool description defines each field and what a call returns. This skill focuses on the parts you won't get right by default: classifying concepts into target types and splitting ambiguous phrases.\n\n> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.\n\n**Scope of this skill:** the patterns below build `dimension` / `measure` / `view` / `dimensional_value` targets. Phrasing for `source` targets is covered at the end.\n\n**A note on matching:** `get_context` searches over the model (sources, fields, views, and their descriptions), and `dimensional_value` targets search the categorical *values* stored in the data. Some servers don't index values; check the tool's description. On one that doesn't, find a literal value by targeting its dimension, then querying its distinct values with `execute_query` (see \"Where value search isn't available\" below).\n\n## Always send `search_text`\n\n**Do not enumerate.** Omitting `search_text` lists a catalog rather than searching it. Knowing the package narrows *where* to look; it does not substitute for saying *what* you need: if you know the package, that is a reason to scope, not a reason to skip `search_text`. Enumerated listings are capped per source and per entity type, and with no relevance signal the cap drops the fields your question is about while keeping join-path noise.\n\nA bare listing has two legitimate uses. The first is answering \"what data is here?\" when the user has named no subject at all. The second is reading a specific entity you already have the exact name of: scope to its source, set `entity_name`, and pass `search_text: null`, which returns that entity's docstring and Malloy code without spending a search. Every other call carries `search_text` on every target.\n\n## Authoring `search_text` for entity targets\n\nWrite `search_text` as a brief semantic **description** of what you're looking for, not an echo of the user's word. This applies even when you already know the entity name from a prior result: still describe it, don't just repeat the name. That is a rule about how to *phrase* a search, and it does not conflict with the exact-entity lookup above: if you want that one entity's code and docstring rather than a ranked set, pin it with `entity_name` and skip the search entirely. Sending its name back as `search_text` is the move this rule forbids, because it searches for a name instead of either describing a concept or asking for the entity.\n\nOne target per concept is enough: the tool handles phrasing variants internally. Don't pile up dimension targets that point at the same field. Use multiple targets only when they describe genuinely distinct concepts (see \"Non-obvious decomposition patterns\" below).\n\n## Target-type decision guide\n\n- **`dimension`**: categorical attribute to group, filter, or join on. Also used for time and numeric fields.\n  - \"region\" becomes `\"the geographic region\"`\n- **`measure`**: aggregation metric (count, sum, average, rate).\n  - \"total revenue\" becomes `\"the total revenue or sales amount\"`\n- **`view`**: pre-built analysis. Include one whenever the question sounds like a canned report (summary, breakdown, top-N, trend).\n  - \"sales summary\" becomes `\"a summary of sales metrics\"`\n- **`dimensional_value`**: a literal value the user named, stored in some dimension. `search_text` is the value itself, the one target where echoing the user's word is right.\n  - \"CyberArk\" stays `\"CyberArk\"`\n  - Best practice is to scope the call to the source that holds the value. An unscoped value search covers every indexed dimension in scope, so it is slow on a large package. If you truly don't know the source, you can leave the scope off, but expect a slow call.\n- **`source`**: data domain, for a question that names a subject area rather than fields (phrasing below).\n\n**Resolving categorical values.** When the user names a literal value like \"premium\" or \"New York City\", send a `dimensional_value` target for it, scoped to its source once you know the source. Filter on the exact string it returns: the data may store `\"Premium\"`, `\"PREMIUM\"`, `\"NYC\"`, or `\"New York\"`, and only the data tells you which.\n\n**Where value search isn't available.** Some servers have no value index and return nothing for a `dimensional_value` target, and on others a particular dimension's values may not be indexed. Then target the *dimension* the value lives on (`\"the subscription tier\"`, `\"the city where the subscriber lives\"`), and confirm the exact stored string by querying that dimension's distinct values with `execute_query` before you filter on it.\n\n## Non-obvious decomposition patterns\n\nThese are the rules you won't apply correctly by default:\n\n1. **Adjective + noun, split.** \"active users\" becomes two dimension targets: one for the attribute (`\"the status of the user account\"`) and one for the noun (`\"the user or account holder\"`). Resolve the modifier (\"active\") to the exact stored value with a `dimensional_value` target, or the status dimension's distinct values where values aren't indexed.\n2. **Ambiguous concept, cover both types.** \"rating\", \"duration\", and the like could be either a dimension or a measure: create one target of each type.\n3. **Time references are dimensions.** \"last year\" becomes a dimension target for the relevant date field (`\"the date the event occurred\"`).\n4. **Numeric ranges are dimensions.** \"aged 50\", \"revenue over $1M\" become dimension targets; the comparison is applied in the query, not matched as text.\n5. **Categorical strings that look numeric are still dimensions.** \"18-30\", \"<5 days\", \"tier 2\" are stored as literal strings on a dimension. Target that dimension, then confirm the exact string with a `dimensional_value` target, or `execute_query` where values aren't indexed.\n6. **\"Top N\" without a named measure, add a ranking measure.** \"top 6 products\" becomes a measure for the ranking concept (`\"the performance metric for a product\"`) plus a dimension for the entity. If the measure is explicit (\"top products by total sales\"), use it directly and skip the generic ranking measure.\n7. **Multiple values for one concept, one dimension target.** Several values (\"premium and basic\") still map to a single dimension target for the parent field; confirm the exact stored values with `dimensional_value` targets, or `execute_query` where values aren't indexed.\n8. **The quantity asked for is a measure, even when nothing names it.** \"How many titles were released in 2019?\" is asking for a count, but no noun in it is the count: the visible phrases are the subject (\"titles\") and the filter (\"2019\"), and mapping only those yields a `source` and a `dimension` target with no way to answer. Always add a measure target for the quantity itself (`\"the number of titles\"`). This holds for every interrogative that IS the aggregation -- \"how many\", \"how much\", \"how often\" -- and it is the pattern most easily lost when a filter or grouping is the loud part of the sentence. Measured: an answerer got this right on \"How many titles are in the dataset?\" and dropped it on \"How many titles were released in 2019?\", where the year took the attention.\n9. **A population qualifier is a target, and so is the one the question omits.** Words like \"real\", \"actual\", \"genuine\", \"live\" or \"production\" are not filler: they name rows the model marks for exclusion. Target the flag itself (`\"the flag marking synthetic, test or monitoring traffic\"`), not just the noun they modify. Add one such target even when the question carries no qualifier at all, because a table of events, requests, sessions or logs usually holds test, internal or cancelled rows and nothing in the wording will say so. Resolve it to the model's own flag rather than inventing a filter on an id or a name; a hand-rolled exclusion and the documented one rarely select the same rows.\n\n## Worked example\n\n**User:** \"Customer churn in NYC over the last year for premium and basic subscribers\"\n\nThe targets for this question:\n\n| target_type | search_text |\n|---|---|\n| `measure` | `\"the rate at which customers leave the service\"` |\n| `dimension` | `\"the city where the subscriber lives\"` |\n| `dimension` | `\"the date the subscription was canceled\"` |\n| `dimension` | `\"the tier of the subscription\"` |\n| `view` | `\"subscriber churn or retention analysis\"` |\n\nKey moves: time (\"last year\") becomes a dimension on the cancellation date; \"NYC\" and \"premium/basic subscribers\" resolve to the city and tier dimensions in this first call, because the source is not known yet and an unscoped value search is slow. One `view` target is included to surface any canned churn analysis.\n\nThe response returns the source these fields live on (here `subscriptions`) with the matched fields on its card. Then send a second call scoped to `subscriptions`, with `dimensional_value` targets for `\"NYC\"`, `\"premium\"` and `\"basic\"`, to get the exact strings to filter on (\"New York City\" vs \"NYC\", \"premium\" vs \"Premium\"). Where values aren't indexed, run `execute_query` on the city and tier dimensions' distinct values instead.\n\n## Authoring `search_text` for `source` targets\n\nAim for **3-8 words that name the entity and its business process**. Don't include filter values, time ranges, or aggregations: those belong in entity targets.\n\n| Too vague | Over-specific (entity-shaped) | Good |\n|---|---|---|\n| `\"orders\"` | `\"total order revenue by customer last year\"` | `\"customer order history and line items\"` |\n| `\"customer data\"` | `\"premium subscribers who churned in NYC\"` | `\"subscriber accounts and churn\"` |\n| `\"metrics\"` | `\"monthly revenue variance by account\"` | `\"sales pipeline and revenue forecasts\"` |\n\nHeuristics:\n\n1. **Translate, don't echo.** \"How did sales go last month?\" becomes `\"sales order revenue\"`, not `\"sales last month\"`.\n2. **Differentiate by data shape or business process, not by the user's industry, brand, or product category.** Prefer `\"order fulfillment and shipping\"` over `\"ecommerce data\"` when multiple commerce-ish packages exist. Do NOT add words like `\"eyewear\"`, `\"subscription box\"`, `\"Acme Corp\"`, or the user's specific vertical/brand. Source summaries describe data structure, not the customer's vertical, so those words add noise and can hurt matching.\n3. **Retry with alternative phrasings** if the right source isn't in the results before concluding it's missing."
     },
     {
       name: "malloy-publish",
@@ -325279,28 +326015,47 @@ If it doesn't exist, create one. Suggest a package name based on the model conte
 
 ### Curating discovery & the query boundary (optional)
 
-By default a package exposes **everything**: every model is listed and every source is directly queryable. That's the right behavior for most packages, and it's the safe default: **omit these fields and nothing changes.** Reach for them when you have raw/staging/scaffolding sources that exist to build a curated entry point and you don't want agents landing on (or querying) them directly.
+A package with no \`index.malloy\` and no \`explores\` exposes **everything**: every model is listed and every source is directly queryable.
+
+To curate, add an **\`index.malloy\`** at the package root. Publisher reads it as the package's published surface, so no manifest field is involved:
+
+\`\`\`malloy
+// index.malloy
+import "order_analysis.malloy"
+import "staging.malloy"
+
+export { orders, customers }
+\`\`\`
+
+What it exports is what agents discover **and** what may be queried. Everything else still compiles, and other models can import, join and extend it, but a direct query against it is refused with a 404 - indistinguishable from a source that does not exist. Reach for this when you have raw/staging/scaffolding sources that exist to build a curated entry point and you don't want agents landing on, or querying, them directly.
+
+**Address queries to the surface.** Once a package has an \`index.malloy\`, \`.../models/staging.malloy/query\` is no longer a query entry point, *even for a source that file declares itself*. Use \`.../models/index.malloy/query\`. If you are debugging a refusal rather than authoring, \`skill:malloy-source-unreachable\` covers the three ways a source can be out of reach and how to tell them apart.
+
+**A surface can be layered.** An \`index.malloy\` may front a file that fronts another. A source re-exported through a chain of files stays queryable through the surface at any depth, because admission follows the declaration rather than the path taken to it.
+
+**Curation hides a landing point, not a column.** A published source may \`join\` an unpublished one, and a query grouping by a joined field returns that field's values normally. If a column must not be readable, do not join it into something you publish; gate it with \`#(authorize)\` instead.
 
-Two optional fields opt the package into curation:
+**Leaving a source out does not put it out of reach, but there is a condition.** \`export { ... }\` also decides what an *importing* file may see, which is Malloy's rule rather than Publisher's. A file that declares no \`export\` hands an importer everything it declares, so an unpublished source stays importable and joinable from the file that declares it. A file that *does* declare one hands over exactly that list: importing a file whose \`export\` omits a source and then naming it fails to compile with \`Reference to undefined object\`. Put an \`export\` on a mid-layer file only when you mean to narrow what its importers can build on, not just what Publisher lists.
+
+**About \`export { … }\`:** the surface filters which *files* are listed; \`export { … }\` (a Malloy statement) filters which *sources within a file* are exposed, and the two compose. You usually don't write it in a leaf model: a file with **no** \`export\` exposes all of its own top-level sources. It must appear after the definitions it names. See [Malloy: Imports & Exports](https://docs.malloydata.dev/documentation/language/imports).
+
+### The older manifest fields
+
+Both still work and are not going away in this release. Both are deprecated where \`index.malloy\` replaces them, and a package using them that way gets a load-time warning naming the replacement. The two uses it cannot replace, an \`explores\` naming several files and \`queryableSources: "all"\`, stay supported without a warning. Do not add either key to a new package that does not need one of those two.
 
 \`\`\`json
 {
   "name": "ecommerce",
-  "version": "0.0.1",
-  "description": "Orders, customers, and revenue analysis",
   "explores": ["order_analysis.malloy", "customer_health.malloy"],
-  "queryableSources": "declared"
+  "queryableSources": "all"
 }
 \`\`\`
 
-- **\`explores\`** (\`string[]\`) - an allowlist of **model file paths** (relative to the package root, not source or view names) whose models agents should discover and land on. Declaring it is the single opt-in for all discovery curation. With \`explores\` set, listings narrow to those files, and within each file to its \`export { ... }\` closure (below), so anything a listed file doesn't export is also dropped. Other files still compile, and can still be imported or joined, but are hidden from listings. Leaving \`explores\` **absent or empty** means every model is listed, unchanged from today, so existing packages don't break when this field is added. An entry that doesn't resolve to a real \`.malloy\` file surfaces in \`exploresWarnings\`; publishing a package that has any is rejected, so fix the path before publishing.
-- **\`queryableSources\`** (\`"declared"\` | \`"all"\`, default \`"declared"\`) - the query boundary. Only takes effect once \`explores\` is set. \`"declared"\` makes queryable == discoverable: only the \`explores\` files and their \`export {}\` closure are valid top-level query targets; other sources still compile, import, and join, but a direct query against one is denied. \`"all"\` curates discovery only: every compiled source stays queryable even though \`explores\` narrows what's listed.
-
-**About \`export { … }\`:** \`explores\` filters which *files* are listed; \`export { … }\` (a Malloy statement) filters which *sources within a file* are exposed, the two compose. You usually don't write it: a file with **no** \`export\` exposes all of its own top-level sources. Add \`export { orders, customers }\` to a file to expose only those and keep imported/scaffolding helpers out of discovery (it must appear after the definitions it names). See [Malloy: Imports & Exports](https://docs.malloydata.dev/documentation/language/imports).
+- **\`explores\`** (\`string[]\`) - model file paths relative to the package root, naming the surface. Reach for it for the one thing \`index.malloy\` cannot express: a surface spanning **several** files. An explicit \`explores\` always wins over the convention, and a package with both an \`index.malloy\` and an \`explores\` that omits it carries a warning saying so. An entry that doesn't resolve to a real \`.malloy\` file surfaces in \`exploresWarnings\`; publishing a package that has any is rejected, so fix the path before publishing. An explicit \`"explores": []\` means "do not curate" and suppresses the convention.
+- **\`queryableSources\`** (\`"declared"\` | \`"all"\`, default \`"declared"\`) - the query boundary. \`"declared"\` is already the default, so the key changes nothing. **\`"all"\` is the exception, and \`index.malloy\` does not replace it:** it curates listings while leaving every source queryable by name, and a surface derived from an \`index.malloy\` always enforces the boundary. If you want listings-only curation, keep both keys.
 
-**Why curate here:** declaring \`explores\` routes agents to the well-documented curated sources instead of raw tables, and \`queryableSources: "declared"\` keeps them from reaching the hidden sources by name. The two axes compose: list a file in \`explores\` for its models to be discoverable, and \`export\` a source within that file for it to be a landing point.
 
-> **Not access control.** \`queryableSources\` gates the query surface (the query endpoints, REST and MCP alike), not compile and not raw file retrieval by exact path: \`/compile\` and \`compile_model\` are deliberately exempt, because compile is the authoring loop and the boundary is discovery curation. It doesn't restrict *who* may query, only *what* is queryable by name. Queryable sources are the union of every \`explores\`-listed file's \`export {}\` closure, whichever listed model path a query addresses them through. To gate access by caller-supplied identity/role, use \`#(authorize)\` on the source, see \`skill:malloy-model\` § Access Control and \`docs/authorize.md\`. Discovery curation and \`#(authorize)\` are independent layers.
+> **Not access control.** The surface gates the query surface (the query endpoints, REST and MCP alike), not compile and not raw file retrieval by exact path: \`/compile\` and \`compile_model\` are deliberately exempt, because compile is the authoring loop and the boundary is discovery curation. It doesn't restrict *who* may query, only *what* is queryable by name. Queryable sources are the union of every listed file's \`export {}\` closure, whichever listed model path a query addresses them through. To gate access by caller-supplied identity/role, use \`#(authorize)\` on the source (and \`#(access_filter)\` to scope rows), see \`skill:malloy-model\` § Access Control and \`docs/authorize.md\`. Discovery curation and these gates are independent layers.
 
 The manifest also carries a \`scope\` field (\`"package"\` | \`"version"\`, default \`"package"\`) controlling whether persisted/materialized artifacts are shared across published versions or owned by a single version, and a \`materialization\` field configuring that persistence policy (a cron \`schedule\` or a \`freshness\` window). Both are unrelated to discovery curation; there is no per-source \`sharing\` or \`schedule\` field, that was retired in favor of the single package-level \`scope\` and \`materialization\`.
 
@@ -325433,10 +326188,10 @@ Wrong: \`pick('Premium') { ... }\` (that's not Malloy syntax).
 **Window functions with \`calculate:\`:** running totals, \`lag()\`, \`lead()\`, and other window operations belong in \`calculate:\`, not \`aggregate:\`.
 \`\`\`malloy
 run: source -> {
-  group_by: month is order_date.month
+  group_by: order_month is order_date.month
   aggregate: revenue
   calculate: prev_month_revenue is lag(revenue)
-  order_by: month
+  order_by: order_month
 }
 \`\`\`
 
@@ -325474,15 +326229,15 @@ where: order_date >= @2020-01-01
 
 ### Truncation accessors return timestamps, not integers
 
-\`order_date.month\` returns a month-truncated timestamp (e.g., \`2025-06-01 00:00:00\`), useful for \`group_by:\`. It is NOT a 1-12 integer, and it cannot be chained: writing \`order_date.month.day\` fails. Stop at the first truncation.
+\`order_date.month\` returns a month-truncated timestamp (e.g., \`2025-06-01 00:00:00\`), useful for \`group_by:\`. It is NOT a 1-12 integer.
 
-Available truncations: \`.year\`, \`.quarter\`, \`.month\`, \`.week\`, \`.day\`, \`.hour\`, \`.minute\`, \`.second\`. Stop at the first.
+Available truncations: \`.year\`, \`.quarter\`, \`.month\`, \`.week\`, \`.day\`, \`.hour\`, \`.minute\`, \`.second\`.
 
-### \`month\`, \`year\`, \`day\`, \`quarter\` are reserved words
+### \`month\`, \`year\`, \`day\`, \`quarter\` are reserved as names
 
-Don't try to extract a numeric month with a function call: \`month(order_date)\`, \`year(order_date)\`, etc. fail to parse in \`where:\` because the names are reserved. The same names can also break aliases:
+They cannot name an output field. The functions are fine: \`month(order_date)\` extracts 1-12 anywhere, including \`where:\`.
 
-Wrong: \`group_by: month is order_date.month\`  →  parse error
+Wrong: \`group_by: month is order_date.month\`  →  \`'month' is a reserved word, so to use it as a name you must quote it\`
 Right: \`group_by: order_month is order_date.month\`
 Right (when a column is literally named \`month\`): \`\` group_by: \`month\` \`\`
 
@@ -325598,7 +326353,7 @@ run: source -> {
 }
 \`\`\`
 
-Charts render only the **first** aggregate. For multiple measures on one chart, place \`# y\` above the \`aggregate:\` keyword or use the \`y=['a','b']\` shorthand. A misplaced chart annotation (e.g., inside \`{ }\`) typically produces the error *"field is a bar chart, but is not a repeated record"*.
+Charts render only the **first** aggregate. For multiple measures on one chart, place \`# y\` above the \`aggregate:\` keyword or use the \`y=['a','b']\` shorthand. A chart annotation left as the last line inside \`{ }\` fails with *"Parser enountered unexpected statement type 'unimplemented'"* (the compiler's spelling); one after the closing \`}\` fails with *"Object annotation not connected to any object"*.
 
 Read the \`malloy-charts\` skill for chart types, properties, data shape requirements, and selection guidance.
 
@@ -325609,11 +326364,10 @@ Read the error against the tables above and below. Most failures match a known p
 | Error message | Likely cause / fix |
 |---|---|
 | \`Cannot compare a timestamp to a number\` | Comparing \`date.year\` to an integer. Use \`date >= @2020-01-01\` instead. |
-| \`no viable alternative at input '<word>'\` | Two common causes: a reserved keyword used as an alias or as a function call (e.g., \`month is ...\`, \`month(date_field)\`) - rename, backtick, or use \`date_field.month\` / a \`?\`-apply filter instead; or a semicolon used to separate fields within a clause - fields under one \`aggregate:\`/\`group_by:\` are comma- or newline-separated, never \`;\` (the error points at the field right after the \`;\`). |
+| \`no viable alternative at input '<word>'\` | Often a \`;\` between fields within one clause - fields under one \`aggregate:\`/\`group_by:\` are comma- or newline-separated (the error points at the field right after the \`;\`). |
 | \`'<field_name>' is not defined\` | Field doesn't exist in the source. Re-check against the model definition; you may have stripped a join prefix. |
-| \`missing {DAY, HOUR, MINUTE, MONTH, QUARTER, SECOND, WEEK, YEAR}\` | Chained date property too deep (e.g., \`.month.something\`). Stop at the first truncation. |
 | \`field is a bar chart, but is not a repeated record\` | Chart annotation placed inside \`{ }\`. Move \`# bar_chart\` above \`run:\` / \`view:\` / \`nest:\`. |
-| \`Parser encountered unexpected statement\` | Unsupported feature, or syntax placed where Malloy doesn't allow it (e.g., \`pick\` inside a nested view). |
+| \`Parser enountered unexpected statement\` | Spelled that way by the compiler. Most often a chart annotation left as the last line inside \`{ }\` - move it above \`run:\`. Also syntax Malloy doesn't allow in that position (e.g., \`pick\` inside a nested view). |
 | Query silently returns zero rows | Filter value mismatch (case, spelling, format). Run a distinct-values query on the dimension to confirm the literal. |
 
 ## Syntax Help
@@ -326304,6 +327058,74 @@ Then hand off to modeling: use your modeling workflow to turn the confirmed scop
 ## Done
 
 Scope confirmed, in the conversation and in \`modeling-notes.md\`: tables in scope, analytical focus, model kind and what it rules out, and what's deferred. Continue with your modeling workflow.`
+    },
+    {
+      name: "malloy-source-unreachable",
+      description: `Work out why a source is missing from get_context, or why a query against it was refused with a 404 or a 403, and what to do next. Use when a source you expect is absent from discovery, when execute_query answers "No queryable source", when a query that used to work stops working, or when deciding whether a package's curation is hiding something you need.`,
+      body: `# A source you cannot reach
+
+> **Tool names** are written bare here - \`get_context\`, \`execute_query\`, \`get_status\`, \`compile_model\`. The exact prefixed name depends on the host surface; match each against the tools you actually have.
+
+Most packages publish a curated surface, so a source being absent or refused is usually the package working as its author intended, not a fault. Read the refusal before working around it, because the three things that can refuse you need three different responses and they are told apart by the status code.
+
+## The three answers
+
+| what you got | what it means | what to do |
+| --- | --- | --- |
+| **404**, "No queryable source", "No queryable model" or "Query target is not queryable" | the source is not on the package's published surface, or does not exist. The two are deliberately indistinguishable so that a refusal cannot be used to probe for hidden names | query something on the surface, or ask the package's author to publish it |
+| **403**, "Access denied" | the source exists and is on the surface, but an \`#(authorize)\` gate did not admit you | supply the givens the gate reads, or accept that this caller may not read it |
+| **200** with zero rows | you were admitted, and an \`#(access_filter)\` narrowed the rows to none of them | this is a real answer. Report it as "no matching rows", never as an error |
+
+A 403 names a source, so it tells you the source exists. A 404 tells you nothing at all. That asymmetry is deliberate: a source that is both hidden AND gated answers **404**, so you can never use a 403 to discover that a hidden name is real.
+
+## Addressing the surface, which is the most common 404
+
+A query names a model file. When a package curates its surface, only files on that surface are valid entry points, **even for a source that file declares itself**:
+
+\`\`\`
+POST .../packages/sales/models/index.malloy/query    {"sourceName": "orders"}   -> 200
+POST .../packages/sales/models/orders.malloy/query   {"sourceName": "orders"}   -> 404
+\`\`\`
+
+Same source, same package. \`orders.malloy\` is off the surface, so it is not an entry point.
+
+**Use the \`model_path\` that \`get_context\` gave you, verbatim.** Its \`source_info.resource_id\` holds \`environment\`, \`package\`, \`model_path\` and \`source\`, and those are exactly \`execute_query\`'s \`environmentName\`, \`packageName\`, \`modelPath\` and \`sourceName\`. On a curated package the \`model_path\` is the surface file, not the file that declares the source. Substituting the declaring file because it looks more correct is how this 404 happens.
+
+## When the source is not in \`get_context\` at all
+
+Work down this list. The first three are far more common than the last.
+
+1. **It is off the surface.** The package publishes a curated set and this source is not in it. Nothing you can do from the query side; it is a package edit.
+2. **The package failed to load, or is serving a stale model.** Call \`get_status\`. A package that never loaded is absent from listings entirely, which reads exactly like "does not exist". A package whose last reload failed to compile is listed and answering, from the model it compiled *before* that save, and carries \`stale: true\`. Neither is visible from a listing alone.
+3. **You are talking to a different server than you think.** Call \`list_packages\` and check the environment and package names are the ones you expect. A stale \`.mcp.json\` outlives the server that wrote it, and another Publisher may hold that port.
+4. **Your search phrasing missed it.** Retry with a bare target (no \`search_text\`) to enumerate rather than rank. If it appears there, the source exists and was a ranking miss.
+
+## What curation does not do
+
+- **It does not hide fields.** A published source may \`join\` an unpublished one, and a query grouping by a joined field returns that field's values normally. Hiding a source removes it as a landing point; it does not redact columns a published source pulls in.
+- **It does not gate \`/compile\`.** \`compile_model\` is exempt, because compile is the authoring loop. A hidden source can still be compile-checked, and that is intended. The exception is a hidden source that is also gated, which answers 404 at compile too.
+- **It is not access control.** Curation answers "what is queryable by name", not "who may query it". Identity is \`#(authorize)\` and \`#(access_filter)\`. A source is not protected by being hidden.
+
+## Reaching an unpublished source from your own model
+
+If you are writing Malloy rather than just querying, an unpublished source is still usable, with one condition that trips people.
+
+\`export { ... }\` decides what an **importing file** can see, which is Malloy's rule and not Publisher's:
+
+- a file that declares **no** \`export\` hands an importer everything it declares, so import the file that declares the source and join it normally;
+- a file that **does** declare one hands over exactly that list. Importing a file whose \`export\` omits the source and then naming it fails to compile with \`Reference to undefined object\`.
+
+So an unpublished source is reachable through a file that exports it, or that exports nothing, and not through a file whose \`export\` leaves it out. Re-export chains are fine at any depth: a source re-exported through several files stays queryable through the surface, because admission follows the declaration rather than the path taken to it.
+
+## Before you report a source as missing
+
+Confirm all three, in this order. Each one has been mistaken for "the data is not there".
+
+1. \`get_status\` shows the package loaded and not \`stale\`.
+2. \`list_packages\` names the environment and package you meant.
+3. An enumerating \`get_context\` call (a target with no \`search_text\`) does not list it.
+
+Only then is it genuinely not published, and the answer to the user is that the package does not expose it, not that the data does not exist.`
     }
   ]
 };
@@ -327699,7 +328521,7 @@ async function withBigQueryLookupRetry(work, parentJobId) {
           parentJobId,
           error: error instanceof Error ? error.message : String(error)
         });
-        await new Promise((resolve6) => setTimeout(resolve6, BIGQUERY_LOOKUP_BACKOFF_MS * attempt));
+        await new Promise((resolve7) => setTimeout(resolve7, BIGQUERY_LOOKUP_BACKOFF_MS * attempt));
       }
     }
   }
@@ -330384,11 +331206,11 @@ var promisifyStore = (passedStore) => {
 
   class PromisifiedStore {
     async increment(key) {
-      return new Promise((resolve6, reject2) => {
+      return new Promise((resolve7, reject2) => {
         legacyStore.incr(key, (error, totalHits, resetTime) => {
           if (error)
             reject2(error);
-          resolve6({ totalHits, resetTime });
+          resolve7({ totalHits, resetTime });
         });
       });
     }
@@ -330518,9 +331340,9 @@ var rateLimit = (passedOptions) => {
     }
   }
   const middleware = handleAsyncErrors(async (request, response, next) => {
-    const closePromise = config.skipFailedRequests && new Promise((resolve6) => response.once("close", resolve6));
-    const finishPromise = (config.skipFailedRequests || config.skipSuccessfulRequests) && new Promise((resolve6) => response.once("finish", resolve6));
-    const errorPromise = config.skipFailedRequests && new Promise((resolve6) => response.once("error", resolve6));
+    const closePromise = config.skipFailedRequests && new Promise((resolve7) => response.once("close", resolve7));
+    const finishPromise = (config.skipFailedRequests || config.skipSuccessfulRequests) && new Promise((resolve7) => response.once("finish", resolve7));
+    const errorPromise = config.skipFailedRequests && new Promise((resolve7) => response.once("error", resolve7));
     debug2("requested %o", request.originalUrl);
     debug2("request from ip %o", request.ip);
     const skip = await config.skip(request, response);
@@ -331862,8 +332684,8 @@ mainServer.timeout = 600000;
 mainServer.keepAliveTimeout = 600000;
 mainServer.headersTimeout = 600000;
 var resolveRestBound = () => {};
-var restBound = new Promise((resolve7) => {
-  resolveRestBound = resolve7;
+var restBound = new Promise((resolve8) => {
+  resolveRestBound = resolve8;
 });
 mainServer.listen(PUBLISHER_PORT, PUBLISHER_HOST, async () => {
   resolveRestBound();