@datarails-ai/dr-appspace-cli 0.12.38 → 0.12.39

package/dist/cli.js

@@ -13,7 +13,7 @@ import { fileURLToPath as fileURLToPath6 } from "url";
 // package.json
 var package_default = {
   name: "@datarails-ai/dr-appspace-cli",
-  version: "0.12.38",
+  version: "0.12.39",
   description: "Datarails App Space CLI \u2014 build, try, push and publish App Space apps",
   type: "module",
   engines: {
@@ -57,7 +57,7 @@ var package_default = {
 };
 
 // src/buildInfo.ts
-var BUILD_TIME = "2026-10-26T15:07:50.401Z";
+var BUILD_TIME = "2026-10-26T15:11:56.868Z";
 function formatBuildTime(iso) {
   if (iso === "") return "";
   const d = new Date(iso);
@@ -97,13 +97,13 @@ function compareSemver(a, b) {
 async function readCache() {
   try {
     const raw = await fs.readFile(cachePath(), "utf8");
-    const parsed = JSON.parse(raw);
-    if (typeof parsed.checked_at !== "number" || typeof parsed.latest_version !== "string" || parsed.latest_version === "") {
+    const parsed2 = JSON.parse(raw);
+    if (typeof parsed2.checked_at !== "number" || typeof parsed2.latest_version !== "string" || parsed2.latest_version === "") {
       return null;
     }
     return {
-      checked_at: parsed.checked_at,
-      latest_version: parsed.latest_version
+      checked_at: parsed2.checked_at,
+      latest_version: parsed2.latest_version
     };
   } catch {
     return null;
@@ -400,14 +400,14 @@ var KeyringStore = class _KeyringStore {
       return out;
     }
     if (raw === void 0) return out;
-    let parsed;
+    let parsed2;
     try {
-      parsed = JSON.parse(raw);
+      parsed2 = JSON.parse(raw);
     } catch {
       return out;
     }
-    if (!Array.isArray(parsed)) return out;
-    for (const item of parsed) {
+    if (!Array.isArray(parsed2)) return out;
+    for (const item of parsed2) {
       const savedAt = parseDate(item?.savedAt);
       const lastUsedAt = parseDate(item?.lastUsedAt);
       if (typeof item?.email === "string" && savedAt !== void 0 && lastUsedAt !== void 0) {
@@ -434,22 +434,22 @@ var KeyringStore = class _KeyringStore {
     const sessionAccount = `${serverKey}:${email}`;
     const raw = await this.backend.get(SERVICE, sessionAccount);
     if (raw === void 0) return void 0;
-    let parsed;
+    let parsed2;
     try {
-      parsed = JSON.parse(raw);
+      parsed2 = JSON.parse(raw);
     } catch (err) {
       throw new KeychainError(`decode session for ${serverKey}:${email}`, {
         cause: err
       });
     }
-    const sessionId = typeof parsed.sessionId === "string" ? parsed.sessionId : "";
-    const csrfToken = typeof parsed.csrfToken === "string" ? parsed.csrfToken : "";
-    const savedAtStr = typeof parsed.savedAt === "string" ? parsed.savedAt : "";
-    const impersonatorEmail = typeof parsed.impersonatorEmail === "string" ? parsed.impersonatorEmail : "";
+    const sessionId = typeof parsed2.sessionId === "string" ? parsed2.sessionId : "";
+    const csrfToken = typeof parsed2.csrfToken === "string" ? parsed2.csrfToken : "";
+    const savedAtStr = typeof parsed2.savedAt === "string" ? parsed2.savedAt : "";
+    const impersonatorEmail = typeof parsed2.impersonatorEmail === "string" ? parsed2.impersonatorEmail : "";
     const impersonated = impersonatorEmail !== "";
-    const cookielessFlag = parsed.cookieless === true;
-    const apiKey = typeof parsed.apiKey === "string" && parsed.apiKey !== "" ? parsed.apiKey : "";
-    const apiKeyEnvVar = typeof parsed.apiKeyEnvVar === "string" && parsed.apiKeyEnvVar !== "" ? parsed.apiKeyEnvVar : "";
+    const cookielessFlag = parsed2.cookieless === true;
+    const apiKey = typeof parsed2.apiKey === "string" && parsed2.apiKey !== "" ? parsed2.apiKey : "";
+    const apiKeyEnvVar = typeof parsed2.apiKeyEnvVar === "string" && parsed2.apiKeyEnvVar !== "" ? parsed2.apiKeyEnvVar : "";
     const keyed = apiKey !== "" || apiKeyEnvVar !== "";
     const cookieless = impersonated || cookielessFlag || keyed;
     if (savedAtStr === "" || !cookieless && (sessionId === "" || csrfToken === "")) {
@@ -463,11 +463,11 @@ var KeyringStore = class _KeyringStore {
     };
     if (impersonated) {
       session.impersonatorEmail = impersonatorEmail;
-      if (typeof parsed.impersonatedUserId === "number") {
-        session.impersonatedUserId = parsed.impersonatedUserId;
+      if (typeof parsed2.impersonatedUserId === "number") {
+        session.impersonatedUserId = parsed2.impersonatedUserId;
       }
-      if (typeof parsed.impersonatedOrgName === "string" && parsed.impersonatedOrgName !== "") {
-        session.impersonatedOrgName = parsed.impersonatedOrgName;
+      if (typeof parsed2.impersonatedOrgName === "string" && parsed2.impersonatedOrgName !== "") {
+        session.impersonatedOrgName = parsed2.impersonatedOrgName;
       }
     }
     if (cookielessFlag) {
@@ -479,14 +479,14 @@ var KeyringStore = class _KeyringStore {
     if (apiKeyEnvVar !== "") {
       session.apiKeyEnvVar = apiKeyEnvVar;
     }
-    if (typeof parsed.apiKeyExpiresAt === "string" && parsed.apiKeyExpiresAt !== "") {
-      session.apiKeyExpiresAt = new Date(parsed.apiKeyExpiresAt);
+    if (typeof parsed2.apiKeyExpiresAt === "string" && parsed2.apiKeyExpiresAt !== "") {
+      session.apiKeyExpiresAt = new Date(parsed2.apiKeyExpiresAt);
     }
-    if (typeof parsed.jwtApiKeyFingerprint === "string" && parsed.jwtApiKeyFingerprint !== "") {
-      session.jwtApiKeyFingerprint = parsed.jwtApiKeyFingerprint;
+    if (typeof parsed2.jwtApiKeyFingerprint === "string" && parsed2.jwtApiKeyFingerprint !== "") {
+      session.jwtApiKeyFingerprint = parsed2.jwtApiKeyFingerprint;
     }
-    if (typeof parsed.jwtExpiresAt === "string" && parsed.jwtExpiresAt !== "") {
-      session.jwtExpiresAt = new Date(parsed.jwtExpiresAt);
+    if (typeof parsed2.jwtExpiresAt === "string" && parsed2.jwtExpiresAt !== "") {
+      session.jwtExpiresAt = new Date(parsed2.jwtExpiresAt);
     }
     const jwtAccess = await this.backend.get(SERVICE, `${sessionAccount}:access`);
     if (jwtAccess !== void 0 && jwtAccess !== "") {
@@ -768,12 +768,12 @@ async function requestDeviceCode(host, options) {
   if (raw === null || typeof raw !== "object") {
     throw new Error(`device/code parse: expected object`);
   }
-  const obj4 = raw;
+  const obj5 = raw;
   return {
-    deviceCode: typeof obj4.device_code === "string" ? obj4.device_code : "",
-    userCode: typeof obj4.user_code === "string" ? obj4.user_code : "",
-    verificationUriComplete: typeof obj4.verification_uri_complete === "string" ? obj4.verification_uri_complete : "",
-    interval: typeof obj4.interval === "number" ? obj4.interval : 0
+    deviceCode: typeof obj5.device_code === "string" ? obj5.device_code : "",
+    userCode: typeof obj5.user_code === "string" ? obj5.user_code : "",
+    verificationUriComplete: typeof obj5.verification_uri_complete === "string" ? obj5.verification_uri_complete : "",
+    interval: typeof obj5.interval === "number" ? obj5.interval : 0
   };
 }
 var defaultSleep = (ms, signal) => new Promise((resolve17, reject) => {
@@ -802,13 +802,13 @@ function parseTokenResponse(text3) {
   if (raw === null || typeof raw !== "object") {
     throw new Error(`token parse: expected object`);
   }
-  const obj4 = raw;
+  const obj5 = raw;
   const tok = {
-    sessionId: typeof obj4.session_id === "string" ? obj4.session_id : "",
-    csrfToken: typeof obj4.csrf_token === "string" ? obj4.csrf_token : ""
+    sessionId: typeof obj5.session_id === "string" ? obj5.session_id : "",
+    csrfToken: typeof obj5.csrf_token === "string" ? obj5.csrf_token : ""
   };
-  if (typeof obj4.access_token === "string") {
-    tok.accessToken = obj4.access_token;
+  if (typeof obj5.access_token === "string") {
+    tok.accessToken = obj5.access_token;
   }
   return tok;
 }
@@ -946,16 +946,16 @@ function decodeJwtClaims(token) {
   } catch (err) {
     throw new Error(`jwt: decode payload: ${msgOf3(err)}`);
   }
-  let parsed;
+  let parsed2;
   try {
-    parsed = JSON.parse(decoded);
+    parsed2 = JSON.parse(decoded);
   } catch (err) {
     throw new Error(`jwt: parse claims: ${msgOf3(err)}`);
   }
-  if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+  if (parsed2 === null || typeof parsed2 !== "object" || Array.isArray(parsed2)) {
     throw new Error("jwt: parse claims: expected object");
   }
-  return parsed;
+  return parsed2;
 }
 function decodeJwtExpiration(token) {
   const claims = decodeJwtClaims(token);
@@ -975,10 +975,10 @@ function parseTokenBody(text3, label) {
   if (raw === null || typeof raw !== "object") {
     throw new Error(`jwt ${label} parse: expected object`);
   }
-  const obj4 = raw;
+  const obj5 = raw;
   return {
-    access: typeof obj4.access === "string" ? obj4.access : "",
-    refresh: typeof obj4.refresh === "string" ? obj4.refresh : ""
+    access: typeof obj5.access === "string" ? obj5.access : "",
+    refresh: typeof obj5.refresh === "string" ? obj5.refresh : ""
   };
 }
 async function mintJwt(host, sessionId, csrfToken, options) {
@@ -1081,9 +1081,9 @@ async function loginAs(host, operatorAccessToken, userId, options) {
     let code;
     let detail;
     try {
-      const parsed = JSON.parse(text3);
-      if (typeof parsed["code"] === "string") code = parsed["code"];
-      if (typeof parsed["detail"] === "string") detail = parsed["detail"];
+      const parsed2 = JSON.parse(text3);
+      if (typeof parsed2["code"] === "string") code = parsed2["code"];
+      if (typeof parsed2["detail"] === "string") detail = parsed2["detail"];
     } catch {
     }
     throw new LoginAsError(res.status, {
@@ -1101,9 +1101,9 @@ async function loginAs(host, operatorAccessToken, userId, options) {
   if (raw === null || typeof raw !== "object") {
     throw new Error("jwt loginas parse: expected object");
   }
-  const obj4 = raw;
-  const access = typeof obj4["access"] === "string" ? obj4["access"] : "";
-  const refresh = typeof obj4["refresh"] === "string" ? obj4["refresh"] : "";
+  const obj5 = raw;
+  const access = typeof obj5["access"] === "string" ? obj5["access"] : "";
+  const refresh = typeof obj5["refresh"] === "string" ? obj5["refresh"] : "";
   if (access === "") {
     throw new Error("jwt loginas: empty access token");
   }
@@ -1113,7 +1113,7 @@ async function loginAs(host, operatorAccessToken, userId, options) {
   } catch (err) {
     throw new Error(`jwt loginas: ${msgOf3(err)}`);
   }
-  return { access, refresh, expiresAt, user: obj4["user"] };
+  return { access, refresh, expiresAt, user: obj5["user"] };
 }
 async function exchangeApiKey(host, apiKey, options) {
   const key = apiKey.trim();
@@ -2135,14 +2135,14 @@ async function readCredentialsFile(path3) {
     if (err.code === "ENOENT") return void 0;
     throw err;
   }
-  let parsed;
+  let parsed2;
   try {
-    parsed = JSON.parse(raw);
+    parsed2 = JSON.parse(raw);
   } catch {
     throw new Error(`credential file ${path3} is not valid JSON`);
   }
   try {
-    return credentialsFileSchema.parse(parsed);
+    return credentialsFileSchema.parse(parsed2);
   } catch (err) {
     const reason = err instanceof Error ? err.message : String(err);
     throw new Error(`credential file ${path3} is malformed: ${reason}`, { cause: err });
@@ -2227,14 +2227,14 @@ var FileKeyringBackend = class _FileKeyringBackend {
   }
   /** Cookie fields out of a metadata blob, dropped when empty. */
   static cookieOf(blob) {
-    let parsed;
+    let parsed2;
     try {
-      parsed = JSON.parse(blob);
+      parsed2 = JSON.parse(blob);
     } catch {
       return {};
     }
-    const sessionId = typeof parsed.sessionId === "string" ? parsed.sessionId : "";
-    const csrfToken = typeof parsed.csrfToken === "string" ? parsed.csrfToken : "";
+    const sessionId = typeof parsed2.sessionId === "string" ? parsed2.sessionId : "";
+    const csrfToken = typeof parsed2.csrfToken === "string" ? parsed2.csrfToken : "";
     return {
       ...sessionId !== "" && { sessionId },
       ...csrfToken !== "" && { csrfToken }
@@ -2248,8 +2248,8 @@ var FileKeyringBackend = class _FileKeyringBackend {
    */
   static fingerprintOf(blob) {
     try {
-      const parsed = JSON.parse(blob);
-      return typeof parsed.jwtApiKeyFingerprint === "string" ? parsed.jwtApiKeyFingerprint : "";
+      const parsed2 = JSON.parse(blob);
+      return typeof parsed2.jwtApiKeyFingerprint === "string" ? parsed2.jwtApiKeyFingerprint : "";
     } catch {
       return "";
     }
@@ -2467,11 +2467,11 @@ function registerLoginCommand(root) {
     }
     let timeoutMs;
     if (opts.timeout !== void 0) {
-      const parsed = Number(opts.timeout);
-      if (!Number.isFinite(parsed) || parsed <= 0) {
+      const parsed2 = Number(opts.timeout);
+      if (!Number.isFinite(parsed2) || parsed2 <= 0) {
         throw new Error(`--timeout must be a positive number of milliseconds`);
       }
-      timeoutMs = parsed;
+      timeoutMs = parsed2;
     }
     const store = fileStore?.store ?? await KeyringStore.defaultWithCleanup();
     await runLogin({
@@ -2962,6 +2962,16 @@ async function connect(opts) {
   return {
     serverKey: client.serverKey,
     baseUrl,
+    host: client.host,
+    email: client.email,
+    claims() {
+      try {
+        const access = client.session.jwtAccess ?? "";
+        return access === "" ? null : decodeJwtClaims(access);
+      } catch {
+        return null;
+      }
+    },
     cleanup,
     upload: (appId, file) => uploadVia(
       (path3, fields, blob, options) => client.postMultipart(path3, fields, blob, options),
@@ -3008,16 +3018,16 @@ async function connect(opts) {
           `the request was intercepted before reaching App Space (HTTP ${res.status}, HTML page returned \u2014 likely the Cloudflare WAF). The CLI gzips UI bundles to avoid this; if you are calling the API yourself, send frontend_bundle_gz.`
         );
       }
-      let parsed = void 0;
+      let parsed2 = void 0;
       try {
-        parsed = text3 === "" ? void 0 : JSON.parse(text3);
+        parsed2 = text3 === "" ? void 0 : JSON.parse(text3);
       } catch {
-        parsed = text3;
+        parsed2 = text3;
       }
       if (!res.ok) {
-        throw new AppSpaceHttpError(describeFailure(res.status, method, path3, parsed), res.status, parsed);
+        throw new AppSpaceHttpError(describeFailure(res.status, method, path3, parsed2), res.status, parsed2);
       }
-      return parsed;
+      return parsed2;
     }
   };
 }
@@ -3131,11 +3141,11 @@ function formatProblems(problems) {
   if (problems.length === 0) return "";
   const width = Math.max(...problems.map((p) => p.code.length + 2)) + 2;
   let out = "";
-  for (const problem5 of problems) {
-    const head = `[${problem5.code}]`.padEnd(width);
-    out += `${head}${problem5.pointer}: ${problem5.message}
+  for (const problem6 of problems) {
+    const head = `[${problem6.code}]`.padEnd(width);
+    out += `${head}${problem6.pointer}: ${problem6.message}
 `;
-    out += `${" ".repeat(head.length)}${problem5.fix}
+    out += `${" ".repeat(head.length)}${problem6.fix}
 `;
   }
   return out;
@@ -3164,13 +3174,13 @@ var NO_CATALOG = {
 };
 async function readCatalogFile(path3) {
   const raw = await readFile2(path3, "utf8");
-  let parsed;
+  let parsed2;
   try {
-    parsed = JSON.parse(raw);
+    parsed2 = JSON.parse(raw);
   } catch {
     throw new Error(`${path3} is not valid JSON.`);
   }
-  const root = unwrap(parsed);
+  const root = unwrap(parsed2);
   const metrics = rows(root["metrics"] ?? root["kpis"] ?? root["business_metrics"]).map(
     (row) => ({
       id: idOf(row),
@@ -3332,8 +3342,8 @@ function findTable(catalog, named13) {
     (table) => table.id.toLowerCase() === want || (table.alias ?? "").toLowerCase() === want || table.name.toLowerCase() === want
   );
 }
-function unwrap(parsed) {
-  let node = isObject(parsed) ? parsed : {};
+function unwrap(parsed2) {
+  let node = isObject(parsed2) ? parsed2 : {};
   for (const key of ["catalog", "data", "result"]) {
     const held = node[key];
     if (isObject(held) && ("tables" in held || "metrics" in held || "kpis" in held)) {
@@ -6830,7 +6840,7 @@ function specTransforms(handlers, spec, problems) {
       out.push({ path: path3, text: text3 });
     }
   }
-  const unreadable = problems.some((problem5) => problem5.code === "transform_unreadable");
+  const unreadable = problems.some((problem6) => problem6.code === "transform_unreadable");
   for (const key of Object.keys(spec.table).filter(isWidgetKey).sort(natural3)) {
     const path3 = isPlainObject(spec.table[key]) ? spec.table[key].transform : void 0;
     if (typeof path3 !== "string" || unreadable || carried !== null && carried.has(path3)) continue;
@@ -8732,8 +8742,8 @@ function unproducedPayloadKeys(contract, { handlerSource = () => void 0, moduleS
       if (produced.includes(key)) continue;
       const there = produced.length === 0 ? "the controls there produce no payload keys" : `the controls there produce ${produced.join(", ")}`;
       const fix = reads.generated ? `Add a control that sets it, or take "${key}" out of the handler's required in contract.json.` : `Add a control that sets it, or read it with payload.get("${key}", <default>).`;
-      const problem5 = `handler "${name}" reads payload "${key}", and nothing on ${either(pages)} that calls it produces that key \u2014 ${there}.`;
-      out.push({ handler: name, key, pages, produced, generated: reads.generated, problem: problem5, fix, message: `${problem5} ${fix}` });
+      const problem6 = `handler "${name}" reads payload "${key}", and nothing on ${either(pages)} that calls it produces that key \u2014 ${there}.`;
+      out.push({ handler: name, key, pages, produced, generated: reads.generated, problem: problem6, fix, message: `${problem6} ${fix}` });
     }
   }
   return out;
@@ -8767,9 +8777,9 @@ function undeclaredCustomCalls(contract, { moduleSource = () => void 0 } = {}) {
 }
 function undeclaredCallMessage(id, module, handler, calls, how) {
   const listed = calls.length === 0 ? "lists none" : `lists ${calls.join(", ")}`;
-  const problem5 = `custom "${id}" calls handler "${handler}" (ui.call ${how}, ui/${module}), and its declares.calls ${listed}.`;
+  const problem6 = `custom "${id}" calls handler "${handler}" (ui.call ${how}, ui/${module}), and its declares.calls ${listed}.`;
   const fix = `Add "${handler}" to declares.calls \u2014 and what it sends to declares.produces \u2014 or stop calling it.`;
-  return { problem: problem5, fix, message: `${problem5} ${fix}` };
+  return { problem: problem6, fix, message: `${problem6} ${fix}` };
 }
 function unreadUploadKeys(contract, { handlerSource = () => void 0 } = {}) {
   const elements = isPlainObject2(contract?.elements) ? contract.elements : {};
@@ -8812,9 +8822,9 @@ function unreadUploadKeys(contract, { handlerSource = () => void 0 } = {}) {
       }
       if (read) continue;
       const id = idOf2(element, uid);
-      const problem5 = `file_upload "${id}" writes the stored file under "${field}" to handler "${handler}" (${via}), and "${handler}" never reads payload["${field}"] \u2014 the file is stored and nothing uses it.`;
+      const problem6 = `file_upload "${id}" writes the stored file under "${field}" to handler "${handler}" (${via}), and "${handler}" never reads payload["${field}"] \u2014 the file is stored and nothing uses it.`;
       const fix = role === "custom" ? `Read payload["${field}"]["upload"] in "${handler}" and hand it to the parser (or write payload["${field}"] into a file column), or drop the upload.` : `Add "${field}" to "${handler}"'s fields (a file column), or drop the upload.`;
-      out.push({ uid, id, page: element.page ?? null, field, handler, via, problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ uid, id, page: element.page ?? null, field, handler, via, problem: problem6, fix, message: `${problem6} ${fix}` });
     }
   }
   return out;
@@ -8830,9 +8840,9 @@ function stepsWithoutAction(contract) {
       const id = idOf2(element, uid);
       const name = named2(step.id) ? step.id : String(index);
       const next = named2(steps[index + 1]?.id) ? steps[index + 1].id : "the next step";
-      const problem5 = `stepper "${id}" step "${name}" names no action, so no handler moves the flow on from it \u2014 a flow that reaches it stays there.`;
+      const problem6 = `stepper "${id}" step "${name}" names no action, so no handler moves the flow on from it \u2014 a flow that reaches it stays there.`;
       const fix = `Give it the handler that moves it to "${next}" (action, action_label), or make it the last step.`;
-      out.push({ uid, id, page: element.page ?? null, step: name, index, problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ uid, id, page: element.page ?? null, step: name, index, problem: problem6, fix, message: `${problem6} ${fix}` });
     });
   }
   return out;
@@ -8905,7 +8915,7 @@ var MAX_HINT2 = 120;
 function validate2(instance, schema, options = {}) {
   const problems = [];
   check2(instance, schema, "", schema, problems, { quote: options.quote === true, inBranch: false });
-  return problems.map((problem5) => `${problem5.at}: ${problem5.why}`);
+  return problems.map((problem6) => `${problem6.at}: ${problem6.why}`);
 }
 function problem2(at, why, kind = "other") {
   return { at: at || "/", why, kind };
@@ -9318,9 +9328,9 @@ function unreachablePages(contract, files = {}) {
     else if (roles.length > 0) why = `it is for ${both(quoted(roles))}, and no page ${either2(quoted(roles))} reaches links to it`;
     else if (gates.length > 0) why = `every nav entry to it is gated to ${either2(quoted(gates))}, and no role shown that entry reaches a page carrying it`;
     else why = "the only pages that link to it are pages no role reaches";
-    const problem5 = `${page.path} is a page of the app, and no role reaches it from the nav \u2014 ${why} \u2014 so only a typed URL opens it.`;
+    const problem6 = `${page.path} is a page of the app, and no role reaches it from the nav \u2014 ${why} \u2014 so only a typed URL opens it.`;
     const fix = roles.length > 0 || gates.length > 0 ? `Gate its nav entry to a role that should open it (pages[].roles on the page, a role's home, or the element's role), or drop the page.` : "Give the pages a nav (a nav element on each page), or drop the page.";
-    out.push({ page: page.path, problem: problem5, fix, message: `${problem5} ${fix}` });
+    out.push({ page: page.path, problem: problem6, fix, message: `${problem6} ${fix}` });
   }
   return out;
 }
@@ -9466,9 +9476,9 @@ function unconfirmedStateChanges(contract, files = {}) {
       named_.push(one.module ? `${one.what} (on ${one.page})` : `${one.what} "${one.id}" (on ${one.page})`);
     }
     const kind = handlers[handler]?.role === "decide" ? "decides a row" : "changes a record's state";
-    const problem5 = `handler "${handler}" ${kind}, and ${both(named_)} ${named_.length === 1 ? "calls" : "call"} it on one click, with no confirm and no dialog in front of it.`;
+    const problem6 = `handler "${handler}" ${kind}, and ${both(named_)} ${named_.length === 1 ? "calls" : "call"} it on one click, with no confirm and no dialog in front of it.`;
     const fix = 'Put the decision behind a confirm: a dialog part whose on_confirm is the handler (with the reason as one of its inputs), a row action with "confirm", a map-form decide whose decision takes a note, or \u2014 in a custom module \u2014 ui.confirm before ui.call.';
-    out.push({ handler, callers: bare.map(({ page, uid, what }) => ({ page, uid, what })), problem: problem5, fix, message: `${problem5} ${fix}` });
+    out.push({ handler, callers: bare.map(({ page, uid, what }) => ({ page, uid, what })), problem: problem6, fix, message: `${problem6} ${fix}` });
   }
   return out;
 }
@@ -9546,18 +9556,18 @@ function unreadReasons(contract, { handlerSource = () => void 0, moduleSource, p
     for (const [key, pages] of [...sent.entries()].sort()) {
       if (read.has(key)) continue;
       const where2 = pages.size === 0 ? "the page" : either2([...pages].sort());
-      const problem5 = `${where2} sends handler "${name}" a "${key}", and the handler never reads it \u2014 the reason a person types is thrown away.`;
+      const problem6 = `${where2} sends handler "${name}" a "${key}", and the handler never reads it \u2014 the reason a person types is thrown away.`;
       const fix = `Read it (payload.get("${key}")) and keep it with the decision \u2014 a column, or the audit note \u2014 or stop asking for it.`;
-      out.push({ handler: name, key, kind: "unread", pages: [...pages].sort(), problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ handler: name, key, kind: "unread", pages: [...pages].sort(), problem: problem6, fix, message: `${problem6} ${fix}` });
     }
     const lines = pyLines(source);
     if (!changesState(name, row, source) || !REJECTS.test(lines.join("\n"))) continue;
     for (const key of REASON_KEYS) {
       if (!reads.optional.includes(key) || reads.required.includes(key)) continue;
       if (requiresReason(lines, key, reasonVars(lines, key))) continue;
-      const problem5 = `handler "${name}" rejects (or overrides), and reads "${key}" without ever requiring it \u2014 a rejection goes through with no reason given.`;
+      const problem6 = `handler "${name}" rejects (or overrides), and reads "${key}" without ever requiring it \u2014 a rejection goes through with no reason given.`;
       const fix = `Refuse the reject path without one: if decision == "rejected" and not ${key}: return {"error": "Give a reason to reject."}.`;
-      out.push({ handler: name, key, kind: "optional", pages: [], problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ handler: name, key, kind: "optional", pages: [], problem: problem6, fix, message: `${problem6} ${fix}` });
     }
   }
   return out;
@@ -9594,9 +9604,9 @@ function unliftableRefusals(contract, { handlerSource = () => void 0 } = {}) {
           }
           if (!refuses) continue;
           const shown2 = line2.trim().replace(/:$/, "");
-          const problem5 = `handler "${name}" refuses outright at line ${si + 1} (${shown2}) on the same path where it demands a "${key}" (line ${gi + 1}), and no reason lifts that refusal \u2014 the page asks for a reason to go ahead, and the reason is ignored.`;
+          const problem6 = `handler "${name}" refuses outright at line ${si + 1} (${shown2}) on the same path where it demands a "${key}" (line ${gi + 1}), and no reason lifts that refusal \u2014 the page asks for a reason to go ahead, and the reason is ignored.`;
           const fix = `Let the reason override it (check "${key}" before refusing, and record it), or tell the reader that this state cannot be overridden and stop asking for a reason.`;
-          out.push({ handler: name, key, line: si + 1, gateLine: gi + 1, problem: problem5, fix, message: `${problem5} ${fix}` });
+          out.push({ handler: name, key, line: si + 1, gateLine: gi + 1, problem: problem6, fix, message: `${problem6} ${fix}` });
         }
       }
     }
@@ -9612,9 +9622,9 @@ function rolesLandingNowhere(contract) {
     const exists = pagesOf(contract).some((page) => page.path === landing);
     if (exists && opens(contract, model, role, landing)) continue;
     const stated2 = model.home.get(role);
-    const problem5 = !exists ? `role "${role}" lands on ${landing} (its home), which is not a page of the app.` : stated2 ? `role "${role}" lands on its home, ${landing}, which is for ${both(quoted(pageRoles(pagesOf(contract).find((page) => page.path === landing))))} \u2014 so the role opens the app on a 404.` : `role "${role}" states no home and lands on ${landing}, which is for ${both(quoted(pageRoles(pagesOf(contract).find((page) => page.path === landing))))} \u2014 so the role opens the app on a 404.`;
+    const problem6 = !exists ? `role "${role}" lands on ${landing} (its home), which is not a page of the app.` : stated2 ? `role "${role}" lands on its home, ${landing}, which is for ${both(quoted(pageRoles(pagesOf(contract).find((page) => page.path === landing))))} \u2014 so the role opens the app on a 404.` : `role "${role}" states no home and lands on ${landing}, which is for ${both(quoted(pageRoles(pagesOf(contract).find((page) => page.path === landing))))} \u2014 so the role opens the app on a 404.`;
     const fix = `Give "${role}" a home it may open (backend.roles[].home: one of its pages), or add it to that page's pages[].roles.`;
-    out.push({ role, page: landing, problem: problem5, fix, message: `${problem5} ${fix}` });
+    out.push({ role, page: landing, problem: problem6, fix, message: `${problem6} ${fix}` });
   }
   return out;
 }
@@ -9653,8 +9663,8 @@ function openToEveryRole(contract) {
   const out = [];
   const say = (kind, names, what, fix) => {
     if (names.length === 0) return;
-    const problem5 = `${names.length === 1 ? `${what.one} ${names[0]} states` : `${names.length} ${what.many} \u2014 ${both(names)} \u2014 state`} no roles, so every role (${all}) may ${what.verb} ${names.length === 1 ? "it" : "them"}.`;
-    out.push({ kind, names, problem: problem5, fix, message: `${problem5} ${fix}` });
+    const problem6 = `${names.length === 1 ? `${what.one} ${names[0]} states` : `${names.length} ${what.many} \u2014 ${both(names)} \u2014 state`} no roles, so every role (${all}) may ${what.verb} ${names.length === 1 ? "it" : "them"}.`;
+    out.push({ kind, names, problem: problem6, fix, message: `${problem6} ${fix}` });
   };
   say(
     "page",
@@ -10572,7 +10582,7 @@ function compile(contract, { kit, extra = {} } = {}) {
   if (handler.unwritable !== null) return refuse2(handler.unwritable.code, handler.unwritable.where, handler.unwritable.message);
   for (const note of handler.notes) problems.push(note);
   if (handler.refusals.length > 0) {
-    for (const problem5 of handler.refusals) problems.push(problem5);
+    for (const problem6 of handler.refusals) problems.push(problem6);
     return { files: {}, problems: problems.sort(byProblem2) };
   }
   const files = {};
@@ -10605,7 +10615,7 @@ function dashboardHandler(composed, handlerName, extra = {}) {
   out.notes.push(...missingExpressions(composed.data?.widgets));
   const carried = [...transformRowProblems(composed.data), ...transformFileProblems(composed.data, extra)];
   if (carried.length > 0) {
-    out.refusals.push(...carried.map((problem5) => ({ ...problem5, lossy: false })));
+    out.refusals.push(...carried.map((problem6) => ({ ...problem6, lossy: false })));
     return out;
   }
   const transforms = transformTexts(composed.data, extra);
@@ -11141,7 +11151,7 @@ function compileDashboard(contract, { kit = null, extra = {}, uiKit, charts, fmt
   }
   problems.push(...handler.notes);
   if (handler.refusals.length > 0) {
-    for (const problem5 of handler.refusals) refuse2(problem5.code, problem5.where, problem5.message);
+    for (const problem6 of handler.refusals) refuse2(problem6.code, problem6.where, problem6.message);
     return refused();
   }
   const restated = restateDashboard(composed, pages, handlerName, handler, { refuse: refuse2, note, stated: Array.isArray(source.pages) ? source.pages : [] });
@@ -11178,17 +11188,17 @@ function compileDashboard(contract, { kit = null, extra = {}, uiKit, charts, fmt
   for (const page of whole.pages) files[page.path] = pageHtml(whole, page, elements, tree, shelf2);
   return { files, problems, contract: whole, order: order2, warnings: narrativeOrderWarnings(composed, applied) };
 }
-function isRefusal(problem5) {
-  return problem5.lossy !== false;
+function isRefusal(problem6) {
+  return problem6.lossy !== false;
 }
 function restateDashboard(composed, pages, handlerName, handler, { refuse: refuse2, note, stated: stated2 }) {
   const app = isPlainObject7(composed.app) ? composed.app : {};
   const typed = isPlainObject7(composed.elements) ? composed.elements : {};
   const declared = treeOf(typed);
-  const conflicts = new Map(declared.problems.map((problem5) => [uidOfPointer(problem5.pointer), problem5]));
+  const conflicts = new Map(declared.problems.map((problem6) => [uidOfPointer(problem6.pointer), problem6]));
   const paths = new Set(pages.map((page) => page.path));
   const unplaced = Object.fromEntries(Object.keys(typed).filter((uid) => isPlainObject7(typed[uid]) && !paths.has(typed[uid].page)).map((uid) => [uid, typed[uid]]));
-  for (const problem5 of placementProblems(unplaced, pages, declared, [])) refuse2(problem5.code, problem5.pointer, problem5.message);
+  for (const problem6 of placementProblems(unplaced, pages, declared, [])) refuse2(problem6.code, problem6.pointer, problem6.message);
   const elements = {};
   const outPages = [];
   for (const page of pages) {
@@ -11996,8 +12006,8 @@ function timeModifierProblem(mod) {
   return `has a malformed time modifier "${mod}" (expected .SHIFT(<unit>, <offset>) or .AS_OF(<anchor>))`;
 }
 function checkModifier(mod) {
-  const problem5 = timeModifierProblem(mod);
-  if (problem5 !== null) refuse(problem5);
+  const problem6 = timeModifierProblem(mod);
+  if (problem6 !== null) refuse(problem6);
 }
 function namedItself(spelled) {
   return `names the metric ${spelled} itself; an operand is [@key], a key data.metrics declares, so the contract names no company's metric \u2014 declare it there (with "reuse": "name" and "create": false to bind the company's own) and write [@<its key>]`;
@@ -12144,6 +12154,27 @@ function metricFormulaProblems(formula, declared) {
     return { problems: [error.message], operands: [], windows: [] };
   }
 }
+function wireFormula(formula, names) {
+  const known = names !== null && typeof names === "object" ? names : {};
+  const { padded, stash } = scan(formula, Object.keys(known));
+  const nameOf5 = (key) => {
+    const name = known[key];
+    if (typeof name !== "string" || name.trim() === "" || /['[\]]/.test(name)) {
+      refuse(`reads [@${key}], bound to a metric named ${JSON.stringify(name ?? null)}, which a CALC formula cannot reference (an operand's name is non-empty, with no ' [ or ])`);
+    }
+    return name;
+  };
+  const wire = padded.replace(STASH_RE, (_m, index) => {
+    const entry = stash[Number(index)];
+    if (entry.kind === "token") return `'${entry.token}'`;
+    if (entry.kind === "window") return `${entry.fn}('${nameOf5(entry.key)}', ${entry.unit}, ${entry.periods})`;
+    return `'${nameOf5(entry.key)}'${entry.mod}`;
+  });
+  if (wire.length > MAX_FORMULA_LENGTH) {
+    refuse(`is ${wire.length} characters with the company's metric names written in, over the server maximum of ${MAX_FORMULA_LENGTH}; shorten the formula or the names`);
+  }
+  return wire;
+}
 
 // ../flows/insights-builder/kit/contract/metricFormats.mjs
 var CURRENCY_PREFIXES = ['"$"', "\u20AC", "\xA3", "\u20AA"];
@@ -12842,11 +12873,11 @@ function metricFilterProblem(filter) {
   if (filter.exclude !== void 0 && typeof filter.exclude !== "boolean") return `states exclude ${JSON.stringify(filter.exclude)}; exclude is true or false`;
   return null;
 }
-function metricReaches(operandsOf, start, target, seen) {
+function metricReaches(operandsOf2, start, target, seen) {
   if (start === target) return true;
   if (seen.has(start)) return false;
   seen.add(start);
-  return (operandsOf.get(start) ?? []).some((one) => metricReaches(operandsOf, one, target, seen));
+  return (operandsOf2.get(start) ?? []).some((one) => metricReaches(operandsOf2, one, target, seen));
 }
 function calcShaped(node) {
   if (node[0] === "num" || node[0] === "name") return true;
@@ -12975,12 +13006,12 @@ function metricProblems(metrics, sources) {
       }
     }
   }
-  const operandsOf = /* @__PURE__ */ new Map();
+  const operandsOf2 = /* @__PURE__ */ new Map();
   for (const key of [...formulas.keys()].sort(natural3)) {
     const { problems: wrong, operands, windows } = metricFormulaProblems(formulas.get(key), declaredKeys);
     for (const one of wrong) say("metric_formula", at(key, "formula"), `metric "${key}"'s formula ${one}`);
     if (wrong.length > 0) continue;
-    operandsOf.set(key, operands);
+    operandsOf2.set(key, operands);
     if (windows.length > 0) {
       advise(
         "metric_window",
@@ -12989,9 +13020,9 @@ function metricProblems(metrics, sources) {
       );
     }
   }
-  for (const key of [...operandsOf.keys()].sort(natural3)) {
-    for (const dep of operandsOf.get(key)) {
-      if (metricReaches(operandsOf, dep, key, /* @__PURE__ */ new Set())) {
+  for (const key of [...operandsOf2.keys()].sort(natural3)) {
+    for (const dep of operandsOf2.get(key)) {
+      if (metricReaches(operandsOf2, dep, key, /* @__PURE__ */ new Set())) {
         say("metric_formula", at(key, "formula"), `metric "${key}"'s formula reads itself${dep === key ? "" : `, through [@${dep}]`}; a calc metric's operands are metrics that exist before it, so none may read it back`);
         break;
       }
@@ -13034,7 +13065,7 @@ function metricProblems(metrics, sources) {
     const visit = (key) => {
       if (used.has(key)) return;
       used.add(key);
-      for (const one of operandsOf.get(key) ?? []) visit(one);
+      for (const one of operandsOf2.get(key) ?? []) visit(one);
     };
     for (const key of read) visit(key);
     for (const key of declaredKeys) {
@@ -13449,8 +13480,8 @@ function paramProblems(contract, sources) {
 }
 function numberFix(value, integer = false) {
   const text3 = typeof value === "string" ? value.trim() : null;
-  const parsed = text3 !== null && text3 !== "" ? Number(text3) : NaN;
-  if (Number.isFinite(parsed) && (!integer || Number.isInteger(parsed))) return `write it as the number ${parsed}, unquoted`;
+  const parsed2 = text3 !== null && text3 !== "" ? Number(text3) : NaN;
+  if (Number.isFinite(parsed2) && (!integer || Number.isInteger(parsed2))) return `write it as the number ${parsed2}, unquoted`;
   return `write ${integer ? "a whole number" : "a number"}, or leave the key out`;
 }
 function uidHint(value, why, elements) {
@@ -16466,7 +16497,7 @@ function measureProblems(name, row, model, handlers = {}) {
         const found = whereProblems(spec.where, EVENTS_SHAPE, at, who, {
           noColumn: (column) => `filters on "${column}", which is no column of the events; filter on at, action, handler, actor or note`
         });
-        problems.push(...found, ...eventHandlerProblems(spec.where, row.table, handlers, at, who, new Set(found.map((problem5) => problem5.pointer))));
+        problems.push(...found, ...eventHandlerProblems(spec.where, row.table, handlers, at, who, new Set(found.map((problem6) => problem6.pointer))));
       } else problems.push(...whereProblems(spec.where, table, at, who, { platform: true }));
     }
   }
@@ -17722,6 +17753,7 @@ function validateContract(contract, catalog) {
   checkKind(app, problems);
   checkPreset(app, problems);
   if (kind === "dashboard") checkSources(doc, catalog, problems, skipped);
+  checkSourceMetricIds(doc, catalog, problems, skipped);
   checkVocabulary(doc, kind, problems, renderer);
   checkPages(doc, kind, problems);
   if (kind === "dashboard") {
@@ -17744,22 +17776,22 @@ function validateContract(contract, catalog) {
   return { problems: dedupe(problems), skipped: dedupeSkipped(skipped), warnings: dedupe(warnings) };
 }
 function checkCustomDeclares(doc, problems) {
-  for (const problem5 of declaresProblems2(doc)) {
+  for (const problem6 of declaresProblems2(doc)) {
     problems.push({
-      code: problem5.code,
-      pointer: problem5.pointer,
-      message: `${problem5.message}.`,
+      code: problem6.code,
+      pointer: problem6.pointer,
+      message: `${problem6.message}.`,
       fix: 'Name only data.sources entries and data.app.handlers in declares \u2014 {"reads": [...], "calls": [...], "produces": {"<handler>": ["<key>", ...]}, "shows": [{"field": ..., "format": ...}]} (docs/appspace/components/catalog.md, custom).'
     });
   }
 }
 function checkTransforms(doc, problems) {
-  for (const problem5 of transformRowProblems2(obj(doc["data"]))) {
-    const row = problem5.code === "transform_row";
+  for (const problem6 of transformRowProblems2(obj(doc["data"]))) {
+    const row = problem6.code === "transform_row";
     problems.push({
       code: row ? "transform-row" : "transform-missing",
-      pointer: problem5.where,
-      message: `${problem5.message}.`,
+      pointer: problem6.where,
+      message: `${problem6.message}.`,
       fix: row ? "Make each change the message names, on this row and its dataset's read; a KPI, a plain read or a computed card takes no transform in this release." : "Name the file transforms/<name>.py \u2014 lowercase letters, digits and underscores, at most 64 of them, with the worker prefix (transforms/w3_revenue_ma.py)."
     });
   }
@@ -18059,6 +18091,30 @@ function checkPreset(app, problems) {
     fix: `Name one of ${PRESETS2.join(", ")}, or drop the key and take the default.`
   });
 }
+function checkSourceMetricIds(doc, catalog, problems, skipped) {
+  const sources = obj(obj(doc["data"])["sources"]);
+  const byId = [];
+  for (const [name, row] of Object.entries(sources)) {
+    const id = obj(obj(obj(row)["from"])["financeos"])["metric_id"];
+    if (typeof id === "number" || typeof id === "string" && id.trim() !== "") byId.push([name, String(id).trim()]);
+  }
+  if (byId.length === 0) return;
+  if (!checksMetrics(catalog)) {
+    const why = catalog.source === "none" ? "no --catalog file and no -s server to read the metric list from" : catalog.checks_skipped.find((one) => one.what === "metric ids")?.why ?? "this tenant's metric list could not be read";
+    if (!skipped.some((one) => one.what === "source metric ids")) skipped.push({ what: "source metric ids", why });
+    return;
+  }
+  const known = new Set(catalog.metrics.map((metric) => metric.id));
+  for (const [name, id] of byId) {
+    if (known.has(id)) continue;
+    problems.push({
+      code: "unknown-metric",
+      pointer: pointer("data", "sources", name, "from", "financeos", "metric_id"),
+      message: `${id} is not a metric this company has.`,
+      fix: `Use an id from this company's metric list, or declare the metric in data.metrics and read it as "@<key>", which ship binds in each company.`
+    });
+  }
+}
 function checkSources(doc, catalog, problems, skipped) {
   const widgets = obj(obj(doc["data"])["widgets"]);
   if (Object.keys(widgets).length === 0) return;
@@ -18300,9 +18356,9 @@ function calendarDateIn(filter) {
 }
 function epochOf(date) {
   const day = date.slice(0, 10);
-  const parsed = Date.parse(`${day}T00:00:00Z`);
-  if (Number.isNaN(parsed)) return void 0;
-  return String(Math.floor(parsed / 1e3));
+  const parsed2 = Date.parse(`${day}T00:00:00Z`);
+  if (Number.isNaN(parsed2)) return void 0;
+  return String(Math.floor(parsed2 / 1e3));
 }
 function addressOf(source, hasAlias, hasId) {
   const declared = source["address"];
@@ -19264,11 +19320,11 @@ function walk3(node, path3, visit) {
 function dedupe(problems) {
   const seen = /* @__PURE__ */ new Set();
   const out = [];
-  for (const problem5 of problems) {
-    const key = `${problem5.code}\0${problem5.pointer}\0${problem5.message}`;
+  for (const problem6 of problems) {
+    const key = `${problem6.code}\0${problem6.pointer}\0${problem6.message}`;
     if (seen.has(key)) continue;
     seen.add(key);
-    out.push(problem5);
+    out.push(problem6);
   }
   return out;
 }
@@ -20580,16 +20636,16 @@ async function readManifest(dir) {
   if (raw === void 0) {
     throw new Error(`no manifest.json in ${dir} \u2014 is this an app folder?`);
   }
-  let parsed;
+  let parsed2;
   try {
-    parsed = JSON.parse(raw);
+    parsed2 = JSON.parse(raw);
   } catch {
     throw new Error(`manifest.json in ${dir} is not valid JSON.`);
   }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+  if (typeof parsed2 !== "object" || parsed2 === null || Array.isArray(parsed2)) {
     throw new Error("manifest.json is not a JSON object.");
   }
-  const manifest = parsed;
+  const manifest = parsed2;
   const id = manifest["id"];
   if (typeof id !== "string" || id === "") {
     throw new Error('manifest.json has no "id".');
@@ -20603,9 +20659,9 @@ async function readState(dir) {
   const raw = await readIfPresent(join5(dir, ".appspace.json"));
   if (raw === void 0) return {};
   try {
-    const parsed = JSON.parse(raw);
-    if (typeof parsed === "object" && parsed !== null) {
-      return parsed;
+    const parsed2 = JSON.parse(raw);
+    if (typeof parsed2 === "object" && parsed2 !== null) {
+      return parsed2;
     }
   } catch {
   }
@@ -20722,8 +20778,8 @@ function summarise(contract) {
 }
 function describeFindings(contract) {
   let out = "";
-  for (const problem5 of contract.problems) {
-    out += `  ${problem5.lossy ? "lossy" : "ok   "} ${problem5.code} at ${problem5.where}: ${problem5.message}
+  for (const problem6 of contract.problems) {
+    out += `  ${problem6.lossy ? "lossy" : "ok   "} ${problem6.code} at ${problem6.where}: ${problem6.message}
 `;
   }
   for (const entry of contract.unresolved) {
@@ -21636,6 +21692,1082 @@ async function previewOne(document, file, opts, shared = {}) {
 import { readFile as readFile7 } from "fs/promises";
 import { join as join8 } from "path";
 import { gunzipSync, gzipSync } from "zlib";
+
+// src/scopes/matcher.ts
+var SCOPE_RE = /^(\*|[a-z][a-z0-9-]*):(\*|read|write|destructive)$/;
+var ACTION_RANK = new Map(
+  ["read", "write", "destructive"].map((action, rank) => [action, rank])
+);
+function actionSatisfies(granted, wanted) {
+  if (granted === "*" || granted === wanted) return true;
+  const g = ACTION_RANK.get(granted);
+  const w = ACTION_RANK.get(wanted);
+  if (g === void 0 || w === void 0) return false;
+  return g > w;
+}
+var WHITESPACE = "\\t\\n\\v\\f\\r \\x1c-\\x1f\\x85\\xa0\\u1680\\u2000-\\u200a\\u2028\\u2029\\u202f\\u205f\\u3000\\ufeff";
+var TRIM_RE = new RegExp(`^[${WHITESPACE}]+|[${WHITESPACE}]+$`, "g");
+var SPLIT_RE = new RegExp(`[${WHITESPACE}]+`);
+function trimShared(value) {
+  return value.replace(TRIM_RE, "");
+}
+function splitScopeString(value) {
+  return value.split(SPLIT_RE).filter((part) => part !== "");
+}
+function parseScope(value) {
+  if (typeof value !== "string") return null;
+  const m = SCOPE_RE.exec(trimShared(value).toLowerCase());
+  return m ? [m[1], m[2]] : null;
+}
+function parsed(scopes) {
+  const list3 = scopes ?? [];
+  const entries = typeof list3 === "string" ? splitScopeString(list3) : Array.isArray(list3) ? list3 : [];
+  return entries.map(parseScope).filter((p) => p !== null);
+}
+function scopeEntries(scopes) {
+  return parsed(scopes);
+}
+function isAgentScoped(scopes) {
+  return parsed(scopes).length > 0;
+}
+function isAllowed(scopes, resource, action) {
+  const entries = parsed(scopes);
+  if (entries.length === 0) return true;
+  const res = trimShared(resource).toLowerCase();
+  const act = trimShared(action).toLowerCase();
+  return entries.some(([r, a]) => (r === "*" || r === res) && actionSatisfies(a, act));
+}
+
+// src/commands/appspace/metrics.ts
+function metricsTransport(client) {
+  const host = (client.host ?? client.baseUrl.replace(/\/api\/app-space$/, "")).replace(/\/+$/, "");
+  return {
+    serverKey: client.serverKey,
+    host,
+    appSpace: client.baseUrl,
+    overridden: client.baseUrl !== `${host}/api/app-space`,
+    email: client.email ?? null,
+    async call(method, url, body) {
+      const headers = {};
+      if (body !== void 0) headers["content-type"] = "application/json";
+      const res = await client.raw({
+        method,
+        url,
+        headers,
+        ...body === void 0 ? {} : { body: JSON.stringify(body) }
+      });
+      const text3 = res.body.toString("utf8");
+      let parsed2 = text3 === "" ? null : text3;
+      try {
+        parsed2 = text3 === "" ? null : JSON.parse(text3);
+      } catch {
+      }
+      return { status: res.status, body: parsed2 };
+    },
+    claims: () => client.claims === void 0 ? null : client.claims()
+  };
+}
+function declaredMetrics(contract) {
+  const data = obj2(obj2(contract)["data"]);
+  const metrics = obj2(data["metrics"]);
+  const out = {};
+  for (const [key, decl] of Object.entries(metrics)) {
+    if (isObj3(decl) && typeof decl["name"] === "string") out[key] = decl;
+  }
+  return out;
+}
+function metricSources(contract) {
+  const sources = obj2(obj2(obj2(contract)["data"])["sources"]);
+  const out = {};
+  for (const [name, row] of Object.entries(sources)) {
+    const metric = obj2(obj2(obj2(row)["from"])["financeos"])["metric"];
+    if (typeof metric === "string" && metric.startsWith("@") && metric.length > 1) out[name] = metric.slice(1);
+  }
+  return out;
+}
+var ENTITY_RE2 = /&(quot|amp|lt|gt|#x27|#39);/g;
+var ENTITIES = { quot: '"', amp: "&", lt: "<", gt: ">", "#x27": "'", "#39": "'" };
+function decodeEntities2(value) {
+  if (typeof value === "string") return value.replace(ENTITY_RE2, (_m, name) => ENTITIES[name] ?? "");
+  if (Array.isArray(value)) return value.map(decodeEntities2);
+  if (isObj3(value)) return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, decodeEntities2(v)]));
+  return value;
+}
+function listOf(body) {
+  const rows2 = Array.isArray(body) ? body : isObj3(body) && Array.isArray(body["results"]) ? body["results"] : null;
+  return rows2 === null ? [] : rows2.filter(isObj3);
+}
+function idIn(value) {
+  if (typeof value === "number" && Number.isInteger(value)) return value;
+  if (typeof value === "string" && /^\d+$/.test(value)) return Number(value);
+  if (isObj3(value)) return idIn(value["id"]);
+  return null;
+}
+function catalogRow(raw) {
+  const id = idIn(raw["id"]);
+  const name = typeof raw["name"] === "string" ? raw["name"] : null;
+  if (id === null || name === null) return null;
+  const configuration = obj2(raw["configuration"]);
+  const status = obj2(raw["status_info"]);
+  const filters = (Array.isArray(raw["filters"]) ? raw["filters"] : []).filter(isObj3).flatMap((one) => {
+    const field = idIn(one["field"]);
+    if (field === null) return [];
+    const values = Array.isArray(one["values"]) ? one["values"].map(String) : one["values"] === void 0 || one["values"] === null ? [] : [String(one["values"])];
+    return [{ field, values, is_excluded: one["is_excluded"] === true, allow_nulls: one["allow_nulls"] === true }];
+  });
+  return {
+    id,
+    name,
+    kind: typeof raw["kind"] === "string" ? raw["kind"].toUpperCase() : "",
+    template: idIn(raw["template"] ?? raw["template_id"]),
+    value_field: idIn(raw["value_field"]),
+    date_field: idIn(raw["date_field"]),
+    aggregator: typeof raw["aggregator"] === "string" ? raw["aggregator"].toUpperCase() : idIn(raw["aggregator"]) === null && isObj3(raw["aggregator"]) && typeof raw["aggregator"]["name"] === "string" ? String(raw["aggregator"]["name"]).toUpperCase() : null,
+    is_cumulative: raw["is_cumulative"] === true,
+    time_aggregation: typeof raw["time_aggregation"] === "string" ? raw["time_aggregation"].toUpperCase() : null,
+    filters,
+    formula: typeof configuration["presented_formula"] === "string" && configuration["presented_formula"] !== "" ? configuration["presented_formula"] : null,
+    format: typeof configuration["format"] === "string" ? configuration["format"] : null,
+    base_metrics: (Array.isArray(raw["base_metrics"]) ? raw["base_metrics"] : []).map(idIn).filter((one) => one !== null),
+    description: typeof raw["description"] === "string" ? raw["description"] : null,
+    status: typeof status["status"] === "string" ? status["status"].toUpperCase() : null,
+    created_at: typeof raw["created_at"] === "string" ? raw["created_at"] : null
+  };
+}
+function authTableRow(raw) {
+  const id = idIn(raw["id"]);
+  if (id === null) return null;
+  const fields = Array.isArray(raw["fields"]) ? raw["fields"].filter(isObj3).map(
+    (one) => ({
+      id: idIn(one["id"]),
+      name: typeof one["name"] === "string" ? one["name"] : "",
+      alias: typeof one["alias"] === "string" && one["alias"].trim() !== "" ? one["alias"].trim() : null
+    })
+  ) : null;
+  return {
+    id,
+    name: typeof raw["name"] === "string" ? raw["name"] : String(id),
+    alias: typeof raw["alias"] === "string" && raw["alias"].trim() !== "" ? raw["alias"].trim() : null,
+    blocked: raw["authoring_blocked"] === true,
+    fields: fields !== null && fields.length > 0 ? fields : null
+  };
+}
+var MetricsReadError = class extends Error {
+};
+async function readJson2(t, url, what) {
+  let answer;
+  try {
+    answer = await t.call("GET", url);
+  } catch (err) {
+    throw new MetricsReadError(`${what} could not be read (${firstLine(err)})`);
+  }
+  if (answer.status < 200 || answer.status >= 300) {
+    throw new MetricsReadError(`${what} could not be read (HTTP ${String(answer.status)}${sentenceOf(answer.body) === "" ? "" : `: ${sentenceOf(answer.body)}`})`);
+  }
+  return decodeEntities2(answer.body);
+}
+async function readCatalog(t) {
+  const body = await readJson2(t, `${t.host}/api/insights/metrics`, "this company's Datarails metrics");
+  return listOf(body).map(catalogRow).filter((one) => one !== null);
+}
+async function readAuthTables(t) {
+  const body = await readJson2(t, `${t.host}/api/insights/metrics/auth_tables`, "the tables you may build metrics on");
+  return listOf(body).map(authTableRow).filter((one) => one !== null);
+}
+async function readTableFields(t, id) {
+  const body = obj2(await readJson2(t, `${t.appSpace}/financeos/tables/${String(id)}`, `the fields of table ${String(id)}`));
+  if (body["reachable"] !== true) throw new MetricsReadError(`the fields of table ${String(id)} could not be read (FinanceOS did not answer)`);
+  return (Array.isArray(body["fields"]) ? body["fields"] : []).filter(isObj3).map(
+    (one) => ({
+      id: idIn(one["id"]),
+      name: typeof one["name"] === "string" ? one["name"] : "",
+      alias: typeof one["alias"] === "string" && one["alias"].trim() !== "" ? one["alias"].trim() : null
+    })
+  );
+}
+var AGGREGATES = {
+  sum: ["SUM", false],
+  count: ["COUNT", false],
+  cumulative_sum: ["SUM", true],
+  cumulative_count: ["COUNT", true]
+};
+function baseReuseKey(def) {
+  const time = rollupOf(def);
+  const filters = def.filters.map((one) => [one.field, [...one.values].map(String).sort(), one.is_excluded, one.allow_nulls]).sort((a, b) => a[0] - b[0] || JSON.stringify(a).localeCompare(JSON.stringify(b)));
+  return `base:${JSON.stringify([def.template, def.value_field, def.date_field, def.aggregator.toUpperCase(), time, def.is_cumulative, filters])}`;
+}
+function rollupOf(def) {
+  return (def.time_aggregation ?? (def.is_cumulative ? "EOP" : "SUM")).toUpperCase();
+}
+var OPERAND_RE = /'([^']*)'|\[([^[\]]*)\]/g;
+var MARK = "
";
+function calcSkeleton(formula, idOf4) {
+  let missing = false;
+  const ids = /* @__PURE__ */ new Set();
+  const marked2 = formula.replace(OPERAND_RE, (_m, quoted3, bracketed) => {
+    const name = quoted3 ?? bracketed ?? "";
+    if (SYSTEM_VARIABLES.includes(name)) return `${MARK}${name.toLowerCase()}${MARK}`;
+    const id = idOf4(name);
+    if (id === null) {
+      missing = true;
+      return MARK + MARK;
+    }
+    ids.add(id);
+    return `${MARK}#${String(id)}${MARK}`;
+  });
+  if (missing) return null;
+  const skeleton = marked2.split(MARK).map((part, index) => index % 2 === 1 ? part : part.toLowerCase().replace(/\s+/g, "")).join("");
+  return { skeleton, ids: [...ids].sort((a, b) => a - b) };
+}
+function calcReuseKey(formula, idOf4) {
+  const shape = calcSkeleton(formula, idOf4);
+  return shape === null ? null : `calc:${shape.skeleton}|${shape.ids.join(",")}`;
+}
+function rowReuseKey(row, byName) {
+  if (row.kind === "BASE") {
+    if (row.template === null || row.value_field === null || row.date_field === null || row.aggregator === null) return null;
+    return baseReuseKey({
+      template: row.template,
+      value_field: row.value_field,
+      date_field: row.date_field,
+      aggregator: row.aggregator,
+      is_cumulative: row.is_cumulative,
+      time_aggregation: row.time_aggregation,
+      filters: row.filters
+    });
+  }
+  if (row.kind === "CALC" && row.formula !== null) return calcReuseKey(row.formula, (name) => byName.get(name)?.id ?? null);
+  return null;
+}
+var METRIC_CREATED_FOOTER = "Created by App Space for the app";
+var METRIC_CREATED_CATEGORY = "App Space";
+function createdFooter(appName) {
+  return `${METRIC_CREATED_FOOTER} "${appName === "" ? "this app" : appName}".`;
+}
+var METRIC_SHIP_REFUSALS = {
+  metric_name_taken: 'this company already has a metric of that name with a different definition, which App Space may not change in place (it did not create it through you, another app or key reads it, or the published version does) \u2014 use theirs with "reuse": "name", or name yours differently',
+  metric_missing: 'a declaration with "create": false names a metric this company does not have',
+  metric_scope: "creating or changing a metric needs the Datarails scope metrics:write, and this session's credential ceiling does not allow it",
+  metric_table: "a BASE names a table you cannot build metrics on: not one of yours, or a permission filter applies to you (authoring blocked)",
+  metric_field: "a BASE names a field its table does not have, or one with no numeric id",
+  metric_preview: "Datarails could not evaluate a CALC's formula (preview_calc_data) \u2014 its own sentence",
+  metric_operand: "a CALC reads a declaration this ship could not bind",
+  metric_unchecked: "this company's metrics could not be read, so nothing could be bound: ship again shortly",
+  metric_create: "Datarails refused to create or change a metric after the checks passed; the metrics already created are kept, and the next ship reuses them",
+  metric_changed: "a metric this ship created or changed, read back from Datarails before the push, does not hold the definition it wrote (another ship or person changed it meanwhile, or Datarails did not take the whole change); nothing is pushed, and the metrics are kept"
+};
+var FIXES = {
+  metric_name_taken: `Use theirs with "reuse": "name", or give the contract's metric another name.`,
+  metric_missing: 'Create the metric in Datarails, or give the declaration a definition and drop "create": false.',
+  metric_scope: `Ask the agent's owner to add metrics:write to its CLI scope ceiling, or create the metric in Datarails and declare it with "reuse": "name".`,
+  metric_table: "Ask an admin for access to the table, or build the metric on a table you can author on.",
+  metric_field: "Name a field of that table by its alias or its name.",
+  metric_preview: "Fix the formula so Datarails can evaluate it.",
+  metric_operand: "Fix the declaration it reads first.",
+  metric_unchecked: "Ship again shortly; nothing was created.",
+  metric_create: "Fix what it names and ship again; the metrics already created are kept, and the next ship reuses them.",
+  metric_changed: "Ship again: the next plan starts from what Datarails holds now. If it happens again, someone else is changing this metric; check it in Datarails."
+};
+function problem4(code, key, message) {
+  return {
+    code,
+    pointer: key === null ? pointer("data", "metrics") : pointer("data", "metrics", key),
+    message: message.endsWith(".") ? message : `${message}.`,
+    fix: FIXES[code] ?? "Change data.metrics so this company can bind it."
+  };
+}
+function dependencyOrder(decls) {
+  const keys2 = Object.keys(decls).sort();
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const visit = (key, path3) => {
+    if (seen.has(key) || path3.has(key)) return;
+    path3.add(key);
+    for (const dep of operandsOf(decls, key)) if (dep in decls) visit(dep, path3);
+    path3.delete(key);
+    seen.add(key);
+    out.push(key);
+  };
+  for (const key of keys2) visit(key, /* @__PURE__ */ new Set());
+  return out;
+}
+function operandsOf(decls, key) {
+  const decl = decls[key];
+  if (decl === void 0 || decl.kind !== "calc" || typeof decl.formula !== "string") return [];
+  const found = metricFormulaProblems(decl.formula, Object.keys(decls));
+  return found.operands;
+}
+function credentialOf(claims) {
+  const scopes = claims === null ? void 0 : claims["scopes"];
+  const scoped = isAgentScoped(scopes);
+  const entries = scopeEntries(scopes).map(([resource, action]) => `${resource}:${action}`);
+  const canWrite = isAllowed(scopes, "metrics", "write");
+  if (claims === null) {
+    return { scoped: false, can_write: true, scopes: [], line: "scope ceiling not read (this session holds no JWT yet); Datarails decides on create" };
+  }
+  if (!scoped) return { scoped: false, can_write: true, scopes: [], line: "can create metrics (no scope ceiling on this session)" };
+  if (canWrite) return { scoped: true, can_write: true, scopes: entries, line: `can create metrics (this session's scope ceiling, ${entries.join(", ")}, allows metrics:write)` };
+  return { scoped: true, can_write: false, scopes: entries, line: `cannot create or change metrics: this session's scope ceiling (${entries.join(", ")}) does not allow metrics:write` };
+}
+function scopeSentence(key, name, credential, verb) {
+  return `metric "${key}": ${verb} "${name}" needs the Datarails scope metrics:write; this build's credential allows ${credential.scopes.join(", ") || "no write scope"}. Ask the agent's owner to add metrics:write to its CLI scope ceiling, or create the metric in Datarails and declare it with "reuse": "name"`;
+}
+function findAuthTable(tables, ref) {
+  if (ref === void 0) return void 0;
+  if (typeof ref.id === "number") return tables.find((one) => one.id === ref.id);
+  const want = (ref.alias ?? ref.name ?? "").trim();
+  if (want === "") return void 0;
+  const exact = tables.find((one) => ref.alias !== void 0 ? one.alias === want : one.name === want);
+  if (exact !== void 0) return exact;
+  const lower = want.toLowerCase();
+  return tables.find((one) => ref.alias !== void 0 ? (one.alias ?? "").toLowerCase() === lower : one.name.toLowerCase() === lower);
+}
+function findField(fields, named13) {
+  const want = named13.trim();
+  const lower = want.toLowerCase();
+  return fields.find((one) => one.alias === want) ?? fields.find((one) => one.name === want) ?? fields.find((one) => (one.alias ?? "").toLowerCase() === lower) ?? fields.find((one) => one.name.toLowerCase() === lower);
+}
+function tableLabel(ref, found) {
+  if (found !== void 0) return found.name;
+  return ref?.alias ?? ref?.name ?? (ref?.id === void 0 ? "?" : `table ${String(ref.id)}`);
+}
+function describeBase(decl, tableName) {
+  const filters = (decl.filters ?? []).map((one) => `${one.field} ${one.exclude === true ? "not in" : "in"} [${one.values.map(String).join(", ")}]`).join("; ");
+  return `BASE on "${tableName}" (${decl.value ?? "?"} by ${decl.date ?? "?"}, ${(decl.aggregate ?? "?").toUpperCase()}${decl.time_aggregation === void 0 ? "" : `, ${decl.time_aggregation.toUpperCase()} over time`})${filters === "" ? "" : ` where ${filters}`}`;
+}
+function describeRow(row, tables) {
+  if (row.kind === "CALC") return `CALC ${row.formula ?? "(no formula)"}`;
+  if (row.kind !== "BASE") return row.kind === "" ? "a metric" : `a ${row.kind} metric`;
+  const table = tables?.find((one) => one.id === row.template);
+  const field = (id) => {
+    const found = table?.fields?.find((one) => one.id === id);
+    return found === void 0 ? `field ${String(id)}` : found.alias ?? found.name;
+  };
+  const filters = row.filters.map((one) => `${field(one.field)} ${one.is_excluded ? "not in" : "in"} [${one.values.join(", ")}]`).join("; ");
+  const aggregate = `${row.is_cumulative ? "CUMULATIVE_" : ""}${row.aggregator ?? "?"}`;
+  return `BASE on "${table?.name ?? `table ${String(row.template)}`}" (${field(row.value_field)} by ${field(row.date_field)}, ${aggregate}${row.time_aggregation === null ? "" : `, ${row.time_aggregation} over time`})${filters === "" ? "" : ` where ${filters}`}`;
+}
+async function readUsage(t, appId, metricId) {
+  let answer;
+  try {
+    answer = await t.call("GET", `${t.appSpace}/apps/${encodeURIComponent(appId)}/metric-bindings/usage?metric_id=${String(metricId)}`);
+  } catch (err) {
+    return `App Space could not be asked whether it may change it (${firstLine(err)})`;
+  }
+  if (answer.status === 404) return "App Space holds no binding of this app it could show you (a first ship, a server without the usage read, or an app that is not yours)";
+  if (answer.status !== 200) return `App Space could not say whether it may change it (HTTP ${String(answer.status)})`;
+  const one = obj2(obj2(obj2(answer.body)["metrics"])[String(metricId)]);
+  const app = obj2(one["this_app"]);
+  return {
+    created_by_app_space: one["created_by_app_space"] === true,
+    created_by_you: one["created_by_you"] === true,
+    keys: Array.isArray(app["keys"]) ? app["keys"].map(String) : [],
+    published: app["published"] === true,
+    read_elsewhere: one["read_elsewhere"] === true,
+    in_place_allowed: one["in_place_allowed"] === true
+  };
+}
+function editRefusal(usage, key, row) {
+  if (typeof usage === "string") return usage;
+  if (!usage.created_by_app_space) return "App Space did not create it";
+  if (!usage.created_by_you) return "App Space created it for someone else, and only its creator may change it in place";
+  if (usage.read_elsewhere) return "another app reads it";
+  if (usage.keys.some((one) => one !== key)) return `this app also reads it as ${usage.keys.filter((one) => one !== key).map((one) => `"${one}"`).join(", ")}`;
+  if (usage.published) return "the app's published version reads it, and its viewers would see the change before you publish";
+  if (!usage.in_place_allowed) return "App Space does not allow it";
+  if (!(row.description ?? "").includes(METRIC_CREATED_FOOTER)) return "its description no longer carries App Space's marker, so the push would not keep it as App Space's";
+  return null;
+}
+async function planMetrics(contract, t, opts) {
+  const decls = declaredMetrics(contract);
+  const catalog = await readCatalog(t);
+  const claims = t.claims();
+  const credential = credentialOf(claims);
+  const byName = new Map(catalog.map((row) => [row.name, row]));
+  const byId = new Map(catalog.map((row) => [row.id, row]));
+  const rowKeys2 = new Map(catalog.map((row) => [row.id, rowReuseKey(row, byName)]));
+  const plan = {
+    server: t.serverKey,
+    host: t.host,
+    org: typeof claims?.["organization_id"] === "number" ? claims["organization_id"] : null,
+    user: typeof claims?.["email"] === "string" ? claims["email"] : t.email,
+    app_id: opts.appId,
+    entries: [],
+    credential,
+    not_checked: [],
+    notes: [],
+    problems: [],
+    internal: { decls, catalog, tables: null, base: {}, tableOf: {}, appName: opts.appName }
+  };
+  if (t.overridden) {
+    plan.notes.push(`metrics are read and created on ${t.host} (the Datarails host of ${t.serverKey}), not on --app-space-host ${t.appSpace}`);
+  }
+  const needsTables = Object.values(decls).some((decl) => decl.kind === "base" && decl.table !== void 0);
+  let tables = null;
+  let tablesWhy = null;
+  if (needsTables) {
+    try {
+      tables = await readAuthTables(t);
+    } catch (err) {
+      tablesWhy = err instanceof Error ? err.message : String(err);
+    }
+  }
+  plan.internal.tables = tables;
+  const fieldsRead = /* @__PURE__ */ new Map();
+  const fieldsOf = async (table) => {
+    if (table.fields !== null) return table.fields;
+    const held = fieldsRead.get(table.id);
+    if (held !== void 0) return held;
+    let got;
+    try {
+      got = await readTableFields(t, table.id);
+    } catch (err) {
+      got = err instanceof Error ? err.message : String(err);
+    }
+    fieldsRead.set(table.id, got);
+    return got;
+  };
+  const resolved = /* @__PURE__ */ new Map();
+  for (const key of dependencyOrder(decls)) {
+    const decl = decls[key];
+    const kind = decl.kind === "base" || decl.kind === "calc" ? decl.kind : null;
+    const entry = { key, name: decl.name, kind, action: "refuse", metric_id: null, metric_name: null, origin: null, reuse_key: null, definition: "", note: "" };
+    const refuse2 = (code, message, note) => {
+      entry.action = "refuse";
+      entry.code = code;
+      entry.message = message;
+      entry.note = note ?? message;
+      plan.problems.push(problem4(code, key, message));
+    };
+    resolved.set(key, entry);
+    let wire = null;
+    let pendingOperands = [];
+    let defProblem = null;
+    if (kind === "calc" && typeof decl.formula === "string") {
+      const operands = operandsOf(decls, key);
+      const names = {};
+      const ids = {};
+      for (const operand of operands) {
+        const dep = resolved.get(operand);
+        if (dep === void 0 || dep.action === "refuse") {
+          defProblem = { code: "metric_operand", message: `metric "${key}" reads [@${operand}], which this ship cannot bind (see "${operand}")` };
+          break;
+        }
+        if (dep.action === "create") {
+          pendingOperands.push(operand);
+          names[operand] = dep.name;
+        } else {
+          names[operand] = dep.metric_name ?? dep.name;
+          if (dep.metric_id !== null) ids[operand] = dep.metric_id;
+        }
+      }
+      if (defProblem === null) {
+        try {
+          wire = wireFormula(decl.formula, names);
+        } catch (err) {
+          defProblem = { code: "metric_preview", message: `metric "${key}"'s formula ${firstLine(err)}` };
+        }
+      }
+      if (wire !== null) {
+        entry.definition = `CALC ${wire}`;
+        if (pendingOperands.length === 0) {
+          const nameToId = new Map(Object.entries(names).map(([operand, name]) => [name, ids[operand] ?? null]));
+          entry.reuse_key = calcReuseKey(wire, (name) => nameToId.get(name) ?? null);
+        }
+      }
+    } else if (kind === "base") {
+      const table = tables === null ? void 0 : findAuthTable(tables, decl.table);
+      entry.definition = describeBase(decl, tableLabel(decl.table, table));
+      if (tables === null) {
+        defProblem = { code: "metric_table", message: `metric "${key}": ${tablesWhy ?? "the tables could not be read"}` };
+      } else if (table === void 0) {
+        defProblem = { code: "metric_table", message: `metric "${key}": this company has no table "${tableLabel(decl.table)}" you can build metrics on` };
+      } else {
+        plan.internal.tableOf[key] = table;
+        const fields = await fieldsOf(table);
+        if (typeof fields === "string") {
+          defProblem = { code: "metric_field", message: `metric "${key}": ${fields}` };
+        } else {
+          const want = [decl.value ?? "", decl.date ?? "", ...(decl.filters ?? []).map((one) => one.field)];
+          const found = want.map((named14) => findField(fields, named14));
+          const missing = want.find((_named, index) => found[index] === void 0);
+          const noId = found.find((one) => one !== void 0 && one.id === null);
+          const aggregate = AGGREGATES[(decl.aggregate ?? "").toLowerCase()];
+          if (missing !== void 0) {
+            defProblem = { code: "metric_field", message: `metric "${key}": the table "${table.name}" has no field "${missing}" (by alias or name)` };
+          } else if (noId !== void 0) {
+            defProblem = { code: "metric_field", message: `metric "${key}": the field "${noId.alias ?? noId.name}" of "${table.name}" has no numeric id, so it cannot be a BASE operand` };
+          } else if (aggregate === void 0) {
+            defProblem = { code: "metric_field", message: `metric "${key}": ${JSON.stringify(decl.aggregate)} is not an aggregate Datarails takes` };
+          } else {
+            const def = {
+              template: table.id,
+              value_field: found[0]?.id,
+              date_field: found[1]?.id,
+              aggregator: aggregate[0],
+              is_cumulative: aggregate[1],
+              time_aggregation: decl.time_aggregation === void 0 ? null : decl.time_aggregation.toUpperCase(),
+              filters: (decl.filters ?? []).map((one, index) => ({
+                field: found[index + 2]?.id,
+                values: one.values.map(String),
+                is_excluded: one.exclude === true,
+                allow_nulls: false
+              }))
+            };
+            plan.internal.base[key] = def;
+            entry.reuse_key = baseReuseKey(def);
+          }
+        }
+      }
+    }
+    const named13 = byName.get(decl.name);
+    if (entry.reuse_key !== null) {
+      const same5 = catalog.filter((row) => rowKeys2.get(row.id) === entry.reuse_key).sort((a, b) => Number(b.name === decl.name) - Number(a.name === decl.name) || (a.created_at ?? "").localeCompare(b.created_at ?? "") || a.id - b.id);
+      const hit = same5[0];
+      if (hit !== void 0) {
+        entry.action = "reuse";
+        entry.metric_id = hit.id;
+        entry.metric_name = hit.name;
+        entry.origin = "reused";
+        entry.note = hit.name === decl.name ? "the same definition" : `the same definition, named "${hit.name}" in this company (not a clash)`;
+        continue;
+      }
+    }
+    if (decl.reuse === "name" && named13 !== void 0) {
+      entry.action = "bind";
+      entry.metric_id = named13.id;
+      entry.metric_name = named13.name;
+      entry.origin = "named";
+      const theirs = describeRow(named13, tables);
+      entry.note = kind === null ? "by name" : entry.reuse_key === null ? `by name (the contract's definition could not be compared here: ${defProblem?.message ?? "an operand is created on push"})` : `by name; its definition differs: ${theirs} against the contract's ${entry.definition}`;
+      continue;
+    }
+    if (defProblem !== null) {
+      refuse2(defProblem.code, defProblem.message);
+      continue;
+    }
+    if (named13 !== void 0 && kind !== null) {
+      const theirs = describeRow(named13, tables);
+      const sameKind = named13.kind === kind.toUpperCase();
+      const previous = rowKeys2.get(named13.id) ?? null;
+      let why = null;
+      if (decl.create === false) why = 'the declaration says "create": false, so this ship writes nothing';
+      else if (!sameKind) why = `it is a ${named13.kind || "different"} metric, and a ${kind.toUpperCase()} cannot replace it in place`;
+      else if (opts.appId === null || opts.appId === "") why = "the contract names no app id to ask App Space about";
+      else if (previous === null) why = "its current definition could not be read in full, so a change could not be recorded";
+      else if (entry.reuse_key === null && pendingOperands.length === 0) why = "the contract's definition could not be compared";
+      else why = editRefusal(await readUsage(t, opts.appId, named13.id), key, named13);
+      if (why === null) {
+        if (!credential.can_write) {
+          refuse2("metric_scope", scopeSentence(key, decl.name, credential, "changing"), `would change in place, but ${credential.line}`);
+          continue;
+        }
+        entry.action = "edit";
+        entry.metric_id = named13.id;
+        entry.metric_name = named13.name;
+        entry.origin = "created";
+        entry.previous_reuse_key = previous;
+        entry.old_definition = theirs;
+        entry.new_definition = entry.definition;
+        entry.note = `in place (App Space made it for this app): was ${theirs}; becomes ${entry.definition}`;
+        if (kind === "calc" && wire !== null && pendingOperands.length === 0) {
+          const preview2 = await previewFormula(t, wire);
+          if (preview2 !== null) {
+            refuse2("metric_preview", `metric "${key}": Datarails could not evaluate ${wire}: ${preview2}`);
+            continue;
+          }
+          entry.preview = "ok";
+        } else if (pendingOperands.length > 0) {
+          entry.after = pendingOperands;
+          entry.preview = "not checked";
+          plan.not_checked.push(`the formula of "${decl.name}" (its operand ${pendingOperands.map((one) => `"${resolved.get(one)?.name ?? one}"`).join(", ")} is created on push)`);
+        }
+        continue;
+      }
+      const message = `metric "${key}": this company already has a metric named "${named13.name}" (id ${String(named13.id)}) with a different definition: ${theirs} against the contract's ${entry.definition}. Either use theirs ("reuse": "name"), or give the contract's metric another name (App Space may not change it in place: ${why})`;
+      refuse2("metric_name_taken", message, `name taken by id ${String(named13.id)} with another definition: see above`);
+      continue;
+    }
+    if (decl.create === false || kind === null) {
+      refuse2("metric_missing", `metric "${key}": this company has no metric named "${decl.name}"; create it in Datarails, or give the declaration a definition`);
+      continue;
+    }
+    if (!credential.can_write) {
+      refuse2("metric_scope", scopeSentence(key, decl.name, credential, "creating"), `would create, but ${credential.line}`);
+      continue;
+    }
+    if (kind === "base") {
+      const table = plan.internal.tableOf[key];
+      if (table?.blocked === true) {
+        refuse2("metric_table", `metric "${key}": you can't build metrics on the table "${table.name}" (a permission filter applies to you); ask an admin for access`);
+        continue;
+      }
+      entry.action = "create";
+      entry.note = `${entry.definition}; extracts after creation`;
+      continue;
+    }
+    entry.action = "create";
+    if (pendingOperands.length > 0) {
+      entry.after = pendingOperands;
+      entry.preview = "not checked";
+      entry.note = `${entry.definition}; created after ${pendingOperands.map((one) => `"${one}"`).join(", ")}`;
+      plan.not_checked.push(`the formula of "${decl.name}" (its operand ${pendingOperands.map((one) => `"${resolved.get(one)?.name ?? one}"`).join(", ")} is created on push)`);
+      continue;
+    }
+    const preview = await previewFormula(t, wire);
+    if (preview !== null) {
+      refuse2("metric_preview", `metric "${key}": Datarails could not evaluate ${wire}: ${preview}`);
+      continue;
+    }
+    entry.preview = "ok";
+    entry.note = `${entry.definition}  preview ok`;
+  }
+  const order2 = Object.keys(decls);
+  plan.entries = [...resolved.values()].sort((a, b) => order2.indexOf(a.key) - order2.indexOf(b.key));
+  for (const entry of plan.entries) {
+    if (entry.metric_id !== null && !byId.has(entry.metric_id)) entry.metric_id = null;
+  }
+  return plan;
+}
+async function previewFormula(t, wire) {
+  let answer;
+  try {
+    answer = await t.call("PUT", `${t.host}/api/insights/metrics/preview_calc_data`, { formula: wire, time_aggregation: "SUM" });
+  } catch (err) {
+    return `the preview could not be run (${firstLine(err)})`;
+  }
+  const body = obj2(decodeEntities2(answer.body));
+  if (answer.status >= 200 && answer.status < 300 && body["success"] !== false) return null;
+  return sentenceOf(body) || `HTTP ${String(answer.status)}`;
+}
+var METRICS_WAIT_CAP = 120;
+var METRICS_WAIT_DEFAULT = 60;
+var POLL_MS = 5e3;
+function metricsWaitOf(raw) {
+  if (raw === void 0 || raw === "") return { seconds: METRICS_WAIT_DEFAULT, note: null };
+  const value = typeof raw === "number" ? raw : Number(raw);
+  if (!Number.isFinite(value) || value < 0) {
+    throw new Error(`--metrics-wait ${String(raw)} is not a number of seconds; give 0 to ${String(METRICS_WAIT_CAP)}`);
+  }
+  if (value > METRICS_WAIT_CAP) {
+    return { seconds: METRICS_WAIT_CAP, note: `--metrics-wait ${String(raw)} is over the cap; waiting at most ${String(METRICS_WAIT_CAP)} s` };
+  }
+  return { seconds: Math.floor(value), note: null };
+}
+async function applyPlan(plan, t, opts) {
+  const out = { ok: true, bindings: {}, created: [], problems: [], notes: [] };
+  if (plan.problems.length > 0) {
+    out.ok = false;
+    out.problems = [...plan.problems];
+    return out;
+  }
+  const { decls } = plan.internal;
+  const byKey2 = new Map(plan.entries.map((entry) => [entry.key, entry]));
+  let category;
+  const fail = (key, message) => {
+    out.ok = false;
+    out.problems.push(problem4("metric_create", key, message));
+    return out;
+  };
+  const waitFor = [];
+  for (const key of dependencyOrder(decls)) {
+    const entry = byKey2.get(key);
+    const decl = decls[key];
+    if (entry === void 0 || decl === void 0) continue;
+    if (entry.action === "reuse" || entry.action === "bind") continue;
+    if (entry.action !== "create" && entry.action !== "edit") continue;
+    let wire = null;
+    if (entry.kind === "calc" && typeof decl.formula === "string") {
+      const names = {};
+      const ids = /* @__PURE__ */ new Map();
+      for (const operand of operandsOf(decls, key)) {
+        const dep = byKey2.get(operand);
+        names[operand] = dep?.metric_name ?? dep?.name ?? operand;
+        ids.set(names[operand], dep?.metric_id ?? null);
+      }
+      wire = wireFormula(decl.formula, names);
+      entry.definition = `CALC ${wire}`;
+      if (entry.action === "edit") entry.new_definition = entry.definition;
+      entry.reuse_key = calcReuseKey(wire, (name) => ids.get(name) ?? null);
+      if (entry.preview !== "ok") {
+        const preview = await previewFormula(t, wire);
+        if (preview !== null) return fail(key, `metric "${key}": Datarails could not evaluate ${wire}: ${preview}`);
+        entry.preview = "ok";
+      }
+    }
+    if (entry.action === "edit") {
+      const body2 = entry.kind === "calc" ? { configuration: { presented_formula: wire, ...formatOf(decl, plan, entry) } } : baseBody(plan.internal.base[key]);
+      const answer2 = await t.call("PATCH", `${t.host}/api/insights/metrics/${String(entry.metric_id)}`, body2).catch((err) => ({ status: 0, body: firstLine(err) }));
+      if (answer2.status < 200 || answer2.status >= 300) {
+        return fail(key, `metric "${key}": Datarails refused to change "${entry.metric_name ?? entry.name}" (id ${String(entry.metric_id)}) in place: ${refusalSentence(answer2, entry, plan)}`);
+      }
+      out.created.push({ key, id: entry.metric_id, name: entry.metric_name ?? entry.name, action: "edit" });
+      if (entry.kind === "base") waitFor.push(entry);
+      continue;
+    }
+    if (category === void 0) {
+      category = await appSpaceCategory(t, out.notes);
+    }
+    const description = [decl.description ?? "", createdFooter(plan.internal.appName)].filter((one) => one !== "").join("\n\n");
+    const body = entry.kind === "calc" ? { name: decl.name, kind: "CALC", configuration: { presented_formula: wire, ...decl.format === void 0 ? {} : { format: decl.format } } } : { name: decl.name, kind: "BASE", ...baseBody(plan.internal.base[key]), ...decl.format === void 0 ? {} : { configuration: { presented_formula: "", format: decl.format } } };
+    body["description"] = description;
+    body["is_approved_by_user"] = true;
+    if (category !== null) body["category"] = category;
+    const answer = await t.call("POST", `${t.host}/api/insights/metrics`, body).catch((err) => ({ status: 0, body: firstLine(err) }));
+    if (answer.status === 422) {
+      let again;
+      try {
+        again = await readCatalog(t);
+      } catch (err) {
+        return fail(key, `metric "${key}": Datarails says a metric named "${decl.name}" exists, and the catalog could not be read again to tell whose (${firstLine(err)})`);
+      }
+      const byName = new Map(again.map((row) => [row.name, row]));
+      const holder = byName.get(decl.name);
+      if (holder === void 0) {
+        return fail(key, `metric "${key}": a metric named "${decl.name}" exists in this company, but its source tables are not shared with you`);
+      }
+      if (entry.reuse_key !== null && rowReuseKey(holder, byName) === entry.reuse_key) {
+        entry.action = "reuse";
+        entry.origin = "reused";
+        entry.metric_id = holder.id;
+        entry.metric_name = holder.name;
+        entry.note = "the same definition (another ship created it a moment ago)";
+        continue;
+      }
+      return fail(
+        key,
+        `metric "${key}": this company now has a metric named "${decl.name}" (id ${String(holder.id)}) with a different definition: ${describeRow(holder, plan.internal.tables)} against the contract's ${entry.definition}. Either use theirs ("reuse": "name"), or give the contract's metric another name`
+      );
+    }
+    if (answer.status < 200 || answer.status >= 300) {
+      return fail(key, `metric "${key}": Datarails refused to create "${decl.name}": ${refusalSentence(answer, entry, plan)}`);
+    }
+    const created = obj2(decodeEntities2(answer.body));
+    const id = idIn(created["id"]);
+    if (id === null || id === 0) return fail(key, `metric "${key}": Datarails created "${decl.name}" and answered no id for it`);
+    entry.metric_id = id;
+    entry.metric_name = typeof created["name"] === "string" && created["name"] !== "" ? created["name"] : decl.name;
+    entry.origin = "created";
+    out.created.push({ key, id, name: entry.metric_name, action: "create" });
+    if (entry.kind === "base") waitFor.push(entry);
+  }
+  if (waitFor.length > 0) await waitForExtraction(t, waitFor, opts, out.notes);
+  const written = plan.entries.filter((entry) => out.created.some((one) => one.key === entry.key));
+  if (written.length > 0) {
+    const drifted = await readBack(t, plan, written);
+    if (drifted.length > 0) {
+      out.ok = false;
+      out.problems.push(...drifted);
+      return out;
+    }
+  }
+  for (const entry of plan.entries) {
+    if (entry.metric_id === null || entry.origin === null) continue;
+    out.bindings[entry.key] = {
+      metric_id: entry.metric_id,
+      origin: entry.origin,
+      ...entry.reuse_key === null ? {} : { reuse_key: entry.reuse_key },
+      ...entry.action === "edit" && typeof entry.previous_reuse_key === "string" ? { previous_reuse_key: entry.previous_reuse_key } : {}
+    };
+  }
+  return out;
+}
+async function readBack(t, plan, written) {
+  let catalog;
+  try {
+    catalog = await readCatalog(t);
+  } catch (err) {
+    return [
+      problem4(
+        "metric_changed",
+        null,
+        `${firstLine(err)} after this ship wrote ${written.map((entry) => `"${entry.metric_name ?? entry.name}"`).join(", ")}, so what Datarails holds could not be checked against the contract; nothing was pushed`
+      )
+    ];
+  }
+  const byName = new Map(catalog.map((row) => [row.name, row]));
+  const problems = [];
+  for (const entry of written) {
+    const label = `"${entry.metric_name ?? entry.name}" (id ${String(entry.metric_id)})`;
+    const row = catalog.find((one) => one.id === entry.metric_id);
+    if (row === void 0) {
+      problems.push(problem4("metric_changed", entry.key, `metric "${entry.key}": ${label} is not among this company's metrics you can read, just after this ship wrote it; nothing was pushed`));
+      continue;
+    }
+    const held = rowReuseKey(row, byName);
+    if (held === null || entry.reuse_key === null) {
+      problems.push(
+        problem4(
+          "metric_changed",
+          entry.key,
+          `metric "${entry.key}": ${label} could not be read back in full after this ship wrote it (Datarails holds ${describeRow(row, plan.internal.tables)}), so it could not be compared with the contract's ${entry.definition}; nothing was pushed`
+        )
+      );
+      continue;
+    }
+    if (held !== entry.reuse_key) {
+      problems.push(
+        problem4(
+          "metric_changed",
+          entry.key,
+          `metric "${entry.key}": Datarails now holds a different definition for ${label} than this ship wrote: ${describeRow(row, plan.internal.tables)} against the contract's ${entry.definition}. Another ship or person changed it after this ship wrote it, or Datarails did not take the whole change; nothing was pushed`
+        )
+      );
+      continue;
+    }
+    entry.reuse_key = held;
+    entry.metric_name = row.name;
+  }
+  return problems;
+}
+function formatOf(decl, plan, entry) {
+  if (decl.format !== void 0) return { format: decl.format };
+  const row = plan.internal.catalog.find((one) => one.id === entry.metric_id);
+  return row?.format === null || row?.format === void 0 ? {} : { format: row.format };
+}
+function baseBody(def) {
+  return {
+    template: def.template,
+    value_field: def.value_field,
+    date_field: def.date_field,
+    aggregator: def.aggregator,
+    is_cumulative: def.is_cumulative,
+    time_aggregation: rollupOf(def),
+    filters: def.filters.map((one) => ({
+      field: one.field,
+      values: one.values,
+      is_excluded: one.is_excluded,
+      allow_nulls: one.allow_nulls,
+      override_global_filter: false
+    }))
+  };
+}
+async function appSpaceCategory(t, notes) {
+  try {
+    const listed = await t.call("GET", `${t.host}/api/insights/metric_categories`);
+    if (listed.status >= 200 && listed.status < 300) {
+      const found = listOf(decodeEntities2(listed.body)).find((one) => one["name"] === METRIC_CREATED_CATEGORY);
+      const id = found === void 0 ? null : idIn(found["id"]);
+      if (id !== null) return id;
+      const made = await t.call("POST", `${t.host}/api/insights/metric_categories`, { name: METRIC_CREATED_CATEGORY });
+      const madeId = made.status >= 200 && made.status < 300 ? idIn(obj2(made.body)["id"]) : null;
+      if (madeId !== null) return madeId;
+      notes.push(`the metrics are not filed under the "${METRIC_CREATED_CATEGORY}" category (creating it answered HTTP ${String(made.status)}); their description still says App Space made them`);
+      return null;
+    }
+    notes.push(`the metrics are not filed under the "${METRIC_CREATED_CATEGORY}" category (the categories answered HTTP ${String(listed.status)}); their description still says App Space made them`);
+  } catch (err) {
+    notes.push(`the metrics are not filed under the "${METRIC_CREATED_CATEGORY}" category (${firstLine(err)}); their description still says App Space made them`);
+  }
+  return null;
+}
+function refusalSentence(answer, entry, plan) {
+  const said2 = sentenceOf(decodeEntities2(answer.body));
+  const table = plan.internal.tableOf[entry.key];
+  if (answer.status === 400 && /invalid pk/i.test(JSON.stringify(answer.body ?? "")) && /template/.test(JSON.stringify(answer.body ?? ""))) {
+    return `you can't build metrics on the table "${table?.name ?? "?"}"; ask an admin for access`;
+  }
+  if (answer.status === 403 && /do not have access to this metric/i.test(said2)) {
+    return entry.kind === "base" ? `the table "${table?.name ?? "?"}" has a permission filter on you (authoring blocked); ask an admin for access` : "one of its operands reads data you cannot see; ask an admin to share its source tables";
+  }
+  if (answer.status === 403) {
+    return `this credential was refused (403${said2 === "" ? "" : `: ${said2}`}); it may lack the Datarails scope metrics:write \u2014 ask the agent's owner to add it to its CLI scope ceiling, or create the metric in Datarails and declare it with "reuse": "name"`;
+  }
+  if (answer.status === 404) return "it no longer exists in this company";
+  if (answer.status === 0) return `the request did not complete (${String(answer.body)})`;
+  return said2 === "" ? `HTTP ${String(answer.status)}` : `${said2} (HTTP ${String(answer.status)})`;
+}
+async function waitForExtraction(t, entries, opts, notes) {
+  const sleep3 = opts.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+  const now = opts.now ?? (() => Date.now());
+  const deadline = now() + Math.max(0, Math.min(opts.waitSeconds, METRICS_WAIT_CAP)) * 1e3;
+  let waiting = entries;
+  for (; ; ) {
+    const still = [];
+    for (const entry of waiting) {
+      const answer = await t.call("GET", `${t.host}/api/insights/metrics/${String(entry.metric_id)}`).catch(() => null);
+      const row = answer !== null && answer.status === 200 && isObj3(answer.body) ? catalogRow(answer.body) : null;
+      entry.status = row?.status ?? entry.status ?? null;
+      if (entry.status === null || entry.status === "PROCESSING") still.push(entry);
+    }
+    waiting = still;
+    if (waiting.length === 0 || now() + POLL_MS > deadline) break;
+    await sleep3(POLL_MS);
+  }
+  for (const entry of waiting) {
+    entry.status = entry.status ?? "PROCESSING";
+    notes.push(`"${entry.metric_name ?? entry.name}" is still being prepared in Datarails; its cards say so until it is ready`);
+  }
+}
+function bindingWarnings(answer) {
+  const block = obj2(answer);
+  const rows2 = (value) => (Array.isArray(value) ? value : []).map(
+    (one) => isObj3(one) ? {
+      key: String(one["key"] ?? "?"),
+      field: typeof one["field"] === "string" ? one["field"] : null,
+      reason: typeof one["reason"] === "string" && one["reason"] !== "" ? one["reason"] : null
+    } : { key: String(one), field: null, reason: null }
+  );
+  const lines = [];
+  for (const one of rows2(block["downgraded"])) {
+    lines.push(
+      `metric "${one.key}" was sent as created by App Space and kept as reused${one.reason === null ? "" : ` (${one.reason})`}: App Space will not change it in place later`
+    );
+  }
+  for (const one of rows2(block["ignored"])) {
+    if (one.field === null || one.field === "previous_reuse_key") {
+      lines.push(
+        `metric "${one.key}" was changed in place in Datarails, and the platform did NOT record the change${one.reason === null ? "" : ` (${one.reason})`}: the metric holds the new definition; check it in Datarails`
+      );
+    } else {
+      lines.push(`metric "${one.key}": the platform did not record ${one.field}${one.reason === null ? "" : ` (${one.reason})`}`);
+    }
+  }
+  return lines;
+}
+function renderPlan(plan) {
+  const head = `Metrics on ${plan.server}${plan.org === null ? "" : ` (org ${String(plan.org)})`}${plan.user === null ? "" : `, as ${plan.user}`}:
+`;
+  const label = (entry) => `${entry.metric_name ?? entry.name}${entry.metric_id === null ? "" : ` (id ${String(entry.metric_id)})`}`;
+  const keyWidth = Math.max(...plan.entries.map((entry) => entry.key.length), 3) + 2;
+  const nameWidth = Math.max(...plan.entries.map((entry) => label(entry).length), 4) + 2;
+  let out = head;
+  for (const entry of plan.entries) {
+    const action = entry.action === "edit" ? "change" : entry.action;
+    out += `  ${entry.key.padEnd(keyWidth)}${label(entry).padEnd(nameWidth)}${action.padEnd(9)}${entry.note}
+`;
+    if (entry.action === "edit") {
+      out += `  ${" ".repeat(keyWidth + nameWidth + 9)}was: ${entry.old_definition ?? "?"}
+`;
+      out += `  ${" ".repeat(keyWidth + nameWidth + 9)}now: ${entry.new_definition ?? "?"}
+`;
+    }
+  }
+  out += `Credential: ${plan.credential.line}
+`;
+  for (const note of plan.notes) out += `note: ${note}
+`;
+  for (const one of plan.not_checked) out += `Not checked: ${one}
+`;
+  return out;
+}
+function renderApplied(plan, applied) {
+  let out = "";
+  for (const one of applied.created) {
+    const entry = plan.entries.find((candidate) => candidate.key === one.key);
+    if (one.action === "edit") {
+      out += `metric "${one.key}": changed "${one.name}" (id ${String(one.id)}) in place
+  was: ${entry?.old_definition ?? "?"}
+  now: ${entry?.new_definition ?? "?"}
+`;
+    } else {
+      out += `metric "${one.key}": created "${one.name}" (id ${String(one.id)})${entry?.status === void 0 || entry.status === null ? "" : `, ${entry.status.toLowerCase()}`}
+`;
+    }
+  }
+  for (const note of applied.notes) out += `note: ${note}
+`;
+  return out;
+}
+function planReport(plan, applied) {
+  return {
+    server: plan.server,
+    host: plan.host,
+    org: plan.org,
+    user: plan.user,
+    credential: plan.credential,
+    entries: plan.entries.map((entry) => ({
+      key: entry.key,
+      name: entry.name,
+      kind: entry.kind,
+      action: entry.action,
+      metric_id: entry.metric_id,
+      metric_name: entry.metric_name,
+      origin: entry.origin,
+      definition: entry.definition,
+      note: entry.note,
+      ...entry.preview === void 0 ? {} : { preview: entry.preview },
+      ...entry.after === void 0 ? {} : { after: entry.after },
+      ...entry.code === void 0 ? {} : { code: entry.code, message: entry.message },
+      ...entry.action === "edit" ? { old_definition: entry.old_definition, new_definition: entry.new_definition } : {},
+      ...entry.status === void 0 ? {} : { status: entry.status }
+    })),
+    not_checked: plan.not_checked,
+    notes: [...plan.notes, ...applied?.notes ?? []],
+    ...applied === void 0 ? {} : { created: applied.created, bindings: applied.bindings, ok: applied.ok }
+  };
+}
+async function checkMetricSources(t, appId, contract) {
+  const out = [];
+  for (const [source, key] of Object.entries(metricSources(contract))) {
+    let answer;
+    try {
+      answer = await t.call("POST", `${t.appSpace}/preview/apps/${encodeURIComponent(appId)}/${encodeURIComponent(source)}`, { op: "load" });
+    } catch (err) {
+      out.push({ source, key, state: "unchecked", message: `could not be run (${firstLine(err)})` });
+      continue;
+    }
+    if (answer.status < 200 || answer.status >= 300) {
+      out.push({ source, key, ...previewRefusal(answer) });
+      continue;
+    }
+    if (!isObj3(answer.body)) {
+      out.push({ source, key, state: "unchecked", message: `could not be read (the preview answered HTTP ${String(answer.status)} with no source answer)` });
+      continue;
+    }
+    const body = answer.body;
+    const held = isObj3(body["result"]) && !("meta" in body) ? obj2(body["result"]) : body;
+    if (!("error" in held) && !("meta" in held) && !("rows" in held)) {
+      out.push({ source, key, state: "unchecked", message: `could not be read (the preview answered HTTP ${String(answer.status)} with no source answer)` });
+      continue;
+    }
+    const status = obj2(obj2(held["meta"])["source"])["status"];
+    const error = typeof held["error"] === "string" ? held["error"] : "";
+    if (status === "processing") out.push({ source, key, state: "preparing", message: error || "Datarails is preparing the metric" });
+    else if (error !== "" || status === "unbound" || status === "gone" || status === "error") {
+      out.push({ source, key, state: "failed", message: error || `the metric is ${String(status)}` });
+    } else out.push({ source, key, state: "figure", message: "read" });
+  }
+  return out;
+}
+var PREVIEW_UNAVAILABLE = /* @__PURE__ */ new Set([401, 403, 407, 408, 429, 502, 503, 504]);
+function previewRefusal(answer) {
+  const said2 = sentenceOf(answer.body);
+  const http = `HTTP ${String(answer.status)}${said2 === "" ? "" : `: ${said2}`}`;
+  if (PREVIEW_UNAVAILABLE.has(answer.status) || !isObj3(answer.body)) {
+    return { state: "unchecked", message: `could not be run (${http})` };
+  }
+  if (answer.status >= 500) {
+    return { state: "failed", message: `its handler failed once pushed (${http}); \`app-space logs <app-id>\` says why` };
+  }
+  return { state: "failed", message: `the preview refused it once pushed (${http})` };
+}
+function sentenceOf(body) {
+  if (typeof body === "string") return /^<(!doctype html|html)/i.test(body.trimStart()) ? "" : body.trim().slice(0, 300);
+  if (!isObj3(body)) return "";
+  const error = body["error"];
+  if (typeof error === "string") return error;
+  if (isObj3(error) && typeof error["message"] === "string") return error["message"];
+  if (typeof body["detail"] === "string") return body["detail"];
+  const parts = [];
+  for (const [field, value] of Object.entries(body)) {
+    if (field === "success") continue;
+    const said2 = Array.isArray(value) ? value.map((one) => typeof one === "string" ? one : JSON.stringify(one)).join(" ") : typeof value === "string" ? value : "";
+    if (said2 !== "") parts.push(`${field}: ${said2}`);
+  }
+  return parts.join("; ").slice(0, 300);
+}
+function firstLine(err) {
+  return (err instanceof Error ? err.message : String(err)).split("\n")[0] ?? "";
+}
+function isObj3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function obj2(value) {
+  return isObj3(value) ? value : {};
+}
+
+// src/commands/appspace/push.ts
 var KIT_ENV = "DR_APPSPACE_KIT";
 function kitForPush(opts, env = process.env) {
   const flag = (opts.kit ?? "").trim();
@@ -21804,12 +22936,39 @@ function describePostCommit(result) {
   }
   return lines.join("");
 }
+async function bindForPush(client, appId, contract, opts) {
+  const transport = metricsTransport(client);
+  const app = contract?.app;
+  const appName = typeof app?.name === "string" ? app.name : appId;
+  const plan = await planMetrics(contract, transport, { appId, appName });
+  process.stderr.write(renderPlan(plan));
+  if (plan.problems.length > 0) {
+    throw new Error(`the Datarails metrics this app declares cannot be bound here; nothing was created or pushed:
+${formatProblems(plan.problems)}`);
+  }
+  const wait = metricsWaitOf(opts.metricsWait);
+  if (wait.note !== null) process.stderr.write(`note: ${wait.note}
+`);
+  const applied = await applyPlan(plan, transport, { waitSeconds: wait.seconds });
+  process.stderr.write(renderApplied(plan, applied));
+  if (!applied.ok) {
+    const kept = applied.created.map((one) => `"${one.name}" (id ${String(one.id)})`).join(", ");
+    throw new Error(
+      `a Datarails metric could not be created, so nothing was pushed${kept === "" ? "" : `; kept, and reused by the next push: ${kept}`}:
+${formatProblems(applied.problems)}`
+    );
+  }
+  return applied.bindings;
+}
 function registerPushCommand(parent) {
   withJsonOption(
     withServerOptions(
       parent.command("push [dir]").description("Push a folder to App Space as a draft.").option("--publish", "Publish it too (needs an admin role).").option("--seed <file>", "Seed rows, as JSON. Only fills empty tables.").option("--force", "Push even if the app changed since you fetched it.").option("--no-contract", "Do not extract and attach the app contract.").option(
         "--kit <asset>",
         `The builder kit that made this app, e.g. appspace-app-kit@12 (default: $${KIT_ENV}). Recorded as the contract row's kit_version; omitted when neither is set.`
+      ).option(
+        "--metrics-wait <seconds>",
+        "When the contract declares Datarails metrics (data.metrics) and this push creates a BASE one, how long to wait for it to extract before pushing anyway (default 60, at most 120)."
       )
     )
   ).action(async (dirArg, opts) => {
@@ -21851,6 +23010,9 @@ async function pushBody(dir, opts) {
   if (opts.force !== true && typeof state.revision === "number") {
     body["expected_revision"] = state.revision;
   }
+  if (opts.metricBindings !== void 0 && Object.keys(opts.metricBindings).length > 0) {
+    body["metric_bindings"] = opts.metricBindings;
+  }
   return { appId, body, handlers };
 }
 function chartsWithoutEcharts(files) {
@@ -21872,6 +23034,9 @@ async function pushFolder(dir, opts) {
   const { appId, body, handlers } = await pushBody(dir, opts);
   const client = await connect(opts);
   try {
+    if (opts.metricBindings === void 0 && Object.keys(declaredMetrics(body["contract"])).length > 0) {
+      body["metric_bindings"] = await bindForPush(client, appId, body["contract"], opts);
+    }
     let result;
     try {
       result = await client.request(`/apps/${encodeURIComponent(appId)}/package`, {
@@ -21888,7 +23053,8 @@ async function pushFolder(dir, opts) {
     const outcome = {
       revision: result.revision,
       stage: result.stage,
-      code_version: typeof result.code_version === "number" ? result.code_version : null
+      code_version: typeof result.code_version === "number" ? result.code_version : null,
+      ...result.metric_bindings === void 0 ? {} : { metric_bindings: result.metric_bindings }
     };
     await recordRevision(dir, result.revision, result.stage, handlers, {
       id: appId,
@@ -21904,6 +23070,8 @@ async function pushFolder(dir, opts) {
 `
     );
     process.stdout.write(describePostCommit(result));
+    for (const line2 of bindingWarnings(result.metric_bindings)) process.stdout.write(`warning: ${line2}
+`);
     process.stdout.write(describeContract(result.contract));
     process.stdout.write(describeIgnoredName(result.name_ignored));
     process.stdout.write(describeSeeding(result));
@@ -21983,9 +23151,9 @@ async function writeReport(dir, report) {
 }
 async function ownedFiles(dir) {
   try {
-    const parsed = JSON.parse(await readFile8(reportPath(dir), "utf8"));
-    if (!Array.isArray(parsed.files)) return /* @__PURE__ */ new Set();
-    return new Set(parsed.files.map(String));
+    const parsed2 = JSON.parse(await readFile8(reportPath(dir), "utf8"));
+    if (!Array.isArray(parsed2.files)) return /* @__PURE__ */ new Set();
+    return new Set(parsed2.files.map(String));
   } catch {
     return /* @__PURE__ */ new Set();
   }
@@ -21995,8 +23163,8 @@ function digestOf(text3) {
 }
 async function recordedDigests(dir) {
   try {
-    const parsed = JSON.parse(await readFile8(reportPath(dir), "utf8"));
-    const held = parsed.digests;
+    const parsed2 = JSON.parse(await readFile8(reportPath(dir), "utf8"));
+    const held = parsed2.digests;
     if (typeof held !== "object" || held === null || Array.isArray(held)) return {};
     return Object.fromEntries(Object.entries(held).filter((entry) => typeof entry[1] === "string"));
   } catch {
@@ -22004,21 +23172,21 @@ async function recordedDigests(dir) {
   }
 }
 async function recordAsInput(dir, path3) {
-  let parsed;
+  let parsed2;
   try {
-    parsed = JSON.parse(await readFile8(reportPath(dir), "utf8"));
+    parsed2 = JSON.parse(await readFile8(reportPath(dir), "utf8"));
   } catch {
     return;
   }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return;
-  const list3 = (key) => Array.isArray(parsed[key]) ? parsed[key].map(String) : [];
-  parsed["files"] = list3("files").filter((one) => one !== path3);
-  parsed["inputs"] = [.../* @__PURE__ */ new Set([...list3("inputs"), path3])].sort();
-  const digests = parsed["digests"];
+  if (typeof parsed2 !== "object" || parsed2 === null || Array.isArray(parsed2)) return;
+  const list3 = (key) => Array.isArray(parsed2[key]) ? parsed2[key].map(String) : [];
+  parsed2["files"] = list3("files").filter((one) => one !== path3);
+  parsed2["inputs"] = [.../* @__PURE__ */ new Set([...list3("inputs"), path3])].sort();
+  const digests = parsed2["digests"];
   if (typeof digests === "object" && digests !== null && !Array.isArray(digests)) {
     delete digests[path3];
   }
-  await writeFile4(reportPath(dir), JSON.stringify(parsed, null, 2) + "\n");
+  await writeFile4(reportPath(dir), JSON.stringify(parsed2, null, 2) + "\n");
 }
 
 // src/commands/appspace/get.ts
@@ -22039,8 +23207,8 @@ function requireBundlePath(name) {
 async function unpushedInputs(dir, pkg) {
   let inputs = [];
   try {
-    const parsed = JSON.parse(await readFile9(reportPath(dir), "utf8"));
-    if (Array.isArray(parsed.inputs)) inputs = parsed.inputs.map(String);
+    const parsed2 = JSON.parse(await readFile9(reportPath(dir), "utf8"));
+    if (Array.isArray(parsed2.inputs)) inputs = parsed2.inputs.map(String);
   } catch {
     return [];
   }
@@ -22305,7 +23473,7 @@ import { cp, mkdir as mkdir5, mkdtemp as mkdtemp2, rm as rm3, writeFile as write
 import { tmpdir as tmpdir3 } from "os";
 import { dirname as dirname4, join as join11, resolve as resolve5, sep as sep2 } from "path";
 var WHAT = "package";
-async function checkPackage(dir, files, contract, opts, online) {
+async function checkPackage(dir, files, contract, opts, online, pendingMetricKeys = []) {
   if (!online) {
     return skip("no -s server to run the push's own checks against; the push is the first to run them");
   }
@@ -22317,13 +23485,13 @@ async function checkPackage(dir, files, contract, opts, online) {
     try {
       payload = await pushBody(scratch, { ...opts, contract: true });
     } catch (err) {
-      return skip(`the push body could not be built (${firstLine(err)})`);
+      return skip(`the push body could not be built (${firstLine2(err)})`);
     }
     let client;
     try {
       client = await connect(opts);
     } catch (err) {
-      return skip(`could not reach the server (${firstLine(err)})`);
+      return skip(`could not reach the server (${firstLine2(err)})`);
     }
     try {
       const path3 = `/apps/${encodeURIComponent(payload.appId)}/package/validate`;
@@ -22336,9 +23504,9 @@ async function checkPackage(dir, files, contract, opts, online) {
           body: JSON.stringify(payload.body)
         });
       } catch (err) {
-        return skip(`the server did not answer (${firstLine(err)})`);
+        return skip(`the server did not answer (${firstLine2(err)})`);
       }
-      return interpret(res.status, parse(res.body), path3, contract);
+      return setAsidePending(interpret(res.status, parse(res.body), path3, contract), pendingMetricKeys);
     } finally {
       client.cleanup();
     }
@@ -22346,11 +23514,28 @@ async function checkPackage(dir, files, contract, opts, online) {
     await rm3(scratch, { recursive: true, force: true });
   }
 }
+function setAsidePending(check5, pending) {
+  if (pending.length === 0) return check5;
+  const mentions3 = (message) => pending.some((key) => new RegExp(`metric_bindings\\.${key.replace(/[^a-z0-9_]/g, "")}(?![a-z0-9_])`).test(message));
+  const kept = check5.problems.filter((one) => !mentions3(one.message));
+  if (kept.length === check5.problems.length) return check5;
+  const keys2 = pending.map((key) => `"${key}"`).join(", ");
+  return {
+    problems: kept,
+    skipped: [
+      ...check5.skipped,
+      {
+        what: "metric bindings",
+        why: `${keys2} ${pending.length === 1 ? "is" : "are"} created on push and ${pending.length === 1 ? "has" : "have"} no id to bind yet` + (kept.length === 0 ? "; the platform's checks after its metric check (a data-model change, the revision) did not run" : "")
+      }
+    ]
+  };
+}
 function interpret(status, body, path3, contract) {
   if (typeof body === "string" && /^<(!doctype html|html)/i.test(body.trimStart())) {
     return skip(`the request was intercepted before reaching App Space (HTTP ${String(status)}, an HTML page)`);
   }
-  if (status === 200 && isObj3(body)) {
+  if (status === 200 && isObj4(body)) {
     const answer = body;
     if (answer.ok === true) return { problems: [], skipped: [] };
     if (answer.ok === false) {
@@ -22399,7 +23584,7 @@ function fromRefusal(status, detail, contract) {
       };
     });
   }
-  if (isObj3(detail) && detail["error"] === "stale_revision") {
+  if (isObj4(detail) && detail["error"] === "stale_revision") {
     return [
       {
         code: "server:stale-revision",
@@ -22409,7 +23594,7 @@ function fromRefusal(status, detail, contract) {
       }
     ];
   }
-  if (isObj3(detail) && Array.isArray(detail["seed"])) {
+  if (isObj4(detail) && Array.isArray(detail["seed"])) {
     return detail["seed"].map((line2) => ({
       code: "server:seed",
       pointer: "/",
@@ -22417,7 +23602,7 @@ function fromRefusal(status, detail, contract) {
       fix: "Fix the --seed file: every key a declared table, every row an object."
     }));
   }
-  if (isObj3(detail) && Array.isArray(detail["problems"])) {
+  if (isObj4(detail) && Array.isArray(detail["problems"])) {
     const hint = typeof detail["hint"] === "string" ? detail["hint"] : null;
     return detail["problems"].map((line2) => fromLine(String(line2), refused, tables, hint));
   }
@@ -22468,11 +23653,11 @@ async function stage(dir, scratch, files) {
 }
 function tablesOf2(contract) {
   const out = /* @__PURE__ */ new Map();
-  const app = isObj3(contract) && isObj3(contract["app"]) ? contract["app"] : {};
-  const model = isObj3(app["data_model"]) ? app["data_model"] : {};
-  const tables = isObj3(model["tables"]) ? model["tables"] : {};
+  const app = isObj4(contract) && isObj4(contract["app"]) ? contract["app"] : {};
+  const model = isObj4(app["data_model"]) ? app["data_model"] : {};
+  const tables = isObj4(model["tables"]) ? model["tables"] : {};
   for (const [name, table] of Object.entries(tables)) {
-    const columns = isObj3(table) && isObj3(table["columns"]) ? table["columns"] : {};
+    const columns = isObj4(table) && isObj4(table["columns"]) ? table["columns"] : {};
     out.set(name, new Set(Object.keys(columns)));
   }
   return out;
@@ -22490,15 +23675,15 @@ function parse(bytes) {
   }
 }
 function detailOf(body) {
-  return isObj3(body) ? body["detail"] : void 0;
+  return isObj4(body) ? body["detail"] : void 0;
 }
 function sentence(text3) {
   return text3.endsWith(".") ? text3 : `${text3}.`;
 }
-function firstLine(err) {
+function firstLine2(err) {
   return (err instanceof Error ? err.message : String(err)).split("\n")[0] ?? "";
 }
-function isObj3(value) {
+function isObj4(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
 
@@ -22540,8 +23725,8 @@ function stripPositional(contract, { keepTree = true, order: order2 } = {}) {
     else delete page.tree;
   }
   if (out.bindings !== void 0) out.bindings = renameDeep(out.bindings, rename2);
-  for (const problem5 of Array.isArray(out.problems) ? out.problems : []) {
-    if (typeof problem5.where === "string") problem5.where = fileOf(problem5.where);
+  for (const problem6 of Array.isArray(out.problems) ? out.problems : []) {
+    if (typeof problem6.where === "string") problem6.where = fileOf(problem6.where);
   }
   return out;
 }
@@ -22946,7 +24131,7 @@ function specSource(data, card) {
     if (!isPlainObject11(row)) return;
     cite(row.source);
     if (typeof row.data === "string") readsOf(row.data);
-    for (const next of [...listOf(row.depends), ...listOf(row.about)]) visit(next);
+    for (const next of [...listOf2(row.depends), ...listOf2(row.about)]) visit(next);
   };
   visit(card);
   return { refs, sentence: parts.join("; ") };
@@ -22955,7 +24140,7 @@ function lookupOf(step) {
   if (!isPlainObject11(step)) return [];
   return Object.values(step).flatMap((value) => isPlainObject11(value) && typeof value.lookup === "string" ? [value.lookup] : []);
 }
-function listOf(value) {
+function listOf2(value) {
   return Array.isArray(value) ? value : [];
 }
 function named6(value) {
@@ -23258,7 +24443,7 @@ function checkPage2(app, page, kit, runtime = null) {
   const missing = runtime === null ? [] : missingLibraries(page).map((one) => one.module);
   const library = runtime === null ? loadsModule(page.path, page.text, WIDGET_LIBRARY2) : !missing.includes("dr-app-runtime") && !missing.includes("dr-app-widgets");
   violations.push(...checkLibraryDraws(page, library, scripts, runtime === null ? null : missing));
-  if (runtime !== null) for (const problem5 of libraryOrderProblems(page)) violations.push({ rule: "R2.6", where: page.path, message: problem5 });
+  if (runtime !== null) for (const problem6 of libraryOrderProblems(page)) violations.push({ rule: "R2.6", where: page.path, message: problem6 });
   if (widgets.length > 0 && !library && !/drInsights\.setData\s*\(/.test(scriptText)) {
     violations.push({
       rule: "R3.4",
@@ -24050,10 +25235,10 @@ var PAGE_PATH4 = /\.html?$/i;
 var AppLoadError2 = class extends Error {
 };
 function loadApp2(dir) {
-  const manifest = readJson2(dir, "manifest.json", true);
-  const dataModel = existsSync2(join13(dir, DATA_MODEL_PATH2)) ? readJson2(dir, DATA_MODEL_PATH2, false) : null;
+  const manifest = readJson3(dir, "manifest.json", true);
+  const dataModel = existsSync2(join13(dir, DATA_MODEL_PATH2)) ? readJson3(dir, DATA_MODEL_PATH2, false) : null;
   const handlersSource = existsSync2(join13(dir, "handlers.json")) ? "handlers.json" : "manifest.json";
-  const handlersIndex = handlersSource === "handlers.json" ? readJson2(dir, "handlers.json", false) : manifest.handlers ?? {};
+  const handlersIndex = handlersSource === "handlers.json" ? readJson3(dir, "handlers.json", false) : manifest.handlers ?? {};
   if (handlersIndex === null || typeof handlersIndex !== "object" || Array.isArray(handlersIndex)) {
     throw new AppLoadError2(`${handlersSource} must be an object mapping handler names to {http, file}`);
   }
@@ -24082,7 +25267,7 @@ function readHandlerSource2(dir, file) {
   if (!existsSync2(full) || !statSync2(full).isFile()) return "";
   return readFileSync4(full, "utf8");
 }
-function readJson2(dir, path3, required) {
+function readJson3(dir, path3, required) {
   const full = join13(dir, path3);
   if (!existsSync2(full)) {
     if (required) throw new AppLoadError2(`${path3} is missing from the app version`);
@@ -25785,7 +26970,7 @@ function labelFor2(node, text3, tree) {
 }
 function textOf2(text3, node) {
   const next = text3.indexOf("<", node.end);
-  return decodeEntities2(text3.slice(node.end, next === -1 ? void 0 : next).replace(/\s+/g, " ").trim());
+  return decodeEntities3(text3.slice(node.end, next === -1 ? void 0 : next).replace(/\s+/g, " ").trim());
 }
 function slotsOf2(node, tree) {
   if (!(WIDGET_ATTR2 in node.attrs)) return {};
@@ -26252,7 +27437,7 @@ function specTransforms2(handlers, spec, problems) {
       out.push({ path: path3, text: text3 });
     }
   }
-  const unreadable = problems.some((problem5) => problem5.code === "transform_unreadable");
+  const unreadable = problems.some((problem6) => problem6.code === "transform_unreadable");
   for (const key of Object.keys(spec.table).filter(isWidgetKey2).sort(natural5)) {
     const path3 = isPlainObject12(spec.table[key]) ? spec.table[key].transform : void 0;
     if (typeof path3 !== "string" || unreadable || carried !== null && carried.has(path3)) continue;
@@ -26548,7 +27733,7 @@ function natural5(a, b) {
 }
 var NAMED_ENTITIES2 = { amp: "&", lt: "<", gt: ">", quot: '"', apos: "'" };
 var ENTITY2 = /&(#[0-9]{1,7}|#[xX][0-9a-fA-F]{1,6}|[a-zA-Z][a-zA-Z0-9]{1,31});/g;
-function decodeEntities2(value) {
+function decodeEntities3(value) {
   const text3 = String(value);
   if (!text3.includes("&")) return text3;
   return text3.replace(ENTITY2, (whole, body) => {
@@ -26561,7 +27746,7 @@ function decodeEntities2(value) {
 function decodedTree2(html) {
   const tree = parseTree2(html);
   for (const node of tree.nodes) {
-    for (const [name, value] of Object.entries(node.attrs)) node.attrs[name] = decodeEntities2(value);
+    for (const [name, value] of Object.entries(node.attrs)) node.attrs[name] = decodeEntities3(value);
   }
   return tree;
 }
@@ -26598,9 +27783,9 @@ var MAX_HINT3 = 120;
 function validate3(instance, schema, options = {}) {
   const problems = [];
   check3(instance, schema, "", schema, problems, { quote: options.quote === true, inBranch: false });
-  return problems.map((problem5) => `${problem5.at}: ${problem5.why}`);
+  return problems.map((problem6) => `${problem6.at}: ${problem6.why}`);
 }
-function problem4(at, why, kind = "other") {
+function problem5(at, why, kind = "other") {
   return { at: at || "/", why, kind };
 }
 function describe4(node, ctx) {
@@ -26635,7 +27820,7 @@ function check3(instance, node, at, root, problems, ctx) {
   if (typeof node.$ref === "string") {
     const target = resolve10(node.$ref, root);
     if (target === null) {
-      problems.push(problem4(at, "the schema names a reference it cannot resolve"));
+      problems.push(problem5(at, "the schema names a reference it cannot resolve"));
       return;
     }
     check3(instance, target, at, root, problems, ctx);
@@ -26643,29 +27828,29 @@ function check3(instance, node, at, root, problems, ctx) {
   if ("type" in node) {
     const names = Array.isArray(node.type) ? node.type : [node.type];
     if (!names.some((name) => isType3(instance, name))) {
-      problems.push(problem4(at, `not of type ${names.join(" or ")}${hint}`, "type"));
+      problems.push(problem5(at, `not of type ${names.join(" or ")}${hint}`, "type"));
       return;
     }
   }
-  if ("const" in node && !same3(instance, node.const)) problems.push(problem4(at, `not the constant this contract fixes${hint}`, "value"));
+  if ("const" in node && !same3(instance, node.const)) problems.push(problem5(at, `not the constant this contract fixes${hint}`, "value"));
   if (Array.isArray(node.enum) && !node.enum.some((one) => same3(instance, one))) {
-    problems.push(problem4(at, `not one of the values this contract allows${hint}`, "value"));
+    problems.push(problem5(at, `not one of the values this contract allows${hint}`, "value"));
   }
   if (typeof node.minimum === "number" && isType3(instance, "number") && instance < node.minimum) {
-    problems.push(problem4(at, `below the minimum this contract sets${hint}`));
+    problems.push(problem5(at, `below the minimum this contract sets${hint}`));
   }
   if (typeof node.pattern === "string" && typeof instance === "string" && !new RegExp(node.pattern, "u").test(instance)) {
     if (ctx.inBranch) {
-      problems.push(problem4(at, `${ctx.quote ? `${JSON.stringify(instance)} ` : ""}does not match ${node.pattern}${hint}`));
+      problems.push(problem5(at, `${ctx.quote ? `${JSON.stringify(instance)} ` : ""}does not match ${node.pattern}${hint}`));
     } else {
-      problems.push(problem4(at, "not in the form this contract requires"));
+      problems.push(problem5(at, "not in the form this contract requires"));
     }
   }
   if (typeof node.minLength === "number" && typeof instance === "string" && [...instance].length < node.minLength) {
-    problems.push(problem4(at, `shorter than this contract allows${hint}`));
+    problems.push(problem5(at, `shorter than this contract allows${hint}`));
   }
   if (typeof node.maxLength === "number" && typeof instance === "string" && [...instance].length > node.maxLength) {
-    problems.push(problem4(at, `longer than this contract allows${hint}`));
+    problems.push(problem5(at, `longer than this contract allows${hint}`));
   }
   if (isObject5(instance)) checkObject3(instance, node, at, root, problems, ctx);
   if (Array.isArray(instance)) checkArray3(instance, node, at, root, problems, ctx, hint);
@@ -26701,16 +27886,16 @@ function checkBranches3(instance, branches, at, root, problems, ctx, wanted, sta
       if (kept.length > MAX_PER_PLACE3) {
         const more = kept.length - MAX_PER_PLACE3;
         kept = kept.slice(0, MAX_PER_PLACE3);
-        kept.push(problem4(at, `and ${more} more problems here`, "more"));
+        kept.push(problem5(at, `and ${more} more problems here`, "more"));
       }
       for (const one of kept) problems.push(one);
     } else {
-      problems.push(problem4(at, `matches none of the shapes this contract has (one of: ${shapes3(branches, root)})`));
+      problems.push(problem5(at, `matches none of the shapes this contract has (one of: ${shapes3(branches, root)})`));
     }
   } else if (matched === 0) {
-    problems.push(problem4(at, "matches none of the shapes this contract has"));
+    problems.push(problem5(at, "matches none of the shapes this contract has"));
   } else if (wanted !== null && matched > wanted) {
-    problems.push(problem4(at, "matches more than one shape this contract has"));
+    problems.push(problem5(at, "matches more than one shape this contract has"));
   }
 }
 function shapeMisses3(found, at) {
@@ -26752,7 +27937,7 @@ function checkObject3(instance, node, at, root, problems, ctx) {
   for (const name of Array.isArray(node.required) ? node.required : []) {
     if (Object.prototype.hasOwnProperty.call(instance, name)) continue;
     const wanted = Object.prototype.hasOwnProperty.call(properties, name) ? properties[name] : null;
-    problems.push(problem4(`${at}/${escape3(name)}`, `required and absent${describe4(wanted, ctx)}`, "required"));
+    problems.push(problem5(`${at}/${escape3(name)}`, `required and absent${describe4(wanted, ctx)}`, "required"));
   }
   for (const [name, value] of Object.entries(instance)) {
     const where2 = `${at}/${escape3(name)}`;
@@ -26761,12 +27946,12 @@ function checkObject3(instance, node, at, root, problems, ctx) {
       continue;
     }
     const extra = node.additionalProperties ?? true;
-    if (extra === false) problems.push(problem4(where2, "not a key this contract carries"));
+    if (extra === false) problems.push(problem5(where2, "not a key this contract carries"));
     else if (isObject5(extra)) check3(value, extra, node["x-tenant-keys"] === true && !ctx.quote ? `${at}/*` : where2, root, problems, ctx);
   }
 }
 function checkArray3(instance, node, at, root, problems, ctx, hint) {
-  if (typeof node.minItems === "number" && instance.length < node.minItems) problems.push(problem4(at, `shorter than this contract allows${hint}`));
+  if (typeof node.minItems === "number" && instance.length < node.minItems) problems.push(problem5(at, `shorter than this contract allows${hint}`));
   if (isObject5(node.items)) instance.forEach((value, index) => check3(value, node.items, `${at}/${index}`, root, problems, ctx));
 }
 function isType3(instance, name) {
@@ -27253,8 +28438,8 @@ function unproducedPayloadKeys2(contract, { handlerSource = () => void 0, module
       if (produced.includes(key)) continue;
       const there = produced.length === 0 ? "the controls there produce no payload keys" : `the controls there produce ${produced.join(", ")}`;
       const fix = reads.generated ? `Add a control that sets it, or take "${key}" out of the handler's required in contract.json.` : `Add a control that sets it, or read it with payload.get("${key}", <default>).`;
-      const problem5 = `handler "${name}" reads payload "${key}", and nothing on ${either4(pages)} that calls it produces that key \u2014 ${there}.`;
-      out.push({ handler: name, key, pages, produced, generated: reads.generated, problem: problem5, fix, message: `${problem5} ${fix}` });
+      const problem6 = `handler "${name}" reads payload "${key}", and nothing on ${either4(pages)} that calls it produces that key \u2014 ${there}.`;
+      out.push({ handler: name, key, pages, produced, generated: reads.generated, problem: problem6, fix, message: `${problem6} ${fix}` });
     }
   }
   return out;
@@ -27288,9 +28473,9 @@ function undeclaredCustomCalls2(contract, { moduleSource = () => void 0 } = {})
 }
 function undeclaredCallMessage2(id, module, handler, calls, how) {
   const listed = calls.length === 0 ? "lists none" : `lists ${calls.join(", ")}`;
-  const problem5 = `custom "${id}" calls handler "${handler}" (ui.call ${how}, ui/${module}), and its declares.calls ${listed}.`;
+  const problem6 = `custom "${id}" calls handler "${handler}" (ui.call ${how}, ui/${module}), and its declares.calls ${listed}.`;
   const fix = `Add "${handler}" to declares.calls \u2014 and what it sends to declares.produces \u2014 or stop calling it.`;
-  return { problem: problem5, fix, message: `${problem5} ${fix}` };
+  return { problem: problem6, fix, message: `${problem6} ${fix}` };
 }
 function unreadUploadKeys2(contract, { handlerSource = () => void 0 } = {}) {
   const elements = isPlainObject13(contract?.elements) ? contract.elements : {};
@@ -27333,9 +28518,9 @@ function unreadUploadKeys2(contract, { handlerSource = () => void 0 } = {}) {
       }
       if (read) continue;
       const id = idOf3(element, uid);
-      const problem5 = `file_upload "${id}" writes the stored file under "${field}" to handler "${handler}" (${via}), and "${handler}" never reads payload["${field}"] \u2014 the file is stored and nothing uses it.`;
+      const problem6 = `file_upload "${id}" writes the stored file under "${field}" to handler "${handler}" (${via}), and "${handler}" never reads payload["${field}"] \u2014 the file is stored and nothing uses it.`;
       const fix = role === "custom" ? `Read payload["${field}"]["upload"] in "${handler}" and hand it to the parser (or write payload["${field}"] into a file column), or drop the upload.` : `Add "${field}" to "${handler}"'s fields (a file column), or drop the upload.`;
-      out.push({ uid, id, page: element.page ?? null, field, handler, via, problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ uid, id, page: element.page ?? null, field, handler, via, problem: problem6, fix, message: `${problem6} ${fix}` });
     }
   }
   return out;
@@ -27351,9 +28536,9 @@ function stepsWithoutAction2(contract) {
       const id = idOf3(element, uid);
       const name = named8(step.id) ? step.id : String(index);
       const next = named8(steps[index + 1]?.id) ? steps[index + 1].id : "the next step";
-      const problem5 = `stepper "${id}" step "${name}" names no action, so no handler moves the flow on from it \u2014 a flow that reaches it stays there.`;
+      const problem6 = `stepper "${id}" step "${name}" names no action, so no handler moves the flow on from it \u2014 a flow that reaches it stays there.`;
       const fix = `Give it the handler that moves it to "${next}" (action, action_label), or make it the last step.`;
-      out.push({ uid, id, page: element.page ?? null, step: name, index, problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ uid, id, page: element.page ?? null, step: name, index, problem: problem6, fix, message: `${problem6} ${fix}` });
     });
   }
   return out;
@@ -27854,9 +29039,9 @@ function unboundControls(contract, files = {}) {
       const param = page.params.find((one) => one?.name === name) ?? {};
       const kind = named9(param.kind) ? param.kind : null;
       const opens3 = param.default === void 0 ? "no value at all" : `its default (${JSON.stringify(param.default)})`;
-      const problem5 = `${page.path} declares param "${name}"${kind === null ? "" : ` (${kind})`}, and no control on the page writes it \u2014 no part in param mode, no custom that calls ui.setParam("${name}", \u2026) or declares it in declares.produces \u2014 so the page only ever shows ${opens3}.`;
+      const problem6 = `${page.path} declares param "${name}"${kind === null ? "" : ` (${kind})`}, and no control on the page writes it \u2014 no part in param mode, no custom that calls ui.setParam("${name}", \u2026) or declares it in declares.produces \u2014 so the page only ever shows ${opens3}.`;
       const fix = `Give it a control \u2014 a part in param mode (props.props.param "${name}": a slider, a number_input, a select, a date_picker or a toggle), or a custom whose module calls ui.setParam("${name}", value) \u2014 or drop the param.`;
-      out.push({ page: page.path, param: name, kind, problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ page: page.path, param: name, kind, problem: problem6, fix, message: `${problem6} ${fix}` });
     }
   }
   return out;
@@ -27910,9 +29095,9 @@ function unreadParams(contract, { moduleSource = () => void 0, handlerSource = (
         continue;
       }
       const there = named_.length === 0 ? "no component there reads a source" : `its sources are ${both2(named_.map((one) => `"${one}"`))}`;
-      const problem5 = `${page.path} declares param "${name}", and no source on the page honours it (${there}) \u2014 moving it changes nothing on the page.`;
+      const problem6 = `${page.path} declares param "${name}", and no source on the page honours it (${there}) \u2014 moving it changes nothing on the page.`;
       const fix = `Add "${name}" to the honors of the source it should move${named_.length === 1 ? ` ("${named_[0]}")` : ""}, or drop the param.`;
-      out.push({ page: page.path, param: name, sources: [...named_], problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ page: page.path, param: name, sources: [...named_], problem: problem6, fix, message: `${problem6} ${fix}` });
     }
   }
   return out;
@@ -29136,9 +30321,9 @@ function unreachablePages2(contract, files = {}) {
     else if (roles.length > 0) why = `it is for ${both3(quoted2(roles))}, and no page ${either5(quoted2(roles))} reaches links to it`;
     else if (gates.length > 0) why = `every nav entry to it is gated to ${either5(quoted2(gates))}, and no role shown that entry reaches a page carrying it`;
     else why = "the only pages that link to it are pages no role reaches";
-    const problem5 = `${page.path} is a page of the app, and no role reaches it from the nav \u2014 ${why} \u2014 so only a typed URL opens it.`;
+    const problem6 = `${page.path} is a page of the app, and no role reaches it from the nav \u2014 ${why} \u2014 so only a typed URL opens it.`;
     const fix = roles.length > 0 || gates.length > 0 ? `Gate its nav entry to a role that should open it (pages[].roles on the page, a role's home, or the element's role), or drop the page.` : "Give the pages a nav (a nav element on each page), or drop the page.";
-    out.push({ page: page.path, problem: problem5, fix, message: `${problem5} ${fix}` });
+    out.push({ page: page.path, problem: problem6, fix, message: `${problem6} ${fix}` });
   }
   return out;
 }
@@ -29284,9 +30469,9 @@ function unconfirmedStateChanges2(contract, files = {}) {
       named_.push(one.module ? `${one.what} (on ${one.page})` : `${one.what} "${one.id}" (on ${one.page})`);
     }
     const kind = handlers[handler]?.role === "decide" ? "decides a row" : "changes a record's state";
-    const problem5 = `handler "${handler}" ${kind}, and ${both3(named_)} ${named_.length === 1 ? "calls" : "call"} it on one click, with no confirm and no dialog in front of it.`;
+    const problem6 = `handler "${handler}" ${kind}, and ${both3(named_)} ${named_.length === 1 ? "calls" : "call"} it on one click, with no confirm and no dialog in front of it.`;
     const fix = 'Put the decision behind a confirm: a dialog part whose on_confirm is the handler (with the reason as one of its inputs), a row action with "confirm", a map-form decide whose decision takes a note, or \u2014 in a custom module \u2014 ui.confirm before ui.call.';
-    out.push({ handler, callers: bare.map(({ page, uid, what }) => ({ page, uid, what })), problem: problem5, fix, message: `${problem5} ${fix}` });
+    out.push({ handler, callers: bare.map(({ page, uid, what }) => ({ page, uid, what })), problem: problem6, fix, message: `${problem6} ${fix}` });
   }
   return out;
 }
@@ -29364,18 +30549,18 @@ function unreadReasons2(contract, { handlerSource = () => void 0, moduleSource,
     for (const [key, pages] of [...sent.entries()].sort()) {
       if (read.has(key)) continue;
       const where2 = pages.size === 0 ? "the page" : either5([...pages].sort());
-      const problem5 = `${where2} sends handler "${name}" a "${key}", and the handler never reads it \u2014 the reason a person types is thrown away.`;
+      const problem6 = `${where2} sends handler "${name}" a "${key}", and the handler never reads it \u2014 the reason a person types is thrown away.`;
       const fix = `Read it (payload.get("${key}")) and keep it with the decision \u2014 a column, or the audit note \u2014 or stop asking for it.`;
-      out.push({ handler: name, key, kind: "unread", pages: [...pages].sort(), problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ handler: name, key, kind: "unread", pages: [...pages].sort(), problem: problem6, fix, message: `${problem6} ${fix}` });
     }
     const lines = pyLines2(source);
     if (!changesState2(name, row, source) || !REJECTS2.test(lines.join("\n"))) continue;
     for (const key of REASON_KEYS2) {
       if (!reads.optional.includes(key) || reads.required.includes(key)) continue;
       if (requiresReason2(lines, key, reasonVars2(lines, key))) continue;
-      const problem5 = `handler "${name}" rejects (or overrides), and reads "${key}" without ever requiring it \u2014 a rejection goes through with no reason given.`;
+      const problem6 = `handler "${name}" rejects (or overrides), and reads "${key}" without ever requiring it \u2014 a rejection goes through with no reason given.`;
       const fix = `Refuse the reject path without one: if decision == "rejected" and not ${key}: return {"error": "Give a reason to reject."}.`;
-      out.push({ handler: name, key, kind: "optional", pages: [], problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ handler: name, key, kind: "optional", pages: [], problem: problem6, fix, message: `${problem6} ${fix}` });
     }
   }
   return out;
@@ -29412,9 +30597,9 @@ function unliftableRefusals2(contract, { handlerSource = () => void 0 } = {}) {
           }
           if (!refuses) continue;
           const shown2 = line2.trim().replace(/:$/, "");
-          const problem5 = `handler "${name}" refuses outright at line ${si + 1} (${shown2}) on the same path where it demands a "${key}" (line ${gi + 1}), and no reason lifts that refusal \u2014 the page asks for a reason to go ahead, and the reason is ignored.`;
+          const problem6 = `handler "${name}" refuses outright at line ${si + 1} (${shown2}) on the same path where it demands a "${key}" (line ${gi + 1}), and no reason lifts that refusal \u2014 the page asks for a reason to go ahead, and the reason is ignored.`;
           const fix = `Let the reason override it (check "${key}" before refusing, and record it), or tell the reader that this state cannot be overridden and stop asking for a reason.`;
-          out.push({ handler: name, key, line: si + 1, gateLine: gi + 1, problem: problem5, fix, message: `${problem5} ${fix}` });
+          out.push({ handler: name, key, line: si + 1, gateLine: gi + 1, problem: problem6, fix, message: `${problem6} ${fix}` });
         }
       }
     }
@@ -29430,9 +30615,9 @@ function rolesLandingNowhere2(contract) {
     const exists = pagesOf2(contract).some((page) => page.path === landing);
     if (exists && opens2(contract, model, role, landing)) continue;
     const stated2 = model.home.get(role);
-    const problem5 = !exists ? `role "${role}" lands on ${landing} (its home), which is not a page of the app.` : stated2 ? `role "${role}" lands on its home, ${landing}, which is for ${both3(quoted2(pageRoles2(pagesOf2(contract).find((page) => page.path === landing))))} \u2014 so the role opens the app on a 404.` : `role "${role}" states no home and lands on ${landing}, which is for ${both3(quoted2(pageRoles2(pagesOf2(contract).find((page) => page.path === landing))))} \u2014 so the role opens the app on a 404.`;
+    const problem6 = !exists ? `role "${role}" lands on ${landing} (its home), which is not a page of the app.` : stated2 ? `role "${role}" lands on its home, ${landing}, which is for ${both3(quoted2(pageRoles2(pagesOf2(contract).find((page) => page.path === landing))))} \u2014 so the role opens the app on a 404.` : `role "${role}" states no home and lands on ${landing}, which is for ${both3(quoted2(pageRoles2(pagesOf2(contract).find((page) => page.path === landing))))} \u2014 so the role opens the app on a 404.`;
     const fix = `Give "${role}" a home it may open (backend.roles[].home: one of its pages), or add it to that page's pages[].roles.`;
-    out.push({ role, page: landing, problem: problem5, fix, message: `${problem5} ${fix}` });
+    out.push({ role, page: landing, problem: problem6, fix, message: `${problem6} ${fix}` });
   }
   return out;
 }
@@ -29471,8 +30656,8 @@ function openToEveryRole2(contract) {
   const out = [];
   const say = (kind, names, what, fix) => {
     if (names.length === 0) return;
-    const problem5 = `${names.length === 1 ? `${what.one} ${names[0]} states` : `${names.length} ${what.many} \u2014 ${both3(names)} \u2014 state`} no roles, so every role (${all}) may ${what.verb} ${names.length === 1 ? "it" : "them"}.`;
-    out.push({ kind, names, problem: problem5, fix, message: `${problem5} ${fix}` });
+    const problem6 = `${names.length === 1 ? `${what.one} ${names[0]} states` : `${names.length} ${what.many} \u2014 ${both3(names)} \u2014 state`} no roles, so every role (${all}) may ${what.verb} ${names.length === 1 ? "it" : "them"}.`;
+    out.push({ kind, names, problem: problem6, fix, message: `${problem6} ${fix}` });
   };
   say(
     "page",
@@ -29859,7 +31044,7 @@ async function runCompile(dir, opts) {
     for (const fill of layoutFills(contract)) report.compose.push(fill);
   }
   const built = await compileFolder(dir, kind, contract, kit, loaded.overlay);
-  const refused = built.problems.filter((problem5) => REFUSALS.has(problem5.code));
+  const refused = built.problems.filter((problem6) => REFUSALS.has(problem6.code));
   if (Object.keys(built.files).length === 0 || refused.length > 0) {
     const lines = (refused.length > 0 ? refused : built.problems).map(asProblem);
     report.validate.problems = lines;
@@ -29869,6 +31054,30 @@ async function runCompile(dir, opts) {
     else process.stdout.write(problemHeading(lines.length) + formatProblems(lines) + formatSkipped(skipped));
     return 1;
   }
+  let metricsPlan = null;
+  if (Object.keys(declaredMetrics(contract)).length > 0) {
+    if (kind !== "app") {
+      skipped.push({ what: "metric bindings", why: "data.metrics binds an app's sources; a dashboard's are not bound yet (design 06 \xA77, step 8)" });
+    } else if (!hasServer(opts)) {
+      skipped.push({ what: "metric bindings", why: "no -s server: data.metrics is bound in each company when the app ships" });
+    } else {
+      const planned = await planMetricsFor(contract, opts);
+      metricsPlan = planned.plan;
+      report.metrics = planned.plan === null ? null : planReport(planned.plan);
+      if (planned.problems.length > 0) {
+        report.validate.problems = planned.problems;
+        report.failure = "validation";
+        await writeReport(dir, report);
+        if (opts.json === true) printJson(report);
+        else {
+          process.stdout.write(
+            (planned.plan === null ? "" : renderPlan(planned.plan)) + problemHeading(planned.problems.length) + formatProblems(planned.problems) + formatSkipped(skipped)
+          );
+        }
+        return 1;
+      }
+    }
+  }
   const paths = Object.keys(built.files).sort();
   const escaping = paths.filter((path3) => !insideFolder(dir, path3));
   if (escaping.length > 0) {
@@ -29915,12 +31124,12 @@ async function runCompile(dir, opts) {
       report.digests = Object.fromEntries(plan.owned.map((path3) => [path3, digestOf(built.files[path3] ?? "")]));
       report.inputs = plan.inputs;
     }
-    return await afterWrite(dir, target, kind, contract, built, report, kit, skipped, opts);
+    return await afterWrite(dir, target, kind, contract, built, report, kit, skipped, opts, metricsPlan);
   } finally {
     if (check5) await rm4(target, { recursive: true, force: true });
   }
 }
-async function afterWrite(dir, target, kind, contract, built, report, kit, skipped, opts) {
+async function afterWrite(dir, target, kind, contract, built, report, kit, skipped, opts, metricsPlan = null) {
   const composed = kind === "dashboard" && !isRuntimeDashboard(contract) ? composeOf(contract) : built.contract ?? contract;
   const extracted = await extractContract(target);
   const diffs = roundTripDiffs(composed, extracted, built.problems, { order: built.order });
@@ -29957,21 +31166,29 @@ async function afterWrite(dir, target, kind, contract, built, report, kit, skipp
     return 4;
   }
   if (target !== dir) {
-    const server = await checkPackage(dir, built.files, contract, opts, hasServer(opts));
+    const server = await checkPackage(
+      dir,
+      built.files,
+      contract,
+      metricsPlan === null ? opts : { ...opts, metricBindings: plannedBindings(metricsPlan) },
+      hasServer(opts),
+      metricsPlan === null ? [] : metricsPlan.entries.filter((entry) => entry.action === "create").map((entry) => entry.key)
+    );
     const notChecked3 = [...skipped, ...server.skipped];
     if ((opts.expect ?? []).length > 0) notChecked3.push({ what: "headline", why: "--check runs no load" });
     report.validate.problems = server.problems;
     report.validate.checks_skipped = notChecked3;
     if (server.problems.length > 0) report.failure = "push-would-be-refused";
     await writeReport(dir, report);
+    const planned = metricsPlan === null ? "" : renderPlan(metricsPlan);
     if (opts.json === true) printJson(report);
     else if (server.problems.length > 0) {
       process.stdout.write(
-        problemHeading(server.problems.length) + formatProblems(server.problems) + formatSkipped(notChecked3)
+        planned + problemHeading(server.problems.length) + formatProblems(server.problems) + formatSkipped(notChecked3)
       );
     } else {
       process.stdout.write(
-        problemHeading(0) + checkedLine(report, Object.keys(built.files).length) + warningLines(report) + formatSkipped(notChecked3)
+        planned + problemHeading(0) + checkedLine(report, Object.keys(built.files).length) + warningLines(report) + formatSkipped(notChecked3)
       );
     }
     return server.problems.length > 0 ? 1 : 0;
@@ -29980,9 +31197,31 @@ async function afterWrite(dir, target, kind, contract, built, report, kit, skipp
     await liveness(dir, kind, report, extracted, opts);
     return finish(dir, report, skipped, opts);
   }
+  let metricBindings;
+  if (metricsPlan !== null) {
+    const created = await applyMetricsFor(metricsPlan, opts);
+    report.metrics = planReport(metricsPlan, created.applied ?? void 0);
+    if (opts.json !== true) process.stdout.write(renderPlan(metricsPlan) + (created.applied === null ? "" : renderApplied(metricsPlan, created.applied)));
+    if (created.problems.length > 0) {
+      report.failure = "metrics-create";
+      report.push = { pushed: false, stage: null, revision: null, contract_source: null };
+      await writeReport(dir, report);
+      if (opts.json === true) printJson(report);
+      else {
+        const kept = (created.applied?.created ?? []).map((one) => `"${one.name}" (id ${String(one.id)})`);
+        const drifted = created.problems.some((one) => one.code === "metric_changed");
+        process.stderr.write(
+          (drifted ? "a Datarails metric this ship wrote does not hold what it wrote when read back, so nothing was pushed" : "a Datarails metric could not be created or changed, so nothing was pushed") + (kept.length === 0 ? ".\n" : `; kept, and reused by the next ship: ${kept.join(", ")}.
+`) + formatProblems(created.problems)
+        );
+      }
+      return 1;
+    }
+    metricBindings = created.applied?.bindings ?? {};
+  }
   let pushed = null;
   try {
-    pushed = await pushFolder(dir, { ...opts, force: opts.force });
+    pushed = await pushFolder(dir, { ...opts, force: opts.force, ...metricBindings === void 0 ? {} : { metricBindings } });
   } catch (err) {
     report.push = { pushed: false, stage: null, revision: null, contract_source: null };
     report.failure = isStaleRevision(err) ? "stale-revision" : isLostRace(err) ? "concurrent-publish" : "push-rejected";
@@ -30006,7 +31245,11 @@ async function afterWrite(dir, target, kind, contract, built, report, kit, skipp
     contract_source: "cli",
     ...typeof pushed?.code_version === "number" ? { code_version: pushed.code_version } : {}
   };
+  if (report.metrics !== void 0 && report.metrics !== null && pushed?.metric_bindings !== void 0) {
+    report.metrics["push"] = pushed.metric_bindings;
+  }
   await liveness(dir, kind, report, extracted, opts);
+  await metricsLiveness(report, extracted, opts);
   return finish(dir, report, skipped, opts);
 }
 async function finish(dir, report, skipped, opts) {
@@ -30207,25 +31450,25 @@ async function writePlan(dir, kind, contract, files, paths, force) {
 }
 function ownedPaths(contract) {
   const out = customHandlerPaths(contract);
-  const data = obj2(obj2(contract)["data"]);
-  for (const row of [...Object.values(obj2(data["sources"])), ...Object.values(obj2(data["widgets"]))]) {
+  const data = obj3(obj3(contract)["data"]);
+  for (const row of [...Object.values(obj3(data["sources"])), ...Object.values(obj3(data["widgets"]))]) {
     const transform = isPlain(row) ? row["transform"] : void 0;
     if (typeof transform === "string" && TRANSFORM_PATH2.test(transform)) out.add(transform);
   }
-  for (const element of Object.values(obj2(obj2(contract)["elements"]))) {
+  for (const element of Object.values(obj3(obj3(contract)["elements"]))) {
     if (isPlain(element) && element["type"] === "custom") {
-      const module = obj2(element["props"])["module"];
+      const module = obj3(element["props"])["module"];
       if (typeof module === "string" && MODULE_RE.test(module)) out.add(`ui/${module}`);
     }
   }
-  const pages = obj2(contract)["pages"];
+  const pages = obj3(contract)["pages"];
   for (const page of Array.isArray(pages) ? pages : []) {
     if (isPlain(page) && page["owned"] === true && typeof page["path"] === "string") out.add(page["path"]);
   }
   return out;
 }
 function customHandlerPaths(contract) {
-  const handlers = obj2(obj2(obj2(obj2(contract)["data"])["app"])["handlers"]);
+  const handlers = obj3(obj3(obj3(obj3(contract)["data"])["app"])["handlers"]);
   const out = /* @__PURE__ */ new Set();
   for (const [name, row] of Object.entries(handlers)) {
     if (isPlain(row) && row["role"] === "custom") out.add(`handlers/${name}.py`);
@@ -30268,7 +31511,7 @@ function roundTripDiffs(input, extracted, compilerProblems = [], { order: order2
   const read = order2 === void 0 ? {} : { order: "keys" };
   const left = stripPositional(normaliseApp(input), stated2);
   const right = stripPositional(normaliseApp(withoutUnstatedChrome(input, extracted)), read);
-  const declared = compilerProblems.some((problem5) => problem5.code === DECLARED_LOSS);
+  const declared = compilerProblems.some((problem6) => problem6.code === DECLARED_LOSS);
   const diffs = [];
   for (const section of ["app", "pages", "elements", "data"]) {
     if (!(section in left)) continue;
@@ -30343,7 +31586,7 @@ function normaliseApp(contract) {
     }
     const model = record2["data_model"];
     if (isPlain(model)) {
-      for (const table of Object.values(obj2(model["tables"]))) {
+      for (const table of Object.values(obj3(model["tables"]))) {
         if (!isPlain(table)) continue;
         const columns = table["columns"];
         if (!isPlain(columns)) continue;
@@ -30363,7 +31606,7 @@ function normaliseApp(contract) {
       }
     }
   }
-  const roles = obj2(out["backend"])["roles"];
+  const roles = obj3(out["backend"])["roles"];
   if (Array.isArray(roles)) {
     for (const role of roles) {
       if (isPlain(role) && Array.isArray(role["sees"]) && role["sees"].length === 0) delete role["sees"];
@@ -30371,7 +31614,7 @@ function normaliseApp(contract) {
   }
   return out;
 }
-function obj2(value) {
+function obj3(value) {
   return isPlain(value) ? value : {};
 }
 function withoutLibrary(section) {
@@ -30715,7 +31958,7 @@ async function recordPulled(dir, contractWritten) {
   } catch {
     return forget();
   }
-  if (Object.keys(built.files).length === 0 || built.problems.some((problem5) => REFUSALS.has(problem5.code))) {
+  if (Object.keys(built.files).length === 0 || built.problems.some((problem6) => REFUSALS.has(problem6.code))) {
     return forget();
   }
   const custom = ownedPaths(contract);
@@ -30821,21 +32064,21 @@ async function pushedState(dir) {
   const raw = await readIfPresent(join15(dir, ".appspace.json"));
   if (raw === void 0) return { stage: null, revision: null };
   try {
-    const parsed = JSON.parse(raw);
+    const parsed2 = JSON.parse(raw);
     return {
-      stage: typeof parsed.stage === "string" ? parsed.stage : null,
-      revision: typeof parsed.revision === "number" ? parsed.revision : null
+      stage: typeof parsed2.stage === "string" ? parsed2.stage : null,
+      revision: typeof parsed2.revision === "number" ? parsed2.revision : null
     };
   } catch {
     return { stage: null, revision: null };
   }
 }
-function asProblem(problem5) {
+function asProblem(problem6) {
   return {
-    code: problem5.code,
-    pointer: problem5.pointer ?? problem5.where ?? "/",
-    message: problem5.message.endsWith(".") ? problem5.message : `${problem5.message}.`,
-    fix: problem5.code in PART_REFUSALS ? `Make the part what its entry in ${CATALOG} says: its props, what it reads, what it may hold.` : problem5.code in PARAM_REFUSALS ? `Fix pages[].params or the source's honors: ${PARAM_REFUSALS[problem5.code] ?? ""}.` : problem5.code in APP_FIXES ? APP_FIXES[problem5.code] ?? "" : problem5.code in TRANSFORM_FIXES ? TRANSFORM_FIXES[problem5.code] ?? "" : "The compiler refuses to guess here: state the fact it names in contract.json."
+    code: problem6.code,
+    pointer: problem6.pointer ?? problem6.where ?? "/",
+    message: problem6.message.endsWith(".") ? problem6.message : `${problem6.message}.`,
+    fix: problem6.code in PART_REFUSALS ? `Make the part what its entry in ${CATALOG} says: its props, what it reads, what it may hold.` : problem6.code in PARAM_REFUSALS ? `Fix pages[].params or the source's honors: ${PARAM_REFUSALS[problem6.code] ?? ""}.` : problem6.code in APP_FIXES ? APP_FIXES[problem6.code] ?? "" : problem6.code in TRANSFORM_FIXES ? TRANSFORM_FIXES[problem6.code] ?? "" : "The compiler refuses to guess here: state the fact it names in contract.json."
   };
 }
 function livenessLine(report) {
@@ -30873,6 +32116,7 @@ function describe5(report, skipped) {
 `;
   out += warningLines(report);
   out += livenessLine(report);
+  out += metricsLines(report);
   if (report.push !== null && report.push.pushed) {
     out += `pushed \u2014 ${report.push.stage ?? "draft"}, revision ${String(report.push.revision ?? 0)}
 `;
@@ -30880,10 +32124,149 @@ function describe5(report, skipped) {
   out += formatSkipped(skipped);
   return out;
 }
+async function planMetricsFor(contract, opts) {
+  const unchecked2 = (why) => ({
+    plan: null,
+    problems: [
+      {
+        code: "metric_unchecked",
+        pointer: "/data/metrics",
+        message: `this company's Datarails metrics could not be checked, so data.metrics cannot be bound: ${why}.`,
+        fix: "Ship again shortly; nothing was created or pushed."
+      }
+    ]
+  });
+  let client;
+  try {
+    client = await connect(opts);
+  } catch (err) {
+    return unchecked2(`no session for ${opts.server ?? "this server"} (${err instanceof Error ? err.message.split("\n")[0] : String(err)})`);
+  }
+  try {
+    const plan = await planMetrics(contract, metricsTransport(client), {
+      appId: appIdOf(contract),
+      appName: isPlain(contract) ? appNameOf(contract) : ""
+    });
+    return { plan, problems: plan.problems };
+  } catch (err) {
+    if (err instanceof MetricsReadError) return unchecked2(err.message);
+    throw err;
+  } finally {
+    client.cleanup();
+  }
+}
+async function applyMetricsFor(plan, opts) {
+  let wait;
+  try {
+    wait = metricsWaitOf(opts.metricsWait);
+  } catch (err) {
+    return {
+      applied: null,
+      problems: [{ code: "metric_create", pointer: "/", message: `${err instanceof Error ? err.message : String(err)}.`, fix: "Pass --metrics-wait a number of seconds from 0 to 120." }]
+    };
+  }
+  if (wait.note !== null && opts.json !== true) process.stderr.write(`note: ${wait.note}
+`);
+  let client;
+  try {
+    client = await connect(opts);
+  } catch (err) {
+    return {
+      applied: null,
+      problems: [
+        {
+          code: "metric_create",
+          pointer: "/data/metrics",
+          message: `no session to create the metrics with (${err instanceof Error ? err.message.split("\n")[0] : String(err)}).`,
+          fix: "Log in again and ship again; nothing was created or pushed."
+        }
+      ]
+    };
+  }
+  try {
+    const applied = await applyPlan(plan, metricsTransport(client), { waitSeconds: wait.seconds });
+    return { applied, problems: applied.ok ? [] : applied.problems };
+  } finally {
+    client.cleanup();
+  }
+}
+function plannedBindings(plan) {
+  const out = {};
+  for (const entry of plan.entries) {
+    if (entry.metric_id === null || entry.origin === null) continue;
+    out[entry.key] = {
+      metric_id: entry.metric_id,
+      origin: entry.origin,
+      ...entry.reuse_key === null ? {} : { reuse_key: entry.reuse_key }
+    };
+  }
+  return out;
+}
+async function metricsLiveness(report, contract, opts) {
+  if (report.metrics === void 0 || report.metrics === null || report.app_id === null) return;
+  if (Object.keys(metricSources(contract)).length === 0) return;
+  let checks;
+  try {
+    const client = await connect(opts);
+    try {
+      checks = await checkMetricSources(metricsTransport(client), report.app_id, contract);
+    } finally {
+      client.cleanup();
+    }
+  } catch (err) {
+    checks = Object.entries(metricSources(contract)).map(([source, key]) => ({
+      source,
+      key,
+      state: "unchecked",
+      message: `could not be run (${err instanceof Error ? err.message.split("\n")[0] : String(err)})`
+    }));
+  }
+  report.metrics["live"] = checks;
+  const failed = checks.filter((one) => one.state === "failed");
+  if (failed.length === 0) return;
+  const problems = failed.map((one) => ({
+    code: "metric-live",
+    pointer: `/data/sources/${one.source}`,
+    message: `source "${one.source}" (metric @${one.key}) drew no figure once pushed: ${one.message}`,
+    fix: "Check the metric in Datarails and the binding ship printed; a card over a declared metric never falls back to another figure."
+  }));
+  report.liveness = {
+    problems: [...report.liveness?.problems ?? [], ...problems],
+    skipped: report.liveness?.skipped ?? [],
+    widgets: report.liveness?.widgets ?? null,
+    ...report.liveness?.others === void 0 ? {} : { others: report.liveness.others }
+  };
+  report.verify.problems = [...report.verify.problems, ...problems];
+  report.verify.violations = (report.verify.violations ?? 0) + problems.length;
+  if (report.failure === null) report.failure = "liveness";
+}
+function metricsLines(report) {
+  const block = report.metrics;
+  if (block === void 0 || block === null) return "";
+  let out = "";
+  for (const line2 of bindingWarnings(block["push"])) out += `warning: ${line2}
+`;
+  const live = Array.isArray(block["live"]) ? block["live"] : [];
+  for (const one of live) {
+    const said2 = one.state === "figure" ? "read its figure" : one.state === "preparing" ? `preparing \u2014 ${one.message} (neither blank nor a pass: run ship again once Datarails has it)` : one.state === "failed" ? `NO figure \u2014 ${one.message}` : `not checked \u2014 ${one.message}`;
+    out += `metric source "${one.source}" (@${one.key}): ${said2}
+`;
+  }
+  return out;
+}
+function metricHelpLines() {
+  return [
+    "Shipped (with -s, --check or --push), each data.metrics key is bound in that company: reused where a metric computes the same thing,",
+    'bound by name with "reuse": "name", changed in place where App Space made it for this app (and says no one else reads it), else created',
+    '(as you, with metrics:write; filed under "App Space", its description naming the app). --check prints the plan and creates nothing. Refused with:',
+    ...Object.entries(METRIC_SHIP_REFUSALS).map(([code, what]) => `  ${code.padEnd(22)}${what}`),
+    '  metric-live           once pushed, a source over a declared metric drew a sentence and no figure (exit 5); "preparing" is said and is neither blank nor a pass'
+  ];
+}
 function registerCompileCommand(parent) {
   withJsonOption(
     withServerOptions(
-      withAssemblyOptions(parent.command("compile [dir]").description("Compile contract.json into the package, and prove it round-trips.").option("--check", "Validate, compile and round-trip into a scratch folder, and verify \u2014 everything a push runs first. Write nothing.").option("--push", "Push the compiled package, contract attached.").option("--seed <file>", "Seed rows, as JSON. Forwarded to the push.").option("--catalog <file>", "Check source ids against this catalog instead of the tenant.").option("--force", "Write over files this compiler did not write (never a custom handler, custom module or owned page).").option("--update-block", "After a push that passed, print the appspace_app_update block a build reply ends with.").addHelpText(
+      withAssemblyOptions(parent.command("compile [dir]").description("Compile contract.json into the package, and prove it round-trips.").option("--check", "Validate, compile and round-trip into a scratch folder, and verify \u2014 everything a push runs first. Write nothing.").option("--push", "Push the compiled package, contract attached.").option("--seed <file>", "Seed rows, as JSON. Forwarded to the push.").option("--catalog <file>", "Check source ids against this catalog instead of the tenant.").option("--force", "Write over files this compiler did not write (never a custom handler, custom module or owned page).").option("--update-block", "After a push that passed, print the appspace_app_update block a build reply ends with.").option("--metrics-wait <seconds>", "With --push: how long to wait for a BASE metric this ship created to extract before pushing anyway (default 60, at most 120).").addHelpText(
         "after",
         [
           "",
@@ -30905,6 +32288,7 @@ function registerCompileCommand(parent) {
           'A declared Datarails metric (data.metrics, read by a source as from.financeos.metric "@<key>") is refused with:',
           ...Object.entries(METRIC_REFUSALS).map(([code, what]) => `  ${code.padEnd(22)}${what}`),
           "  (warnings, never refusals: metric_window, a window function Datarails gates by company; metric_unused, a declaration no source reads; expr_could_be_metric, an expr a calc metric could say)",
+          ...metricHelpLines(),
           "",
           "A transform (a dashboard dataset series row's transforms/<name>.py, or an app source's) is refused with:",
           ...Object.entries(TRANSFORM_REFUSALS).map(([code, what]) => `  ${code.padEnd(22)}${what}`)
@@ -30936,7 +32320,7 @@ function registerShipCommand(parent) {
         parent.command("ship [dir]").description("Assemble, compile, push and prove a dashboard pass; print the update block the reply ends with.").option("--seed <file>", "Seed rows, as JSON. Forwarded to the push.").option("--force", "Write over files this compiler did not write (never a custom handler). Refused with --onto-live.").option(
           "--onto-live",
           "Land this pass's cards on the app as it is live now, keeping every card already there: pull it, add them, push against its revision, and start over when another push lands first. Needs --app-id and --skeleton, and a folder of its own."
-        )
+        ).option("--metrics-wait <seconds>", "How long to wait for a BASE metric this ship created to extract before pushing anyway (default 60, at most 120).").addHelpText("after", ["", ...metricHelpLines()].join("\n"))
       )
     )
   ).action(async (dirArg, opts) => {
@@ -31115,7 +32499,7 @@ async function runEject(target, opts) {
   }
 }
 async function ejectHandler(dir, contract, name) {
-  const handlers = obj3(obj3(obj3(contract["data"])["app"])["handlers"]);
+  const handlers = obj4(obj4(obj4(contract["data"])["app"])["handlers"]);
   const row = handlers[name];
   if (!isPlain2(row)) {
     const known = Object.keys(handlers).sort();
@@ -31173,7 +32557,7 @@ function literalEnd2(text3, open2) {
   return -1;
 }
 async function ejectSource(dir, contract, name) {
-  const sources = obj3(obj3(contract["data"])["sources"]);
+  const sources = obj4(obj4(contract["data"])["sources"]);
   if (!isPlain2(sources[name])) {
     const known = Object.keys(sources).sort();
     throw new Refused(
@@ -31183,7 +32567,7 @@ async function ejectSource(dir, contract, name) {
   const path3 = `handlers/${name}.py`;
   if (!insideFolder(dir, path3)) throw new Refused(`${JSON.stringify(path3)} is not a path inside ${dir}.`);
   const dependents = Object.keys(sources).filter((other) => {
-    const from = obj3(sources[other])["from"];
+    const from = obj4(sources[other])["from"];
     return Array.isArray(from) && from.includes(name);
   }).sort();
   if (dependents.length > 0) {
@@ -31209,9 +32593,9 @@ async function ejectSource(dir, contract, name) {
     throw new Refused(`${path3} as compiled carries no SOURCES = {\u2026} table, so it is not a generated source handler.`);
   }
   await mayPlace(dir, path3, body, [compiled]);
-  const data = obj3(contract["data"]);
-  const app = obj3(data["app"]);
-  const handlers = obj3(app["handlers"]);
+  const data = obj4(contract["data"]);
+  const app = obj4(data["app"]);
+  const handlers = obj4(app["handlers"]);
   handlers[name] = { role: "custom" };
   app["handlers"] = handlers;
   data["app"] = app;
@@ -31239,8 +32623,8 @@ async function ejectPage(dir, contract, path3) {
     throw new Refused(`${path3} as compiled has no <head> to carry ${OWNED_META}.`);
   }
   await mayPlace(dir, path3, marked2, [compiled]);
-  const elements = obj3(contract["elements"]);
-  const gone = new Set(Object.keys(elements).filter((uid) => obj3(elements[uid])["page"] === path3));
+  const elements = obj4(contract["elements"]);
+  const gone = new Set(Object.keys(elements).filter((uid) => obj4(elements[uid])["page"] === path3));
   for (const uid of gone) delete elements[uid];
   for (const element of Object.values(elements)) {
     if (!isPlain2(element) || !Array.isArray(element["children"])) continue;
@@ -31251,11 +32635,11 @@ async function ejectPage(dir, contract, path3) {
   kept["owned"] = true;
   if (gate !== null && kept["roles"] === void 0) kept["role"] = gate;
   pages[index] = kept;
-  const app = obj3(obj3(contract["data"])["app"]);
+  const app = obj4(obj4(contract["data"])["app"]);
   if (Array.isArray(app["screens"])) {
     app["screens"] = app["screens"].filter((screen) => !(isPlain2(screen) && screen["page"] === path3));
   }
-  const sources = Object.keys(obj3(obj3(contract["data"])["sources"]));
+  const sources = Object.keys(obj4(obj4(contract["data"])["sources"]));
   const served = sources.filter((name) => files[`handlers/${name}.py`] !== void 0);
   const wrote = await commit(dir, contract, path3, marked2, (after) => {
     const lost = served.filter((name) => after[`handlers/${name}.py`] === void 0).sort();
@@ -31296,19 +32680,19 @@ ${OWNED_META}${html.slice(at2)}`;
 ${OWNED_META}${html.slice(at)}`;
 }
 async function ejectElement(dir, contract, uid) {
-  const elements = obj3(contract["elements"]);
+  const elements = obj4(contract["elements"]);
   const element = elements[uid];
   if (!isPlain2(element)) {
     throw new Refused(`the contract has no element ${JSON.stringify(uid)}; an element's uid is its key in contract.elements.`);
   }
   const type = String(element["type"] ?? "");
-  if (type === "custom") throw new Refused(`${uid} is already a custom element, drawn by ${String(obj3(element["props"])["module"] ?? "its module")}.`);
+  if (type === "custom") throw new Refused(`${uid} is already a custom element, drawn by ${String(obj4(element["props"])["module"] ?? "its module")}.`);
   if (!EJECTABLE.has(type)) {
     throw new Refused(
       `${uid} is a ${type || "typeless element"}, and element: ejects a chart or a stat \u2014 a root that draws one source's answer. To own a ${type || "screen"}'s markup, eject its page: page:${String(element["page"] ?? "<ui/path.html>")}.`
     );
   }
-  const props = obj3(element["props"]);
+  const props = obj4(element["props"]);
   const name = freeName(moduleName(props["id"], type, uid), ownedPaths(contract));
   const module = `components/${name}.js`;
   const path3 = `ui/${module}`;
@@ -31389,9 +32773,9 @@ ${lines}
   return built.files;
 }
 function refusedLines(built) {
-  const refused = built.problems.filter((problem5) => REFUSALS.has(problem5.code));
+  const refused = built.problems.filter((problem6) => REFUSALS.has(problem6.code));
   if (Object.keys(built.files).length > 0 && refused.length === 0) return null;
-  return (refused.length > 0 ? refused : built.problems).map((problem5) => `  [${problem5.code}] ${problem5.message}`).join("\n");
+  return (refused.length > 0 ? refused : built.problems).map((problem6) => `  [${problem6.code}] ${problem6.message}`).join("\n");
 }
 async function mayPlace(dir, path3, text3, same5) {
   const existing = await readIfPresent(join16(dir, path3));
@@ -31436,7 +32820,7 @@ ${lines}
 function isPlain2(value) {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }
-function obj3(value) {
+function obj4(value) {
   return isPlain2(value) ? value : {};
 }
 function registerEjectCommand(parent) {
@@ -31668,13 +33052,13 @@ function parseFileSpec(spec) {
   return { field, path: path3 };
 }
 function parseFileSpecs(specs) {
-  const parsed = specs.map(parseFileSpec);
+  const parsed2 = specs.map(parseFileSpec);
   const seen = /* @__PURE__ */ new Set();
-  for (const one of parsed) {
+  for (const one of parsed2) {
     if (seen.has(one.field)) throw new Error(`--file ${one.field} is given twice; give each field one file.`);
     seen.add(one.field);
   }
-  return parsed;
+  return parsed2;
 }
 var MIME_TYPES = {
   ".pdf": "application/pdf",
@@ -32865,15 +34249,15 @@ function answerOf(res) {
   if (res.body.length === 0 || res.body.length > ROWS_BODY_LIMIT) return {};
   const type = Object.entries(res.headers).find(([key]) => key.toLowerCase() === "content-type")?.[1];
   if (type !== void 0 && !/json/i.test(type)) return {};
-  let parsed;
+  let parsed2;
   try {
-    parsed = JSON.parse(res.body.toString("utf8"));
+    parsed2 = JSON.parse(res.body.toString("utf8"));
   } catch {
     return {};
   }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return {};
+  if (typeof parsed2 !== "object" || parsed2 === null || Array.isArray(parsed2)) return {};
   const out = { object: true };
-  const { rows: rows2, error, needs } = parsed;
+  const { rows: rows2, error, needs } = parsed2;
   if (needs && typeof needs === "object" && !Array.isArray(needs)) {
     const reason = needs.reason;
     if (reason === true || reason && typeof reason === "object" && !Array.isArray(reason)) {
@@ -32954,8 +34338,8 @@ function harvestNodes(document) {
     const filter = el.getAttribute(FILTER);
     if (filter !== null && filter !== "") props.filter = readFilter(filter);
     const args = el.getAttribute(ARGS);
-    const parsed = args !== null && args !== "" ? readArgs(args) : null;
-    if (parsed !== null) props.args = parsed;
+    const parsed2 = args !== null && args !== "" ? readArgs(args) : null;
+    if (parsed2 !== null) props.args = parsed2;
     const typed = el.getAttribute(PROPS);
     const typedProps = typed !== null && typed !== "" ? readProps(typed) : null;
     if (typedProps !== null) props.props = typedProps;
@@ -33251,8 +34635,8 @@ function createCanvas2dStub(canvas) {
   for (const name of CANVAS_2D_VOID_METHODS) target[name] = () => void 0;
   const spares = /* @__PURE__ */ new Map();
   return new Proxy(target, {
-    get(obj4, prop, receiver) {
-      if (typeof prop === "symbol" || prop in obj4) return Reflect.get(obj4, prop, receiver);
+    get(obj5, prop, receiver) {
+      if (typeof prop === "symbol" || prop in obj5) return Reflect.get(obj5, prop, receiver);
       if (prop === "then") return void 0;
       let spare = spares.get(prop);
       if (spare === void 0) {
@@ -33536,13 +34920,13 @@ async function runUiSmoke(opts) {
     const graceUntil = Date.now() + graceMs;
     while (Date.now() < deadline) {
       if (drivePrompt?.()) lastActivity = Date.now();
-      const parsed = dom.window.document.readyState === "complete";
+      const parsed2 = dom.window.document.readyState === "complete";
       const started = calls.length > since || inFlight > 0;
       if (!started && Date.now() < graceUntil) {
         await sleep(25);
         continue;
       }
-      if (parsed && inFlight === 0 && Date.now() - lastActivity >= quietMs) break;
+      if (parsed2 && inFlight === 0 && Date.now() - lastActivity >= quietMs) break;
       await sleep(25);
     }
   }
@@ -34817,9 +36201,9 @@ function unboundControls2(contract, files = {}) {
       const param = page.params.find((one) => one?.name === name) ?? {};
       const kind = named12(param.kind) ? param.kind : null;
       const opens3 = param.default === void 0 ? "no value at all" : `its default (${JSON.stringify(param.default)})`;
-      const problem5 = `${page.path} declares param "${name}"${kind === null ? "" : ` (${kind})`}, and no control on the page writes it \u2014 no part in param mode, no custom that calls ui.setParam("${name}", \u2026) or declares it in declares.produces \u2014 so the page only ever shows ${opens3}.`;
+      const problem6 = `${page.path} declares param "${name}"${kind === null ? "" : ` (${kind})`}, and no control on the page writes it \u2014 no part in param mode, no custom that calls ui.setParam("${name}", \u2026) or declares it in declares.produces \u2014 so the page only ever shows ${opens3}.`;
       const fix = `Give it a control \u2014 a part in param mode (props.props.param "${name}": a slider, a number_input, a select, a date_picker or a toggle), or a custom whose module calls ui.setParam("${name}", value) \u2014 or drop the param.`;
-      out.push({ page: page.path, param: name, kind, problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ page: page.path, param: name, kind, problem: problem6, fix, message: `${problem6} ${fix}` });
     }
   }
   return out;
@@ -34873,9 +36257,9 @@ function unreadParams2(contract, { moduleSource = () => void 0, handlerSource =
         continue;
       }
       const there = named_.length === 0 ? "no component there reads a source" : `its sources are ${both4(named_.map((one) => `"${one}"`))}`;
-      const problem5 = `${page.path} declares param "${name}", and no source on the page honours it (${there}) \u2014 moving it changes nothing on the page.`;
+      const problem6 = `${page.path} declares param "${name}", and no source on the page honours it (${there}) \u2014 moving it changes nothing on the page.`;
       const fix = `Add "${name}" to the honors of the source it should move${named_.length === 1 ? ` ("${named_[0]}")` : ""}, or drop the param.`;
-      out.push({ page: page.path, param: name, sources: [...named_], problem: problem5, fix, message: `${problem5} ${fix}` });
+      out.push({ page: page.path, param: name, sources: [...named_], problem: problem6, fix, message: `${problem6} ${fix}` });
     }
   }
   return out;
@@ -34917,9 +36301,9 @@ function pushedContract(bundle, pages) {
     const found = contractBlockText(html);
     if (found === null) continue;
     try {
-      const parsed = JSON.parse(found);
-      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
-        return parsed;
+      const parsed2 = JSON.parse(found);
+      if (typeof parsed2 === "object" && parsed2 !== null && !Array.isArray(parsed2)) {
+        return parsed2;
       }
     } catch {
     }
@@ -35852,11 +37236,11 @@ function customDeclaresFindings(contract, bundle, runs) {
   if (contract === null || !isAppContract3(contract)) return [];
   const out = [];
   const said2 = /* @__PURE__ */ new Set();
-  const undeclared = (uid, page, module, handler, problem5, fix) => {
+  const undeclared = (uid, page, module, handler, problem6, fix) => {
     const key = `${uid}|${handler}`;
     if (said2.has(key)) return;
     said2.add(key);
-    out.push({ code: "custom-undeclared-call", where: `${page ?? "ui/"} \u2192 ${module}`, message: problem5, fix, see: SEE.declares });
+    out.push({ code: "custom-undeclared-call", where: `${page ?? "ui/"} \u2192 ${module}`, message: problem6, fix, see: SEE.declares });
   };
   for (const found of DECLARES.undeclaredCustomCalls(contract, pushedFiles(bundle, {}))) {
     undeclared(found.uid, found.page, found.module, found.handler, found.problem, found.fix);
@@ -35869,8 +37253,8 @@ function customDeclaresFindings(contract, bundle, runs) {
       if (element?.type !== "custom" || declares === null || typeof module !== "string") continue;
       if (declares.calls.includes(entry.handler)) continue;
       const id = typeof element.props?.["id"] === "string" ? element.props["id"] : entry.uid;
-      const { problem: problem5, fix } = DECLARES.undeclaredCallMessage(id, module, entry.handler, declares.calls, "observed at load");
-      undeclared(entry.uid, element.page ?? null, module, entry.handler, problem5, fix);
+      const { problem: problem6, fix } = DECLARES.undeclaredCallMessage(id, module, entry.handler, declares.calls, "observed at load");
+      undeclared(entry.uid, element.page ?? null, module, entry.handler, problem6, fix);
     }
   }
   for (const run of runs) {
@@ -36200,13 +37584,13 @@ async function loadFixtures(dir, explicit) {
     if (explicit !== void 0) throw new Error(`no fixtures file at ${path3}.`);
     return { fixtures: { cases: [], ui: { entry: "index.html" } } };
   }
-  let parsed;
+  let parsed2;
   try {
-    parsed = JSON.parse(raw);
+    parsed2 = JSON.parse(raw);
   } catch {
     throw new FixtureError(`${path3} is not valid JSON.`);
   }
-  return { fixtures: parseFixtures(parsed, path3), source: path3 };
+  return { fixtures: parseFixtures(parsed2, path3), source: path3 };
 }
 async function runHandlerCases(cases, dir, appId, client, roleOf = () => void 0) {
   const code = /* @__PURE__ */ new Map();
@@ -36534,7 +37918,7 @@ ${attached}`;
     }
     out += `  FAIL ${head}
 ${attached}`;
-    for (const problem5 of outcome.problems) out += `         ${problem5}
+    for (const problem6 of outcome.problems) out += `         ${problem6}
 `;
   }
   return out;
@@ -36599,7 +37983,7 @@ function rederiveComponentBindings(contract) {
     model
   });
   contract.problems = [
-    ...contract.problems.filter((problem5) => !COMPONENT_PROBLEM_CODES.has(problem5.code)),
+    ...contract.problems.filter((problem6) => !COMPONENT_PROBLEM_CODES.has(problem6.code)),
     ...problems
   ].sort(byProblem4);
 }
@@ -36655,7 +38039,7 @@ function mergeDomComponents(contract, components, page) {
     contract.elements[uid] = element;
   }
   contract.problems = contract.problems.filter(
-    (problem5) => !(problem5.code === "duplicate_dom_id" && problem5.where.startsWith(`${page}@dom#`))
+    (problem6) => !(problem6.code === "duplicate_dom_id" && problem6.where.startsWith(`${page}@dom#`))
   );
   for (const { id, uid } of duplicates) {
     contract.problems.push({
@@ -36768,15 +38152,15 @@ function untouchedHandlers(declared, cases, interactions, runs = []) {
   return declared.filter((name) => !touched.has(name) && !calls.some((call) => callsHandler(call.url, name))).sort();
 }
 async function readSeed(dir) {
-  let parsed;
+  let parsed2;
   try {
-    parsed = JSON.parse(await readFile13(join18(dir, "seed.json"), "utf8"));
+    parsed2 = JSON.parse(await readFile13(join18(dir, "seed.json"), "utf8"));
   } catch {
     return null;
   }
-  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return null;
+  if (typeof parsed2 !== "object" || parsed2 === null || Array.isArray(parsed2)) return null;
   const seed = {};
-  for (const [table, rows2] of Object.entries(parsed)) {
+  for (const [table, rows2] of Object.entries(parsed2)) {
     if (!Array.isArray(rows2)) continue;
     seed[table] = rows2.filter(
       (row) => typeof row === "object" && row !== null && !Array.isArray(row)
@@ -37270,11 +38654,16 @@ function describeTryRole(one) {
 function rolesAllowed(handler, view) {
   return view.roles.filter((role) => view.allowed[role]?.[handler] === true);
 }
+function unboundNote(result) {
+  const meta = result?.meta;
+  if (meta?.source?.status !== "unbound") return null;
+  return 'this source reads a metric the contract declares (data.metrics), and a dry-run carries no metric bindings \u2014 they belong to a pushed version \u2014 so it always answers "isn\'t set up" here. `app-space ship` binds the metric and runs this source against the draft after its push.';
+}
 function registerTryCommand(parent) {
   withJsonOption(
     withServerOptions(
       parent.command("try <handler>").description(
-        "Run one handler against the app's real ctx, using the code on disk, without publishing."
+        `Run one handler against the app's real ctx, using the code on disk, without publishing. A source over a declared Datarails metric (data.metrics) answers "isn't set up" here: a dry-run carries no metric bindings; ship checks it after its push.`
       ).option("--dir <path>", "The app folder (default: current directory).", ".").option(
         "--payload <json>",
         "JSON payload for the handler, or @<path> to read it from a JSON file (relative to the working directory).",
@@ -37354,6 +38743,9 @@ function registerTryCommand(parent) {
       if (res.ok) {
         process.stdout.write(`ok
 ${JSON.stringify(res.result, null, 2)}
+`);
+        const note = unboundNote(res.result);
+        if (note !== null) process.stdout.write(`note: ${note}
 `);
         return;
       }