@malloy-publisher/server 0.7.0 → 0.8.0

package/dist/server.mjs

@@ -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;
@@ -275083,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";
@@ -275959,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);
@@ -276385,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];
@@ -276392,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();
@@ -276519,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,
@@ -276533,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}`);
@@ -276664,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);
@@ -276749,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);
@@ -276885,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;
       }
@@ -276900,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;
       }
@@ -277045,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) {
@@ -309253,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();
@@ -309382,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
@@ -310271,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) {
@@ -310451,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}`);
@@ -311124,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}`);
@@ -311656,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 {
@@ -311884,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;
           }
         }
@@ -311944,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();
@@ -311969,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;
@@ -317195,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.
 
@@ -319067,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",
@@ -319977,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",
@@ -320236,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
@@ -320416,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
@@ -320661,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
@@ -322012,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> \\
@@ -323155,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
@@ -324059,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",
@@ -324936,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",
@@ -325928,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 the published surface (an `index.malloy` with `export { ... }`) and access controls (access modifiers, gates); always propose, the user decides whether to apply |\n\n### The pauses are the point\n\nThese are governed semantic models: the business decisions in them must be confirmed by a human subject-matter expert, and the **(user)** steps exist to collect that confirmation. They are real stops, not progress reports. A model can be complete, compiling, and fully documented and still be wrong everywhere it guessed; a capable agent can build the whole thing without pausing once, which is exactly the failure mode this workflow exists to prevent.\n\nWhen a decision goes unanswered (the user explicitly declines to decide, or nobody is there to ask), do not silently proceed as if it were settled. Take your best-supported position, label it an assumption in the field's own `#(doc)` (see `skill:malloy-document` § Mark conventions as conventions), record it under \"Open decisions\" in `modeling-notes.md`, and raise it again at Review. An unlabeled assumption is indistinguishable from a confirmed fact, and misleads everyone downstream.\n\n### Step 7 Review is a checklist, not a summary\n\nPresent these to the user, with answers:\n\n- **Which definitions did the user actually confirm?** List them; everything else is an assumption.\n- **Which thresholds and bucket boundaries did you choose?** For each: the evidence (distribution query, metadata, prior art) and the `#(doc)` hedge that marks it.\n- **Which questions were left unanswered?** Each must already carry a labeled assumption and an \"Open decisions\" entry.\n- **Does the headline metric have more than one defensible definition?** If yes, that is a blocking question: put the candidate definitions to the user with their counts side by side, not in a footnote.\n\nThe user confirming this checklist is what makes the model governed. A summary of what you built is not a checkpoint.\n\nPublishing is out of scope for open-source v1. Self-hosters move a finished model into a served package via git and the host's publish path; see `skill:malloy-publish` for the local-to-served handoff.\n\n**Two paths to a model: both produce the same fully documented result:**\n- **Schema-first:** \"Model my data\" → 8-step workflow above using the relevant skills\n- **Analysis-first:** a data question arrives before any model exists → `skill:malloy-model-as-you-go`. It answers the question with `skill:malloy-analysis`, then codifies what the answer assumed into the model, one question at a time, confirming binding decisions first. The model exists by the end; there is no separate formalize step.\n- **Open-ended exploration** with no intent to keep anything: `skill:malloy-analyze`. If it turns into something worth keeping, formalize via `skill:malloy-model` (`reference/analysis-to-model.md`).\n\n## Agent Behavior\n\n**Research before asking.** Present proposals with evidence. Never ask open-ended questions: propose with data and let the user confirm.\n\n**Use business language.** Say \"I simplified the column name\" not \"reserved word replaced.\" Don't expose Malloy internals unless the user asks.\n\n**Describe what you're doing, not which step you're on.** The user doesn't have the skill files open. Say \"I'll propose which tables to include and how they relate\" not \"Steps 3 and 4.\" Say \"Now I'll write the source files\" not \"Moving to Step 5.\" Explain the purpose of each phase in plain language before doing it.\n\n**Present choices as A/B/C.** When asking the user to choose, use lettered options with one-line descriptions. Mark your recommendation.\n\n**Complete all workflow steps.** Once modeling begins, complete through Review and propose Curate. A field without documentation is not finished. If you lose track, re-read the model and your notes. Suggest notebooks at the end.\n\n## Route by Intent\n\n| User says... | Route to |\n|-------------|----------|\n| \"Model my data\", \"create a model\" | 8-step workflow (`skill:malloy-discover`) |\n| \"Model from LookML\" | 8-step with prior art via `skill:malloy-lookml-review` |\n| \"Explore this data\", \"what's interesting?\", \"show me the top X\" | `skill:malloy-analyze` (EDA) |\n| \"Build a dashboard\", \"create views\" on existing model | `skill:malloy-analyze` (views), plus `skill:malloy-charts` or `skill:malloy-notebooks` as needed |\n| \"Build a model but not sure what metrics\" | `skill:malloy-model-as-you-go`: answer their first real question, codify what it assumed, repeat |\n\n**If the user's first message is a data question** (not \"build me a model\"), route to `skill:malloy-model-as-you-go`. It answers with `skill:malloy-analysis` and grows the model from what each answer assumed, so there is nothing to formalize afterwards.\n\n## Additional Support Skills\n\nThese supplemental skills may also be loaded as needed:\n\n- **`skill:malloy`**: Index of Malloy skills and routing guide\n- **`skill:malloy-debug`**: Fix compile errors and interpret diagnostics\n\n## Publisher MCP Tools\n\nEnsure the Publisher MCP tools are configured before modeling. No server yet? `skill:malloy-getting-started` covers setup, including the one-command scaffolder (`npm create @malloy-publisher/malloy-package@latest <name>`) and why local authoring needs `--watch-env <env>`: start the server without it and your saved edits are never read.\n\n| Tool | Purpose |\n|------|---------|\n| `get_context` | Ground yourself in a package: its sources, views, and fields |\n| `execute_query` | Run ad-hoc queries for validation |\n| `compile_model` | Compile-check a change and get diagnostics back without running a query |\n| `reload_package` | Recompile a package from disk so a saved edit becomes queryable by name |\n| `search_malloy_docs` | Search Malloy docs (call BEFORE unfamiliar patterns) |\n| `search_database_schema` | Find the tables in a database connection by plain-English description, when modelling data that is not in a package yet. Returns each table's columns and the `source:` line to start from. Names and types only: no row value is returned |\n\nNever guess field names. Ground yourself with `get_context` to see the sources and fields a package defines.\n\n### The edit-and-run loop\n\nPublisher compiles each configured package at boot and serves that cached model, so a source or view you add afterwards is not queryable by name until you reload the package. The loop is:\n\n1. **Validate** the change with `compile_model`, picking the scope that matches what you are doing:\n   - Adding a new definition or query: the default (`scope: \"append\"`) compiles your text in the model's namespace. Note its diagnostic positions land in the model-plus-your-text concatenation.\n   - **Editing an existing definition: `scope: \"file\"`**, with the whole edited file as `source`. It compiles your text AS the file (append would collide with \"Cannot redefine\"), and diagnostics land at the true line numbers of your text.\n   - Before saving a change other files import: `scope: \"package\"` with the edited file as `source` runs reload's worker compiler over every `.malloy` and `.malloynb` file against your edit, so a rename that breaks an importer surfaces now instead of at reload. Each diagnostic carries `model`, the file it points at; files hidden from discovery can appear. If `modelPath` does not exactly match an existing file, a warning says the source was treated as new.\n2. **Save** it to the package's model file.\n3. **Reload** with `reload_package`.\n4. **Run** the new view with `execute_query`.\n\nA reload that fails to compile is safe: your files are left alone and the previously compiled model keeps serving, with the compile errors returned to you. Compile first anyway for faster feedback, and a `scope: \"package\"` dry-run with no `source` uses reload's compiler and file selection (imports across files, every `.malloy` and `.malloynb` file as saved) without touching the served model. Keep the source of truth outside `publisher_data/`, which is not version-controlled and is wiped by a `--init` restart. If these tools are missing, the Publisher you are connected to predates them; fall back to validating with a throwaway `execute_query`. An older Publisher that has `compile_model` but rejects `scope` supports only the append behavior.\n\n## SQL-to-Malloy Quick Reference\n\n| SQL | Malloy |\n|-----|--------|\n| `COUNT(*)` | `count()` |\n| `COUNT(DISTINCT x)` | `count(x)` |\n| `NOW()` | `now` |\n| `CASE WHEN...END` | `pick...when...else` |\n| `col IN ('a','b')` | `col ? 'a' \\| 'b'` |\n| `COALESCE(a,b)` | `a ?? b` |\n| `CAST(x AS type)` | `x::type` |\n| `DATEDIFF(day, a, b)` | `days(a to b)` |\n| `CONCAT(a, b)` or `a \\|\\| b` | `concat(a, b)` |\n| `TIMESTAMP_DIFF(a, b, SECOND)` | `seconds(b to a)` |\n\n## Critical Rules\n\n1. **All keywords require colons**: `source:`, `dimension:`, `measure:`, `view:`\n2. **Use `is` not `as`**: `dimension: name is expression`\n3. **Arrow operator required**: `run: source -> { operations }`\n4. **Specify join type**: `join_one:`, `join_many:`, `join_cross:`\n5. **Safe division**: `revenue / nullif(count, 0)`\n6. **Group definitions under one keyword**: `measure:` then indent fields beneath\n\n## Common Anti-Patterns\n\n```\nWRONG: source flights is ...           RIGHT: source: flights is ...\nWRONG: dimension: x as y               RIGHT: dimension: y is x\nWRONG: count(*)                        RIGHT: count()\nWRONG: count(distinct x)               RIGHT: count(x)\nWRONG: revenue / order_count           RIGHT: revenue / nullif(order_count, 0)\nWRONG: run: src { ... }                RIGHT: run: src -> { ... }\n```\n\n## Reserved Words: Scan Schema First\n\n**Malloy has many reserved words. When in doubt, backtick it.** Most likely to appear as column names:\n\n```\ndate, time, day, month, year, quarter, week, hour, minute, second,\nnumber, string, boolean, type, table, source, index, count, sum, avg, min, max,\ntrue, false, null, is, on, with, all, from, by, in, to, for, select, order_by,\ntop, bottom, desc, asc, row, range, current, window, rank\n```\n\n- `number`: only the bare word needs backticking; `account_number` is fine\n- `source`: reserved; use a different alias like `traffic_source`\n- `string`, `boolean`, `true`, `false`: backtick any column with these exact names\n\n## Gotcha Skills: Read Before Writing Code\n\nThe following skills contain detailed WRONG/RIGHT patterns that prevent the most common Malloy errors. **Read them before writing code:**\n\n- **`skill:malloy-gotchas-modeling`**: Reserved words, NULL checks, date functions, type casts, rename pitfalls, query-based source gotchas, `conn.sql()` anti-pattern\n- **`skill:malloy-gotchas-queries`**: Chart constraints, aggregate filters, joined field aliasing, time truncation vs extraction\n- **`skill:malloy-gotchas-rendering`**: Tag syntax, scale rules, sparkline setup, big_value patterns"
+      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",
@@ -329095,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;
@@ -329277,6 +329810,7 @@ class MaterializationService {
       });
       let instructions;
       let carried;
+      let derivedRefused = {};
       if (orchestrated) {
         instructions = opts.buildInstructions;
         carried = this.referenceManifestToEntries(opts.referenceManifest);
@@ -329286,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",
@@ -329297,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,
@@ -329307,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) {
@@ -329336,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)) {
@@ -329345,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))
@@ -329392,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 = {};
@@ -329485,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,
@@ -329496,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,
@@ -329597,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;
@@ -329633,6 +330189,7 @@ class MaterializationService {
     const retainedThisRun = [];
     const failures = {};
     const failedReasons = [];
+    const refusals = [];
     const builtSources = [];
     const writtenTargets = new Map;
     const claimedBy = new Map;
@@ -329699,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") {
@@ -329779,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) {
@@ -329788,7 +330386,7 @@ class MaterializationService {
       }
       throw err;
     }
-    return { entries, failures };
+    return { entries, failures, sourcesRefused: refusals.length };
   }
   destinationForCleanup(environment, destinationName) {
     try {
@@ -331518,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() {
@@ -331609,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);
@@ -331762,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) {