@malloy-publisher/server 0.6.0 → 0.8.0

package/dist/server.mjs

@@ -175849,7 +175849,7 @@ import os from "os";
 function normalizeModelPath(p) {
   return p.replace(/\\/g, "/").replace(/^\.\//, "");
 }
-var API_PREFIX = "/api/v0", README_NAME = "README.md", PUBLISHER_CONFIG_NAME = "publisher.config.json", PACKAGE_MANIFEST_NAME = "publisher.json", MODEL_FILE_SUFFIX = ".malloy", NOTEBOOK_FILE_SUFFIX = ".malloynb", DEFAULT_QUERY_ROW_LIMIT = 1000, DEFAULT_MAX_QUERY_ROWS = 1e5, DEFAULT_MAX_RESPONSE_BYTES = 50000000, DEFAULT_QUERY_TIMEOUT_MS = 300000, DEFAULT_MAX_CONCURRENT_QUERIES = 32, TEMP_DIR_PATH, PUBLISHER_DATA_DIR = "publisher_data";
+var API_PREFIX = "/api/v0", README_NAME = "README.md", PUBLISHER_CONFIG_NAME = "publisher.config.json", PACKAGE_MANIFEST_NAME = "publisher.json", MODEL_FILE_SUFFIX = ".malloy", NOTEBOOK_FILE_SUFFIX = ".malloynb", INDEX_MODEL_NAME = "index.malloy", DEFAULT_QUERY_ROW_LIMIT = 1000, DEFAULT_MAX_QUERY_ROWS = 1e5, DEFAULT_MAX_RESPONSE_BYTES = 50000000, DEFAULT_QUERY_TIMEOUT_MS = 300000, DEFAULT_MAX_CONCURRENT_QUERIES = 32, TEMP_DIR_PATH, PUBLISHER_DATA_DIR = "publisher_data";
 var init_constants = __esm(() => {
   TEMP_DIR_PATH = os.tmpdir();
 });
@@ -233150,7 +233150,7 @@ var require_utils92 = __commonJS((exports, module) => {
 
 // ../../node_modules/ssh2/lib/protocol/crypto/build/Release/sshcrypto.node
 var require_sshcrypto = __commonJS((exports, module) => {
-  module.exports = __require("./sshcrypto-xqan60jb.node");
+  module.exports = __require("./sshcrypto-cqb52edz.node");
 });
 
 // ../../node_modules/ssh2/lib/protocol/crypto/poly1305.js
@@ -270853,10 +270853,10 @@ function recordMaterializationRun(mode, outcome, durationMs) {
   runCounter().add(1, { mode, outcome });
   runDuration().record(durationMs, { mode });
 }
-function recordSourcesOutcome(outcome, count) {
+function recordSourcesOutcome(outcome, count, mode) {
   if (count <= 0)
     return;
-  sourcesCounter().add(count, { outcome });
+  sourcesCounter().add(count, { outcome, mode });
 }
 function recordIncrementalStep(step, reason) {
   incrementalStepCounter().add(1, reason ? { step, reason } : { step });
@@ -270930,7 +270930,7 @@ var init_materialization_metrics = __esm(() => {
   resetHooks3 = [];
   runCounter = lazyCounter3("publisher_materialization_runs_total", "Materialization builds completed. Labels: mode ('auto'|'orchestrated'), outcome ('success'|'partial'|'failed'|'cancelled').");
   runDuration = lazyHistogram2("publisher_materialization_run_duration_ms", "Wall-clock duration of a materialization build. Label: mode ('auto'|'orchestrated').", "ms");
-  sourcesCounter = lazyCounter3("publisher_materialization_sources_total", "Persist sources processed by a materialization run. Label: outcome ('built'|'reused'|'failed').");
+  sourcesCounter = lazyCounter3("publisher_materialization_sources_total", "Persist sources processed by a materialization run. Labels: outcome ('built'|'reused'|'failed'|'refused'), mode ('auto'|'orchestrated').");
   incrementalStepCounter = lazyCounter3("publisher_materialization_incremental_step_total", 'Refreshes of a source declared refresh="incremental". Labels: step ' + "('delta'|'seed'|'skip'), and for seed/skip a bounded reason code " + "(IncrementalStepReasonCode). A 'seed' is a full rebuild the delta path " + "declined, so a rising seed rate means the feature is not engaging — and " + "the reason label says why without a log dive.");
   buildPlanComputeDuration = lazyHistogram2("publisher_materialization_build_plan_compute_duration_ms", "Wall-clock duration of compiling a package's build plan (Package.buildPlan).", "ms");
   buildPlanComputeFailedCounter = lazyCounter3("publisher_materialization_build_plan_compute_failed_total", "Package loads whose build plan failed to compute. The ROOT-CAUSE signal for " + "colocated_bind_dropped{reason='build_plan_unavailable'}, which fires only " + "per dropped entry per load -- a package that loads once and is never " + "reloaded ticks that counter once and then sits with its colocated tier " + "off and a flat total, indistinguishable from healthy.");
@@ -270949,7 +270949,7 @@ var init_materialization_metrics = __esm(() => {
   storageBuildFailureCounter = lazyCounter3("publisher_storage_build_failures_total", "storage= build failures (federation/passthrough/attach/CTAS), distinct from " + "in-warehouse build failures. Labels: destination (connection name), " + "reason ('build_failed'|'billed_read_not_captured'). The second is the " + "expensive one: the warehouse read ran and was charged, and the rows could " + "not be captured — so a re-drive pays for it again. Worth alerting on " + "separately from a failure that costs only a retry.");
   attributionSkippedCounter = lazyCounter3("publisher_storage_build_attribution_skipped_total", "storage= builds whose warehouse read went out UNATTRIBUTED while tagging was " + "on. Label: reason ('job_listing_unavailable'|'tag_failed'|" + "'read_row_not_found'|'read_row_ambiguous'|'cost_query_failed'). " + "The read still ran and the " + "build still succeeded — what was lost is the label in the customer's own " + "query history, and the cost on this side. Without this an operator who " + "turns tagging on and sees nothing has a single log line to go on.");
   eligibilityRefusedCounter = lazyCounter3("publisher_materialization_eligibility_refused_total", "materialization-eligibility refusals, both tiers. Label: reason " + "('free_parameter'|'given_in_persisted_query'|'dynamic_projection'|" + "'dynamic_join'|'dynamic_joined_where'|'partition_without_storage'|" + "'partition_column_unknown'|'partition_column_not_public'|" + "'merge_key_scope_unresolved'|'preaggregate_over_dynamic_source'|" + "'authorize'|'partition'|'not_duckdb_portable'|" + "'public_surface_unknown'). 'given' is retained on the enum for records " + "that carry it and is no longer produced: where a given sits decides the " + "outcome, so one reason covering every placement cannot be raised.");
-  serveShapeTierDropCounter = lazyCounter3("publisher_storage_serve_shape_tier_drop_total", "storage serve-shape compile escalations: a refinement tier failed to " + "compile and the riskiest category was dropped. Label: tier (the failed " + "tier index, 0=full).");
+  serveShapeTierDropCounter = lazyCounter3("publisher_storage_serve_shape_tier_drop_total", "storage serve-shape compile escalations: a refinement tier failed to " + "compile and the riskiest category was dropped, or one or more lifted " + "entry points failed to compile and were dropped alone. Label: tier (the " + "failed tier index, 0=full; 'lifts' for dropped lifts).");
   serveShapeTypeFallbackCounter = lazyCounter3("publisher_storage_serve_shape_type_fallback_total", "Captured DuckDB column types mapped to json in the serve shape (type " + "fidelity loss). Label: kind ('array'|'unrecognized').");
   chainedStorageBuildCounter = lazyCounter3("publisher_storage_chained_build_total", "Chained storage= source builds (a source reading a storage-materialized " + "upstream). Label: outcome ('parent_reuse'|'inline_fallback'|" + "'strict_refused'). The parent_reuse share is the headline signal for how " + "far the stack-on-the-parent path gets us vs recompute-from-raw.");
   colocatedBindDroppedCounter = lazyCounter3("publisher_materialization_colocated_bind_dropped_total", "Colocated serve-manifest entries dropped by bindColocatedServeManifest. " + "Label: reason ('build_plan_unavailable' when the package's build plan " + "failed to compute, so no source was examined at all; 'refused' when the " + "source itself was examined and found ineligible). 'build_plan_unavailable' " + "is a whole-package regression -- colocated is the default tier and is NOT " + "gated by PERSIST_STORAGE_MODE, so every colocated binding for the package " + "reverts to live recompute until a load succeeds.");
@@ -271455,6 +271455,291 @@ var init_preaggregation_serve_bindings = __esm(() => {
   init_preaggregation_synthesis();
 });
 
+// src/service/persist_dynamic_terms.ts
+import { Annotations as Annotations4 } from "@malloydata/malloy";
+function givenNames(node) {
+  const names = new Set;
+  collectGivenRefs(node, names);
+  return [...names];
+}
+function readsAGiven(node, seen, depth = 0) {
+  if (depth > MAX_WALK_DEPTH) {
+    throw new Error("given walk exceeded max depth");
+  }
+  if (node === null || typeof node !== "object")
+    return false;
+  if (seen.has(node))
+    return false;
+  seen.add(node);
+  if (Array.isArray(node)) {
+    return node.some((item) => readsAGiven(item, seen, depth + 1));
+  }
+  const record = node;
+  if (record.node === "given" || record.node === "givenReference")
+    return true;
+  if (record.givenRef !== undefined)
+    return true;
+  const summary = record.refSummary;
+  if (summary?.givenUsage && summary.givenUsage.length > 0)
+    return true;
+  if (Array.isArray(record.givenUsage) && record.givenUsage.length > 0) {
+    return true;
+  }
+  return Object.values(record).some((v) => readsAGiven(v, seen, depth + 1));
+}
+function buildSubstitutesAGiven(persistSource) {
+  let def;
+  try {
+    def = persistSource._sourceDef;
+  } catch {
+    return true;
+  }
+  return defSubstitutesAGiven(def);
+}
+function defSubstitutesAGiven(def) {
+  try {
+    if (def === null || typeof def !== "object") {
+      throw new Error("compiled source definition is not readable");
+    }
+    const query = def.query;
+    if (query !== null && typeof query === "object") {
+      const usage = query.givenUsage;
+      if (Array.isArray(usage) && usage.length > 0)
+        return true;
+      if (argumentBindsAGiven(query))
+        return true;
+      if (Array.isArray(usage))
+        return false;
+    }
+    const {
+      filterList: _readTimeFilters,
+      fields: _readTimeFields,
+      ...relation
+    } = def;
+    return readsAGiven(relation, new WeakSet);
+  } catch {
+    return true;
+  }
+}
+function argumentBindsAGiven(node, depth = 0) {
+  if (depth > MAX_WALK_DEPTH) {
+    throw new Error("argument walk exceeded max depth");
+  }
+  if (node === null || typeof node !== "object")
+    return false;
+  if (Array.isArray(node)) {
+    return node.some((item) => argumentBindsAGiven(item, depth + 1));
+  }
+  for (const [key, value] of Object.entries(node)) {
+    if ((key === "arguments" || key === "sourceArguments") && readsAGiven(value, new WeakSet)) {
+      return true;
+    }
+    if (argumentBindsAGiven(value, depth + 1))
+      return true;
+  }
+  return false;
+}
+function classifyDynamicTerms(persistSource) {
+  let def;
+  try {
+    def = persistSource._sourceDef;
+  } catch (err) {
+    return unreadable(err, "which givens the build would bake in");
+  }
+  return classifyDef(def, 0);
+}
+function classifyDef(def, depth) {
+  if (defSubstitutesAGiven(def)) {
+    return {
+      ok: false,
+      reason: "given_in_persisted_query",
+      detail: `a given is read while the persisted relation is BUILT, so its ` + `value is substituted at build time — from the declaration's ` + `default, the only value available then — and every caller is ` + `served that one slice. Move the given out of the persisted query ` + `and into the source's extend block (\`where: …\`), where it is ` + `left out of the build and applied per caller when the artifact ` + `is read`
+    };
+  }
+  if (def === null || typeof def !== "object") {
+    return unreadable(new Error("compiled source definition is not readable"), "which givens the build would bake in");
+  }
+  const record = def;
+  try {
+    const joinedTerms = [];
+    const fieldRefusal = classifyFields(record.fields, joinedTerms, depth);
+    if (fieldRefusal)
+      return fieldRefusal;
+    const terms = collectDynamicTerms(record.filterList);
+    const {
+      filterList: _accounted,
+      fields: _alsoAccounted,
+      query: _cleared,
+      ...rest
+    } = record;
+    if (readsAGiven(rest, new WeakSet)) {
+      return {
+        ok: false,
+        reason: "given_in_persisted_query",
+        detail: `a given sits in a part of the source this pass cannot place ` + `— it is neither an extend-block \`where:\` nor a field ` + `declared on the source — so the publisher cannot prove the ` + `build leaves it out`
+      };
+    }
+    return joinedTerms.length > 0 ? { ok: true, terms, joinedTerms } : { ok: true, terms };
+  } catch (err) {
+    return unreadable(err, "the build leaves every given out");
+  }
+}
+function unreadable(err, cannotProve) {
+  return {
+    ok: false,
+    reason: "given_in_persisted_query",
+    detail: `its given usage could not be determined ` + `(${err instanceof Error ? err.message : String(err)}), so the ` + `publisher cannot prove ${cannotProve}`
+  };
+}
+function classifyFields(fields, joinedTerms, depth) {
+  if (!Array.isArray(fields))
+    return;
+  for (const field of fields) {
+    if (field === null || typeof field !== "object")
+      continue;
+    const f = field;
+    const label = typeof f.as === "string" ? f.as : typeof f.name === "string" ? f.name : "(unnamed)";
+    if (f.join !== undefined) {
+      if (readsAGiven(f.onExpression, new WeakSet)) {
+        return {
+          ok: false,
+          reason: "dynamic_join",
+          detail: `the join '${label}' has a given in its \`on:\` condition, ` + `which decides which rows join per caller`
+        };
+      }
+      if (readsAGiven(f, new WeakSet)) {
+        const joined = joinedSourceRefusal(f, label, depth);
+        if (!joined.ok)
+          return joined;
+        joinedTerms.push(...joined.joinedTerms);
+      }
+      continue;
+    }
+    if (readsAGiven(f, new WeakSet)) {
+      return {
+        ok: false,
+        reason: "dynamic_projection",
+        detail: `the field '${label}' reads a given, so its value would ` + `differ per caller`
+      };
+    }
+  }
+  return;
+}
+function joinedSourceRefusal(f, label, depth) {
+  const refuse = (why) => ({
+    ok: false,
+    reason: "dynamic_joined_where",
+    detail: `the source joined as '${label}' is itself scoped by a given, ${why}`
+  });
+  if (depth >= MAX_JOIN_DEPTH) {
+    return refuse(`and is joined more than ${MAX_JOIN_DEPTH} levels deep`);
+  }
+  const sourceID = f.sourceID;
+  if (typeof sourceID !== "string" || sourceID.length === 0) {
+    return refuse(`and is joined through a refinement (\`… extend { … }\`) rather than ` + `by name, so the serve shape cannot bind the join to that source's ` + `stored table. Declare the refinement on a named source and join ` + `that`);
+  }
+  const source = sourceID.split("@")[0] || sourceID;
+  if (!declaresStorage(f.annotations)) {
+    return refuse(`and '${source}' is not materialized into a storage destination, so ` + `the join has no stored table to read per caller. Give '${source}' ` + `\`#@ persist … storage=\`, or drop \`storage=\` from this source`);
+  }
+  const target = { ...f };
+  for (const key of JOIN_ONLY_KEYS)
+    delete target[key];
+  const inner = classifyDef(target, depth + 1);
+  if (!inner.ok) {
+    return refuse(`and '${source}' could not itself be materialized per caller: ` + inner.detail);
+  }
+  return {
+    ok: true,
+    joinedTerms: [
+      { alias: label, source, terms: inner.terms },
+      ...(inner.joinedTerms ?? []).map((nested) => ({
+        ...nested,
+        alias: `${label}.${nested.alias}`
+      }))
+    ]
+  };
+}
+function declaresStorage(annotations) {
+  if (annotations === undefined || annotations === null)
+    return false;
+  try {
+    const tag = new Annotations4(annotations).parseAsTag("@").tag;
+    if (!tag.has("persist"))
+      return false;
+    const storage = tag.text("storage");
+    return typeof storage === "string" && storage.trim().length > 0;
+  } catch {
+    return false;
+  }
+}
+function givenScopedJoinTargets(fields) {
+  if (!Array.isArray(fields))
+    return [];
+  const out = [];
+  for (const field of fields) {
+    if (field === null || typeof field !== "object")
+      continue;
+    const f = field;
+    if (f.join === undefined || !readsAGiven(f, new WeakSet))
+      continue;
+    const restricted = f.accessModifier != null && f.accessModifier !== "public";
+    out.push(!restricted && typeof f.sourceID === "string" && f.sourceID.length > 0 ? f.sourceID : undefined);
+  }
+  return out;
+}
+function localFieldNames(entry) {
+  const usage = entry?.refSummary?.fieldUsage;
+  if (!Array.isArray(usage))
+    return [];
+  const names = new Set;
+  for (const use of usage) {
+    const path9 = use?.path;
+    if (!Array.isArray(path9) || path9.length !== 1 || typeof path9[0] !== "string") {
+      return [];
+    }
+    names.add(path9[0]);
+  }
+  return [...names];
+}
+function readTimeDynamicTerms(persistSource) {
+  try {
+    const def = persistSource._sourceDef;
+    return collectDynamicTerms(def?.filterList);
+  } catch {
+    return [{ code: "<unreadable>", givens: [], columns: [] }];
+  }
+}
+function collectDynamicTerms(filterList) {
+  if (!Array.isArray(filterList))
+    return [];
+  const terms = [];
+  for (const entry of filterList) {
+    if (entry === null || typeof entry !== "object")
+      continue;
+    if (!readsAGiven(entry, new WeakSet))
+      continue;
+    const code = entry.code;
+    terms.push({
+      code: typeof code === "string" ? code : "",
+      givens: givenNames(entry),
+      columns: localFieldNames(entry)
+    });
+  }
+  return terms;
+}
+var MAX_WALK_DEPTH = 200, JOIN_ONLY_KEYS, MAX_JOIN_DEPTH = 4;
+var init_persist_dynamic_terms = __esm(() => {
+  init_given();
+  JOIN_ONLY_KEYS = [
+    "join",
+    "onExpression",
+    "matrixOperation",
+    "refSummary",
+    "referenceID"
+  ];
+});
+
 // src/service/materialization_serve_transform.ts
 import {
   InMemoryURLReader,
@@ -271639,6 +271924,8 @@ function serveShapeDiagnostics(allBindings, freshBindings) {
   };
 }
 function derivedSourceFragment(lift) {
+  if (lift.text !== undefined)
+    return `source: ${lift.text}`;
   const lines = refinementLines(lift.refinements);
   const body = lines.length > 0 ? ` extend {
 ${lines.join(`
@@ -271653,7 +271940,7 @@ function optsOutOfPersist(def) {
 function liftDerivedSources(ctx) {
   const lifts = [];
   const available = new Set(ctx.shapeSourceNames);
-  const pending = Object.entries(ctx.contents).filter(([name, def]) => typeof def?.extends === "string" && !(ctx.boundSourceNames ?? ctx.shapeSourceNames).has(name) && def?.persistent !== true && !optsOutOfPersist(def));
+  const pending = Object.entries(ctx.contents).filter(([name, def]) => derivedFrom(def) !== undefined && !(ctx.boundSourceNames ?? ctx.shapeSourceNames).has(name) && def?.persistent !== true && !optsOutOfPersist(def));
   let progressed = true;
   while (progressed) {
     progressed = false;
@@ -271662,10 +271949,10 @@ function liftDerivedSources(ctx) {
       if (!entry)
         continue;
       const [name, def] = entry;
-      const base = ctx.sourceNameById.get(def.extends);
+      const base = ctx.sourceNameById.get(derivedFrom(def));
       if (!base || !available.has(base))
         continue;
-      const lift = liftOneDerivedSource(name, def, base, available, ctx);
+      const lift = typeof def.extends === "string" ? liftOneDerivedSource(name, def, base, available, ctx) : liftQueryDerivedSource(name, def, base, available, ctx);
       pending[i] = undefined;
       progressed = true;
       if (!lift)
@@ -271676,6 +271963,74 @@ function liftDerivedSources(ctx) {
   }
   return lifts;
 }
+function derivedFrom(def) {
+  if (typeof def?.extends === "string")
+    return def.extends;
+  if (def?.type !== "query_source")
+    return;
+  return structRefSourceId(def.query?.structRef);
+}
+function structRefSourceId(structRef) {
+  if (typeof structRef === "string")
+    return structRef;
+  const sourceID = structRef?.sourceID;
+  return typeof sourceID === "string" && sourceID.length > 0 ? sourceID : undefined;
+}
+function liftQueryDerivedSource(sourceName, def, base, available, ctx) {
+  if (!def.location)
+    return;
+  const text = ctx.liftText(def.location);
+  if (!text)
+    return;
+  const reached = referencedSourceIds(def.query?.pipeline);
+  for (const sourceID of reached) {
+    const name = ctx.sourceNameById.get(sourceID);
+    if (!name || !available.has(name))
+      return;
+  }
+  const declaredJoins = (def.fields ?? []).filter((f) => typeof f.join === "string");
+  for (const join5 of declaredJoins) {
+    const sourceID = join5.sourceID;
+    const name = typeof sourceID === "string" ? ctx.sourceNameById.get(sourceID) : undefined;
+    if (!name || !available.has(name))
+      return;
+  }
+  return { sourceName, base, refinements: [], text };
+}
+function referencedSourceIds(pipeline) {
+  const out = [];
+  let tooDeep = false;
+  const walk2 = (node, depth) => {
+    if (tooDeep)
+      return;
+    if (depth > 200) {
+      tooDeep = true;
+      return;
+    }
+    if (node === null || typeof node !== "object")
+      return;
+    if (Array.isArray(node)) {
+      for (const item of node)
+        walk2(item, depth + 1);
+      return;
+    }
+    const record = node;
+    if (typeof record.join === "string") {
+      out.push(typeof record.sourceID === "string" ? record.sourceID : "");
+      return;
+    }
+    if (record.structRef !== undefined) {
+      out.push(structRefSourceId(record.structRef) ?? "");
+    }
+    for (const [key, value] of Object.entries(record)) {
+      if (key === "structRef")
+        continue;
+      walk2(value, depth + 1);
+    }
+  };
+  walk2(pipeline, 0);
+  return tooDeep ? [""] : out;
+}
 function liftOneDerivedSource(sourceName, def, base, available, ctx) {
   const baseDef = ctx.contents[base];
   const baseFieldNames = new Set((baseDef?.fields ?? []).map((f) => fieldKey(f)).filter(Boolean));
@@ -271978,10 +272333,29 @@ async function assertServesInDuckDB(sourceName, binding, connections) {
     });
   }
 }
+function withholdUnreproducibleCallerScopedJoins(bindings, contents, sourceNameById) {
+  let kept = bindings;
+  for (;; ) {
+    const destinationOf = new Map(kept.map((b) => [b.sourceName, b.destinationName]));
+    const next = kept.filter((b) => givenScopedJoinTargets(contents?.[b.sourceName]?.fields).every((sourceID) => {
+      const target = sourceID === undefined ? undefined : sourceNameById.get(sourceID);
+      return target !== undefined && destinationOf.has(target) && destinationOf.get(target) === b.destinationName;
+    }));
+    if (next.length === kept.length) {
+      const keptNames = new Set(kept.map((b) => b.sourceName));
+      return {
+        kept,
+        withheld: bindings.map((b) => b.sourceName).filter((name) => !keptNames.has(name))
+      };
+    }
+    kept = next;
+  }
+}
 var BARE_IDENTIFIER, NEVER_THINNED, UNREPRODUCIBLE_FILTER = "__unreproducible_filter__";
 var init_materialization_serve_transform = __esm(() => {
   init_errors();
   init_logger();
+  init_persist_dynamic_terms();
   init_materialization_metrics();
   init_quoting();
   BARE_IDENTIFIER = /^[A-Za-z_][A-Za-z0-9_]*$/;
@@ -272673,11 +273047,11 @@ async function resolveGateShape(entry, originModelDef, graftScope, deps) {
             if (name)
               givenNamesById.set(id, name);
           }
-          const givenNames = Array.from(givenNamesById.values());
+          const givenNames2 = Array.from(givenNamesById.values());
           const literalNames = referencedGivenNames(filterText);
-          const accountedFor = new Set(givenNames);
+          const accountedFor = new Set(givenNames2);
           const unaccounted = literalNames.filter((name) => !accountedFor.has(name));
-          if (givenNames.length !== expansion.givenIds.size || unaccounted.length > 0) {
+          if (givenNames2.length !== expansion.givenIds.size || unaccounted.length > 0) {
             classification = {
               shape: "rejected",
               cause: "unreachable_given",
@@ -272686,7 +273060,7 @@ async function resolveGateShape(entry, originModelDef, graftScope, deps) {
           } else {
             classification = {
               shape: "row_level",
-              givenNames,
+              givenNames: givenNames2,
               givenNamesById
             };
           }
@@ -272920,209 +273294,6 @@ var init_gate_classification = __esm(() => {
   init_gate_registry_walk();
 });
 
-// src/service/persist_dynamic_terms.ts
-function givenNames(node) {
-  const names = new Set;
-  collectGivenRefs(node, names);
-  return [...names];
-}
-function readsAGiven(node, seen, depth = 0) {
-  if (depth > MAX_WALK_DEPTH) {
-    throw new Error("given walk exceeded max depth");
-  }
-  if (node === null || typeof node !== "object")
-    return false;
-  if (seen.has(node))
-    return false;
-  seen.add(node);
-  if (Array.isArray(node)) {
-    return node.some((item) => readsAGiven(item, seen, depth + 1));
-  }
-  const record = node;
-  if (record.node === "given" || record.node === "givenReference")
-    return true;
-  if (record.givenRef !== undefined)
-    return true;
-  const summary = record.refSummary;
-  if (summary?.givenUsage && summary.givenUsage.length > 0)
-    return true;
-  if (Array.isArray(record.givenUsage) && record.givenUsage.length > 0) {
-    return true;
-  }
-  return Object.values(record).some((v) => readsAGiven(v, seen, depth + 1));
-}
-function buildSubstitutesAGiven(persistSource) {
-  try {
-    const def = persistSource._sourceDef;
-    if (def === null || typeof def !== "object") {
-      throw new Error("compiled source definition is not readable");
-    }
-    const query = def.query;
-    if (query !== null && typeof query === "object") {
-      const usage = query.givenUsage;
-      if (Array.isArray(usage) && usage.length > 0)
-        return true;
-      if (argumentBindsAGiven(query))
-        return true;
-      if (Array.isArray(usage))
-        return false;
-    }
-    const {
-      filterList: _readTimeFilters,
-      fields: _readTimeFields,
-      ...relation
-    } = def;
-    return readsAGiven(relation, new WeakSet);
-  } catch {
-    return true;
-  }
-}
-function argumentBindsAGiven(node, depth = 0) {
-  if (depth > MAX_WALK_DEPTH) {
-    throw new Error("argument walk exceeded max depth");
-  }
-  if (node === null || typeof node !== "object")
-    return false;
-  if (Array.isArray(node)) {
-    return node.some((item) => argumentBindsAGiven(item, depth + 1));
-  }
-  for (const [key, value] of Object.entries(node)) {
-    if ((key === "arguments" || key === "sourceArguments") && readsAGiven(value, new WeakSet)) {
-      return true;
-    }
-    if (argumentBindsAGiven(value, depth + 1))
-      return true;
-  }
-  return false;
-}
-function classifyDynamicTerms(persistSource) {
-  if (buildSubstitutesAGiven(persistSource)) {
-    return {
-      ok: false,
-      reason: "given_in_persisted_query",
-      detail: `a given is read while the persisted relation is BUILT, so its ` + `value is substituted at build time — from the declaration's ` + `default, the only value available then — and every caller is ` + `served that one slice. Move the given out of the persisted query ` + `and into the source's extend block (\`where: …\`), where it is ` + `left out of the build and applied per caller when the artifact ` + `is read`
-    };
-  }
-  let def;
-  try {
-    def = persistSource._sourceDef;
-    if (def === null || typeof def !== "object") {
-      throw new Error("compiled source definition is not readable");
-    }
-  } catch (err) {
-    return {
-      ok: false,
-      reason: "given_in_persisted_query",
-      detail: `its given usage could not be determined ` + `(${err instanceof Error ? err.message : String(err)}), so the ` + `publisher cannot prove which givens the build would bake in`
-    };
-  }
-  try {
-    const fieldRefusal = classifyFields(def.fields);
-    if (fieldRefusal)
-      return fieldRefusal;
-    const terms = collectDynamicTerms(def.filterList);
-    const {
-      filterList: _accounted,
-      fields: _alsoAccounted,
-      query: _cleared,
-      ...rest
-    } = def;
-    if (readsAGiven(rest, new WeakSet)) {
-      return {
-        ok: false,
-        reason: "given_in_persisted_query",
-        detail: `a given sits in a part of the source this pass cannot place ` + `— it is neither an extend-block \`where:\` nor a field ` + `declared on the source — so the publisher cannot prove the ` + `build leaves it out`
-      };
-    }
-    return { ok: true, terms };
-  } catch (err) {
-    return {
-      ok: false,
-      reason: "given_in_persisted_query",
-      detail: `its given usage could not be determined ` + `(${err instanceof Error ? err.message : String(err)}), so the ` + `publisher cannot prove the build leaves every given out`
-    };
-  }
-}
-function classifyFields(fields) {
-  if (!Array.isArray(fields))
-    return;
-  for (const field of fields) {
-    if (field === null || typeof field !== "object")
-      continue;
-    const f = field;
-    const label = typeof f.as === "string" ? f.as : typeof f.name === "string" ? f.name : "(unnamed)";
-    if (f.join !== undefined) {
-      if (readsAGiven(f.onExpression, new WeakSet)) {
-        return {
-          ok: false,
-          reason: "dynamic_join",
-          detail: `the join '${label}' has a given in its \`on:\` condition, ` + `which decides which rows join per caller`
-        };
-      }
-      if (readsAGiven(f, new WeakSet)) {
-        return {
-          ok: false,
-          reason: "dynamic_joined_where",
-          detail: `the source joined as '${label}' is itself scoped by a ` + `given. Enter through a non-persisted extension that ` + `declares the join instead, so the given term is part of ` + `the query rather than of the artifact`
-        };
-      }
-      continue;
-    }
-    if (readsAGiven(f, new WeakSet)) {
-      return {
-        ok: false,
-        reason: "dynamic_projection",
-        detail: `the field '${label}' reads a given, so its value would ` + `differ per caller`
-      };
-    }
-  }
-  return;
-}
-function localFieldNames(entry) {
-  const usage = entry?.refSummary?.fieldUsage;
-  if (!Array.isArray(usage))
-    return [];
-  const names = new Set;
-  for (const use of usage) {
-    const path9 = use?.path;
-    if (!Array.isArray(path9) || path9.length !== 1 || typeof path9[0] !== "string") {
-      return [];
-    }
-    names.add(path9[0]);
-  }
-  return [...names];
-}
-function readTimeDynamicTerms(persistSource) {
-  try {
-    const def = persistSource._sourceDef;
-    return collectDynamicTerms(def?.filterList);
-  } catch {
-    return [{ code: "<unreadable>", givens: [], columns: [] }];
-  }
-}
-function collectDynamicTerms(filterList) {
-  if (!Array.isArray(filterList))
-    return [];
-  const terms = [];
-  for (const entry of filterList) {
-    if (entry === null || typeof entry !== "object")
-      continue;
-    if (!readsAGiven(entry, new WeakSet))
-      continue;
-    const code = entry.code;
-    terms.push({
-      code: typeof code === "string" ? code : "",
-      givens: givenNames(entry),
-      columns: localFieldNames(entry)
-    });
-  }
-  return terms;
-}
-var MAX_WALK_DEPTH = 200;
-var init_persist_dynamic_terms = __esm(() => {
-  init_given();
-});
-
 // src/service/incremental_declaration.ts
 function safeTag(source) {
   try {
@@ -273623,7 +273794,7 @@ var init_preaggregation_compile = __esm(() => {
 });
 
 // src/service/build_plan.ts
-import { Annotations as Annotations4 } from "@malloydata/malloy";
+import { Annotations as Annotations5 } from "@malloydata/malloy";
 function deriveColumns(persistSource) {
   try {
     return persistSource._explore.intrinsicFields.filter((f) => f.isAtomicField()).map((f) => ({
@@ -273638,6 +273809,9 @@ function deriveColumns(persistSource) {
     return [];
   }
 }
+function wireTerm(term) {
+  return { code: term.code, givens: term.givens };
+}
 function planDynamicFields(source, annotationFields) {
   const out = {};
   const partition = resolvePartitionColumns(source, annotationFields);
@@ -273646,9 +273820,13 @@ function planDynamicFields(source, annotationFields) {
   }
   const classified = classifyDynamicTerms(source);
   if (classified.ok && classified.terms.length > 0) {
-    out.strippedTerms = classified.terms.map((term) => ({
-      code: term.code,
-      givens: term.givens
+    out.strippedTerms = classified.terms.map(wireTerm);
+  }
+  if (classified.ok && classified.joinedTerms?.length) {
+    out.joinedTerms = classified.joinedTerms.map((joined) => ({
+      alias: joined.alias,
+      source: joined.source,
+      terms: joined.terms.map(wireTerm)
     }));
   }
   return out;
@@ -273850,7 +274028,7 @@ function detectDroppedPersistSources(malloyModel, recognizedNames) {
         continue;
       let isPersist = false;
       try {
-        isPersist = new Annotations4(def.annotations).parseAsTag("@").tag.has("persist");
+        isPersist = new Annotations5(def.annotations).parseAsTag("@").tag.has("persist");
       } catch {
         continue;
       }
@@ -274006,11 +274184,11 @@ function deriveBuildPlan(graphs, sources, connectionDigests, sourceNames, source
       continue;
     try {
       const annotationFields = deriveAnnotationFields(source);
-      const declaresStorage = !!annotationFields.storage;
+      const declaresStorage2 = !!annotationFields.storage;
       const rollup = options?.preaggregatePlans?.[sourceID];
       if (!rollup) {
         try {
-          if (declaresStorage) {
+          if (declaresStorage2) {
             assertMaterializationEligible(source, deriveAnnotationFields(source));
           } else {
             assertColocatedPersistNotAuthorizeGated(source, source.name, "persist", options?.sourceGateOutcomes?.[sourceID], annotationFields);
@@ -274022,7 +274200,7 @@ function deriveBuildPlan(graphs, sources, connectionDigests, sourceNames, source
             name: source.name,
             sourceID: source.sourceID,
             modelPath: sourceModelPaths?.[sourceID],
-            tier: declaresStorage ? "storage" : "colocated",
+            tier: declaresStorage2 ? "storage" : "colocated",
             reason: err.reason || "authorize",
             message: errMessage(err)
           };
@@ -274032,7 +274210,7 @@ function deriveBuildPlan(graphs, sources, connectionDigests, sourceNames, source
         let storageRefused = false;
         try {
           assertColocatedPersistNotAuthorizeGated(source, source.name, "preaggregate", options?.sourceGateOutcomes?.[sourceID], annotationFields);
-          if (declaresStorage) {
+          if (declaresStorage2) {
             storageRefused = true;
             assertMaterializationEligible(source, deriveAnnotationFields(source));
             storageRefused = false;
@@ -274436,9 +274614,11 @@ function extractRunTargetSourceName(query) {
 }
 function buildSourceAliasMap(query) {
   const aliasOf = new Map;
-  const declRe = /source\s*:\s*(?:`([^`]+)`|(\w+))\s+is\s+(?:`([^`]+)`|(\w+))/g;
+  const text = stripMalloyCommentsAndLiterals(query);
+  const ident = String.raw`(?:\x60([^\x60]+)\x60|([\p{L}\p{N}_]+))`;
+  const declRe = new RegExp(String.raw`source\s*:\s*${ident}(?:\s*\([^)]*\))?\s+is\s*\(?\s*${ident}`, "gu");
   let match;
-  while ((match = declRe.exec(query)) !== null) {
+  while ((match = declRe.exec(text)) !== null) {
     aliasOf.set(match[1] ?? match[2], match[3] ?? match[4]);
   }
   return aliasOf;
@@ -274489,8 +274669,9 @@ function stripMalloyCommentsAndLiterals(text) {
   }
   return out.join("");
 }
-function buildDerivationBaseMap(text) {
+function buildDerivationBaseMap(query) {
   const basesOf = new Map;
+  const text = stripMalloyCommentsAndLiterals(query);
   const ident = String.raw`(?:\x60([^\x60]+)\x60|([\p{L}\p{N}_]+))`;
   const declRe = new RegExp(String.raw`(?:source|query)\s*:\s*${ident}(?:\s*\([^)]*\))?\s+is\s*\(?\s*${ident}`, "gu");
   let match;
@@ -275080,8 +275261,8 @@ import {
   InMemoryURLReader as InMemoryURLReader2,
   isSourceDef as isSourceDef7,
   MalloyConfig as MalloyConfig2,
-  MalloyError as MalloyError3,
-  Annotations as Annotations5,
+  MalloyError as MalloyError4,
+  Annotations as Annotations6,
   modelDefToModelInfo as modelDefToModelInfo2,
   Runtime as Runtime2
 } from "@malloydata/malloy";
@@ -275956,7 +276137,7 @@ var init_model = __esm(() => {
         if (error instanceof Error && error.stack) {
           logger.error("Error stack", error.stack);
         }
-        if (error instanceof MalloyError3) {
+        if (error instanceof MalloyError4) {
           const problems = error.problems;
           for (const problem of problems) {
             logger.error("Problem", problem);
@@ -276112,17 +276293,15 @@ var init_model = __esm(() => {
       return this.admittedByPackage(name, this.queryBoundary.packageCuratedSources);
     }
     isCuratedQuery(name) {
-      if ((this.getQueries() ?? []).some((q) => q.name === name))
+      if (!this.isNotebook() && (this.getQueries() ?? []).some((q) => q.name === name))
         return true;
       return this.admittedByPackage(name, this.queryBoundary.packageCuratedQueries);
     }
     assertQueryBoundaryEarly(sourceName, queryName, query) {
-      if (this.modelPath.endsWith(NOTEBOOK_FILE_SUFFIX))
-        return "cleared";
       const { mode, exploresDeclared, isQueryEntryPoint } = this.queryBoundary;
       if (mode === "all" || !exploresDeclared)
         return "cleared";
-      if (!isQueryEntryPoint) {
+      if (!isQueryEntryPoint && !this.isNotebook()) {
         throw new NotQueryableError(`No queryable model "${this.modelPath}".`);
       }
       if (queryName && !query) {
@@ -276140,18 +276319,16 @@ var init_model = __esm(() => {
       if (query) {
         const target = extractRunTargetSourceName(query);
         if (target && !this.isCuratedSource(target) && !this.derivesFromCurated(target, query) && this.sources?.some((s) => s.name === target)) {
-          throw new NotQueryableError(`No queryable source "${target}".`);
+          throw new NotQueryableError("Query target is not queryable.");
         }
       }
       return "deferred";
     }
     assertQueryBoundaryCompiled(compiledSource, query) {
-      if (this.modelPath.endsWith(NOTEBOOK_FILE_SUFFIX))
-        return;
       const { mode, exploresDeclared, isQueryEntryPoint } = this.queryBoundary;
       if (mode === "all" || !exploresDeclared)
         return;
-      if (!isQueryEntryPoint) {
+      if (!isQueryEntryPoint && !this.isNotebook()) {
         throw new NotQueryableError(`No queryable model "${this.modelPath}".`);
       }
       if (compiledSource) {
@@ -276168,7 +276345,12 @@ var init_model = __esm(() => {
         return;
       this.assertQueryBoundaryCompiled(await this.resolveAuthorizeSourceFromRunnable(runnable), query);
     }
+    isNotebook() {
+      return this.modelPath.endsWith(NOTEBOOK_FILE_SUFFIX);
+    }
     ownCuratedSourceNames() {
+      if (this.isNotebook())
+        return new Set;
       return new Set((this.getSources() ?? []).map((s) => s.name).filter((n) => n !== undefined));
     }
     derivesFromCurated(name, query) {
@@ -276381,6 +276563,44 @@ var init_model = __esm(() => {
     async compileServeShape(enriched, rollupGroups = [], isRetry = false) {
       const tiers = buildServeShapeTiers(rollupGroups);
       const nothingToEscalate = rollupGroups.length === 0 && !enriched.some((b) => (b.refinements ?? []).length > 0);
+      let lifts = this.liftedDerivedSources(enriched);
+      if (lifts.length > 0) {
+        const probe = async (candidate) => {
+          const m = this.buildServeShapeMaterializer(enriched, tiers[0].groups, candidate);
+          try {
+            await m.getModel();
+            return m;
+          } catch (err) {
+            return err instanceof Error ? err : new Error(String(err));
+          }
+        };
+        const withAll = await probe(lifts);
+        if (!(withAll instanceof Error))
+          return withAll;
+        const withNone = await probe([]);
+        const kept = [];
+        let best;
+        if (!(withNone instanceof Error)) {
+          best = withNone;
+          for (const lift of lifts) {
+            const attempt = await probe([...kept, lift]);
+            if (attempt instanceof Error)
+              continue;
+            kept.push(lift);
+            best = attempt;
+          }
+        }
+        if (kept.length < lifts.length)
+          recordServeShapeTierDrop("lifts");
+        logger.warn("Storage serve shape failed to compile with its lifted entry points; the ones that do not compile serve live", {
+          model: this.modelPath,
+          dropped: lifts.filter((l) => !kept.includes(l)).map((l) => l.sourceName),
+          error: withAll.message
+        });
+        if (best)
+          return best;
+        lifts = [];
+      }
       const lastTier = tiers.length - 1;
       for (let tier = 0;tier <= lastTier; tier++) {
         const { keep, groups } = tiers[tier];
@@ -276388,7 +276608,7 @@ var init_model = __esm(() => {
           ...b,
           refinements: b.refinements.filter((r) => keep.has(r.kind))
         } : b);
-        const materializer = this.buildServeShapeMaterializer(shaped, groups, tier === 0 ? this.liftedDerivedSources(enriched) : []);
+        const materializer = this.buildServeShapeMaterializer(shaped, groups, tier === 0 ? lifts : []);
         if (tier === lastTier) {
           try {
             await materializer.getModel();
@@ -276515,10 +276735,17 @@ var init_model = __esm(() => {
     }
     serveBindingsWithRefinements(bindings) {
       const { contents, sourceNameById, liftText } = this.authorModelLift();
-      const materializedSourceNames = new Set(bindings.map((b) => b.sourceName));
-      return bindings.map((b) => {
+      const onShape = bindings.map((b) => ({
+        ...b,
+        schema: narrowSchemaToPublic(b.schema, contents?.[b.sourceName]?.fields)
+      })).filter((b) => b.schema.length > 0);
+      const { kept, withheld } = withholdUnreproducibleCallerScopedJoins(onShape, contents, sourceNameById);
+      if (withheld.length > 0) {
+        logger.warn("Withheld storage serve bindings whose caller-scoped join cannot be reproduced; those sources serve live", { model: this.modelPath, withheld });
+      }
+      const materializedSourceNames = new Set(kept.map((b) => b.sourceName));
+      return kept.map((b) => {
         const fields = contents?.[b.sourceName]?.fields;
-        const schema = narrowSchemaToPublic(b.schema, fields);
         const refinements = [
           ...extractJoins(fields, {
             sourceNameById,
@@ -276529,13 +276756,13 @@ var init_model = __esm(() => {
           ...extractSourceFilters(contents?.[b.sourceName]?.filterList),
           ...extractViews(fields, liftText)
         ];
-        return { ...b, schema, refinements };
-      }).filter((b) => b.schema.length > 0);
+        return { ...b, refinements };
+      });
     }
     async getQueryResults(sourceName, queryName, query, filterParams, bypassFilters, givens, abortSignal, queryMetadataInput, responseShape = "full", bypassAuthorize = false) {
       const startTime = performance.now();
       if (this.compilationError) {
-        if (this.compilationError instanceof MalloyError3 || this.compilationError instanceof ModelCompilationError) {
+        if (this.compilationError instanceof MalloyError4 || this.compilationError instanceof ModelCompilationError) {
           throw this.compilationError;
         }
         throw new BadRequestError(`Model compilation failed: ${this.compilationError.message}`);
@@ -276660,7 +276887,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         if (error instanceof FilterValidationError) {
           throw new BadRequestError(error.message);
         }
-        if (error instanceof MalloyError3) {
+        if (error instanceof MalloyError4) {
           throw error;
         }
         const errorMessage = error instanceof Error ? error.message : String(error);
@@ -276745,7 +276972,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
             });
             throw new BadRequestError(err instanceof Error ? err.message : String(err));
           }
-          if (err instanceof MalloyError3) {
+          if (err instanceof MalloyError4) {
             throw err;
           }
           const errorMessage = err instanceof Error ? err.message : String(err);
@@ -276881,7 +277108,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
       if (!this.modelDef)
         return;
       try {
-        return new Annotations5(ownModelAnnotations(this.modelDef)).parseAsTag().tag;
+        return new Annotations6(ownModelAnnotations(this.modelDef)).parseAsTag().tag;
       } catch {
         return;
       }
@@ -276896,7 +277123,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
         const def = entry;
         if (!def.annotations)
           return;
-        return new Annotations5(def.annotations).parseAsTag("@").tag;
+        return new Annotations6(def.annotations).parseAsTag("@").tag;
       } catch {
         return;
       }
@@ -277041,7 +277268,7 @@ run: ${sourceName ? `${quoteMalloyIdentifier2(sourceName)} -> ` : ""}${quoteMall
             });
             throw new BadRequestError(error instanceof Error ? error.message : String(error));
           }
-          if (error instanceof MalloyError3) {
+          if (error instanceof MalloyError4) {
             throw error;
           }
           if (error instanceof PayloadTooLargeError) {
@@ -302208,7 +302435,7 @@ class QueryController {
     const p = await environment.getPackage(packageName, false);
     const model = p.getModel(modelPath);
     if (!model) {
-      throw new ModelNotFoundError(`${modelPath} does not exist`);
+      throw new ModelNotFoundError(`No queryable model "${modelPath}".`);
     } else {
       const {
         result,
@@ -309249,18 +309476,59 @@ class StorageManager {
 
 // src/service/environment.ts
 init_telemetry();
-import { MalloyError as MalloyError5, Runtime as Runtime3 } from "@malloydata/malloy";
+import { MalloyError as MalloyError6, Runtime as Runtime3 } from "@malloydata/malloy";
 init_constants();
 init_errors();
 init_authorize();
-init_authorize_metrics();
-init_config();
-init_logger();
-init_pg_helpers();
 import crypto4 from "crypto";
 import * as fs8 from "fs";
 import * as path12 from "path";
 import { fileURLToPath as fileURLToPath7, pathToFileURL as pathToFileURL2 } from "url";
+
+// src/service/compile_restriction.ts
+init_errors();
+import { Malloy, MalloyError as MalloyError3 } from "@malloydata/malloy";
+var RESTRICTED_CONSTRUCT_CODE = "restricted-construct-forbidden";
+var SYNTAX_ERROR_CODE = "syntax-error";
+function isParseFailure(problem) {
+  return problem.code === SYNTAX_ERROR_CODE && problem.severity === "error";
+}
+function restrictedRejections(problems) {
+  return problems.filter((problem) => problem.code === RESTRICTED_CONSTRUCT_CODE);
+}
+async function assertNoRestrictedConstructs(runtime, model, source) {
+  let problems;
+  try {
+    const compiled = await Malloy.compile({
+      source,
+      model,
+      restrictedMode: true,
+      method: "extendModel",
+      urlReader: runtime.urlReader,
+      connections: runtime.connections,
+      noThrowOnError: true
+    });
+    problems = compiled.problems ?? [];
+  } catch (error) {
+    if (!(error instanceof MalloyError3))
+      throw error;
+    problems = error.problems;
+  }
+  const rejected = restrictedRejections(problems);
+  if (rejected.length === 0) {
+    if (problems.some(isParseFailure)) {
+      throw new CompileRefusedError(`This Malloy cannot be compiled at scope "append": the submitted ` + `text could not be parsed on its own, so it cannot be checked ` + `against the model's published surface. Fix: send text that ` + `stands alone as top-level Malloy -- a complete ` + `\`source:\`/\`query:\`/\`run:\` statement rather than a ` + `continuation of one already in the model.`);
+    }
+    return;
+  }
+  throw new CompileRefusedError(`This Malloy cannot be compiled at scope "append", which validates a ` + `fragment against the model's published surface: ` + `${rejected.map((problem) => problem.message).join(" ")} ` + `Fix: reference the model's own sources. Defining sources and ` + `imports belongs in the model file itself -- see the compile-scope ` + `documentation.`);
+}
+
+// src/service/environment.ts
+init_authorize_metrics();
+init_config();
+init_logger();
+init_pg_helpers();
 init_materialization_metrics();
 init_path_safety();
 init_utils4();
@@ -309378,7 +309646,7 @@ import {
   EmptyURLReader,
   FixedConnectionMap as FixedConnectionMap2,
   MalloyConfig as MalloyConfig3,
-  MalloyError as MalloyError4
+  MalloyError as MalloyError5
 } from "@malloydata/malloy";
 
 // src/package_load_metrics.ts
@@ -310267,7 +310535,7 @@ function toTableNameManifest(entries) {
   return out;
 }
 function packageLoadFailureStatus(error) {
-  if (error instanceof ModelCompilationError || error instanceof MalloyError4) {
+  if (error instanceof ModelCompilationError || error instanceof MalloyError5) {
     return "compilation_error";
   }
   if (error instanceof BadRequestError) {
@@ -310326,6 +310594,23 @@ class Package {
     const explores = this.packageMetadata.explores;
     return !!(explores && explores.length > 0);
   }
+  surfaceWidenedWarning;
+  noteSurfaceChangeFrom(previousSurface) {
+    this.surfaceWidenedWarning = undefined;
+    if (!previousSurface || previousSurface.length === 0 || this.packageMetadata.explores !== undefined) {
+      return;
+    }
+    const message = `This package published "${previousSurface.join('", "')}" before the last ` + `reload and publishes no surface now, so every model in it is listed ` + `and queryable by name again, including the sources that surface was ` + `withholding. A surface file that was deleted or renamed is the usual ` + `cause. If that was intended, nothing to do. If not, restore the file ` + `(under its original name -- the name IS the surface), or declare an ` + `"explores" in publisher.json naming what this package should ` + `publish. To keep the package open deliberately, write ` + `"explores": [], which says so and stops this notice.`;
+    this.surfaceWidenedWarning = message;
+    logger.warn(`Package ${this.packageName} no longer publishes a surface`, {
+      packageName: this.packageName,
+      detail: message
+    });
+  }
+  surfaceIsIndexModel() {
+    const explores = this.packageMetadata.explores;
+    return this.models.has(INDEX_MODEL_NAME) && explores?.length === 1 && explores[0] === INDEX_MODEL_NAME;
+  }
   exploreSet() {
     const explores = this.packageMetadata.explores;
     return explores && explores.length > 0 ? new Set(explores) : null;
@@ -310430,7 +310715,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 MalloyError4 || realError instanceof ModelCompilationError) {
+      if (realError instanceof MalloyError5 || realError instanceof ModelCompilationError) {
         throw realError;
       }
       throw new ServiceUnavailableError(`Package-load worker pool unavailable: ${realError.message}`);
@@ -310665,6 +310950,8 @@ class Package {
       ...this.droppedPersistWarnings(),
       ...this.persistRefusalWarnings(),
       ...this.emptyDiscoveryWarnings(),
+      ...this.brokenSurfaceWarnings(),
+      ...this.surfaceWidenedWarning !== undefined ? [{ message: this.surfaceWidenedWarning }] : [],
       ...this.persistenceCollisionWarnings().map((message) => ({ message })),
       ...this.preaggregateAccessWarnings(),
       ...incrementalPolicyAdvisories(this.incrementalPolicySources),
@@ -310825,7 +311112,7 @@ class Package {
       if (entry.endsWith(NOTEBOOK_FILE_SUFFIX)) {
         problems.push({
           entry,
-          reason: `notebooks are always public and cannot be explores. ` + `Fix: remove it, and list a ${MODEL_FILE_SUFFIX} model file instead.`
+          reason: `notebooks are always listed and cannot be explores. ` + `Fix: remove it, and list a ${MODEL_FILE_SUFFIX} model file instead.`
         });
       } else if (!malloyModels.has(entry)) {
         problems.push({
@@ -310996,13 +311283,39 @@ class Package {
       if (model.hasEmptyDiscoverySurface()) {
         warnings.push({
           model: modelPath,
-          message: `Model "${modelPath}" is listed in explores but exposes ` + `nothing: its export closure surfaces no sources or named ` + `queries (typically an import-only file, or an export {} ` + `that filters everything out). Add e.g. ` + `'export { source_name }' to surface sources on this ` + `model, or remove it from explores.`
+          message: `Model "${modelPath}" is on this package's discovery ` + `surface but exposes nothing: its export closure surfaces ` + `no sources or named queries (typically an import-only ` + `file, or an export {} that filters everything out). Add ` + `e.g. 'export { source_name }' to surface sources on this ` + `model, or ` + (this.surfaceIsIndexModel() ? `delete the file AND any "explores" entry naming it. ` + `Deleting the file alone returns the package to ` + `listing every model only when no "explores" was ` + `written; where one was, it would be left naming a ` + `model that no longer exists and the package would ` + `list nothing.` : `remove it from explores.`)
         });
       }
     }
     return warnings;
   }
+  brokenSurfaceWarnings() {
+    const exploreSet = this.exploreSet();
+    if (!exploreSet || exploreSet.size === 0)
+      return [];
+    const surface = Array.from(this.models.entries()).filter(([modelPath]) => modelPath.endsWith(MODEL_FILE_SUFFIX) && exploreSet.has(modelPath));
+    if (surface.length === 0)
+      return [];
+    if (!surface.every(([, model]) => !!model.getCompilationError())) {
+      return [];
+    }
+    const collateral = Array.from(this.models.entries()).filter(([modelPath, model]) => modelPath.endsWith(MODEL_FILE_SUFFIX) && !exploreSet.has(modelPath) && !model.getCompilationError()).length;
+    const [firstPath] = surface[0];
+    const subject = surface.length === 1 ? `Model "${firstPath}" is this package's whole discovery surface ` + `and failed to compile` : `Every model on this package's discovery surface ` + `(${surface.map(([p]) => `"${p}"`).join(", ")}) failed to ` + `compile`;
+    return [
+      {
+        model: firstPath,
+        message: `${subject}, so the package exposes nothing: every model in ` + `it, including the ${collateral} that compiled, is now refused ` + `by name with a 404 that reads as "does not exist". Fix the ` + `compile error${surface.length === 1 ? "" : "s"} to restore ` + `them -- ` + surface.map(([modelPath, model]) => `${modelPath}: ` + `${model.getCompilationError()?.message ?? "unknown error"}`).join("; ")
+      }
+    ];
+  }
   logEmptyDiscoveryWarnings() {
+    for (const warning of this.brokenSurfaceWarnings()) {
+      logger.warn(`Package ${this.packageName} has a broken discovery surface`, {
+        packageName: this.packageName,
+        detail: warning.message
+      });
+    }
     for (const warning of this.emptyDiscoveryWarnings()) {
       logger.warn(`Package ${this.packageName} has a blank-looking model`, {
         packageName: this.packageName,
@@ -311075,7 +311388,7 @@ class Package {
       });
     } catch (err) {
       const realError = err instanceof Error ? err : new Error(`Package-load worker pool failure: ${String(err)}`);
-      if (realError instanceof MalloyError4 || realError instanceof ModelCompilationError) {
+      if (realError instanceof MalloyError5 || realError instanceof ModelCompilationError) {
         throw realError;
       }
       throw new ServiceUnavailableError(`Package-load worker pool unavailable: ${realError.message}`);
@@ -311120,7 +311433,9 @@ class Package {
     await this.pushPreaggregateServeModels();
     this.renderTagWarnings = renderTagWarnings;
     this.manifestWarnings = outcome.packageMetadata.manifestWarnings ?? [];
+    const previousSurface = this.packageMetadata.explores;
     this.packageMetadata.explores = outcome.packageMetadata.explores;
+    this.noteSurfaceChangeFrom(previousSurface);
     this.packageMetadata.queryableSources = outcome.packageMetadata.queryableSources;
     this.packageMetadata.manifestLocation = outcome.packageMetadata.manifestLocation ?? null;
     this.applyDiscoveryPolicyToModels();
@@ -311282,6 +311597,29 @@ class Package {
       });
     }
   }
+  lintTilesAgainstSurface(modelPath, manifest) {
+    const model = this.models.get(modelPath);
+    if (!model || !manifest.tiles)
+      return [];
+    const listedModel = (this.packageMetadata.explores ?? []).find((entry) => entry.endsWith(MODEL_FILE_SUFFIX) && !isDashboardModelPath(entry));
+    const importInto = listedModel ? `a listed file such as "${listedModel}"` : `a file you list there`;
+    const findings = [];
+    for (const tile of manifest.tiles) {
+      try {
+        model.assertQueryBoundaryEarly(undefined, undefined, `run: ${tile.query}`);
+      } catch (error) {
+        if (!(error instanceof NotQueryableError))
+          throw error;
+        findings.push({
+          model: modelPath,
+          subject: manifest.name,
+          message: `tile "${tile.query}" reads a source this package's surface ` + `does not publish, so the tile answers 404 once served, ` + `although the file compiles. Listing a file publishes what ` + `it declares, not what it imports. Fix: add the file that ` + `declares the source to 'explores', keeping the entries ` + `already there, or import it into ${importInto} and add ` + `it to that file's export { … }.`,
+          severity: "error"
+        });
+      }
+    }
+    return findings;
+  }
   async lintDashboards(factsByPath, allFacts, heldBack, unconventionalSlugs, knownSlugs, droppedByError) {
     const warnings = [];
     const withheldDrills = new Map;
@@ -311315,10 +311653,11 @@ class Package {
             });
           }
         }
+        const remedy = this.surfaceIsIndexModel() ? `This package's surface is "${INDEX_MODEL_NAME}", and a ` + `dashboard file cannot be exported from it -- dashboards are ` + `files, not sources. To serve this one, declare (or extend) ` + `an 'explores' in publisher.json listing both ` + `"${INDEX_MODEL_NAME}" and "${modelPath}"; an explicit key ` + `overrides the convention. Or set ` + `queryableSources: "all" to keep the curated surface for ` + `discovery only.` : `Add it to 'explores', or set queryableSources: "all" to ` + `keep the curated surface for discovery only.`;
         warnings.push({
           model: modelPath,
           subject: name,
-          message: `is a dashboard, but "${modelPath}" is not listed in ` + `'explores' and this package sets ` + `queryableSources: "declared", so its query would be ` + `refused. It is not served. Add it to 'explores', or set ` + `queryableSources: "all" to keep the curated surface for ` + `discovery only. Listing it is not always sufficient on its ` + `own: the queryable sources are the union of every listed ` + `file's export closure, so a tile reading a source that only ` + `an UNLISTED file exports is still refused. List that file ` + `too, or re-export the source from one already listed.`,
+          message: `is a dashboard, but "${modelPath}" is not part of this ` + `package's discovery surface and this package sets ` + `queryableSources: "declared", so its query would be ` + `refused. It is not served. ${remedy} Listing it is not ` + `always sufficient on its own: the queryable sources are ` + `the union of every listed file's export closure, so a tile ` + `reading a source that only an UNLISTED file exports is ` + `still refused. List that file too, or re-export the source ` + `from one already listed.`,
           severity: "warn"
         });
       }
@@ -311328,6 +311667,11 @@ class Package {
         for (const finding of findings) {
           warnings.push({ model: modelPath, ...finding });
         }
+        if (manifest) {
+          for (const finding of this.lintTilesAgainstSurface(modelPath, manifest)) {
+            warnings.push(finding);
+          }
+        }
       }
       const drillFacts = Array.from(allFacts.values());
       for (const finding of withheldDrills.values()) {
@@ -311576,6 +311920,15 @@ function getPackageAdmissionRejectionsCounter() {
   });
   return packageAdmissionRejectionsCounter;
 }
+var compileRefusalsCounter = null;
+function getCompileRefusalsCounter() {
+  if (compileRefusalsCounter)
+    return compileRefusalsCounter;
+  compileRefusalsCounter = publisherMeter().createCounter("publisher_compile_refusals_total", {
+    description: "Compiles refused at append scope, labelled by reason and environment"
+  });
+  return compileRefusalsCounter;
+}
 var COMPILE_SCOPES = ["append", "file", "package"];
 async function denyHiddenAsNotQueryable(convert, gate) {
   try {
@@ -311804,7 +312157,7 @@ ${source}` : source ?? "";
               }, () => hasExactGateModel ? gateModel.assertAuthorizedForRunnable(finalQuery, givens ?? {}) : gateModel.assertAuthorizedFromCompiledRunnable(finalQuery, givens ?? {}));
             }
           } catch (error) {
-            if (!(error instanceof MalloyError5))
+            if (!(error instanceof MalloyError6))
               throw error;
           }
         }
@@ -311864,6 +312217,36 @@ ${source}` : source ?? "";
         }
         return { problems };
       }
+      if (scope === "append") {
+        let baseModel;
+        try {
+          baseModel = await runtime.loadModel(pathToFileURL2(modelPath)).getModel();
+        } catch (error) {
+          logger.warn("Compile gate could not load the base model", {
+            modelPath,
+            error
+          });
+          getCompileRefusalsCounter().add(1, {
+            environment: this.environmentName,
+            reason: "base_model_load_failed"
+          });
+          if (error instanceof MalloyError6) {
+            throw new CompileRefusedError(`Cannot validate the submitted source: the model ` + `"${modelName}" does not compile, so there is nothing ` + `to check the submitted source against. Problems: ` + error.problems.map((p) => p.message).join("; "));
+          }
+          throw new CompileRefusedError(`Cannot validate the submitted source: the model ` + `"${modelName}" could not be loaded to check it against.`);
+        }
+        try {
+          await assertNoRestrictedConstructs(runtime, baseModel, source ?? "");
+        } catch (error) {
+          if (error instanceof CompileRefusedError) {
+            getCompileRefusalsCounter().add(1, {
+              environment: this.environmentName,
+              reason: "restricted_construct"
+            });
+          }
+          throw error;
+        }
+      }
       try {
         const modelMaterializer = runtime.loadModel(virtualUrl);
         const model = await modelMaterializer.getModel();
@@ -311889,14 +312272,14 @@ ${source}` : source ?? "";
             if (typeof givenCode === "string" && givenCode.startsWith("runtime-given-")) {
               throw new BadRequestError(error instanceof Error ? error.message : String(error));
             }
-            if (error instanceof MalloyError5) {
+            if (error instanceof MalloyError6) {
               throw error;
             }
           }
         }
         return { problems: tagProblems(model.problems), sql };
       } catch (error) {
-        if (error instanceof MalloyError5) {
+        if (error instanceof MalloyError6) {
           return { problems: tagProblems(error.problems) };
         }
         throw error;
@@ -312202,6 +312585,7 @@ ${source}` : source ?? "";
       await this.rebindServeBindingsFromLocalStore(_package);
       if (existingPackage !== undefined && reload) {
         this.retireConnectionGeneration(`package ${packageName}`, () => existingPackage.getMalloyConfig().shutdown("close"));
+        _package.noteSurfaceChangeFrom(existingPackage.getPackageMetadata().explores);
       }
       this.packages.set(packageName, _package);
       this.setPackageStatus(packageName, "serving" /* SERVING */);
@@ -312505,11 +312889,12 @@ ${source}` : source ?? "";
       const materializationBase = metadata.materialization !== undefined ? { ...metadata.materialization, ...preservedQueryMetadata } : onDiskMaterialization !== undefined ? { ...onDiskMaterialization } : undefined;
       const materializationBlock = resolvedScope !== undefined ? { ...materializationBase ?? {}, scope: resolvedScope } : materializationBase;
       const resolvedQueryMetadata = metadata.queryMetadata ?? materializationBlock?.queryMetadata ?? existingManifest.queryMetadata;
+      const echoesDerivedSurface = existingManifest.explores === undefined && Array.isArray(metadata.explores) && metadata.explores.length === 1 && metadata.explores[0] === INDEX_MODEL_NAME;
       const updatedManifest = {
         ...existingManifest,
         name: metadata.name,
         description: metadata.description,
-        ...metadata.explores !== undefined ? { explores: metadata.explores } : {},
+        ...metadata.explores !== undefined && !echoesDerivedSurface ? { explores: metadata.explores } : {},
         ...metadata.queryableSources !== undefined ? { queryableSources: metadata.queryableSources } : {},
         ...metadata.manifestLocation !== undefined ? { manifestLocation: metadata.manifestLocation } : {},
         ...resolvedScope !== undefined ? { scope: resolvedScope } : {},
@@ -317113,7 +317498,7 @@ var compileShape = {
 var COMPILE_DESCRIPTION = `Compile-check Malloy without running a query. Use this while authoring instead of a throwaway execute_query.
 
 ## Scopes (the scope parameter)
-- "append" (default): append source to modelPath. Use for NEW definitions; existing definitions report "Cannot redefine". Positions refer to the concatenated file.
+- "append" (default): append source to modelPath. Use for NEW definitions; existing definitions report "Cannot redefine". Positions refer to the concatenated file. Refused here, with a 400: import, connection.table(...), connection.sql(...), raw-SQL functions, given: declarations (reading the model's givens as $NAME is fine), ##! flags, and text that does not stand alone as top-level Malloy — a bare view:/dimension:/measure:, or anything parsing only as a continuation of the model's last statement. Wrap a view body in a top-level query:, a field in a throwaway source: check is <source> extend { … }; use "file" or "package" for a model that declares data roots.
 - "file": compile source AS modelPath. Use to validate an EDIT before saving; positions match the submitted file.
 - "package": run reload's worker compiler over all .malloy/.malloynb files without changing the served package. Optional source replaces modelPath so importers see the edit. Diagnostics may name files hidden from discovery; no rows or SQL are returned, and authorize gates still apply to caller text. A missing exact path is warned and treated as a new file. Save and call reload_package to serve a clean edit.
 
@@ -318985,7 +319370,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| `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. |\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",
@@ -319207,6 +319592,21 @@ If the agent could not reasonably have known to ask, that is a model gap.
 | \`GUIDANCE-NOT-RETRIEVED\` | entities came back, governing guidance did not | model: put guidance on the entities agents search for |
 | \`GUIDANCE-DECLINED\` | guidance was retrieved and judged inapplicable | model: state the business default, not a caveat |
 
+**Before diagnosing a \`NOT-RETURNED\`, check the call actually returned
+nothing.** The \`tool_call\` event carries \`retrieval_mode\` and \`rankedSummary\`.
+A \`rankedSummary\` of \`null\` means the response could not be read, not that it
+was empty -- a body too large for the model's context is written to a file, and
+the run records no summary for it. There is nothing to diagnose there: say the
+call was not measured.
+
+And **never attribute a miss to the embedding index unless \`retrieval_mode\`
+says \`lexical\`.** The mode is recorded per call precisely so this is checkable.
+A diagnosis once explained a phantom empty result with "the index was not ready
+yet" on a run whose index was ready before the first question and whose
+response did hold results; the empty list was a parsing bug in the harness. An
+unverifiable cause that sounds right is worse than \`needs_human\`, because it
+closes the finding.
+
 A missing join is coverage, not an agent-call miss. The model has to volunteer
 relationships. A declared join is not a retrieval entity; do not look for it in
 \`get_context\` results.
@@ -319880,7 +320280,145 @@ Available: case-format.`
     {
       name: "eval-import/case-format",
       description: "Reading an arriving question list. Reference detail for the eval-import skill.",
-      body: "<!-- What an arriving item maps to, and how to read the four formats questions actually arrive in. The file shapes themselves are in eval-answer/reference/ledger-schema.md; this is only what is specific to an import. -->\n\n# Reading an arriving question list\n\n`reference/ledger-schema.md` in `skill:eval-answer` defines `set.json`,\n`cases.jsonl` and every golden field. This covers two things it does not: what\nan arriving item maps onto, and how the four formats break.\n\n## What an import fills in\n\nOn the case:\n\n| field | from the source | when it is missing |\n|---|---|---|\n| `qid` | their id, if they gave one, prefixed with the set name | derive from the question: a slug of its first words plus a counter. Stable, because scores are keyed on it |\n| `question` | the question text, byte for byte | it is not a case. Do not reconstruct a question from a criterion |\n| `questionSha` | never from the source | stamped at conversion by `import_cases.py --stamp` |\n| `split` | rarely present | you choose, and freeze it at import |\n| `source` | how it arrived: the filename, or the log query | say `unknown` rather than guessing a provenance |\n| `golden` | see the classification table in `SKILL.md` | absent. A case with no golden is legitimate |\n| `expectedEntities` | almost never present | leave it out. Guessing which fields an answer needs invents a retrieval expectation nobody stated, and it scores as a retrieval miss forever. The one exception is a key you derived yourself (`SKILL.md`, Deriving a key yourself): then you are not guessing, you are recording what you used |\n\n`expectedEntities` is the one most worth leaving empty. A wrong `required` id\ncannot be delivered by any run, so it reads as a model failure on every case\nit touches: five copied ids cost a real set two days.\n\nOn `set.json`: `name`, `description`, `datasetVersion: 1`,\n`targetModelPath`, `targetPackage` (the package under test -- it arms the\nguard that refuses a \"truth\" server also serving it), and a `sourceNote` saying\nwhere the questions came from and what shape they arrived in. `truthPackage` is\nusually absent at import, and until it exists no golden can reach `verified`;\n`verify_goldens.py --promote` is what takes it there afterwards. `init_truth_package.py` in\n`skill:eval-answer` scaffolds one.\n\n## Their field names will not be your field names\n\nAn arriving JSONL is somebody else's schema. Map it explicitly rather than\ntrusting a name that looks familiar, and write down the mapping you used in\n`sourceNote`. Names seen in real sets:\n\n| theirs | usually means | trap |\n|---|---|---|\n| `prompt`, `query`, `input`, `nl_question` | the question | `query` is the trap: in half of these it is the SQL or Malloy they ran, not the question |\n| `answer`, `expected`, `output`, `ground_truth` | a golden value, prose, or both mixed in one string | a paragraph under `answer` is criteria, not a value. Classify it, do not store it as a number |\n| `sql`, `malloy`, `gold_query` | their derivation | run it (`SKILL.md` step 3). This is the field that upgrades a typed number into something checkable |\n| `criteria`, `rubric`, `assertions`, `must_include` | prose criteria | apply the query test in `SKILL.md` step 4 to EACH one, not to the field |\n| `id`, `case_id`, `uuid` | their id | keep it, prefixed. Two sets from one customer collide otherwise |\n| `difficulty`, `category`, `tags` | their own labels | keep as-is on the case for slicing. Never let one become `split` |\n\nA field you cannot map is a question for its author. Keep it verbatim under a\n`sourceFields` object on the case rather than discarding it or forcing it into\na field it does not mean.\n\n## The four formats\n\n**JSONL.** One object per line, and the easy one. The failures are all in the\nmapping above, plus two mechanical ones: a trailing incomplete line, and a\n`\\n` inside a question that a naive line split breaks. Parse it as JSON per\nline, and count the lines you produced against the lines they sent. Report the\ncount in the import summary: an import that silently dropped 3 of 50 is a\nmeasurement on 47 cases claiming to be one on 50.\n\n**CSV or a spreadsheet export.** Questions contain commas, quotes and newlines,\nso use a real CSV reader, never a split on `,`. Watch for a header row that is\nnot row one (an exported sheet often has a title and a blank line above it), for\nmerged cells arriving as empty strings that belong to the row above, and for a\nnumber that arrived as text with a thousands separator or a currency symbol. A\nnumber you cannot parse cleanly is a string; keep it as their text and say so,\nrather than reading `1,234` as `1.234` or as `1234` without checking.\n\n**A markdown doc or an email thread.** The questions are prose among other\nprose, so the hard part is deciding what IS a question. Rules that hold up:\na heading or a numbered list item is usually a case boundary; a sentence\nending in a question mark inside a paragraph about something else usually is\nnot. Criteria attached to a question tend to follow it as a bullet list or a\n\"should\" sentence. Quote a boundary you are unsure of and ask, rather than\nsplitting on your best guess: a question invented by a bad split is\nindistinguishable, later, from one a human asked. Nothing in this format is\nbyte-clean, which makes the verbatim copy in `as-received/` load-bearing.\n\n**A pull from production logs.** The best source, because real traffic asks\nwhat people actually ask, and the messiest. Three things to do:\nde-duplicate near-identical prompts before you import 40 of one question;\nstrip the parts that are not the question (a system preamble, a UI-injected\nscope line, a pasted table); and keep the trace or request id on the case as\n`source`, so a case can be taken back to the session it came from. Almost\nnone of these arrive with a golden, which is fine: bare questions are a\ncoverage measurement. Where the log also holds the query the agent ran, that\nis NOT a golden. It is what an unevaluated agent did, and importing it as a\nkey scores the model against its own past behavior.\n\n## A worked line\n\nTheirs:\n\n```json\n{\"case_id\": \"q-014\", \"prompt\": \"How did denim sell last quarter versus the one before?\",\n \"sql\": \"SELECT ...\", \"answer\": \"Up 12.4% to 1.83M. Should break out by channel.\",\n \"difficulty\": \"hard\"}\n```\n\nYours, after applying step 3 and step 4:\n\n```json\n{\"qid\": \"ecom-q-014\", \"question\": \"How did denim sell last quarter versus the one before?\",\n \"questionSha\": \"<stamped>\", \"split\": \"dev\", \"source\": \"questions.jsonl\",\n \"golden\": {\"status\": \"provisional\", \"kind\": \"scalar\", \"value\": 1830000,\n            \"canonicalQuery\": \"SELECT ...\", \"verifiedBy\": \"authored_query\",\n            \"rubric\": \"Reports the quarter-over-quarter change for denim, and breaks the figure out by channel.\"},\n \"sourceFields\": {\"difficulty\": \"hard\"}}\n```\n\nAnd one that arrived as criteria alone, with no number anywhere:\n\n```json\n{\"qid\": \"ecom-q-021\", \"question\": \"Which channels are underperforming?\",\n \"questionSha\": \"<stamped>\", \"split\": \"dev\", \"source\": \"questions.jsonl\",\n \"golden\": {\"status\": \"verified\", \"kind\": \"criteria\",\n            \"verifiedBy\": \"authored_criteria\",\n            \"rubric\": \"Names the channels and says what it measured underperformance against. Does not use list price.\",\n            \"mustNotUse\": [\"retail_price\"]}}\n```\n\nNo query settles \"underperforming\", so there is nothing to derive and nothing\nthat can be numerically wrong: the clauses are the whole key, and this case\nscores on the first run.\n\n`criteria` and `unanswerable` are the two kinds an import may mark `verified`,\nand they arrive looking alike. A criterion reading \"PASS: a refusal that names\nthe missing data\" belongs to the second: the key is that the data is absent,\nso `kind: unanswerable`, and filing it as `criteria` beside a value would make\na correct refusal fail.\n\nWhat happened to that one `answer` string: the number became a provisional\nvalue, checkable because they sent the query that produced it; \"should break\nout by channel\" is a shape nothing can settle with a query, so it became\nrubric prose and scores on day one; and \"Up 12.4%\" is a second figure the\nrubric now has to state consistently with the value, which\n`verify_goldens.py` reads the accepting clause for."
+      body: `<!-- What an arriving item maps to, and how to read the four formats questions actually arrive in. The file shapes themselves are in eval-answer/reference/ledger-schema.md; this is only what is specific to an import. -->
+
+# Reading an arriving question list
+
+\`reference/ledger-schema.md\` in \`skill:eval-answer\` defines \`set.json\`,
+\`cases.jsonl\` and every golden field. This covers two things it does not: what
+an arriving item maps onto, and how the four formats break.
+
+## What an import fills in
+
+On the case:
+
+| field | from the source | when it is missing |
+|---|---|---|
+| \`qid\` | their id, if they gave one, prefixed with the set name | derive from the question: a slug of its first words plus a counter. Stable, because scores are keyed on it |
+| \`question\` | the question text, byte for byte. One exception: a source hard-wrapped at a column width cannot be one line byte for byte, so a line break inside a question becomes one space, the seal is on the unwrapped text, and \`sourceNote\` says so | it is not a case. Do not reconstruct a question from a criterion |
+| \`questionSha\` | never from the source | stamped at conversion by \`import_cases.py --stamp\` |
+| \`split\` | rarely present | you choose, and freeze it at import |
+| \`source\` | how it arrived: the filename, or the log query | say \`unknown\` rather than guessing a provenance |
+| \`golden\` | see the classification table in \`SKILL.md\` | absent. A case with no golden is legitimate |
+| \`expectedEntities\` | almost never present | leave it out. Guessing which fields an answer needs invents a retrieval expectation nobody stated, and it scores as a retrieval miss forever. The one exception is a key you derived yourself (\`SKILL.md\`, Deriving a key yourself): then you are not guessing, you are recording what you used |
+
+\`expectedEntities\` is the one most worth leaving empty. A wrong \`required\` id
+cannot be delivered by any run, so it reads as a model failure on every case
+it touches: five copied ids cost a real set two days.
+
+On \`set.json\`: \`name\`, \`description\`, \`datasetVersion: 1\`,
+\`targetModelPath\`, \`targetPackage\` (the package under test -- it arms the
+guard that refuses a "truth" server also serving it), and a \`sourceNote\` saying
+where the questions came from and what shape they arrived in. \`truthPackage\` is
+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.
+
+## Their field names will not be your field names
+
+An arriving JSONL is somebody else's schema. Map it explicitly rather than
+trusting a name that looks familiar, and write down the mapping you used in
+\`sourceNote\`. Names seen in real sets:
+
+| theirs | usually means | trap |
+|---|---|---|
+| \`prompt\`, \`query\`, \`input\`, \`nl_question\` | the question | \`query\` is the trap: in half of these it is the SQL or Malloy they ran, not the question |
+| \`answer\`, \`expected\`, \`output\`, \`ground_truth\` | a golden value, prose, or both mixed in one string | a paragraph under \`answer\` is criteria, not a value. Classify it, do not store it as a number |
+| \`sql\`, \`malloy\`, \`gold_query\` | their derivation | run it (\`SKILL.md\` step 3). This is the field that upgrades a typed number into something checkable |
+| \`criteria\`, \`rubric\`, \`assertions\`, \`must_include\` | prose criteria | apply the query test in \`SKILL.md\` step 4 to EACH one, not to the field |
+| \`id\`, \`case_id\`, \`uuid\` | their id | keep it, prefixed. Two sets from one customer collide otherwise |
+| \`difficulty\`, \`category\`, \`tags\` | their own labels | keep as-is on the case for slicing. Never let one become \`split\` |
+
+A field you cannot map is a question for its author. Keep it verbatim under a
+\`sourceFields\` object on the case rather than discarding it or forcing it into
+a field it does not mean.
+
+## The four formats
+
+**JSONL.** One object per line, and the easy one. The failures are all in the
+mapping above, plus two mechanical ones: a trailing incomplete line, and a
+\`\\n\` inside a question that a naive line split breaks. Parse it as JSON per
+line, and count the lines you produced against the lines they sent. Report the
+count in the import summary: an import that silently dropped 3 of 50 is a
+measurement on 47 cases claiming to be one on 50.
+
+**CSV or a spreadsheet export.** Questions contain commas, quotes and newlines,
+so use a real CSV reader, never a split on \`,\`. Watch for a header row that is
+not row one (an exported sheet often has a title and a blank line above it), for
+merged cells arriving as empty strings that belong to the row above, and for a
+number that arrived as text with a thousands separator or a currency symbol. A
+number you cannot parse cleanly is a string; keep it as their text and say so,
+rather than reading \`1,234\` as \`1.234\` or as \`1234\` without checking.
+
+**A markdown doc or an email thread.** The questions are prose among other
+prose, so the hard part is deciding what IS a question. Rules that hold up:
+a heading or a numbered list item is usually a case boundary; a sentence
+ending in a question mark inside a paragraph about something else usually is
+not. Criteria attached to a question tend to follow it as a bullet list or a
+"should" sentence. Quote a boundary you are unsure of and ask, rather than
+splitting on your best guess: a question invented by a bad split is
+indistinguishable, later, from one a human asked. Nothing in this format is
+byte-clean, which makes the verbatim copy in \`as-received/\` load-bearing.
+
+**A pull from production logs.** The best source, because real traffic asks
+what people actually ask, and the messiest. Three things to do:
+de-duplicate near-identical prompts before you import 40 of one question;
+strip the parts that are not the question (a system preamble, a UI-injected
+scope line, a pasted table); and keep the trace or request id on the case as
+\`source\`, so a case can be taken back to the session it came from. Almost
+none of these arrive with a golden, which is fine: bare questions are a
+coverage measurement. Where the log also holds the query the agent ran, that
+is NOT a golden. It is what an unevaluated agent did, and importing it as a
+key scores the model against its own past behavior.
+
+## A worked line
+
+Theirs:
+
+\`\`\`json
+{"case_id": "q-014", "prompt": "How did denim sell last quarter versus the one before?",
+ "sql": "SELECT ...", "answer": "Up 12.4% to 1.83M. Should break out by channel.",
+ "difficulty": "hard"}
+\`\`\`
+
+Yours, after applying step 3 and step 4:
+
+\`\`\`json
+{"qid": "ecom-q-014", "question": "How did denim sell last quarter versus the one before?",
+ "questionSha": "<stamped>", "split": "dev", "source": "questions.jsonl",
+ "golden": {"status": "provisional", "kind": "scalar", "value": 1830000,
+            "canonicalQuery": "SELECT ...", "verifiedBy": "authored_query",
+            "rubric": "Reports the quarter-over-quarter change for denim, and breaks the figure out by channel."},
+ "sourceFields": {"difficulty": "hard"}}
+\`\`\`
+
+And one that arrived as criteria alone, with no number anywhere:
+
+\`\`\`json
+{"qid": "ecom-q-021", "question": "Which channels are underperforming?",
+ "questionSha": "<stamped>", "split": "dev", "source": "questions.jsonl",
+ "golden": {"status": "verified", "kind": "criteria",
+            "verifiedBy": "authored_criteria",
+            "rubric": "Names the channels and says what it measured underperformance against. Does not use list price.",
+            "mustNotUse": ["retail_price"]}}
+\`\`\`
+
+No query settles "underperforming", so there is nothing to derive and nothing
+that can be numerically wrong: the clauses are the whole key, and this case
+scores on the first run.
+
+\`criteria\` and \`unanswerable\` are the two kinds an import may mark \`verified\`,
+and they arrive looking alike. A criterion reading "PASS: a refusal that names
+the missing data" belongs to the second: the key is that the data is absent,
+so \`kind: unanswerable\`, and filing it as \`criteria\` beside a value would make
+a correct refusal fail.
+
+What happened to that one \`answer\` string: the number became a provisional
+value, checkable because they sent the query that produced it; "should break
+out by channel" is a shape nothing can settle with a query, so it became
+rubric prose and scores on day one; and "Up 12.4%" is a second figure the
+rubric now has to state consistently with the value, which
+\`verify_goldens.py\` reads the accepting clause for.`
     },
     {
       name: "eval-improve",
@@ -320139,7 +320677,7 @@ reply, ONLY this JSON object:
       description: "Decide whether ONE answer matches its golden, and say whether you believe the golden. Read this before emitting any verdict. Covers containment, column pairing, near_match, refusals, and the gold_status judgement. Use when scoring an attempt in an evaluation run; never to conduct a run (eval-loop), diagnose a failure (eval-diagnose) or edit a model (eval-improve).",
       body: `# The judge
 
-JUDGE_VERSION: 5
+JUDGE_VERSION: 6
 
 This skill IS the judge. One fresh judge subagent is spawned per attempt, with
 this skill installed in its workspace and the case materials in its prompt. It
@@ -320252,6 +320790,27 @@ Output, exactly this shape:
    reading that produced it, that is \`no_match\`. Use \`near_match\` only when you
    can name the rubric clause that makes the difference defensible.
 
+   **A rubric clause cannot make a wrong VALUE defensible, and a clause that
+   tries is a defect in the rubric rather than a licence to you.** \`near_match\`
+   turns on the answer being right under a reading the QUESTION allows -- a tie
+   broken the other way, a grain the question left open, a basis the question
+   never fixed. It does not turn on the answer being transparent about how it
+   got a figure the question did not ask for. Those two look alike in a rubric
+   and are opposites in a report: one is a number a reader can act on, the
+   other is a number a reader would act on wrongly. Naming the method makes a
+   wrong figure DIAGNOSABLE, which is worth having, and it is not partial
+   credit.
+
+   The test, before you write \`near_match\` on a case with a value: would a
+   reader who acted on this figure be wrong? If yes, it is \`no_match\` however
+   plainly the answer explained itself, and however the rubric is worded. Say
+   in \`why\` that you are overriding a rubric clause, so the clause gets fixed.
+   This rule exists because a set shipped one: a question asked for sales over
+   the company's season, the answer gave the meteorological window 25% lower
+   and said which window it used, and a clause granting \`near_match\` for a
+   stated window kept a materially wrong answer out of the pass rate
+   entirely -- the arm reported 100%.
+
    It is a third outcome because as a pass it was a large share of the measured
    noise: the same unchanged answer reads \`match\` in one run and \`near_match\`
    in the next, and the pass rate moves although nothing did. A verdict whose
@@ -320298,6 +320857,29 @@ Output, exactly this shape:
    total; the question had never asked for one. A rubric that means "campaign
    total only" must say so as \`REQUIRED\`, and the question should say so too.
 
+### Rubric markers
+
+A case rubric marks its alternate readings and disclosures with the words
+below, and each word fixes the verdict. Apply them as written; do not re-weigh
+a reading the rubric has already classified. (\`reference/writing-rubrics.md\`
+is where authors are told to use them; this table is the judge's half.)
+
+| Marker | Verdict | Meaning |
+|---|---|---|
+| \`PREFERRED\` | \`match\` | The reading the golden encodes. |
+| \`ACCEPT\` | \`match\` | Equally right: a different but faithful route to the same claim. Check the figure against the golden the way the clause says to. |
+| \`DIVERGENT\` | \`near_match\` | Defensible and not what was asked for. Never \`no_match\`, however clearly the answer committed to it. |
+| \`WRONG\` | \`no_match\` | Plausible and incorrect; the clause usually names the trap. |
+| \`REQUIRED\` | omitted: \`no_match\` | A disclosure without which the number misleads. |
+| \`CREDITED\` | omitted: \`match\` | Context a good analyst adds; its absence costs nothing. |
+
+Measured on an unchanged answer, rubric and golden: an answer whose
+recommended figure the rubric marked \`DIVERGENT\` scored \`near_match\` under
+one judge and \`no_match\` under the next, because the judge had never been
+told what the word meant and weighed the commitment instead. An unmarked
+clause is \`CREDITED\` (the author's bug, not yours to repair by inventing a
+requirement).
+
 ### Anchors
 
 - **match**: question "total sales by category"; golden 8 rows
@@ -320543,6 +321125,14 @@ Rules that follow from this:
   must say "for the campaign as a whole". If it does not, the rubric must accept
   a correct figure at any stated grain (judge rule 11). A rubric that quietly
   assumes the golden's grain fails correct answers.
+- **Fix the cardinality in the question, or accept any prefix in the rubric.**
+  "The most", "the top ones", "most often" name no N; the truth query needs
+  one, so the golden fixes 10 or 20 or 25 and an answer that shows five
+  correct rows reads as missing fifteen. Measured over one 24-case set, that
+  class alone produced a \`no_match\`, a flip and two \`near_match\` verdicts on
+  answers whose rows were a correct prefix of the golden's. Either write the N
+  into the question, or mark the rubric \`ACCEPT the first N of the golden's
+  order for any N of at least five\`, and say which order the golden is in.
 - **A right value plus a missing \`CREDITED\` disclosure is a \`match\`.** Not a
   near match. Do not deduct for it.
 - **\`DIVERGENT\` is about definitions, not arithmetic.** A clause permitting a
@@ -320915,11 +321505,19 @@ the run measure something other than what it names:
    first time somebody tidies up; the set, the run directory and the write-up
    belong in git beside the model.
 
-2. The server must be up with retrieval tracing on, so a call's ranked results
-   can be recovered afterwards (open-source Publisher: \`PUBLISHER_MCP_TRACE=retrieval\`).
-   Confirm a trace lookup is available (absent means tracing is off).
-   Refuse to start a scored run without it: failures without traces cannot be
-   attributed.
+2. The server must be up. Where your host offers retrieval tracing, turn it on
+   and confirm a trace lookup answers, so a call's ranked results can be
+   recovered afterwards.
+
+   **Open-source Publisher has none.** \`PUBLISHER_MCP_TRACE=retrieval\` is set by
+   \`serve.py\` and read by nothing: the trace store was written and never merged,
+   so there is no trace tool and \`traceId\` is null on every local attempt. This
+   does not block a scored run, because attribution never depended on it:
+   \`rankedSummary\` is copied onto the \`tool_call\` event at capture, precisely so
+   the evidence survives without a store. So do not refuse a local run for want
+   of tracing -- an earlier version of this rule did, and it refused every local
+   run there has ever been. Refuse one whose \`tool_call\` events carry no
+   \`rankedSummary\`, which is what attribution actually reads.
 
 3. Health-check: your host's status check until it reports serving, and inspect
    \`loadErrors\`. A dead database that still answers HTTP is an environment
@@ -321087,6 +321685,13 @@ conductor. Do not:
 
 - The model is the only thing improve edits. No question text, qids, or
   expected values in any name, doc, or comment.
+- **You are measuring a model, not reviewing this harness.** Read a script when
+  a number you have to report cannot be explained otherwise, and stop there. Do
+  not audit the scripts, propose fixes to them, or hand back tooling critique
+  in place of a result -- a run that ends in harness feedback has not answered
+  the question it was asked. A defect that changed a number gets one sentence
+  in the report; a defect that changed nothing gets one line in chat, once.
+  Fixing it is a different task, and the user starts it.
 - When the environment misbehaves, stop. Never diagnose a sick system. The
   harness is part of the environment: a known-broken measurement does not
   become quotable by being finished. Measured against this directive, an arm
@@ -321879,6 +322484,10 @@ check, a judge, and a conformant \`events.jsonl\`.
 #    if it does not reach \`ready\`: the sync is lazy, so without it the first
 #    cases are answered LEXICALLY and the run reports that as the model's
 #    number.
+#    Semantic retrieval needs EMBEDDING_API_KEY in the server's environment
+#    (the Publisher does not read OPENAI_API_KEY); without it every ranking is
+#    lexical, the warm-up reports \`cooldown\`, and the provider's own error is
+#    only in publisher.log (grep Embedding).
 python3 skills/eval-loop/scripts/serve.py --publisher-dir <publisher>/packages/server \\
   --server-root <root> --port 4811 --mcp-port 4040 --trace-retrieval \\
   --warm-retrieval --environment <env> --package <pkg> \\
@@ -322047,6 +322656,30 @@ one exception is anything that qualifies THIS run's number -- a truncated
 attempt, a contaminated one, an unestablished answer key -- which the "Eval
 failures" section exists for.
 
+**Do not audit the harness. You were asked to measure a model.** This is the
+most common way this job goes wrong, and it does not look like going wrong: a
+run turns up something odd in a script, the odd thing is genuinely a bug, and
+the reply comes back as a critique of the tooling with the model's score
+somewhere underneath. The reader asked what their model scored. Answer that.
+
+So, unless the user asked you to work on the harness:
+
+- Do not read harness source to satisfy your own curiosity about a number.
+  Read it when a number you must report cannot be explained any other way, and
+  stop when it can.
+- Do not propose harness fixes, refactors, flags or "while I was in there"
+  improvements. Not in the report, not in the chat reply.
+- When a harness defect DID change this run's number, the report gets one
+  sentence: what the number should be and why. Not the mechanism, not the
+  file, not the fix.
+- Keep a defect that changed nothing out of the report entirely. Mention it
+  once in chat, in a line, and let the user decide whether they want it
+  chased.
+
+A harness bug you found and did not chase is not a loose end. It is the job
+being done. If the user wants it fixed they will say so, and then it is a
+different task with its own turn.
+
 ## Step 1: build the artifacts, before writing a word
 
 \`\`\`bash
@@ -322085,6 +322718,29 @@ not in \`~/Downloads\`, both of which have lost a findings document before.
 from the console.** A figure retyped from scrollback is a figure nobody can
 check, and the console rounds.
 
+### Keep it under a page and a half
+
+**Budget: about 80 lines, and 120 is the ceiling for a run with several
+distinct failures.** Reports have shipped at 200 and the length is not
+thoroughness -- it is the artifact links restated as prose, the cascade
+explained twice, and a paragraph apologising for a figure nobody disputed.
+A reader who wants the detail opens the case matrix, which is why step 1 builds
+it. What cannot be recovered from the artifacts is your judgement: what broke,
+why, and what to do. Spend the lines there.
+
+What earns its place: the headline, one row per case, one short entry per
+failure, the retrieval numbers, and the next steps. What does not: restating a
+number you already gave, explaining what a cascade is before showing it,
+defending a decision nobody questioned, or any section whose content is that
+nothing happened -- except "Eval failures", where "None." is the point.
+
+**Being brief is not being terse with the vocabulary.** The reader does not
+know what \`near_match\`, a cluster, recall or a holdout is, so the first time
+one appears, say what it means in the same sentence -- "\`near_match\`, which is
+excluded from the pass rate" -- and then use it. Cutting the explanations is
+how a short report becomes an unreadable one; cutting the restatements is how
+it becomes a good one.
+
 ### The template
 
 \`\`\`markdown
@@ -322098,7 +322754,7 @@ check, and the console rounds.
 - Target \`<env>/<package>\`, model \`<modelPath>\`, pinned \`<modelSha or targetVersion>\`
 - Answerer \`<model>\`, judge \`<model>\`, cap \`<maxTurns>\` turns
 - Steps run: scrape/run, eval<, diagnose><, improve>
-- Cost $X answerer + $Y judge
+- Cost $X answerer + $Y judge, N turns median / N p90, N entities delivered per answer
 
 ## The result
 
@@ -322109,9 +322765,15 @@ check, and the console rounds.
 
 [case matrix](<url>) - [aggregate tables](<url>)
 
-## Retrieval and coverage
+## Coverage, retrieval, accuracy, cost
 
-Covered? -> Retrieved? -> Correct?, with the per-arm numbers under each.
+**Coverage N of M** -- how many questions the model can express an answer to at
+all. **Entity recall N%** -- one number, first, before the cascade. It is the share
+of the entities an answer needed that retrieval actually handed the agent, and
+it is the headline of this section for the same reason the pass rate is the
+headline of the last one. Then the cascade: Covered? -> Retrieved? -> Correct?,
+with the per-arm numbers under each. Say in one clause what recall counts, then
+give the number.
 
 ## Model failures
 
@@ -322140,10 +322802,10 @@ these in order and put every one that fires into the list, with its command:
 
 | If the run shows | Then the next step is |
 |---|---|
-| \`coverage: unmeasured\` | run \`check_coverage.py --set <set> --model <pkg> --out coverage.json\`, then re-run with \`--coverage\` so it charges the failures |
+| \`coverage: unmeasured\` | the run was given \`--no-coverage\`, or the measurement failed and said so. It is measured by default, so say in "Eval failures" that this score cannot tell a model gap from a bad answer, and re-run without the flag |
 | \`goldenCheck: skipped\` or the set names no \`truthPackage\` | build one with \`init_truth_package.py\`; until then the goldens were derived through the model under test and certify themselves |
 | any golden still \`provisional\` | re-derive and \`verify_goldens.py --promote\` |
-| a stale entity name warning | fix \`expectedEntities\`; it scores as a retrieval miss on every run until you do |
+| a stale entity name warning | fix \`expectedEntities\`; it scores as a retrieval miss on every run until you do. A next step, not a section: it goes in this list and nowhere else in the report |
 | a passing case with recall below 1.0 | check whether \`required\` over-specifies one path |
 | \`truncated\` non-empty | re-run those cases at a higher cap with \`--from\` |
 | diagnose did not run | run it, or say the failures have no owner yet |
@@ -322186,8 +322848,23 @@ wrong answer. One entry each: what the answer said, what was right, and the
 mechanism in one sentence. Do not write a cluster id here; write what it got
 wrong.
 
-**Eval failures** are everything that stopped the run measuring the model.
-Report every one that occurred, with its count and its qids, and say plainly
+**Eval failures** are the things that stopped the run measuring the model, and
+**only** those. The test is one question: *did this cost a verdict, or make one
+untrustworthy?* If no, it does not appear in the report at any length.
+
+That rules out most of what is tempting to put here, and all of it has been put
+here on a real run: a \`-dirty\` model pin, a stale-entity-name warning that cost
+no case, a defect you hit in the harness and worked around, a setup step that
+took two tries, anything you would open with "worth knowing, though it changes
+no verdict". A reader wants to know what their model scored. Harness defects are
+real and belong in a harness issue, filed against the harness -- that is the
+skill's opening rule, and this section is where it gets broken.
+
+The section is usually two words. "**None.**" is a complete and good answer, and
+a reader who sees it learns exactly what they need to. Do not pad it into a
+paragraph explaining the absence.
+
+Report every one that DID occur, with its count and its qids, and say plainly
 that these are NOT evidence about the model:
 
 | What happened | How it reads in the ledger | Who fixes it |
@@ -322206,11 +322883,32 @@ harness prints \`INCOMPLETE\` and withholds the percentage; the report does the
 same. Give the counts and the re-run command instead of a number with a caveat,
 because the number is what gets repeated and the caveat is what gets dropped.
 
-## Retrieval and coverage belong in every report
+## The four measurements, and why a report carries all of them
+
+A pass rate says an answer was wrong. It does not say where, and on its own it
+makes every failure look like the model's. A run measures four things, in this
+order, and each one tells you whether the next is even a fair question:
+
+| | Measures | A failure here means |
+|---|---|---|
+| **a. Coverage** | can the data and the model express an answer at all | nothing downstream was winnable. Fix the model |
+| **b. Retrieval** | did \`get_context\` hand the agent the entities it needed | the model has it and the agent never saw it: the docs, or the search wording |
+| **c. Accuracy** | did the agent get the answer right | it had what it needed and still missed: the agent, or a doc that misleads |
+| **d. Cost** | dollars, turns, wall-clock, entities per answer | it works and cannot be afforded, which is its own kind of not working |
+
+**Coverage first, and a report without it is incomplete.** A model that cannot
+express an answer can never succeed at that question, so a pass rate quoted
+without coverage cannot distinguish a bad model from an unanswerable set.
+\`run_baseline.py\` measures it by default; if a run skipped it, say so in
+"Eval failures" and treat the score as provisional.
+
+**Cost is a result, not an aside.** Report dollars, the turn and call counts,
+and the entity payload per answer. An agent that answers correctly in 40 turns
+and 75 delivered entities per question is a different product from one that
+does it in 8 and 5, and only the report says which you have.
 
-A pass rate says an answer was wrong. It does not say WHERE, and the three
-metrics that do are already in the run summary and the notebook. Report them,
-because a report that omits them makes every failure look like the model's:
+Report them all, because a report that omits them makes every failure look
+like the model's:
 
 **Copy the cascade the run printed. Do not re-derive it.** \`cascade_lines()\`
 in \`run_baseline.py\` already renders every rung, and it carries one field a
@@ -322426,6 +323124,7 @@ This table is a catalogue of what exists, not of what is loaded. A host that ins
 | \`skill:malloy-notebooks\` | Building Malloy notebooks (.malloynb) |
 | \`skill:malloy-analysis-report\` | Combining validated queries into a notebook report or dashboard |
 | \`skill:malloy-analysis-pitfalls\` | Checking a query and its results before presenting an answer |
+| \`skill:malloy-source-unreachable\` | A source is missing from discovery, or a query was refused with a 404 or 403 |
 | \`malloy-notebook-chat\` | The chat is bound to a notebook or saved report; answer from its cells. Ships in \`analysis\`. |
 | \`skill:malloy-phrase-detection\` | Turning a plain-English question into search targets for the context tool |
 
@@ -322482,7 +323181,7 @@ Call \`search_malloy_docs\` with your question. Use \`skill:malloy-patterns\` to
     },
     {
       name: "malloy-analysis",
-      description: "The workflow for answering a data question over a Malloy semantic model - a metric, breakdown, trend or chart - from get_context discovery through execute_query to verified delivery.",
+      description: "Read before your first get_context call on any business or data question. The required workflow, not background: which source, which rows, how to verify. Skipping it causes confident wrong answers.",
       body: `# Malloy analysis workflow
 
 > **Tool names** are written bare here - \`get_context\`, \`execute_query\`, \`search_malloy_docs\`. The exact prefixed name depends on the host surface; match each against the tools you actually have.
@@ -322891,6 +323590,13 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
 
 ## Build sequence
 
+0. **CHECK THE PACKAGE CAN SERVE A DASHBOARD AT ALL.** If its root holds an \`index.malloy\`, that
+   file is the package's surface, and a dashboard's file is not something it can \`export\`, so the
+   dashboard you are about to write will compile and then be withheld. Every package made by the
+   scaffolder has that file, so this is the common case, not the corner one. Serving dashboards
+   there means declaring an \`explores\` in \`publisher.json\` naming \`index.malloy\` and every dashboard
+   file, which overrides the convention. Settle that first: it is a different curation shape for the
+   package, not a line to add at the end. See "Read the lint" for the warning it produces otherwise.
 1. **READ THE MODEL FIRST.** Get the real source, view, dimension, and given names from the package:
    \`get_context\` if you have it, otherwise the REST model endpoint or the \`.malloy\` files.
    Never guess a name. A guessed field in a query fails the whole package load, not just that one
@@ -322925,8 +323631,11 @@ Scanned at a glance is a dashboard; read top to bottom is a notebook.
    include wants \`"scope": "package"\`**, which recompiles every file as saved: \`file\` only checks the
    one you are editing, so renaming a source in \`_shared.malloy\` passes it while breaking every
    dashboard that imports it. A clean compile is not a working dashboard: some tag mistakes surface
-   at step 6, and some only when you look at the page in step 7. (The third scope, \`append\`, is the
-   default and is what a not-yet-saved file gets.)
+   at step 6, and some only when you look at the page in step 7. **A not-yet-saved dashboard wants
+   \`"scope": "file"\` too**, not the default: a dashboard file opens with an \`import\`, and the
+   default \`append\` scope refuses one, so the new-file case fails on the import and again on the
+   path that does not exist yet. \`append\` is for a fragment checked against a model that is
+   already on disk, which a dashboard file is not.
 6. **SAVE IT, RELOAD, AND READ THE MANIFEST AND THE WARNINGS.** \`reload_package\`, or
    \`GET …/packages/<pkg>?reload=true\`. Check the status the reload returns as well as the warnings:
    a 424 means the package did not load and your edit is not live. **The \`warnings\` key is absent
@@ -323301,8 +324010,8 @@ Package warnings after a reload are the dashboard's test suite. Fix all of them:
 Findings carry a \`severity\`, but \`warn\` is the ordinary default and tells you nothing about how bad
 one is. Read the text, not the severity and not the count. One message is worth recognising because
 it changes what the rest of the list means: **"Dashboard lint stopped early, so this list is
-incomplete"**. A dashboard withheld from \`explores\` also loses its own findings, so a short list for a
-withheld file is not a clean bill of health.
+incomplete"**. A dashboard withheld from the package's surface also loses its own findings, so a
+short list for a withheld file is not a clean bill of health.
 
 **Read the status the reload itself returns, not the listing.** One dashboard that fails to compile
 fails the whole package load, and the reload answers **424** with the compile error. A package that
@@ -323317,11 +324026,22 @@ at all appears there too, without \`stale\`, and is absent from the listing enti
 
 If the reload is 200 and the others are listed but yours is not, discovery skipped the file instead,
 usually a missing or misspelled \`# artifact\` tag, which is the same mechanism that deliberately skips
-an untagged shared include. There is a second cause if the package's \`publisher.json\` carries an
-\`explores\` list: a dashboard whose file is missing from it is withheld rather than served, and the
-warning says so and names the fix. The list is what matters, not the \`queryableSources\` setting, which
-is \`declared\` by default; a package with no \`explores\` list withholds nothing. Where there is one, a
-\`suggest\` source has to be queryable as well as resolvable, so it needs to be on the list too.
+an untagged shared include. There is a second cause whenever the package has a curated surface: a
+dashboard whose file is off it is withheld rather than served, and the warning says so and names the
+fix. A package has a surface in two ways, and the second is easy to miss because no manifest field
+records it:
+
+- the package's \`publisher.json\` carries an \`explores\` list, and the dashboard's file is not on it;
+- the package root holds an **\`index.malloy\`**, which IS the surface. This bites in both
+  directions, and a dashboard's file is not something an \`index.malloy\` exports either way: adding
+  that file to a package that has dashboards withholds every one of them, and adding a dashboard to
+  a package that already has one (every scaffolded package does) means it is never served. The fix
+  is the same in both directions, and it is not an edit to \`index.malloy\`: declare an \`explores\` in
+  \`publisher.json\` naming \`index.malloy\` and every dashboard file.
+
+Either way the surface is what matters, not the \`queryableSources\` setting, which is \`declared\` by
+default; a package with neither withholds nothing. Where there is a surface, a \`suggest\` source has
+to be queryable as well as resolvable, so it needs to be reachable through it too.
 
 **A clean reload is not proof the tags are right.** The checks above read names and resolve them; the
 separate warning for a tag that does not _parse_ is syntax only: it carries no
@@ -323818,7 +324538,42 @@ view: overview is {
     {
       name: "malloy-html-data-app-embedding",
       description: "Embed an in-package HTML data app into a host page or another application, including auto-sizing and auth. Read when embedding a Publisher page via Publisher.embed.",
-      body: '# Embedding an HTML Data App\n\n> `Publisher.embed(selector, { src })` drops a package page into a host page as a sandboxed, auto-resizing iframe. Same-origin embeds authenticate with the browser\'s cookies; cross-origin embeds need a signed token.\n\n## The host-page pattern\n\n```html\n<script src="https://your-publisher/sdk/publisher.js"></script>\n<div id="dashboard"></div>\n<script>\n  const handle = Publisher.embed("#dashboard", {\n    src: "https://your-publisher/environments/demo/packages/sales/index.html",\n  });\n  // handle.destroy() removes the iframe and detaches its listeners.\n</script>\n```\n\n`embed(selector, options)` returns `{ iframe, destroy() }`. Options: `src` (required), `token` (a signed token for cross-origin auth, appended as `embed_token`), `height` (omit to auto-size; a number is treated as pixels), and `allow` (the iframe permissions policy).\n\n## Sizing and the resize contract\n\nOmit `height` and the frame auto-sizes. The embedded page measures its real content height and posts a `publisher:resize` message to the host, which resizes the iframe and accepts that message only from the iframe it created. You write none of this; it ships in `/sdk/publisher.js`, so the embedded page only has to load that script.\n\nDo not rely on `body { min-height: 100vh }` to drive the frame height. The runtime deliberately measures the content\'s bottom edge, not the viewport, to avoid a grow-forever loop.\n\n## Auth\n\n- Same-origin or same-tenant: pass no token. The browser\'s cookies authenticate the iframe.\n- Cross-origin: mint a short-lived signed token server-side and pass it as `options.token`. The runtime appends it to the iframe URL as `embed_token`; the embedded page must read it (from `location.search`) and call `Publisher.setToken(token)`. Because it rides in the URL, it can land in browser history, Referer headers, and server logs, so keep it short-lived and scoped to that one embed, and never put a long-lived or admin token in client HTML.\n\n## Guardrails (v1)\n\n- The iframe is sandboxed (`allow-scripts allow-same-origin allow-forms`). Design for that: no top-level navigation, no popups.\n- Embedded author JavaScript runs with the viewing user\'s data authority, so treat everything under `public/` as strictly first-party code: do not load untrusted third-party scripts, and do not move query results off to other hosts. Tighter per-embed isolation is planned.'
+      body: `# Embedding an HTML Data App
+
+> \`Publisher.embed(selector, { src })\` drops a package page into a host page as a sandboxed, auto-resizing iframe. Same-origin embeds authenticate with the browser's cookies; cross-origin embeds need a signed token.
+
+> **A cross-origin embed also needs the server to permit it.** Publisher sends \`Content-Security-Policy: frame-ancestors 'self'\` by default, so a page embedded from another origin is refused by the browser and renders blank -- with nothing logged server-side, which makes it look like a broken page rather than a policy. The deployment must set \`PUBLISHER_FRAME_ANCESTORS\` to the host page's origin (space-separated for several, or \`*\` to allow any). Check this first when an embed is blank: the browser console names \`frame-ancestors\`.
+
+## The host-page pattern
+
+\`\`\`html
+<script src="https://your-publisher/sdk/publisher.js"></script>
+<div id="dashboard"></div>
+<script>
+  const handle = Publisher.embed("#dashboard", {
+    src: "https://your-publisher/environments/demo/packages/sales/index.html",
+  });
+  // handle.destroy() removes the iframe and detaches its listeners.
+</script>
+\`\`\`
+
+\`embed(selector, options)\` returns \`{ iframe, destroy() }\`. Options: \`src\` (required), \`token\` (a signed token for cross-origin auth, appended as \`embed_token\`), \`height\` (omit to auto-size; a number is treated as pixels), and \`allow\` (the iframe permissions policy).
+
+## Sizing and the resize contract
+
+Omit \`height\` and the frame auto-sizes. The embedded page measures its real content height and posts a \`publisher:resize\` message to the host, which resizes the iframe and accepts that message only from the iframe it created. You write none of this; it ships in \`/sdk/publisher.js\`, so the embedded page only has to load that script.
+
+Do not rely on \`body { min-height: 100vh }\` to drive the frame height. The runtime deliberately measures the content's bottom edge, not the viewport, to avoid a grow-forever loop.
+
+## Auth
+
+- Same-origin or same-tenant: pass no token. The browser's cookies authenticate the iframe.
+- Cross-origin: mint a short-lived signed token server-side and pass it as \`options.token\`. The runtime appends it to the iframe URL as \`embed_token\`; the embedded page must read it (from \`location.search\`) and call \`Publisher.setToken(token)\`. Because it rides in the URL, it can land in browser history, Referer headers, and server logs, so keep it short-lived and scoped to that one embed, and never put a long-lived or admin token in client HTML.
+
+## Guardrails (v1)
+
+- The iframe is sandboxed (\`allow-scripts allow-same-origin allow-forms\`). Design for that: no top-level navigation, no popups.
+- Embedded author JavaScript runs with the viewing user's data authority, so treat everything under \`public/\` as strictly first-party code: do not load untrusted third-party scripts, and do not move query results off to other hosts. Tighter per-embed isolation is planned.`
     },
     {
       name: "malloy-html-data-app-runtime",
@@ -324695,12 +325450,12 @@ Present coverage in this order:
     {
       name: "malloy-materialization",
       description: "Add and debug Malloy Persistence materializations in a package - persist an expensive source so queries read a pre-built table. Read this whenever the user wants to materialize a source, add a persist annotation, speed up a slow source, or asks why a persist source isn't building.",
-      body: "# Materialization (Malloy Persistence)\n\nMaterialize an expensive source once so queries read a **pre-built warehouse table** instead of recomputing it every time. You tag a source `#@ persist`, a materialization run builds it into a physical table, and queries against it are rewritten to read that table.\n\n> **The #1 gotcha, up front:** if a persist source isn't materializing, it is almost always one of two things - a `.malloy` file in the package missing the `##! experimental.persistence` flag (which aborts the *whole* package's build plan), or no build ever ran (a standalone Publisher does not build on publish - see **Building and refreshing**). Jump to **Debugging a no-op build**.\n\n## The recipe (get this right and it just works)\n\n1. **`##! experimental.persistence` on EVERY `.malloy` file in the package** - not only the file that declares the persist source. Either form enables it:\n   - `##! experimental.persistence`, or\n   - `##! experimental { access_modifiers, sql_functions, persistence }` (add `persistence` to the existing list).\n\n   **Why every file:** the build plan is computed by asking *every* `.malloy` file in the package for its persist sources, and that call **throws on any file whose model lacks the flag** (`Model must have ##! experimental.persistence`). One unflagged helper or import file, even one with no persist source of its own, aborts the whole package's build plan, so *every* persist source in the package drops out. This is the most common cause of a no-op build.\n\n2. **`#@ persist name=\"...\"` on a query-based source, with the name quoted:**\n   ```malloy\n   #@ persist name=\"my_dataset.my_table\"\n   source: my_rollup is some_source -> { group_by: ...; aggregate: ... }\n   ```\n   - **Only `query_source` and `sql_select` sources are persistable** - a source whose definition has a `-> { ... }` pipeline or a `conn.sql(\"...\")`. This **includes** one refined by a trailing `extend { ... }`. What is **not** persistable is a *plain* `extend` over a bare `conn.table(...)`; a `#@ persist` on such a source is **silently ignored** (its annotation is never read) - that one source just won't materialize, and the rest of the package still builds.\n   - **Quote the name.** `name=\"my_table\"` (or a path `name=\"dataset.table\"` / `name=\"project.dataset.table\"`) is required. A **bare** `name=my_table` **always fails the build/publish** with `persist annotation name must be quoted` (a raw-source scan that hard-stops); it never silently no-ops.\n   - `name=` is the target table name. In a standalone Publisher this **is** the physical table (rebuilt in place); a hosted (control-plane) deployment builds it under a content-addressed generation name. In both, the source's identity for reuse is a content address of its connection and canonical SQL (its `sourceEntityId`), so **republishing unchanged persist logic reuses the existing table** and changing the logic builds fresh.\n\n3. **Package persistence policy in `publisher.json`** (all optional):\n   ```jsonc\n   {\n     \"name\": \"my-package\",\n     \"materialization\": {\n       \"scope\": \"package\",  // default; \"version\" = each published version owns its own tables\n       \"freshness\": { \"window\": \"24h\", \"fallback\": \"live\" },\n       \"queryMetadata\": { \"team\": \"finance\" }  // tags the build's backend statements\n     }\n   }\n   ```\n   Enforced at publish (strict), on edits (strict), at load (warn, still serves), and by the scheduler (an offending package is skipped):\n   - **`scope`**: `package` (default; artifacts reused across published versions) or `version` (each artifact owned by one version). Package-level only; there is no per-source scope. A root-level `scope` is the deprecated home and still works, with a warning; declaring both homes with different values is rejected.\n   - **`materialization.freshness`** (`window` + `fallback` of `live`/`stale_ok`/`fail`) is the objective a **hosted control plane** enforces by refreshing the table to meet it (`fallback: \"live\"` serves live compute while stale/absent). A **standalone** Publisher does **not** act on `freshness` for refresh - see **Building and refreshing**.\n   - **`materialization.queryMetadata`** is a bag of string properties attached to every statement the build issues, for the backend's own cost attribution (Snowflake `QUERY_TAG`, BigQuery job labels, a leading SQL comment elsewhere). Overridable per source with `#@ persist queryMetadata.<name>=\"<value>\"`. Observability only: it never changes what gets built. See `docs/query-metadata.md`.\n   - **`materialization.schedule`** is a 5-field UTC cron (`min hour dom mon dow`; `L`/`W`/`#`/`?` rejected). It **requires `scope: \"version\"`** and is **mutually exclusive with `freshness`**. This is how a standalone Publisher refreshes on a cadence.\n\n4. **Reads vs writes.** The persist source can *read* any dataset the connection can read; the persist *target* (`name=`'s dataset) must be a dataset the connection can **write** (typically a scratch dataset).\n\n## Building and refreshing (standalone vs. hosted)\n\nA `#@ persist` tag declares *what* to materialize; it does not by itself build anything.\n\n- **Standalone Publisher:** publishing or loading a package only computes its build plan - **no table is built until a materialization run executes.** Trigger one explicitly (`malloy-pub materialize --package <pkg> --wait`, or the materialization API), or turn on the opt-in local scheduler (off unless `PUBLISHER_LOCAL_MATERIALIZATION_SCHEDULER` is set) to fire the package's `schedule` cron. Refresh is a re-run or that cron; `freshness` is not a refresh trigger here, so a freshness-only standalone package builds once and is not auto-refreshed.\n- **Hosted (control-plane) deployment:** the build runs automatically on publish, best-effort - a build failure does **not** fail the publish (which is why a broken persist can look like a silent no-op), and the control plane drives refresh to meet the `freshness` objective.\n\nEither way, a successful publish alone does not prove a table exists - confirm the build separately.\n\n## Serve-time routing is `query_source`-only (today)\n\nBoth persistable types *build* a table, but only a **`query_source`** (a `-> { ... }` pipeline) is rewritten to *read* it at query time. A raw **`sql_select`** (`conn.sql(\"...\")`, including `conn.sql(\"...\") extend { ... }`) builds its table and then the query path re-inlines its SQL, so the table is built and never read, and queries are no faster. If you have raw SQL you want served from a table, wrap it in a thin `query_source` and persist that:\n\n```malloy\nsource: x_raw is my_conn.sql(\"select ...\")\n#@ persist name=\"scratch_dataset.x\"\nsource: x is x_raw -> { select: * }\n```\n\n## Confirming it worked\n\nAfter a build runs, re-run one of the source's queries - a persisted `query_source` should return quickly, reading the pre-built table instead of recomputing the upstream. Your host also reports each persisted source as **ready** with its physical table name (a materialization run detail, CLI listing, or materialization view, depending on the host); if nothing is listed, either no build ran (standalone) or the build plan was empty - see **Debugging a no-op build**.\n\n## Debugging a no-op build\n\nSymptom: no table was built and the source still recomputes on every query. Check, in order:\n\n0. **Did a build actually run?** On a standalone Publisher, publish/load does **not** build - run `malloy-pub materialize` (or enable the scheduler). \"Publishes fine, no table\" is the *expected* standalone state, not a model bug. On a hosted deployment the build is automatic but best-effort, so a failure is silent - look for a `FAILED` run.\n1. **A `.malloy` file missing the persistence flag** (the most common real bug). Every model file's `##!` line needs `persistence`, including pure helper/import files with no persist source - one unflagged file aborts the whole package's build plan.\n2. **An unquoted persist name** - a bare `name=foo` **always** hard-stops the build/publish with `persist annotation name must be quoted`; use `name=\"foo\"`. (If you got *no* error at all, it isn't this.)\n3. **A `#@ persist` on a non-persistable source** - a bare `extend` over `conn.table(...)` is silently ignored, so *that* source won't materialize (the rest of the package is unaffected). Tag a `query_source` / `sql_select` instead.\n4. **A persisted raw `sql_select` that builds but is never read** - if the table exists yet queries are no faster, it's the serve-routing gap above; wrap the `sql_select` in a `query_source`.\n\n**Isolation test** - add a trivial, self-contained persist source in its own file and rebuild:\n```malloy\n##! experimental.persistence\nsource: smoke_raw is my_conn.table('some_dataset.some_table')\n#@ persist name=\"scratch_dataset.persist_smoke_test\"\nsource: persist_smoke is smoke_raw -> { aggregate: n is count() }\n```\n- If **even this** doesn't build (after a real materialization run), the whole package's plan is aborting - a sibling `.malloy` file is missing the flag. Fix rule 1 across the package.\n- If the smoke source **does** build but your real one doesn't, your real source is the problem - a non-persistable type (a bare `extend`), or its own file's flag.\n\nDelete the smoke file and drop its table afterward.\n\n## Persisting a `#(access_filter)`-gated source\n\nA gated source **can** be persisted, but only on one tier and only in one shape, and the thing to be\ncareful about is not refused by anything - you have to decide it.\n\n- **`storage=` and `#@ preaggregate` always refuse a gated source**, with a 422 at build time naming the\n  source. (`#@ persist storage=<name>` is the tier that materializes into a separate registered storage\n  destination and serves from there, rather than building in the source's own connection; `#@ preaggregate`\n  stores a rollup Publisher derives from a measure you annotated with a grain, rather than a source you\n  wrote.) A rollup also groups *across* the gated column, so it could not be row-filtered afterwards even\n  in principle.\n- **A colocated `#@ persist` (no `storage=`) is admitted** when the gate is provably the entry point's\n  **own row filter**. It is refused when the gate is reached only through a join, inherited from a base\n  the compiler cannot attribute cleanly, or does not classify as a row filter at all. The gate is found\n  through the import -> rename -> `query_source` chain, so a gate the persisted source did not declare\n  itself still counts.\n\n**What to be wary of.** Persisting does not weaken the gate: it changes only where rows are read FROM, and\nthe gate still runs live on every query as that query's own `WHERE`, so filtered rows come back filtered.\nWhat freezes is the **column the gate filters on**. A row whose access decision changes - it changes\nowner, say - keeps being served under its OLD decision until the next rebuild. That is a stale *access\ndecision*, not merely stale data, and nothing raises an error.\n\n**None of this is needed for the gate to work.** It is enforced live on every query either way; what\nneeds a bound is how long a *stale* decision can survive. Of the three controls that look like that\nbound, only the first is:\n\n- **`materialization.freshness` `{ \"window\": \"24h\", \"fallback\": \"live\" }` is the bound.** The serve path\n  re-checks freshness per query, so once the artifact ages past the window it drops out of the serving set\n  and the query recomputes live, correctly filtered - whether or not a rebuild ever lands. Three details\n  decide whether you actually get that. **`fallback` must be `live`**: under `stale_ok` a stale artifact\n  keeps being served, which voids the bound, and window and fallback resolve *independently* per layer,\n  so a package-level `stale_ok` silently defeats a window you set on the source. That is a statement about\n  **layers**, which do not combine - not about siblings, below. Prefer the\n  **per-source** spelling `#@ persist name=\"...\" freshness.window=\"24h\" freshness.fallback=\"live\"` over\n  the package-wide `materialization.freshness` key: the gated source is what needs the bound, and setting\n  it package-wide forces every other persisted source to recompute once stale too. And **a\n  content-identical sibling shares the artifact, so it shares the window**: reuse is keyed on the\n  content-addressed `sourceEntityId`, which folds the connection and the SQL but *not* the source name, so\n  two persist sources whose bodies compute the same SQL resolve to one table carrying one freshness\n  policy. The tightest window any of them declares governs all of them - a sibling declaring nothing\n  cannot loosen yours, and yours pulls that sibling's reads off the table once it lapses. A sibling's\n  `stale_ok` cannot void your bound either: the fold keeps whichever fallback bounds staleness, so the\n  layer rule above does not carry over here. If two sources need genuinely different windows, give them\n  genuinely different SQL.\n\n  Both of those are properties of the **host** that assembles the manifest, not of the annotation. Where\n  the host does not fold, which sibling's policy reaches the wire is unspecified; and a host that folds at\n  manifest-assembly time typically applies it when a version's manifest is next published rather than\n  retroactively to manifests already distributed - so you can declare the window correctly and not have it\n  in force yet.\n- **A cron alone is not a bound.** A failed build or a stopped scheduler leaves the source serving its old\n  decisions indefinitely. `freshness` and `schedule` are mutually exclusive; for a gated source, take the\n  window.\n- **`refresh=\"incremental\"` does not bound revocation.** The delta only re-reads rows in\n  `[covered_through, frontier)`, so a row that changes owner *without its watermark advancing* is never\n  re-read - while the entry still reports an advancing `coveredThrough` and reads as healthy. Only a full\n  rebuild recomputes the gating column.\n\n**And the window only binds where the serving manifest carries it.** Freshness is enforced from fields a\ncontrol plane stamps onto the manifest it distributes; a Publisher that serves what it just built binds the\ntable with no `dataAsOf` and no window, and an entry carrying no window never ages out. So on a standalone\ndeployment the declared window is inert and the artifact serves until the next full rebuild - which leaves a\nrebuild cadence you actually verify as the only bound, and makes leaving a revocation-sensitive source\nunpersisted the safer call.\n\nWhen recommending `#@ persist` on a gated source, pair it with a freshness window and say out loud what\nstaleness the author is accepting. A gated source with neither a window nor a full-rebuild cadence has no\nbound on how long a revoked row keeps being served.\n\n## Gotchas\n\n- **Every `.malloy` file needs the persistence flag** - one unflagged file aborts the whole package's build plan. (A `#@ persist` on a *non*-persistable source, by contrast, is silently ignored and does not affect other sources.)\n- **A tag doesn't build** - a standalone Publisher materializes only on an explicit run or its scheduler; only a hosted control plane builds on publish.\n- **Serve-time routing is `query_source`-only** - a raw `sql_select` builds a table the query path doesn't read; wrap it in a `query_source`.\n- **Quote the name** - a bare `name=` always hard-stops the build.\n- **Republishing unchanged persist logic reuses the table** - reuse is keyed on the content-addressed `sourceEntityId`, not the `name=`.\n- **Removing a persist source (or a smoke test) does not drop its table** - physical-table cleanup is the caller's responsibility; drop it yourself.\n- **A `#(access_filter)`-gated source freezes its gating column when persisted** - the gate still runs live, but a revoked row keeps being served under its old access decision until the next rebuild. `storage=` and `#@ preaggregate` refuse a gated source outright. See **Persisting a `#(access_filter)`-gated source**."
+      body: "# Materialization (Malloy Persistence)\n\nMaterialize an expensive source once so queries read a **pre-built warehouse table** instead of recomputing it every time. You tag a source `#@ persist`, a materialization run builds it into a physical table, and queries against it are rewritten to read that table.\n\n> **The #1 gotcha, up front:** if a persist source isn't materializing, it is almost always one of two things - a `.malloy` file in the package missing the `##! experimental.persistence` flag (which aborts the *whole* package's build plan), or no build ever ran (a standalone Publisher does not build on publish - see **Building and refreshing**). Jump to **Debugging a no-op build**.\n\n## The recipe (get this right and it just works)\n\n1. **`##! experimental.persistence` on EVERY `.malloy` file in the package** - not only the file that declares the persist source. Either form enables it:\n   - `##! experimental.persistence`, or\n   - `##! experimental { access_modifiers, sql_functions, persistence }` (add `persistence` to the existing list).\n\n   **Why every file:** the build plan is computed by asking *every* `.malloy` file in the package for its persist sources, and that call **throws on any file whose model lacks the flag** (`Model must have ##! experimental.persistence`). One unflagged helper or import file, even one with no persist source of its own, aborts the whole package's build plan, so *every* persist source in the package drops out. This is the most common cause of a no-op build.\n\n2. **`#@ persist name=\"...\"` on a query-based source, with the name quoted:**\n   ```malloy\n   #@ persist name=\"my_dataset.my_table\"\n   source: my_rollup is some_source -> { group_by: ...; aggregate: ... }\n   ```\n   - **Only `query_source` and `sql_select` sources are persistable** - a source whose definition has a `-> { ... }` pipeline or a `conn.sql(\"...\")`. This **includes** one refined by a trailing `extend { ... }`. What is **not** persistable is a *plain* `extend` over a bare `conn.table(...)`; a `#@ persist` on such a source is **silently ignored** (its annotation is never read) - that one source just won't materialize, and the rest of the package still builds.\n   - **Quote the name.** `name=\"my_table\"` (or a path `name=\"dataset.table\"` / `name=\"project.dataset.table\"`) is required. A **bare** `name=my_table` **always fails the build/publish** with `persist annotation name must be quoted` (a raw-source scan that hard-stops); it never silently no-ops.\n   - `name=` is the target table name. In a standalone Publisher this **is** the physical table (rebuilt in place); a hosted (control-plane) deployment builds it under a content-addressed generation name. In both, the source's identity for reuse is a content address of its connection and canonical SQL (its `sourceEntityId`), so **republishing unchanged persist logic reuses the existing table** and changing the logic builds fresh.\n\n3. **Package persistence policy in `publisher.json`** (all optional):\n   ```jsonc\n   {\n     \"name\": \"my-package\",\n     \"materialization\": {\n       \"scope\": \"package\",  // default; \"version\" = each published version owns its own tables\n       \"freshness\": { \"window\": \"24h\", \"fallback\": \"live\" },\n       \"queryMetadata\": { \"team\": \"finance\" }  // tags the build's backend statements\n     }\n   }\n   ```\n   Enforced at publish (strict), on edits (strict), at load (warn, still serves), and by the scheduler (an offending package is skipped):\n   - **`scope`**: `package` (default; artifacts reused across published versions) or `version` (each artifact owned by one version). Package-level only; there is no per-source scope. A root-level `scope` is the deprecated home and still works, with a warning; declaring both homes with different values is rejected.\n   - **`materialization.freshness`** (`window` + `fallback` of `live`/`stale_ok`/`fail`) is the objective a **hosted control plane** enforces by refreshing the table to meet it (`fallback: \"live\"` serves live compute while stale/absent). A **standalone** Publisher does **not** act on `freshness` for refresh - see **Building and refreshing**.\n   - **`materialization.queryMetadata`** is a bag of string properties attached to every statement the build issues, for the backend's own cost attribution (Snowflake `QUERY_TAG`, BigQuery job labels, a leading SQL comment elsewhere). Overridable per source with `#@ persist queryMetadata.<name>=\"<value>\"`. Observability only: it never changes what gets built. See `docs/query-metadata.md`.\n   - **`materialization.schedule`** is a 5-field UTC cron (`min hour dom mon dow`; `L`/`W`/`#`/`?` rejected). It **requires `scope: \"version\"`** and is **mutually exclusive with `freshness`**. This is how a standalone Publisher refreshes on a cadence.\n\n4. **Reads vs writes.** The persist source can *read* any dataset the connection can read; the persist *target* (`name=`'s dataset) must be a dataset the connection can **write** (typically a scratch dataset).\n\n## Building and refreshing (standalone vs. hosted)\n\nA `#@ persist` tag declares *what* to materialize; it does not by itself build anything.\n\n- **Standalone Publisher:** publishing or loading a package only computes its build plan - **no table is built until a materialization run executes.** Trigger one explicitly (`malloy-pub materialize --package <pkg> --wait`, or the materialization API), or turn on the opt-in local scheduler (off unless `PUBLISHER_LOCAL_MATERIALIZATION_SCHEDULER` is set) to fire the package's `schedule` cron. Refresh is a re-run or that cron; `freshness` is not a refresh trigger here, so a freshness-only standalone package builds once and is not auto-refreshed.\n- **Hosted (control-plane) deployment:** the build runs automatically on publish, best-effort - a build failure does **not** fail the publish (which is why a broken persist can look like a silent no-op), and the control plane drives refresh to meet the `freshness` objective.\n\nEither way, a successful publish alone does not prove a table exists - confirm the build separately.\n\n## Serve-time routing is `query_source`-only (today)\n\nBoth persistable types *build* a table, but only a **`query_source`** (a `-> { ... }` pipeline) is rewritten to *read* it at query time. A raw **`sql_select`** (`conn.sql(\"...\")`, including `conn.sql(\"...\") extend { ... }`) builds its table and then the query path re-inlines its SQL, so the table is built and never read, and queries are no faster. If you have raw SQL you want served from a table, wrap it in a thin `query_source` and persist that:\n\n```malloy\nsource: x_raw is my_conn.sql(\"select ...\")\n#@ persist name=\"scratch_dataset.x\"\nsource: x is x_raw -> { select: * }\n```\n\n## Confirming it worked\n\nAfter a build runs, re-run one of the source's queries - a persisted `query_source` should return quickly, reading the pre-built table instead of recomputing the upstream. Your host also reports each persisted source as **ready** with its physical table name (a materialization run detail, CLI listing, or materialization view, depending on the host); if nothing is listed, either no build ran (standalone) or the build plan was empty - see **Debugging a no-op build**.\n\n## Debugging a no-op build\n\nSymptom: no table was built and the source still recomputes on every query. Check, in order:\n\n0. **Did a build actually run?** On a standalone Publisher, publish/load does **not** build - run `malloy-pub materialize` (or enable the scheduler). \"Publishes fine, no table\" is the *expected* standalone state, not a model bug. On a hosted deployment the build is automatic but best-effort, so a failure is silent - look for a `FAILED` run.\n1. **A `.malloy` file missing the persistence flag** (the most common real bug). Every model file's `##!` line needs `persistence`, including pure helper/import files with no persist source - one unflagged file aborts the whole package's build plan.\n2. **An unquoted persist name** - a bare `name=foo` **always** hard-stops the build/publish with `persist annotation name must be quoted`; use `name=\"foo\"`. (If you got *no* error at all, it isn't this.)\n3. **A `#@ persist` on a non-persistable source** - a bare `extend` over `conn.table(...)` is silently ignored, so *that* source won't materialize (the rest of the package is unaffected). Tag a `query_source` / `sql_select` instead.\n4. **A persisted raw `sql_select` that builds but is never read** - if the table exists yet queries are no faster, it's the serve-routing gap above; wrap the `sql_select` in a `query_source`.\n\n**Isolation test** - add a trivial, self-contained persist source in its own file and rebuild:\n```malloy\n##! experimental.persistence\nsource: smoke_raw is my_conn.table('some_dataset.some_table')\n#@ persist name=\"scratch_dataset.persist_smoke_test\"\nsource: persist_smoke is smoke_raw -> { aggregate: n is count() }\n```\n- If **even this** doesn't build (after a real materialization run), the whole package's plan is aborting - a sibling `.malloy` file is missing the flag. Fix rule 1 across the package.\n- If the smoke source **does** build but your real one doesn't, your real source is the problem - a non-persistable type (a bare `extend`), or its own file's flag.\n\nDelete the smoke file and drop its table afterward.\n\n## Persisting a `#(access_filter)`-gated source\n\nA gated source **can** be persisted, but only on one tier and only in one shape, and the thing to be\ncareful about is not refused by anything - you have to decide it.\n\n- **`storage=` and `#@ preaggregate` always refuse a gated source**, naming it. The build skips a refused\n  source, records it on the run (`metadata.refusedSources`), and builds the rest of the package. A run fails\n  on a refusal only when every authored source it targeted was refused, or when `sourceNames` named this one;\n  a refused rollup never fails it. (`#@ persist storage=<name>` is the tier that materializes into a separate\n  registered storage destination and serves from there, rather than building in the source's own connection;\n  `#@ preaggregate` stores a rollup Publisher derives from a measure you annotated with a grain, rather than a\n  source you wrote.) A rollup also groups *across* the gated column, so it could not be row-filtered afterwards\n  even in principle.\n- **A colocated `#@ persist` (no `storage=`) is admitted** when the gate is provably the entry point's\n  **own row filter**. It is refused when the gate is reached only through a join, inherited from a base\n  the compiler cannot attribute cleanly, or does not classify as a row filter at all. The gate is found\n  through the import -> rename -> `query_source` chain, so a gate the persisted source did not declare\n  itself still counts.\n\n**What to be wary of.** Persisting does not weaken the gate: it changes only where rows are read FROM, and\nthe gate still runs live on every query as that query's own `WHERE`, so filtered rows come back filtered.\nWhat freezes is the **column the gate filters on**. A row whose access decision changes - it changes\nowner, say - keeps being served under its OLD decision until the next rebuild. That is a stale *access\ndecision*, not merely stale data, and nothing raises an error.\n\n**None of this is needed for the gate to work.** It is enforced live on every query either way; what\nneeds a bound is how long a *stale* decision can survive. Of the three controls that look like that\nbound, only the first is:\n\n- **`materialization.freshness` `{ \"window\": \"24h\", \"fallback\": \"live\" }` is the bound.** The serve path\n  re-checks freshness per query, so once the artifact ages past the window it drops out of the serving set\n  and the query recomputes live, correctly filtered - whether or not a rebuild ever lands. Three details\n  decide whether you actually get that. **`fallback` must be `live`**: under `stale_ok` a stale artifact\n  keeps being served, which voids the bound, and window and fallback resolve *independently* per layer,\n  so a package-level `stale_ok` silently defeats a window you set on the source. That is a statement about\n  **layers**, which do not combine - not about siblings, below. Prefer the\n  **per-source** spelling `#@ persist name=\"...\" freshness.window=\"24h\" freshness.fallback=\"live\"` over\n  the package-wide `materialization.freshness` key: the gated source is what needs the bound, and setting\n  it package-wide forces every other persisted source to recompute once stale too. And **a\n  content-identical sibling shares the artifact, so it shares the window**: reuse is keyed on the\n  content-addressed `sourceEntityId`, which folds the connection and the SQL but *not* the source name, so\n  two persist sources whose bodies compute the same SQL resolve to one table carrying one freshness\n  policy. The tightest window any of them declares governs all of them - a sibling declaring nothing\n  cannot loosen yours, and yours pulls that sibling's reads off the table once it lapses. A sibling's\n  `stale_ok` cannot void your bound either: the fold keeps whichever fallback bounds staleness, so the\n  layer rule above does not carry over here. If two sources need genuinely different windows, give them\n  genuinely different SQL.\n\n  Both of those are properties of the **host** that assembles the manifest, not of the annotation. Where\n  the host does not fold, which sibling's policy reaches the wire is unspecified; and a host that folds at\n  manifest-assembly time typically applies it when a version's manifest is next published rather than\n  retroactively to manifests already distributed - so you can declare the window correctly and not have it\n  in force yet.\n- **A cron alone is not a bound.** A failed build or a stopped scheduler leaves the source serving its old\n  decisions indefinitely. `freshness` and `schedule` are mutually exclusive; for a gated source, take the\n  window.\n- **`refresh=\"incremental\"` does not bound revocation.** The delta only re-reads rows in\n  `[covered_through, frontier)`, so a row that changes owner *without its watermark advancing* is never\n  re-read - while the entry still reports an advancing `coveredThrough` and reads as healthy. Only a full\n  rebuild recomputes the gating column.\n\n**And the window only binds where the serving manifest carries it.** Freshness is enforced from fields a\ncontrol plane stamps onto the manifest it distributes; a Publisher that serves what it just built binds the\ntable with no `dataAsOf` and no window, and an entry carrying no window never ages out. So on a standalone\ndeployment the declared window is inert and the artifact serves until the next full rebuild - which leaves a\nrebuild cadence you actually verify as the only bound, and makes leaving a revocation-sensitive source\nunpersisted the safer call.\n\nWhen recommending `#@ persist` on a gated source, pair it with a freshness window and say out loud what\nstaleness the author is accepting. A gated source with neither a window nor a full-rebuild cadence has no\nbound on how long a revoked row keeps being served.\n\n## Gotchas\n\n- **Every `.malloy` file needs the persistence flag** - one unflagged file aborts the whole package's build plan. (A `#@ persist` on a *non*-persistable source, by contrast, is silently ignored and does not affect other sources.)\n- **A tag doesn't build** - a standalone Publisher materializes only on an explicit run or its scheduler; only a hosted control plane builds on publish.\n- **Serve-time routing is `query_source`-only** - a raw `sql_select` builds a table the query path doesn't read; wrap it in a `query_source`.\n- **Quote the name** - a bare `name=` always hard-stops the build.\n- **Republishing unchanged persist logic reuses the table** - reuse is keyed on the content-addressed `sourceEntityId`, not the `name=`.\n- **Removing a persist source (or a smoke test) does not drop its table** - physical-table cleanup is the caller's responsibility; drop it yourself.\n- **A `#(access_filter)`-gated source freezes its gating column when persisted** - the gate still runs live, but a revoked row keeps being served under its old access decision until the next rebuild. `storage=` and `#@ preaggregate` refuse a gated source outright. See **Persisting a `#(access_filter)`-gated source**."
     },
     {
       name: "malloy-materialization-tuning",
       description: "Optimize a package's Malloy Persistence materializations for cost and performance using the malloy-pub CLI and the materialization history. Recommend what to persist, what to stop persisting, and how to schedule/scope it. Use when the user asks to make a package cheaper or faster, tune persistence, decide what to materialize, or review persist/schedule choices.",
-      body: "# Tuning materializations for cost and performance\n\nThis skill turns the signals the open-source Publisher already records (the materialization history, per-run timings, and which sources were built vs reused) into concrete, **recommendations-only** advice: which sources to persist, which to stop persisting, and how to schedule and scope them. It is the local counterpart to the platform's usage-driven optimization: the Publisher has the raw signals, and you read them with the `malloy-pub` CLI.\n\n> **Recommendations only. Never change a model, schedule, or scope without the user's explicit go-ahead.** Present the findings and the proposed edits, then apply them only when asked. Persisting the wrong source wastes storage and rebuild time; unpersisting a hot one makes queries slow. Let the user decide.\n\nAssumes the `malloy-pub` CLI is on PATH and points at the server (`--url` or `MALLOY_PUBLISHER_URL`, default `http://localhost:4000`). Substitute the real environment and package for `<env>` / `<pkg>`.\n\n## Step 1: Take inventory\n\nEstablish what the package persists today and how it is governed.\n\n- **Persist sources:** the sources annotated `#@ persist name=\"…\"` in the package's `.malloy` files. Read the models (or `get_context` the package) to list them.\n- **Schedule + scope:**\n\n  ```bash\n  malloy-pub schedule view --environment <env> --package <pkg>\n  ```\n\n  This prints the cron (or `none`, meaning publish / on-demand only), the persist **scope** (`package` = artifacts reused across versions; `version` = per published version), and whether a freshness policy is set. A control-plane-managed package (manifestLocation set) is refreshed by the control plane, not the standalone scheduler, so leave its cadence alone.\n\n## Step 2: Read the materialization history\n\nThe history is where cost lives. Each run records its trigger, timing, and how many sources were built vs reused.\n\n- **For one package** (newest first). A materialization is a run of one package's persist sources, so this is the listing; to review a whole environment, read each package in turn (`malloy-pub list package --environment <env>` names them):\n\n  ```bash\n  malloy-pub list materialization --environment <env> --package <pkg>\n  ```\n\n  Columns: ID, Status, **Trigger** (`SCHEDULER` vs `ON_DEMAND`), Started, Completed, Error.\n\n- **A single run's detail** (the cost signals):\n\n  ```bash\n  malloy-pub get materialization <id> --environment <env> --package <pkg>\n  ```\n\n  In the JSON, read:\n  - `metadata.durationMs`: how long the build took.\n  - `metadata.sourcesBuilt` vs `metadata.sourcesReused`: how much work each run actually did. A run that is nearly all _reused_ is cheap; one that is nearly all _built_ every time is where cost accumulates.\n  - `metadata.trigger`: `SCHEDULER` (a cron fired it) or `ON_DEMAND`.\n  - `manifest.entries[*]`: the persisted sources: `sourceName`, `physicalTableName`, `realization`.\n\nLook across several runs, not one: the pattern over the recent history (how often it rebuilds, how much it reuses, how long it takes) is the signal.\n\n## Step 3: Analyze and recommend\n\nWeigh rebuild cost against query benefit. Common findings:\n\n- **Persist candidate:** an expensive, frequently-queried source that is _not_ persisted (recomputed on every query). Recommend adding `#@ persist name=\"…\"`. Strongest when the source is a heavy aggregate/join reused by many queries and its inputs change slowly. If the source carries a `#(access_filter)` gate, check which case it is first. A gate reached only through a `join_*`, or inherited from a base it cannot be attributed to, makes the colocated persist **refuse with a 422** - so do not recommend persisting it at all. Where the gate is provably the source's own row filter the persist is admitted, and then only recommend it alongside a freshness window (`freshness.fallback=\"live\"`): the gating column freezes at build time, so without one a revoked row can be served under its old access decision indefinitely (see `skill:malloy-materialization`, which also covers where that window does and does not bind).\n- **Removal candidate:** a persisted source that is cheap to compute, rarely queried, or rebuilt far more often than it is read. Recommend dropping the `#@ persist` annotation (and its table): the storage + rebuild cost is not buying anything.\n- **Cadence mismatch:** a `SCHEDULER` cadence out of step with how fast the data changes or how long a build takes. If most scheduled runs are all-reused (nothing changed), the cron is too frequent, so loosen it. If queries routinely read stale data, tighten it. If the build's `durationMs` approaches the interval, the cadence is too aggressive.\n- **Scope mismatch:** `scope: version` re-materializes per published version (right when versions must be isolated, e.g. a schedule); `scope: package` reuses one lineage across versions (cheaper when versions can share). A schedule _requires_ `version`. If a package carries a schedule it does not need, clearing the schedule frees it to use the cheaper package scope.\n\nFrame each recommendation with the evidence from Step 2 (the run IDs, timings, built/reused counts) so the user can judge it.\n\n## Step 4: Apply (only once approved)\n\n- **Add a persist source:** add the `#@ persist` annotation in the `.malloy` file (use the modeling workflow to validate and reload), then rebuild so it is materialized:\n\n  ```bash\n  malloy-pub materialize --environment <env> --package <pkg> --wait\n  ```\n\n- **Remove a persist source:** delete the `#@ persist` annotation, then drop the old run's tables **before** rebuilding what remains:\n\n  ```bash\n  malloy-pub delete materialization <id> --environment <env> --package <pkg> --drop-tables\n  malloy-pub materialize --environment <env> --package <pkg> --wait\n  ```\n\n  > `--drop-tables` drops **every** physical table in that run's manifest, not just the removed source's: auto-run assigns stable table names and carries unchanged sources forward, so an old run's manifest names tables a newer manifest still serves. Do the drop **first, then rebuild**: `materialize --wait` re-creates every source that is still persisted, ending in the desired state. Dropping a run whose tables the current serving manifest depends on, without an immediate rebuild, breaks queries (`Table ... does not exist`).\n\n- **Change the schedule / cadence:**\n\n  ```bash\n  malloy-pub schedule set \"0 6 * * *\" --environment <env> --package <pkg>   # 5-field UTC cron\n  malloy-pub schedule clear --environment <env> --package <pkg>\n  ```\n\n  `set` also sets `scope: version` (a schedule requires it); the server rejects an invalid cron or an illegal scope/freshness combination, so a rejection means the change was unsafe.\n\n- **Change the scope:** `scope` is declared in the package's `publisher.json` under `materialization` (`\"scope\": \"package\"` or `\"version\"`; the root-level form is deprecated but still read). Edit it there, then reload/republish the package. Remember a schedule pins scope to `version`, so clear the schedule first if moving to `package`.\n\nAfter applying, re-run Step 2 on the next few builds to confirm the change did what you predicted (more reuse, shorter builds, or a table that is actually read).\n\n## What this skill does not do\n\n- It does not decide for the user or apply changes silently; every edit needs an explicit go-ahead.\n- It cannot see per-query read counts (the open-source Publisher records build history, not query-level table usage), so \"rarely queried\" is a judgment from the model and the user's knowledge, not a measured metric. Say so when it matters."
+      body: "# Tuning materializations for cost and performance\n\nThis skill turns the signals the open-source Publisher already records (the materialization history, per-run timings, and which sources were built vs reused) into concrete, **recommendations-only** advice: which sources to persist, which to stop persisting, and how to schedule and scope them. It is the local counterpart to the platform's usage-driven optimization: the Publisher has the raw signals, and you read them with the `malloy-pub` CLI.\n\n> **Recommendations only. Never change a model, schedule, or scope without the user's explicit go-ahead.** Present the findings and the proposed edits, then apply them only when asked. Persisting the wrong source wastes storage and rebuild time; unpersisting a hot one makes queries slow. Let the user decide.\n\nAssumes the `malloy-pub` CLI is on PATH and points at the server (`--url` or `MALLOY_PUBLISHER_URL`, default `http://localhost:4000`). Substitute the real environment and package for `<env>` / `<pkg>`.\n\n## Step 1: Take inventory\n\nEstablish what the package persists today and how it is governed.\n\n- **Persist sources:** the sources annotated `#@ persist name=\"…\"` in the package's `.malloy` files. Read the models (or `get_context` the package) to list them.\n- **Schedule + scope:**\n\n  ```bash\n  malloy-pub schedule view --environment <env> --package <pkg>\n  ```\n\n  This prints the cron (or `none`, meaning publish / on-demand only), the persist **scope** (`package` = artifacts reused across versions; `version` = per published version), and whether a freshness policy is set. A control-plane-managed package (manifestLocation set) is refreshed by the control plane, not the standalone scheduler, so leave its cadence alone.\n\n## Step 2: Read the materialization history\n\nThe history is where cost lives. Each run records its trigger, timing, and how many sources were built vs reused.\n\n- **For one package** (newest first). A materialization is a run of one package's persist sources, so this is the listing; to review a whole environment, read each package in turn (`malloy-pub list package --environment <env>` names them):\n\n  ```bash\n  malloy-pub list materialization --environment <env> --package <pkg>\n  ```\n\n  Columns: ID, Status, **Trigger** (`SCHEDULER` vs `ON_DEMAND`), Started, Completed, Error.\n\n- **A single run's detail** (the cost signals):\n\n  ```bash\n  malloy-pub get materialization <id> --environment <env> --package <pkg>\n  ```\n\n  In the JSON, read:\n  - `metadata.durationMs`: how long the build took.\n  - `metadata.sourcesBuilt` vs `metadata.sourcesReused`: how much work each run actually did. A run that is nearly all _reused_ is cheap; one that is nearly all _built_ every time is where cost accumulates.\n  - `metadata.sourcesRefused` and `metadata.refusedSources`: sources the eligibility gate skipped. Each one serves live on every query, so a refused source the user expected to be persisted is a finding in its own right; its entry's `message` says what to change.\n  - `metadata.trigger`: `SCHEDULER` (a cron fired it) or `ON_DEMAND`.\n  - `manifest.entries[*]`: the persisted sources: `sourceName`, `physicalTableName`, `realization`.\n\nLook across several runs, not one: the pattern over the recent history (how often it rebuilds, how much it reuses, how long it takes) is the signal.\n\n## Step 3: Analyze and recommend\n\nWeigh rebuild cost against query benefit. Common findings:\n\n- **Persist candidate:** an expensive, frequently-queried source that is _not_ persisted (recomputed on every query). Recommend adding `#@ persist name=\"…\"`. Strongest when the source is a heavy aggregate/join reused by many queries and its inputs change slowly. If the source carries a `#(access_filter)` gate, check which case it is first. A gate reached only through a `join_*`, or inherited from a base it cannot be attributed to, means the colocated persist is **refused** - the build skips it and it serves live - so do not recommend persisting it at all. Where the gate is provably the source's own row filter the persist is admitted, and then only recommend it alongside a freshness window (`freshness.fallback=\"live\"`): the gating column freezes at build time, so without one a revoked row can be served under its old access decision indefinitely (see `skill:malloy-materialization`, which also covers where that window does and does not bind).\n- **Removal candidate:** a persisted source that is cheap to compute, rarely queried, or rebuilt far more often than it is read. Recommend dropping the `#@ persist` annotation (and its table): the storage + rebuild cost is not buying anything.\n- **Cadence mismatch:** a `SCHEDULER` cadence out of step with how fast the data changes or how long a build takes. If most scheduled runs are all-reused (nothing changed), the cron is too frequent, so loosen it. If queries routinely read stale data, tighten it. If the build's `durationMs` approaches the interval, the cadence is too aggressive.\n- **Scope mismatch:** `scope: version` re-materializes per published version (right when versions must be isolated, e.g. a schedule); `scope: package` reuses one lineage across versions (cheaper when versions can share). A schedule _requires_ `version`. If a package carries a schedule it does not need, clearing the schedule frees it to use the cheaper package scope.\n\nFrame each recommendation with the evidence from Step 2 (the run IDs, timings, built/reused counts) so the user can judge it.\n\n## Step 4: Apply (only once approved)\n\n- **Add a persist source:** add the `#@ persist` annotation in the `.malloy` file (use the modeling workflow to validate and reload), then rebuild so it is materialized:\n\n  ```bash\n  malloy-pub materialize --environment <env> --package <pkg> --wait\n  ```\n\n- **Remove a persist source:** delete the `#@ persist` annotation, then drop the old run's tables **before** rebuilding what remains:\n\n  ```bash\n  malloy-pub delete materialization <id> --environment <env> --package <pkg> --drop-tables\n  malloy-pub materialize --environment <env> --package <pkg> --wait\n  ```\n\n  > `--drop-tables` drops **every** physical table in that run's manifest, not just the removed source's: auto-run assigns stable table names and carries unchanged sources forward, so an old run's manifest names tables a newer manifest still serves. Do the drop **first, then rebuild**: `materialize --wait` re-creates every source that is still persisted, ending in the desired state. Dropping a run whose tables the current serving manifest depends on, without an immediate rebuild, breaks queries (`Table ... does not exist`).\n\n- **Change the schedule / cadence:**\n\n  ```bash\n  malloy-pub schedule set \"0 6 * * *\" --environment <env> --package <pkg>   # 5-field UTC cron\n  malloy-pub schedule clear --environment <env> --package <pkg>\n  ```\n\n  `set` also sets `scope: version` (a schedule requires it); the server rejects an invalid cron or an illegal scope/freshness combination, so a rejection means the change was unsafe.\n\n- **Change the scope:** `scope` is declared in the package's `publisher.json` under `materialization` (`\"scope\": \"package\"` or `\"version\"`; the root-level form is deprecated but still read). Edit it there, then reload/republish the package. Remember a schedule pins scope to `version`, so clear the schedule first if moving to `package`.\n\nAfter applying, re-run Step 2 on the next few builds to confirm the change did what you predicted (more reuse, shorter builds, or a table that is actually read).\n\n## What this skill does not do\n\n- It does not decide for the user or apply changes silently; every edit needs an explicit go-ahead.\n- It cannot see per-query read counts (the open-source Publisher records build history, not query-level table usage), so \"rarely queried\" is a judgment from the model and the user's knowledge, not a measured metric. Say so when it matters."
     },
     {
       name: "malloy-model",
@@ -325687,7 +326442,7 @@ source: first_touch is conn.table('events') -> {
     {
       name: "malloy-modeling",
       description: "Build semantic models with Malloy for the Malloy Publisher. Read this skill whenever the user asks about modeling data or specifically mentions Malloy.",
-      body: "# STOP - READ BEFORE WRITING ANY MALLOY CODE\n\n> **AI AGENTS: You MUST review this file before writing Malloy code.** Cross-skill references below use logical `skill:` names; load the referenced skill before acting. Before writing code, also read the gotcha skills: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering`.\n\n## Pre-Flight Checklist\n\n1. **Discover first**: ground yourself before writing ANY code, with the tool that matches what you are modelling.\n   - Modelling data **already in a package**: `get_context` returns that package's sources, views, and fields (with their docs).\n   - Modelling **a database with no package yet**: `get_context` has nothing to return, so use `search_database_schema` instead. It walks the connection's schemas and tables, ranks them against a plain-English description, and gives you each table's columns plus the `source:` line to start from. Take those names verbatim into step 5.\n   Never guess field names either way.\n2. **Search docs proactively**: call `search_malloy_docs` BEFORE writing unfamiliar patterns (window functions, query-based sources, pipelines). Don't guess. Malloy syntax is specific and SQL intuition is often wrong.\n3. **Use `skill:malloy-patterns`** to discover available doc topics (YoY, cohorts, rendering, window functions).\n4. **Check diagnostics** after writing: fix the FIRST error first, errors cascade.\n5. **Read the gotcha skills**: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering` prevent the most common mistakes.\n\n**Quick syntax reminders:**\n1. **Backtick reserved words:** `` `Date` ``, `` `Hour` ``, `` `Timestamp` ``, `` `Type` ``, `` `number` ``, `` `source` ``\n2. **Use `having:` for aggregate filters**: not `where:` on measures\n3. **Alias joined fields in `group_by`** if using them in `order_by`\n4. **`count()` counts rows; `count(x)` counts distinct values of `x`**: `count(distinct x)` is deprecated, write `count(x)`\n5. **One tag per line**: `# label=\"Revenue\"` and `# currency` on separate lines\n6. **No fixed scale on measures**: use `# currency` not `# currency=usd0m`\n7. **Cast strings for aggregates:** `avg(score::number)` not `avg(score)`\n8. **Boolean columns:** use `= true` not `= 'true'` (no quotes!)\n9. **Read data files in place:** `.csv`, `.parquet`, `.json`, `.ndjson`, and `.xlsx` all work as-is through `duckdb.table('data/file.ext')`. Never convert a file to another format first, and never read one with python or jq to \"have a look\" first: query it. For `.xlsx`, check the row count before trusting it: a workbook with a title row or a blank spacer reads short and reports no error. (Per-format quirks: `skill:malloy-gotchas-modeling`)\n\n## Planning and `modeling-notes.md`\n\nIf the IDE has a native plan mode, use it for the high-level approach: do data exploration during planning, then present a concrete plan for user approval before writing any files.\n\n`modeling-notes.md` is an expected output of the workflow, not an optional extra. Start it at step 2 (Propose Scope) and grow it as you work: it persists alongside the model, and its value is as the thing the user argues with at step 3, before source files exist; written after the build it can only document decisions already baked in. Record findings and problems as they are found during discovery (`skill:malloy-discover`), and every unconfirmed decision as an open item. Only when there is no writable workspace do the notes live in the conversation instead.\n\nKeep it compact, with these sections:\n\n```markdown\n# Modeling notes - <package>\n## Scope           what was confirmed, what the model is FOR, skip list with reasons\n## Grain and keys  proven by query, not by column name\n## Coverage        coverage cliffs; columns excluded for nullity\n## Decisions       each with its evidence\n## Open decisions  ASSUMPTIONS, NOT CONFIRMED: every threshold or definition the user\n                   has not settled, one entry each, mirrored by a hedge in its #(doc)\n## Validation      reconciliation checks performed, and their results\n```\n\n## 8-Step Modeling Workflow\n\nThe agent orchestrates all steps. Steps marked **(user)** pause for input. Each step has a dedicated skill with full instructions. Read each step's skill **before starting that step**, including the decision skills for steps 1–4 (`skill:malloy-discover`, `skill:malloy-scope`, `skill:malloy-define`). They govern what the model says; skipping them to reach the build skills is how unreviewed business logic ships.\n\n**A field is not complete until it has its definition, `#(doc)` tag, and rendering tags, and any threshold or business convention in it is user-confirmed, distribution-derived, or explicitly flagged in its `#(doc)`** (see `skill:malloy-document` § Mark conventions as conventions). Documentation is part of defining a field, not a separate activity. Read `skill:malloy-document` for full documentation standards (doc string writing, tag ordering).\n\n```\nDISCOVER → SCOPE → SOURCES → DEFINITIONS → BUILD BASE → BUILD JOINED → REVIEW → CURATE\n (silent)  (user)   (user)      (user)       (agent)      (agent)      (user)   (user)\n```\n\n| Step | Skill | What Happens |\n|------|-------|-------------|\n| 1. Discover | `skill:malloy-discover` | Read the model and data; scan sources, fields, distributions; detect prior art. With no package yet, start from `search_database_schema` to find the tables in the connection |\n| 2. Propose Scope | `skill:malloy-scope` | Present findings, user selects focus |\n| 3. Propose Sources | `skill:malloy-define` | Propose source plan, user confirms architecture |\n| 4. Propose Definitions | `skill:malloy-define` | Propose fields per base source, user confirms logic |\n| 5. Build Base Sources | `skill:malloy-model` | Write fully documented base source files (one per table), check diagnostics. Read `skill:malloy-document` for doc standards. |\n| 6. Build Joined Sources | `skill:malloy-model` | Write fully documented joined source files, validate. Read `skill:malloy-document` for doc standards. |\n| 7. Review | (none) | Present the review checklist below; user confirms or corrects |\n| 8. Curate | `skill:malloy-model` | Propose access controls (`explores`, `queryableSources`, access modifiers); always propose, the user decides whether to apply |\n\n### The pauses are the point\n\nThese are governed semantic models: the business decisions in them must be confirmed by a human subject-matter expert, and the **(user)** steps exist to collect that confirmation. They are real stops, not progress reports. A model can be complete, compiling, and fully documented and still be wrong everywhere it guessed; a capable agent can build the whole thing without pausing once, which is exactly the failure mode this workflow exists to prevent.\n\nWhen a decision goes unanswered (the user explicitly declines to decide, or nobody is there to ask), do not silently proceed as if it were settled. Take your best-supported position, label it an assumption in the field's own `#(doc)` (see `skill:malloy-document` § Mark conventions as conventions), record it under \"Open decisions\" in `modeling-notes.md`, and raise it again at Review. An unlabeled assumption is indistinguishable from a confirmed fact, and misleads everyone downstream.\n\n### Step 7 Review is a checklist, not a summary\n\nPresent these to the user, with answers:\n\n- **Which definitions did the user actually confirm?** List them; everything else is an assumption.\n- **Which thresholds and bucket boundaries did you choose?** For each: the evidence (distribution query, metadata, prior art) and the `#(doc)` hedge that marks it.\n- **Which questions were left unanswered?** Each must already carry a labeled assumption and an \"Open decisions\" entry.\n- **Does the headline metric have more than one defensible definition?** If yes, that is a blocking question: put the candidate definitions to the user with their counts side by side, not in a footnote.\n\nThe user confirming this checklist is what makes the model governed. A summary of what you built is not a checkpoint.\n\nPublishing is out of scope for open-source v1. Self-hosters move a finished model into a served package via git and the host's publish path; see `skill:malloy-publish` for the local-to-served handoff.\n\n**Two paths to a model: both produce the same fully documented result:**\n- **Schema-first:** \"Model my data\" → 8-step workflow above using the relevant skills\n- **Analysis-first:** a data question arrives before any model exists → `skill:malloy-model-as-you-go`. It answers the question with `skill:malloy-analysis`, then codifies what the answer assumed into the model, one question at a time, confirming binding decisions first. The model exists by the end; there is no separate formalize step.\n- **Open-ended exploration** with no intent to keep anything: `skill:malloy-analyze`. If it turns into something worth keeping, formalize via `skill:malloy-model` (`reference/analysis-to-model.md`).\n\n## Agent Behavior\n\n**Research before asking.** Present proposals with evidence. Never ask open-ended questions: propose with data and let the user confirm.\n\n**Use business language.** Say \"I simplified the column name\" not \"reserved word replaced.\" Don't expose Malloy internals unless the user asks.\n\n**Describe what you're doing, not which step you're on.** The user doesn't have the skill files open. Say \"I'll propose which tables to include and how they relate\" not \"Steps 3 and 4.\" Say \"Now I'll write the source files\" not \"Moving to Step 5.\" Explain the purpose of each phase in plain language before doing it.\n\n**Present choices as A/B/C.** When asking the user to choose, use lettered options with one-line descriptions. Mark your recommendation.\n\n**Complete all workflow steps.** Once modeling begins, complete through Review and propose Curate. A field without documentation is not finished. If you lose track, re-read the model and your notes. Suggest notebooks at the end.\n\n## Route by Intent\n\n| User says... | Route to |\n|-------------|----------|\n| \"Model my data\", \"create a model\" | 8-step workflow (`skill:malloy-discover`) |\n| \"Model from LookML\" | 8-step with prior art via `skill:malloy-lookml-review` |\n| \"Explore this data\", \"what's interesting?\", \"show me the top X\" | `skill:malloy-analyze` (EDA) |\n| \"Build a dashboard\", \"create views\" on existing model | `skill:malloy-analyze` (views), plus `skill:malloy-charts` or `skill:malloy-notebooks` as needed |\n| \"Build a model but not sure what metrics\" | `skill:malloy-model-as-you-go`: answer their first real question, codify what it assumed, repeat |\n\n**If the user's first message is a data question** (not \"build me a model\"), route to `skill:malloy-model-as-you-go`. It answers with `skill:malloy-analysis` and grows the model from what each answer assumed, so there is nothing to formalize afterwards.\n\n## Additional Support Skills\n\nThese supplemental skills may also be loaded as needed:\n\n- **`skill:malloy`**: Index of Malloy skills and routing guide\n- **`skill:malloy-debug`**: Fix compile errors and interpret diagnostics\n\n## Publisher MCP Tools\n\nEnsure the Publisher MCP tools are configured before modeling. No server yet? `skill:malloy-getting-started` covers setup, including the one-command scaffolder (`npm create @malloy-publisher/malloy-package@latest <name>`) and why local authoring needs `--watch-env <env>`: start the server without it and your saved edits are never read.\n\n| Tool | Purpose |\n|------|---------|\n| `get_context` | Ground yourself in a package: its sources, views, and fields |\n| `execute_query` | Run ad-hoc queries for validation |\n| `compile_model` | Compile-check a change and get diagnostics back without running a query |\n| `reload_package` | Recompile a package from disk so a saved edit becomes queryable by name |\n| `search_malloy_docs` | Search Malloy docs (call BEFORE unfamiliar patterns) |\n| `search_database_schema` | Find the tables in a database connection by plain-English description, when modelling data that is not in a package yet. Returns each table's columns and the `source:` line to start from. Names and types only: no row value is returned |\n\nNever guess field names. Ground yourself with `get_context` to see the sources and fields a package defines.\n\n### The edit-and-run loop\n\nPublisher compiles each configured package at boot and serves that cached model, so a source or view you add afterwards is not queryable by name until you reload the package. The loop is:\n\n1. **Validate** the change with `compile_model`, picking the scope that matches what you are doing:\n   - Adding a new definition or query: the default (`scope: \"append\"`) compiles your text in the model's namespace. Note its diagnostic positions land in the model-plus-your-text concatenation.\n   - **Editing an existing definition: `scope: \"file\"`**, with the whole edited file as `source`. It compiles your text AS the file (append would collide with \"Cannot redefine\"), and diagnostics land at the true line numbers of your text.\n   - Before saving a change other files import: `scope: \"package\"` with the edited file as `source` runs reload's worker compiler over every `.malloy` and `.malloynb` file against your edit, so a rename that breaks an importer surfaces now instead of at reload. Each diagnostic carries `model`, the file it points at; files hidden from discovery can appear. If `modelPath` does not exactly match an existing file, a warning says the source was treated as new.\n2. **Save** it to the package's model file.\n3. **Reload** with `reload_package`.\n4. **Run** the new view with `execute_query`.\n\nA reload that fails to compile is safe: your files are left alone and the previously compiled model keeps serving, with the compile errors returned to you. Compile first anyway for faster feedback, and a `scope: \"package\"` dry-run with no `source` uses reload's compiler and file selection (imports across files, every `.malloy` and `.malloynb` file as saved) without touching the served model. Keep the source of truth outside `publisher_data/`, which is not version-controlled and is wiped by a `--init` restart. If these tools are missing, the Publisher you are connected to predates them; fall back to validating with a throwaway `execute_query`. An older Publisher that has `compile_model` but rejects `scope` supports only the append behavior.\n\n## SQL-to-Malloy Quick Reference\n\n| SQL | Malloy |\n|-----|--------|\n| `COUNT(*)` | `count()` |\n| `COUNT(DISTINCT x)` | `count(x)` |\n| `NOW()` | `now` |\n| `CASE WHEN...END` | `pick...when...else` |\n| `col IN ('a','b')` | `col ? 'a' \\| 'b'` |\n| `COALESCE(a,b)` | `a ?? b` |\n| `CAST(x AS type)` | `x::type` |\n| `DATEDIFF(day, a, b)` | `days(a to b)` |\n| `CONCAT(a, b)` or `a \\|\\| b` | `concat(a, b)` |\n| `TIMESTAMP_DIFF(a, b, SECOND)` | `seconds(b to a)` |\n\n## Critical Rules\n\n1. **All keywords require colons**: `source:`, `dimension:`, `measure:`, `view:`\n2. **Use `is` not `as`**: `dimension: name is expression`\n3. **Arrow operator required**: `run: source -> { operations }`\n4. **Specify join type**: `join_one:`, `join_many:`, `join_cross:`\n5. **Safe division**: `revenue / nullif(count, 0)`\n6. **Group definitions under one keyword**: `measure:` then indent fields beneath\n\n## Common Anti-Patterns\n\n```\nWRONG: source flights is ...           RIGHT: source: flights is ...\nWRONG: dimension: x as y               RIGHT: dimension: y is x\nWRONG: count(*)                        RIGHT: count()\nWRONG: count(distinct x)               RIGHT: count(x)\nWRONG: revenue / order_count           RIGHT: revenue / nullif(order_count, 0)\nWRONG: run: src { ... }                RIGHT: run: src -> { ... }\n```\n\n## Reserved Words: Scan Schema First\n\n**Malloy has many reserved words. When in doubt, backtick it.** Most likely to appear as column names:\n\n```\ndate, time, day, month, year, quarter, week, hour, minute, second,\nnumber, string, boolean, type, table, source, index, count, sum, avg, min, max,\ntrue, false, null, is, on, with, all, from, by, in, to, for, select, order_by,\ntop, bottom, desc, asc, row, range, current, window, rank\n```\n\n- `number`: only the bare word needs backticking; `account_number` is fine\n- `source`: reserved; use a different alias like `traffic_source`\n- `string`, `boolean`, `true`, `false`: backtick any column with these exact names\n\n## Gotcha Skills: Read Before Writing Code\n\nThe following skills contain detailed WRONG/RIGHT patterns that prevent the most common Malloy errors. **Read them before writing code:**\n\n- **`skill:malloy-gotchas-modeling`**: Reserved words, NULL checks, date functions, type casts, rename pitfalls, query-based source gotchas, `conn.sql()` anti-pattern\n- **`skill:malloy-gotchas-queries`**: Chart constraints, aggregate filters, joined field aliasing, time truncation vs extraction\n- **`skill:malloy-gotchas-rendering`**: Tag syntax, scale rules, sparkline setup, big_value patterns"
+      body: "# STOP - READ BEFORE WRITING ANY MALLOY CODE\n\n> **AI AGENTS: You MUST review this file before writing Malloy code.** Cross-skill references below use logical `skill:` names; load the referenced skill before acting. Before writing code, also read the gotcha skills: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering`.\n\n## Pre-Flight Checklist\n\n1. **Discover first**: ground yourself before writing ANY code, with the tool that matches what you are modelling.\n   - Modelling data **already in a package**: `get_context` returns that package's sources, views, and fields (with their docs).\n   - Modelling **a database with no package yet**: `get_context` has nothing to return, so use `search_database_schema` instead. It walks the connection's schemas and tables, ranks them against a plain-English description, and gives you each table's columns plus the `source:` line to start from. Take those names verbatim into step 5.\n   Never guess field names either way.\n2. **Search docs proactively**: call `search_malloy_docs` BEFORE writing unfamiliar patterns (window functions, query-based sources, pipelines). Don't guess. Malloy syntax is specific and SQL intuition is often wrong.\n3. **Use `skill:malloy-patterns`** to discover available doc topics (YoY, cohorts, rendering, window functions).\n4. **Check diagnostics** after writing: fix the FIRST error first, errors cascade.\n5. **Read the gotcha skills**: `skill:malloy-gotchas-modeling`, `skill:malloy-gotchas-queries`, and `skill:malloy-gotchas-rendering` prevent the most common mistakes.\n\n**Quick syntax reminders:**\n1. **Backtick reserved words:** `` `Date` ``, `` `Hour` ``, `` `Timestamp` ``, `` `Type` ``, `` `number` ``, `` `source` ``\n2. **Use `having:` for aggregate filters**: not `where:` on measures\n3. **Alias joined fields in `group_by`** if using them in `order_by`\n4. **`count()` counts rows; `count(x)` counts distinct values of `x`**: `count(distinct x)` is deprecated, write `count(x)`\n5. **One tag per line**: `# label=\"Revenue\"` and `# currency` on separate lines\n6. **No fixed scale on measures**: use `# currency` not `# currency=usd0m`\n7. **Cast strings for aggregates:** `avg(score::number)` not `avg(score)`\n8. **Boolean columns:** use `= true` not `= 'true'` (no quotes!)\n9. **Read data files in place:** `.csv`, `.parquet`, `.json`, `.ndjson`, and `.xlsx` all work as-is through `duckdb.table('data/file.ext')`. Never convert a file to another format first, and never read one with python or jq to \"have a look\" first: query it. For `.xlsx`, check the row count before trusting it: a workbook with a title row or a blank spacer reads short and reports no error. (Per-format quirks: `skill:malloy-gotchas-modeling`)\n\n## Planning and `modeling-notes.md`\n\nIf the IDE has a native plan mode, use it for the high-level approach: do data exploration during planning, then present a concrete plan for user approval before writing any files.\n\n`modeling-notes.md` is an expected output of the workflow, not an optional extra. Start it at step 2 (Propose Scope) and grow it as you work: it persists alongside the model, and its value is as the thing the user argues with at step 3, before source files exist; written after the build it can only document decisions already baked in. Record findings and problems as they are found during discovery (`skill:malloy-discover`), and every unconfirmed decision as an open item. Only when there is no writable workspace do the notes live in the conversation instead.\n\nKeep it compact, with these sections:\n\n```markdown\n# Modeling notes - <package>\n## Scope           what was confirmed, what the model is FOR, skip list with reasons\n## Grain and keys  proven by query, not by column name\n## Coverage        coverage cliffs; columns excluded for nullity\n## Decisions       each with its evidence\n## Open decisions  ASSUMPTIONS, NOT CONFIRMED: every threshold or definition the user\n                   has not settled, one entry each, mirrored by a hedge in its #(doc)\n## Validation      reconciliation checks performed, and their results\n```\n\n## 8-Step Modeling Workflow\n\nThe agent orchestrates all steps. Steps marked **(user)** pause for input. Each step has a dedicated skill with full instructions. Read each step's skill **before starting that step**, including the decision skills for steps 1–4 (`skill:malloy-discover`, `skill:malloy-scope`, `skill:malloy-define`). They govern what the model says; skipping them to reach the build skills is how unreviewed business logic ships.\n\n**A field is not complete until it has its definition, `#(doc)` tag, and rendering tags, and any threshold or business convention in it is user-confirmed, distribution-derived, or explicitly flagged in its `#(doc)`** (see `skill:malloy-document` § Mark conventions as conventions). Documentation is part of defining a field, not a separate activity. Read `skill:malloy-document` for full documentation standards (doc string writing, tag ordering).\n\n```\nDISCOVER → SCOPE → SOURCES → DEFINITIONS → BUILD BASE → BUILD JOINED → REVIEW → CURATE\n (silent)  (user)   (user)      (user)       (agent)      (agent)      (user)   (user)\n```\n\n| Step | Skill | What Happens |\n|------|-------|-------------|\n| 1. Discover | `skill:malloy-discover` | Read the model and data; scan sources, fields, distributions; detect prior art. With no package yet, start from `search_database_schema` to find the tables in the connection |\n| 2. Propose Scope | `skill:malloy-scope` | Present findings, user selects focus |\n| 3. Propose Sources | `skill:malloy-define` | Propose source plan, user confirms architecture |\n| 4. Propose Definitions | `skill:malloy-define` | Propose fields per base source, user confirms logic |\n| 5. Build Base Sources | `skill:malloy-model` | Write fully documented base source files (one per table), check diagnostics. Read `skill:malloy-document` for doc standards. |\n| 6. Build Joined Sources | `skill:malloy-model` | Write fully documented joined source files, validate. Read `skill:malloy-document` for doc standards. |\n| 7. Review | (none) | Present the review checklist below; user confirms or corrects |\n| 8. Curate | `skill:malloy-model` | Propose the published surface (an `index.malloy` with `export { ... }`) and access controls (access modifiers, gates); always propose, the user decides whether to apply |\n\n### The pauses are the point\n\nThese are governed semantic models: the business decisions in them must be confirmed by a human subject-matter expert, and the **(user)** steps exist to collect that confirmation. They are real stops, not progress reports. A model can be complete, compiling, and fully documented and still be wrong everywhere it guessed; a capable agent can build the whole thing without pausing once, which is exactly the failure mode this workflow exists to prevent.\n\nWhen a decision goes unanswered (the user explicitly declines to decide, or nobody is there to ask), do not silently proceed as if it were settled. Take your best-supported position, label it an assumption in the field's own `#(doc)` (see `skill:malloy-document` § Mark conventions as conventions), record it under \"Open decisions\" in `modeling-notes.md`, and raise it again at Review. An unlabeled assumption is indistinguishable from a confirmed fact, and misleads everyone downstream.\n\n### Step 7 Review is a checklist, not a summary\n\nPresent these to the user, with answers:\n\n- **Which definitions did the user actually confirm?** List them; everything else is an assumption.\n- **Which thresholds and bucket boundaries did you choose?** For each: the evidence (distribution query, metadata, prior art) and the `#(doc)` hedge that marks it.\n- **Which questions were left unanswered?** Each must already carry a labeled assumption and an \"Open decisions\" entry.\n- **Does the headline metric have more than one defensible definition?** If yes, that is a blocking question: put the candidate definitions to the user with their counts side by side, not in a footnote.\n\nThe user confirming this checklist is what makes the model governed. A summary of what you built is not a checkpoint.\n\nPublishing is out of scope for open-source v1. Self-hosters move a finished model into a served package via git and the host's publish path; see `skill:malloy-publish` for the local-to-served handoff.\n\n**Two paths to a model: both produce the same fully documented result:**\n- **Schema-first:** \"Model my data\" → 8-step workflow above using the relevant skills\n- **Analysis-first:** a data question arrives before any model exists → `skill:malloy-model-as-you-go`. It answers the question with `skill:malloy-analysis`, then codifies what the answer assumed into the model, one question at a time, confirming binding decisions first. The model exists by the end; there is no separate formalize step.\n- **Open-ended exploration** with no intent to keep anything: `skill:malloy-analyze`. If it turns into something worth keeping, formalize via `skill:malloy-model` (`reference/analysis-to-model.md`).\n\n## Agent Behavior\n\n**Research before asking.** Present proposals with evidence. Never ask open-ended questions: propose with data and let the user confirm.\n\n**Use business language.** Say \"I simplified the column name\" not \"reserved word replaced.\" Don't expose Malloy internals unless the user asks.\n\n**Describe what you're doing, not which step you're on.** The user doesn't have the skill files open. Say \"I'll propose which tables to include and how they relate\" not \"Steps 3 and 4.\" Say \"Now I'll write the source files\" not \"Moving to Step 5.\" Explain the purpose of each phase in plain language before doing it.\n\n**Present choices as A/B/C.** When asking the user to choose, use lettered options with one-line descriptions. Mark your recommendation.\n\n**Complete all workflow steps.** Once modeling begins, complete through Review and propose Curate. A field without documentation is not finished. If you lose track, re-read the model and your notes. Suggest notebooks at the end.\n\n## Route by Intent\n\n| User says... | Route to |\n|-------------|----------|\n| \"Model my data\", \"create a model\" | 8-step workflow (`skill:malloy-discover`) |\n| \"Model from LookML\" | 8-step with prior art via `skill:malloy-lookml-review` |\n| \"Explore this data\", \"what's interesting?\", \"show me the top X\" | `skill:malloy-analyze` (EDA) |\n| \"Build a dashboard\", \"create views\" on existing model | `skill:malloy-analyze` (views), plus `skill:malloy-charts` or `skill:malloy-notebooks` as needed |\n| \"Build a model but not sure what metrics\" | `skill:malloy-model-as-you-go`: answer their first real question, codify what it assumed, repeat |\n\n**If the user's first message is a data question** (not \"build me a model\"), route to `skill:malloy-model-as-you-go`. It answers with `skill:malloy-analysis` and grows the model from what each answer assumed, so there is nothing to formalize afterwards.\n\n## Additional Support Skills\n\nThese supplemental skills may also be loaded as needed:\n\n- **`skill:malloy`**: Index of Malloy skills and routing guide\n- **`skill:malloy-debug`**: Fix compile errors and interpret diagnostics\n\n## Publisher MCP Tools\n\nEnsure the Publisher MCP tools are configured before modeling. No server yet? `skill:malloy-getting-started` covers setup, including the one-command scaffolder (`npm create @malloy-publisher/malloy-package@latest <name>`) and why local authoring needs `--watch-env <env>`: start the server without it and your saved edits are never read.\n\n| Tool | Purpose |\n|------|---------|\n| `get_context` | Ground yourself in a package: its sources, views, and fields |\n| `execute_query` | Run ad-hoc queries for validation |\n| `compile_model` | Compile-check a change and get diagnostics back without running a query |\n| `reload_package` | Recompile a package from disk so a saved edit becomes queryable by name |\n| `search_malloy_docs` | Search Malloy docs (call BEFORE unfamiliar patterns) |\n| `search_database_schema` | Find the tables in a database connection by plain-English description, when modelling data that is not in a package yet. Returns each table's columns and the `source:` line to start from. Names and types only: no row value is returned |\n\nNever guess field names. Ground yourself with `get_context` to see the sources and fields a package defines.\n\n### The edit-and-run loop\n\nPublisher compiles each configured package at boot and serves that cached model, so a source or view you add afterwards is not queryable by name until you reload the package. The loop is:\n\n1. **Validate** the change with `compile_model`, picking the scope that matches what you are doing:\n   - Adding a new definition or query: the default (`scope: \"append\"`) compiles your text in the model's namespace. Note its diagnostic positions land in the model-plus-your-text concatenation. Append checks your text against what the model already publishes, so it refuses text that declares its own data root -- `import`, `connection.table(...)` and `connection.sql(...)` are rejected. A `source:` line handed to you by `search_database_schema` is exactly that shape, so validate it at `file` or `package` scope instead.\n   - **Editing an existing definition: `scope: \"file\"`**, with the whole edited file as `source`. It compiles your text AS the file (append would collide with \"Cannot redefine\"), and diagnostics land at the true line numbers of your text.\n   - Before saving a change other files import: `scope: \"package\"` with the edited file as `source` runs reload's worker compiler over every `.malloy` and `.malloynb` file against your edit, so a rename that breaks an importer surfaces now instead of at reload. Each diagnostic carries `model`, the file it points at; files hidden from discovery can appear. If `modelPath` does not exactly match an existing file, a warning says the source was treated as new.\n2. **Save** it to the package's model file.\n3. **Reload** with `reload_package`.\n4. **Run** the new view with `execute_query`.\n\nA reload that fails to compile is safe: your files are left alone and the previously compiled model keeps serving, with the compile errors returned to you. Compile first anyway for faster feedback, and a `scope: \"package\"` dry-run with no `source` uses reload's compiler and file selection (imports across files, every `.malloy` and `.malloynb` file as saved) without touching the served model. Keep the source of truth outside `publisher_data/`, which is not version-controlled and is wiped by a `--init` restart. If these tools are missing, the Publisher you are connected to predates them; fall back to validating with a throwaway `execute_query`. An older Publisher that has `compile_model` but rejects `scope` supports only the append behavior.\n\n## SQL-to-Malloy Quick Reference\n\n| SQL | Malloy |\n|-----|--------|\n| `COUNT(*)` | `count()` |\n| `COUNT(DISTINCT x)` | `count(x)` |\n| `NOW()` | `now` |\n| `CASE WHEN...END` | `pick...when...else` |\n| `col IN ('a','b')` | `col ? 'a' \\| 'b'` |\n| `COALESCE(a,b)` | `a ?? b` |\n| `CAST(x AS type)` | `x::type` |\n| `DATEDIFF(day, a, b)` | `days(a to b)` |\n| `CONCAT(a, b)` or `a \\|\\| b` | `concat(a, b)` |\n| `TIMESTAMP_DIFF(a, b, SECOND)` | `seconds(b to a)` |\n\n## Critical Rules\n\n1. **All keywords require colons**: `source:`, `dimension:`, `measure:`, `view:`\n2. **Use `is` not `as`**: `dimension: name is expression`\n3. **Arrow operator required**: `run: source -> { operations }`\n4. **Specify join type**: `join_one:`, `join_many:`, `join_cross:`\n5. **Safe division**: `revenue / nullif(count, 0)`\n6. **Group definitions under one keyword**: `measure:` then indent fields beneath\n\n## Common Anti-Patterns\n\n```\nWRONG: source flights is ...           RIGHT: source: flights is ...\nWRONG: dimension: x as y               RIGHT: dimension: y is x\nWRONG: count(*)                        RIGHT: count()\nWRONG: count(distinct x)               RIGHT: count(x)\nWRONG: revenue / order_count           RIGHT: revenue / nullif(order_count, 0)\nWRONG: run: src { ... }                RIGHT: run: src -> { ... }\n```\n\n## Reserved Words: Scan Schema First\n\n**Malloy has many reserved words. When in doubt, backtick it.** Most likely to appear as column names:\n\n```\ndate, time, day, month, year, quarter, week, hour, minute, second,\nnumber, string, boolean, type, table, source, index, count, sum, avg, min, max,\ntrue, false, null, is, on, with, all, from, by, in, to, for, select, order_by,\ntop, bottom, desc, asc, row, range, current, window, rank\n```\n\n- `number`: only the bare word needs backticking; `account_number` is fine\n- `source`: reserved; use a different alias like `traffic_source`\n- `string`, `boolean`, `true`, `false`: backtick any column with these exact names\n\n## Gotcha Skills: Read Before Writing Code\n\nThe following skills contain detailed WRONG/RIGHT patterns that prevent the most common Malloy errors. **Read them before writing code:**\n\n- **`skill:malloy-gotchas-modeling`**: Reserved words, NULL checks, date functions, type casts, rename pitfalls, query-based source gotchas, `conn.sql()` anti-pattern\n- **`skill:malloy-gotchas-queries`**: Chart constraints, aggregate filters, joined field aliasing, time truncation vs extraction\n- **`skill:malloy-gotchas-rendering`**: Tag syntax, scale rules, sparkline setup, big_value patterns"
     },
     {
       name: "malloy-notebook-chat",
@@ -325721,7 +326476,7 @@ Steps to follow when the user asks a question:
     {
       name: "malloy-phrase-detection",
       description: "How to phrase search_text on a get_context call so retrieval returns the fields you need instead of a truncated catalog. Covers target-type classification and decomposition patterns.",
-      body: "# Search Target Construction for `get_context`\n\nThe `get_context` tool description defines each field and what a call returns. This skill focuses on the parts you won't get right by default: classifying concepts into target types and splitting ambiguous phrases.\n\n> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.\n\n**Scope of this skill:** the patterns below build `dimension` / `measure` / `view` targets. Phrasing for `source` targets is covered at the end.\n\n**A note on matching:** `get_context` searches over the model (sources, fields, views, and their descriptions), not the distinct categorical *values* stored in the data. To find which literal values a categorical dimension holds, target the dimension, then query its distinct values with `execute_query` (see the patterns below).\n\n## Always send `search_text`\n\n**Do not enumerate.** Omitting `search_text` lists a catalog rather than searching it. Knowing the package narrows *where* to look; it does not substitute for saying *what* you need: if you know the package, that is a reason to scope, not a reason to skip `search_text`. Enumerated listings are capped per source and per entity type, and with no relevance signal the cap drops the fields your question is about while keeping join-path noise.\n\nA bare listing has two legitimate uses. The first is answering \"what data is here?\" when the user has named no subject at all. The second is reading a specific entity you already have the exact name of: scope to its source, set `entity_name`, and pass `search_text: null`, which returns that entity's docstring and Malloy code without spending a search. Every other call carries `search_text` on every target.\n\n## Authoring `search_text` for entity targets\n\nWrite `search_text` as a brief semantic **description** of what you're looking for, not an echo of the user's word. This applies even when you already know the entity name from a prior result: still describe it, don't just repeat the name. That is a rule about how to *phrase* a search, and it does not conflict with the exact-entity lookup above: if you want that one entity's code and docstring rather than a ranked set, pin it with `entity_name` and skip the search entirely. Sending its name back as `search_text` is the move this rule forbids, because it searches for a name instead of either describing a concept or asking for the entity.\n\nOne target per concept is enough: the tool handles phrasing variants internally. Don't pile up dimension targets that point at the same field. Use multiple targets only when they describe genuinely distinct concepts (see \"Non-obvious decomposition patterns\" below).\n\n## Target-type decision guide\n\n- **`dimension`**: categorical attribute to group, filter, or join on. Also used for time and numeric fields.\n  - \"region\" becomes `\"the geographic region\"`\n- **`measure`**: aggregation metric (count, sum, average, rate).\n  - \"total revenue\" becomes `\"the total revenue or sales amount\"`\n- **`view`**: pre-built analysis. Include one whenever the question sounds like a canned report (summary, breakdown, top-N, trend).\n  - \"sales summary\" becomes `\"a summary of sales metrics\"`\n- **`source`**: data domain, for a question that names a subject area rather than fields (phrasing below).\n\n**Resolving categorical values (no value-search target in v1).** When the user names a literal value like \"premium\" or \"New York City\", target the *dimension* it lives on (`\"the subscription tier\"`, `\"the city where the subscriber lives\"`). Then confirm the exact stored string by querying that dimension's distinct values with `execute_query` before you filter on it. The data may store `\"Premium\"`, `\"PREMIUM\"`, `\"NYC\"`, or `\"New York\"`, and only the data tells you which.\n\n## Non-obvious decomposition patterns\n\nThese are the rules you won't apply correctly by default:\n\n1. **Adjective + noun, split.** \"active users\" becomes two dimension targets: one for the attribute (`\"the status of the user account\"`) and one for the noun (`\"the user or account holder\"`). Resolve the modifier (\"active\") to the exact stored value by querying the status dimension's distinct values with `execute_query`.\n2. **Ambiguous concept, cover both types.** \"rating\", \"duration\", and the like could be either a dimension or a measure: create one target of each type.\n3. **Time references are dimensions.** \"last year\" becomes a dimension target for the relevant date field (`\"the date the event occurred\"`).\n4. **Numeric ranges are dimensions.** \"aged 50\", \"revenue over $1M\" become dimension targets; the comparison is applied in the query, not matched as text.\n5. **Categorical strings that look numeric are still dimensions.** \"18-30\", \"<5 days\", \"tier 2\" are stored as literal strings on a dimension. Target that dimension, then confirm the exact string with `execute_query`.\n6. **\"Top N\" without a named measure, add a ranking measure.** \"top 6 products\" becomes a measure for the ranking concept (`\"the performance metric for a product\"`) plus a dimension for the entity. If the measure is explicit (\"top products by total sales\"), use it directly and skip the generic ranking measure.\n7. **Multiple values for one concept, one dimension target.** Several values (\"premium and basic\") still map to a single dimension target for the parent field; enumerate the exact stored values with `execute_query`.\n8. **The quantity asked for is a measure, even when nothing names it.** \"How many titles were released in 2019?\" is asking for a count, but no noun in it is the count: the visible phrases are the subject (\"titles\") and the filter (\"2019\"), and mapping only those yields a `source` and a `dimension` target with no way to answer. Always add a measure target for the quantity itself (`\"the number of titles\"`). This holds for every interrogative that IS the aggregation -- \"how many\", \"how much\", \"how often\" -- and it is the pattern most easily lost when a filter or grouping is the loud part of the sentence. Measured: an answerer got this right on \"How many titles are in the dataset?\" and dropped it on \"How many titles were released in 2019?\", where the year took the attention.\n9. **A population qualifier is a target, and so is the one the question omits.** Words like \"real\", \"actual\", \"genuine\", \"live\" or \"production\" are not filler: they name rows the model marks for exclusion. Target the flag itself (`\"the flag marking synthetic, test or monitoring traffic\"`), not just the noun they modify. Add one such target even when the question carries no qualifier at all, because a table of events, requests, sessions or logs usually holds test, internal or cancelled rows and nothing in the wording will say so. Resolve it to the model's own flag rather than inventing a filter on an id or a name; a hand-rolled exclusion and the documented one rarely select the same rows.\n\n## Worked example\n\n**User:** \"Customer churn in NYC over the last year for premium and basic subscribers\"\n\nThe targets for this question:\n\n| target_type | search_text |\n|---|---|\n| `measure` | `\"the rate at which customers leave the service\"` |\n| `dimension` | `\"the city where the subscriber lives\"` |\n| `dimension` | `\"the date the subscription was canceled\"` |\n| `dimension` | `\"the tier of the subscription\"` |\n| `view` | `\"subscriber churn or retention analysis\"` |\n\nKey moves: time (\"last year\") becomes a dimension on the cancellation date; \"NYC\" and \"premium/basic subscribers\" do not get their own value targets, they resolve to the city and tier dimensions. One `view` target is included to surface any canned churn analysis.\n\nThe response returns the source these fields live on (here `subscriptions`) with the matched fields on its card. Then run `execute_query` to read the city and tier dimensions' distinct values and confirm the exact strings to filter on (\"New York City\" vs \"NYC\", \"premium\" vs \"Premium\").\n\n## Authoring `search_text` for `source` targets\n\nAim for **3-8 words that name the entity and its business process**. Don't include filter values, time ranges, or aggregations: those belong in entity targets.\n\n| Too vague | Over-specific (entity-shaped) | Good |\n|---|---|---|\n| `\"orders\"` | `\"total order revenue by customer last year\"` | `\"customer order history and line items\"` |\n| `\"customer data\"` | `\"premium subscribers who churned in NYC\"` | `\"subscriber accounts and churn\"` |\n| `\"metrics\"` | `\"monthly revenue variance by account\"` | `\"sales pipeline and revenue forecasts\"` |\n\nHeuristics:\n\n1. **Translate, don't echo.** \"How did sales go last month?\" becomes `\"sales order revenue\"`, not `\"sales last month\"`.\n2. **Differentiate by data shape or business process, not by the user's industry, brand, or product category.** Prefer `\"order fulfillment and shipping\"` over `\"ecommerce data\"` when multiple commerce-ish packages exist. Do NOT add words like `\"eyewear\"`, `\"subscription box\"`, `\"Acme Corp\"`, or the user's specific vertical/brand. Source summaries describe data structure, not the customer's vertical, so those words add noise and can hurt matching.\n3. **Retry with alternative phrasings** if the right source isn't in the results before concluding it's missing."
+      body: "# Search Target Construction for `get_context`\n\nThe `get_context` tool description defines each field and what a call returns. This skill focuses on the parts you won't get right by default: classifying concepts into target types and splitting ambiguous phrases.\n\n> **Tool names** are written bare here - `get_context`, `execute_query`, `search_malloy_docs`. The exact prefixed name depends on the host surface; match each against the tools you actually have.\n\n**Scope of this skill:** the patterns below build `dimension` / `measure` / `view` / `dimensional_value` targets. Phrasing for `source` targets is covered at the end.\n\n**A note on matching:** `get_context` searches over the model (sources, fields, views, and their descriptions), and `dimensional_value` targets search the categorical *values* stored in the data. Some servers don't index values; check the tool's description. On one that doesn't, find a literal value by targeting its dimension, then querying its distinct values with `execute_query` (see \"Where value search isn't available\" below).\n\n## Always send `search_text`\n\n**Do not enumerate.** Omitting `search_text` lists a catalog rather than searching it. Knowing the package narrows *where* to look; it does not substitute for saying *what* you need: if you know the package, that is a reason to scope, not a reason to skip `search_text`. Enumerated listings are capped per source and per entity type, and with no relevance signal the cap drops the fields your question is about while keeping join-path noise.\n\nA bare listing has two legitimate uses. The first is answering \"what data is here?\" when the user has named no subject at all. The second is reading a specific entity you already have the exact name of: scope to its source, set `entity_name`, and pass `search_text: null`, which returns that entity's docstring and Malloy code without spending a search. Every other call carries `search_text` on every target.\n\n## Authoring `search_text` for entity targets\n\nWrite `search_text` as a brief semantic **description** of what you're looking for, not an echo of the user's word. This applies even when you already know the entity name from a prior result: still describe it, don't just repeat the name. That is a rule about how to *phrase* a search, and it does not conflict with the exact-entity lookup above: if you want that one entity's code and docstring rather than a ranked set, pin it with `entity_name` and skip the search entirely. Sending its name back as `search_text` is the move this rule forbids, because it searches for a name instead of either describing a concept or asking for the entity.\n\nOne target per concept is enough: the tool handles phrasing variants internally. Don't pile up dimension targets that point at the same field. Use multiple targets only when they describe genuinely distinct concepts (see \"Non-obvious decomposition patterns\" below).\n\n## Target-type decision guide\n\n- **`dimension`**: categorical attribute to group, filter, or join on. Also used for time and numeric fields.\n  - \"region\" becomes `\"the geographic region\"`\n- **`measure`**: aggregation metric (count, sum, average, rate).\n  - \"total revenue\" becomes `\"the total revenue or sales amount\"`\n- **`view`**: pre-built analysis. Include one whenever the question sounds like a canned report (summary, breakdown, top-N, trend).\n  - \"sales summary\" becomes `\"a summary of sales metrics\"`\n- **`dimensional_value`**: a literal value the user named, stored in some dimension. `search_text` is the value itself, the one target where echoing the user's word is right.\n  - \"CyberArk\" stays `\"CyberArk\"`\n  - Best practice is to scope the call to the source that holds the value. An unscoped value search covers every indexed dimension in scope, so it is slow on a large package. If you truly don't know the source, you can leave the scope off, but expect a slow call.\n- **`source`**: data domain, for a question that names a subject area rather than fields (phrasing below).\n\n**Resolving categorical values.** When the user names a literal value like \"premium\" or \"New York City\", send a `dimensional_value` target for it, scoped to its source once you know the source. Filter on the exact string it returns: the data may store `\"Premium\"`, `\"PREMIUM\"`, `\"NYC\"`, or `\"New York\"`, and only the data tells you which.\n\n**Where value search isn't available.** Some servers have no value index and return nothing for a `dimensional_value` target, and on others a particular dimension's values may not be indexed. Then target the *dimension* the value lives on (`\"the subscription tier\"`, `\"the city where the subscriber lives\"`), and confirm the exact stored string by querying that dimension's distinct values with `execute_query` before you filter on it.\n\n## Non-obvious decomposition patterns\n\nThese are the rules you won't apply correctly by default:\n\n1. **Adjective + noun, split.** \"active users\" becomes two dimension targets: one for the attribute (`\"the status of the user account\"`) and one for the noun (`\"the user or account holder\"`). Resolve the modifier (\"active\") to the exact stored value with a `dimensional_value` target, or the status dimension's distinct values where values aren't indexed.\n2. **Ambiguous concept, cover both types.** \"rating\", \"duration\", and the like could be either a dimension or a measure: create one target of each type.\n3. **Time references are dimensions.** \"last year\" becomes a dimension target for the relevant date field (`\"the date the event occurred\"`).\n4. **Numeric ranges are dimensions.** \"aged 50\", \"revenue over $1M\" become dimension targets; the comparison is applied in the query, not matched as text.\n5. **Categorical strings that look numeric are still dimensions.** \"18-30\", \"<5 days\", \"tier 2\" are stored as literal strings on a dimension. Target that dimension, then confirm the exact string with a `dimensional_value` target, or `execute_query` where values aren't indexed.\n6. **\"Top N\" without a named measure, add a ranking measure.** \"top 6 products\" becomes a measure for the ranking concept (`\"the performance metric for a product\"`) plus a dimension for the entity. If the measure is explicit (\"top products by total sales\"), use it directly and skip the generic ranking measure.\n7. **Multiple values for one concept, one dimension target.** Several values (\"premium and basic\") still map to a single dimension target for the parent field; confirm the exact stored values with `dimensional_value` targets, or `execute_query` where values aren't indexed.\n8. **The quantity asked for is a measure, even when nothing names it.** \"How many titles were released in 2019?\" is asking for a count, but no noun in it is the count: the visible phrases are the subject (\"titles\") and the filter (\"2019\"), and mapping only those yields a `source` and a `dimension` target with no way to answer. Always add a measure target for the quantity itself (`\"the number of titles\"`). This holds for every interrogative that IS the aggregation -- \"how many\", \"how much\", \"how often\" -- and it is the pattern most easily lost when a filter or grouping is the loud part of the sentence. Measured: an answerer got this right on \"How many titles are in the dataset?\" and dropped it on \"How many titles were released in 2019?\", where the year took the attention.\n9. **A population qualifier is a target, and so is the one the question omits.** Words like \"real\", \"actual\", \"genuine\", \"live\" or \"production\" are not filler: they name rows the model marks for exclusion. Target the flag itself (`\"the flag marking synthetic, test or monitoring traffic\"`), not just the noun they modify. Add one such target even when the question carries no qualifier at all, because a table of events, requests, sessions or logs usually holds test, internal or cancelled rows and nothing in the wording will say so. Resolve it to the model's own flag rather than inventing a filter on an id or a name; a hand-rolled exclusion and the documented one rarely select the same rows.\n\n## Worked example\n\n**User:** \"Customer churn in NYC over the last year for premium and basic subscribers\"\n\nThe targets for this question:\n\n| target_type | search_text |\n|---|---|\n| `measure` | `\"the rate at which customers leave the service\"` |\n| `dimension` | `\"the city where the subscriber lives\"` |\n| `dimension` | `\"the date the subscription was canceled\"` |\n| `dimension` | `\"the tier of the subscription\"` |\n| `view` | `\"subscriber churn or retention analysis\"` |\n\nKey moves: time (\"last year\") becomes a dimension on the cancellation date; \"NYC\" and \"premium/basic subscribers\" resolve to the city and tier dimensions in this first call, because the source is not known yet and an unscoped value search is slow. One `view` target is included to surface any canned churn analysis.\n\nThe response returns the source these fields live on (here `subscriptions`) with the matched fields on its card. Then send a second call scoped to `subscriptions`, with `dimensional_value` targets for `\"NYC\"`, `\"premium\"` and `\"basic\"`, to get the exact strings to filter on (\"New York City\" vs \"NYC\", \"premium\" vs \"Premium\"). Where values aren't indexed, run `execute_query` on the city and tier dimensions' distinct values instead.\n\n## Authoring `search_text` for `source` targets\n\nAim for **3-8 words that name the entity and its business process**. Don't include filter values, time ranges, or aggregations: those belong in entity targets.\n\n| Too vague | Over-specific (entity-shaped) | Good |\n|---|---|---|\n| `\"orders\"` | `\"total order revenue by customer last year\"` | `\"customer order history and line items\"` |\n| `\"customer data\"` | `\"premium subscribers who churned in NYC\"` | `\"subscriber accounts and churn\"` |\n| `\"metrics\"` | `\"monthly revenue variance by account\"` | `\"sales pipeline and revenue forecasts\"` |\n\nHeuristics:\n\n1. **Translate, don't echo.** \"How did sales go last month?\" becomes `\"sales order revenue\"`, not `\"sales last month\"`.\n2. **Differentiate by data shape or business process, not by the user's industry, brand, or product category.** Prefer `\"order fulfillment and shipping\"` over `\"ecommerce data\"` when multiple commerce-ish packages exist. Do NOT add words like `\"eyewear\"`, `\"subscription box\"`, `\"Acme Corp\"`, or the user's specific vertical/brand. Source summaries describe data structure, not the customer's vertical, so those words add noise and can hurt matching.\n3. **Retry with alternative phrasings** if the right source isn't in the results before concluding it's missing."
     },
     {
       name: "malloy-publish",
@@ -325774,28 +326529,47 @@ If it doesn't exist, create one. Suggest a package name based on the model conte
 
 ### Curating discovery & the query boundary (optional)
 
-By default a package exposes **everything**: every model is listed and every source is directly queryable. That's the right behavior for most packages, and it's the safe default: **omit these fields and nothing changes.** Reach for them when you have raw/staging/scaffolding sources that exist to build a curated entry point and you don't want agents landing on (or querying) them directly.
+A package with no \`index.malloy\` and no \`explores\` exposes **everything**: every model is listed and every source is directly queryable.
+
+To curate, add an **\`index.malloy\`** at the package root. Publisher reads it as the package's published surface, so no manifest field is involved:
+
+\`\`\`malloy
+// index.malloy
+import "order_analysis.malloy"
+import "staging.malloy"
+
+export { orders, customers }
+\`\`\`
+
+What it exports is what agents discover **and** what may be queried. Everything else still compiles, and other models can import, join and extend it, but a direct query against it is refused with a 404 - indistinguishable from a source that does not exist. Reach for this when you have raw/staging/scaffolding sources that exist to build a curated entry point and you don't want agents landing on, or querying, them directly.
+
+**Address queries to the surface.** Once a package has an \`index.malloy\`, \`.../models/staging.malloy/query\` is no longer a query entry point, *even for a source that file declares itself*. Use \`.../models/index.malloy/query\`. If you are debugging a refusal rather than authoring, \`skill:malloy-source-unreachable\` covers the three ways a source can be out of reach and how to tell them apart.
+
+**A surface can be layered.** An \`index.malloy\` may front a file that fronts another. A source re-exported through a chain of files stays queryable through the surface at any depth, because admission follows the declaration rather than the path taken to it.
 
-Two optional fields opt the package into curation:
+**Curation hides a landing point, not a column.** A published source may \`join\` an unpublished one, and a query grouping by a joined field returns that field's values normally. If a column must not be readable, do not join it into something you publish; gate it with \`#(authorize)\` instead.
+
+**Leaving a source out does not put it out of reach, but there is a condition.** \`export { ... }\` also decides what an *importing* file may see, which is Malloy's rule rather than Publisher's. A file that declares no \`export\` hands an importer everything it declares, so an unpublished source stays importable and joinable from the file that declares it. A file that *does* declare one hands over exactly that list: importing a file whose \`export\` omits a source and then naming it fails to compile with \`Reference to undefined object\`. Put an \`export\` on a mid-layer file only when you mean to narrow what its importers can build on, not just what Publisher lists.
+
+**About \`export { … }\`:** the surface filters which *files* are listed; \`export { … }\` (a Malloy statement) filters which *sources within a file* are exposed, and the two compose. You usually don't write it in a leaf model: a file with **no** \`export\` exposes all of its own top-level sources. It must appear after the definitions it names. See [Malloy: Imports & Exports](https://docs.malloydata.dev/documentation/language/imports).
+
+### The older manifest fields
+
+Both still work and are not going away in this release. Both are deprecated where \`index.malloy\` replaces them, and a package using them that way gets a load-time warning naming the replacement. The two uses it cannot replace, an \`explores\` naming several files and \`queryableSources: "all"\`, stay supported without a warning. Do not add either key to a new package that does not need one of those two.
 
 \`\`\`json
 {
   "name": "ecommerce",
-  "version": "0.0.1",
-  "description": "Orders, customers, and revenue analysis",
   "explores": ["order_analysis.malloy", "customer_health.malloy"],
-  "queryableSources": "declared"
+  "queryableSources": "all"
 }
 \`\`\`
 
-- **\`explores\`** (\`string[]\`) - an allowlist of **model file paths** (relative to the package root, not source or view names) whose models agents should discover and land on. Declaring it is the single opt-in for all discovery curation. With \`explores\` set, listings narrow to those files, and within each file to its \`export { ... }\` closure (below), so anything a listed file doesn't export is also dropped. Other files still compile, and can still be imported or joined, but are hidden from listings. Leaving \`explores\` **absent or empty** means every model is listed, unchanged from today, so existing packages don't break when this field is added. An entry that doesn't resolve to a real \`.malloy\` file surfaces in \`exploresWarnings\`; publishing a package that has any is rejected, so fix the path before publishing.
-- **\`queryableSources\`** (\`"declared"\` | \`"all"\`, default \`"declared"\`) - the query boundary. Only takes effect once \`explores\` is set. \`"declared"\` makes queryable == discoverable: only the \`explores\` files and their \`export {}\` closure are valid top-level query targets; other sources still compile, import, and join, but a direct query against one is denied. \`"all"\` curates discovery only: every compiled source stays queryable even though \`explores\` narrows what's listed.
-
-**About \`export { … }\`:** \`explores\` filters which *files* are listed; \`export { … }\` (a Malloy statement) filters which *sources within a file* are exposed, the two compose. You usually don't write it: a file with **no** \`export\` exposes all of its own top-level sources. Add \`export { orders, customers }\` to a file to expose only those and keep imported/scaffolding helpers out of discovery (it must appear after the definitions it names). See [Malloy: Imports & Exports](https://docs.malloydata.dev/documentation/language/imports).
+- **\`explores\`** (\`string[]\`) - model file paths relative to the package root, naming the surface. Reach for it for the one thing \`index.malloy\` cannot express: a surface spanning **several** files. An explicit \`explores\` always wins over the convention, and a package with both an \`index.malloy\` and an \`explores\` that omits it carries a warning saying so. An entry that doesn't resolve to a real \`.malloy\` file surfaces in \`exploresWarnings\`; publishing a package that has any is rejected, so fix the path before publishing. An explicit \`"explores": []\` means "do not curate" and suppresses the convention.
+- **\`queryableSources\`** (\`"declared"\` | \`"all"\`, default \`"declared"\`) - the query boundary. \`"declared"\` is already the default, so the key changes nothing. **\`"all"\` is the exception, and \`index.malloy\` does not replace it:** it curates listings while leaving every source queryable by name, and a surface derived from an \`index.malloy\` always enforces the boundary. If you want listings-only curation, keep both keys.
 
-**Why curate here:** declaring \`explores\` routes agents to the well-documented curated sources instead of raw tables, and \`queryableSources: "declared"\` keeps them from reaching the hidden sources by name. The two axes compose: list a file in \`explores\` for its models to be discoverable, and \`export\` a source within that file for it to be a landing point.
 
-> **Not access control.** \`queryableSources\` gates the query surface (the query endpoints, REST and MCP alike), not compile and not raw file retrieval by exact path: \`/compile\` and \`compile_model\` are deliberately exempt, because compile is the authoring loop and the boundary is discovery curation. It doesn't restrict *who* may query, only *what* is queryable by name. Queryable sources are the union of every \`explores\`-listed file's \`export {}\` closure, whichever listed model path a query addresses them through. To gate access by caller-supplied identity/role, use \`#(authorize)\` on the source (and \`#(access_filter)\` to scope rows), see \`skill:malloy-model\` § Access Control and \`docs/authorize.md\`. Discovery curation and these gates are independent layers.
+> **Not access control.** The surface gates the query surface (the query endpoints, REST and MCP alike), not compile and not raw file retrieval by exact path: \`/compile\` and \`compile_model\` are deliberately exempt, because compile is the authoring loop and the boundary is discovery curation. It doesn't restrict *who* may query, only *what* is queryable by name. Queryable sources are the union of every listed file's \`export {}\` closure, whichever listed model path a query addresses them through. To gate access by caller-supplied identity/role, use \`#(authorize)\` on the source (and \`#(access_filter)\` to scope rows), see \`skill:malloy-model\` § Access Control and \`docs/authorize.md\`. Discovery curation and these gates are independent layers.
 
 The manifest also carries a \`scope\` field (\`"package"\` | \`"version"\`, default \`"package"\`) controlling whether persisted/materialized artifacts are shared across published versions or owned by a single version, and a \`materialization\` field configuring that persistence policy (a cron \`schedule\` or a \`freshness\` window). Both are unrelated to discovery curation; there is no per-source \`sharing\` or \`schedule\` field, that was retired in favor of the single package-level \`scope\` and \`materialization\`.
 
@@ -326798,6 +327572,74 @@ Then hand off to modeling: use your modeling workflow to turn the confirmed scop
 ## Done
 
 Scope confirmed, in the conversation and in \`modeling-notes.md\`: tables in scope, analytical focus, model kind and what it rules out, and what's deferred. Continue with your modeling workflow.`
+    },
+    {
+      name: "malloy-source-unreachable",
+      description: `Work out why a source is missing from get_context, or why a query against it was refused with a 404 or a 403, and what to do next. Use when a source you expect is absent from discovery, when execute_query answers "No queryable source", when a query that used to work stops working, or when deciding whether a package's curation is hiding something you need.`,
+      body: `# A source you cannot reach
+
+> **Tool names** are written bare here - \`get_context\`, \`execute_query\`, \`get_status\`, \`compile_model\`. The exact prefixed name depends on the host surface; match each against the tools you actually have.
+
+Most packages publish a curated surface, so a source being absent or refused is usually the package working as its author intended, not a fault. Read the refusal before working around it, because the three things that can refuse you need three different responses and they are told apart by the status code.
+
+## The three answers
+
+| what you got | what it means | what to do |
+| --- | --- | --- |
+| **404**, "No queryable source", "No queryable model" or "Query target is not queryable" | the source is not on the package's published surface, or does not exist. The two are deliberately indistinguishable so that a refusal cannot be used to probe for hidden names | query something on the surface, or ask the package's author to publish it |
+| **403**, "Access denied" | the source exists and is on the surface, but an \`#(authorize)\` gate did not admit you | supply the givens the gate reads, or accept that this caller may not read it |
+| **200** with zero rows | you were admitted, and an \`#(access_filter)\` narrowed the rows to none of them | this is a real answer. Report it as "no matching rows", never as an error |
+
+A 403 names a source, so it tells you the source exists. A 404 tells you nothing at all. That asymmetry is deliberate: a source that is both hidden AND gated answers **404**, so you can never use a 403 to discover that a hidden name is real.
+
+## Addressing the surface, which is the most common 404
+
+A query names a model file. When a package curates its surface, only files on that surface are valid entry points, **even for a source that file declares itself**:
+
+\`\`\`
+POST .../packages/sales/models/index.malloy/query    {"sourceName": "orders"}   -> 200
+POST .../packages/sales/models/orders.malloy/query   {"sourceName": "orders"}   -> 404
+\`\`\`
+
+Same source, same package. \`orders.malloy\` is off the surface, so it is not an entry point.
+
+**Use the \`model_path\` that \`get_context\` gave you, verbatim.** Its \`source_info.resource_id\` holds \`environment\`, \`package\`, \`model_path\` and \`source\`, and those are exactly \`execute_query\`'s \`environmentName\`, \`packageName\`, \`modelPath\` and \`sourceName\`. On a curated package the \`model_path\` is the surface file, not the file that declares the source. Substituting the declaring file because it looks more correct is how this 404 happens.
+
+## When the source is not in \`get_context\` at all
+
+Work down this list. The first three are far more common than the last.
+
+1. **It is off the surface.** The package publishes a curated set and this source is not in it. Nothing you can do from the query side; it is a package edit.
+2. **The package failed to load, or is serving a stale model.** Call \`get_status\`. A package that never loaded is absent from listings entirely, which reads exactly like "does not exist". A package whose last reload failed to compile is listed and answering, from the model it compiled *before* that save, and carries \`stale: true\`. Neither is visible from a listing alone.
+3. **You are talking to a different server than you think.** Call \`list_packages\` and check the environment and package names are the ones you expect. A stale \`.mcp.json\` outlives the server that wrote it, and another Publisher may hold that port.
+4. **Your search phrasing missed it.** Retry with a bare target (no \`search_text\`) to enumerate rather than rank. If it appears there, the source exists and was a ranking miss.
+
+## What curation does not do
+
+- **It does not hide fields.** A published source may \`join\` an unpublished one, and a query grouping by a joined field returns that field's values normally. Hiding a source removes it as a landing point; it does not redact columns a published source pulls in.
+- **It does not gate \`/compile\`.** \`compile_model\` is exempt, because compile is the authoring loop. A hidden source can still be compile-checked, and that is intended. The exception is a hidden source that is also gated, which answers 404 at compile too.
+- **It is not access control.** Curation answers "what is queryable by name", not "who may query it". Identity is \`#(authorize)\` and \`#(access_filter)\`. A source is not protected by being hidden.
+
+## Reaching an unpublished source from your own model
+
+If you are writing Malloy rather than just querying, an unpublished source is still usable, with one condition that trips people.
+
+\`export { ... }\` decides what an **importing file** can see, which is Malloy's rule and not Publisher's:
+
+- a file that declares **no** \`export\` hands an importer everything it declares, so import the file that declares the source and join it normally;
+- a file that **does** declare one hands over exactly that list. Importing a file whose \`export\` omits the source and then naming it fails to compile with \`Reference to undefined object\`.
+
+So an unpublished source is reachable through a file that exports it, or that exports nothing, and not through a file whose \`export\` leaves it out. Re-export chains are fine at any depth: a source re-exported through several files stays queryable through the surface, because admission follows the declaration rather than the path taken to it.
+
+## Before you report a source as missing
+
+Confirm all three, in this order. Each one has been mistaken for "the data is not there".
+
+1. \`get_status\` shows the package loaded and not \`stale\`.
+2. \`list_packages\` names the environment and package you meant.
+3. An enumerating \`get_context\` call (a target with no \`search_text\`) does not list it.
+
+Only then is it genuinely not published, and the answer to the user is that the package does not expose it, not that the data does not exist.`
     }
   ]
 };
@@ -328767,6 +329609,25 @@ function tallySources(entries, failures, carried) {
     sourcesReused: Object.keys(carried).filter((id) => !failures[id]).length
   };
 }
+function refusalRecord(persistSource, err, tier, modelPath) {
+  return {
+    name: persistSource.name,
+    sourceID: persistSource.sourceID,
+    ...modelPath ? { modelPath } : {},
+    tier,
+    reason: err.reason || "authorize",
+    message: errMessage(err)
+  };
+}
+function allSourcesRefusedError(errors2) {
+  if (errors2.length === 1)
+    return errors2[0];
+  const reason = errors2.every((e) => e.reason === errors2[0].reason) ? errors2[0].reason : undefined;
+  return new MaterializationEligibilityError({
+    message: errors2.map((e) => e.message).join("; "),
+    reason
+  });
+}
 function redactConnectionSecrets(message, ...connections) {
   const secrets = new Set;
   const seen = new WeakSet;
@@ -328949,6 +329810,7 @@ class MaterializationService {
       });
       let instructions;
       let carried;
+      let derivedRefused = {};
       if (orchestrated) {
         instructions = opts.buildInstructions;
         carried = this.referenceManifestToEntries(opts.referenceManifest);
@@ -328958,9 +329820,17 @@ class MaterializationService {
         }
       } else {
         const priorEntries = opts.forceRefresh ? {} : await this.getMostRecentManifestEntries(environmentId, packageName, id);
-        ({ instructions, carried } = this.deriveSelfInstructions(compiled, opts.sourceNames, priorEntries, incremental));
+        ({
+          instructions,
+          carried,
+          refused: derivedRefused
+        } = this.deriveSelfInstructions(compiled, opts.sourceNames, priorEntries, incremental));
       }
-      const { entries, failures } = await this.executeInstructedBuild(compiled, environment, instructions, carried, signal, opts.strictUpstreams ?? false, orchestrated ? { environmentId, packageName } : undefined, {
+      const {
+        entries,
+        failures,
+        sourcesRefused: instructedRefused
+      } = await this.executeInstructedBuild(compiled, environment, instructions, carried, signal, opts.strictUpstreams ?? false, orchestrated ? { environmentId, packageName } : undefined, {
         packageMaterialization: pkg.getMaterializationConfig?.() ?? null,
         context: {
           queryClass: "materialize",
@@ -328969,8 +329839,9 @@ class MaterializationService {
           trigger: opts.runContext?.trigger ?? opts.trigger?.toLowerCase(),
           runId: opts.runContext?.runId ?? id
         }
-      }, incremental);
+      }, incremental, Object.values(derivedRefused));
       const { sourcesBuilt, sourcesFailed, sourcesReused } = tallySources(entries, failures, carried);
+      const sourcesRefused = Object.keys(derivedRefused).length + instructedRefused;
       const durationMs = Date.now() - startedAt;
       await this.commitManifest(id, entries, failures, {
         forceRefresh: opts.forceRefresh,
@@ -328979,24 +329850,27 @@ class MaterializationService {
         trigger: opts.trigger,
         sourcesBuilt,
         sourcesReused,
+        ...sourcesRefused > 0 ? { sourcesRefused } : {},
+        ...Object.keys(derivedRefused).length > 0 ? { refusedSources: derivedRefused } : {},
         durationMs
       });
       if (!orchestrated) {
         await this.autoLoadManifest(environment, packageName, entries);
       }
-      recordSourcesOutcome("built", sourcesBuilt);
-      recordSourcesOutcome("reused", sourcesReused);
-      if (sourcesFailed > 0) {
-        recordSourcesOutcome("failed", sourcesFailed);
-      }
-      this.recordRun(mode, sourcesFailed > 0 ? "partial" : "success", startedAt);
-      logger[sourcesFailed > 0 ? "warn" : "info"](sourcesFailed > 0 ? "Materialization build complete with failed sources" : "Materialization build complete", {
+      recordSourcesOutcome("built", sourcesBuilt, mode);
+      recordSourcesOutcome("reused", sourcesReused, mode);
+      recordSourcesOutcome("failed", sourcesFailed - instructedRefused, mode);
+      recordSourcesOutcome("refused", sourcesRefused, mode);
+      const partial = sourcesFailed > 0;
+      this.recordRun(mode, partial ? "partial" : "success", startedAt);
+      logger[partial || sourcesRefused > 0 ? "warn" : "info"](sourcesFailed > 0 ? "Materialization build complete with failed sources" : sourcesRefused > 0 ? "Materialization build complete with refused sources" : "Materialization build complete", {
         materializationId: id,
         packageName,
         mode,
         sourcesBuilt,
         sourcesReused,
         sourcesFailed,
+        sourcesRefused,
         durationMs
       });
     } catch (err) {
@@ -329008,6 +329882,8 @@ class MaterializationService {
     const include = sourceNames ? new Set(sourceNames) : null;
     const instructions = [];
     const carried = {};
+    const refused = {};
+    const refusals = [];
     const seen = new Set;
     for (const graph of compiled.graphs) {
       for (const persistSource of iterGraphSources(graph, compiled.sources)) {
@@ -329017,24 +329893,28 @@ class MaterializationService {
           continue;
         }
         const destination = resolveStorageDestination(persistSource);
-        if (destination) {
-          if (compiled.preaggregatePlans?.[persistSource.sourceID]) {
-            try {
-              assertMaterializationEligible(persistSource, deriveAnnotationFields(persistSource));
-            } catch (err) {
-              if (!(err instanceof MaterializationEligibilityError))
-                throw err;
-              logger.warn("Skipping a pre-aggregation rollup the storage tier refuses", {
-                sourceName: persistSource.name,
-                reason: errMessage(err)
-              });
-              continue;
-            }
-          } else {
+        const isRollup = !!compiled.preaggregatePlans?.[persistSource.sourceID];
+        try {
+          if (destination) {
             assertMaterializationEligible(persistSource, deriveAnnotationFields(persistSource));
+          } else {
+            assertColocatedPersistNotAuthorizeGated(persistSource, persistSource.name, isRollup ? "preaggregate" : "persist", compiled.sourceGateOutcomes?.[persistSource.sourceID], deriveAnnotationFields(persistSource));
           }
-        } else {
-          assertColocatedPersistNotAuthorizeGated(persistSource, persistSource.name, compiled.preaggregatePlans?.[persistSource.sourceID] ? "preaggregate" : "persist", compiled.sourceGateOutcomes?.[persistSource.sourceID], deriveAnnotationFields(persistSource));
+        } catch (err) {
+          if (!(err instanceof MaterializationEligibilityError))
+            throw err;
+          if (include)
+            throw err;
+          if (!refused[persistSource.sourceID]) {
+            refused[persistSource.sourceID] = refusalRecord(persistSource, err, isRollup ? "preaggregate" : destination ? "storage" : "colocated", compiled.sourceModelPaths?.[persistSource.sourceID]);
+            if (!isRollup)
+              refusals.push(err);
+            logger.warn("Skipping a persist source the eligibility gate refuses", {
+              sourceName: persistSource.name,
+              reason: errMessage(err)
+            });
+          }
+          continue;
         }
         const sourceEntityId = computeSourceEntityId(persistSource, compiled.connectionDigests);
         if (seen.has(sourceEntityId))
@@ -329064,7 +329944,10 @@ class MaterializationService {
         });
       }
     }
-    return { instructions, carried };
+    if (refusals.length > 0 && instructions.length === 0 && Object.keys(carried).length === 0) {
+      throw allSourcesRefusedError(refusals);
+    }
+    return { instructions, carried, refused };
   }
   referenceManifestToEntries(referenceManifest) {
     const entries = {};
@@ -329157,8 +330040,9 @@ class MaterializationService {
     return {};
   }
   async autoLoadManifest(environment, packageName, entries) {
+    const builtEntries = Object.fromEntries(Object.entries(entries).filter(([, entry]) => !isLegacyFailedEntry(entry)));
     const manifestEntries = {};
-    for (const [sourceEntityId, entry] of Object.entries(entries)) {
+    for (const [sourceEntityId, entry] of Object.entries(builtEntries)) {
       if (entry.physicalTableName && !entry.storageDestinationName) {
         manifestEntries[sourceEntityId] = {
           tableName: entry.physicalTableName,
@@ -329168,7 +330052,7 @@ class MaterializationService {
     }
     try {
       await environment.reloadAllModelsForPackage(packageName, manifestEntries);
-      await environment.bindPackageStorageServeBindings(packageName, entries);
+      await environment.bindPackageStorageServeBindings(packageName, builtEntries);
       recordAutoLoadOutcome("success");
       logger.info("Auto-run: loaded manifest into package models", {
         packageName,
@@ -329269,7 +330153,7 @@ class MaterializationService {
       ...ledger !== undefined ? { callerLedger: indexCallerLedger(ledger) } : {}
     };
   }
-  async executeInstructedBuild(compiled, environment, instructions, seedEntries, signal, strict = false, owner, buildMetadata, incremental) {
+  async executeInstructedBuild(compiled, environment, instructions, seedEntries, signal, strict = false, owner, buildMetadata, incremental, priorRefusals = []) {
     const { graphs, sources, connectionDigests, connections } = compiled;
     const bySourceID = new Map;
     const bySourceEntityId = new Map;
@@ -329305,6 +330189,7 @@ class MaterializationService {
     const retainedThisRun = [];
     const failures = {};
     const failedReasons = [];
+    const refusals = [];
     const builtSources = [];
     const writtenTargets = new Map;
     const claimedBy = new Map;
@@ -329371,10 +330256,44 @@ class MaterializationService {
           }
           if (!instruction)
             continue;
-          if (orchestratedInstruction?.destination && getPersistStorageMode() !== "off") {
-            assertMaterializationEligible(persistSource, deriveAnnotationFields(persistSource));
-          } else {
-            assertColocatedPersistNotAuthorizeGated(persistSource, persistSource.name, compiled.preaggregatePlans?.[persistSource.sourceID] ? "preaggregate" : "persist", compiled.sourceGateOutcomes?.[persistSource.sourceID], deriveAnnotationFields(persistSource));
+          try {
+            if (orchestratedInstruction?.destination && getPersistStorageMode() !== "off") {
+              assertMaterializationEligible(persistSource, deriveAnnotationFields(persistSource));
+            } else {
+              assertColocatedPersistNotAuthorizeGated(persistSource, persistSource.name, compiled.preaggregatePlans?.[persistSource.sourceID] ? "preaggregate" : "persist", compiled.sourceGateOutcomes?.[persistSource.sourceID], deriveAnnotationFields(persistSource));
+            }
+          } catch (err) {
+            if (!(err instanceof MaterializationEligibilityError))
+              throw err;
+            const failedKey = sourceEntityId ?? instruction.sourceEntityId;
+            if (!failures[failedKey]) {
+              const reason = errMessage(err);
+              refusals.push(err);
+              logger.warn("Instructed source refused by the eligibility gate", {
+                packageName: owner?.packageName,
+                sourceName: persistSource.name,
+                physicalTableName: instruction.physicalTableName,
+                reason
+              });
+              failures[failedKey] = {
+                sourceEntityId: failedKey,
+                sourceName: persistSource.name,
+                materializedTableId: instruction.materializedTableId,
+                physicalTableName: instruction.physicalTableName,
+                reason,
+                refused: true,
+                connectionName: persistSource.connectionName,
+                ...instruction.destination ? { storageDestinationName: instruction.destination } : {}
+              };
+              entries[failedKey] = {
+                sourceEntityId: failedKey,
+                sourceName: persistSource.name,
+                physicalTableName: instruction.physicalTableName,
+                materializedTableId: instruction.materializedTableId,
+                error: reason
+              };
+            }
+            continue;
           }
           sourceEntityId ??= computeSourceEntityId(persistSource, connectionDigests);
           if (!orchestratedInstruction && instruction.destination && getPersistStorageMode() !== "off") {
@@ -329451,7 +330370,14 @@ class MaterializationService {
         }
       }
       if (builtSources.length === 0 && failedReasons.length > 0) {
-        throw new Error(failedReasons.join("; "));
+        throw new Error([
+          ...failedReasons,
+          ...refusals.map((e) => e.message),
+          ...priorRefusals.map((r) => r.message)
+        ].join("; "));
+      }
+      if (builtSources.length === 0 && refusals.length > 0) {
+        throw allSourcesRefusedError(refusals);
       }
     } catch (err) {
       if (owner) {
@@ -329460,7 +330386,7 @@ class MaterializationService {
       }
       throw err;
     }
-    return { entries, failures };
+    return { entries, failures, sourcesRefused: refusals.length };
   }
   destinationForCleanup(environment, destinationName) {
     try {
@@ -331190,6 +332116,22 @@ function rateLimitMiddleware(perMinute) {
   });
 }
 
+// src/frame_ancestors.ts
+var FRAME_ANCESTORS_ENV = "PUBLISHER_FRAME_ANCESTORS";
+function frameAncestorsMiddleware(raw) {
+  const frameAncestors = parseFrameAncestors(raw);
+  return (_req, res, next) => {
+    res.setHeader("Content-Security-Policy", `frame-ancestors ${frameAncestors}`);
+    res.removeHeader("X-Frame-Options");
+    next();
+  };
+}
+function parseFrameAncestors(raw) {
+  if (raw === undefined || raw.trim() === "")
+    return "'self'";
+  return raw.trim();
+}
+
 // src/server.ts
 assertSupportedNodeVersion();
 function parseArgs() {
@@ -331281,6 +332223,7 @@ var isDevelopment = process.env["NODE_ENV"] === "development";
 var app = import_express.default();
 app.use(loggerMiddleware);
 app.use(httpMetricsMiddleware);
+app.use(frameAncestorsMiddleware(process.env[FRAME_ANCESTORS_ENV]));
 app.use(rateLimitMiddleware(parseRateLimit(process.env[RATE_LIMIT_ENV])));
 checkHeapConfiguration();
 var environmentStore = new EnvironmentStore(SERVER_ROOT);
@@ -331434,12 +332377,6 @@ async function serveFromPackage(req, res) {
       res.status(403).end();
       return;
     }
-    const ext = path17.extname(realFullPath).toLowerCase();
-    if (ext === ".html" || ext === ".htm") {
-      const frameAncestors = process.env.PUBLISHER_FRAME_ANCESTORS || "*";
-      res.setHeader("Content-Security-Policy", `frame-ancestors ${frameAncestors}`);
-      res.removeHeader("X-Frame-Options");
-    }
     res.setHeader("X-Content-Type-Options", "nosniff");
     res.sendFile(realFullPath, (err) => {
       if (err) {