@malloy-publisher/server 0.8.0 → 0.8.1

package/dist/server.mjs

@@ -176449,6 +176449,8 @@ function internalErrorToHttpError(error) {
     return httpError(422, error.message);
   } else if (error instanceof ModelCompilationError) {
     return httpError(424, error.message);
+  } else if (error instanceof PackageManifestError) {
+    return httpError(424, error.message);
   } else if (error instanceof ConnectionError) {
     if (error.callerSafe) {
       return httpError(502, error.message);
@@ -176489,7 +176491,7 @@ function httpError(code, message, reason) {
     }
   };
 }
-var GENERIC_INTERNAL_MESSAGE = "Internal server error.", GENERIC_UPSTREAM_MESSAGE = "Upstream connection error.", MAX_LOGGED_DETAIL_CHARS = 2000, NotImplementedError, BadRequestError, InvalidArgumentError, CompileRefusedError, EnvironmentNotFoundError, PackageNotFoundError, ModelNotFoundError, DashboardNotFoundError, ConnectionNotFoundError, TableNotFoundError, ConnectionError, DestinationNotFoundError, ConnectionAuthError, UnsupportedCatalogFormatError, ModelCompilationError, MaterializationEligibilityError, PublisherConfigError, FrozenConfigError, AccessDeniedError, NotQueryableError, MaterializationNotFoundError, MaterializationConflictError, WriteConflictError, WriteRolledBackError, InvalidStateTransitionError, ServiceUnavailableError, PayloadTooLargeError, ResponseUnserializableError, QueryTimeoutError;
+var GENERIC_INTERNAL_MESSAGE = "Internal server error.", GENERIC_UPSTREAM_MESSAGE = "Upstream connection error.", MAX_LOGGED_DETAIL_CHARS = 2000, NotImplementedError, BadRequestError, InvalidArgumentError, CompileRefusedError, EnvironmentNotFoundError, PackageNotFoundError, ModelNotFoundError, DashboardNotFoundError, ConnectionNotFoundError, TableNotFoundError, ConnectionError, DestinationNotFoundError, ConnectionAuthError, UnsupportedCatalogFormatError, ModelCompilationError, PackageManifestError, MaterializationEligibilityError, PublisherConfigError, FrozenConfigError, AccessDeniedError, NotQueryableError, OffSurfaceError, MaterializationNotFoundError, MaterializationConflictError, WriteConflictError, WriteRolledBackError, InvalidStateTransitionError, ServiceUnavailableError, PayloadTooLargeError, ResponseUnserializableError, QueryTimeoutError;
 var init_errors = __esm(() => {
   init_constants();
   init_logger();
@@ -176564,6 +176566,12 @@ var init_errors = __esm(() => {
       super(error.message);
     }
   };
+  PackageManifestError = class PackageManifestError extends Error {
+    constructor(message) {
+      super(message);
+      this.name = "PackageManifestError";
+    }
+  };
   MaterializationEligibilityError = class MaterializationEligibilityError extends Error {
     reason;
     constructor(error) {
@@ -176596,6 +176604,12 @@ var init_errors = __esm(() => {
       this.name = "NotQueryableError";
     }
   };
+  OffSurfaceError = class OffSurfaceError extends NotQueryableError {
+    constructor(message) {
+      super(message);
+      this.name = "OffSurfaceError";
+    }
+  };
   MaterializationNotFoundError = class MaterializationNotFoundError extends Error {
     constructor(message) {
       super(message);
@@ -270749,6 +270763,12 @@ function deserializeError(serialized) {
       wrapped.stack = serialized.stack;
     return wrapped;
   }
+  if (serialized.isManifestError) {
+    const manifestError = new PackageManifestError(serialized.message);
+    if (serialized.stack)
+      manifestError.stack = serialized.stack;
+    return manifestError;
+  }
   return err;
 }
 function getPackageLoadPool() {
@@ -270801,11 +270821,11 @@ function recordAuthorizeBypass(entryPoint) {
   });
   bypassCounter.add(1, { entry_point: entryPoint });
 }
-function recordRowLevelGateDecision(decision) {
+function recordRowLevelGateDecision(decision, site = "entry_point") {
   rowLevelDecisionCounter ??= publisherMeter().createCounter("publisher_authorize_row_level_total", {
-    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."
+    description: "How a row-level `#(access_filter)` gate resolved a request. Labels: decision ('denied_by_gate'|'empty_after_filter'), site ('entry_point'|'caller_join'). '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. site says whether the gate was the query's own run target or a source the caller's text joined."
   });
-  rowLevelDecisionCounter.add(1, { decision });
+  rowLevelDecisionCounter.add(1, { decision, site });
 }
 function recordRowLevelGateRejected(cause) {
   rowLevelRejectionCounter ??= publisherMeter().createCounter("publisher_authorize_row_level_rejected_total", {
@@ -270819,11 +270839,11 @@ function recordAuthorizeAdmitAllGate(route) {
   });
   admitAllCounter.add(1, { route });
 }
-function recordLockDecision(decision) {
+function recordLockDecision(decision, site = "entry_point") {
   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."
+    description: "How a `#(authorize)` lock resolved a request. Labels: decision ('admitted'|'denied_by_lock'|'denied_unresolvable'), site ('entry_point'|'caller_join'). 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. site says whether the lock was on the query's own run target or on a source the caller's text joined."
   });
-  lockDecisionCounter.add(1, { decision });
+  lockDecisionCounter.add(1, { decision, site });
 }
 var guardRejectionCounter = null, bypassCounter = null, rowLevelDecisionCounter = null, rowLevelRejectionCounter = null, admitAllCounter = null, lockDecisionCounter = null;
 var init_authorize_metrics = __esm(() => {
@@ -274478,18 +274498,20 @@ function buildPredicate(filter2, value) {
     }
   }
 }
+function filterHasValue(filter2, params) {
+  const value = params[filter2.name];
+  return value !== undefined && value !== null && (Array.isArray(value) ? value.length > 0 : value !== "");
+}
 function buildFilterClause(filters, params) {
   const predicates2 = [];
   for (const filter2 of filters) {
-    const value = params[filter2.name];
-    const hasValue = value !== undefined && value !== null && (Array.isArray(value) ? value.length > 0 : value !== "");
-    if (!hasValue) {
+    if (!filterHasValue(filter2, params)) {
       if (filter2.required) {
         throw new FilterValidationError(`Required filter "${filter2.name}" (dimension: ${filter2.dimension}) was not provided`);
       }
       continue;
     }
-    predicates2.push(buildPredicate(filter2, value));
+    predicates2.push(buildPredicate(filter2, params[filter2.name]));
   }
   if (predicates2.length === 0) {
     return "";
@@ -274605,85 +274627,1051 @@ var init_json_utils = __esm(() => {
 });
 
 // src/service/query_text.ts
+import { ParseUtil } from "@malloydata/malloy-tag";
 function extractRunTargetSourceName(query) {
+  return extractRunTargetSourceNames(query).at(-1);
+}
+function extractRunTargetSourceNames(query) {
   if (!query)
-    return;
-  const runMatch = query.match(/run\s*:\s*(?:`([^`]+)`|(\w+))/);
-  const arrowMatch = query.match(/^\s*(?:`([^`]+)`|(\w+))\s*->/m);
-  return runMatch?.[1] ?? runMatch?.[2] ?? arrowMatch?.[1] ?? arrowMatch?.[2];
+    return [];
+  const tokens = tokenize2(stripMalloyCommentsAndLiterals(query));
+  const targets = [];
+  for (let k = 0;k + 1 < tokens.count; k++) {
+    if (!isWord(tokens, k, "run") || !textIs(tokens, k + 1, ":"))
+      continue;
+    let j = k + 2;
+    while (textIs(tokens, j, "(") && tokens.kind[j] === PUNCT)
+      j++;
+    if (isName(tokens, j))
+      targets.push(textOf(tokens, j));
+  }
+  if (targets.length > 0)
+    return targets;
+  for (let k = 0;k + 2 < tokens.count; k++) {
+    if (isName(tokens, k) && textIs(tokens, k + 1, "-") && textIs(tokens, k + 2, ">") && tokens.start[k + 2] === tokens.start[k + 1] + 1 && opensLine(tokens, k)) {
+      return [textOf(tokens, k)];
+    }
+  }
+  return [];
+}
+function opensLine(tokens, k) {
+  if (k === 0)
+    return true;
+  const from = tokens.end[k - 1];
+  const to = tokens.start[k];
+  for (let at = from;at < to; at++) {
+    const code = tokens.source.charCodeAt(at);
+    if (code === 10 || code === 13)
+      return true;
+  }
+  return false;
+}
+function malloyIdentifiers(text) {
+  return [...scanIdentifiers(stripMalloyCommentsAndLiterals(text))];
 }
 function buildSourceAliasMap(query) {
   const aliasOf = new Map;
-  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(text)) !== null) {
-    aliasOf.set(match[1] ?? match[2], match[3] ?? match[4]);
-  }
+  readDefinitions(query, (keyword, name, base) => {
+    if (keyword === "source" && base !== UNREADABLE_BASE) {
+      aliasOf.set(name, base);
+    }
+  });
   return aliasOf;
 }
 function stripMalloyCommentsAndLiterals(text) {
-  const out = text.split("");
+  if (typeof text !== "string")
+    throw new TypeError("query text must be a string");
+  const parts = [];
+  let copied = 0;
   const blank = (from, to) => {
-    for (let i = from;i < to && i < out.length; i++) {
-      if (out[i] !== `
-`)
-        out[i] = " ";
+    const end = Math.min(to, text.length);
+    if (from >= end)
+      return;
+    parts.push(text.slice(copied, from));
+    let run = from;
+    for (let k = from;k < end; k++) {
+      if (text.charCodeAt(k) < 32) {
+        let slashes = k;
+        while (slashes > run && text.charCodeAt(slashes - 1) === 92)
+          slashes--;
+        parts.push(" ".repeat(slashes - run), text.slice(slashes, k + 1));
+        run = k + 1;
+      }
+    }
+    let tail = end;
+    if (end < text.length && text.charCodeAt(end) < 32) {
+      while (tail > run && text.charCodeAt(tail - 1) === 92)
+        tail--;
+    }
+    parts.push(" ".repeat(tail - run), text.slice(tail, end));
+    copied = end;
+  };
+  const inert = (from, to) => {
+    parts.push(text.slice(copied, from), "~".repeat(to - from));
+    copied = to;
+  };
+  const scan = new StringScan(text);
+  const sqlResume = [];
+  let depth = 0;
+  const sql = (from) => {
+    const stop = sqlStop(text, from);
+    blank(from, stop.bodyEnd);
+    if (stop.opensCode) {
+      sqlResume.push(depth);
+      depth++;
     }
+    return stop.end;
   };
-  for (let i = 0;i < text.length; i++) {
-    const two = text.slice(i, i + 2);
-    if (two === "--" || two === "//") {
-      const nl = text.indexOf(`
-`, i);
-      const end = nl === -1 ? text.length : nl;
-      blank(i, end);
-      i = end;
-      continue;
+  let prefixAt = -1;
+  let blankedSince = -1;
+  const marks = [];
+  const trivia = (from, to) => {
+    blank(from, to);
+    if (prefixAt < 0)
+      return;
+    for (let k = Math.min(to, text.length) - 1;k >= from; k--) {
+      if (text.charCodeAt(k) >= 32) {
+        blankedSince = k;
+        break;
+      }
     }
-    if (two === "/*") {
+  };
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (text.startsWith("--", i) || text.startsWith("//", i) || code === 35) {
+      const end = code === 35 ? skipAnnotation(text, i, trivia) : lineTrivia(text, i, trivia);
+      if (end >= 0) {
+        i = end;
+        continue;
+      }
+    } else if (text.startsWith("/*", i)) {
       const close = text.indexOf("*/", i + 2);
       const end = close === -1 ? text.length : close + 2;
-      blank(i, end);
-      i = end - 1;
+      trivia(i, end);
+      i = end;
       continue;
     }
-    const ch = text[i];
-    if (ch === "`") {
-      const close = text.indexOf("`", i + 1);
-      i = close === -1 ? text.length : close;
+    if (prefixAt >= 0 && !isLexerSpace(code)) {
+      if ((code === 39 || code === 34 || code === 96) && blankedSince >= 0) {
+        marks.push(blankedSince);
+      }
+      prefixAt = -1;
+      blankedSince = -1;
+    }
+    if (code === 123) {
+      depth++;
+      i++;
       continue;
     }
-    if (ch === "'" || ch === '"') {
-      let j = i + 1;
-      while (j < text.length && text[j] !== ch) {
-        if (text[j] === "\\")
-          j++;
-        j++;
+    if (code === 125) {
+      depth--;
+      i++;
+      if (sqlResume.length > 0 && sqlResume[sqlResume.length - 1] === depth) {
+        sqlResume.pop();
+        i = sql(i);
       }
-      blank(i + 1, j);
-      i = j;
       continue;
     }
+    if (text.startsWith('"""', i)) {
+      i = sql(i + 3);
+      continue;
+    }
+    if (code === 39 || code === 34 || code === 96) {
+      const close = scan.stringClose(i);
+      if (close < 0) {
+        i++;
+        continue;
+      }
+      if (code !== 96)
+        blank(i + 1, close);
+      i = close + 1;
+      continue;
+    }
+    const prefixed = scan.prefixedLiteral(i);
+    if (prefixed) {
+      const { open: open2, quote, bodyEnd, end } = prefixed;
+      const tick = text.charCodeAt(open2) === 96;
+      if (tick)
+        inert(open2, open2 + quote);
+      blank(open2 + quote, bodyEnd);
+      if (tick && text.charCodeAt(bodyEnd) === 96)
+        inert(bodyEnd, end);
+      i = end;
+      continue;
+    }
+    const letter = code | 32;
+    if ((letter === 102 || letter === 115) && !continuesToken(text, i)) {
+      prefixAt = i;
+    }
+    i++;
+  }
+  parts.push(text.slice(copied));
+  let out = parts.join("");
+  for (const at of marks)
+    out = `${out.slice(0, at)}~${out.slice(at + 1)}`;
+  return out;
+}
+function lineTrivia(text, i, blank) {
+  const end = toEndOfLine(text, i);
+  if (end >= 0)
+    blank(i, end);
+  return end;
+}
+function lineEnd(text, i) {
+  let at = i;
+  while (at < text.length) {
+    const code = text.charCodeAt(at);
+    if (code === 10 || code === 13)
+      return at;
+    at++;
+  }
+  return at;
+}
+function toEndOfLine(text, i) {
+  const end = lineEnd(text, i);
+  if (text.charCodeAt(end) === 13 && text.charCodeAt(end + 1) !== 10) {
+    return -1;
+  }
+  return end;
+}
+function nextLine(text, i) {
+  const end = lineEnd(text, i);
+  if (text.charCodeAt(end) === 13 && text.charCodeAt(end + 1) === 10) {
+    return end + 2;
+  }
+  return Math.min(end + 1, text.length);
+}
+function skipAnnotation(text, i, blank) {
+  const end = toEndOfLine(text, i);
+  if (end < 0)
+    return -1;
+  const closer = text.startsWith("##|", i) ? "|##" : text.startsWith("#|", i) ? "|#" : undefined;
+  if (!closer) {
+    blank(i, end);
+    return end;
+  }
+  let column = 0;
+  for (let at2 = text.lastIndexOf(`
+`, i - 1) + 1;at2 < i; at2++) {
+    if ((text.charCodeAt(at2) & 64512) !== 56320)
+      column++;
+  }
+  let at = nextLine(text, i);
+  blank(i, at);
+  while (at < text.length) {
+    const closes = closesBlock(text, at, column, closer);
+    const after = nextLine(text, at);
+    blank(at, after);
+    at = after;
+    if (closes)
+      break;
   }
-  return out.join("");
+  return at;
+}
+function closesBlock(text, at, column, closer) {
+  for (let c = 0;c < column; c++) {
+    const code = text.charCodeAt(at + c);
+    if (code !== 32 && code !== 9)
+      return false;
+  }
+  const from = at + column;
+  if (!text.startsWith(closer, from))
+    return false;
+  return closer !== "|#" || text.charCodeAt(from + 2) !== 35;
+}
+function sqlStop(text, from) {
+  const reach = [false, false, false, false];
+  let furthest = from;
+  const mark = (at) => {
+    reach[at & 3] = true;
+    furthest = Math.max(furthest, at);
+  };
+  mark(from);
+  let stop = {
+    bodyEnd: text.length,
+    end: text.length,
+    opensCode: false
+  };
+  let found = false;
+  for (let j = from;j < text.length && j <= furthest; j++) {
+    if (!reach[j & 3])
+      continue;
+    reach[j & 3] = false;
+    const code = text.charCodeAt(j);
+    const next = text.charCodeAt(j + 1);
+    if (code === 34 && next === 34 && text.charCodeAt(j + 2) === 34) {
+      if (!found || j + 3 > stop.end) {
+        stop = { bodyEnd: j, end: j + 3, opensCode: false };
+      }
+      found = true;
+      continue;
+    }
+    if (code === 37 && next === 123) {
+      if (!found || j + 2 > stop.end) {
+        stop = { bodyEnd: j, end: j + 2, opensCode: true };
+      }
+      found = true;
+      continue;
+    }
+    if (code === 92) {
+      mark(j + 1);
+      mark(j + 2);
+    } else if (code === 34) {
+      mark(next === 34 ? j + 3 : j + 2);
+    } else if (code === 37) {
+      mark(j + 2);
+    } else {
+      mark(j + 1);
+    }
+  }
+  return stop;
+}
+function isLexerSpace(code) {
+  return code === 32 || code === 9 || code === 10 || code === 11 || code === 13 || code === 160;
+}
+
+class StringScan {
+  text;
+  stringFailedAt = [-1, -1, -1];
+  tripleUnclosedFrom = [Infinity, Infinity, Infinity];
+  constructor(text) {
+    this.text = text;
+  }
+  stringClose(i) {
+    const text = this.text;
+    const quote = text.charCodeAt(i);
+    const slot = quoteSlot(quote);
+    if (i < this.stringFailedAt[slot])
+      return -1;
+    let j = i + 1;
+    while (j < text.length) {
+      const code = text.charCodeAt(j);
+      if (code === quote)
+        return j;
+      if (code === 92) {
+        if (j + 1 >= text.length || text.charCodeAt(j + 1) === 10)
+          break;
+        j += 2;
+        continue;
+      }
+      if (code < 32 && code !== 9)
+        break;
+      j++;
+    }
+    this.stringFailedAt[slot] = j;
+    return -1;
+  }
+  prefixedLiteral(i) {
+    const text = this.text;
+    const code = text.charCodeAt(i);
+    if (code === 47) {
+      if (text.charCodeAt(i + 1) !== 39)
+        return;
+      return this.raw(i + 1, 39, false);
+    }
+    const letter = code | 32;
+    if (letter !== 102 && letter !== 114 && letter !== 115)
+      return;
+    if (continuesToken(text, i))
+      return;
+    if (letter === 114) {
+      return text.charCodeAt(i + 1) === 39 ? this.raw(i + 1, 39, false) : undefined;
+    }
+    let open2 = i + 1;
+    while (open2 < text.length && isLexerSpace(text.charCodeAt(open2)))
+      open2++;
+    const quote = text.charCodeAt(open2);
+    if (letter === 115) {
+      return quote === 39 || quote === 34 ? this.raw(open2, quote, true) : undefined;
+    }
+    if (quote !== 39 && quote !== 34 && quote !== 96)
+      return;
+    if (text.charCodeAt(open2 + 1) === quote && text.charCodeAt(open2 + 2) === quote) {
+      const close = this.tripleClose(open2 + 3, quote);
+      if (close >= 0) {
+        return { open: open2, quote: 3, bodyEnd: close, end: close + 3 };
+      }
+    }
+    return this.raw(open2, quote, true);
+  }
+  raw(open2, quote, endsAtNewline) {
+    const text = this.text;
+    let j = open2 + 1;
+    while (j < text.length) {
+      const code = text.charCodeAt(j);
+      if (code === 10) {
+        return endsAtNewline ? { open: open2, quote: 1, bodyEnd: j, end: j + 1 } : undefined;
+      }
+      if (code === 92) {
+        if (j + 1 >= text.length || text.charCodeAt(j + 1) === 10) {
+          return;
+        }
+        j += 2;
+        continue;
+      }
+      if (code === quote)
+        return { open: open2, quote: 1, bodyEnd: j, end: j + 1 };
+      j++;
+    }
+    return;
+  }
+  tripleClose(body, quote) {
+    const text = this.text;
+    const slot = quoteSlot(quote);
+    if (body >= this.tripleUnclosedFrom[slot])
+      return -1;
+    let j = body;
+    while (j < text.length) {
+      const code = text.charCodeAt(j);
+      if (code === 92) {
+        j += 2;
+        continue;
+      }
+      if (code === quote && text.charCodeAt(j + 1) === quote && text.charCodeAt(j + 2) === quote) {
+        return j;
+      }
+      j++;
+    }
+    this.tripleUnclosedFrom[slot] = body;
+    return -1;
+  }
+}
+function quoteSlot(quote) {
+  return quote === 39 ? 0 : quote === 34 ? 1 : 2;
+}
+function continuesToken(text, i) {
+  if (i === 0)
+    return false;
+  let at = i - 1;
+  if ((text.charCodeAt(at) & 64512) === 56320 && at > 0)
+    at--;
+  const code = text.charCodeAt(at);
+  return code === 36 || isNameCode(code, text, at);
 }
 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;
-  while ((match = declRe.exec(text)) !== null) {
-    const name = match[1] ?? match[2];
-    const base = match[3] ?? match[4];
-    const bases = basesOf.get(name) ?? new Set;
-    bases.add(base);
-    basesOf.set(name, bases);
+  const out = new Map;
+  readDefinitions(query, (_keyword, name, base) => addEdge(out, name, base));
+  return out;
+}
+function readDefinitions(query, onItem) {
+  const tokens = tokenize2(stripMalloyCommentsAndLiterals(query));
+  let depth = 0;
+  for (let i = 0;i < tokens.count; i++) {
+    if (isPunct(tokens, i, "{"))
+      depth++;
+    else if (isPunct(tokens, i, "}"))
+      depth--;
+    if (depth !== 0 || !isStatementKeyword(tokens, i))
+      continue;
+    const keyword = isWord(tokens, i, "source") ? "source" : isWord(tokens, i, "query") ? "query" : undefined;
+    if (!keyword)
+      continue;
+    readStatementItems(tokens, i + 2, false, (name, base) => onItem(keyword, name, base));
+  }
+}
+function isNameCode(code, text, at) {
+  if (code < 128) {
+    return code >= 48 && code <= 57 || code >= 65 && code <= 90 || code >= 97 && code <= 122 || code === 95;
+  }
+  return NAME_CHAR.test(String.fromCodePoint(text.codePointAt(at)));
+}
+function isSpaceCode(code, text, at) {
+  if (code < 128)
+    return code === 32 || code >= 9 && code <= 13;
+  return SPACE_CHAR.test(String.fromCodePoint(text.codePointAt(at)));
+}
+function unitsAt(text, at) {
+  return text.codePointAt(at) > 65535 ? 2 : 1;
+}
+function tokenize2(text) {
+  const size = text.length + 1;
+  const tokens = {
+    source: text,
+    count: 0,
+    kind: new Uint8Array(size),
+    start: new Int32Array(size),
+    end: new Int32Array(size),
+    partner: new Int32Array(size).fill(-1),
+    decoded: new Map
+  };
+  const push = (kind, start, end) => {
+    const index = tokens.count++;
+    tokens.kind[index] = kind;
+    tokens.start[index] = start;
+    tokens.end[index] = end;
+    return index;
+  };
+  const open2 = [];
+  const scan = new StringScan(text);
+  let i = 0;
+  while (i < text.length) {
+    const code = text.charCodeAt(i);
+    if (isSpaceCode(code, text, i)) {
+      i += unitsAt(text, i);
+      continue;
+    }
+    const close = code === 96 ? scan.stringClose(i) : -1;
+    if (close >= 0) {
+      const index2 = push(QUOTED, i + 1, close);
+      const inner = text.slice(i + 1, close);
+      if (inner.includes("\\")) {
+        tokens.decoded.set(index2, ParseUtil.parseString(inner));
+      }
+      i = close + 1;
+      continue;
+    }
+    if (isNameCode(code, text, i)) {
+      let j = i + unitsAt(text, i);
+      while (j < text.length && isNameCode(text.charCodeAt(j), text, j)) {
+        j += unitsAt(text, j);
+      }
+      push(NAME, i, j);
+      i = j;
+      continue;
+    }
+    const units = unitsAt(text, i);
+    const index = push(PUNCT, i, i + units);
+    if (code === 40 || code === 91 || code === 123) {
+      open2.push(index);
+    } else if (code === 41 || code === 93 || code === 125) {
+      const at = open2.pop();
+      if (at !== undefined) {
+        tokens.partner[at] = index;
+        tokens.partner[index] = at;
+      }
+    }
+    i += units;
+  }
+  return tokens;
+}
+function textOf(tokens, i) {
+  return tokens.decoded.get(i) ?? tokens.source.slice(tokens.start[i], tokens.end[i]);
+}
+function textIs(tokens, i, char) {
+  return i >= 0 && i < tokens.count && tokens.end[i] - tokens.start[i] === 1 && tokens.source.charCodeAt(tokens.start[i]) === char.charCodeAt(0);
+}
+function isPunct(tokens, i, char) {
+  return textIs(tokens, i, char) && tokens.kind[i] === PUNCT;
+}
+function isName(tokens, i) {
+  return i >= 0 && i < tokens.count && tokens.kind[i] !== PUNCT;
+}
+function isWord(tokens, i, word) {
+  if (i < 0 || i >= tokens.count || tokens.kind[i] !== NAME || tokens.end[i] - tokens.start[i] !== word.length) {
+    return false;
+  }
+  const from = tokens.start[i];
+  for (let k = 0;k < word.length; k++) {
+    const code = tokens.source.charCodeAt(from + k);
+    const lower = code >= 65 && code <= 90 ? code + 32 : code;
+    if (lower !== word.charCodeAt(k))
+      return false;
   }
-  return basesOf;
+  return true;
+}
+function isStatementKeyword(tokens, i) {
+  return i < tokens.count && tokens.kind[i] === NAME && textIs(tokens, i + 1, ":") && !textIs(tokens, i + 2, ":") && !textIs(tokens, i - 1, ":") && !textIs(tokens, i - 1, ".");
+}
+function readBase(tokens, i) {
+  let j = i;
+  while (textIs(tokens, j, "(") && tokens.kind[j] === PUNCT)
+    j++;
+  if (!isName(tokens, j) || isLiteralPrefix(tokens, j))
+    return UNREADABLE_BASE;
+  return textOf(tokens, j);
+}
+function isLiteralPrefix(tokens, i) {
+  if (!(isWord(tokens, i, "f") || isWord(tokens, i, "s") || isWord(tokens, i, "r"))) {
+    return false;
+  }
+  return ["'", '"', "`", "~"].some((quote) => isPunct(tokens, i + 1, quote));
+}
+function readStatementItems(tokens, start, shorthand, onItem) {
+  let atItemStart = true;
+  let i = start;
+  while (i < tokens.count) {
+    if (tokens.kind[i] === PUNCT) {
+      if (textIs(tokens, i, ";"))
+        return;
+      if (tokens.partner[i] > i) {
+        i = tokens.partner[i] + 1;
+        atItemStart = false;
+        continue;
+      }
+      if (textIs(tokens, i, ")") || textIs(tokens, i, "]") || textIs(tokens, i, "}")) {
+        return;
+      }
+      atItemStart = textIs(tokens, i, ",");
+      i++;
+      continue;
+    }
+    if (isStatementKeyword(tokens, i))
+      return;
+    let k = i + 1;
+    if (textIs(tokens, k, "(") && tokens.partner[k] > k) {
+      k = tokens.partner[k] + 1;
+    }
+    if (isWord(tokens, k, "is")) {
+      onItem(textOf(tokens, i), readBase(tokens, k + 1));
+      i = k + 1;
+    } else {
+      if (shorthand && atItemStart) {
+        const name = textOf(tokens, i);
+        onItem(name, name);
+      }
+      i++;
+    }
+    atItemStart = false;
+  }
+}
+function addEdge(map, name, base) {
+  const bases = map.get(name) ?? new Set;
+  bases.add(base);
+  map.set(name, bases);
+}
+function buildJoinBaseMap(query) {
+  const out = new Map;
+  const tokens = tokenize2(stripMalloyCommentsAndLiterals(query));
+  for (let i = 0;i < tokens.count; i++) {
+    if (!isStatementKeyword(tokens, i))
+      continue;
+    if (!/^join_(?:one|many|cross)$/i.test(textOf(tokens, i)))
+      continue;
+    readStatementItems(tokens, i + 2, true, (alias, base) => addEdge(out, alias, base));
+  }
+  return out;
+}
+function buildIsEdgeMap(query) {
+  const out = new Map;
+  const tokens = tokenize2(stripMalloyCommentsAndLiterals(query));
+  for (let k = 1;k < tokens.count; k++) {
+    if (!isWord(tokens, k, "is"))
+      continue;
+    let n = k - 1;
+    if (textIs(tokens, n, ")") && tokens.kind[n] === PUNCT && tokens.partner[n] >= 0) {
+      n = tokens.partner[n] - 1;
+    }
+    if (!isName(tokens, n))
+      continue;
+    addEdge(out, textOf(tokens, n), readBase(tokens, k + 1));
+  }
+  return out;
+}
+function scanIdentifiers(text) {
+  const tokens = tokenize2(text);
+  const names = new Set;
+  for (let i = 0;i < tokens.count; i++) {
+    if (isName(tokens, i))
+      names.add(textOf(tokens, i));
+  }
+  return names;
 }
+function collectIdentifierNames(text) {
+  const names = scanIdentifiers(text);
+  for (const name of scanIdentifiers(stripMalloyCommentsAndLiterals(text))) {
+    names.add(name);
+  }
+  return names;
+}
+var UNREADABLE_BASE = "`", PUNCT = 0, NAME = 1, QUOTED = 2, NAME_CHAR, SPACE_CHAR;
+var init_query_text = __esm(() => {
+  NAME_CHAR = /\p{Alphabetic}/u;
+  SPACE_CHAR = /\s/u;
+});
+
+// src/service/caller_joins.ts
+import { isSourceDef as isSourceDef6 } from "@malloydata/malloy";
+function isCallerAuthored(location, region, authorUrls) {
+  const url2 = location?.url;
+  if (url2 === undefined)
+    return true;
+  if (region.kind === "span" && url2 === region.url) {
+    const line = location?.range?.start?.line;
+    return !(typeof line === "number" && line < region.fromLine);
+  }
+  return !authorUrls.has(url2);
+}
+function isSourceJoin(field) {
+  return !!field.join && isSourceDef6(field);
+}
+function aliasOf(field) {
+  return field.as ?? field.name ?? "";
+}
+function contentsStruct(modelDef, name) {
+  const entry = modelDef?.contents[name];
+  return entry && isSourceDef6(entry) ? entry : undefined;
+}
+function runTargetStruct(prepared) {
+  const ref = prepared._query?.structRef;
+  if (typeof ref === "string")
+    return contentsStruct(prepared._modelDef, ref);
+  return ref && typeof ref === "object" ? ref : undefined;
+}
+function collectCallerJoins(prepared, region, authorUrls) {
+  const query = prepared._query;
+  if (!query)
+    throw new CallerJoinWalkError("no compiled query to walk");
+  const isCaller = (location) => isCallerAuthored(location, region, authorUrls);
+  const modelDef = prepared._modelDef;
+  const found = [];
+  const record = (join6, path10, depth) => {
+    if (depth >= CALLER_JOIN_MAX_DEPTH) {
+      throw new CallerJoinWalkError("caller joins nest past the depth bound");
+    }
+    if (found.length >= CALLER_JOIN_MAX_COUNT) {
+      throw new CallerJoinWalkError("too many caller joins");
+    }
+    found.push({ join: join6, alias: aliasOf(join6), path: path10 });
+    walkStruct(join6, path10, depth + 1);
+  };
+  const walkFields = (fields, path10, key, depth, synthesized) => {
+    for (const field of fields ?? []) {
+      const fieldPath = [...path10, key, aliasOf(field)];
+      if (isSourceJoin(field)) {
+        if (field.location?.url === undefined) {
+          if (synthesized)
+            continue;
+          throw new CallerJoinWalkError("a join carries no location");
+        }
+        if (isCaller(field.location))
+          record(field, fieldPath, depth);
+      } else if (field.type === "turtle" && isCaller(field.location)) {
+        walkPipeline(field.pipeline, [...fieldPath, "pipeline"], depth);
+      }
+    }
+  };
+  const walkStruct = (struct, path10, depth) => {
+    const composite = struct.type === "composite";
+    walkFields(struct.fields, path10, "fields", depth, composite);
+    if (composite) {
+      for (const [i, member] of (struct.sources ?? []).entries()) {
+        walkStruct(member, [...path10, "sources", i], depth);
+      }
+    }
+    if (struct.type === "query_source") {
+      walkQuery(struct.query, [...path10, "query"], depth);
+    }
+  };
+  const walkQuery = (q, path10, depth) => {
+    if (!q)
+      return;
+    const ref = q.structRef;
+    const base = typeof ref === "string" ? contentsStruct(modelDef, ref) : ref;
+    if (base && (typeof ref !== "string" || isCaller(base.location))) {
+      walkStruct(base, [...path10, "structRef"], depth);
+    }
+    if (q.compositeResolvedSourceDef) {
+      walkStruct(q.compositeResolvedSourceDef, [...path10, "resolved"], depth);
+    }
+    walkPipeline(q.pipeline, [...path10, "pipeline"], depth);
+  };
+  const walkPipeline = (pipeline, path10, depth) => {
+    for (const [i, segment] of (pipeline ?? []).entries()) {
+      walkFields(segment.extendSource, [...path10, i], "extendSource", depth, false);
+      for (const field of segment.queryFields ?? []) {
+        if (field.type === "turtle") {
+          walkPipeline(field.pipeline, [...path10, i, "queryFields", aliasOf(field), "pipeline"], depth);
+        }
+      }
+    }
+  };
+  const target = runTargetStruct(prepared);
+  if (target)
+    walkStruct(target, ["target"], 0);
+  const resolved = query.compositeResolvedSourceDef;
+  if (resolved) {
+    assertResolvedJoinsAccountedFor(resolved, target, isCaller);
+    walkStruct(resolved, ["resolved"], 0);
+  }
+  walkPipeline(query.pipeline, ["pipeline"], 0);
+  assertEveryCallerJoinPlaced(prepared, found, isCaller);
+  return found;
+}
+function assertResolvedJoinsAccountedFor(resolved, target, isCaller) {
+  const declared = new Set((target?.fields ?? []).filter(isSourceJoin).map((f) => aliasOf(f)));
+  for (const field of resolved.fields ?? []) {
+    if (!isSourceJoin(field) || isCaller(field.location))
+      continue;
+    if (!declared.has(aliasOf(field))) {
+      throw new CallerJoinWalkError("a resolved composite carries a join the declared source does not");
+    }
+  }
+}
+function assertEveryCallerJoinPlaced(prepared, found, isCaller) {
+  const placed = new Set(found.map((f) => f.join));
+  const seen = new Set;
+  let budget = IR_SCAN_MAX_NODES;
+  const stack = [prepared._query, runTargetStruct(prepared)];
+  const modelDef = prepared._modelDef;
+  while (stack.length > 0) {
+    const value = stack.pop();
+    if (!value || typeof value !== "object" || seen.has(value))
+      continue;
+    seen.add(value);
+    if (--budget < 0) {
+      throw new CallerJoinWalkError("compiled query too large to scan");
+    }
+    if (Array.isArray(value)) {
+      for (const item of value)
+        stack.push(item);
+      continue;
+    }
+    const node = value;
+    if (isSourceJoin(node)) {
+      if (!isCaller(node.location))
+        continue;
+      if (!placed.has(node)) {
+        throw new CallerJoinWalkError("a caller join sits where the walk does not look");
+      }
+    }
+    for (const [key, child] of Object.entries(node)) {
+      if (key === "location" || key === "annotations" || key === "outputStruct") {
+        continue;
+      }
+      if (key === "fields" && node.type === "composite")
+        continue;
+      if (key === "structRef" && typeof child === "string") {
+        const named = contentsStruct(modelDef, child);
+        if (named && isCaller(named.location))
+          stack.push(named);
+        continue;
+      }
+      stack.push(child);
+    }
+  }
+}
+function derivationTerminals(start, basesOf, isModelSource, maxNames = DERIVATION_CHAIN_MAX_NAMES) {
+  const seen = new Set;
+  const terminals = [];
+  const worklist = [start];
+  for (let i = 0;i < worklist.length; i++) {
+    const name = worklist[i];
+    if (seen.has(name))
+      continue;
+    seen.add(name);
+    if (seen.size > maxNames)
+      return { proven: false, at: name };
+    if (isModelSource(name)) {
+      terminals.push(name);
+      continue;
+    }
+    const bases = basesOf.get(name);
+    if (!bases || bases.size === 0)
+      return { proven: false, at: name };
+    for (const base of bases)
+      worklist.push(base);
+  }
+  return { proven: true, terminals };
+}
+function resolveCallerJoin(callerJoin, compiledModelDef, region, context) {
+  const names = new Set;
+  const boundaryNames = new Set;
+  const callerSources = [];
+  let composite = false;
+  let curatedQuery;
+  let unprovenAt;
+  let boundaryUnprovenAt;
+  const isCaller = (location) => isCallerAuthored(location, region, context.authorUrls);
+  const text = regionMaps(region);
+  const fail = (at) => {
+    unprovenAt ??= at;
+    return false;
+  };
+  const add = (name, forBoundary) => {
+    names.add(name);
+    if (forBoundary)
+      boundaryNames.add(name);
+  };
+  const chainOf = (start) => derivationTerminals(start, text.derivations(), (name) => context.isModelSource(name));
+  const byContentsKey = (key, forBoundary) => {
+    const entry = contentsStruct(compiledModelDef, key);
+    if (entry && isCaller(entry.location)) {
+      const chain2 = chainOf(key);
+      callerSources.push({ key, struct: entry, chain: chain2 });
+      if (forBoundary) {
+        if (chain2.proven) {
+          for (const name2 of chain2.terminals)
+            boundaryNames.add(name2);
+        } else {
+          boundaryUnprovenAt ??= chain2.at;
+        }
+      }
+      return true;
+    }
+    const name = entry ? aliasOf(entry) : key;
+    if (context.isModelSource(name)) {
+      add(name, forBoundary);
+      return true;
+    }
+    if (entry)
+      return fail(name);
+    const chain = chainOf(key);
+    if (!chain.proven)
+      return fail(chain.at);
+    for (const terminal of chain.terminals)
+      add(terminal, forBoundary);
+    return true;
+  };
+  const isUnmodifiedModelQuery = (q) => {
+    if (!q.name || !context.isModelQuery(q.name))
+      return false;
+    const declared = compiledModelDef.contents[q.name];
+    return declared?.type === "query" && !isCaller(declared.location) && JSON.stringify(q.pipeline) === JSON.stringify(declared.pipeline);
+  };
+  const bySourceID = (sourceID, forBoundary) => {
+    const keys = Object.entries(compiledModelDef.contents).filter(([, value]) => isSourceDef6(value) && value.sourceID === sourceID).map(([key]) => key);
+    if (keys.length === 0)
+      return fail(sourceID);
+    return keys.every((key) => byContentsKey(key, forBoundary));
+  };
+  const resolveStruct = (struct, isJoinItself, forBoundary, depth) => {
+    if (depth > RESOLVE_MAX_DEPTH)
+      return fail(callerJoin.alias);
+    let anchored = false;
+    if (struct.sourceID) {
+      if (!bySourceID(struct.sourceID, forBoundary))
+        return false;
+      anchored = true;
+    }
+    if (struct.type === "composite") {
+      composite = true;
+      const members = struct.sources;
+      if (!Array.isArray(members) || members.length === 0) {
+        return fail(callerJoin.alias);
+      }
+      const membersForBoundary = forBoundary && !struct.sourceID;
+      for (const member of members) {
+        if (!resolveStruct(member, false, membersForBoundary, depth + 1)) {
+          return false;
+        }
+      }
+      anchored = true;
+    }
+    if (struct.type === "query_source") {
+      const q = struct.query;
+      if (isJoinItself && q && isUnmodifiedModelQuery(q)) {
+        curatedQuery = q.name;
+      }
+      const ref = q?.structRef;
+      if (typeof ref === "string") {
+        if (!byContentsKey(ref, forBoundary))
+          return false;
+      } else if (ref && typeof ref === "object") {
+        if (!resolveStruct(ref, false, forBoundary, depth + 1))
+          return false;
+      } else {
+        return fail(callerJoin.alias);
+      }
+      anchored = true;
+    }
+    if (anchored)
+      return true;
+    if (!isJoinItself)
+      return fail(callerJoin.alias);
+    const bases = new Set([
+      ...text.joins().get(callerJoin.alias) ?? [],
+      ...text.isEdges().get(callerJoin.alias) ?? []
+    ]);
+    if (bases.size === 0)
+      return fail(callerJoin.alias);
+    for (const base of bases) {
+      if (!byContentsKey(base, forBoundary))
+        return false;
+    }
+    return true;
+  };
+  if (!resolveStruct(callerJoin.join, true, true, 0)) {
+    return { kind: "unproven", at: unprovenAt ?? callerJoin.alias };
+  }
+  return {
+    kind: "resolved",
+    names,
+    boundaryNames,
+    curatedQuery,
+    composite,
+    callerSources,
+    boundaryUnprovenAt
+  };
+}
+function regionMaps(region) {
+  let maps = regionMapsCache.get(region);
+  if (!maps) {
+    const once = (build) => {
+      let value;
+      return () => value ??= build();
+    };
+    maps = {
+      derivations: once(() => buildDerivationBaseMap(region.text)),
+      joins: once(() => buildJoinBaseMap(region.text)),
+      isEdges: once(() => buildIsEdgeMap(region.text))
+    };
+    regionMapsCache.set(region, maps);
+  }
+  return maps;
+}
+function locateCallerJoin(prepared, path10) {
+  const query = prepared._query;
+  const modelDef = prepared._modelDef;
+  const resolve4 = (ref) => typeof ref === "string" ? contentsStruct(modelDef, ref) : ref;
+  const byAlias = (list, alias) => {
+    const matches = (list ?? []).filter((f) => aliasOf(f) === alias);
+    return matches.length === 1 ? matches[0] : undefined;
+  };
+  let node;
+  if (path10[0] === "target") {
+    node = resolve4(query?.compositeResolvedSourceDef ?? query?.structRef);
+  } else if (path10[0] === "resolved") {
+    node = query?.compositeResolvedSourceDef;
+  } else if (path10[0] === "pipeline") {
+    node = query?.pipeline;
+  } else {
+    return;
+  }
+  let i = 1;
+  while (i < path10.length && node !== undefined && node !== null) {
+    const step = path10[i];
+    if (typeof step === "number") {
+      node = Array.isArray(node) ? node[step] : undefined;
+      i += 1;
+      continue;
+    }
+    const current = node;
+    switch (step) {
+      case "fields":
+      case "extendSource":
+      case "queryFields":
+        node = byAlias(current[step], path10[i + 1]);
+        i += 2;
+        break;
+      case "pipeline":
+      case "query":
+      case "sources":
+        node = current[step];
+        i += 1;
+        break;
+      case "structRef":
+        node = resolve4(current.structRef);
+        i += 1;
+        break;
+      case "resolved":
+        node = current.compositeResolvedSourceDef;
+        i += 1;
+        break;
+      default:
+        return;
+    }
+  }
+  const found = node;
+  return found && typeof found === "object" && isSourceJoin(found) ? found : undefined;
+}
+var CallerJoinWalkError, CALLER_JOIN_MAX_DEPTH = 16, CALLER_JOIN_MAX_COUNT = 256, IR_SCAN_MAX_NODES = 200000, DERIVATION_CHAIN_MAX_NAMES = 64, RESOLVE_MAX_DEPTH = 8, regionMapsCache;
+var init_caller_joins = __esm(() => {
+  init_query_text();
+  CallerJoinWalkError = class CallerJoinWalkError extends Error {
+  };
+  regionMapsCache = new WeakMap;
+});
 
 // src/service/preaggregation_validation.ts
 import {
@@ -274917,10 +275905,430 @@ var init_preaggregation_validation = __esm(() => {
   init_preaggregation_classifier();
 });
 
-// src/service/source_extraction.ts
+// src/service/filter_binding_guard.ts
 import {
   isJoined as isJoined4,
-  isSourceDef as isSourceDef6,
+  isSourceDef as isSourceDef7
+} from "@malloydata/malloy";
+function nextDerivationLink(current, modelDef, seen) {
+  const declared = resolveDeclaredSource(current, modelDef);
+  if (declared.kind === "resolved" && !seen.has(declared.source)) {
+    return declared.source;
+  }
+  if (declared.kind === "none") {
+    const viaIdentity = findSourceByOwnAnnotationIdentity(current, modelDef, new Set(seen));
+    if (viaIdentity && !seen.has(viaIdentity))
+      return viaIdentity;
+    const viaQuerySource = resolveQuerySourceBase(current, modelDef);
+    if (viaQuerySource && !seen.has(viaQuerySource))
+      return viaQuerySource;
+  }
+  return;
+}
+function activeName2(f) {
+  return f.as ?? f.name;
+}
+function deepEqualIgnoring(a, b) {
+  return JSON.stringify(strip(a)) === JSON.stringify(strip(b));
+}
+function strip(value) {
+  if (Array.isArray(value))
+    return value.map(strip);
+  if (value && typeof value === "object") {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      if (IGNORED_KEYS.has(k))
+        continue;
+      out[k] = strip(v);
+    }
+    return out;
+  }
+  return value;
+}
+function fieldsIdentical(a, b) {
+  if (!a || !b)
+    return false;
+  if (a.name !== b.name || a.type !== b.type)
+    return false;
+  if (!deepEqualIgnoring(a.e, b.e))
+    return false;
+  if (isJoined4(a) || isJoined4(b)) {
+    if (!isJoined4(a) || !isJoined4(b))
+      return false;
+    if (a.join !== b.join)
+      return false;
+    if (!deepEqualIgnoring(a.onExpression, b.onExpression))
+      return false;
+  }
+  return true;
+}
+function resolveFieldByPath(struct, path10) {
+  let current = struct;
+  let field;
+  for (let i = 0;i < path10.length; i++) {
+    if (!current)
+      return;
+    field = current.fields?.find((f) => activeName2(f) === path10[i]);
+    if (!field)
+      return;
+    if (i < path10.length - 1) {
+      if (!isJoined4(field))
+        return;
+      current = field;
+    }
+  }
+  return field;
+}
+function fieldPathIdentical(declaring, executed, path10) {
+  let dCur = declaring;
+  let eCur = executed;
+  for (let i = 0;i < path10.length; i++) {
+    const name = path10[i];
+    const dField = dCur?.fields?.find((f) => activeName2(f) === name);
+    const eField = eCur?.fields?.find((f) => activeName2(f) === name);
+    if (!fieldsIdentical(dField, eField))
+      return false;
+    if (i < path10.length - 1) {
+      if (!dField || !isJoined4(dField) || !eField || !isJoined4(eField)) {
+        return false;
+      }
+      dCur = dField;
+      eCur = eField;
+    }
+  }
+  return true;
+}
+function fieldUsageClosure(declaring, refSummary) {
+  const seen = new Set;
+  const paths = [];
+  const queue = (refSummary?.fieldUsage ?? []).map((u) => [...u.path]);
+  while (queue.length > 0) {
+    if (paths.length >= MAX_CLOSURE_SIZE)
+      return { paths, truncated: true };
+    const path10 = queue.shift();
+    if (!path10)
+      break;
+    const key = path10.join("\x00");
+    if (seen.has(key))
+      continue;
+    seen.add(key);
+    paths.push(path10);
+    const field = resolveFieldByPath(declaring, path10);
+    const nested = field?.refSummary;
+    const prefix = path10.slice(0, -1);
+    for (const u of nested?.fieldUsage ?? []) {
+      queue.push([...prefix, ...u.path]);
+    }
+  }
+  return { paths, truncated: false };
+}
+function assertFilterConditionBindsToDeclaringSource(declaringStruct, executedStruct, condition) {
+  const { paths, truncated } = fieldUsageClosure(declaringStruct, condition.refSummary);
+  if (truncated) {
+    throw new Error("a row-security filter's field-usage closure exceeded the resolution bound");
+  }
+  for (const path10 of paths) {
+    if (!fieldPathIdentical(declaringStruct, executedStruct, path10)) {
+      throw new Error(`a row-security filter references \`${path10.join(".")}\`, which resolves to a different field on the executed source`);
+    }
+  }
+}
+function assertFilterDimensionBindsToDeclaringSource(declaringStruct, executedStruct, dimension) {
+  const { paths, truncated } = fieldUsageClosure(declaringStruct, {
+    fieldUsage: [{ path: [dimension] }]
+  });
+  if (truncated) {
+    throw new Error("a #(filter) dimension's field-usage closure exceeded the resolution bound");
+  }
+  for (const path10 of paths) {
+    if (!fieldPathIdentical(declaringStruct, executedStruct, path10)) {
+      throw new Error(`a #(filter) dimension references \`${path10.join(".")}\`, which resolves to a different field on the executed source`);
+    }
+  }
+}
+function isEarlierPosition(a, b) {
+  return a.line < b.line || a.line === b.line && a.character < b.character;
+}
+function allAnnotationNotes(annotations, depth = 0) {
+  if (!annotations || depth > ANCESTOR_WALK_MAX_DEPTH)
+    return [];
+  return [
+    ...annotations.blockNotes ?? [],
+    ...annotations.notes ?? [],
+    ...allAnnotationNotes(annotations.inherits, depth + 1)
+  ];
+}
+function ownLevelNotes2(annotations) {
+  return [...annotations?.blockNotes ?? [], ...annotations?.notes ?? []];
+}
+function findNoteOwner(notes, modelDef) {
+  for (const note of notes) {
+    if (!note.at)
+      continue;
+    let best;
+    for (const value of Object.values(modelDef.contents)) {
+      if (!isSourceDef7(value) || !value.location)
+        continue;
+      if (!ownLevelNotes2(value.annotations).includes(note))
+        continue;
+      if (value.location.url !== note.at.url)
+        continue;
+      if (!best?.location || isEarlierPosition(value.location.range.start, best.location.range.start)) {
+        best = value;
+      }
+    }
+    if (best)
+      return best;
+  }
+  return;
+}
+function isGateNote(note) {
+  try {
+    return parseAuthorizeAnnotation(note.text) !== null;
+  } catch {
+    return false;
+  }
+}
+function findAnnotationDeclaringSource(struct, modelDef, resolveSibling) {
+  const notes = allAnnotationNotes(struct.annotations).filter(isGateNote);
+  const viaNotes = findNoteOwner(notes, modelDef);
+  if (viaNotes)
+    return viaNotes;
+  let current = struct;
+  const seen = new Set([struct]);
+  for (let depth = 0;depth < ANCESTOR_WALK_MAX_DEPTH; depth++) {
+    const next = nextDerivationLink(current, modelDef, seen);
+    if (!next)
+      break;
+    if (ownLevelNotes2(next.annotations).some(isGateNote))
+      return next;
+    seen.add(next);
+    current = next;
+  }
+  for (const note of notes) {
+    const sibling = findSiblingAnnotationDeclaringSource(note, resolveSibling);
+    if (sibling)
+      return sibling;
+  }
+  return findCompositeMemberDeclaringSource(struct, modelDef);
+}
+function findCompositeMemberDeclaringSource(struct, modelDef) {
+  const member = resolveCompositeResolvedBase(struct);
+  if (!member)
+    return;
+  if (ownLevelNotes2(member.annotations).some(isGateNote))
+    return member;
+  let current = member;
+  const seen = new Set([member]);
+  for (let depth = 0;depth < ANCESTOR_WALK_MAX_DEPTH; depth++) {
+    const next = nextDerivationLink(current, modelDef, seen);
+    if (!next)
+      break;
+    if (ownLevelNotes2(next.annotations).some(isGateNote))
+      return next;
+    seen.add(next);
+    current = next;
+  }
+  return;
+}
+function findFilterAnnotationDeclaringSource(struct, modelDef, filter2, parseAnnotation2, resolveSibling) {
+  const matches = (notes) => notes.filter((note) => {
+    let parsed;
+    try {
+      parsed = parseAnnotation2(note.text);
+    } catch {
+      return false;
+    }
+    return !!parsed && parsed.dimension === filter2.dimension && parsed.type === filter2.type && parsed.name === filter2.name;
+  });
+  const matched = matches(allAnnotationNotes(struct.annotations));
+  const viaNotes = findNoteOwner(matched, modelDef);
+  if (viaNotes)
+    return viaNotes;
+  let current = struct;
+  const seen = new Set([struct]);
+  for (let depth = 0;depth < ANCESTOR_WALK_MAX_DEPTH; depth++) {
+    const next = nextDerivationLink(current, modelDef, seen);
+    if (!next)
+      break;
+    if (matches(ownLevelNotes2(next.annotations)).length > 0)
+      return next;
+    seen.add(next);
+    current = next;
+  }
+  for (const note of matched) {
+    const sibling = findSiblingAnnotationDeclaringSource(note, resolveSibling);
+    if (sibling)
+      return sibling;
+  }
+  return;
+}
+function assertGraftedGateBindsToDeclaringSource(entryPointStruct, executedStruct, condition, modelDef, resolveSibling) {
+  if (!entryPointStruct) {
+    throw new Error("a row-security gate's entry point could not be resolved");
+  }
+  const declaring = findAnnotationDeclaringSource(entryPointStruct, modelDef, resolveSibling);
+  if (!declaring) {
+    throw new Error("a row-security gate's declaring source could not be resolved");
+  }
+  assertFilterConditionBindsToDeclaringSource(declaring, executedStruct, condition);
+}
+function rangesEqual(a, b) {
+  return a.start.line === b.start.line && a.start.character === b.start.character && a.end.line === b.end.line && a.end.character === b.end.character;
+}
+function locationContains(outer, inner) {
+  if (outer.url !== inner.url)
+    return false;
+  if (isEarlierPosition(inner.range.start, outer.range.start))
+    return false;
+  if (isEarlierPosition(outer.range.end, inner.range.end))
+    return false;
+  return true;
+}
+function spanSize(range) {
+  return (range.end.line - range.start.line) * 1e5 + (range.end.character - range.start.character);
+}
+function findConditionOriginByLocation(modelDef, at) {
+  let best;
+  let bestSpan = Infinity;
+  for (const value of Object.values(modelDef.contents)) {
+    if (!isSourceDef7(value) || !value.location)
+      continue;
+    if (!locationContains(value.location, at)) {
+      continue;
+    }
+    const span = spanSize(value.location.range);
+    if (span < bestSpan) {
+      best = value;
+      bestSpan = span;
+    }
+  }
+  return best;
+}
+function findSiblingDeclaringSource(at, resolveSibling) {
+  if (!at || !resolveSibling)
+    return;
+  const siblingModelDef = resolveSibling(at.url);
+  if (!siblingModelDef)
+    return;
+  return findConditionOriginByLocation(siblingModelDef, at);
+}
+function findSiblingAnnotationDeclaringSource(note, resolveSibling) {
+  if (!note?.at || !resolveSibling)
+    return;
+  const siblingModelDef = resolveSibling(note.at.url);
+  if (!siblingModelDef)
+    return;
+  for (const value of Object.values(siblingModelDef.contents)) {
+    if (!isSourceDef7(value))
+      continue;
+    for (const candidate of ownLevelNotes2(value.annotations)) {
+      if (candidate.at && candidate.at.url === note.at.url && rangesEqual(candidate.at.range, note.at.range)) {
+        return value;
+      }
+    }
+  }
+  return;
+}
+function firstFieldUsageLocation(condition) {
+  const refSummary = condition.refSummary;
+  const first2 = refSummary?.fieldUsage?.[0];
+  return first2?.at;
+}
+function findFilterOrigin(struct, condition, modelDef, resolveSibling) {
+  let origin2 = struct;
+  let current = struct;
+  const seen = new Set([struct]);
+  for (let depth = 0;depth < ANCESTOR_WALK_MAX_DEPTH; depth++) {
+    let next = modelDef ? nextDerivationLink(current, modelDef, seen) : undefined;
+    if (!next && modelDef) {
+      const at = firstFieldUsageLocation(condition);
+      if (at) {
+        const candidate = findConditionOriginByLocation(modelDef, at);
+        if (candidate && !seen.has(candidate))
+          next = candidate;
+      }
+    }
+    if (!next || !next.filterList?.includes(condition))
+      break;
+    origin2 = next;
+    seen.add(next);
+    current = next;
+  }
+  if (origin2 === struct) {
+    const sibling = findSiblingDeclaringSource(firstFieldUsageLocation(condition), resolveSibling);
+    if (sibling && siblingCandidateOwnsCondition(sibling, condition)) {
+      return sibling;
+    }
+  }
+  return origin2;
+}
+function siblingCandidateOwnsCondition(candidate, condition) {
+  const at = firstFieldUsageLocation(condition);
+  if (!at)
+    return false;
+  return !!candidate.filterList?.some((c) => {
+    if (c.code !== condition.code)
+      return false;
+    const candidateAt = firstFieldUsageLocation(c);
+    return !!candidateAt && candidateAt.url === at.url && rangesEqual(candidateAt.range, at.range);
+  });
+}
+function conditionReadsNoField(condition) {
+  const refSummary = condition.refSummary;
+  return !refSummary?.fieldUsage || refSummary.fieldUsage.length === 0;
+}
+function isOwnFreshFilter(struct, condition, freshness) {
+  const at = firstFieldUsageLocation(condition);
+  if (!at)
+    return false;
+  const structLocation = struct.location;
+  if (structLocation && locationContains(structLocation, at))
+    return true;
+  if (freshness.queryLocation && locationContains(freshness.queryLocation, at)) {
+    return true;
+  }
+  return !!freshness.compiledUrl && at.url === freshness.compiledUrl;
+}
+function assertInheritedSourceFiltersBind(struct, modelDef, freshness = {}, resolveSibling = undefined, depth = 0, visited = new Set, alreadyProven = new Set) {
+  if (visited.has(struct))
+    return;
+  if (depth > MAX_JOIN_RECURSION_DEPTH) {
+    throw new Error("row-security filter recursion exceeded the join-depth resolution bound");
+  }
+  visited.add(struct);
+  for (const condition of struct.filterList ?? []) {
+    if (alreadyProven.has(condition))
+      continue;
+    if (conditionReadsNoField(condition))
+      continue;
+    const origin2 = findFilterOrigin(struct, condition, modelDef, resolveSibling);
+    if (origin2 !== struct) {
+      assertFilterConditionBindsToDeclaringSource(origin2, struct, condition);
+      continue;
+    }
+    if (isOwnFreshFilter(struct, condition, freshness))
+      continue;
+    throw new Error("a row-security filter's declaring source could not be resolved");
+  }
+  for (const field of struct.fields ?? []) {
+    if (isJoined4(field) && isSourceDef7(field)) {
+      assertInheritedSourceFiltersBind(field, modelDef, freshness, resolveSibling, depth + 1, visited, alreadyProven);
+    }
+  }
+}
+var MAX_CLOSURE_SIZE = 256, MAX_JOIN_RECURSION_DEPTH = 16, IGNORED_KEYS;
+var init_filter_binding_guard = __esm(() => {
+  init_gate_registry_walk();
+  init_gate_classification();
+  init_authorize();
+  IGNORED_KEYS = new Set(["location", "annotations", "accessModifier"]);
+});
+
+// src/service/source_extraction.ts
+import {
+  isJoined as isJoined5,
+  isSourceDef as isSourceDef8,
   modelDefToModelInfo
 } from "@malloydata/malloy";
 function joinFieldNamesUnresolvableDeclaration(field, modelDef) {
@@ -274932,12 +276340,12 @@ function joinFieldNamesUnresolvableDeclaration(field, modelDef) {
     if (!entry)
       continue;
     const declared = entry.type === "source_registry_reference" ? modelDef.contents[entry.name] : entry;
-    if (declared && isSourceDef6(declared))
+    if (declared && isSourceDef8(declared))
       return false;
   }
   return true;
 }
-function isEarlierPosition(a, b) {
+function isEarlierPosition2(a, b) {
   return a.line < b.line || a.line === b.line && a.character < b.character;
 }
 function considerNoteOwner(declaredBy, note, candidate) {
@@ -274945,12 +276353,12 @@ function considerNoteOwner(declaredBy, note, candidate) {
   if (!location || location.url !== note.at.url)
     return;
   const currentLocation = declaredBy.get(note)?.location;
-  if (!currentLocation || isEarlierPosition(location.range.start, currentLocation.range.start)) {
+  if (!currentLocation || isEarlierPosition2(location.range.start, currentLocation.range.start)) {
     declaredBy.set(note, candidate);
   }
 }
 function collectSourceInfos(modelDef) {
-  const names = Object.keys(modelDef.contents).filter((name) => isSourceDef6(modelDef.contents[name]));
+  const names = Object.keys(modelDef.contents).filter((name) => isSourceDef8(modelDef.contents[name]));
   const exports = [...new Set([...modelDef.exports, ...names])];
   return modelDefToModelInfo({ ...modelDef, exports }).entries.filter((entry) => entry.kind === "source");
 }
@@ -274963,7 +276371,7 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
   const nearMissAuthorize = [];
   const sweptStructs = [];
   for (const obj of Object.values(modelDef.contents)) {
-    if (!isSourceDef6(obj))
+    if (!isSourceDef8(obj))
       continue;
     const struct = obj;
     sweptStructs.push(obj);
@@ -274982,7 +276390,7 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
     const entry = value.entry;
     if (entry.type === "source_registry_reference")
       continue;
-    if (!isSourceDef6(entry))
+    if (!isSourceDef8(entry))
       continue;
     sweptStructs.push(entry);
     for (const note of ownLevelNotes(entry.annotations)) {
@@ -275015,7 +276423,7 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
       });
     }
   }
-  const sources = Object.values(modelDef.contents).filter((obj) => isSourceDef6(obj)).map((sourceObj) => {
+  const sources = Object.values(modelDef.contents).filter((obj) => isSourceDef8(obj)).map((sourceObj) => {
     const struct = sourceObj;
     const sourceName = struct.as || struct.name;
     const annotations = annotationTexts(struct.annotations);
@@ -275090,7 +276498,7 @@ function extractSourcesFromModelDef(modelDef, givens, onParseError) {
         continue;
       }
       const fieldName2 = field.as || field.name;
-      if (isJoined4(field) && isSourceDef6(field)) {
+      if (isJoined5(field) && isSourceDef8(field)) {
         const joinedStruct = field;
         if (joinFieldNamesUnresolvableDeclaration(joinedStruct, modelDef)) {
           continue;
@@ -275259,7 +276667,7 @@ import {
   API,
   FixedConnectionMap,
   InMemoryURLReader as InMemoryURLReader2,
-  isSourceDef as isSourceDef7,
+  isSourceDef as isSourceDef9,
   MalloyConfig as MalloyConfig2,
   MalloyError as MalloyError4,
   Annotations as Annotations6,
@@ -275275,18 +276683,18 @@ 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) {
+function denyUnlessAdmitted(resolution, givens, label, site = "entry_point") {
   if (resolution.shape === "lock") {
     const outcome = decideLock(resolution.condition.e, (id) => resolution.givenNamesById.get(id), givens);
     if (outcome === "admit") {
-      recordLockDecision("admitted");
+      recordLockDecision("admitted", site);
       return;
     }
-    recordLockDecision(outcome === "unresolvable" ? "denied_unresolvable" : "denied_by_lock");
+    recordLockDecision(outcome === "unresolvable" ? "denied_unresolvable" : "denied_by_lock", site);
     throw new AccessDeniedError(`Access denied for source "${label}".`);
   }
-  recordLockDecision("denied_unresolvable");
-  recordRowLevelGateDecision("denied_by_gate");
+  recordLockDecision("denied_unresolvable", site);
+  recordRowLevelGateDecision("denied_by_gate", site);
   if (resolution.cause)
     recordRowLevelGateRejected(resolution.cause);
   throw new AccessDeniedError(`Access denied for source "${label}".`);
@@ -275359,7 +276767,41 @@ function hydrateMarkdownOnlyCells(notebookCells) {
     return { type: "code", text: sc.text };
   });
 }
-var MALLOY_VERSION, REQUEST_CHAIN_MAX_NAMES = 64, NO_PREAGGREGATE_VIOLATIONS, Model;
+function scrubHiddenIds(def, published) {
+  const hidden = (id) => typeof id === "string" && !published.has(id.split("@")[0]);
+  const walk2 = (value) => {
+    if (Array.isArray(value))
+      return value.map(walk2);
+    if (!value || typeof value !== "object")
+      return value;
+    const record = value;
+    if (typeof record.join === "string" && (hidden(record.sourceID) || hidden(record.referenceID))) {
+      return joinOutline(record);
+    }
+    const out = {};
+    for (const [key, inner] of Object.entries(record)) {
+      if (SOURCE_IDENTITY_KEYS.has(key) && hidden(inner))
+        continue;
+      out[key] = walk2(inner);
+    }
+    return out;
+  };
+  return walk2(def);
+}
+function joinOutline(field) {
+  const name = field.as ?? field.name;
+  if (typeof field.join !== "string") {
+    return { type: field.type, name };
+  }
+  const fields = Array.isArray(field.fields) ? field.fields : [];
+  return {
+    type: field.type,
+    join: field.join,
+    name,
+    fields: fields.map((inner) => inner && typeof inner === "object" ? joinOutline(inner) : inner)
+  };
+}
+var MALLOY_VERSION, REQUEST_CHAIN_MAX_NAMES = 64, NO_PREAGGREGATE_VIOLATIONS, Model, SOURCE_IDENTITY_KEYS;
 var init_model = __esm(() => {
   init_telemetry();
   init_materialization_metrics();
@@ -275387,9 +276829,12 @@ var init_model = __esm(() => {
   init_motly();
   init_model_limits();
   init_json_utils();
+  init_query_text();
+  init_caller_joins();
   init_query_metadata();
   init_preaggregation_validation();
   init_gate_registry_walk();
+  init_filter_binding_guard();
   init_gate_classification();
   init_source_extraction();
   init_authorize_metrics();
@@ -275423,7 +276868,9 @@ var init_model = __esm(() => {
     preaggregateViolationsMemo;
     authorizeReferencedGivenNames = new Set;
     discoveryCurationEnabled = false;
+    siblingModelDefResolver;
     queryBoundary = { mode: "all", exploresDeclared: false, isQueryEntryPoint: true };
+    fileDerivationBases;
     freshnessResolver;
     preaggregateEntityIdResolver;
     entryPointGatesBySource = new Map;
@@ -275431,7 +276878,7 @@ var init_model = __esm(() => {
     gateClassificationDepsCache;
     graftedMaterializerCache = new Map;
     static GRAFTED_MATERIALIZER_CACHE_MAX = 32;
-    rowLevelFilteredRunnables = new WeakSet;
+    rowLevelFilteredRunnables = new WeakMap;
     meter = publisherMeter();
     queryExecutionHistogram = this.meter.createHistogram("malloy_model_query_duration", {
       description: "How long it takes to execute a Malloy model query",
@@ -275580,7 +277027,7 @@ var init_model = __esm(() => {
       if (!modelDef)
         return byName;
       for (const entry of Object.values(modelDef.contents)) {
-        if (!isSourceDef7(entry))
+        if (!isSourceDef9(entry))
           continue;
         const name = entry.as ?? entry.name;
         byName.set(name, this.collectEntryPointGates(entry, modelDef, new Set, true));
@@ -275619,14 +277066,14 @@ var init_model = __esm(() => {
     reachableStructsForNoteSweep(modelDef) {
       const structs = [];
       for (const obj of Object.values(modelDef.contents)) {
-        if (isSourceDef7(obj))
+        if (isSourceDef9(obj))
           structs.push(obj);
       }
       for (const value of Object.values(modelDef.sourceRegistry ?? {})) {
         const entry = value.entry;
         if (entry.type === "source_registry_reference")
           continue;
-        if (isSourceDef7(entry))
+        if (isSourceDef9(entry))
           structs.push(entry);
       }
       structs.push(...derivedStructsReachable(structs, modelDef));
@@ -275660,7 +277107,11 @@ var init_model = __esm(() => {
     async assertAuthorizedForAllSources(runnable, givens, bypassAuthorize = false, options) {
       await this.authorizeAndBindRunnable(runnable, givens, {
         bypassAuthorize,
-        checkOnly: options?.checkOnly
+        checkOnly: options?.checkOnly,
+        callerJoins: options?.callerRegion ? {
+          runnable,
+          region: options.callerRegion
+        } : undefined
       });
     }
     async collectAuthorizeEntryPointGates(runnable, givens, graftScope, skipOwnSourceGate = false) {
@@ -275716,7 +277167,7 @@ var init_model = __esm(() => {
       }
       return rowLevel;
     }
-    async queryEntryPointHasRowLevelGate(runnable) {
+    async queryEntryPointHasRowLevelGate(runnable, callerRegion) {
       try {
         const { struct, modelDef, compositeResolvedSourceDef } = await this.resolveRunTargetStruct(runnable);
         if (!modelDef)
@@ -275726,7 +277177,15 @@ var init_model = __esm(() => {
         if (compositeResolvedSourceDef) {
           gates.push(...this.collectEntryPointGates(compositeResolvedSourceDef, modelDef, seen, true, undefined, struct ? ownLevelNotes(struct.annotations) : []));
         }
-        return gates.length > 0;
+        if (gates.length > 0)
+          return true;
+        if (!callerRegion)
+          return false;
+        const callerJoins = await this.resolvedCallerJoins(runnable, callerRegion);
+        if (!callerJoins)
+          return true;
+        const gated = (name) => (this.entryPointGatesBySource.get(name)?.length ?? 0) > 0;
+        return callerJoins.some(({ resolution, compiledModelDef }) => resolution.kind === "unproven" || Array.from(resolution.names).some(gated) || resolution.callerSources.some((source) => !source.chain.proven || source.chain.terminals.some(gated) || this.collectEntryPointGates(source.struct, compiledModelDef, new Set, true).length > 0));
       } catch {
         return true;
       }
@@ -275739,7 +277198,7 @@ var init_model = __esm(() => {
         return;
       if (this.entryPointGatesBySource.has(entryPoint))
         return;
-      const proof = this.requestChainProvesUngated(entryPoint, buildDerivationBaseMap(stripMalloyCommentsAndLiterals(query)));
+      const proof = this.requestChainProvesUngated(entryPoint, buildDerivationBaseMap(query));
       if (proof.proven) {
         for (const base of proof.gatedBases) {
           for (const entry of this.entryPointGatesBySource.get(base) ?? []) {
@@ -275757,7 +277216,7 @@ var init_model = __esm(() => {
     async assertLocksOnRequestDeclaredBases(entryPoint, query, givens, bypassAuthorize) {
       if (!this.declaresAnyGate())
         return;
-      const basesOf = buildDerivationBaseMap(stripMalloyCommentsAndLiterals(query));
+      const basesOf = buildDerivationBaseMap(query);
       const seen = new Set;
       const worklist = entryPoint ? [entryPoint] : [...basesOf.keys()];
       for (let i = 0;i < worklist.length; i++) {
@@ -275765,8 +277224,6 @@ var init_model = __esm(() => {
         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);
@@ -275793,65 +277250,297 @@ var init_model = __esm(() => {
       return this.declaresAnyGateMemo;
     }
     requestChainProvesUngated(entryPoint, basesOf) {
-      const seen = new Set;
-      const gatedBases = [];
-      const worklist = [entryPoint];
-      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 { proven: false, reason: "chain_not_established", at: name };
+      const chain = derivationTerminals(entryPoint, basesOf, (name) => this.entryPointGatesBySource.has(name), REQUEST_CHAIN_MAX_NAMES);
+      if (!chain.proven) {
+        return {
+          proven: false,
+          reason: "chain_not_established",
+          at: chain.at
+        };
+      }
+      return {
+        proven: true,
+        gatedBases: chain.terminals.filter((name) => (this.entryPointGatesBySource.get(name)?.length ?? 0) > 0)
+      };
+    }
+    resolvedCallerJoins(runnable, region) {
+      const cached2 = this.callerJoinResolutions.get(runnable);
+      if (cached2 && cached2.region === region)
+        return cached2.result;
+      const result = this.computeCallerJoins(runnable, region);
+      this.callerJoinResolutions.set(runnable, { region, result });
+      return result;
+    }
+    callerJoinResolutions = new WeakMap;
+    async computeCallerJoins(runnable, region) {
+      let prepared;
+      try {
+        prepared = await runnable.getPreparedQuery();
+      } catch {
+        return;
+      }
+      const compiledModelDef = prepared._modelDef;
+      if (!compiledModelDef) {
+        throw new CallerJoinWalkError("the compiled query carries no model");
+      }
+      const authorUrls = this.authorUrls();
+      const context = {
+        isModelSource: (name) => this.entryPointGatesBySource.has(name),
+        isModelQuery: (name) => this.modelDef?.contents[name]?.type === "query",
+        authorUrls
+      };
+      return collectCallerJoins(prepared, region, authorUrls).map((callerJoin) => ({
+        callerJoin,
+        compiledModelDef,
+        resolution: resolveCallerJoin(callerJoin, compiledModelDef, region, context)
+      }));
+    }
+    authorUrlsMemo;
+    authorUrls() {
+      if (this.authorUrlsMemo)
+        return this.authorUrlsMemo;
+      const urls = new Set;
+      const modelDef = this.modelDef;
+      if (modelDef) {
+        urls.add(modelDef.modelID);
+        for (const url2 of Object.keys(modelDef.modelAnnotations ?? {})) {
+          urls.add(url2);
+        }
+        for (const imported of modelDef.imports ?? []) {
+          urls.add(imported.importURL);
         }
-        const modelGates = this.entryPointGatesBySource.get(name);
-        if (modelGates !== undefined) {
-          if (modelGates.length > 0)
-            gatedBases.push(name);
+        const walk2 = (tree) => {
+          for (const [url2, deps] of Object.entries(tree ?? {})) {
+            urls.add(url2);
+            walk2(deps);
+          }
+        };
+        walk2(modelDef.dependencies);
+        for (const entry of Object.values(modelDef.contents)) {
+          const url2 = entry?.location?.url;
+          if (url2)
+            urls.add(url2);
+        }
+      }
+      this.authorUrlsMemo = urls;
+      return urls;
+    }
+    async decideCallerSource(source, compiledModelDef, alias, givens, graftScope) {
+      const gates = this.collectEntryPointGates(source.struct, compiledModelDef, new Set, true);
+      if (gates.length > 0) {
+        return Promise.all(gates.map((entry) => this.resolveGateShape(entry, compiledModelDef, graftScope)));
+      }
+      if (!source.chain.proven) {
+        this.denyCallerJoin(alias, "chain_not_established", source.chain.at);
+      }
+      for (const base of source.chain.terminals) {
+        for (const entry of this.entryPointGatesBySource.get(base) ?? []) {
+          const shape = this.modelDef ? await this.resolveGateShape(entry, this.modelDef, graftScope) : { shape: "rejected", cause: undefined };
+          if (shape.shape === "row_level") {
+            this.denyCallerJoin(alias, "row_filter_not_graftable", base);
+          }
+          denyUnlessAdmitted(shape, givens, alias, "caller_join");
+        }
+      }
+      return [];
+    }
+    async probeCallerJoinGates(runnable, region, givens, graftScope) {
+      if (!this.declaresAnyGate())
+        return [];
+      let resolved;
+      try {
+        resolved = await this.resolvedCallerJoins(runnable, region);
+      } catch (err) {
+        this.denyCallerJoin(await this.resolveAuthorizeSourceFromRunnable(runnable) ?? "query", "walk_incomplete", err instanceof Error ? err.message : String(err));
+      }
+      if (!resolved)
+        return [];
+      const grafts = [];
+      for (const { callerJoin, compiledModelDef, resolution } of resolved) {
+        const alias = callerJoin.alias;
+        if (resolution.kind === "unproven") {
+          this.denyCallerJoin(alias, "chain_not_established", resolution.at);
+        }
+        const shapes = [];
+        for (const name of resolution.names) {
+          for (const entry of this.entryPointGatesBySource.get(name) ?? []) {
+            shapes.push({
+              at: name,
+              shape: this.modelDef ? await this.resolveGateShape(entry, this.modelDef, graftScope) : { shape: "rejected", cause: undefined }
+            });
+          }
+        }
+        for (const source of resolution.callerSources) {
+          for (const shape of await this.decideCallerSource(source, compiledModelDef, alias, givens, graftScope)) {
+            shapes.push({ at: source.key, shape });
+          }
+        }
+        for (const { at, shape } of shapes) {
+          if (shape.shape === "row_level") {
+            if (resolution.composite) {
+              this.denyCallerJoin(alias, "row_filter_not_graftable", at);
+            }
+            grafts.push({
+              label: alias,
+              graftTarget: shape.graftTarget,
+              filterText: shape.filterText,
+              condition: shape.condition,
+              givenNames: shape.givenNames,
+              callerJoinPath: callerJoin.path
+            });
+            continue;
+          }
+          denyUnlessAdmitted(shape, givens, alias, "caller_join");
+        }
+      }
+      return grafts;
+    }
+    denyCallerJoin(alias, reason, at) {
+      recordRowLevelGateDecision("denied_by_gate", "caller_join");
+      logger.debug("Caller join is not provably allowed; denying", {
+        modelPath: this.modelPath,
+        alias,
+        reason,
+        at
+      });
+      throw new AccessDeniedError(`Access denied for source "${alias}".`);
+    }
+    async assertCallerJoinsQueryable(runnable, region) {
+      const { mode, exploresDeclared } = this.queryBoundary;
+      if (mode === "all" || !exploresDeclared)
+        return;
+      const refusal = () => this.notQueryable("Query target is not queryable.", true, "source");
+      let resolved;
+      try {
+        resolved = await this.resolvedCallerJoins(runnable, region);
+      } catch {
+        throw refusal();
+      }
+      if (!resolved)
+        throw refusal();
+      for (const { resolution } of resolved) {
+        if (resolution.kind === "unproven")
+          throw refusal();
+        if (resolution.boundaryUnprovenAt !== undefined)
+          throw refusal();
+        if (resolution.curatedQuery && this.isCuratedQuery(resolution.curatedQuery)) {
           continue;
         }
-        const bases = basesOf.get(name);
-        if (!bases || bases.size === 0) {
-          return { proven: false, reason: "chain_not_established", at: name };
+        for (const name of resolution.boundaryNames) {
+          if (!this.isCuratedSource(name))
+            throw refusal();
+        }
+      }
+    }
+    async assertCallerJoinBasesEarly(query, givens, phase, decided = new Set) {
+      const joins = buildJoinBaseMap(query);
+      if (joins.size === 0)
+        return;
+      if (phase === "boundary") {
+        const { mode, exploresDeclared } = this.queryBoundary;
+        if (mode === "all" || !exploresDeclared)
+          return;
+      } else if (!this.declaresAnyGate() || !this.modelDef) {
+        return;
+      }
+      const derivations = buildDerivationBaseMap(query);
+      for (const [alias, bases] of joins) {
+        const seen = new Set;
+        const worklist = [...bases];
+        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)
+            break;
+          if (!this.entryPointGatesBySource.has(name)) {
+            for (const base of derivations.get(name) ?? []) {
+              worklist.push(base);
+            }
+            const querySource = this.queries?.find((q) => q.name === name)?.sourceName;
+            if (querySource && (phase !== "boundary" || !this.isCuratedQuery(name))) {
+              worklist.push(querySource);
+            }
+            continue;
+          }
+          if (phase === "boundary") {
+            if (!this.isCuratedSource(name)) {
+              throw this.notQueryable("Query target is not queryable.", true, "source");
+            }
+            continue;
+          }
+          if (decided.has(name))
+            continue;
+          try {
+            for (const entry of this.entryPointGatesBySource.get(name) ?? []) {
+              const resolution = await this.resolveGateShape(entry, this.modelDef, this.defaultGraftScope());
+              if (resolution.shape === "row_level")
+                continue;
+              denyUnlessAdmitted(resolution, givens, alias, "caller_join");
+            }
+          } catch (error) {
+            if (error instanceof AccessDeniedError) {
+              this.assertQueryBoundaryEarly(name, undefined, undefined);
+            }
+            throw error;
+          }
+          decided.add(name);
         }
-        for (const base of bases)
-          worklist.push(base);
       }
-      return { proven: true, gatedBases };
     }
     async authorizeAndBindRunnable(runnable, givens, options) {
       if (options?.bypassAuthorize) {
         this.noteAuthorizeBypass("runnable", await this.resolveAuthorizeSourceFromRunnable(runnable));
+        await this.assertNoMisboundInheritedFilters(runnable);
         return runnable;
       }
       const graftScope = options?.graftScope ?? this.defaultGraftScope();
-      const rowLevel = await this.probeEntryPointGates(runnable, givens, graftScope, options?.skipOwnSourceGate ?? false);
-      if (rowLevel.length === 0) {
+      const entryPointRowLevel = await this.probeEntryPointGates(runnable, givens, graftScope, options?.skipOwnSourceGate ?? false);
+      if (entryPointRowLevel.length === 0) {
         if (options?.callerQueryText && !options?.skipOwnSourceGate) {
           await this.assertRequestDeclaredEntryPointIsNotLaundered(runnable, options.callerQueryText, givens, graftScope);
         }
+      }
+      const callerJoinRowLevel = options?.callerJoins ? await this.probeCallerJoinGates(options.callerJoins.runnable, options.callerJoins.region, givens, graftScope) : [];
+      if (callerJoinRowLevel.length > 0 && options?.callerJoins?.runnable !== runnable) {
+        this.denyCallerJoin(callerJoinRowLevel[0].label, "routed_past_caller_join_gate", callerJoinRowLevel[0].graftTarget);
+      }
+      const rowLevel = [...entryPointRowLevel, ...callerJoinRowLevel];
+      if (rowLevel.length === 0) {
+        await this.assertNoMisboundInheritedFilters(runnable);
         return runnable;
       }
+      const siteOf = (graft) => graft.callerJoinPath ? "caller_join" : "entry_point";
       if (!options?.recompile) {
         const decidable = (g) => g.givenNames.length === 0 || g.givenNames.every((name) => Object.hasOwn(givens, name));
         if (!options?.checkOnly || !rowLevel.every(decidable)) {
-          recordRowLevelGateDecision("denied_by_gate");
+          recordRowLevelGateDecision("denied_by_gate", siteOf(rowLevel[0]));
           throw new AccessDeniedError(`Access denied for source "${rowLevel[0].label}".`);
         }
         return runnable;
       }
       try {
-        const graftedMaterializer = this.getOrBuildGraftedMaterializer(rowLevel, graftScope);
-        const recompiled = options.recompile(graftedMaterializer, rowLevel);
+        const grafts = Array.from(new Map(rowLevel.map((g) => [
+          `${g.graftTarget}\x00${g.filterText}`,
+          g
+        ])).values());
+        const graftedMaterializer = this.getOrBuildGraftedMaterializer(grafts, graftScope);
+        const recompiled = options.recompile(graftedMaterializer, grafts);
         if (options.proveGraft) {
+          if (callerJoinRowLevel.length > 0) {
+            throw new Error("a caller-join graft has no prover here");
+          }
           await options.proveGraft(recompiled);
         } else {
           await this.assertGateLanded(recompiled, rowLevel);
         }
-        this.rowLevelFilteredRunnables.add(recompiled);
+        await this.assertGraftedGatesBind(recompiled, rowLevel, graftScope);
+        await this.assertNoMisboundInheritedFilters(recompiled, new Set(rowLevel.map((r) => r.condition)), siteOf(rowLevel[0]));
+        this.rowLevelFilteredRunnables.set(recompiled, rowLevel);
         return recompiled;
       } catch (err) {
-        recordRowLevelGateDecision("denied_by_gate");
+        recordRowLevelGateDecision("denied_by_gate", siteOf(rowLevel[0]));
         logger.debug("Row-level authorize attach failed; denying", {
           modelPath: this.modelPath,
           error: err instanceof Error ? err.message : String(err)
@@ -275867,20 +277556,26 @@ var init_model = __esm(() => {
           return {
             struct: undefined,
             modelDef: undefined,
-            compositeResolvedSourceDef: undefined
+            compositeResolvedSourceDef: undefined,
+            compiledUrl: undefined,
+            queryLocation: undefined
           };
         const structRef = prepared._query?.structRef;
         const struct = typeof structRef === "string" ? modelDef.contents[structRef] : structRef;
         return {
           struct: struct && typeof struct === "object" ? struct : undefined,
           modelDef,
-          compositeResolvedSourceDef: prepared._query?.compositeResolvedSourceDef
+          compositeResolvedSourceDef: prepared._query?.compositeResolvedSourceDef,
+          compiledUrl: typeof prepared._query?.location?.url === "string" && prepared._query.location.url.startsWith("internal://") ? prepared._query.location.url : undefined,
+          queryLocation: prepared._query?.location
         };
       } catch {
         return {
           struct: undefined,
           modelDef: undefined,
-          compositeResolvedSourceDef: undefined
+          compositeResolvedSourceDef: undefined,
+          compiledUrl: undefined,
+          queryLocation: undefined
         };
       }
     }
@@ -275928,7 +277623,7 @@ var init_model = __esm(() => {
       const copy = structuredClone(modelDef);
       for (const { graftTarget, condition } of grafts) {
         const target = copy.contents[graftTarget];
-        if (!target || !isSourceDef7(target)) {
+        if (!target || !isSourceDef9(target)) {
           throw new Error(`graft target "${graftTarget}" is not a source in this model`);
         }
         target.filterList = [...target.filterList ?? [], condition];
@@ -275957,14 +277652,64 @@ var init_model = __esm(() => {
         struct.filterList = [...struct.filterList ?? [], condition];
       }
     }
+    async assertGraftedGatesBind(recompiled, rowLevel, graftScope) {
+      let executedStruct;
+      let preparedForCallerJoins;
+      for (const { graftTarget, condition, callerJoinPath } of rowLevel) {
+        const entryPointStruct = graftScope.modelDef.contents[graftTarget];
+        let site;
+        if (callerJoinPath) {
+          preparedForCallerJoins ??= await recompiled.getPreparedQuery();
+          const located = locateCallerJoin(preparedForCallerJoins, callerJoinPath);
+          site = located && condition.code ? this.resolveFilterListLandingStruct(located, graftScope.modelDef, condition.code, 0) : undefined;
+          if (!site) {
+            throw new Error("a caller join's row-security gate could not be re-located on the recompiled query");
+          }
+        } else {
+          if (executedStruct === undefined) {
+            const { struct, compositeResolvedSourceDef } = await this.resolveRunTargetStruct(recompiled);
+            executedStruct = compositeResolvedSourceDef ?? struct;
+            if (!executedStruct) {
+              throw new Error("a row-security gate's executed source could not be resolved");
+            }
+          }
+          site = executedStruct;
+        }
+        assertGraftedGateBindsToDeclaringSource(isSourceDef9(entryPointStruct) ? entryPointStruct : undefined, site, condition, graftScope.modelDef, this.siblingModelDefResolver);
+      }
+    }
+    async assertNoMisboundInheritedFilters(runnable, alreadyProven = new Set, site = "entry_point") {
+      const {
+        struct,
+        modelDef,
+        compositeResolvedSourceDef,
+        compiledUrl,
+        queryLocation
+      } = await this.resolveRunTargetStruct(runnable);
+      const target = compositeResolvedSourceDef ?? struct;
+      if (!target)
+        return;
+      try {
+        assertInheritedSourceFiltersBind(target, modelDef, { compiledUrl, queryLocation }, this.siblingModelDefResolver, undefined, undefined, alreadyProven);
+      } catch (err) {
+        recordRowLevelGateDecision("denied_by_gate", site);
+        logger.debug("Inherited source filter binding check failed; denying", {
+          modelPath: this.modelPath,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        const label = target.as || target.name;
+        throw new AccessDeniedError(`Access denied for source "${label}".`);
+      }
+    }
     async assertGateLanded(recompiled, grafts) {
       const prepared = await recompiled.getPreparedQuery();
       const modelDef = prepared._modelDef ?? this.modelDef;
       const structRef = prepared._query?.compositeResolvedSourceDef ?? prepared._query?.structRef;
       const resolvedRef = typeof structRef === "string" ? modelDef?.contents[structRef] : structRef;
       const struct = resolvedRef && typeof resolvedRef === "object" ? resolvedRef : undefined;
-      for (const { condition } of grafts) {
-        if (!condition.code || !this.filterListContainsCode(struct, modelDef, condition.code, 0)) {
+      for (const { condition, callerJoinPath } of grafts) {
+        const site = callerJoinPath ? locateCallerJoin(prepared, callerJoinPath) : struct;
+        if (!condition.code || !this.filterListContainsCode(site, modelDef, condition.code, 0)) {
           throw new Error("a row-level gate condition did not land on the recompiled query");
         }
       }
@@ -275989,7 +277734,7 @@ var init_model = __esm(() => {
           const struct = snapshot;
           for (const { graftTarget, condition } of grafts) {
             const target = scope.modelDef.contents[graftTarget];
-            if (!target || !isSourceDef7(target) || !target.sourceID || struct.sourceID !== target.sourceID) {
+            if (!target || !isSourceDef9(target) || !target.sourceID || struct.sourceID !== target.sourceID) {
               throw new Error(`own-scope run target does not match graft target "${graftTarget}"`);
             }
             if (!struct.filterList?.some((f) => f.code === condition.code)) {
@@ -276019,30 +277764,59 @@ var init_model = __esm(() => {
     }
     static MAX_GATE_PROOF_DEPTH = 8;
     filterListContainsCode(struct, modelDef, code, depth) {
+      return this.resolveFilterListLandingStruct(struct, modelDef, code, depth) !== undefined;
+    }
+    resolveFilterListLandingStruct(struct, modelDef, code, depth) {
       if (!struct || depth > Model.MAX_GATE_PROOF_DEPTH)
-        return false;
+        return;
       if (struct.filterList?.some((f) => f.code === code))
-        return true;
+        return struct;
       const duck = struct;
       if (duck.type === "query_source" && modelDef) {
         const ref = duck.query?.compositeResolvedSourceDef ?? duck.query?.structRef;
         const base = typeof ref === "string" ? modelDef.contents[ref] : ref;
-        if (base && isSourceDef7(base)) {
-          return this.filterListContainsCode(base, modelDef, code, depth + 1);
+        if (base && isSourceDef9(base)) {
+          return this.resolveFilterListLandingStruct(base, modelDef, code, depth + 1);
         }
       }
-      return false;
+      return;
     }
-    async assertAuthorizedForText(text, givens) {
+    async assertAuthorizedForText(text, givens, options) {
       const target = extractRunTargetSourceName(text);
       await this.assertAuthorized(target, givens);
-      if (!hasCallerAuthorizeAnnotation(text)) {
+      if (hasCallerAuthorizeAnnotation(text))
+        return;
+      if (options?.wholeFile) {
         await this.assertLocksOnRequestDeclaredBases(target ?? "", text, givens);
+        return;
       }
+      const decided = new Set(target ? [target] : []);
+      await this.assertCallerJoinBasesEarly(text, givens, "locks", decided);
+      await this.assertLocksOnAppearingNames(text, givens, false, decided);
     }
-    async assertAuthorizedForRunnable(runnable, givens) {
+    async assertLocksOnAppearingNames(text, givens, bypassAuthorize, decided) {
+      if (!this.declaresAnyGate())
+        return;
+      for (const name of collectIdentifierNames(text)) {
+        const asQuery = this.queries?.find((q) => q.name === name)?.sourceName;
+        const source = (this.entryPointGatesBySource.get(name)?.length ?? 0) > 0 ? name : asQuery && (this.entryPointGatesBySource.get(asQuery)?.length ?? 0) > 0 ? asQuery : undefined;
+        if (!source || decided.has(source))
+          continue;
+        decided.add(source);
+        try {
+          await this.assertAuthorized(source, givens, bypassAuthorize);
+        } catch (error) {
+          if (error instanceof AccessDeniedError) {
+            this.assertQueryBoundaryEarly(source, undefined, undefined);
+          }
+          throw error;
+        }
+      }
+    }
+    async assertAuthorizedForRunnable(runnable, givens, callerRegion) {
       await this.assertAuthorizedForAllSources(runnable, givens, false, {
-        checkOnly: true
+        checkOnly: true,
+        callerRegion
       });
     }
     async resolveAuthorizeSourceFromRunnable(runnable) {
@@ -276065,17 +277839,54 @@ var init_model = __esm(() => {
       const target = extractRunTargetSourceName(scanned);
       if (!target)
         return;
-      const aliasOf = buildSourceAliasMap(scanned);
+      const aliasOf2 = buildSourceAliasMap(scanned);
       let current = target;
       const seen = new Set;
       while (current && !seen.has(current)) {
         if (this.filterMap.has(current))
           return current;
         seen.add(current);
-        current = aliasOf.get(current);
+        current = aliasOf2.get(current);
       }
       return;
     }
+    sameDeclarationLocation(a, b) {
+      const la = a.location;
+      const lb = b.location;
+      if (!la || !lb)
+        return false;
+      return la.url === lb.url && JSON.stringify(la.range.start) === JSON.stringify(lb.range.start) && JSON.stringify(la.range.end) === JSON.stringify(lb.range.end);
+    }
+    fieldIsUnaliased(struct, name) {
+      const field = struct.fields?.find((f) => (f.as ?? f.name) === name);
+      return !!field && field.name === name && !field.e;
+    }
+    async assertFilterAnnotationsBindToDeclaringSource(runnable, declaringSourceName, filters) {
+      try {
+        const { struct, modelDef, compositeResolvedSourceDef } = await this.resolveRunTargetStruct(runnable);
+        const executedStruct = compositeResolvedSourceDef ?? struct;
+        if (!executedStruct || !modelDef) {
+          throw new Error("a #(filter) run target could not be resolved");
+        }
+        const candidateStruct = modelDef.contents[declaringSourceName];
+        if (!candidateStruct || !isSourceDef9(candidateStruct)) {
+          throw new Error(`a #(filter) declaring source "${declaringSourceName}" could not be resolved`);
+        }
+        for (const filter2 of filters) {
+          const declaringStruct = findFilterAnnotationDeclaringSource(candidateStruct, modelDef, filter2, parseFilterAnnotation, this.siblingModelDefResolver) ?? (this.sameDeclarationLocation(candidateStruct, executedStruct) && this.fieldIsUnaliased(candidateStruct, filter2.dimension) ? candidateStruct : undefined);
+          if (!declaringStruct) {
+            throw new Error("a #(filter) dimension's declaring source could not be resolved");
+          }
+          assertFilterDimensionBindsToDeclaringSource(declaringStruct, executedStruct, filter2.dimension);
+        }
+      } catch (err) {
+        logger.debug("#(filter) annotation binding check failed; denying", {
+          modelPath: this.modelPath,
+          error: err instanceof Error ? err.message : String(err)
+        });
+        throw new AccessDeniedError(`Access denied for source "${declaringSourceName}".`);
+      }
+    }
     static async create(packageName, packagePath, modelPath, malloyConfig, options) {
       const { runtime, modelURL, importBaseURL, dataStyles, modelType } = await Model.getModelRuntime(packagePath, modelPath, malloyConfig, options);
       try {
@@ -276113,7 +277924,7 @@ var init_model = __esm(() => {
             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))
+              if (!struct || !isSourceDef9(struct))
                 return;
               validateSourceLineGateGivenUsage(sourceName, route, struct, condition.refSummary, condition.e, compiledModelDef, (cause, detail) => {
                 recordRowLevelGateRejected(cause);
@@ -276269,6 +278080,42 @@ var init_model = __esm(() => {
     }
     setQueryBoundary(policy) {
       this.queryBoundary = policy;
+      this.fileDerivationBases = policy.derivationText ? buildDerivationBaseMap(stripMalloyCommentsAndLiterals(policy.derivationText)) : undefined;
+    }
+    assertFileOnSurface() {
+      const { mode, exploresDeclared, isQueryEntryPoint } = this.queryBoundary;
+      if (mode === "all" || !exploresDeclared)
+        return;
+      if (!isQueryEntryPoint && !this.isNotebook()) {
+        throw this.notQueryable(`No queryable model "${this.modelPath}".`, true, "model");
+      }
+    }
+    setSiblingModelDefResolver(resolver) {
+      this.siblingModelDefResolver = resolver;
+    }
+    notQueryable(refusal, explainable, refused) {
+      const surface = this.queryBoundary.offSurface;
+      if (explainable && surface && !this.hasAnyAuthorizeNote()) {
+        return new OffSurfaceError(`${refusal} ${this.offSurfaceReason(surface, refused)}`);
+      }
+      return new NotQueryableError(refusal);
+    }
+    offSurfaceReason(surface, refused) {
+      const where = surface.indexModel ? `It is not on this package's published surface, "${INDEX_MODEL_NAME}": ` + `only what that file exports is queryable, and only through it.` : `It is not on this package's published surface, the models ` + `publisher.json "explores" lists (${JSON.stringify(surface.files)}): ` + `only what those files export is queryable, and only through them.`;
+      let fix;
+      if (refused === "model") {
+        fix = surface.indexModel ? `import "${this.modelPath}" in "${INDEX_MODEL_NAME}", name the ` + `sources you want in that file's export { ... }, and address ` + `the query to "${INDEX_MODEL_NAME}".` : `import "${this.modelPath}" in a listed model, name the sources ` + `you want in that model's export { ... }, and address the ` + `query to that model.`;
+      } else if (!this.isNotebook() && !this.isDashboard()) {
+        fix = `name the ${refused} in the export { ... } of "${this.modelPath}".`;
+      } else {
+        const exporter = surface.indexModel ? `"${INDEX_MODEL_NAME}"` : `a listed model`;
+        const readdress = this.isDashboard() ? "" : surface.indexModel ? `, and address the query to "${INDEX_MODEL_NAME}"` : `, and address the query to that model`;
+        fix = `name the ${refused} in the export { ... } of ${exporter}, ` + `importing the file that declares it if needed${readdress}.`;
+      }
+      return `${where} Fix: ${fix}`;
+    }
+    declaresSource(name) {
+      return this.sources?.some((s) => s.name === name) ?? false;
     }
     definitionIdentity(name) {
       if (!name)
@@ -276293,51 +278140,52 @@ var init_model = __esm(() => {
       return this.admittedByPackage(name, this.queryBoundary.packageCuratedSources);
     }
     isCuratedQuery(name) {
-      if (!this.isNotebook() && (this.getQueries() ?? []).some((q) => q.name === name))
+      if (!this.isNotebook() && !this.isDashboard() && (this.getQueries() ?? []).some((q) => q.name === name))
         return true;
       return this.admittedByPackage(name, this.queryBoundary.packageCuratedQueries);
     }
-    assertQueryBoundaryEarly(sourceName, queryName, query) {
-      const { mode, exploresDeclared, isQueryEntryPoint } = this.queryBoundary;
+    assertQueryBoundaryEarly(sourceName, queryName, query, derivationContext) {
+      const { mode, exploresDeclared } = this.queryBoundary;
       if (mode === "all" || !exploresDeclared)
         return "cleared";
-      if (!isQueryEntryPoint && !this.isNotebook()) {
-        throw new NotQueryableError(`No queryable model "${this.modelPath}".`);
-      }
+      this.assertFileOnSurface();
       if (queryName && !query) {
         if (!sourceName && this.isCuratedQuery(queryName))
           return "cleared";
         if (sourceName && this.isCuratedSource(sourceName))
           return "cleared";
-        throw new NotQueryableError(`No queryable query "${queryName}".`);
+        if (!sourceName && this.isDashboard() && (this.queries ?? []).some((q) => q.name === queryName)) {
+          return "deferred";
+        }
+        if (sourceName) {
+          throw this.notQueryable(`No queryable source "${sourceName}".`, this.declaresSource(sourceName), "source");
+        }
+        throw this.notQueryable(`No queryable query "${queryName}".`, (this.queries ?? []).some((q) => q.name === queryName), "query");
       }
       if (sourceName) {
         if (this.isCuratedSource(sourceName))
           return "cleared";
-        throw new NotQueryableError(`No queryable source "${sourceName}".`);
+        throw this.notQueryable(`No queryable source "${sourceName}".`, this.declaresSource(sourceName), "source");
       }
-      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("Query target is not queryable.");
+      for (const target of query ? extractRunTargetSourceNames(query) : []) {
+        if (!this.isCuratedSource(target) && !this.derivesFromCurated(target, query, derivationContext) && this.declaresSource(target)) {
+          throw this.notQueryable("Query target is not queryable.", true, "source");
         }
       }
       return "deferred";
     }
-    assertQueryBoundaryCompiled(compiledSource, query) {
-      const { mode, exploresDeclared, isQueryEntryPoint } = this.queryBoundary;
+    assertQueryBoundaryCompiled(compiledSource, query, derivationContext) {
+      const { mode, exploresDeclared } = this.queryBoundary;
       if (mode === "all" || !exploresDeclared)
         return;
-      if (!isQueryEntryPoint && !this.isNotebook()) {
-        throw new NotQueryableError(`No queryable model "${this.modelPath}".`);
-      }
+      this.assertFileOnSurface();
       if (compiledSource) {
         if (this.isCuratedSource(compiledSource))
           return;
-        if (query && this.derivesFromCurated(compiledSource, query))
+        if ((query || derivationContext || this.fileDerivationBases) && this.derivesFromCurated(compiledSource, query, derivationContext))
           return;
       }
-      throw new NotQueryableError("Query target is not queryable.");
+      throw this.notQueryable("Query target is not queryable.", compiledSource !== undefined, "source");
     }
     async assertCompiledTargetQueryable(runnable, query) {
       const { mode, exploresDeclared } = this.queryBoundary;
@@ -276345,18 +278193,95 @@ var init_model = __esm(() => {
         return;
       this.assertQueryBoundaryCompiled(await this.resolveAuthorizeSourceFromRunnable(runnable), query);
     }
+    async assertNotebookCellOnSurface(cellIndex, runnable) {
+      const { mode, exploresDeclared } = this.queryBoundary;
+      if (mode === "all" || !exploresDeclared)
+        return;
+      const cells = this.runnableNotebookCells ?? [];
+      const cellText = cells[cellIndex]?.text ?? "";
+      const context = cells.slice(0, cellIndex + 1).filter((c) => c.type === "code").map((c) => c.text).join(`
+`);
+      const early = this.assertQueryBoundaryEarly(undefined, undefined, cellText, context);
+      if (early === "deferred") {
+        this.assertQueryBoundaryCompiled(await this.resolveAuthorizeSourceFromRunnable(runnable), cellText, context);
+      }
+    }
+    async surfaceRefusal(request) {
+      const { mode, exploresDeclared } = this.queryBoundary;
+      if (mode === "all" || !exploresDeclared)
+        return;
+      const text = request.query ?? (request.queryName ? `run: ${quoteMalloyIdentifier2(request.queryName)}` : undefined);
+      if (!text || !this.modelMaterializer)
+        return;
+      let compiledSource;
+      try {
+        const runnable = this.modelMaterializer.loadRestrictedQuery(`
+` + text);
+        await runnable.getPreparedQuery();
+        compiledSource = await this.resolveAuthorizeSourceFromRunnable(runnable);
+      } catch (error) {
+        if (error instanceof MalloyError4 || error instanceof ModelCompilationError) {
+          return;
+        }
+        throw error;
+      }
+      try {
+        const early = this.assertQueryBoundaryEarly(undefined, request.query ? undefined : request.queryName, request.query);
+        if (early === "deferred") {
+          this.assertQueryBoundaryCompiled(compiledSource, request.query);
+        }
+        return;
+      } catch (error) {
+        if (error instanceof OffSurfaceError) {
+          return {
+            source: compiledSource && this.offSurfaceBase(compiledSource)
+          };
+        }
+        if (error instanceof NotQueryableError)
+          return {};
+        throw error;
+      }
+    }
+    offSurfaceBase(name) {
+      const seen = new Set;
+      let current = name;
+      while (!seen.has(current)) {
+        seen.add(current);
+        const bases = this.fileDerivationBases?.get(current);
+        const next = bases ? Array.from(bases).find((base) => !this.isCuratedSource(base)) : undefined;
+        if (!next)
+          return current;
+        current = next;
+      }
+      return current;
+    }
     isNotebook() {
       return this.modelPath.endsWith(NOTEBOOK_FILE_SUFFIX);
     }
+    isDashboard() {
+      return this.queryBoundary.dashboard === true;
+    }
     ownCuratedSourceNames() {
-      if (this.isNotebook())
+      if (this.isNotebook() || this.isDashboard())
         return new Set;
       return new Set((this.getSources() ?? []).map((s) => s.name).filter((n) => n !== undefined));
     }
-    derivesFromCurated(name, query) {
+    derivesFromCurated(name, query, derivationContext) {
       const own = this.ownCuratedSourceNames();
       const packageCurated = this.queryBoundary.packageCuratedSources;
-      const basesOf = buildDerivationBaseMap(stripMalloyCommentsAndLiterals(query));
+      const basesOf = query ? buildDerivationBaseMap(stripMalloyCommentsAndLiterals(query)) : new Map;
+      const contextBases = derivationContext ? buildDerivationBaseMap(stripMalloyCommentsAndLiterals(derivationContext)) : undefined;
+      for (const [derived, bases] of [
+        ...this.fileDerivationBases ?? [],
+        ...contextBases ?? []
+      ]) {
+        const into = basesOf.get(derived);
+        if (into)
+          for (const base of bases)
+            into.add(base);
+        else
+          basesOf.set(derived, new Set(bases));
+      }
       const proven = new Set;
       const inProgress = new Set;
       const proves = (current) => {
@@ -276780,13 +278705,22 @@ var init_model = __esm(() => {
       const liveBuildManifest = this.withoutPreaggregateEntries(buildManifest);
       const querySurfaceGivens = this.filterGivensToModelSurface(givens);
       const boundary = this.assertQueryBoundaryEarly(sourceName, queryName, query);
+      const callerRegion = !sourceName && !queryName && query ? { kind: "query", text: query } : undefined;
+      const readCallerJoinText = !!callerRegion && !hasCallerAuthorizeAnnotation(callerRegion.text);
+      if (readCallerJoinText) {
+        await this.assertCallerJoinBasesEarly(callerRegion.text, givens ?? {}, "boundary");
+      }
       const surfaceName = extractRunTargetSourceName(query);
       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);
-        }
+      }
+      const decided = new Set(earlySource ? [earlySource] : []);
+      if (readCallerJoinText && !bypassAuthorize) {
+        await this.assertCallerJoinBasesEarly(callerRegion.text, givens ?? {}, "locks", decided);
+      }
+      if (query && !hasCallerAuthorizeAnnotation(query)) {
+        await this.assertLocksOnAppearingNames(query, givens ?? {}, bypassAuthorize, decided);
       }
       try {
         for (const [field, callerText] of [
@@ -276821,6 +278755,8 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
           throw new BadRequestError("Invalid query request. (Query AND !sourceName) OR (queryName AND sourceName) must be defined.");
         }
         const isAdHocQuery = !sourceName && !queryName && !!query;
+        let injectedFilters;
+        let injectedFilterSourceName;
         if (!bypassFilters) {
           const effectiveSource = isAdHocQuery ? this.resolveFilterSource(query) : sourceName;
           if (effectiveSource) {
@@ -276828,14 +278764,20 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
             if (filters.length > 0) {
               const filterClause = buildFilterClause(filters, filterParams ?? {});
               queryString = injectFilterRefinement(queryString, filterClause);
+              injectedFilters = filters.filter((f) => filterHasValue(f, filterParams ?? {}));
+              injectedFilterSourceName = effectiveSource;
             }
           }
         }
         runnable = this.modelMaterializer.loadRestrictedQuery(queryString);
         liveRunnable = runnable;
+        if (injectedFilters && injectedFilters.length > 0 && injectedFilterSourceName) {
+          await runnable.getPreparedQuery();
+          await this.assertFilterAnnotationsBindToDeclaringSource(runnable, injectedFilterSourceName, injectedFilters);
+        }
         const storageRoutingPossible = getPersistStorageMode() === "on" && this.serveBindings.length > 0 && !!this.serveDestinationConfig;
         const preaggServeMaterializer = this.preaggregateServeMaterializer;
-        const routingBlockedByRowLevelGate = (storageRoutingPossible || !!preaggServeMaterializer) && !bypassAuthorize && this.hasAnyAuthorizeNote() && await this.queryEntryPointHasRowLevelGate(runnable);
+        const routingBlockedByRowLevelGate = (storageRoutingPossible || !!preaggServeMaterializer) && !bypassAuthorize && this.hasAnyAuthorizeNote() && await this.queryEntryPointHasRowLevelGate(runnable, callerRegion);
         if (routingBlockedByRowLevelGate) {
           recordStorageServeRouting("blocked_by_row_level_gate");
         }
@@ -276884,6 +278826,9 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         if (error instanceof BadRequestError) {
           throw error;
         }
+        if (error instanceof AccessDeniedError) {
+          throw error;
+        }
         if (error instanceof FilterValidationError) {
           throw new BadRequestError(error.message);
         }
@@ -276905,11 +278850,15 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
       const compiledSource = await this.resolveAuthorizeSourceFromRunnable(runnable);
       if (boundary === "deferred") {
         this.assertQueryBoundaryCompiled(compiledSource, query);
+        if (callerRegion && liveRunnable) {
+          await this.assertCallerJoinsQueryable(liveRunnable, callerRegion);
+        }
       }
       runnable = await this.authorizeAndBindRunnable(runnable, givens ?? {}, {
         recompile: (mm) => mm.loadRestrictedQuery(queryString),
         bypassAuthorize,
-        callerQueryText: query
+        callerQueryText: query,
+        callerJoins: callerRegion && liveRunnable ? { runnable: liveRunnable, region: callerRegion } : undefined
       });
       const maxRows = getMaxQueryRows();
       const maxBytes = getMaxResponseBytes();
@@ -276960,8 +278909,9 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
               modelPath: this.modelPath,
               error: err instanceof Error ? err.message : String(err)
             });
-            recordRowLevelGateDecision("denied_by_gate");
-            throw new AccessDeniedError(`Access denied for source "${compiledSource ?? sourceName ?? "unknown"}".`);
+            const unbound = this.rowLevelFilteredRunnables.get(runnable)?.find((graft) => graft.callerJoinPath && graft.givenNames.some((name) => !(name in (givens ?? {}))));
+            recordRowLevelGateDecision("denied_by_gate", unbound ? "caller_join" : "entry_point");
+            throw new AccessDeniedError(`Access denied for source "${unbound?.label ?? compiledSource ?? sourceName ?? "unknown"}".`);
           }
           const givenCode = err?.code;
           if (typeof givenCode === "string" && givenCode.startsWith("runtime-given-")) {
@@ -277020,7 +278970,8 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         executionTime = performance.now() - startTime;
       }
       if (this.queryHadRowLevelFilterAttached(runnable) && queryResults.totalRows === 0) {
-        recordRowLevelGateDecision("empty_after_filter");
+        const first2 = this.rowLevelFilteredRunnables.get(runnable)?.[0];
+        recordRowLevelGateDecision("empty_after_filter", first2?.callerJoinPath ? "caller_join" : "entry_point");
       }
       assertWithinModelRowLimit(queryResults.totalRows, maxRows, "model_query");
       const wrappedResult = API.util.wrapResult(queryResults);
@@ -277118,7 +279069,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         return;
       try {
         const entry = this.modelDef.contents?.[sourceName];
-        if (!entry || !isSourceDef7(entry))
+        if (!entry || !isSourceDef9(entry))
           return;
         const def = entry;
         if (!def.annotations)
@@ -277129,42 +279080,121 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
       }
     }
     getStandardModel() {
+      const published = this.publishedNames();
+      const keep = (items) => published && items ? items.filter((item) => item.name && published.has(item.name)) : items;
       return {
         type: "source",
         packageName: this.packageName,
         modelPath: this.modelPath,
         malloyVersion: MALLOY_VERSION,
         dataStyles: JSON.stringify(this.dataStyles),
-        modelDef: JSON.stringify(this.modelDef),
-        modelInfo: JSON.stringify(this.modelInfo ?? {}),
-        sourceInfos: this.getSourceInfos()?.map((sourceInfo) => JSON.stringify(sourceInfo)),
-        sources: this.getSources(),
-        queries: this.getQueries(),
+        modelDef: JSON.stringify(this.publishedModelDef(published)),
+        modelInfo: JSON.stringify(this.modelInfo ? { ...this.modelInfo, entries: keep(this.modelInfo.entries) } : {}),
+        sourceInfos: keep(this.getSourceInfos())?.map((sourceInfo) => JSON.stringify(sourceInfo)),
+        sources: keep(this.getSources()),
+        queries: keep(this.getQueries()),
         givens: this.givens
       };
     }
-    serializeNewSources(newSources) {
-      return newSources?.map((source) => JSON.stringify(this.givens && this.givens.length > 0 ? { ...source, givens: this.givens } : source));
+    publishedNames() {
+      if (!this.discoveryCurationEnabled)
+        return;
+      const exports = this.modelDef?.exports;
+      if (!Array.isArray(exports))
+        return;
+      const names = new Set(exports);
+      const { mode, exploresDeclared } = this.queryBoundary;
+      if (!this.isDashboard() || mode === "all" || !exploresDeclared) {
+        return names;
+      }
+      const readable = (source) => this.isCuratedSource(source) || this.derivesFromCurated(source);
+      const admitted = new Set;
+      for (const name of names) {
+        const query = this.queries?.find((q) => q.name === name);
+        const source = query ? query.sourceName : name;
+        if (source && readable(source))
+          admitted.add(name);
+      }
+      return admitted;
+    }
+    publishedModelDef(published) {
+      if (!published || !this.modelDef)
+        return this.modelDef;
+      const runsPublished = (query) => {
+        const ref = query.structRef;
+        const name = typeof ref === "string" ? ref : ref?.as ?? ref?.name;
+        return name !== undefined && published.has(name);
+      };
+      return {
+        ...this.modelDef,
+        contents: Object.fromEntries(Object.entries(this.modelDef.contents ?? {}).filter(([name]) => published.has(name)).map(([name, def]) => [name, scrubHiddenIds(def, published)])),
+        exports: (this.modelDef.exports ?? []).filter((name) => published.has(name)),
+        sourceRegistry: Object.fromEntries(Object.entries(this.modelDef.sourceRegistry ?? {}).filter(([key]) => published.has(key.split("@")[0]))),
+        queryList: (this.modelDef.queryList ?? []).filter(runsPublished),
+        references: []
+      };
+    }
+    showsFileText(text) {
+      if (this.isDashboard())
+        return true;
+      const published = this.publishedNames();
+      if (!published)
+        return true;
+      const unpublished = new Set(Object.keys(this.modelDef?.contents ?? {}).filter((name) => !published.has(name)));
+      if (unpublished.size === 0)
+        return true;
+      return !malloyIdentifiers(text).some((name) => unpublished.has(name));
+    }
+    serializeNewSources(newSources, cellIndex) {
+      const readable = this.notebookReadable(cellIndex);
+      return newSources?.filter((source) => !readable || readable(source.name)).map((source) => JSON.stringify(this.givens && this.givens.length > 0 ? { ...source, givens: this.givens } : source));
+    }
+    notebookReadable(cellIndex) {
+      const { mode, exploresDeclared } = this.queryBoundary;
+      if (mode === "all" || !exploresDeclared)
+        return;
+      const context = (this.runnableNotebookCells ?? []).slice(0, cellIndex + 1).filter((c) => c.type === "code").map((c) => c.text).join(`
+`);
+      return (name) => this.isCuratedSource(name) || this.derivesFromCurated(name, undefined, context);
+    }
+    async showsCellQueryInfo(cellIndex, cell) {
+      if (!cell.runnable)
+        return true;
+      try {
+        await this.assertNotebookCellOnSurface(cellIndex, cell.runnable);
+        return true;
+      } catch (error) {
+        if (error instanceof NotQueryableError)
+          return false;
+        throw error;
+      }
     }
     async getNotebookModel() {
-      const notebookCells = this.runnableNotebookCells.map((cell) => {
-        return {
+      const cells = this.runnableNotebookCells;
+      const notebookCells = [];
+      for (const [index, cell] of cells.entries()) {
+        notebookCells.push({
           type: cell.type,
           text: cell.text,
-          newSources: this.serializeNewSources(cell.newSources),
-          queryInfo: cell.queryInfo ? JSON.stringify(cell.queryInfo) : undefined
-        };
-      });
+          newSources: this.serializeNewSources(cell.newSources, index),
+          queryInfo: cell.queryInfo && await this.showsCellQueryInfo(index, cell) ? JSON.stringify(cell.queryInfo) : undefined
+        });
+      }
       const allAnnotations = this.modelDef ? ownModelNotes(this.modelDef) : [];
       const notebookTag = motlyTag(allAnnotations);
+      const readable = this.notebookReadable(notebookCells.length - 1);
+      const shownSource = (name) => !readable || name !== undefined && readable(name);
       const notebook = {
         type: "notebook",
         packageName: this.packageName,
         modelPath: this.modelPath,
         malloyVersion: MALLOY_VERSION,
-        modelInfo: JSON.stringify(this.modelInfo ?? {}),
-        sources: this.modelDef && this.sources,
-        queries: this.modelDef && this.queries,
+        modelInfo: JSON.stringify(this.modelInfo ? {
+          ...this.modelInfo,
+          entries: this.modelInfo.entries?.filter((entry) => entry.kind === "source" ? shownSource(entry.name) : true)
+        } : {}),
+        sources: this.modelDef && this.sources?.filter((source) => shownSource(source.name)),
+        queries: this.modelDef && this.queries?.filter((query) => !readable || shownSource(query.sourceName)),
         annotations: allAnnotations,
         autorun: readAutorun(notebookTag),
         startingGivens: readStartingGivens(notebookTag, (name) => (this.givens ?? []).find((g) => g.name === name)?.type),
@@ -277192,6 +279222,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
       let queryName = undefined;
       let queryResult = undefined;
       if (cell.runnable) {
+        await this.assertNotebookCellOnSurface(cellIndex, cell.runnable);
         try {
           let runnableToExecute = cell.runnable;
           let textToExecute = cell.text;
@@ -277208,6 +279239,11 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
           if (filterClause && cell.modelMaterializer) {
             textToExecute = injectFilterRefinement(cell.text, filterClause);
             runnableToExecute = cell.modelMaterializer.loadQuery(textToExecute);
+            const injectedCellFilters = cellFilters.filter((f) => filterHasValue(f, filterParams ?? {}));
+            if (injectedCellFilters.length > 0 && effectiveSource) {
+              await runnableToExecute.getPreparedQuery();
+              await this.assertFilterAnnotationsBindToDeclaringSource(runnableToExecute, effectiveSource, injectedCellFilters);
+            }
           }
           if (cell.modelMaterializer) {
             const textForRecompile = textToExecute;
@@ -277291,7 +279327,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         text: cell.text,
         queryName,
         result: queryResult,
-        newSources: this.serializeNewSources(cell.newSources)
+        newSources: this.serializeNewSources(cell.newSources, cellIndex)
       };
     }
     static async getModelRuntime(packagePath, modelPath, malloyConfig, options) {
@@ -277489,6 +279525,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
       }
     }
   };
+  SOURCE_IDENTITY_KEYS = new Set(["extends", "sourceID", "referenceID"]);
 });
 
 // ../../node_modules/concat-map/index.js
@@ -299818,9 +301855,10 @@ class ModelController {
       if (model.getType() === "notebook") {
         throw new ModelNotFoundError(`${modelPath} is a notebook`);
       }
+      model.assertFileOnSurface();
       const [compiled, sourceText] = await Promise.all([
         model.getModel(),
-        p.getModelFileText(modelPath).catch((error) => {
+        p.getModelFileText(modelPath).then((text) => model.showsFileText(text) ? text : undefined).catch((error) => {
           logger.warn("getModel: model source text unavailable", {
             environmentName,
             packageName,
@@ -299832,7 +301870,7 @@ class ModelController {
       ]);
       return sourceText === undefined ? compiled : { ...compiled, sourceText };
     } catch (error) {
-      if (error instanceof ModelNotFoundError) {
+      if (error instanceof ModelNotFoundError || error instanceof NotQueryableError) {
         throw error;
       }
       throw new Error(`Failed to get model ${modelPath} from package ${packageName} in environment ${environmentName}: ${error}`);
@@ -300143,6 +302181,24 @@ var BACK_PRESSURE_SUGGESTIONS = [
   "If this persists, raise the limit or scale up the pod."
 ];
 function classifyToolError(operation, identifier, error) {
+  if (error instanceof OffSurfaceError) {
+    return {
+      message: error.message,
+      suggestions: [
+        "This is curation, not a typo: the name is real and the package does not publish it. Retrying with a different spelling will not help.",
+        "To query what IS published, call get_context for this package and use the model_path it returns, verbatim."
+      ]
+    };
+  }
+  if (error instanceof PackageManifestError) {
+    return {
+      message: error.message,
+      suggestions: [
+        "This is not transient. The package's publisher.json is invalid, so retrying fails the same way until the file is fixed.",
+        "Fix the field the message names in publisher.json, then call reload_package."
+      ]
+    };
+  }
   if (error instanceof EnvironmentNotFoundError || error instanceof PackageNotFoundError || error instanceof ModelNotFoundError || error instanceof NotQueryableError || error instanceof ConnectionNotFoundError) {
     return getNotFoundError(identifier);
   }
@@ -302003,7 +304059,7 @@ async function runContextQuery(request, environmentStore, extraWarnings = []) {
       return jsonResource(uri, {
         sources: sources2,
         ...listingEnvelope,
-        ...warningsFor("This package loaded but exposes no sources. That is a curation gap, not an empty database: check the package's explores list and export {} statements, and call get_status for load errors and stale packages.")
+        ...warningsFor("This package loaded but exposes no sources. That is a curation gap, not an empty database: check what the package's index.malloy exports (its export { ... }), and call get_status for load errors and stale packages.")
       });
     }
     return jsonResource(uri, {
@@ -309483,7 +311539,7 @@ init_authorize();
 import crypto4 from "crypto";
 import * as fs8 from "fs";
 import * as path12 from "path";
-import { fileURLToPath as fileURLToPath7, pathToFileURL as pathToFileURL2 } from "url";
+import { fileURLToPath as fileURLToPath7, pathToFileURL as pathToFileURL3 } from "url";
 
 // src/service/compile_restriction.ts
 init_errors();
@@ -309638,6 +311694,7 @@ init_materialization_metrics();
 var import_recursive_readdir = __toESM(require_recursive_readdir(), 1);
 import * as fs7 from "fs/promises";
 import * as path11 from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
 import"@malloydata/db-duckdb/native";
 import { DuckDBConnection as DuckDBConnection3 } from "@malloydata/db-duckdb";
 import {
@@ -310538,7 +312595,7 @@ function packageLoadFailureStatus(error) {
   if (error instanceof ModelCompilationError || error instanceof MalloyError5) {
     return "compilation_error";
   }
-  if (error instanceof BadRequestError) {
+  if (error instanceof BadRequestError || error instanceof PackageManifestError) {
     return "policy_rejected";
   }
   if (error instanceof ServiceUnavailableError) {
@@ -310589,6 +312646,7 @@ class Package {
     this.malloyConfig = malloyConfig;
     this.applyDiscoveryPolicyToModels();
     this.applyQueryBoundaryToModels();
+    this.applySiblingModelResolverToModels();
   }
   exploresDeclared() {
     const explores = this.packageMetadata.explores;
@@ -310600,7 +312658,7 @@ class Package {
     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.`;
+    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. Fix: if that was not intended, ` + `restore ${INDEX_MODEL_NAME} under that exact name.`;
     this.surfaceWidenedWarning = message;
     logger.warn(`Package ${this.packageName} no longer publishes a surface`, {
       packageName: this.packageName,
@@ -310644,6 +312702,8 @@ class Package {
           continue;
         if (!exploreSet.has(modelPath))
           continue;
+        if (this.isServedDashboard(modelPath))
+          continue;
         for (const source of model.getSources() ?? []) {
           add(sources, source.name, model.definitionIdentity(source.name));
         }
@@ -310654,16 +312714,39 @@ class Package {
       packageCuratedSources = sources;
       packageCuratedQueries = queries;
     }
+    const offSurface = mode === "declared" && exploresDeclared && exploreSet ? {
+      indexModel: this.surfaceIsIndexModel(),
+      files: [...exploreSet].sort()
+    } : undefined;
     for (const [modelPath, model] of this.models) {
+      const dashboardText = this.dashboardFileText.get(modelPath);
+      const dashboard = dashboardText !== undefined;
       model.setQueryBoundary({
         mode,
         exploresDeclared,
-        isQueryEntryPoint: exploreSet ? exploreSet.has(modelPath) : true,
+        isQueryEntryPoint: exploreSet ? exploreSet.has(modelPath) || dashboard : true,
         packageCuratedSources,
-        packageCuratedQueries
+        packageCuratedQueries,
+        offSurface,
+        dashboard,
+        derivationText: dashboardText
       });
     }
   }
+  dashboardFileText = new Map;
+  isServedDashboard(modelPath) {
+    return this.dashboardFileText.has(modelPath);
+  }
+  applySiblingModelResolverToModels() {
+    const byUrl = new Map;
+    for (const [modelPath, model] of this.models) {
+      byUrl.set(pathToFileURL2(path11.join(this.packagePath, modelPath)).toString(), model);
+    }
+    const resolver = (url2) => byUrl.get(url2)?.getModelDef();
+    for (const model of this.models.values()) {
+      model.setSiblingModelDefResolver(resolver);
+    }
+  }
   static async create(environmentName, packageName, packagePath, environmentMalloyConfig, cleanupDirectoryOnFailure = false) {
     assertSafeEnvironmentPath(packagePath);
     const startTime = performance.now();
@@ -310715,7 +312798,7 @@ class Package {
       defaultConnectionName: "duckdb"
     }).catch((err) => {
       const realError = err instanceof Error ? err : new Error(`Package-load worker pool failure: ${String(err)}`);
-      if (realError instanceof MalloyError5 || realError instanceof ModelCompilationError) {
+      if (realError instanceof MalloyError5 || realError instanceof ModelCompilationError || realError instanceof PackageManifestError) {
         throw realError;
       }
       throw new ServiceUnavailableError(`Package-load worker pool unavailable: ${realError.message}`);
@@ -311280,10 +313363,12 @@ class Package {
         continue;
       if (exploreSet && !exploreSet.has(modelPath))
         continue;
+      if (exploreSet && this.isServedDashboard(modelPath))
+        continue;
       if (model.hasEmptyDiscoverySurface()) {
         warnings.push({
           model: modelPath,
-          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.`)
+          message: this.surfaceIsIndexModel() ? `${INDEX_MODEL_NAME} exports nothing, so nothing in this ` + `package can be queried. Fix: add an export { ... } ` + `naming the sources to publish.` : `${modelPath} exports nothing, so nothing can be queried ` + `through it. Fix: add an export { ... } naming the ` + `sources to publish, or remove it from "explores".`
         });
       }
     }
@@ -311293,7 +313378,7 @@ class Package {
     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));
+    const surface = Array.from(this.models.entries()).filter(([modelPath]) => modelPath.endsWith(MODEL_FILE_SUFFIX) && exploreSet.has(modelPath) && !this.isServedDashboard(modelPath));
     if (surface.length === 0)
       return [];
     if (!surface.every(([, model]) => !!model.getCompilationError())) {
@@ -311388,7 +313473,7 @@ class Package {
       });
     } catch (err) {
       const realError = err instanceof Error ? err : new Error(`Package-load worker pool failure: ${String(err)}`);
-      if (realError instanceof MalloyError5 || realError instanceof ModelCompilationError) {
+      if (realError instanceof MalloyError5 || realError instanceof ModelCompilationError || realError instanceof PackageManifestError) {
         throw realError;
       }
       throw new ServiceUnavailableError(`Package-load worker pool unavailable: ${realError.message}`);
@@ -311440,6 +313525,7 @@ class Package {
     this.packageMetadata.manifestLocation = outcome.packageMetadata.manifestLocation ?? null;
     this.applyDiscoveryPolicyToModels();
     this.applyQueryBoundaryToModels();
+    this.applySiblingModelResolverToModels();
     await this.discoverDashboards();
     this.recordManifestBinding(entries);
     this.wireFreshnessResolvers();
@@ -311464,7 +313550,9 @@ class Package {
     const values = await Promise.all(Array.from(this.models.keys()).filter((modelPath) => {
       if (!modelPath.endsWith(MODEL_FILE_SUFFIX))
         return false;
-      return exploreSet ? exploreSet.has(modelPath) : true;
+      if (!exploreSet)
+        return true;
+      return exploreSet.has(modelPath) && !this.isServedDashboard(modelPath);
     }).map(async (modelPath) => {
       let error;
       try {
@@ -311481,18 +313569,6 @@ class Package {
     }));
     return values;
   }
-  isQueryableEntryPoint(modelPath) {
-    if (!this.queryBoundaryActive())
-      return true;
-    const exploreSet = this.exploreSet();
-    return exploreSet ? exploreSet.has(modelPath) : true;
-  }
-  servableEntryPoints() {
-    if (!this.queryBoundaryActive())
-      return () => true;
-    const exploreSet = this.exploreSet();
-    return (modelPath) => exploreSet ? exploreSet.has(modelPath) : true;
-  }
   queryBoundaryActive() {
     if (this.packageMetadata.queryableSources === "all")
       return false;
@@ -311510,7 +313586,6 @@ class Package {
     const discovered = new Map;
     const factsByPath = new Map;
     const allFacts = new Map;
-    const heldBack = [];
     const unconventionalSlugs = [];
     const droppedByError = [];
     const dashboardSlugs = new Set;
@@ -311576,10 +313651,6 @@ class Package {
         };
       }
       dashboardSlugs.add(name);
-      if (!this.isQueryableEntryPoint(modelPath)) {
-        heldBack.push({ modelPath, name });
-        continue;
-      }
       if (!matchesDocumentedDashboardName(name)) {
         unconventionalSlugs.push({ modelPath, name });
       }
@@ -311588,7 +313659,34 @@ class Package {
         factsByPath.set(modelPath, facts);
     }
     this.dashboards = discovered;
-    this.dashboardWarnings = await this.lintDashboards(factsByPath, allFacts, heldBack, unconventionalSlugs, dashboardSlugs, droppedByError);
+    const dashboardFileText = new Map;
+    for (const manifest of discovered.values()) {
+      const model = this.models.get(manifest.entryFile);
+      if (!model)
+        continue;
+      try {
+        dashboardFileText.set(manifest.entryFile, await model.getFileText(this.packagePath));
+      } catch {
+        dashboardFileText.set(manifest.entryFile, "");
+      }
+    }
+    this.dashboardFileText = dashboardFileText;
+    this.applyQueryBoundaryToModels();
+    this.lintInputs = {
+      factsByPath,
+      allFacts,
+      unconventionalSlugs,
+      dashboardSlugs,
+      droppedByError
+    };
+    await this.relintDashboards();
+  }
+  lintInputs;
+  async relintDashboards() {
+    const inputs = this.lintInputs;
+    if (!inputs)
+      return;
+    this.dashboardWarnings = await this.lintDashboards(inputs.factsByPath, inputs.allFacts, inputs.unconventionalSlugs, inputs.dashboardSlugs, inputs.droppedByError);
     for (const warning of this.dashboardWarnings) {
       logger.warn("Dashboard lint", {
         packageName: this.packageName,
@@ -311597,32 +313695,60 @@ class Package {
       });
     }
   }
-  lintTilesAgainstSurface(modelPath, manifest) {
+  async lintTilesAgainstSurface(modelPath, manifest) {
     const model = this.models.get(modelPath);
-    if (!model || !manifest.tiles)
+    if (!model || !this.queryBoundaryActive())
       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"
-        });
-      }
+    const surfaceIsIndex = this.surfaceIsIndexModel();
+    const listedModel = (this.packageMetadata.explores ?? []).find((entry) => entry.endsWith(MODEL_FILE_SUFFIX) && !this.isServedDashboard(entry));
+    const unexported = surfaceIsIndex ? `which ${INDEX_MODEL_NAME} doesn't export` : `which no file "explores" lists exports`;
+    const fixFor = (source) => {
+      const name = source ?? "the source it reads";
+      return surfaceIsIndex ? `Fix: add ${name} to the export { ... } in ${INDEX_MODEL_NAME}.` : listedModel ? `Fix: add ${name} to the export { ... } in ${listedModel}.` : `Fix: delete "explores" from publisher.json and add ${name} ` + `to the export { ... } in ${INDEX_MODEL_NAME}.`;
+    };
+    const checks = [];
+    for (const tile of manifest.tiles ?? []) {
+      checks.push({
+        request: { query: `run: ${tile.query}` },
+        describe: (source) => `Tile ${tile.query} on dashboard ${manifest.name} reads ` + `${source}, ${unexported}, so it won't load.`
+      });
+    }
+    if (manifest.query) {
+      checks.push({
+        request: { queryName: manifest.query },
+        describe: (source) => `Dashboard ${manifest.name} reads ${source}, ` + `${unexported}, so it won't load.`
+      });
+    }
+    for (const given of manifest.givens) {
+      const suggest = given.suggest;
+      if (!suggest)
+        continue;
+      const request = suggest.query ? { queryName: suggest.query } : suggest.source && suggest.dimension ? {
+        query: `run: ${suggest.source} -> { group_by: ${suggest.dimension} }`
+      } : undefined;
+      if (!request)
+        continue;
+      checks.push({
+        request,
+        describe: (source) => `Filter ${given.name} on dashboard ${manifest.name} suggests ` + `from ${source}, ${unexported}, so its list will be ` + `empty.`
+      });
     }
+    const refusals = await Promise.all(checks.map(({ request }) => model.surfaceRefusal(request)));
+    const findings = [];
+    refusals.forEach((refusal, i) => {
+      if (!refusal)
+        return;
+      findings.push({
+        model: modelPath,
+        subject: manifest.name,
+        message: `${checks[i].describe(refusal.source ?? "a source")} ${fixFor(refusal.source)}`,
+        severity: "error"
+      });
+    });
     return findings;
   }
-  async lintDashboards(factsByPath, allFacts, heldBack, unconventionalSlugs, knownSlugs, droppedByError) {
+  async lintDashboards(factsByPath, allFacts, unconventionalSlugs, knownSlugs, droppedByError) {
     const warnings = [];
-    const withheldDrills = new Map;
     try {
       for (const { modelPath, name } of droppedByError) {
         warnings.push({
@@ -311640,27 +313766,6 @@ class Package {
           severity: "warn"
         });
       }
-      for (const { modelPath, name } of heldBack) {
-        for (const file of allFacts.values()) {
-          for (const drill of file.drills) {
-            if (!drill.to.includes(name))
-              continue;
-            const where = `${drill.source}.${drill.dimension}`;
-            withheldDrills.set(`${where}|${name}`, {
-              subject: where,
-              message: `# drill on ${where} targets "${name}", which IS a ` + `dashboard in this package but is not served (see the ` + `finding on "${modelPath}"), so the click has nowhere ` + `to land.`,
-              severity: "error"
-            });
-          }
-        }
-        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 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"
-        });
-      }
       for (const [modelPath, facts] of factsByPath) {
         const manifest = this.dashboards.get(dashboardSlug(modelPath));
         const findings = manifest ? lintDashboard(facts, manifest) : lintUndiscoveredDashboard(facts);
@@ -311668,15 +313773,12 @@ class Package {
           warnings.push({ model: modelPath, ...finding });
         }
         if (manifest) {
-          for (const finding of this.lintTilesAgainstSurface(modelPath, manifest)) {
+          for (const finding of await this.lintTilesAgainstSurface(modelPath, manifest)) {
             warnings.push(finding);
           }
         }
       }
       const drillFacts = Array.from(allFacts.values());
-      for (const finding of withheldDrills.values()) {
-        warnings.push(finding);
-      }
       for (const finding of lintDrillTargets(drillFacts, knownSlugs)) {
         warnings.push(finding);
       }
@@ -311695,7 +313797,7 @@ class Package {
         error: errMessage(err)
       });
       warnings.push({
-        message: `Dashboard lint stopped early, so this list is incomplete: an ` + `unknown subset of the curation, dashboard, drill, given and ` + `unsupported-component checks did not run. Treat a missing ` + `finding of any of those kinds as unknown rather than clean, ` + `including the absence of a "held back from the listing" ` + `finding. Reload the package to run the lint again. The ` + `dashboards themselves are unaffected, because they are ` + `discovered before the lint runs. An operator can find the ` + `cause in the server log under "Dashboard lint failed".`,
+        message: `Dashboard lint stopped early, so this list is incomplete: an ` + `unknown subset of the tile, dashboard, drill, given and ` + `unsupported-component checks did not run. Treat a missing ` + `finding of any of those kinds as unknown rather than clean. ` + `Reload the package to run the lint again. The ` + `dashboards themselves are unaffected, because they are ` + `discovered before the lint runs. An operator can find the ` + `cause in the server log under "Dashboard lint failed".`,
         severity: "warn"
       });
     }
@@ -311725,8 +313827,7 @@ class Package {
     return warnings;
   }
   listDashboards() {
-    const servable = this.servableEntryPoints();
-    return Array.from(this.dashboards.values()).filter((manifest) => servable(manifest.entryFile)).map((manifest) => ({
+    return Array.from(this.dashboards.values()).map((manifest) => ({
       resource: this.dashboardResource(manifest.name),
       packageName: this.packageName,
       name: manifest.name,
@@ -311738,9 +313839,6 @@ class Package {
   }
   getDashboard(name) {
     const manifest = this.dashboards.get(name);
-    if (manifest && !this.isQueryableEntryPoint(manifest.entryFile)) {
-      return;
-    }
     if (!manifest)
       return;
     return {
@@ -311888,6 +313986,7 @@ class Package {
     this.packageMetadata = packageMetadata;
     this.applyDiscoveryPolicyToModels();
     this.applyQueryBoundaryToModels();
+    this.applySiblingModelResolverToModels();
   }
 }
 
@@ -312079,9 +314178,10 @@ class Environment {
       const modelPath = safeJoinUnderRoot(this.environmentPath, packageName, modelName);
       const packagePath = safeJoinUnderRoot(this.environmentPath, packageName);
       const modelDir = path12.dirname(modelPath);
-      const virtualUrl = scope === "append" ? pathToFileURL2(path12.join(modelDir, "__compile_check.malloy")) : pathToFileURL2(modelPath);
+      const virtualUrl = scope === "append" ? pathToFileURL3(path12.join(modelDir, "__compile_check.malloy")) : pathToFileURL3(modelPath);
       const virtualUri = virtualUrl.toString();
       let fullSource = source ?? "";
+      let callerRegion;
       if (scope === "append") {
         let modelContent = "";
         try {
@@ -312089,6 +314189,13 @@ class Environment {
         } catch {}
         fullSource = modelContent ? `${modelContent}
 ${source}` : source ?? "";
+        callerRegion = {
+          kind: "span",
+          url: virtualUri,
+          fromLine: modelContent ? modelContent.split(`
+`).length : 0,
+          text: source ?? ""
+        };
       }
       const substitute = scope !== "package" || source !== undefined;
       const interceptingReader = {
@@ -312115,7 +314222,9 @@ ${source}` : source ?? "";
       if (gateModel && hasExactGateModel && source !== undefined) {
         await denyHiddenAsNotQueryable(() => {
           gateModel.assertQueryBoundaryEarly(undefined, undefined, source);
-        }, () => gateModel.assertAuthorizedForText(source, givens ?? {}));
+        }, () => gateModel.assertAuthorizedForText(source, givens ?? {}, {
+          wholeFile: scope !== "append"
+        }));
       }
       const boundManifestEntries = pkg.getBuildManifestEntries();
       const runtime = new Runtime3({
@@ -312173,6 +314282,9 @@ ${source}` : source ?? "";
             replacement: source === undefined ? undefined : { modelPath: modelName, source }
           });
         } catch (error) {
+          if (error instanceof MalloyError6 || error instanceof ModelCompilationError || error instanceof PackageManifestError) {
+            throw error;
+          }
           throw new ServiceUnavailableError(`Package compile worker unavailable: ${error instanceof Error ? error.message : String(error)}`);
         }
         const seen = new Set;
@@ -312220,7 +314332,7 @@ ${source}` : source ?? "";
       if (scope === "append") {
         let baseModel;
         try {
-          baseModel = await runtime.loadModel(pathToFileURL2(modelPath)).getModel();
+          baseModel = await runtime.loadModel(pathToFileURL3(modelPath)).getModel();
         } catch (error) {
           logger.warn("Compile gate could not load the base model", {
             modelPath,
@@ -312261,7 +314373,7 @@ ${source}` : source ?? "";
               throw new NotQueryableError("Query target is not queryable.");
             }
             return gateModel.assertCompiledTargetQueryable(materializer, source);
-          }, () => hasExactGateModel ? gateModel.assertAuthorizedForRunnable(materializer, givens ?? {}) : gateModel.assertAuthorizedFromCompiledRunnable(materializer, givens ?? {}));
+          }, () => hasExactGateModel ? gateModel.assertAuthorizedForRunnable(materializer, givens ?? {}, callerRegion) : gateModel.assertAuthorizedFromCompiledRunnable(materializer, givens ?? {}));
         }
         let sql;
         if (includeSql && queryMaterializer) {
@@ -312971,6 +315083,8 @@ ${source}` : source ?? "";
           await _package.reloadAllModels({});
           _package.bindStorageServeBindings({});
         }
+      } else {
+        await _package.relintDashboards();
       }
       return _package.getPackageMetadata();
     });
@@ -318692,12 +320806,17 @@ recall is scoring search against an expectation that was never satisfiable.
 Because it runs from the model text alone it is cheap enough to point at every
 published version and read as a trend, which is what it is for. Its verdicts are
 \`eval-diagnose\`'s codes verbatim, validated against that table at startup, so
-\`COVERAGE\`, \`AMBIGUOUS\`, \`NO-DISAMBIG\` and \`CONVENTION\` mean there exactly what
-they mean here. It writes nothing: not a golden, not the case-level \`coverage\`
+\`MISSING\`, \`AMBIGUOUS\`, \`RULE_UNWRITTEN\` and \`UNDERSPECIFIED\` mean there exactly
+what they mean here. A pass is \`MODELLED\`. It writes nothing: not a golden, not the case-level \`coverage\`
 field, not a run directory. Where its verdict and that field disagree is where a
 version regressed, and the field is the standing judgement about the question
 while this is a measurement against one build.
 
+Its \`--out\` report records \`compiledSurface\`: \`read\`, or why the compiled field
+list was not read. Without that list the judge calls a column a source exposes
+implicitly absent, so check the field before comparing two runs. A \`--model\`
+run never has it.
+
 How to invoke it. Either \`--model <file-or-dir>\` for a local package or
 \`--publisher <url> --package <pkg>\` for a served one, plus \`--set <dir>\`, and
 \`--version <label>\` to stamp the report so a trend has an x-axis:
@@ -318745,7 +320864,7 @@ purpose. Separately, the whole model goes into one prompt per case, so past a
 few thousand lines it stops running on Linux and above about 100 KB the verdict
 stops being stable. Do not take the over-size message's advice to narrow
 \`--model\` to one file, which drops every imported source and manufactures
-\`COVERAGE\` verdicts.
+\`MISSING\` verdicts.
 
 ## Validate the definitions, not every answer
 
@@ -318859,6 +320978,10 @@ was. Separately, the whole model goes into one prompt per case, which caps the
 package size it can run on at all and destabilises the verdict well before that
 cap.
 
+The measurements below predate the renamed verdicts, and their tables keep the
+names they were taken under: \`ok\` is now \`MODELLED\`, \`COVERAGE\` is \`MISSING\`,
+\`NO-DISAMBIG\` is merged into \`AMBIGUOUS\`, and \`CONVENTION\` is \`RULE_UNWRITTEN\`.
+
 ## Measured against a labelled set: the label drifts too
 
 The \`evals/ecommerce\` set in \`credibledata/malloy-samples\` labels every case
@@ -319002,7 +321125,7 @@ concatenates every \`*.malloy\` under the tree and does **not** resolve \`import
 real packages split across files exactly that way (in
 \`credibledata/malloy-samples\`, \`ecommerce/brand_synergy.malloy\` opens with
 \`import "ecommerce.malloy"\`). Narrowing to one file drops every imported source,
-so the judge correctly answers \`COVERAGE\`, no entity represents the concept
+so the judge correctly answers \`MISSING\`, no entity represents the concept
 anywhere, for cases the model answers perfectly well. That is a false gap
 indistinguishable from a real one, and it lands in the numerator of a published
 trend.
@@ -319050,11 +321173,10 @@ format address the cost, the ceiling and \`json_objects()\` together. Stdlib
 \`urllib\` keeps the stdlib-only promise; the real cost is auth, since \`claude -p\`
 rides the CLI's credentials.
 
-**And for a large package, stop sending the whole model.** Rule out \`COVERAGE\`
+**And for a large package, stop sending the whole model.** Rule out \`MISSING\`
 against a complete inventory of names and one-line docs, a small fraction of the
 bytes, which keeps "no candidate anywhere" decidable; then send full text for
-the candidate sources only, to settle \`AMBIGUOUS\`, \`NO-DISAMBIG\` and
-\`CONVENTION\`. Deliberately NOT retrieval ranking: folding retrieval into this
+the candidate sources only, to settle \`AMBIGUOUS\` and \`RULE_UNWRITTEN\`. Deliberately NOT retrieval ranking: folding retrieval into this
 number would collapse the distinction from recall that the metric exists to
 draw.`
     },
@@ -319199,7 +321321,7 @@ record, and \`verify_definitions.py\` re-runs and compares it on every rebuild.
     "query": "run: order_items -> { aggregate: control is sale_price.sum() { where: status != 'Cancelled' } - inventory_items.cost.sum() { where: status != 'Cancelled' } }",
     "note": "excludes Cancelled, per status's own doc and units_sold"
   },
-  "cause": "CONVENTION"
+  "cause": "RULE_UNWRITTEN"
 }
 \`\`\`
 
@@ -319223,7 +321345,7 @@ Authoring a control is judgement, and the same rules as authoring a golden apply
 where two populations are both defensible from the docs, do not pick one --
 record the ambiguity in \`note\` and leave the record \`unchecked\`. \`cause\` is the
 \`eval-diagnose\` code the author expects a disagreement to mean (the cogs case is
-\`CONVENTION\`); it is carried onto the finding, not inferred.
+\`RULE_UNWRITTEN\`); it is carried onto the finding, not inferred.
 
 This is **validate what someone asserted**, not **find business-wrong definitions
 unaided**. It turns "I believe \`total_gross_margin\` should exclude cancelled
@@ -319370,7 +321492,7 @@ a permanent parallel mechanism.`
     {
       name: "eval-answer/ledger-schema",
       description: "The eval ledger: files and events. Reference detail for the eval-answer skill.",
-      body: "# The eval ledger: files and events\n\nThe ledger is plain files in the model package's git repository. There is no\neval API and no eval database. The conductor (`skill:eval-loop`) reads and\nwrites these files directly; the stages share them as their contract.\n`eval-answer` writes `attempt`, `tool_call`, and `score`. An engine-side\n`eval-retrieval` skill, which does not ship here, writes `retrieval_score` and\n`probe`; both stay in this contract so one validator covers every run\ndirectory.\n`eval-diagnose` writes `issue` and `issue_status`. `eval-improve` writes\n`candidate`. `eval-loop` writes `acceptance_check`, further `issue_status`, and\n`checkpoint`.\n\n**The contract is code: `eval-answer/scripts/ledger.py`.** Every script that\nwrites `run.json` or `events.jsonl` builds its lines through that module, so a\nfield rename that reaches only one writer fails at write time. This document\nis the human-readable rendering; where the two disagree, the module is right\nand this file is the bug. Check any run directory with:\n\n```\npython3 skills/eval-answer/scripts/ledger.py validate <runDir>\n```\n\nErrors are broken identity (missing `run.json`, a missing required field, two\nscores for one attempt); warnings are missing comparison pins (a run without\n`skillsVersion` still measures, but cannot anchor an A/B on that pin) and\ngrandfathered unknown fields on old runs.\n\n## Layout\n\n```\nevals/<set>/\n  set.json                  # set metadata (below)\n  cases.jsonl               # one case per line\n  judge-regressions.jsonl   # judge verdicts a human overruled\n  runs/<runId>/\n    run.json                # run config, the attribution pins\n    events.jsonl            # append-only event lines\n    artifacts/              # prediction CSVs, judge outputs, transcripts\n```\n\nThe set directory lives in the SAME git repository as the model it evaluates,\nso a checkpoint (a git commit) pins the model and the ledger together. Never\nplace `evals/` inside the directory tree the answerer's package serves: gold\nin the served tree is a contamination path.\n\nRules that make the ledger trustworthy:\n\n- `events.jsonl` is append-only. Never edit a line. To void one, append a new\n  event whose payload marks the old one `voided`. One sanctioned exception: a\n  re-runnable stage (diagnose, improve) replaces ITS OWN prior events, keyed by\n  issue id, through `ledger.replace_events()` -- so a crash-and-rerun does not\n  duplicate issues. A stage never touches another stage's lines.\n- A stage never rewrites another stage's fields.\n- One artifact directory per attempt (`qid` plus `sample`). Never overwrite a\n  previous attempt's prediction CSV.\n- End-of-run numbers come from counting event lines (`jq` over\n  `events.jsonl`), never from arithmetic recalled in prose.\n\n## `set.json`\n\n| Field | Notes |\n|---|---|\n| `name` | Set name; also the directory name. |\n| `description` | |\n| `datasetVersion` | Integer. Bump on any golden repair or case change. Runs record the version they scored against. |\n| `targetModelPath` | Model path within the package. |\n| `truthPackage` | Name of the package holding the semantics-free sources every golden is re-derived from -- a package NAME, not an object. Without it `verify_goldens.py` re-derives nothing: it reports \"nothing to re-derive against\" and **exits 3**, which a caller must read as unverified rather than as a pass. The checks that need no truth server -- rubric figures, verification axis, stale rubric claims, set names -- still run and still report. `init_truth_package.py` scaffolds the package. |\n| `truthModel` | Model file inside that package. Default `truth.malloy`. |\n| `targetPackage` | Name of the package UNDER TEST. `verify_goldens.py` refuses a \"truth\" server that also serves it, because an answerer on that server can retrieve the raw truth sources beside the model and quietly change what is under test. `run_baseline.py` and `improve.py` pass the package they were given, so this field is the fallback for a direct call; without either the guard cannot fire. |\n| `truthTableRewrite` | Boolean, default false. Rewrites `duckdb.table('data/x.parquet')` refs to bare `x` in canonical queries, for a truth package whose tables are registered rather than read from files. |\n\n## `cases.jsonl`\n\nOne JSON object per line:\n\n| Field | Notes |\n|---|---|\n| `qid` | Stable case id. |\n| `question` | Exact text the answerer will see. |\n| `split` | `dev` or `holdout`. Frozen at import. Diagnose and improve read `dev` only; the acceptance check runs both. |\n| `tags` | list |\n| `state` | `candidate` / `selected` / `excluded`. |\n| `source` | Where the case came from. |\n| `golden` | `status` (`verified` / `provisional` / `invalid` / `ambiguous` / `verified_wrong`, the last being a key a person has established is wrong, which `run_baseline.py` drops from every aggregate), `kind`, `value` or `path` (artifact under the set directory), `canonicalQuery` (runs against the **truth** package, never the model under test), `verifiedBy`, and `verification` -- `{primaryAxis, variesAxis, note}` naming what the second derivation varied. **A golden is written only after two differently shaped derivations agree** (the truth query and a second one that varies a different axis -- group by something else, sum a different way, take a different route through the raw tables); `gold/<qid>.json` holds both (`truthRows`, `verifyRows`, `agreement`). Two derivations that vary the same axis share every other blind spot: that is how a golden that summed three overlapping time slices, 3x too high, passed its check. `verify_goldens.py` re-derives the value, reads the accepting clause of the rubric against the rows, and flags a second derivation that names no axis. **The question asks for data, never for an interpretation of it**, and either fixes the grain or the rubric accepts a correct figure at any stated grain (`skill:eval-judge` rules 10 and 11). |\n| `golden.kind` | What the key IS. A value (`scalar`, rows), `unanswerable`, or `criteria`: prose with no value, where the author's criteria are the whole key. `criteria` is the one kind that is legitimately `verified` on arrival, because there is no derivation to perform and nothing that can be numerically wrong; an imported key holding a VALUE is `provisional` until re-derived (`skill:eval-import`). **`verify_goldens.py --promote` is the only thing that writes `golden.status`**: it marks a `provisional` golden `verified` when its value re-derived cleanly from the truth package AND a second derivation exists. `--refresh` rewrites a drifted VALUE and never changes a status; `invalid` and `ambiguous` are settled by a person through the golden side door. |\n| `golden.rubric` | **On the golden, not on the case.** The prose the judge is shown as `CASE RUBRIC`, naming what counts as correct and what does not. `run_baseline.py` reads `golden.rubric`; a rubric written at the case's top level is silently not passed, the judge is told `CASE RUBRIC: none`, and it then scores from the golden value and the answer alone -- which reads as a judge that ignores its instructions. |\n| `golden.mustState` | **On the golden, not on the case.** What the answer has to say out loud. Read from `golden.mustState` by the run-package builder. |\n| `goldenRevision` | Integer. Bump on every golden change; `score` events stamp the revision they compared against. |\n| `expectedEntities` | `required`: entity ids (`kind:source:name`) the answer cannot be produced without. `requiredAnyOf`: a list of **groups**, each a list of ids of which any one suffices -- for a case the model can answer through more than one route. Naming only one route scores the other as a retrieval miss and steers the fix to the docs for an entity whose docs were never the problem. `acceptable`: ids that are not noise if returned. An entity counts as delivered when returned under its exact id, under the same type and name on a sibling source, or by name in a returned source's documentation; `score_retrieval.py` records the route per entity as `delivery`. |\n\n## Term files (`eval-retrieval` only)\n\nA customer set has no term file. The engine-side `eval-retrieval` skill keeps\n`intents.jsonl` fixtures -- search term, entity type, a description of what the\nsearcher meant, a validity flag -- beside its own scripts, for evaluating the\nengine against fixed inputs. Their shape and the `retrieval_score` events they\nproduce are documented there and validated here.\n\n## `run.json`\n\nThe attribution pins. Two runs are comparable only when these match where it\nmatters. Two runs with different `target` values are comparable on answer\nverdicts only if the same model version reached both, which is rarely worth\nassuming:\n\nRequired fields are the run's **identity** -- every run ever written carries\nthem. The rest are optional in the schema, but the **comparison pins** are\nwarned about when absent, because a run missing one cannot take part in an A/B\non that axis.\n\n| Field | Notes |\n|---|---|\n| `runId` *(required)* | Directory name. |\n| `target` *(required)* | Which server answered, and how it reached the data: `local`, `local-proxied`, or `platform`. Decides what an improve step is even allowed to do (see `skill:eval-loop`). |\n| `answererModel` *(required)* | |\n| `phase` / `started` *(required)* | |\n| `judgeModel` / `judgeVersion` / `rubricSha` *(pins)* | The judge's model, and the version + content sha of `skill:eval-judge`. |\n| `judgePromptSha` *(pin)* | Content sha of the prompt the judge is SHOWN, which is the harness's own template and not the skill file `rubricSha` covers. The template carries the golden rendering, the evidence blocks and the tie-breaking rules, so two runs whose prompts differed compared as the same judge -- the blind spot that let a golden-rendering defect run through three arms with every test passing, because the tests covered the code paths and not the text the model sees. Absent on runs written before it existed. |\n| `datasetVersion` *(pin)* | From `set.json` at run time. |\n| `modelSha` *(pin)* | Content sha of the `model.malloy` snapshot in the run directory -- the bytes the answerer actually queried. A git sha is not enough: a snapshot host serves a copy, often of a dirty tree no commit names. |\n| `skillsVersion` *(pin)* | HEAD of the checkout the agents' skills were loaded from, dirty-marked (`ledger.skills_git_sha(root)`). The skills are the doctrine the agents load; a run that cannot name their version cannot anchor a skills A/B. |\n| `skillsRoot` / `harnessVersion` | Which checkout supplied the doctrine (`--skills-root`, e.g. a Publisher checkout for the open-source skills; default this one), and this checkout's own HEAD. The eval-* skills always come from the harness checkout, whatever `skillsRoot` says. Two runs whose `skillsRoot` differ are a skills A/B only if their manifests name the same skills. |\n| `diagnoserModel` / `improverModel` | Written by `diagnose.py` / `improve.py` when those stages run, so the run names every LLM that touched it. Absent on a run that was only answered and judged. |\n| `modelGitSha` | Commit of the model repo, from `--model-repo`; `-dirty` suffix when that path had uncommitted changes -- fine for a band measurement, not for an A/B pin. **Null unless `--model-repo` names the repo.** It cannot be inferred: Publisher serves a COPY under `publisher_data/`, so the tree around the served file is the server's storage, not the model's history, and the field named that until 2026-09-03. `modelSha` above is the pin that always works; this is the pointer to where those bytes are versioned, and absent beats wrong. |\n| `modelRepo` | The path `--model-repo` named, so a reader can tell an absent pin from an unrecorded one. |\n| `modelDir` | The package directory `--model-dir` named, when it was: the path the `-dirty` marker on `modelGitSha` was decided over. Absent means the whole repo, where any unrelated untracked file marks the model dirty. |\n| `environment` / `package` / `modelPath` | What was served, and from where. On a platform target `environment` is the organization and `package` is the workspace the MCP URL is scoped to. |\n| `scope` | Platform target only: the `environment/package[@version]` the answerer was told to pass as an explicit `scopes` entry on every `get_context` / `execute_query` call. A workspace can serve many packages (a personal workspace serves every package the user can read), so without this the run also measures whether retrieval picks the right package -- a different measurement. Absent means unscoped. |\n| `targetVersion` *(pin)* | Platform target only: the published version the answers came from. Both hosted tools default an omitted version to the PINNED one, meaning whatever the workspace serves at the moment of the call, so this only describes the run when `--scope` carries it to every call. `--target-version` supplies it when the scope omits it; a scope naming a different version is refused rather than treated as an override, because a run cannot say which build answered if two pins disagree. |\n| `mcpUrl` / `publisher` | The endpoints the answerer and the re-execution used. |\n| `predictionsReExecuted` | Whether re-execution was POSSIBLE: the server was serving the bytes this run is pinned to. It is one bool for the whole run and says nothing about any given query, so it reads stronger than it is; `reExecution` below is what actually happened. |\n| `reExecution` | `{attempted, ok, failed, noQuery, notReExecuted, notJudged, missing}` over the run's predictions. `failed` means the query ran and the server returned an error, which is a different thing from an answer with no query at all. `notJudged` is a case the judge was never handed: a golden refused before judging (`provisional`, `invalid`, `ambiguous`, `verified_wrong`, missing), an attempt that submitted nothing, or every case under `--no-judge`. Those used to land in `missing` and read as corrupt artifacts on a freshly imported set. `ok`, `failed`, `noQuery`, `notReExecuted`, `notJudged` and `missing` partition the cases, so they sum to the case count; `attempted` is `ok + failed` and sits outside that sum. |\n| `retrievalMode` | Which retriever answered: `semantic`, `lexical`, `mixed` (it changed mid-run, so nothing can be averaged across it) or `unreported` (nothing ranked, which on a configured server means no embedding provider). Only a RANKING call names a retriever, so a call that enumerates a type or looks a name up is `unreported` on a fully semantic server and must not make the run read as `mixed`. Local retrieval degrades to lexical SILENTLY without an embedding key, and a pair compared across that reads as a model change, so `flip_table.py` refuses the pair unless both sides match. |\n| `retrievalCalls` | `{semantic, lexical, unreported}` call counts behind `retrievalMode`. `unreported` counts the calls that did not rank, which is a different thing from calls that fell back. |\n| `retrievalGate` | What the pre-arm retrieval gate found, or why it did not run. A run is held until `get_context` answers semantic twice in a row, because the first calls after a restart are lexical by design and an arm started immediately measures two retrievers. `not run (no answering phase)` under `--rebuild`/`--rejudge`, and `skipped by --no-retrieval-gate` when the operator opted out -- which is a different fact from a gate that passed, and the field is what tells them apart. |\n| `coverageReport` | The `check_coverage.py --out` report this run read, when `--coverage` named one: its path, the model version it was stamped with, its `agentModel`, and `decided` of `cases`. Coverage is a read of the MODEL, so it is measured separately and costs a judge call per case; the run does not run it, it consumes it. Its per-case verdict then beats the authored `coverage` label in retrieval attribution, and each `score_retrieval` row records `coverage_source` (`measured`, `authored`, `none`) so nobody has to guess which one charged the failure. Absent when no report was given, which is a different fact from a report that found everything covered. |\n| `label` | `<set>-<phase>-<nn>`, assigned by `run_baseline.py` from the set name, the run's phase and the next free number beside it (`ecommerce-baseline-01`, `ecommerce-baseline-02`, `ecommerce-blind_gate-01`). The A/A pair is two runs of the same phase; the post-edit arms are two runs of `blind_gate`. Hand-typed names do not survive one afternoon of runs -- `base`, `rejudged2`, `r3`, `post1` sort wrongly, group not at all, and cannot be matched to an arm. `--label` overrides for a run that genuinely needs a human name. |\n| `effort` | |\n| `maxTurns` / `answererTimeout` *(pins)* | The answerer's turn cap and per-attempt timeout, as the arm ran them. `skill:eval-loop` step 6 lists the call budget among the pins to freeze for a whole run, and nothing wrote one, so no two runs could be compared on the setting that decides whether a case got to finish at all. Distinct from `callBudget`, which no harness has ever written. Size the cap from a pilot rather than taking the default: on a 29-case arm at the default 30, completed attempts had a median of 17 turns and a 90th percentile of 26, and the four cases that ran past it were recorded as wrong answers. |\n| `truncated` / `contaminated` | The qids excluded for a HARNESS-owned reason: the cap cut the answer off, or the attempt breached isolation. Both leave the denominator, both are named here rather than only in the console, and either one makes `status` `incomplete`. |\n| `answererCostUsd` / `judgeCostUsd` | What the arm cost, split by role. The judge's half was discarded until 2026-09-02, so every \"cost per arm\" quoted before then was the answerer alone. Per-case judge cost is on each `score` event. |\n| `answererCostCopiedFrom` | The run whose attempts `answererCostUsd` was COPIED from, when this run spawned no answerer -- a `--rejudge`, a `--rebuild`, a `--from`. Those copy the source's attempt events verbatim, `cost_usd` included, so the figure is right about the attempts and wrong as this run's spend: one re-judge reported $17.56 of answering that never happened. Null when this run paid, so a total over several run files can skip the copies. |\n| `goldenCheck` | What `verify_goldens.py` said before the run started: `N ok, M drifted, K other finding(s)`, or why it did not run (no truth server on a platform target; `--skip-golden-check`; rebuild). A run that started on a drifted set says so here rather than pretending its verdicts mean something. `run_baseline` calls `verify()` without a model, so the set-name audit (check 5) does not run in-arm; the trailing `N stale entity name(s)` is the in-arm lint's own count, and `entity-name lint not run` says there was no model text to lint against. Without it the field read `0 other finding(s)` for a check that never happened. |\n| `staleEntityNames` | The `expectedEntities` names that appear nowhere in the served model, from the in-arm lint. Each one depresses the run's own recall on every case listing it, so a stale set reads as a retrieval failure until someone checks by hand. `null` when there was no model text to lint against (a platform target), which is a different fact from `[]`. |\n| `status` | `complete`; `aborted` when four consecutive attempts errored or found the server dead and the harness stopped rather than spend the rest of the budget on attempts nobody will trust; or `incomplete` when the arm ran to the end and still cannot report a rate, because `truncated` or `contaminated` is non-empty. `incomplete` is a third state, not a soft `complete`: the arm did everything asked of it and the number is still unearned. It does NOT stop the run being compared: `flip_table.py` scores the cases both arms did, and names the ones this arm left unscored -- an excluded case carries no verdict, so it can never be counted as a flip. |\n| `packageSha` / `servedRevision` *(pins)* | Taken from the server, not recomputed: `sourceContentSha` is a content hash over EVERY model path in the package, so an edit to an imported file moves it where a sha of the one `--model-path` does not; `servedRevision` is minted per load, so it identifies a load rather than content and is a poor pin alone. Measured: `publisher.json`'s `version` moves neither, and nothing in Publisher reads it -- it is not in the Package API schema and never returned, so it pins nothing. |\n| `datasetSha` *(pin)* | Content hash of `set.json` + `cases.jsonl`. Deliberately SEPARATE from the model's sha: a golden repair is not a model change, and one pin covering both would make every answer-key fix read as an edit to the model, which is the distinction an A/B rests on. Automatic, so nobody has to remember it; `datasetVersion` stays beside it as the human-readable sequence. **Local targets only.** A hosted target that publishes IMMUTABLE versions needs none of this: the set rides inside the version, and immutability -- not hashing -- is what makes a pin trustworthy. There, `targetVersion` alone identifies model and set together. |\n| `doubtedGoldens` | The cases whose golden is not believed: `qid`, `gold_status` (`suspect` or `verified_wrong`), `gold_note`, and `declaredBy` (`judge` or `set`). A status the SET declared is a key somebody already settled, not an opinion the judge formed this run, and attributing both to the judge claimed a judgement that never happened. **Read this before diagnose.** These are dataset issues, not model failures, and they go through the golden side door in `skill:eval-loop`. Empty list when no key is in doubt from either source. Written from the same scan that prints the end-of-run warning, because a warning that lives only in console text is one scrollback away from sending a modelling agent at a model that is already right. |\n| `mode` / `setName` / `serverVersion` / `traceMode` / `callBudget` | Defined and accepted, **not yet written by any harness** -- kept in the schema for the platform target and the conductor, which need them. (`targetVersion` and `status` were in this list and are both written now.) |\n\n## Events\n\nEvery line in `events.jsonl` is **flat**: `{ \"kind\": ..., <fields> }`, one\nJSON object per line, with an optional `at` ISO timestamp. Case-scoped kinds\n(`attempt`, `tool_call`, `score`) carry `qid`, `sample`, `phase` on the line;\nrun-level kinds do not. (An earlier draft of this document nested fields under\na `payload` with a `caseId`; no writer ever did that, and 23 run directories\nexist in the flat shape, so the flat shape is the contract.) `kind` is one of:\n`attempt`, `tool_call`, `score`, `retrieval_score`, `issue`, `issue_status`,\n`candidate`, `acceptance_check`, `checkpoint`.\n\n### `attempt`\n\n| Field | Type | Notes |\n|---|---|---|\n| `qid` | string | |\n| `sample` | int or null | Which repeat. Required even when null. |\n| `phase` | string | `baseline` / `loop` / `blind_gate` / `canary` / `final`. `phase` lives here, on the attempt, not in run config. |\n| `question_sha` | string | Hash of the exact text the answerer saw, so two runs can be compared on whether they asked the same thing. A case may carry `questionSha`, the seal stamped at conversion, and that wins when present; the ecommerce set writes a 16-char prefix of it, and a set without one left this null. Neither form proves the question was not edited, since both follow the case as it now reads: that comparison is check 6 of `verify_goldens.py`. |\n| `submitted` | bool | False when there was no final query. Not a wrong answer. |\n| `final_query` | string or null | Required to replay. A named view is recorded as the Malloy it stands for, `run: <source> -> <view>`, so every consumer sees one shape and the query re-executes. |\n| `final_query_source` | string or null | How `final_query` was chosen: `declared` (the answer printed it), `last_ok` (the last call the server answered) or `last`. `last` is a warning: a trailing sanity probe may be standing in for the answer's own query. |\n| `servedRevision` | string or null | From the package actually queried. |\n| `n_get_context` / `n_execute` / `n_execute_errors` | int | |\n| `host_tool_uses` | int | EVERY tool use the host logged, MCP calls included. It counted only the non-MCP ones until 2026-09-03, which made the under-report check below true of almost every clean attempt. |\n| `mcp_tool_uses` | int or null | The MCP subset: `get_context` plus `execute_query`. Null on a run written before the split. |\n| `reported_calls` | int | MCP calls the answerer claimed. `reported_calls > host_tool_uses` is the under-report floor from `skill:eval-answer`: the answerer cannot have made more calls than the host logged. `validate_run` warns on it, and only for runs that carry `mcp_tool_uses`, because the field meant something narrower before. |\n| `contaminated` | bool or `\"unknown\"` | `\"unknown\"` when no host log exists. Read it with `ledger.is_contaminated`, never for truthiness: runs written before 2026-09-03 carry the strings `\"true\"`/`\"false\"`, and `bool(\"false\")` is True. `ledger.event` now rejects those strings on write; `validate_run` grandfathers them on read as a warning. |\n| `contamination_reasons` | list | Empty when clean. |\n| `input_tokens` / `output_tokens` / `cache_read_tokens` / `cache_write_tokens` | int or null | Answerer token usage, the four counts that reprice a run from its own ledger. Null when the host does not report it. `cost_usd` beside them comes from the CLI's `total_cost_usd`, which prices cache reads and writes at their rates, so it was always cache-inclusive; what was missing was the breakdown that reproduces it. `cache_write_tokens` (`cache_creation_input_tokens` upstream) was never captured before 2026-09-15, and on one analysed run cache writes were 44% of the agent's cost, the single largest line. **Read `input_tokens` with care:** it counts only the tokens after the last cache breakpoint. One run recorded 224 for 24 questions beside 2.4M cache reads; the 224 is not the context volume, and a token total that omits the cache columns is not a size. |\n| `cost_usd` | float or null | Answerer cost for this attempt. |\n| `num_turns` / `wall_seconds` | int, float or null | |\n| `answer_text` | string or null | The answer the judge scored. Kept so a verdict can be re-read without the transcript. |\n| `skills_invoked` | list of string | The skills the answerer invoked through the `Skill` tool, deduplicated and sorted, counted from its own transcript. Always a list on a run that recorded it, so an EMPTY list is the finding: the arm granted a manifest and the agent reached for none of it. Absent on runs written before 2026-09-15, which is why every reader takes `or []`. Only explicit `Skill` calls are counted, and only skills the arm granted -- one outside `--answerer-skills` is a contamination breach and lands in `contamination_reasons` instead. What it is for: a manifest names what an arm GRANTED, and comparing two arms' doctrine is meaningless if the doctrine never loaded. |\n| `transcriptPath` | string | The answerer's transcript under `artifacts/`. |\n\nToken counts sit here rather than being derived later because the claim a\nsemantic model makes is about cost as well as correctness -- that a documented\nmodel reaches a good answer in fewer turns and tokens than working from raw\nschema. A ledger that counts calls but not tokens can state half of that.\n\n### `tool_call`\n\nOne event per MCP `get_context` or `execute_query` the attempt made.\n\n| Field | Type | Notes |\n|---|---|---|\n| `tool` | string | `get_context` or `execute_query`. |\n| `traceId` | string or null | `get_context` only; look up in your host's trace store. |\n| `targets` | string, list or null | **What the answerer asked for**: the search terms it sent to `get_context`. Null for `execute_query`. |\n| `rankedSummary` | object | Copied at capture so evidence survives trace eviction: `entityIds` (identity, in response order), `hits` (one row per entity: `entity_id`, `source`, `relevance`, `matched_targets`, `position`, `position_in_source`), `resultCount`, `docTokens`. **There is no rank.** This field previously documented `ranks` and \"per-target `targets` with within-target ranks\"; no writer ever wrote either, and what `ranks` did hold was `range(1, n+1)` over a list already flattened source-card by source-card -- a position, not a rank, and not even a relevance order, since the response sorts globally and then buckets into cards. Ask relevance questions of `hits[].relevance`. |\n| `rankedSummary.hits[].matched_targets` | list or null | Which of the caller's search targets matched this entity, each with the server's own relevance. **`null` means no attribution was published**, which is not the same as `[]`: the server attaches it to entities only (a source card's attribution is discarded before an entity object exists) and only on the semantic path, because a lexical score is relative to its own query and comparing two of them means nothing. A lexical run therefore cannot say which target found what, and a reader must report that as unavailable rather than as \"never asked\". |\n| `retrieval_mode` | string or null | `get_context` only: the `retrieval` field of the response that answered, `semantic` or `lexical`. Null when the server named none, which means no embedding provider. Recorded per call because the semantic path can fall over partway through a run. |\n| `query` | string or null | `execute_query` only: the Malloy the call sent, so the final query can be chosen by which call the server actually answered. |\n| `modelPath` | string or null | `execute_query` only: the model file the call named. A source does not resolve outside the file that declares it, so re-execution needs this. |\n| `error` | string or null | |\n\nNever persist `execute_query` result rows, givens, or credentials.\n\n`targets` records the request; `rankedSummary` records the response. Without\nboth, a low per-attempt recall has two readings that cannot be told apart: the\nanswerer searched for the wrong thing, or it searched well and retrieval ranked\nthe right entity too low. Those have opposite owners -- `agent-skill` and\n`retrieval` -- so a ledger holding only the response cannot attribute the\nfailure, and any recall computed from it is a blend of answerer behaviour and\nretrieval quality.\n\nThat blend is also why per-attempt recall is **not** comparable across arms: a\nstronger answerer searches better and scores higher retrieval recall without\nretrieval having changed. Use it for attribution within an arm. Comparing\nretrieval itself between engine versions is `eval-retrieval`'s job, with fixed\nterms, and is not something a customer run reports.\n\n### `score`\n\nThe answer judge's verdict for one attempt (protocol in\n`skill:eval-judge`). Every attempt in a scored run gets exactly one.\n\n| Field | Type | Notes |\n|---|---|---|\n| `verdict` | string or null | `match` / `near_match` / `no_match` / `needs_human`; null when the attempt is not scorable. Only `match` and `no_match` are decisions; see below. |\n| `reason` | string | Why, from the judge; for a null verdict, why not scorable, and it is ALWAYS one of these: `not_submitted`, `answerer_truncated`, `contaminated`, `judge_unparseable`, `no_saved_verdict`, `judge_error: <text>`, or `golden_<status>` -- `golden_missing`, `golden_provisional`, `golden_invalid`, `golden_ambiguous`, `golden_verified_wrong`. A null verdict never arrives without one: a nulling that does not say which of these it was is indistinguishable from the field being dropped on the write path, and was read as exactly that from a real run. The `golden_*` reasons and `answerer_truncated` are decided before the judge is called, so neither an unestablished key nor a cut-off attempt costs a judge call. |\n| `confidence` | int or null | 1 to 10. Confidence of 5 or lower forces `needs_human`. |\n| `column_pairing` | object or null | The judge's named gold-to-prediction column correspondence. |\n| `judge_version` / `rubric_sha` | string | Pins which rubric produced this verdict. |\n| `golden_revision` | int | From the case at score time. |\n| `contaminated` | bool or `\"unknown\"` | Copied from the attempt; true or unknown means `verdict: null`. |\n| `must_not_use_hits` | list or null | Entries of `golden.mustNotUse` a script found in the final query. A hit forces `verdict: no_match`. Decided by `check_must_not_use.py`, never by the judge: it is a question about query text. Only a BARE name vetoes; an entry with a connective (`X as ...`, `X through ...`) objects to a use of X rather than to X, and goes to the judge with the prose entries and a path's bare leaf. |\n| `judge_verdict` | string or null | What the judge said when a MECHANICAL override replaced it: a `must_not_use_hits` veto, or contamination voiding the verdict. Null otherwise, so the judge's own agreement rate stays measurable across both. When a case is vetoed AND contaminated this still holds the judge's read, not the veto's `no_match`. |\n| `artifactPath` | string | The full judge output under `artifacts/`. |\n| `gold_status` | string | `verified` / `verified_benign` / `suspect` / `verified_wrong`, and never anything else: the case file's `golden.status` is a DIFFERENT vocabulary that shares only `verified` and `verified_wrong`, and only those two fall back into this field. A `provisional` / `invalid` / `ambiguous` key is reported through the verdict's `reason` (`golden_<status>`) instead, so nothing downstream has to match on two vocabularies in one field. **From the judge**, which scored against the golden as written and reports separately whether it believes it; falls back to the case's standing `golden.status` when the judge does not say, written onto the verdict itself so the run summary and the aggregates see it too. `verified_wrong` excludes the case from run aggregates -- from the judge OR from the case file; assigning the fallback into a copy of the verdict meant a key the set had marked wrong stayed in the aggregates unless the judge independently agreed. `suspect` and `verified_wrong` route to the golden side door as `dataset` issues, never to improve. |\n| `gold_note` | string or null | The judge's evidence for a non-`verified` status: the two values, or the model line against the rubric sentence. Null when `verified`. |\n\nA `golden_*` reason means the ANSWER KEY is not something a verdict can be\nissued against. A golden the set stamps `provisional`, `invalid` or `ambiguous`\nis refused, as is a case with no golden at all and one the set marks\n`verified_wrong`; a golden with NO `status` is unguarded rather than\nunscorable, because sets that predate the field would otherwise score zero of\nzero. A golden holding no value is not refused either: that is how a\n`kind: unanswerable` case and a `kind: criteria` golden are written. This\nmatters most for an imported set, because `skill:eval-import` stamps\n`provisional` on every golden it writes and enforces it -- so a set is\nunscorable by construction until its keys are re-derived, and `run_baseline`\nrefuses to spend at all when every case in a set is in that state.\n\n`not_submitted` means the attempt produced NOTHING to judge: no answer text and\nno query. An attempt that wrote prose without querying **is judged**, and\nagainst a golden that holds a value an answer containing none of it is\n`no_match` (`skill:eval-judge`, `reference/refusal.md` rule 10). Excusing those\nas unscorable dropped a confident refusal on an answerable case out of the pass\nrate, which is the one thing the answerable-sounds-unanswerable cases exist to\nmeasure. A refusal is exempt only where `golden.kind` is `unanswerable`, and\nthere naming the gap is the pass and a confident number is the fail.\n\n`answerer_truncated` means the answerer hit the run's `maxTurns` cap and the\nCLI returned whatever it had, which is usually a sentence stopping mid-thought.\nIt is refused BEFORE the golden gate and before a saved verdict is reused, so\n`--rebuild` over a run made without this re-derives the right ledger from its\ntranscripts. A cap is a harness setting, so a case cut off by one says nothing\nabout whether the model could answer it: measured on one 29-case arm, four\nattempts ended at exactly 31 turns and each was judged as a wrong answer, one\nof them on the text \"Let me build the correct monthly trend query.\"\n\n`contaminated` means the attempt breached isolation (`contamination_reasons`\nnames how) and the verdict is withheld rather than lost. The judge's own read\nmoves to `judge_verdict`. Before this reason was written, a voided verdict kept\nthe judge's prose in `reason` beside `verdict: null`, and a run report\nreasonably concluded the ledger was dropping the field -- it recovered nine\n\"lost\" verdicts by re-parsing the stored judge replies, every one of which had\nbeen voided on purpose.\n\nBoth are HARNESS-owned, not model-owned, and a run containing either reports\n`status: incomplete` in `run.json` and **prints no pass rate**. `unscorable`\n(no established golden) and `judge_unparseable` do not suppress the rate: the\nfirst is a dataset state no arm can fix, and the second already has a retry.\n\nAggregates count decided verdicts only. `match` and `no_match` are the pass and\nthe fail; **`near_match`, `needs_human` and null are none of the above** and stay\nout of acceptance arithmetic. `near_match` is excluded because it means \"defensibly\ndifferent\", and an arguable verdict that moves a pass rate is a measurement\nartefact rather than a result (`skill:eval-judge` rule 7). Report its count:\nit rising is how a set tells you its rubrics are going vague.\n\nThis applies to `score`. On `retrieval_score` below, `near_match` **is** counted\ntowards recall and precision, because an overlapping entity is a genuine\nretrieval success. The two are different questions that share a word.\n\n### `retrieval_score` (written by `eval-retrieval`, not by a customer run)\n\nOne per term judged in a fixed-term replay (run-level; no `caseId`).\n\n| Field | Type | Notes |\n|---|---|---|\n| `intentId` / `term` / `entityType` | string | From the term file. |\n| `in_scope` | bool | Does THIS model version represent the concept? False is a coverage gap, not a retrieval failure. |\n| `judgments` | list | Per returned entity: `entityId`, `rank`, `level` (`match` / `near_match` / `no_match`), `confidence`, `why`. Empty when nothing returned. |\n| `judge_version` / `rubric_sha` | string | |\n| `traceId` | string or null | The `get_context` call judged. |\n\nRun-level metrics fall out by counting:\n\n- `coverage` = in-scope terms / valid terms -- a property of the model and its\n  data, reported on its own, never as a retrieval number.\n- `recall` (on in-scope terms) = fraction whose judgments contain a `match`.\n- `precision@N` = `match` judgments / judged, with N stated.\n\n### `issue`\n\n| Field | Type | Notes |\n|---|---|---|\n| `issue_id` | string | Stable across status events. |\n| `qids` | list | Affected cases. |\n| `primary_code` / `contributing_codes` | string / list | From `skill:eval-diagnose`, verbatim. |\n| `component` | string | `dataset` / `agent-call` / `get_context/model` / `get_context/retrieval` / `construction` / `model-definition`. |\n| `owner` | string | `model` / `retrieval` / `agent-skill` / `dataset`. Environment failures stop the run; they are never diagnosed, so there is no environment owner. |\n| `severity` / `confidence` | string | |\n| `sufficiency` | string | `sufficient` / `insufficient` / `unknown`. |\n| `traceIds` | list | |\n| `diagnosis` | string | Written before any edit exists. |\n\n### `issue_status`\n\n`issue_id` plus `status`: `open` / `batched` / `fixed` / `rejected` /\n`deferred`. Readers take the latest event for that `issue_id`. Do not invent\na status column.\n\n### `candidate`\n\nWritten by `eval-improve`, for every proposed edit, accepted or not. A\nrejected direction keeps its record.\n\n| Field | Notes |\n|---|---|\n| `issue_ids` | |\n| `files` | Paths the edit touched. |\n| `diffSummary` | One line per file. |\n| `probes` | Query and result for each factual claim. |\n| `meaningChanged` | Entities whose *meaning* the edit changed; `[]` for a docs-only edit. |\n| `goldenSuspect` | Each `{qid, entity, stored, rederived}`: a golden this edit may have invalidated. Reported by the improver, never repaired by it. **Non-empty halts the acceptance check** until adjudicated through the golden side door. |\n| `goldenAudit` | The set's `verify_goldens.py` run against the edited model: `{ran, clean, model, tail}`. Catches drift and rubric-vs-model contradictions only; a golden whose value silently moved is invisible to it, which is why `goldenSuspect` exists alongside. |\n\n### `acceptance_check`\n\nCalled `gate` before 2026-09-03. `ledger.py` reads the old kind as this one, so\nrun directories written earlier still validate and nothing rewrites them.\n\nWritten by `eval-loop`, one per acceptance check decision, BEFORE any checkpoint commit.\n\n| Field | Notes |\n|---|---|\n| `issue_ids` | |\n| `decision` | `accepted` / `rejected`. |\n| `class` | `docs` / `definition` / `retrieval` / `justified`. |\n| `baselineRunId` / `finalRunIds` | Plural: acceptance needs two independent runs. |\n| `regressions` | Case ids whose verdict got worse vs baseline. Must be empty to accept. |\n| `holdoutDelta` | Confident-verdict delta on the holdout slice. |\n| `reason` | Including independent deterministic justification when that is the basis. |\n\n### `checkpoint`\n\nWritten by `eval-loop` after an accepted acceptance check, or when a restore runs. The\nmodel bytes live in git, not in this payload.\n\n| Field | Notes |\n|---|---|\n| `action` | `created` / `restored`. |\n| `label` | |\n| `modelGitSha` | The commit this checkpoint names (create), or the commit restored to. |\n| `issueIds` | Issues the accepted edit closed. Empty on restore. |\n\n## `judge-regressions.jsonl`\n\nAppend a line whenever a human overrules a judge verdict: the case or intent,\nthe judge's verdict, the human's, and why. Re-run this file against the judge\nwhenever `skill:eval-judge` or the judge model changes; a rubric change that\nflips old human-settled verdicts is a judge regression, not new truth."
+      body: "# The eval ledger: files and events\n\nThe ledger is plain files in the model package's git repository. There is no\neval API and no eval database. The conductor (`skill:eval-loop`) reads and\nwrites these files directly; the stages share them as their contract.\n`eval-answer` writes `attempt`, `tool_call`, and `score`. An engine-side\n`eval-retrieval` skill, which does not ship here, writes `retrieval_score` and\n`probe`; both stay in this contract so one validator covers every run\ndirectory.\n`eval-diagnose` writes `issue` and `issue_status`. `eval-improve` writes\n`candidate`. `eval-loop` writes `acceptance_check`, further `issue_status`, and\n`checkpoint`.\n\n**The contract is code: `eval-answer/scripts/ledger.py`.** Every script that\nwrites `run.json` or `events.jsonl` builds its lines through that module, so a\nfield rename that reaches only one writer fails at write time. This document\nis the human-readable rendering; where the two disagree, the module is right\nand this file is the bug. Check any run directory with:\n\n```\npython3 skills/eval-answer/scripts/ledger.py validate <runDir>\n```\n\nErrors are broken identity (missing `run.json`, a missing required field, two\nscores for one attempt); warnings are missing comparison pins (a run without\n`skillsVersion` still measures, but cannot anchor an A/B on that pin) and\ngrandfathered unknown fields on old runs.\n\n## Layout\n\n```\nevals/<set>/\n  set.json                  # set metadata (below)\n  cases.jsonl               # one case per line\n  judge-regressions.jsonl   # judge verdicts a human overruled\n  runs/<runId>/\n    run.json                # run config, the attribution pins\n    events.jsonl            # append-only event lines\n    artifacts/              # prediction CSVs, judge outputs, transcripts\n```\n\nThe set directory lives in the SAME git repository as the model it evaluates,\nso a checkpoint (a git commit) pins the model and the ledger together. Never\nplace `evals/` inside the directory tree the answerer's package serves: gold\nin the served tree is a contamination path.\n\nRules that make the ledger trustworthy:\n\n- `events.jsonl` is append-only. Never edit a line. To void one, append a new\n  event whose payload marks the old one `voided`. One sanctioned exception: a\n  re-runnable stage (diagnose, improve) replaces ITS OWN prior events, keyed by\n  issue id, through `ledger.replace_events()` -- so a crash-and-rerun does not\n  duplicate issues. A stage never touches another stage's lines.\n- A stage never rewrites another stage's fields.\n- One artifact directory per attempt (`qid` plus `sample`). Never overwrite a\n  previous attempt's prediction CSV.\n- End-of-run numbers come from counting event lines (`jq` over\n  `events.jsonl`), never from arithmetic recalled in prose.\n\n## `set.json`\n\n| Field | Notes |\n|---|---|\n| `name` | Set name; also the directory name. |\n| `description` | |\n| `datasetVersion` | Integer. Bump on any golden repair or case change. Runs record the version they scored against. |\n| `targetModelPath` | Model path within the package. |\n| `truthPackage` | Name of the package holding the semantics-free sources every golden is re-derived from -- a package NAME, not an object. Without it `verify_goldens.py` re-derives nothing: it reports \"nothing to re-derive against\" and **exits 3**, which a caller must read as unverified rather than as a pass. The checks that need no truth server -- rubric figures, verification axis, stale rubric claims, set names -- still run and still report. `init_truth_package.py` scaffolds the package. |\n| `truthModel` | Model file inside that package. Default `truth.malloy`. |\n| `targetPackage` | Name of the package UNDER TEST. `verify_goldens.py` refuses a \"truth\" server that also serves it, because an answerer on that server can retrieve the raw truth sources beside the model and quietly change what is under test. `run_baseline.py` and `improve.py` pass the package they were given, so this field is the fallback for a direct call; without either the guard cannot fire. |\n| `truthTableRewrite` | Boolean, default false. Rewrites `duckdb.table('data/x.parquet')` refs to bare `x` in canonical queries, for a truth package whose tables are registered rather than read from files. |\n\n## `cases.jsonl`\n\nOne JSON object per line:\n\n| Field | Notes |\n|---|---|\n| `qid` | Stable case id. |\n| `question` | Exact text the answerer will see. |\n| `split` | `dev` or `holdout`. Frozen at import. Diagnose and improve read `dev` only; the acceptance check runs both. |\n| `tags` | list |\n| `state` | `candidate` / `selected` / `excluded`. |\n| `source` | Where the case came from. |\n| `golden` | `status` (`verified` / `provisional` / `invalid` / `ambiguous` / `verified_wrong`, the last being a key a person has established is wrong, which `run_baseline.py` drops from every aggregate), `kind`, `value` or `path` (artifact under the set directory), `canonicalQuery` (runs against the **truth** package, never the model under test), `verifiedBy`, and `verification` -- `{primaryAxis, variesAxis, note}` naming what the second derivation varied. **A golden is written only after two differently shaped derivations agree** (the truth query and a second one that varies a different axis -- group by something else, sum a different way, take a different route through the raw tables); `gold/<qid>.json` holds both (`truthRows`, `verifyRows`, `agreement`). Two derivations that vary the same axis share every other blind spot: that is how a golden that summed three overlapping time slices, 3x too high, passed its check. `verify_goldens.py` re-derives the value, reads the accepting clause of the rubric against the rows, and flags a second derivation that names no axis. **The question asks for data, never for an interpretation of it**, and either fixes the grain or the rubric accepts a correct figure at any stated grain (`skill:eval-judge` rules 10 and 11). |\n| `golden.kind` | What the key IS. A value (`scalar`, rows), `unanswerable`, or `criteria`: prose with no value, where the author's criteria are the whole key. `criteria` is the one kind that is legitimately `verified` on arrival, because there is no derivation to perform and nothing that can be numerically wrong; an imported key holding a VALUE is `provisional` until re-derived (`skill:eval-import`). **`verify_goldens.py --promote` is the only thing that writes `golden.status`**: it marks a `provisional` golden `verified` when its value re-derived cleanly from the truth package AND a second derivation exists. `--refresh` rewrites a drifted VALUE and never changes a status; `invalid` and `ambiguous` are settled by a person through the golden side door. |\n| `golden.rubric` | **On the golden, not on the case.** The prose the judge is shown as `CASE RUBRIC`, naming what counts as correct and what does not. `run_baseline.py` reads `golden.rubric`; a rubric written at the case's top level is silently not passed, the judge is told `CASE RUBRIC: none`, and it then scores from the golden value and the answer alone -- which reads as a judge that ignores its instructions. |\n| `golden.mustState` | **On the golden, not on the case.** What the answer has to say out loud. Read from `golden.mustState` by the run-package builder. |\n| `goldenRevision` | Integer. Bump on every golden change; `score` events stamp the revision they compared against. |\n| `expectedEntities` | `required`: entity ids (`kind:source:name`) the answer cannot be produced without. `requiredAnyOf`: a list of **groups**, each a list of ids of which any one suffices -- for a case the model can answer through more than one route. Naming only one route scores the other as a retrieval miss and steers the fix to the docs for an entity whose docs were never the problem. `acceptable`: ids that are not noise if returned. An entity counts as delivered when returned under its exact id, under the same type and name on a sibling source, or by name in a returned source's documentation; `score_retrieval.py` records the route per entity as `delivery`. |\n\n## Term files (`eval-retrieval` only)\n\nA customer set has no term file. The engine-side `eval-retrieval` skill keeps\n`intents.jsonl` fixtures -- search term, entity type, a description of what the\nsearcher meant, a validity flag -- beside its own scripts, for evaluating the\nengine against fixed inputs. Their shape and the `retrieval_score` events they\nproduce are documented there and validated here.\n\n## `run.json`\n\nThe attribution pins. Two runs are comparable only when these match where it\nmatters. Two runs with different `target` values are comparable on answer\nverdicts only if the same model version reached both, which is rarely worth\nassuming:\n\nRequired fields are the run's **identity** -- every run ever written carries\nthem. The rest are optional in the schema, but the **comparison pins** are\nwarned about when absent, because a run missing one cannot take part in an A/B\non that axis.\n\n| Field | Notes |\n|---|---|\n| `runId` *(required)* | Directory name. |\n| `target` *(required)* | Which server answered, and how it reached the data: `local`, `local-proxied`, or `platform`. Decides what an improve step is even allowed to do (see `skill:eval-loop`). |\n| `answererModel` *(required)* | |\n| `phase` / `started` *(required)* | |\n| `judgeModel` / `judgeVersion` / `rubricSha` *(pins)* | The judge's model, and the version + content sha of `skill:eval-judge`. |\n| `judgePromptSha` *(pin)* | Content sha of the prompt the judge is SHOWN, which is the harness's own template and not the skill file `rubricSha` covers. The template carries the golden rendering, the evidence blocks and the tie-breaking rules, so two runs whose prompts differed compared as the same judge -- the blind spot that let a golden-rendering defect run through three arms with every test passing, because the tests covered the code paths and not the text the model sees. Absent on runs written before it existed. |\n| `datasetVersion` *(pin)* | From `set.json` at run time. |\n| `modelSha` *(pin)* | Content sha of the `model.malloy` snapshot in the run directory -- the bytes the answerer actually queried. A git sha is not enough: a snapshot host serves a copy, often of a dirty tree no commit names. |\n| `skillsVersion` *(pin)* | HEAD of the checkout the agents' skills were loaded from, dirty-marked (`ledger.skills_git_sha(root)`). The skills are the doctrine the agents load; a run that cannot name their version cannot anchor a skills A/B. |\n| `skillsRoot` / `harnessVersion` | Which checkout supplied the doctrine (`--skills-root`, e.g. a Publisher checkout for the open-source skills; default this one), and this checkout's own HEAD. The eval-* skills always come from the harness checkout, whatever `skillsRoot` says. Two runs whose `skillsRoot` differ are a skills A/B only if their manifests name the same skills. |\n| `diagnoserModel` / `improverModel` | Written by `diagnose.py` / `improve.py` when those stages run, so the run names every LLM that touched it. Absent on a run that was only answered and judged. |\n| `modelGitSha` | Commit of the model repo, from `--model-repo`; `-dirty` suffix when that path had uncommitted changes -- fine for a band measurement, not for an A/B pin. **Null unless `--model-repo` names the repo.** It cannot be inferred: Publisher serves a COPY under `publisher_data/`, so the tree around the served file is the server's storage, not the model's history, and the field named that until 2026-09-03. `modelSha` above is the pin that always works; this is the pointer to where those bytes are versioned, and absent beats wrong. |\n| `modelRepo` | The path `--model-repo` named, so a reader can tell an absent pin from an unrecorded one. |\n| `modelDir` | The package directory `--model-dir` named, when it was: the path the `-dirty` marker on `modelGitSha` was decided over. Absent means the whole repo, where any unrelated untracked file marks the model dirty. |\n| `environment` / `package` / `modelPath` | What was served, and from where. On a platform target `environment` is the organization and `package` is the workspace the MCP URL is scoped to. |\n| `scope` | Platform target only: the `environment/package[@version]` the answerer was told to pass as an explicit `scopes` entry on every `get_context` / `execute_query` call. A workspace can serve many packages (a personal workspace serves every package the user can read), so without this the run also measures whether retrieval picks the right package -- a different measurement. Absent means unscoped. |\n| `targetVersion` *(pin)* | Platform target only: the published version the answers came from. Both hosted tools default an omitted version to the PINNED one, meaning whatever the workspace serves at the moment of the call, so this only describes the run when `--scope` carries it to every call. `--target-version` supplies it when the scope omits it; a scope naming a different version is refused rather than treated as an override, because a run cannot say which build answered if two pins disagree. |\n| `mcpUrl` / `publisher` | The endpoints the answerer and the re-execution used. |\n| `predictionsReExecuted` | Whether re-execution was POSSIBLE: the server was serving the bytes this run is pinned to. It is one bool for the whole run and says nothing about any given query, so it reads stronger than it is; `reExecution` below is what actually happened. |\n| `reExecution` | `{attempted, ok, failed, noQuery, notReExecuted, notJudged, missing}` over the run's predictions. `failed` means the query ran and the server returned an error, which is a different thing from an answer with no query at all. `notJudged` is a case the judge was never handed: a golden refused before judging (`provisional`, `invalid`, `ambiguous`, `verified_wrong`, missing), an attempt that submitted nothing, or every case under `--no-judge`. Those used to land in `missing` and read as corrupt artifacts on a freshly imported set. `ok`, `failed`, `noQuery`, `notReExecuted`, `notJudged` and `missing` partition the cases, so they sum to the case count; `attempted` is `ok + failed` and sits outside that sum. |\n| `retrievalMode` | Which retriever answered: `semantic`, `lexical`, `mixed` (it changed mid-run, so nothing can be averaged across it) or `unreported` (nothing ranked, which on a configured server means no embedding provider). Only a RANKING call names a retriever, so a call that enumerates a type or looks a name up is `unreported` on a fully semantic server and must not make the run read as `mixed`. Local retrieval degrades to lexical SILENTLY without an embedding key, and a pair compared across that reads as a model change, so `flip_table.py` refuses the pair unless both sides match. |\n| `retrievalCalls` | `{semantic, lexical, unreported}` call counts behind `retrievalMode`. `unreported` counts the calls that did not rank, which is a different thing from calls that fell back. |\n| `retrievalGate` | What the pre-arm retrieval gate found, or why it did not run. A run is held until `get_context` answers semantic twice in a row, because the first calls after a restart are lexical by design and an arm started immediately measures two retrievers. `not run (no answering phase)` under `--rebuild`/`--rejudge`, and `skipped by --no-retrieval-gate` when the operator opted out -- which is a different fact from a gate that passed, and the field is what tells them apart. |\n| `coverageReport` | The `check_coverage.py --out` report this run read, when `--coverage` named one: its path, the model version it was stamped with, its `agentModel`, and `decided` of `cases`. Coverage is a read of the MODEL, so it is measured separately and costs a judge call per case; the run does not run it, it consumes it. Its per-case verdict then beats the authored `coverage` label in retrieval attribution, and each `score_retrieval` row records `coverage_source` (`measured`, `authored`, `none`) so nobody has to guess which one charged the failure. Absent when no report was given, which is a different fact from a report that found everything covered. |\n| `label` | `<set>-<phase>-<nn>`, assigned by `run_baseline.py` from the set name, the run's phase and the next free number beside it (`ecommerce-baseline-01`, `ecommerce-baseline-02`, `ecommerce-blind_gate-01`). The A/A pair is two runs of the same phase; the post-edit arms are two runs of `blind_gate`. Hand-typed names do not survive one afternoon of runs -- `base`, `rejudged2`, `r3`, `post1` sort wrongly, group not at all, and cannot be matched to an arm. `--label` overrides for a run that genuinely needs a human name. |\n| `effort` | |\n| `maxTurns` / `answererTimeout` *(pins)* | The answerer's turn cap and per-attempt timeout, as the arm ran them. `skill:eval-loop` step 6 lists the call budget among the pins to freeze for a whole run, and nothing wrote one, so no two runs could be compared on the setting that decides whether a case got to finish at all. Distinct from `callBudget`, which no harness has ever written. Size the cap from a pilot rather than taking the default: on a 29-case arm at the default 30, completed attempts had a median of 17 turns and a 90th percentile of 26, and the four cases that ran past it were recorded as wrong answers. |\n| `truncated` / `contaminated` | The qids excluded for a HARNESS-owned reason: the cap cut the answer off, or the attempt breached isolation. Both leave the denominator, both are named here rather than only in the console, and either one makes `status` `incomplete`. |\n| `answererCostUsd` / `judgeCostUsd` | What the arm cost, split by role. The judge's half was discarded until 2026-09-02, so every \"cost per arm\" quoted before then was the answerer alone. Per-case judge cost is on each `score` event. |\n| `answererCostCopiedFrom` | The run whose attempts `answererCostUsd` was COPIED from, when this run spawned no answerer -- a `--rejudge`, a `--rebuild`, a `--from`. Those copy the source's attempt events verbatim, `cost_usd` included, so the figure is right about the attempts and wrong as this run's spend: one re-judge reported $17.56 of answering that never happened. Null when this run paid, so a total over several run files can skip the copies. |\n| `goldenCheck` | What `verify_goldens.py` said before the run started: `N ok, M drifted, K other finding(s)`, or why it did not run (no truth server on a platform target; `--skip-golden-check`; rebuild). A run that started on a drifted set says so here rather than pretending its verdicts mean something. `run_baseline` calls `verify()` without a model, so the set-name audit (check 5) does not run in-arm; the trailing `N stale entity name(s)` is the in-arm lint's own count, and `entity-name lint not run` says there was no model text to lint against. Without it the field read `0 other finding(s)` for a check that never happened. |\n| `staleEntityNames` | The `expectedEntities` names that appear nowhere in the served model, from the in-arm lint. Each one depresses the run's own recall on every case listing it, so a stale set reads as a retrieval failure until someone checks by hand. `null` when there was no model text to lint against (a platform target), which is a different fact from `[]`. |\n| `status` | `complete`; `aborted` when four consecutive attempts errored or found the server dead and the harness stopped rather than spend the rest of the budget on attempts nobody will trust; or `incomplete` when the arm ran to the end and still cannot report a rate, because `truncated` or `contaminated` is non-empty. `incomplete` is a third state, not a soft `complete`: the arm did everything asked of it and the number is still unearned. It does NOT stop the run being compared: `flip_table.py` scores the cases both arms did, and names the ones this arm left unscored -- an excluded case carries no verdict, so it can never be counted as a flip. |\n| `packageSha` / `servedRevision` *(pins)* | Taken from the server, not recomputed: `sourceContentSha` is a content hash over EVERY model path in the package, so an edit to an imported file moves it where a sha of the one `--model-path` does not; `servedRevision` is minted per load, so it identifies a load rather than content and is a poor pin alone. Measured: `publisher.json`'s `version` moves neither, and nothing in Publisher reads it -- it is not in the Package API schema and never returned, so it pins nothing. |\n| `datasetSha` *(pin)* | Content hash of `set.json` + `cases.jsonl`. Deliberately SEPARATE from the model's sha: a golden repair is not a model change, and one pin covering both would make every answer-key fix read as an edit to the model, which is the distinction an A/B rests on. Automatic, so nobody has to remember it; `datasetVersion` stays beside it as the human-readable sequence. **Local targets only.** A hosted target that publishes IMMUTABLE versions needs none of this: the set rides inside the version, and immutability -- not hashing -- is what makes a pin trustworthy. There, `targetVersion` alone identifies model and set together. |\n| `doubtedGoldens` | The cases whose golden is not believed: `qid`, `gold_status` (`suspect` or `verified_wrong`), `gold_note`, and `declaredBy` (`judge` or `set`). A status the SET declared is a key somebody already settled, not an opinion the judge formed this run, and attributing both to the judge claimed a judgement that never happened. **Read this before diagnose.** These are dataset issues, not model failures, and they go through the golden side door in `skill:eval-loop`. Empty list when no key is in doubt from either source. Written from the same scan that prints the end-of-run warning, because a warning that lives only in console text is one scrollback away from sending a modelling agent at a model that is already right. |\n| `mode` / `setName` / `serverVersion` / `traceMode` / `callBudget` | Defined and accepted, **not yet written by any harness** -- kept in the schema for the platform target and the conductor, which need them. (`targetVersion` and `status` were in this list and are both written now.) |\n\n## Events\n\nEvery line in `events.jsonl` is **flat**: `{ \"kind\": ..., <fields> }`, one\nJSON object per line, with an optional `at` ISO timestamp. Case-scoped kinds\n(`attempt`, `tool_call`, `score`) carry `qid`, `sample`, `phase` on the line;\nrun-level kinds do not. (An earlier draft of this document nested fields under\na `payload` with a `caseId`; no writer ever did that, and 23 run directories\nexist in the flat shape, so the flat shape is the contract.) `kind` is one of:\n`attempt`, `tool_call`, `score`, `retrieval_score`, `issue`, `issue_status`,\n`candidate`, `acceptance_check`, `checkpoint`.\n\n### `attempt`\n\n| Field | Type | Notes |\n|---|---|---|\n| `qid` | string | |\n| `sample` | int or null | Which repeat. Required even when null. |\n| `phase` | string | `baseline` / `loop` / `blind_gate` / `canary` / `final`. `phase` lives here, on the attempt, not in run config. |\n| `question_sha` | string | Hash of the exact text the answerer saw, so two runs can be compared on whether they asked the same thing. A case may carry `questionSha`, the seal stamped at conversion, and that wins when present; the ecommerce set writes a 16-char prefix of it, and a set without one left this null. Neither form proves the question was not edited, since both follow the case as it now reads: that comparison is check 6 of `verify_goldens.py`. |\n| `submitted` | bool | False when there was no final query. Not a wrong answer. |\n| `final_query` | string or null | Required to replay. A named view is recorded as the Malloy it stands for, `run: <source> -> <view>`, so every consumer sees one shape and the query re-executes. |\n| `final_query_source` | string or null | How `final_query` was chosen: `declared` (the answer printed it), `last_ok` (the last call the server answered) or `last`. `last` is a warning: a trailing sanity probe may be standing in for the answer's own query. |\n| `servedRevision` | string or null | From the package actually queried. |\n| `n_get_context` / `n_execute` / `n_execute_errors` | int | |\n| `host_tool_uses` | int | EVERY tool use the host logged, MCP calls included. It counted only the non-MCP ones until 2026-09-03, which made the under-report check below true of almost every clean attempt. |\n| `mcp_tool_uses` | int or null | The MCP subset: `get_context` plus `execute_query`. Null on a run written before the split. |\n| `reported_calls` | int | MCP calls the answerer claimed. `reported_calls > host_tool_uses` is the under-report floor from `skill:eval-answer`: the answerer cannot have made more calls than the host logged. `validate_run` warns on it, and only for runs that carry `mcp_tool_uses`, because the field meant something narrower before. |\n| `contaminated` | bool or `\"unknown\"` | `\"unknown\"` when no host log exists. Read it with `ledger.is_contaminated`, never for truthiness: runs written before 2026-09-03 carry the strings `\"true\"`/`\"false\"`, and `bool(\"false\")` is True. `ledger.event` now rejects those strings on write; `validate_run` grandfathers them on read as a warning. |\n| `contamination_reasons` | list | Empty when clean. |\n| `input_tokens` / `output_tokens` / `cache_read_tokens` / `cache_write_tokens` | int or null | Answerer token usage, the four counts that reprice a run from its own ledger. Null when the host does not report it. `cost_usd` beside them comes from the CLI's `total_cost_usd`, which prices cache reads and writes at their rates, so it was always cache-inclusive; what was missing was the breakdown that reproduces it. `cache_write_tokens` (`cache_creation_input_tokens` upstream) was never captured before 2026-09-15, and on one analysed run cache writes were 44% of the agent's cost, the single largest line. **Read `input_tokens` with care:** it counts only the tokens after the last cache breakpoint. One run recorded 224 for 24 questions beside 2.4M cache reads; the 224 is not the context volume, and a token total that omits the cache columns is not a size. |\n| `cost_usd` | float or null | Answerer cost for this attempt. |\n| `num_turns` / `wall_seconds` | int, float or null | |\n| `answer_text` | string or null | The answer the judge scored. Kept so a verdict can be re-read without the transcript. |\n| `skills_invoked` | list of string | The skills the answerer invoked through the `Skill` tool, deduplicated and sorted, counted from its own transcript. Always a list on a run that recorded it, so an EMPTY list is the finding: the arm granted a manifest and the agent reached for none of it. Absent on runs written before 2026-09-15, which is why every reader takes `or []`. Only explicit `Skill` calls are counted, and only skills the arm granted -- one outside `--answerer-skills` is a contamination breach and lands in `contamination_reasons` instead. What it is for: a manifest names what an arm GRANTED, and comparing two arms' doctrine is meaningless if the doctrine never loaded. |\n| `transcriptPath` | string | The answerer's transcript under `artifacts/`. |\n\nToken counts sit here rather than being derived later because the claim a\nsemantic model makes is about cost as well as correctness -- that a documented\nmodel reaches a good answer in fewer turns and tokens than working from raw\nschema. A ledger that counts calls but not tokens can state half of that.\n\n### `tool_call`\n\nOne event per MCP `get_context` or `execute_query` the attempt made.\n\n| Field | Type | Notes |\n|---|---|---|\n| `tool` | string | `get_context` or `execute_query`. |\n| `traceId` | string or null | `get_context` only; look up in your host's trace store. |\n| `targets` | string, list or null | **What the answerer asked for**: the search terms it sent to `get_context`. Null for `execute_query`. |\n| `rankedSummary` | object | Copied at capture so evidence survives trace eviction: `entityIds` (identity, in response order), `hits` (one row per entity: `entity_id`, `source`, `relevance`, `matched_targets`, `position`, `position_in_source`), `resultCount`, `docTokens`. **There is no rank.** This field previously documented `ranks` and \"per-target `targets` with within-target ranks\"; no writer ever wrote either, and what `ranks` did hold was `range(1, n+1)` over a list already flattened source-card by source-card -- a position, not a rank, and not even a relevance order, since the response sorts globally and then buckets into cards. Ask relevance questions of `hits[].relevance`. |\n| `rankedSummary.hits[].matched_targets` | list or null | Which of the caller's search targets matched this entity, each with the server's own relevance. **`null` means no attribution was published**, which is not the same as `[]`: the server attaches it to entities only (a source card's attribution is discarded before an entity object exists) and only on the semantic path, because a lexical score is relative to its own query and comparing two of them means nothing. A lexical run therefore cannot say which target found what, and a reader must report that as unavailable rather than as \"never asked\". |\n| `retrieval_mode` | string or null | `get_context` only: the `retrieval` field of the response that answered, `semantic` or `lexical`. Null when the server named none, which means no embedding provider. Recorded per call because the semantic path can fall over partway through a run. |\n| `query` | string or null | `execute_query` only: the Malloy the call sent, so the final query can be chosen by which call the server actually answered. |\n| `modelPath` | string or null | `execute_query` only: the model file the call named. A source does not resolve outside the file that declares it, so re-execution needs this. |\n| `error` | string or null | |\n\nNever persist `execute_query` result rows, givens, or credentials.\n\n`targets` records the request; `rankedSummary` records the response. Without\nboth, a low per-attempt recall has two readings that cannot be told apart: the\nanswerer searched for the wrong thing, or it searched well and retrieval ranked\nthe right entity too low. Those have opposite owners -- `agent-skill` and\n`retrieval` -- so a ledger holding only the response cannot attribute the\nfailure, and any recall computed from it is a blend of answerer behaviour and\nretrieval quality.\n\nThat blend is also why per-attempt recall is **not** comparable across arms: a\nstronger answerer searches better and scores higher retrieval recall without\nretrieval having changed. Use it for attribution within an arm. Comparing\nretrieval itself between engine versions is `eval-retrieval`'s job, with fixed\nterms, and is not something a customer run reports.\n\n### `score`\n\nThe answer judge's verdict for one attempt (protocol in\n`skill:eval-judge`). Every attempt in a scored run gets exactly one.\n\n| Field | Type | Notes |\n|---|---|---|\n| `verdict` | string or null | `match` / `near_match` / `no_match` / `needs_human`; null when the attempt is not scorable. Only `match` and `no_match` are decisions; see below. |\n| `reason` | string | Why, from the judge; for a null verdict, why not scorable, and it is ALWAYS one of these: `not_submitted`, `answerer_truncated`, `contaminated`, `judge_unparseable`, `no_saved_verdict`, `judge_error: <text>`, or `golden_<status>` -- `golden_missing`, `golden_provisional`, `golden_invalid`, `golden_ambiguous`, `golden_verified_wrong`. A null verdict never arrives without one: a nulling that does not say which of these it was is indistinguishable from the field being dropped on the write path, and was read as exactly that from a real run. The `golden_*` reasons and `answerer_truncated` are decided before the judge is called, so neither an unestablished key nor a cut-off attempt costs a judge call. |\n| `confidence` | int or null | 1 to 10. Confidence of 5 or lower forces `needs_human`. |\n| `column_pairing` | object or null | The judge's named gold-to-prediction column correspondence. |\n| `judge_version` / `rubric_sha` | string | Pins which rubric produced this verdict. |\n| `golden_revision` | int | From the case at score time. |\n| `contaminated` | bool or `\"unknown\"` | Copied from the attempt; true or unknown means `verdict: null`. |\n| `must_not_use_hits` | list or null | Entries of `golden.mustNotUse` a script found in the final query. A hit forces `verdict: no_match`. Decided by `check_must_not_use.py`, never by the judge: it is a question about query text. Only a BARE name vetoes; an entry with a connective (`X as ...`, `X through ...`) objects to a use of X rather than to X, and goes to the judge with the prose entries and a path's bare leaf. |\n| `judge_verdict` | string or null | What the judge said when a MECHANICAL override replaced it: a `must_not_use_hits` veto, or contamination voiding the verdict. Null otherwise, so the judge's own agreement rate stays measurable across both. When a case is vetoed AND contaminated this still holds the judge's read, not the veto's `no_match`. |\n| `artifactPath` | string | The full judge output under `artifacts/`. |\n| `gold_status` | string | `verified` / `verified_benign` / `suspect` / `verified_wrong`, and never anything else: the case file's `golden.status` is a DIFFERENT vocabulary that shares only `verified` and `verified_wrong`, and only those two fall back into this field. A `provisional` / `invalid` / `ambiguous` key is reported through the verdict's `reason` (`golden_<status>`) instead, so nothing downstream has to match on two vocabularies in one field. **From the judge**, which scored against the golden as written and reports separately whether it believes it; falls back to the case's standing `golden.status` when the judge does not say, written onto the verdict itself so the run summary and the aggregates see it too. `verified_wrong` excludes the case from run aggregates -- from the judge OR from the case file; assigning the fallback into a copy of the verdict meant a key the set had marked wrong stayed in the aggregates unless the judge independently agreed. `suspect` and `verified_wrong` route to the golden side door as `dataset` issues, never to improve. |\n| `gold_note` | string or null | The judge's evidence for a non-`verified` status: the two values, or the model line against the rubric sentence. Null when `verified`. |\n\nA `golden_*` reason means the ANSWER KEY is not something a verdict can be\nissued against. A golden the set stamps `provisional`, `invalid` or `ambiguous`\nis refused, as is a case with no golden at all and one the set marks\n`verified_wrong`; a golden with NO `status` is unguarded rather than\nunscorable, because sets that predate the field would otherwise score zero of\nzero. A golden holding no value is not refused either: that is how a\n`kind: unanswerable` case and a `kind: criteria` golden are written. This\nmatters most for an imported set, because `skill:eval-import` stamps\n`provisional` on every golden it writes and enforces it -- so a set is\nunscorable by construction until its keys are re-derived, and `run_baseline`\nrefuses to spend at all when every case in a set is in that state.\n\n`not_submitted` means the attempt produced NOTHING to judge: no answer text and\nno query. An attempt that wrote prose without querying **is judged**, and\nagainst a golden that holds a value an answer containing none of it is\n`no_match` (`skill:eval-judge`, `reference/refusal.md` rule 10). Excusing those\nas unscorable dropped a confident refusal on an answerable case out of the pass\nrate, which is the one thing the answerable-sounds-unanswerable cases exist to\nmeasure. A refusal is exempt only where `golden.kind` is `unanswerable`, and\nthere naming the gap is the pass and a confident number is the fail.\n\n`answerer_truncated` means the answerer hit the run's `maxTurns` cap and the\nCLI returned whatever it had, which is usually a sentence stopping mid-thought.\nIt is refused BEFORE the golden gate and before a saved verdict is reused, so\n`--rebuild` over a run made without this re-derives the right ledger from its\ntranscripts. A cap is a harness setting, so a case cut off by one says nothing\nabout whether the model could answer it: measured on one 29-case arm, four\nattempts ended at exactly 31 turns and each was judged as a wrong answer, one\nof them on the text \"Let me build the correct monthly trend query.\"\n\n`contaminated` means the attempt breached isolation (`contamination_reasons`\nnames how) and the verdict is withheld rather than lost. The judge's own read\nmoves to `judge_verdict`. Before this reason was written, a voided verdict kept\nthe judge's prose in `reason` beside `verdict: null`, and a run report\nreasonably concluded the ledger was dropping the field -- it recovered nine\n\"lost\" verdicts by re-parsing the stored judge replies, every one of which had\nbeen voided on purpose.\n\nBoth are HARNESS-owned, not model-owned, and a run containing either reports\n`status: incomplete` in `run.json` and **prints no pass rate**. `unscorable`\n(no established golden) and `judge_unparseable` do not suppress the rate: the\nfirst is a dataset state no arm can fix, and the second already has a retry.\n\nAggregates count decided verdicts only. `match` and `no_match` are the pass and\nthe fail; **`near_match`, `needs_human` and null are none of the above** and stay\nout of acceptance arithmetic. `near_match` is excluded because it means \"defensibly\ndifferent\", and an arguable verdict that moves a pass rate is a measurement\nartefact rather than a result (`skill:eval-judge` rule 7). Report its count:\nit rising is how a set tells you its rubrics are going vague.\n\nThis applies to `score`. On `retrieval_score` below, `near_match` **is** counted\ntowards recall and precision, because an overlapping entity is a genuine\nretrieval success. The two are different questions that share a word.\n\n### `retrieval_score` (written by `eval-retrieval`, not by a customer run)\n\nOne per term judged in a fixed-term replay (run-level; no `caseId`).\n\n| Field | Type | Notes |\n|---|---|---|\n| `intentId` / `term` / `entityType` | string | From the term file. |\n| `in_scope` | bool | Does THIS model version represent the concept? False is a coverage gap, not a retrieval failure. |\n| `judgments` | list | Per returned entity: `entityId`, `rank`, `level` (`match` / `near_match` / `no_match`), `confidence`, `why`. Empty when nothing returned. |\n| `judge_version` / `rubric_sha` | string | |\n| `traceId` | string or null | The `get_context` call judged. |\n\nRun-level metrics fall out by counting:\n\n- `coverage` = in-scope terms / valid terms -- a property of the model and its\n  data, reported on its own, never as a retrieval number.\n- `recall` (on in-scope terms) = fraction whose judgments contain a `match`.\n- `precision@N` = `match` judgments / judged, with N stated.\n\n### `issue`\n\n| Field | Type | Notes |\n|---|---|---|\n| `issue_id` | string | Stable across status events. |\n| `qids` | list | Affected cases. |\n| `primary_code` / `contributing_codes` | string / list | From `skill:eval-diagnose`, verbatim. An event written before the codes were renamed may carry a retired one: `COVERAGE` is now `MISSING`, `NO-DISAMBIG` is `AMBIGUOUS`, and `CONVENTION` is `RULE_UNWRITTEN`. Read those as the new name; nothing rewrites old events. |\n| `component` | string | `dataset` / `agent-call` / `get_context/model` / `get_context/retrieval` / `construction` / `model-definition`. |\n| `owner` | string | `model` / `retrieval` / `agent-skill` / `dataset`. Environment failures stop the run; they are never diagnosed, so there is no environment owner. |\n| `severity` / `confidence` | string | |\n| `sufficiency` | string | `sufficient` / `insufficient` / `unknown`. |\n| `traceIds` | list | |\n| `diagnosis` | string | Written before any edit exists. |\n\n### `issue_status`\n\n`issue_id` plus `status`: `open` / `batched` / `fixed` / `rejected` /\n`deferred`. Readers take the latest event for that `issue_id`. Do not invent\na status column.\n\n### `candidate`\n\nWritten by `eval-improve`, for every proposed edit, accepted or not. A\nrejected direction keeps its record.\n\n| Field | Notes |\n|---|---|\n| `issue_ids` | |\n| `files` | Paths the edit touched. |\n| `diffSummary` | One line per file. |\n| `probes` | Query and result for each factual claim. |\n| `meaningChanged` | Entities whose *meaning* the edit changed; `[]` for a docs-only edit. |\n| `goldenSuspect` | Each `{qid, entity, stored, rederived}`: a golden this edit may have invalidated. Reported by the improver, never repaired by it. **Non-empty halts the acceptance check** until adjudicated through the golden side door. |\n| `goldenAudit` | The set's `verify_goldens.py` run against the edited model: `{ran, clean, model, tail}`. Catches drift and rubric-vs-model contradictions only; a golden whose value silently moved is invisible to it, which is why `goldenSuspect` exists alongside. |\n\n### `acceptance_check`\n\nCalled `gate` before 2026-09-03. `ledger.py` reads the old kind as this one, so\nrun directories written earlier still validate and nothing rewrites them.\n\nWritten by `eval-loop`, one per acceptance check decision, BEFORE any checkpoint commit.\n\n| Field | Notes |\n|---|---|\n| `issue_ids` | |\n| `decision` | `accepted` / `rejected`. |\n| `class` | `docs` / `definition` / `retrieval` / `justified`. |\n| `baselineRunId` / `finalRunIds` | Plural: acceptance needs two independent runs. |\n| `regressions` | Case ids whose verdict got worse vs baseline. Must be empty to accept. |\n| `holdoutDelta` | Confident-verdict delta on the holdout slice. |\n| `reason` | Including independent deterministic justification when that is the basis. |\n\n### `checkpoint`\n\nWritten by `eval-loop` after an accepted acceptance check, or when a restore runs. The\nmodel bytes live in git, not in this payload.\n\n| Field | Notes |\n|---|---|\n| `action` | `created` / `restored`. |\n| `label` | |\n| `modelGitSha` | The commit this checkpoint names (create), or the commit restored to. |\n| `issueIds` | Issues the accepted edit closed. Empty on restore. |\n\n## `judge-regressions.jsonl`\n\nAppend a line whenever a human overrules a judge verdict: the case or intent,\nthe judge's verdict, the human's, and why. Re-run this file against the judge\nwhenever `skill:eval-judge` or the judge model changes; a rubric change that\nflips old human-settled verdicts is a judge regression, not new truth."
     },
     {
       name: "eval-diagnose",
@@ -319575,7 +321697,7 @@ Prior \`score\` events are not rewritten. They keep the old \`golden_revision\`.
 | \`NEVER-ASKED\` | no utterance targeted a needed concept | agent-skill, and model if nothing would have prompted the ask |
 | \`VAGUE\` | compound or generic utterances, so nothing could rank | agent-skill |
 | \`QUESTION-VOCAB\` | utterances parroted the question where the data uses other words | agent-skill, and model if that vocabulary is undocumented |
-| \`NO-DISAMBIG\` | two plausible candidates, never resolved | model: docs should answer, not require the question |
+| \`RULE_UNWRITTEN\` | the data is present and the model does not encode the rule for combining or filtering it, so whoever answers invents one. Qualified \`(guessable)\` when the data forces the rule -- list price minus sale price -- and \`(arbitrary)\` when it is a business decision nobody could derive, such as a season window or whether revenue is net of tax. Only the stated conventions tell those apart: from the model alone the two look identical, and an unqualified reading defaults to the harmless one | model: write the rule down |
 | \`ASSUMED\` | assumed a scope or convention instead of checking | model if nothing warned; agent-skill otherwise |
 | \`WRONG-TYPE-OR-SCOPE\` | asked, but with the wrong target type or an empty/wrong scope | agent-skill |
 
@@ -319585,10 +321707,10 @@ If the agent could not reasonably have known to ask, that is a model gap.
 
 | Code | When | Owner |
 |---|---|---|
-| \`COVERAGE\` | no representing entity anywhere | model |
+| \`MISSING\` | no query over this model could produce the concept. Not merely "no named measure": if the parts are present and only the formula is absent, that is \`RULE_UNWRITTEN\` | model: add an entity, a dimension value, or a data source |
 | \`NOT-RETURNED\` | it exists, the ask was on target, it never came back | model: labels, docs, synonyms, index |
 | \`LOW-RANK\` | returned, buried under noise the agent reasonably skipped | model |
-| \`AMBIGUOUS\` | several near-identical candidates | model: "use X for …, Y when …" |
+| \`AMBIGUOUS\` | several candidates and nothing says which this question means. Judged over the entities AND their docs: a \`#(doc)\` that resolves the choice makes it \`MODELLED\`, which is why a sentence of documentation is usually the whole fix | model: "use X for …, Y when …" |
 | \`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 |
 
@@ -319629,7 +321751,7 @@ with both queries. Otherwise it is still \`NOT-RETURNED\` / \`LOW-RANK\`.
 | \`SCOPE\` | right entities, wrong population | model if the scope rule was undocumented |
 | \`GRAIN\` | right entities, wrong grain | model or agent-skill |
 | \`FILTER-LITERAL\` | filter literal did not match stored values | model (document the stored form) and agent-skill |
-| \`CONVENTION\` | right data, wrong statistical or business convention | model: expose a named measure |
+| \`UNDERSPECIFIED\` | the QUESTION is unclear, not the model -- "adjusted sales" that never says what the adjustment is, or a business that has not decided whether revenue includes tax | the asker, or whoever owns the definition. Never scored against the model |
 | \`SYNTAX\` | could not express it; execute errors; never submitted | agent-skill |
 
 ### model-definition
@@ -319720,7 +321842,7 @@ the case, and one issue event covers all of its cases rather than one per case.
 **Group on shared cause, not shared symptom.** Two cases that both returned a
 wrong revenue number belong together only if the same entity, doc gap, or
 convention explains both. Same \`owner\` and same \`component\` is a hint, never a
-criterion: two \`COVERAGE\` issues about different missing entities are two
+criterion: two \`MISSING\` issues about different missing entities are two
 clusters, and merging them produces an edit that fixes neither cleanly.
 
 Order clusters by how many cases they would fix. Cluster the non-model owners
@@ -320314,6 +322436,24 @@ usually absent at import, and until it exists no golden can reach \`verified\`;
 \`verify_goldens.py --promote\` is what takes it there afterwards. \`init_truth_package.py\` in
 \`skill:eval-answer\` scaffolds one.
 
+\`conventions\` is optional: a list of strings, each defining one term the way
+the business uses it, for a term the question does not define itself. The
+coverage check (\`check_coverage.py\` in \`skill:eval-answer\`) shows them to its
+judge as definitions it may not replace with its own reading. End each one with
+the questions it governs, as an "Applies to questions that ..." sentence:
+
+\`\`\`json
+"conventions": [
+  "\\"Summer\\" means 25 May to 15 September inclusive. Applies to questions that ask about summer."
+]
+\`\`\`
+
+The scope sentence is what stops the judge applying a definition to every
+question. Without it, one set came back with nine of twelve cases as gaps, and
+the check warns about any convention that has none. Record only a definition
+someone gave you. A convention you invent turns your guess into the business's
+rule, and scores the model against it.
+
 ## Their field names will not be your field names
 
 An arriving JSONL is somebody else's schema. Map it explicitly rather than
@@ -322934,9 +325074,9 @@ Two things stop it:
 
 **Label a rung for what it measures, not for what a reader will assume.**
 "Can the model express an answer?" is wrong for most of what lands on the \`no\`
-side of the first rung. \`CONVENTION\` means the data is present and no named
-measure encodes the statistical or business convention; \`NO-DISAMBIG\` means two
-plausible candidates and no doc saying which the question means. The model can
+side of the first rung. \`RULE_UNWRITTEN\` means the data is present and the
+model does not encode the rule for combining or filtering it; \`AMBIGUOUS\` means
+several candidates and no doc saying which the question means. The model can
 express an answer in both -- it does not say WHICH answer is meant. So the rung
 asks whether the model NAMES what the question needs.
 
@@ -323590,17 +325730,14 @@ 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.
+   \`get_context\` if you have it, otherwise the REST model endpoint for \`index.malloy\` (it answers
+   404 for a file off the surface) or the \`.malloy\` files.
    Never guess a name. A guessed field in a query fails the whole package load, not just that one
    dashboard; a guessed tile or suggest source is quieter, and only shows up in the package warnings.
+   If the package root holds an \`index.malloy\` (every scaffolded package does), a tile reads only the
+   sources that file exports. A source the dashboard file declares on top of an exported one works;
+   one on top of a hidden source does not. See "Read the lint" for the warning you get otherwise.
 2. **PICK THE VIEWS TO SHOW.** A dashboard is \`## artifact { tiles=[…] }\` naming existing views, so
    this is the design step: which views, how wide each sits, what each is called. There is one form,
    so there is no form to choose.
@@ -324010,8 +326147,7 @@ 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 the package's surface also loses its own findings, so a
-short list for a withheld file is not a clean bill of health.
+incomplete"**.
 
 **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
@@ -324024,24 +326160,23 @@ failed, and the entry clears on the next reload that compiles. That is the one c
 the fact, so make it the first thing you run when a page will not change. A package that never loaded
 at all appears there too, without \`stale\`, and is absent from the listing entirely.
 
-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 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.
+If the reload is 200 and the others are listed but yours is not, discovery skipped the file,
+usually a missing or misspelled \`# artifact\` tag. That is the same mechanism that deliberately skips
+an untagged shared include, and it is also how you hide a dashboard on purpose: drop its tag. The
+package surface never hides a dashboard. Every tagged dashboard is listed and served.
+
+**A tile over a hidden source answers 404.** When the package has an \`index.malloy\`, tiles, a
+single-query dashboard's query, and filter \`suggest\` lists read only the sources it exports. The
+dashboard file admits nothing of its own, so importing a source into it is not enough. The package
+load warns once per tile that will fail, for example:
+
+\`\`\`
+Tile orders_staging -> by_flag on dashboard overview reads orders_staging, which index.malloy doesn't export, so it won't load. Fix: add orders_staging to the export { ... } in index.malloy.
+\`\`\`
+
+The fix is the one the warning names: add the source to the \`export { ... }\` in \`index.malloy\`. A
+\`suggest\` over a hidden source gets the same warning, ending "so its list will be empty". Do not
+add an \`explores\` to \`publisher.json\` to serve a dashboard; it is deprecated and no longer needed.
 
 **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
@@ -325727,12 +327862,11 @@ For date-range filters, declare two filters with distinct \`name\` values target
 
 ### When to use \`required\`
 
-\`required\` filters are a correctness, latency, and governance mechanism, not just UX. Mark a filter \`required\` when:
+\`required\` filters are a correctness and latency mechanism, not just UX. Mark a filter \`required\` when:
 
 1. **Modeling correctness, the source's \`primary_key:\` is only unique under a filter.** If a high-cardinality key is not unique across the whole table but is unique within a scoping dimension, then that scoping dimension MUST be supplied for symmetric aggregation to produce correct numbers. For example, if \`events.id\` repeats across days but is unique within a single \`event_date\`, queries that don't pin the date can fan out and return hash-collision-sized garbage (~10²¹). Declare \`#(filter) name=Event_Date dimension=event_date type=equal required\` so the server refuses queries that don't provide it.
 2. **Query latency, the source spans more data than any single query should scan.** A multi-year, multi-region table where every reasonable analysis is scoped to a date range or region: making the date filter required prevents accidental full-table scans.
 3. **Partial views** that are only meaningful inside a date range, region, or business segment.
-4. **Governance**, an analyst should never query the raw source without a scoping filter applied.
 
 For (1), pair the required filter with a comment explaining the cardinality dependency, and consider also declaring \`#(doc)\` on the source noting the constraint.
 
@@ -325746,7 +327880,7 @@ Publisher formats values based on the dimension's data type, \`string\` → \`'v
 
 ### Bypass
 
-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.
+Pass \`bypass_filters=true\` (REST) or \`bypassFilters: true\` (POST body) to skip filter injection entirely. \`#(filter)\` is not a security boundary against caller-authored query text or \`bypassFilters\`; use givens + \`#(authorize)\`.
 
 ## Access Control: \`#(authorize)\` and \`#(access_filter)\`
 
@@ -326466,7 +328600,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)`/`#(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."
+      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**When the package root holds an `index.malloy`, cells read only what it exports.** A cell over a source `index.malloy` does not export answers 404, even when the notebook imports that source's file. A source an earlier cell derives from an exported one (`source: mine is customers extend { ... }`) still works. A cell's own source over a raw table (`duckdb.table(...)`) is refused. To use a source in a notebook, add it to the `export { ... }` in `index.malloy`. A package with no `index.malloy` and no legacy `explores` has no such limit.\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",
@@ -326541,7 +328675,7 @@ 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.
+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. Where nothing in the model is gated, the 404 says the source is off the surface and how to publish it; where a gate is in play, it reads exactly like 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.
 
@@ -326555,19 +328689,20 @@ What it exports is what agents discover **and** what may be queried. Everything
 
 ### 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.
+\`publisher.json\` has two older keys for this, \`explores\` and \`queryableSources\`. A new package uses neither: \`index.malloy\` does the job.
 
-\`\`\`json
-{
-  "name": "ecommerce",
-  "explores": ["order_analysis.malloy", "customer_health.malloy"],
-  "queryableSources": "all"
-}
-\`\`\`
+- **\`explores\`** (\`string[]\`) is deprecated in every form. The files it lists are listed and queryable, and what they export is the surface, wherever they live. The one exception is a tagged dashboard it lists, which reads the surface and adds nothing to it. A package that sets it gets a load-time warning naming the edit that replaces it. A surface spanning several files needs no \`explores\`: import them all into one \`index.malloy\` and export what you publish.
 
-- **\`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.
+  \`\`\`malloy
+  // index.malloy
+  import "order_analysis.malloy"
+  import "customer_health.malloy"
 
+  export { orders, customers, customer_health }
+  \`\`\`
+
+  \`"explores": []\` is deprecated too. It used to mean "do not curate". To publish everything now, rename or remove \`index.malloy\`, and point any file that imports it at the new name first: a broken import fails the whole package. An entry that doesn't resolve to a real \`.malloy\` file surfaces in \`exploresWarnings\`, and publishing a package that has any is rejected. When \`explores\` is set and does not list \`index.malloy\`, the index file is ignored, and a warning says so.
+- **\`queryableSources\`** (\`"declared"\` | \`"all"\`) is deprecated too. \`"declared"\` is the default, so setting it does nothing and draws a warning. **\`"all"\` has one use:** hiding an \`#(authorize)\`-gated source from listings while authorized callers still query it by name. It keeps the listings \`index.malloy\` curates and leaves every source queryable by name. It needs no \`explores\` beside it and draws no warning. Leave it out unless you have that case.
 
 > **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.
 
@@ -327576,70 +329711,7 @@ Scope confirmed, in the conversation and in \`modeling-notes.md\`: tables in sco
     {
       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.`
+      body: '# A source you cannot reach\n\n> **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.\n\nMost 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.\n\n## The three answers\n\n| what you got | what it means | what to do |\n| --- | --- | --- |\n| **404** that says "not on this package\'s published surface" | the name is real and the package does not publish it. It is curation, not a typo | follow the fix the message names (usually: name it in the `export { ... }` of `index.malloy` and address the query there), or query what IS published |\n| **404**, plain "No queryable source", "No queryable model" or "Query target is not queryable" | the name does not exist, or it is hidden in a model that carries an `#(authorize)` or `#(access_filter)` gate. In a gated model the two are deliberately indistinguishable, so a refusal cannot be used to probe for hidden names | check the name against `get_context`, then query something on the surface or ask the package\'s author to publish it |\n| **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 |\n| **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 |\n\nA 403 names a source, so it tells you the source exists. A plain 404 tells you nothing at all. That asymmetry is deliberate: a source that is both hidden AND gated answers a plain **404**, so you can never use a 403, or the wording of a 404, to discover that a hidden gated name is real.\n\n## Addressing the surface, which is the most common 404\n\nA 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**:\n\n```\nPOST .../packages/sales/models/index.malloy/query    {"sourceName": "orders"}   -> 200\nPOST .../packages/sales/models/orders.malloy/query   {"sourceName": "orders"}   -> 404\n```\n\nSame source, same package. `orders.malloy` is off the surface, so it is not an entry point.\n\n**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.\n\n## Other places a hidden source answers 404\n\nThe query route is not the only one held to the surface. On a curated package, a source or file off it also shows up as a 404 here:\n\n- **Reading a model.** `GET .../models/{path}` answers 404 for a file off the surface, with the same words as the query route. The file still exists and still compiles; read `index.malloy` instead. A model that is on the surface lists only the names it publishes, not everything it imports.\n- **A dashboard tile.** A tile, a single-query dashboard\'s query, or a filter `suggest` over a hidden source answers 404. The dashboard itself is still listed. The package load warns once per tile, for example `Tile orders_staging -> by_flag on dashboard overview reads orders_staging, which index.malloy doesn\'t export, so it won\'t load. Fix: add orders_staging to the export { ... } in index.malloy.` It is in the `warnings` on the package\'s own response, `GET .../packages/{pkg}`.\n- **A notebook cell.** A cell over a hidden source answers 404, even when the notebook imports its file. A source an earlier cell derives from a published one still works.\n\nThe fix is the same in each case: add the source to the `export { ... }` in `index.malloy`, or use what is already published.\n\n## When the source is not in `get_context` at all\n\nWork down this list. The first three are far more common than the last.\n\n1. **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.\n2. **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.\n3. **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.\n4. **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.\n\n## What curation does not do\n\n- **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.\n- **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.\n- **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.\n\n## Reaching an unpublished source from your own model\n\nIf you are writing Malloy rather than just querying, an unpublished source is still usable, with one condition that trips people.\n\n`export { ... }` decides what an **importing file** can see, which is Malloy\'s rule and not Publisher\'s:\n\n- a file that declares **no** `export` hands an importer everything it declares, so import the file that declares the source and join it normally;\n- 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`.\n\nSo 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.\n\n## Before you report a source as missing\n\nConfirm all three, in this order. Each one has been mistaken for "the data is not there".\n\n1. `get_status` shows the package loaded and not `stale`.\n2. `list_packages` names the environment and package you meant.\n3. An enumerating `get_context` call (a target with no `search_text`) does not list it.\n\nOnly 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.'
     }
   ]
 };