@vxil/cli 0.10.0 → 0.11.1

package/dist/vxil.js

@@ -6,13 +6,13 @@ var __export = (target, all) => {
 };
 
 // bin/vxil.ts
-import { writeFileSync as writeFileSync6, mkdirSync as mkdirSync5, existsSync as existsSync8, appendFileSync as appendFileSync2, readFileSync as readFileSync8, chmodSync as chmodSync2, openSync, closeSync, fstatSync, renameSync } from "node:fs";
+import { writeFileSync as writeFileSync6, mkdirSync as mkdirSync5, existsSync as existsSync8, appendFileSync as appendFileSync2, readFileSync as readFileSync8, chmodSync as chmodSync2, openSync, closeSync, fstatSync, renameSync, mkdtempSync, rmSync as rmSync2 } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { resolve as resolve7, dirname as dirname5, basename as basename4 } from "node:path";
-import { createInterface } from "node:readline";
+import { resolve as resolve7, dirname as dirname5, basename as basename4, join as join4 } from "node:path";
+import { createInterface as createInterface2 } from "node:readline";
 import { watch } from "node:fs";
 import { createServer } from "node:http";
-import { homedir as homedir3, hostname } from "node:os";
+import { homedir as homedir3, hostname, tmpdir } from "node:os";
 
 // src/lib.ts
 import { pathToFileURL, fileURLToPath } from "node:url";
@@ -3903,8 +3903,9 @@ var AiConfigSchema = Type.Object({
   // stamps on the latest version, and POSTs a new version ONLY when the content
   // differs — so a push is idempotent and versions stay monotonic per name.
   // Item shape mirrors ai-v1 core.ts TemplateBody exactly (`template` is the
-  // name). Stored templates the config does not declare are reported (there is
-  // no delete route — they are never removed). Bounded to 50 entries: the
+  // name). Stored templates the config does not declare are reported and left
+  // in place — RETIRED (soft: hidden from list + render, history kept) only
+  // under --allow-destructive (cvskit F67, 2026-10-01). Bounded to 50 entries: the
   // manifest rides the 1 MiB config body cap. An Optional ARRAY is ONE leaf.
   templates: Type.Optional(Type.Array(DeclaredAiTemplateSchema, { maxItems: AI_MAX_DECLARED_TEMPLATES }))
 });
@@ -4009,7 +4010,18 @@ var PaymentsConfigSchema = Type.Object({
     // sandbox event is persisted as outcome 'rejected_environment' (200, never
     // folded) unless the tenant opts in here. Stripe/Paddle/PayPal separate
     // environments by signing secret / API base, so only RC carries this knob.
-    acceptSandbox: Type.Boolean({ default: false })
+    acceptSandbox: Type.Boolean({ default: false }),
+    // (2026-10-01 §4.13 A18) Store-review purchases on a PRODUCTION tenant:
+    // the reviewer accounts' RevenueCat `app_user_id`s (≤ 20). A SANDBOX event
+    // whose subject (and, for a TRANSFER, every source user) is listed here
+    // folds — recorded `environment: 'sandbox'` on the delivery, the
+    // subscription and the charge, so it stays out of revenue — while every
+    // other sandbox event is still `rejected_environment`. The narrow,
+    // production-safe alternative to `acceptSandbox` (which folds EVERY
+    // TestFlight purchase and is refused by the CLI's production promotion
+    // gate). No default on purpose (Value.Default would materialize it into
+    // every RC manifest); absent = an empty list.
+    sandboxUsers: Type.Optional(Type.Array(Type.String({ minLength: 1, maxLength: 256 }), { maxItems: 20 }))
   })),
   paypal: Type.Optional(Type.Object({
     clientIdRef: Type.String(),
@@ -4077,7 +4089,15 @@ var PaymentsConfigSchema = Type.Object({
         creditType: Type.String({ minLength: 1 }),
         amount: Type.Integer({ minimum: 1 }),
         // #128
-        period: Type.String()
+        period: Type.String(),
+        // (2026-10-01 §4.13 W9) 'add' (the reader's default, today's
+        // behaviour) ADDS `amount` each period; 'reset' makes the period's
+        // grant REPLACE what is left: the unspent available balance of
+        // `creditType` is written off as one `expire` ledger row and `amount`
+        // granted, so the user starts every period with exactly `amount`
+        // (credits held by an in-flight job stay held). No schema default (it
+        // would materialize into every manifest carrying grants).
+        mode: Type.Optional(Type.Union([Type.Literal("add"), Type.Literal("reset")]))
       })))
     })),
     // provider price/plan id → tier. A real subscription webhook carries the
@@ -4209,7 +4229,11 @@ var FunctionsConfigSchema = Type.Object({
               // effective attempts = min(maxAttempts, jobs.retry.defaultMaxAttempts).
               retry: Type.Optional(Type.Object({
                 maxAttempts: Type.Integer({ minimum: 1, maximum: FN_RETRY_MAX_ATTEMPTS })
-              }))
+              })),
+              // W7 (2026-10-01): cron only — 'skip' = a due tick fires nothing
+              // while the previous tick's run is still open (queued / running /
+              // retrying / waiting / delayed). Absent = 'allow' (every tick runs).
+              overlap: Type.Optional(Type.Union([Type.Literal("allow"), Type.Literal("skip")]))
             }),
             { maxItems: 8 }
           )
@@ -4222,6 +4246,23 @@ var FunctionsConfigSchema = Type.Object({
         // names of tenant secrets injected at invoke time
         egressAllow: Type.Optional(Type.Array(Type.String())),
         // Outbound Worker allowlist hosts
+        // R1 (2026-10-01): the runtime settings this function's script was
+        // UPLOADED with — server-SET by the deploy pipeline (never authored),
+        // read back by the rollback re-upload so a restored script runs under
+        // the settings it was deployed and tested with, not today's. Absent =
+        // the legacy settings (@vxil/types FUNCTIONS_RUNTIME_LEGACY). Unbounded
+        // strings on purpose (the deploy writes them from the one constant).
+        // cpuMs (F2, 2026-10-01): the per-invoke CPU limit the script was
+        // uploaded with (limits.cpu_ms = min(declared limits.cpuMs, the tier's
+        // cpuMsPerInvoke, FN_MAX_CPU_MS)) — server-set; the nightly plan pass
+        // rewrites it after a tier change. Absent = the platform default.
+        runtime: Type.Optional(
+          Type.Object({
+            compatibilityDate: Type.String(),
+            compatibilityFlags: Type.Optional(Type.Array(Type.String())),
+            cpuMs: Type.Optional(Type.Number())
+          })
+        ),
         // Per-function resource declarations. BOTH members are OPTIONAL (the bag
         // used to REQUIRE all three, a latent 422 the moment anything sent it —
         // nothing ever did, because the CLI never carried it) and BOTH are
@@ -4389,21 +4430,26 @@ function lowerTriggerBindings(trigger) {
     const n = r && typeof r === "object" ? r.maxAttempts : void 0;
     return typeof n === "number" && Number.isInteger(n) ? { retry: { maxAttempts: n } } : {};
   };
-  if (t === "cron") return [{ kind: "cron", ...str2("schedule") ? { schedule: str2("schedule") } : {}, ...retryOf() }];
-  if (t === "queue") return [{ kind: "queue", ...str2("source") ? { source: str2("source") } : {}, ...retryOf() }];
-  if (t === "webhook") return [{ kind: "webhook", ...str2("source") ? { source: str2("source") } : {}, ...retryOf() }];
+  const overlapOf = () => {
+    const o = trigger?.overlap;
+    return o === void 0 || o === "allow" ? {} : { overlap: o };
+  };
+  if (t === "cron") return [{ kind: "cron", ...str2("schedule") ? { schedule: str2("schedule") } : {}, ...retryOf(), ...overlapOf() }];
+  if (t === "queue") return [{ kind: "queue", ...str2("source") ? { source: str2("source") } : {}, ...retryOf(), ...overlapOf() }];
+  if (t === "webhook") return [{ kind: "webhook", ...str2("source") ? { source: str2("source") } : {}, ...retryOf(), ...overlapOf() }];
   if (t === "cmsHook" || t === "cms-hook") {
     return [{
       kind: "cmsHook",
       ...str2("collection") ? { collection: str2("collection") } : {},
       ...str2("event") ? { event: str2("event") } : {},
-      ...retryOf()
+      ...retryOf(),
+      ...overlapOf()
     }];
   }
   if (t === "authHook" || t === "auth-hook") {
-    return [{ kind: "authHook", ...str2("event") ? { event: str2("event") } : {}, ...retryOf() }];
+    return [{ kind: "authHook", ...str2("event") ? { event: str2("event") } : {}, ...retryOf(), ...overlapOf() }];
   }
-  return [{ kind: "http", ...str2("path") ? { path: str2("path") } : {}, ...retryOf() }];
+  return [{ kind: "http", ...str2("path") ? { path: str2("path") } : {}, ...retryOf(), ...overlapOf() }];
 }
 function lowerAllTriggerBindings(def, name) {
   const declared = [def.trigger, ...def.triggers ?? []].filter((t) => Boolean(t));
@@ -4415,9 +4461,9 @@ function lowerAllTriggerBindings(def, name) {
   return bindings;
 }
 var CONFIG_FILENAMES = ["vxil.config.ts", "vxil.config.mjs", "vxil.config.js"];
-var VXIL_CONFIG_PKG_VERSION = "0.6.0";
-var VXIL_SDK_PKG_VERSION = "0.10.0";
-var VXIL_CLI_PKG_VERSION = "0.10.0";
+var VXIL_CONFIG_PKG_VERSION = "0.7.0";
+var VXIL_SDK_PKG_VERSION = "0.11.1";
+var VXIL_CLI_PKG_VERSION = "0.11.1";
 function ensureScaffoldPackageJson(cwd, opts = {}) {
   const file = resolve(cwd, "package.json");
   const wanted = {
@@ -7054,10 +7100,50 @@ function scopesForFunctionAudience(aud, scopes) {
 }
 var TENANT_SLUG_RE = /^[a-z0-9][a-z0-9-]{1,62}$/;
 var FUNCTION_SOURCE_MAX_BYTES = 512e3;
+var FN_PLATFORM_DEFAULT_CPU_MS = 3e4;
+function functionScriptCpuMs(declaredCpuMs, ceilingMs) {
+  const d = typeof declaredCpuMs === "number" && Number.isFinite(declaredCpuMs) && declaredCpuMs >= 1 ? Math.floor(declaredCpuMs) : null;
+  return d === null ? ceilingMs : Math.min(d, ceilingMs);
+}
+function recordedScriptCpuMs(raw) {
+  const c = raw?.cpuMs;
+  return isPositiveInt(c) ? c : FN_PLATFORM_DEFAULT_CPU_MS;
+}
+function planScriptCpuMs(runtime, declaredCpuMs, ceilingMs) {
+  const recorded = runtime?.cpuMs;
+  if (!isPositiveInt(recorded) && ceilingMs >= FN_PLATFORM_DEFAULT_CPU_MS) return FN_PLATFORM_DEFAULT_CPU_MS;
+  return functionScriptCpuMs(declaredCpuMs, ceilingMs);
+}
+function isPositiveInt(v) {
+  return typeof v === "number" && Number.isInteger(v) && v > 0;
+}
 var FUNCTIONS_RUNTIME = {
   compatibilityDate: "2025-09-01",
   compatibilityFlags: []
 };
+var FUNCTIONS_RUNTIME_LEGACY = {
+  compatibilityDate: "2025-09-01",
+  compatibilityFlags: []
+};
+function recordedFunctionsRuntime(raw) {
+  const r = raw;
+  if (r && typeof r === "object" && typeof r.compatibilityDate === "string" && /^\d{4}-\d{2}-\d{2}$/.test(r.compatibilityDate) && (r.compatibilityFlags === void 0 || Array.isArray(r.compatibilityFlags) && r.compatibilityFlags.every((f) => typeof f === "string"))) {
+    return {
+      compatibilityDate: r.compatibilityDate,
+      compatibilityFlags: [...r.compatibilityFlags ?? []],
+      ...isPositiveInt(r.cpuMs) ? { cpuMs: r.cpuMs } : {}
+    };
+  }
+  return { compatibilityDate: FUNCTIONS_RUNTIME_LEGACY.compatibilityDate, compatibilityFlags: [...FUNCTIONS_RUNTIME_LEGACY.compatibilityFlags] };
+}
+function sameFunctionsRuntime(a, b2) {
+  return a.compatibilityDate === b2.compatibilityDate && a.compatibilityFlags.length === b2.compatibilityFlags.length && a.compatibilityFlags.every((f, i) => f === b2.compatibilityFlags[i]);
+}
+function functionsRuntimeHashSuffix(settings) {
+  if (sameFunctionsRuntime(settings, FUNCTIONS_RUNTIME_LEGACY)) return "";
+  return `
+/* vxil-runtime ${settings.compatibilityDate} ${settings.compatibilityFlags.join(",")} */`;
+}
 
 // ../runtime/src/hash.ts
 async function sha256Hex(input) {
@@ -7465,7 +7551,7 @@ async function readOnlyPlan(api, block, allowDestructive) {
     s.created.push(...plan.create);
     s.updated.push(...plan.update);
     s.unchanged.push(...plan.unchanged);
-    s.undeclared.push(...plan.undeclared);
+    destructive([], plan.undeclared);
   }
   return out;
 }
@@ -7586,8 +7672,43 @@ import { existsSync as existsSync2, readFileSync as readFileSync2, realpathSync
 import { homedir } from "node:os";
 import { dirname as dirname2, resolve as resolve2, relative, isAbsolute, sep } from "node:path";
 import { createHash } from "node:crypto";
-function sourceSha12(source) {
-  return createHash("sha256").update(source, "utf8").digest("hex").slice(0, 12);
+function describeBinding(b2) {
+  const parts = [b2.kind];
+  if (b2.kind === "cron") parts.push(b2.schedule ? `'${b2.schedule}'` : "(no schedule)");
+  else if (b2.kind === "webhook" || b2.kind === "queue") parts.push(b2.source ? `source ${b2.source}` : "(every event)");
+  else if (b2.kind === "cmsHook") parts.push(`${b2.collection ?? "(every collection)"} on ${b2.event ?? "beforeWrite"}`);
+  else if (b2.kind === "authHook") parts.push(b2.event ?? "(every auth event)");
+  else if (b2.kind === "http" && b2.path) parts.push(b2.path);
+  if (b2.retry) parts.push(`retry:${b2.retry.maxAttempts}`);
+  if (b2.overlap) parts.push(`overlap:${b2.overlap}`);
+  return parts.join(" ");
+}
+function diffBindings(remote, local) {
+  const r = remote.map(describeBinding);
+  const l = local.map(describeBinding);
+  const removed = r.filter((x) => !l.includes(x));
+  const added = l.filter((x) => !r.includes(x));
+  return removed.length || added.length ? { removed, added } : null;
+}
+function hookReconcileOf(data2) {
+  if (!data2) return null;
+  const n = (v) => typeof v === "number" && Number.isFinite(v) ? v : 0;
+  const cms = data2.cms_hook_subscriptions;
+  const wh = data2.webhook_subscriptions;
+  const hr = data2.hook_reconcile;
+  if (!cms && !wh && !hr) return null;
+  const failed = Math.max(n(hr?.failed), n(cms?.failed) + n(wh?.failed));
+  if (failed === 0) return { failed };
+  const listed = Array.isArray(data2.warnings) ? data2.warnings.find((w) => typeof w === "string" && /trigger subscription/i.test(w)) : void 0;
+  const warning = typeof data2.hook_reconcile_warning === "string" ? data2.hook_reconcile_warning : listed;
+  return { failed, ...warning ? { warning } : {} };
+}
+function hookReconcileRemedy(fnName) {
+  return fnName ? `re-run the reconcile with \`vxil functions deploy ${fnName} --force\` or \`vxil push --server\` (a plain re-push sends no deploy for an unchanged function, so it would not retry it)` : "re-run the reconcile with `vxil push --server` (a plain re-push sends no deploy, so it would not retry it)";
+}
+function sourceSha12(source, runtime) {
+  const suffix = runtime ? functionsRuntimeHashSuffix(runtime) : "";
+  return createHash("sha256").update(source + suffix, "utf8").digest("hex").slice(0, 12);
 }
 function escapesRoot(root, path) {
   const rel = relative(root, path);
@@ -7751,7 +7872,11 @@ async function readRemote(api) {
   const res = await api("GET", "/v1/functions");
   const map2 = /* @__PURE__ */ new Map();
   const unavailable = readUnavailable("GET /v1/functions", res);
-  if (res.status !== 200) return { map: map2, unavailable };
+  const wire = res.status === 200 ? res.body.data?.runtime : void 0;
+  const deployRuntime = wire ? recordedFunctionsRuntime(wire) : FUNCTIONS_RUNTIME;
+  const ceilingWire = res.status === 200 ? res.body.data?.cpuMsCeiling : void 0;
+  const cpuMsCeiling = typeof ceilingWire === "number" && Number.isInteger(ceilingWire) && ceilingWire > 0 ? ceilingWire : null;
+  if (res.status !== 200) return { map: map2, unavailable, deployRuntime, cpuMsCeiling };
   const fns = Array.isArray(res.body.data?.functions) ? res.body.data.functions : [];
   for (const f of fns) {
     map2.set(f.name, {
@@ -7761,10 +7886,11 @@ async function readRemote(api) {
       egressAllow: f.egressAllow ?? [],
       bindings: f.bindings ?? [],
       signature: f.signature ?? null,
-      limits: f.limits ?? null
+      limits: f.limits ?? null,
+      runtime: recordedFunctionsRuntime(f.runtime)
     });
   }
-  return { map: map2, unavailable: null };
+  return { map: map2, unavailable: null, deployRuntime, cpuMsCeiling };
 }
 function sameSecretSet(a, b2) {
   return a.length === b2.length && a.every((x) => b2.includes(x));
@@ -7777,7 +7903,7 @@ function sameStringSet2(a, b2) {
 function clampFunctionScopes(scopes) {
   return (scopes ?? []).map(String).filter((s) => s && !DENY_FUNCTION_SCOPES.has(s));
 }
-async function planFunctions({ api, functions, cwd, apply, onNote }) {
+async function planFunctions({ api, functions, cwd, apply, onNote, remoteOnly = "ignore", force = false }) {
   const read = await readRemote(api);
   if (read.unavailable) {
     if (apply) {
@@ -7798,13 +7924,20 @@ async function planFunctions({ api, functions, cwd, apply, onNote }) {
     const secrets = normalizeSecretRefs(def.secrets);
     const limits = normalizeFnLimits(def.limits);
     const remoteFn = remote.get(name);
-    const sha = sourceSha12(source);
+    const sha = sourceSha12(source, read.deployRuntime);
     const retryN = bindings.find((b2) => b2.retry)?.retry?.maxAttempts;
     const label = `${name} (${Math.round(bytes / 100) / 10} KB) [${bindings.map((b2) => b2.kind).join("+")}${retryN !== void 0 ? " \xB7 retry:" + retryN : ""}${def.scopes?.length ? " \xB7 " + def.scopes.join(",") : ""}${secrets.length ? " \xB7 secrets:" + secrets.map((s) => s.slice("secret:".length)).join(",") : ""}${limits?.cpuMs !== void 0 ? " \xB7 cpu:" + limits.cpuMs + "ms" : ""}${limits?.timeoutMs !== void 0 ? " \xB7 egress:" + limits.timeoutMs + "ms" : ""}]`;
-    if (remoteFn !== void 0 && remoteFn.scriptRef.endsWith(`-${sha}`) && sameSecretSet(remoteFn.secrets, secrets) && sameStringSet2(clampFunctionScopes(def.scopes), remoteFn.scopes) && sameStringSet2(def.egressAllow ?? [], remoteFn.egressAllow) && stableStringify(remoteFn.bindings) === stableStringify(bindings) && stableStringify(remoteFn.signature) === stableStringify(def.signature ?? null) && stableStringify(remoteFn.limits ?? null) === stableStringify(limits ?? null)) {
-      return { change: { name, kind: "unchanged", detail: label }, applied: 0, cmsHooks: null, webhooks: null };
+    if (remoteFn !== void 0 && remoteFn.scriptRef.endsWith(`-${sha}`) && sameSecretSet(remoteFn.secrets, secrets) && sameFunctionsRuntime(remoteFn.runtime, read.deployRuntime) && (read.cpuMsCeiling === null || recordedScriptCpuMs(remoteFn.runtime) === planScriptCpuMs(remoteFn.runtime, limits?.cpuMs, read.cpuMsCeiling)) && sameStringSet2(clampFunctionScopes(def.scopes), remoteFn.scopes) && sameStringSet2(def.egressAllow ?? [], remoteFn.egressAllow) && stableStringify(remoteFn.bindings) === stableStringify(bindings) && stableStringify(remoteFn.signature) === stableStringify(def.signature ?? null) && stableStringify(remoteFn.limits ?? null) === stableStringify(limits ?? null) && !force) {
+      return { change: { name, kind: "unchanged", detail: label }, applied: 0, cmsHooks: null, webhooks: null, hook: null };
     }
-    const change = { name, kind: remoteFn === void 0 ? "deploy-new" : "deploy-update", detail: label };
+    const bindingChanges = remoteFn !== void 0 ? diffBindings(remoteFn.bindings, bindings) : null;
+    const change = {
+      name,
+      kind: remoteFn === void 0 ? "deploy-new" : "deploy-update",
+      detail: label,
+      bindings: bindings.map(describeBinding),
+      ...bindingChanges ? { bindingChanges } : {}
+    };
     if (apply) {
       const body = { source, trigger: triggerKind, secrets };
       if (bindings.length) body.bindings = bindings;
@@ -7821,12 +7954,35 @@ async function planFunctions({ api, functions, cwd, apply, onNote }) {
       const cmsHooks = data2?.cms_hook_subscriptions ?? null;
       const webhooks = data2?.webhook_subscriptions ?? null;
       const warnings2 = (data2?.warnings ?? []).map((message) => ({ fn: name, message: String(message) }));
-      return { change, applied: 1, cmsHooks, webhooks, warnings: warnings2 };
+      return { change, applied: 1, cmsHooks, webhooks, warnings: warnings2, hook: hookReconcileOf(data2) };
     }
-    return { change, applied: 0, cmsHooks: null, webhooks: null, warnings: [] };
+    return { change, applied: 0, cmsHooks: null, webhooks: null, warnings: [], hook: null };
   });
-  const changes = results.map((r) => r.change);
+  const remoteOnlyNames = remoteOnly === "ignore" ? [] : [...remote.keys()].filter((n) => !(n in functions)).sort();
+  const remoteOnlyKept = [];
+  let lastDeleteHook = null;
+  const remoteOnlyChanges = [];
+  for (const name of remoteOnlyNames) {
+    const r = remote.get(name);
+    const bl = r.bindings.map(describeBinding);
+    const what = `${name} [deployed, not in vxil.config${bl.length ? ` \xB7 ${bl.join(" + ")}` : ""}${r.scopes.length ? ` \xB7 ${r.scopes.join(",")}` : ""}]`;
+    if (remoteOnly !== "delete") {
+      remoteOnlyKept.push(name);
+      remoteOnlyChanges.push({ name, kind: "remote-only", detail: `${what} \u2014 kept (it still runs with its old code, bindings and scopes); \`vxil push --allow-destructive\` deletes it` });
+      continue;
+    }
+    if (!apply) {
+      remoteOnlyChanges.push({ name, kind: "delete", detail: `${what} \u2014 will be DELETED by this push (--allow-destructive)` });
+      continue;
+    }
+    const del = await deleteRemoteFunction(api, name);
+    if (del.hook) lastDeleteHook = del.hook;
+    remoteOnlyChanges.push({ name, kind: "delete", detail: `${what} \u2014 ${del.gone ? "already gone" : "deleted (its triggers are unwired; the script is reaped by the nightly GC)"}` });
+  }
+  const changes = [...results.map((r) => r.change), ...remoteOnlyChanges];
   const applied = results.reduce((s, r) => s + r.applied, 0);
+  const deployHooks = results.map((r) => r.hook).filter((h) => h !== null);
+  const hookReconcile = lastDeleteHook ?? deployHooks[deployHooks.length - 1] ?? null;
   const sum = (pick) => results.reduce((acc, r) => {
     const v = pick(r);
     if (!v) return acc;
@@ -7835,12 +7991,51 @@ async function planFunctions({ api, functions, cwd, apply, onNote }) {
   const cmsHookSubscriptions = sum((r) => r.cmsHooks);
   const webhookSubscriptions = sum((r) => r.webhooks);
   const warnings = results.flatMap((r) => r.warnings ?? []);
-  return { changes, applied, cmsHookSubscriptions, webhookSubscriptions, ...warnings.length ? { warnings } : {} };
+  return {
+    changes,
+    applied,
+    cmsHookSubscriptions,
+    webhookSubscriptions,
+    ...warnings.length ? { warnings } : {},
+    hookReconcile,
+    ...remoteOnlyKept.length ? { remoteOnlyKept } : {}
+  };
+}
+async function deleteRemoteFunction(api, name, version) {
+  const res = await api(
+    "DELETE",
+    `/v1/functions/${encodeURIComponent(name)}`,
+    void 0,
+    version !== void 0 ? { "if-match": String(version) } : {}
+  );
+  if (res.status === 404) return { gone: true, hook: null };
+  if (res.status !== 200) {
+    const e = res.body.error ?? {};
+    throw new Error(`functions: delete ${name} failed: ${e.code ?? res.status} ${e.message ?? ""} ${e.hint ?? ""}`.trim());
+  }
+  const data2 = res.body.data;
+  return { gone: data2?.deleted === false, hook: hookReconcileOf(data2) };
 }
 function formatFnChanges(changes) {
   const actionable = changes.filter((c) => c.kind !== "unchanged");
   if (!actionable.length) return "  (no function changes)";
-  return actionable.map((c) => `  ${c.kind === "deploy-new" ? "+" : "~"} ${c.detail}`).join("\n");
+  const mark = (k) => k === "deploy-new" ? "+" : k === "deploy-update" ? "~" : "-";
+  const out = [];
+  for (const c of actionable) {
+    out.push(`  ${mark(c.kind)} ${c.detail}`);
+    if (c.bindingChanges) {
+      for (const b2 of c.bindingChanges.removed) out.push(`      - binding ${b2}`);
+      for (const b2 of c.bindingChanges.added) out.push(`      + binding ${b2}`);
+      if ([...c.bindingChanges.removed, ...c.bindingChanges.added].some((b2) => /^(webhook|cmsHook|authHook)\b/.test(b2))) {
+        out.push("      (its trigger subscription is updated on deploy and keeps the events it has not delivered yet)");
+      }
+    } else if (c.bindings?.length && c.kind === "deploy-new") {
+      for (const b2 of c.bindings) out.push(`      binding ${b2}`);
+    } else if (c.bindings?.length) {
+      out.push(`      bindings unchanged: ${c.bindings.join(" \xB7 ")}`);
+    }
+  }
+  return out.join("\n");
 }
 async function probeFunctionsEntitlement(api, name) {
   const res = await api("POST", `/v1/functions/${encodeURIComponent(name)}`, {});
@@ -7873,7 +8068,7 @@ function formatFunctionsPreflight(e, opts) {
   }
   const plan = /'([a-z]+)' plan/.exec(e.message ?? "")?.[1];
   const planLabel = plan ? `the ${plan[0].toUpperCase()}${plan.slice(1)} plan` : "a paid plan";
-  return `functions need ${planLabel}${e.message ? ` (${e.message})` : ""} \u2014 ${n} would be refused with 402 tier_required. Upgrade in the dashboard (${billingPageFor(opts.tenantId, opts.baseUrl)}) or with \`vxil billing upgrade --tier ${plan ?? "<tier>"}\` (it needs your dashboard session \u2014 \`vxil login\` \u2014 not the project key)` + (opts.verb === "push" ? ", or run `vxil push --skip-functions` to push the cms schema and feature config without them" : "") + ".";
+  return `functions need ${planLabel}${e.message ? ` (${e.message})` : ""} \u2014 ${n} would be refused with 402 tier_required. Upgrade in the dashboard (${billingPageFor(opts.tenantId, opts.baseUrl)}) or with \`vxil billing upgrade --tier ${plan ?? "<tier>"}\` (it needs your dashboard session \u2014 \`vxil login\` \u2014 not the project key); or, if this project is not production, mark it staging or development (\`vxil projects workload <slug> staging\`) \u2014 Free deploys functions there, within the Free limits` + (opts.verb === "push" ? "; or run `vxil push --skip-functions` to push the cms schema and feature config without them" : "") + ".";
 }
 function formatLogLines(lines) {
   const out = [];
@@ -8499,6 +8694,7 @@ var API_CHEATSHEET = [
   { feature: "jobs", what: "enqueue a job", cmd: `vxil api POST /v1/jobs/enqueue '{"job_name":"resize","target_url":"https://\u2026","payload":{}}'` },
   { feature: "jobs", what: "wake runs waiting on an event", cmd: `vxil api POST /v1/jobs/events '{"event":"order.paid","payload":{}}'` },
   { feature: "jobs", what: "replay / cancel a run", cmd: "vxil api POST /v1/jobs/runs/<run_id>/replay   \xB7 vxil api POST /v1/jobs/runs/<run_id>/cancel" },
+  { feature: "jobs", what: "list schedules: held (fired, not started 2+ intervals), skipped_fires, overlap \u2014 fn-cron:* rows are function crons", cmd: "vxil api GET /v1/jobs/schedules" },
   { feature: "jobs", what: "create / pause / resume / delete a schedule", cmd: `vxil api POST /v1/jobs/schedules '{"job_name":"digest","target_url":"https://\u2026","cron":"0 8 * * *"}'   \xB7 POST /v1/jobs/schedules/<schedule_id>/pause \xB7 POST \u2026/resume \xB7 vxil api DELETE /v1/jobs/schedules/<schedule_id>` },
   { feature: "jobs", what: "flow rules (rate + parallelism per endpoint or job)", cmd: `vxil api POST /v1/jobs/flow-rules '{"match_kind":"job_name","match_value":"resize","max_parallel":2}'   \xB7 vxil api DELETE /v1/jobs/flow-rules/<rule_id>` },
   // files
@@ -9002,7 +9198,7 @@ function promotionRefusals(cfg, allowed) {
     out.push({
       kind: "sandbox",
       flag: PROMOTION_OVERRIDE_FLAGS.sandbox,
-      message: `sandbox provider flags [${sandboxes.join(", ")}] would ship to a live money path (a sandbox key signs with the wrong secret; RevenueCat folds test purchases as outcome rejected_environment). Set them false, or override with --${PROMOTION_OVERRIDE_FLAGS.sandbox}.`
+      message: `sandbox provider flags [${sandboxes.join(", ")}] would ship to a live money path (a sandbox key signs with the wrong secret; revenuecat.acceptSandbox folds EVERY TestFlight / test-track purchase into live entitlements \u2014 for store review, list the reviewer app_user_ids in revenuecat.sandboxUsers instead, which a production push allows). Set them false, or override with --${PROMOTION_OVERRIDE_FLAGS.sandbox}.`
     });
   }
   const devOrigins = devRedirectOrigins(redirectOrigins(cfg));
@@ -9088,7 +9284,12 @@ async function linkViaDeviceFlow(dash, slug, io) {
   throw new Error("link timed out waiting for browser approval \u2014 run `vxil link <slug>` again");
 }
 function reconcileLinkTenant(flagTenant, verified) {
-  if (verified === "(unknown)") return { tenantId: flagTenant ?? "(unknown)" };
+  if (verified === "(unknown)") {
+    if (flagTenant === void 0) return { tenantId: "(unknown)" };
+    return {
+      error: `cannot verify --tenant ${flagTenant} against the key \u2014 the server named no tenant for it (GET /v1/features meta.tenant_id absent); nothing was linked. Drop --tenant to record the binding unverified (\`vxil doctor\` then warns that the key tenant is not verified).`
+    };
+  }
   if (flagTenant !== void 0 && flagTenant !== verified) {
     return {
       error: `--tenant ${flagTenant} does not match the key's own tenant ${verified} (GET /v1/features meta.tenant_id) \u2014 nothing was linked. Check which key you passed, or drop --tenant to record the key's tenant.`
@@ -9271,7 +9472,362 @@ async function acceptInviteViaSession(dash, cookie, token) {
   return { tenant_id: d.tenant_id, role: d.role ?? "" };
 }
 
+// src/credentialExport.ts
+async function exportCredentialsViaSession(dash, cookie, tenantId, onPage) {
+  let after = null;
+  let n = 0;
+  let total = null;
+  for (let pages = 0; pages < 1e4; pages++) {
+    const q = after !== null ? `?after=${encodeURIComponent(after)}` : "";
+    const r = await dash("GET", `/dashboard/tenants/${encodeURIComponent(tenantId)}/credentials/export${q}`, void 0, cookie);
+    if (r.status === 401) return { unauthorized: true };
+    if (r.status !== 200) throw new Error(`the credential export was refused (${errText(r)})`);
+    const p = data(r);
+    if (pages === 0 && typeof p.total === "number") total = p.total;
+    const users = p.users ?? [];
+    await onPage(users);
+    n += users.length;
+    after = p.next_after ?? null;
+    if (after === null) return { users: n, total };
+  }
+  throw new Error("the credential export did not finish within 10,000 pages");
+}
+function credentialsHeader(slug, tenantId, now = /* @__PURE__ */ new Date()) {
+  return JSON.stringify({
+    vxil_credentials: 1,
+    project: slug,
+    source_tenant: tenantId,
+    exported_at: now.toISOString(),
+    format: {
+      scrypt: "scrypt$<N>$<r>$<p>$<salt base64>$<32-byte key base64> (N=16384, r=8, p=1)",
+      bcrypt: "an imported bcrypt string its user has not signed in with on vxil yet"
+    },
+    import: "POST /v1/auth/users/import accepts both formats as-is. User ids are unique across projects in an environment, so while the source project still holds these users every row answers id_taken: delete the source project first, then import into the new one."
+  });
+}
+function credentialLine(c) {
+  return JSON.stringify({ t: "credential", r: c });
+}
+var CREDENTIAL_EXPORT_NOTE = [
+  "This exports the stored password hash of every user of this project who has a password.",
+  "A hash lets anyone who holds the file test password guesses offline, at their own pace \u2014 and many",
+  "people reuse passwords. Keep the file encrypted, on as few machines as possible, and delete it once",
+  "it is imported. The export is recorded in the project's audit log (auth.credentials.exported) and",
+  "can run once an hour. Only a project owner can run it."
+].join("\n");
+
+// src/exportPostgres.ts
+import { createReadStream } from "node:fs";
+import { createInterface } from "node:readline";
+var PG_TYPE = {
+  string: "text",
+  text: "text",
+  int: "bigint",
+  float: "double precision",
+  bool: "boolean",
+  datetime: "timestamptz",
+  json: "jsonb",
+  relation: "text",
+  // the related item's _id (see the column comment)
+  file: "text"
+  // the object_id in <schema>.files
+};
+var DATA_TYPE = {
+  text: "text",
+  bigint: "bigint",
+  "double precision": "double precision",
+  boolean: "boolean",
+  timestamptz: "timestamp with time zone",
+  jsonb: "jsonb"
+};
+var IDENT_RE = /^[a-z_][a-z0-9_]{0,62}$/;
+function quoteIdent(name) {
+  if (!IDENT_RE.test(name)) throw new Error(`not a safe SQL identifier: '${name}'`);
+  return `"${name}"`;
+}
+var META_COLS = [
+  { name: "_id", type: "text" },
+  { name: "_status", type: "text" },
+  { name: "_created_at", type: "timestamptz" },
+  { name: "_updated_at", type: "timestamptz" },
+  { name: "_published_at", type: "timestamptz" },
+  { name: "_data", type: "jsonb" }
+];
+function collectionTables(fields) {
+  const by = /* @__PURE__ */ new Map();
+  for (const f of fields) {
+    if (!IDENT_RE.test(f.collection) || !IDENT_RE.test(f.field)) continue;
+    by.set(f.collection, [...by.get(f.collection) ?? [], f]);
+  }
+  return [...by.keys()].sort().map((c) => ({
+    table: `cms_${c}`.slice(0, 63),
+    pk: "_id",
+    columns: [
+      ...META_COLS,
+      ...by.get(c).sort((a, b2) => a.field.localeCompare(b2.field)).map((f) => ({
+        name: f.field,
+        type: PG_TYPE[f.type] ?? "jsonb",
+        field: f,
+        ...f.type === "relation" && f.relation_to ? { comment: `relation \u2192 cms_${f.relation_to}._id` } : {},
+        ...f.type === "file" ? { comment: "file \u2192 files.object_id" } : {}
+      }))
+    ]
+  }));
+}
+var USERS_TABLE = {
+  table: "users",
+  pk: "id",
+  columns: [
+    { name: "id", type: "text" },
+    { name: "email", type: "text" },
+    { name: "display_name", type: "text" },
+    { name: "avatar_url", type: "text" },
+    { name: "attributes", type: "jsonb" }
+  ]
+};
+var CREDENTIAL_COLUMNS = [
+  { name: "password_hash", type: "text" },
+  { name: "password_algorithm", type: "text" },
+  { name: "email_verified", type: "boolean" }
+];
+var FILES_TABLE = {
+  table: "files",
+  pk: "object_id",
+  columns: [
+    { name: "object_id", type: "text" },
+    { name: "end_user_id", type: "text" },
+    { name: "filename", type: "text" },
+    { name: "content_type", type: "text" },
+    { name: "size_bytes", type: "bigint" },
+    { name: "checksum_sha256", type: "text" },
+    { name: "status", type: "text" },
+    { name: "created_at", type: "timestamptz" },
+    { name: "uploaded_at", type: "timestamptz" },
+    { name: "download_url", type: "text", comment: "a presigned URL \u2014 dead after download_expires_at" },
+    { name: "download_expires_at", type: "timestamptz" },
+    { name: "_row", type: "jsonb" }
+  ]
+};
+function coerce(type, v) {
+  if (v === void 0 || v === null) return { value: null, mismatch: false };
+  switch (type) {
+    case "text":
+      return typeof v === "string" ? { value: v, mismatch: false } : typeof v === "number" || typeof v === "boolean" ? { value: String(v), mismatch: false } : { value: null, mismatch: true };
+    case "bigint":
+      return typeof v === "number" && Number.isSafeInteger(v) ? { value: v, mismatch: false } : typeof v === "string" && /^-?\d{1,15}$/.test(v) ? { value: Number(v), mismatch: false } : { value: null, mismatch: true };
+    case "double precision":
+      return typeof v === "number" && Number.isFinite(v) ? { value: v, mismatch: false } : typeof v === "string" && v.trim() !== "" && Number.isFinite(Number(v)) ? { value: Number(v), mismatch: false } : { value: null, mismatch: true };
+    case "boolean":
+      return typeof v === "boolean" ? { value: v, mismatch: false } : { value: null, mismatch: true };
+    case "timestamptz":
+      return typeof v === "string" && Number.isFinite(Date.parse(v)) ? { value: new Date(Date.parse(v)).toISOString(), mismatch: false } : { value: null, mismatch: true };
+    case "jsonb":
+      return { value: v, mismatch: false };
+    default:
+      return { value: null, mismatch: true };
+  }
+}
+async function* exportLines(path) {
+  const rl = createInterface({ input: createReadStream(path, "utf8"), crlfDelay: Infinity });
+  for await (const line of rl) {
+    if (!line.trim()) continue;
+    let o;
+    try {
+      o = JSON.parse(line);
+    } catch {
+      throw new Error(`${path}: a line is not JSON \u2014 was the export cut short?`);
+    }
+    const x = o;
+    if (typeof x.t === "string" && x.r && typeof x.r === "object") {
+      yield { t: x.t, r: x.r, ...x.download && typeof x.download === "object" ? { download: x.download } : {} };
+    }
+  }
+}
+var TableLoader = class {
+  constructor(sql, schema, plan, runAt, upsertCols) {
+    this.sql = sql;
+    this.schema = schema;
+    this.plan = plan;
+    this.runAt = runAt;
+    this.upsertCols = upsertCols;
+  }
+  sql;
+  schema;
+  plan;
+  runAt;
+  upsertCols;
+  rows = [];
+  count = 0;
+  mismatches = {};
+  /** CREATE IF NOT EXISTS + ADD COLUMN IF NOT EXISTS; refuses a column whose
+   *  existing type differs (never ALTERs your data's type behind your back). */
+  async ensure() {
+    const s = quoteIdent(this.schema);
+    const t = `${s}.${quoteIdent(this.plan.table)}`;
+    await this.sql.unsafe(`CREATE SCHEMA IF NOT EXISTS ${s}`);
+    await this.sql.unsafe(`CREATE TABLE IF NOT EXISTS ${t} (${quoteIdent(this.plan.pk)} text PRIMARY KEY, "_exported_at" timestamptz NOT NULL)`);
+    const have = new Map((await this.sql`
+      SELECT column_name, data_type FROM information_schema.columns
+      WHERE table_schema = ${this.schema} AND table_name = ${this.plan.table}`).map((r) => [r.column_name, r.data_type]));
+    for (const c of this.plan.columns) {
+      if (c.name === this.plan.pk) continue;
+      const cur = have.get(c.name);
+      if (cur !== void 0 && cur !== DATA_TYPE[c.type]) {
+        throw new Error(`${this.schema}.${this.plan.table}.${c.name} is ${cur} in your database but the field is now ${c.type} \u2014 rename or drop that column (or export into a fresh --pg-schema); vxil never rewrites a column type for you`);
+      }
+      if (cur === void 0) await this.sql.unsafe(`ALTER TABLE ${t} ADD COLUMN IF NOT EXISTS ${quoteIdent(c.name)} ${c.type}`);
+      if (c.comment) await this.sql.unsafe(`COMMENT ON COLUMN ${t}.${quoteIdent(c.name)} IS '${c.comment.replace(/'/g, "''")}'`);
+    }
+  }
+  async add(row2) {
+    this.rows.push(row2);
+    this.count++;
+    if (this.rows.length >= 500) await this.flush();
+  }
+  /** Mark a column mismatch (the value went to _data / _row only). */
+  miss(col) {
+    this.mismatches[col] = (this.mismatches[col] ?? 0) + 1;
+  }
+  async flush() {
+    if (this.rows.length === 0) return;
+    const cols = this.upsertCols ?? this.plan.columns.map((c) => c.name);
+    const typeOf = new Map(this.plan.columns.map((c) => [c.name, c.type]));
+    const t = `${quoteIdent(this.schema)}.${quoteIdent(this.plan.table)}`;
+    const list = [...cols, "_exported_at"].map(quoteIdent).join(", ");
+    const rec = [...cols.map((c) => `${quoteIdent(c)} ${typeOf.get(c) ?? "text"}`), '"_exported_at" timestamptz'].join(", ");
+    const set = [...cols.filter((c) => c !== this.plan.pk), "_exported_at"].map((c) => `${quoteIdent(c)} = EXCLUDED.${quoteIdent(c)}`).join(", ");
+    const batch = this.rows.map((r) => ({ ...r, _exported_at: this.runAt }));
+    this.rows = [];
+    await this.sql.unsafe(
+      `INSERT INTO ${t} (${list}) SELECT ${list} FROM jsonb_to_recordset($1::text::jsonb) AS x(${rec}) ON CONFLICT (${quoteIdent(this.plan.pk)}) DO UPDATE SET ${set}`,
+      [JSON.stringify(batch)]
+    );
+  }
+  /** After a COMPLETE export: drop what this run did not see. */
+  async prune() {
+    const t = `${quoteIdent(this.schema)}.${quoteIdent(this.plan.table)}`;
+    const r = await this.sql.unsafe(`DELETE FROM ${t} WHERE "_exported_at" < $1::timestamptz`, [this.runAt]);
+    return r.count;
+  }
+};
+async function clearCredentialColumns(sql, schema) {
+  const [has] = await sql`
+    SELECT count(*)::int AS n FROM information_schema.columns
+    WHERE table_schema = ${schema} AND table_name = 'users' AND column_name IN ('password_hash', 'password_algorithm')`;
+  if ((has?.n ?? 0) < 2) return 0;
+  const r = await sql.unsafe(
+    `UPDATE ${quoteIdent(schema)}."users" SET "password_hash" = NULL, "password_algorithm" = NULL WHERE "password_hash" IS NOT NULL`
+  );
+  return r.count;
+}
+async function loadIntoPostgres(sql, schema, inputs, log, runAt = (/* @__PURE__ */ new Date()).toISOString()) {
+  quoteIdent(schema);
+  const report = { tables: [], skipped: [] };
+  const done = async (l, complete) => {
+    await l.flush();
+    const pruned = complete ? await l.prune() : null;
+    report.tables.push({ table: `${schema}.${l.plan.table}`, rows: l.count, pruned, mismatches: l.mismatches });
+    log(`  \u2713 ${schema}.${l.plan.table}: ${l.count} row(s)${pruned !== null ? `, ${pruned} removed (gone on vxil)` : " (export incomplete \u2014 nothing removed)"}` + (Object.keys(l.mismatches).length ? ` \xB7 values that did not fit their column (kept in _data): ${Object.entries(l.mismatches).map(([c, n]) => `${c}=${n}`).join(" ")}` : ""));
+  };
+  if (inputs.users) {
+    const plan = inputs.credentials ? { ...USERS_TABLE, columns: [...USERS_TABLE.columns, ...CREDENTIAL_COLUMNS] } : USERS_TABLE;
+    const l = new TableLoader(sql, schema, plan, runAt, USERS_TABLE.columns.map((c) => c.name));
+    await l.ensure();
+    for await (const { t, r } of exportLines(inputs.users)) {
+      if (t !== "users") continue;
+      await l.add({ id: r.id, email: r.email ?? null, display_name: r.display_name ?? null, avatar_url: r.avatar_url ?? null, attributes: r.attributes ?? {} });
+    }
+    await done(l, inputs.complete.users);
+    const cleared = await clearCredentialColumns(sql, schema);
+    if (cleared > 0 && !inputs.credentials) {
+      log(`  \u2713 ${schema}.users: ${cleared} password hash(es) cleared \u2014 this run did not include --include-password-hashes, and the mirror never keeps an older one`);
+    }
+    if (inputs.credentials) {
+      const c = new TableLoader(sql, schema, plan, runAt, ["id", "email", "password_hash", "password_algorithm", "email_verified"]);
+      for await (const { t, r } of exportLines(inputs.credentials)) {
+        if (t !== "credential") continue;
+        await c.add({ id: r.id, email: r.email ?? null, password_hash: r.password_hash, password_algorithm: r.algorithm, email_verified: r.email_verified === true });
+      }
+      await c.flush();
+      log(`  \u2713 ${schema}.users: ${c.count} password hash(es) loaded \u2014 treat this database as holding credentials`);
+    }
+  }
+  if (inputs.cms) {
+    const fields = [];
+    for await (const { t, r } of exportLines(inputs.cms)) {
+      if (t === "fields") fields.push({ collection: String(r.collection), field: String(r.field), type: String(r.type), relation_to: r.relation_to ?? null });
+    }
+    const loaders = /* @__PURE__ */ new Map();
+    for (const plan of collectionTables(fields)) {
+      const l = new TableLoader(sql, schema, plan, runAt);
+      await l.ensure();
+      loaders.set(plan.table.slice("cms_".length), l);
+    }
+    for await (const { t, r } of exportLines(inputs.cms)) {
+      if (t !== "items" || r.deleted_at) continue;
+      const l = loaders.get(String(r.collection));
+      if (!l) {
+        report.skipped.push(`cms item ${String(r.item_id)}: collection '${String(r.collection)}' has no fields in the export`);
+        continue;
+      }
+      const data2 = r.data && typeof r.data === "object" ? r.data : {};
+      const row2 = {
+        _id: r.item_id,
+        _status: r.status ?? null,
+        _created_at: r.created_at ?? null,
+        _updated_at: r.updated_at ?? null,
+        _published_at: r.published_at ?? null,
+        _data: data2
+      };
+      for (const c of l.plan.columns) {
+        if (!c.field) continue;
+        const v = coerce(c.type, data2[c.field.field]);
+        if (v.mismatch) l.miss(c.name);
+        row2[c.name] = v.value;
+      }
+      await l.add(row2);
+    }
+    for (const l of loaders.values()) await done(l, inputs.complete.cms);
+  }
+  if (inputs.files) {
+    const l = new TableLoader(sql, schema, FILES_TABLE, runAt);
+    await l.ensure();
+    for await (const { t, r, download } of exportLines(inputs.files)) {
+      if (t !== "objects") continue;
+      const row2 = { _row: r, download_url: download?.url ?? null, download_expires_at: download?.expires_at ?? null };
+      for (const c of FILES_TABLE.columns) {
+        if (c.name in row2) continue;
+        const v = coerce(c.type, r[c.name]);
+        if (v.mismatch) l.miss(c.name);
+        row2[c.name] = v.value;
+      }
+      await l.add(row2);
+    }
+    await done(l, inputs.complete.files);
+  }
+  return report;
+}
+
+// src/migrate/adapters/targetPg.ts
+function openTargetDatabase(url) {
+  if (!/^postgres(ql)?:\/\//i.test(url)) {
+    throw new Error("--to-postgres needs a postgres:// (or postgresql://) connection string");
+  }
+  return src_default(url, {
+    max: 1,
+    prepare: false,
+    // transaction-pooler compatible
+    onnotice: () => {
+    },
+    connection: { application_name: "vxil-export" }
+  });
+}
+
 // src/projects.ts
+var PROJECT_WORKLOADS = ["production", "staging", "development"];
+function isWorkload(v) {
+  return typeof v === "string" && PROJECT_WORKLOADS.includes(v);
+}
 async function listProjectsViaSession(dash, cookie) {
   const r = await dash("GET", "/dashboard/tenants", void 0, cookie);
   if (r.status === 401) return { unauthorized: true };
@@ -9283,18 +9839,26 @@ function renderProjects(tenants, bound) {
   return tenants.map((t) => {
     const slot = bound.get(t.slug);
     const kind = t.kind === "dev" ? ` \xB7 dev${t.expires_at ? `, expires ${t.expires_at}` : ""}` : "";
-    return `${slot ? `[${slot}]`.padEnd(14) : "".padEnd(14)}${t.slug}  ${t.display_name}  ${t.tier}${t.role ? ` \xB7 ${t.role}` : ""}${kind}`;
+    const workload = t.kind !== "dev" && t.workload ? ` \xB7 ${t.workload}` : "";
+    return `${slot ? `[${slot}]`.padEnd(14) : "".padEnd(14)}${t.slug}  ${t.display_name}  ${t.tier}${workload}${t.role ? ` \xB7 ${t.role}` : ""}${kind}`;
   });
 }
-function parseProjectCreate(slug, name) {
+function parseProjectCreate(slug, name, workload) {
   const s = (slug ?? "").trim();
-  if (!s) return { error: "usage: vxil projects create <slug> [--name <display name>] [--json]" };
+  if (!s) return { error: "usage: vxil projects create <slug> [--name <display name>] [--workload production|staging|development] [--json]" };
   if (!TENANT_SLUG_RE.test(s)) return { error: `'${s}' is not a valid slug \u2014 lowercase letters, digits and hyphens (${TENANT_SLUG_RE.source})` };
+  if (workload !== void 0 && !isWorkload(workload)) {
+    return { error: `--workload must be one of ${PROJECT_WORKLOADS.join(", ")}` };
+  }
   const display = (name ?? "").trim() || s;
-  return { body: { slug: s, display_name: display } };
+  return { body: { slug: s, display_name: display, ...workload !== void 0 ? { workload } : {} } };
 }
 async function createProjectViaSession(dash, cookie, body) {
-  const r = await dash("POST", "/dashboard/tenants", { slug: body.slug, display_name: body.display_name }, cookie);
+  const r = await dash("POST", "/dashboard/tenants", {
+    slug: body.slug,
+    display_name: body.display_name,
+    ...body.workload ? { workload: body.workload } : {}
+  }, cookie);
   if (r.status === 401) return { unauthorized: true };
   if (r.status !== 201 && r.status !== 200) throw new Error(`could not create '${body.slug}' (${errText(r)})`);
   const d = data(r);
@@ -9306,10 +9870,32 @@ async function createProjectViaSession(dash, cookie, body) {
       display_name: d.display_name ?? body.display_name,
       tier: d.tier ?? "free",
       kind: d.kind ?? null,
-      expires_at: d.expires_at ?? null
+      expires_at: d.expires_at ?? null,
+      ...d.workload ? { workload: d.workload } : {}
     }
   };
 }
+function parseWorkloadArg(v) {
+  if (!v) return { error: `usage: vxil projects workload <slug> ${PROJECT_WORKLOADS.join("|")} [--json]` };
+  return isWorkload(v) ? { workload: v } : { error: `workload must be one of ${PROJECT_WORKLOADS.join(", ")} (got '${v}')` };
+}
+async function setProjectWorkloadViaSession(dash, cookie, tenantId, workload) {
+  const r = await dash("PATCH", `/dashboard/tenants/${tenantId}`, { workload }, cookie);
+  if (r.status === 401) return { unauthorized: true };
+  if (r.status !== 200) throw new Error(`could not change the workload (${errText(r)})`);
+  return { change: data(r) };
+}
+function renderWorkloadChange(slug, c) {
+  if (!c.changed) return { stdout: `\u2713 '${slug}' is already ${c.workload}`, stderr: [] };
+  const err = [];
+  const w = c.functions_wall;
+  if (w && (w.walled ?? 0) > 0) {
+    err.push("its functions are paused: a production project needs a plan that includes functions for production (Developer and up) \u2014 upgrade (`vxil billing upgrade`), or set the workload back");
+  }
+  if (w && (w.unwalled ?? 0) > 0) err.push("its paused functions are running again");
+  if (w && ((w.failed ?? 0) > 0 || w.error)) err.push("the functions wall could not be applied right now \u2014 the nightly pass retries it");
+  return { stdout: `\u2713 '${slug}' is now ${c.workload} (was ${c.from ?? "?"})`, stderr: err };
+}
 async function deleteProjectViaSession(dash, cookie, tenantId, slug) {
   const r = await dash("DELETE", `/dashboard/tenants/${tenantId}`, { confirm: slug }, cookie);
   if (r.status === 401) return { unauthorized: true };
@@ -9989,7 +10575,9 @@ function buildEnvelope(opts) {
     vxil_base: DEV_VXIL_BASE,
     scoped_jwts: scopedJwts,
     secrets: opts.secrets ?? {},
-    payload: opts.payload
+    payload: opts.payload,
+    // a deployed cron tick names the slot it was due for (2026-10-01)
+    ...trigger === "cron" ? { scheduled_for: opts.scheduledFor ?? new Date(Math.floor(Date.now() / 6e4) * 6e4).toISOString() } : {}
   };
 }
 function audForPath(pathname) {
@@ -10286,6 +10874,42 @@ function stripApiVersionsBlock(src) {
   if (j < 0) return src;
   return src.slice(0, i) + src.slice(j + API_VERSIONS_BLOCK_TAIL.length);
 }
+function parseApiVersionsBlock(src) {
+  const i = src.indexOf(API_VERSIONS_BLOCK_HEAD);
+  if (i < 0) return null;
+  const start = i + API_VERSIONS_BLOCK_HEAD.length;
+  const j = src.indexOf(API_VERSIONS_BLOCK_TAIL, start);
+  if (j < 0) return null;
+  const out = {};
+  for (const line of src.slice(start, j).split("\n")) {
+    if (!line.trim()) continue;
+    const m = /^\s+(?:"((?:[^"\\]|\\.)*)"|([A-Za-z_$][\w$]*)): \[(.*)\],$/.exec(line);
+    if (!m) return null;
+    const key = m[1] !== void 0 ? JSON.parse(`"${m[1]}"`) : m[2];
+    let majors;
+    try {
+      majors = JSON.parse(`[${m[3]}]`);
+    } catch {
+      return null;
+    }
+    if (!Array.isArray(majors) || !majors.every((x) => typeof x === "string")) return null;
+    out[key] = majors;
+  }
+  return out;
+}
+function apiMajorDrift(pinned, live) {
+  const rows = [];
+  const feats = [.../* @__PURE__ */ new Set([...Object.keys(pinned), ...Object.keys(live)])].sort(compareCodePoints);
+  const known = /* @__PURE__ */ new Set(["v1", ...Object.values(pinned).flat()]);
+  for (const f of feats) {
+    const a = [...pinned[f] ?? []].sort();
+    const b2 = [...live[f] ?? []].sort();
+    if (!(f in live)) continue;
+    if (!(f in pinned) && b2.every((m) => known.has(m))) continue;
+    if (a.join("|") !== b2.join("|")) rows.push({ feature: f, pinned: a, live: b2 });
+  }
+  return rows;
+}
 function canonicalCollections(collections) {
   return [...collections].sort((a, b2) => compareCodePoints(a.collection, b2.collection)).map((c) => ({ ...c, fields: [...c.fields].sort((a, b2) => compareCodePoints(a.field, b2.field)) }));
 }
@@ -10331,6 +10955,7 @@ function checkGeneratedTypes(existing, generated, opts) {
   let unpinnedNotice = false;
   if (opts.offline) {
     have = stripApiVersionsBlock(have);
+    want = stripApiVersionsBlock(want);
   } else if (existing && hasApiVersionsBlock(generated) && !hasApiVersionsBlock(existing)) {
     unpinnedNotice = true;
     want = stripApiVersionsBlock(want);
@@ -10686,7 +11311,7 @@ var TOOLS = [
   {
     name: "jobs_list_runs",
     feature: "jobs",
-    description: "List job runs (state machine: queued\u2192running\u2192succeeded | retrying\u2192dead | cancelled; delayed = scheduled future delivery, waiting = suspended on an event).",
+    description: "List job runs (state machine: queued\u2192running\u2192succeeded | retrying\u2192dead | cancelled; delayed = scheduled future delivery, waiting = suspended on an event). A platform webhook delivery run (job_name webhooks.deliver) carries webhook_event + audit_id (the event id in the audit log, = the audit_id your handler receives) \u2014 the event a dead delivery lost; its payload stays redacted.",
     inputSchema: {
       type: "object",
       properties: {
@@ -10787,7 +11412,7 @@ var TOOLS = [
   {
     name: "jobs_create_schedule",
     feature: "jobs",
-    description: "Create a recurring (5-field cron, UTC) or one-shot (run_at ISO) schedule that enqueues the job on the minute tick. Exactly one of cron/run_at.",
+    description: "Create a recurring (5-field cron, UTC) or one-shot (run_at ISO) schedule that enqueues the job on the minute tick. Exactly one of cron/run_at. overlap 'skip' (cron only): no new run while the previous one is still open \u2014 the slot is counted, never caught up.",
     inputSchema: {
       type: "object",
       properties: {
@@ -10795,13 +11420,22 @@ var TOOLS = [
         target_url: { type: "string" },
         payload: { type: "object", additionalProperties: true },
         cron: { type: "string", description: "e.g. '0 */6 * * *' (UTC)" },
-        run_at: { type: "string", description: "future ISO timestamp" }
+        run_at: { type: "string", description: "future ISO timestamp" },
+        overlap: { type: "string", enum: ["allow", "skip"], default: "allow", description: "cron only: 'skip' fires nothing while an earlier run of this schedule is queued / running / retrying / waiting / delayed" }
       },
       required: ["job_name", "target_url"]
     },
     method: "POST",
     path: "/v1/jobs/schedules"
   },
+  {
+    name: "jobs_list_schedules",
+    feature: "jobs",
+    description: "List the tenant's schedules (incl. the fn-cron:* function ticks): cron, state, next/last run, overlap, skipped_fires, and `held` \u2014 non-null when the schedule fired on time but its oldest run has not started for 2+ intervals (held downstream).",
+    inputSchema: { type: "object", properties: {} },
+    method: "GET",
+    path: "/v1/jobs/schedules"
+  },
   {
     name: "jobs_get_signing_secret",
     feature: "jobs",
@@ -10924,6 +11558,19 @@ var TOOLS = [
     method: "GET",
     path: (a) => `/v1/files/${encodeURIComponent(String(a.object_id))}/download-url`
   },
+  {
+    name: "files_get_download_urls",
+    feature: "files",
+    description: "Mint presigned GET URLs for up to 100 objects in one call (comma-separated object_ids). Unknown, deleted or still-uploading ids are listed under errors[] instead of failing the batch.",
+    inputSchema: {
+      type: "object",
+      properties: { object_ids: { type: "string", description: "Comma-separated object ids (at most 100)." } },
+      required: ["object_ids"]
+    },
+    method: "GET",
+    path: "/v1/files/download-urls",
+    queryArgs: ["object_ids"]
+  },
   {
     name: "files_list",
     feature: "files",
@@ -11045,7 +11692,7 @@ var TOOLS = [
   {
     name: "cms_query_items",
     feature: "cms",
-    description: 'Query content items with the bounded DSL. filter is a JSON object (\u22648 terms): {"price":{"$gte":10},"status":"published"}; ops $eq $ne $gt $gte $lt $lte $in $contains $startsWith (substring/prefix, LIKE-escaped) $arrayContains/$anyOf (array fields: all-of / any-of). sort: "-field" (slot-indexed fields + created_at/updated_at/published_at). $expand inlines relation/file fields. count=true returns {count} instead of a page (filter only \u2014 no sort/limit/$expand).',
+    description: 'Query content items with the bounded DSL. filter is a JSON object (\u22648 terms): {"price":{"$gte":10},"status":"published"}; ops $eq $ne $gt $gte $lt $lte $in $contains $startsWith (substring/prefix, LIKE-escaped) $arrayContains/$anyOf (array fields: all-of / any-of). sort: "-field" (slot-indexed fields + created_at/updated_at/published_at). Paging: pass the returned next_cursor back as cursor WITH THE SAME filter and sort (works for the default order and for any slot/timestamp sort; not for a dotted join sort). $expand inlines relation/file fields. count=true returns {count} instead of a page (filter only \u2014 no sort/limit/cursor/$expand).',
     inputSchema: {
       type: "object",
       properties: {
@@ -11053,6 +11700,7 @@ var TOOLS = [
         filter: { type: "string", description: "JSON filter object as a string" },
         sort: { type: "string" },
         limit: { type: "number", default: 25 },
+        cursor: { type: "string", description: "next_cursor from the previous page (same filter + sort)" },
         $expand: {
           type: "string",
           description: "comma-separated relation/file field names to inline (bounded depth; see cms_list_collections for relation_to). Cannot be combined with count=true."
@@ -11063,7 +11711,7 @@ var TOOLS = [
     },
     method: "GET",
     path: (a) => `/v1/cms/items/${encodeURIComponent(String(a.collection))}`,
-    queryArgs: ["filter", "sort", "limit", "$expand", "count"]
+    queryArgs: ["filter", "sort", "limit", "cursor", "$expand", "count"]
   },
   {
     name: "cms_inc_item",
@@ -11501,6 +12149,20 @@ var TOOLS = [
     method: "DELETE",
     path: (a) => `/v1/webhooks/subscriptions/${encodeURIComponent(String(a.sub_id))}`
   },
+  {
+    name: "functions_delete",
+    feature: "functions",
+    description: "Remove ONE deployed function from the project: a new functions config version without it \u2014 invokes answer 404 and its crons and event triggers are unbound. The deployed code is kept until the nightly cleanup, so a functions config rollback restores it exactly. 404 function_not_found when the name is not deployed. Read the deployed names from the vxil://functions/catalog resource first. Needs features:write.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        name: { type: "string", description: "The deployed function name (lowercase, e.g. on-payment)." }
+      },
+      required: ["name"]
+    },
+    method: "DELETE",
+    path: (a) => `/v1/functions/${encodeURIComponent(String(a.name))}`
+  },
   {
     name: "webhooks_test_subscription",
     feature: "webhooks",
@@ -11710,6 +12372,21 @@ var TOOLS = [
     method: "POST",
     path: "/v1/ai/generate"
   },
+  {
+    name: "ai_generation_get",
+    feature: "ai",
+    description: "Read a generation back: pass generation_id for one (status pending|processing|completed|failed, usage, run_id, and for a job-lane generation the settled answer in result.text, kept 30 days), or correlation_id to find yours by your own handle (newest first, at most 20; each with result:null \u2014 call again with that generation_id for its text) \u2014 the recovery read after a timed-out or lost job answer. result_state says stored | purged | not_recorded (sync and stream generations return their answer directly and record none).",
+    inputSchema: {
+      type: "object",
+      properties: {
+        generation_id: { type: "string", description: "The generation_id from the generate answer (use this OR correlation_id)." },
+        correlation_id: { type: "string", minLength: 1, maxLength: 128, description: "The correlation_id you sent on ai_generate / the REST generate call." }
+      }
+    },
+    method: "GET",
+    path: (a) => a.generation_id ? `/v1/ai/generations/${encodeURIComponent(String(a.generation_id))}` : "/v1/ai/generations",
+    queryArgs: ["correlation_id"]
+  },
   {
     name: "ai_classify",
     feature: "ai",
@@ -11770,6 +12447,18 @@ var TOOLS = [
     method: "POST",
     path: "/v1/ai/judge"
   },
+  {
+    name: "ai_template_retire",
+    feature: "ai",
+    description: "Retire a stored prompt template (soft): every live version of the name leaves the template list and can no longer be rendered by ai_generate / ai_classify / ai_judge (404 template_not_found, by name or by version); the stored versions stay for the generations that used them, and storing the name again starts a new live version. 404 template_not_found when no live version exists. Needs ai:write. Prefer declaring templates in vxil.config \u2014 `vxil push --allow-destructive` retires the ones the config dropped.",
+    inputSchema: {
+      type: "object",
+      properties: { name: { type: "string", pattern: "^[a-zA-Z0-9_.\\-]{1,128}$", description: "The template name." } },
+      required: ["name"]
+    },
+    method: "DELETE",
+    path: (a) => `/v1/ai/templates/${encodeURIComponent(String(a.name))}`
+  },
   {
     name: "rag_answer",
     feature: "rag",
@@ -11849,18 +12538,25 @@ var TOOLS = [
   {
     name: "payments_consume",
     feature: "payments",
-    description: "Debit credits from an end-user \u2014 idempotent (idempotency_key REQUIRED; the SAME key always returns the SAME result, never double-charges) and balance-guarded (never oversells; returns 402 INSUFFICIENT_CREDITS when available can't cover amount). Pass job_id to make the debit a PROVISIONAL hold tied to a background job: a linked jobs run that terminally fails auto-refunds the hold, a success settles it. amount must be >= 1. Needs payments:write.",
+    description: "Debit credits from an end-user \u2014 idempotent (idempotency_key REQUIRED; the SAME key always returns the SAME result, never double-charges) and balance-guarded (never oversells; returns 402 INSUFFICIENT_CREDITS when available can't cover amount). Name ONE credit_type, or an ordered credit_types list (e.g. ['free','subscription','topup']): the WHOLE amount comes from the FIRST type whose available balance covers it \u2014 never split across types \u2014 and the answer's credit_type names the one debited. Pass job_id to make the debit a PROVISIONAL hold tied to a background job: a linked jobs run that terminally fails auto-refunds the hold, a success settles it. amount must be >= 1. Needs payments:write.",
     inputSchema: {
       type: "object",
       properties: {
         user_id: { type: "string", description: "Opaque end_user_id to debit." },
-        credit_type: { type: "string", description: "Credit type to debit, e.g. 'scans'." },
+        credit_type: { type: "string", description: "Credit type to debit, e.g. 'scans'. Give this OR credit_types." },
+        credit_types: {
+          type: "array",
+          items: { type: "string" },
+          minItems: 1,
+          maxItems: 8,
+          description: "Ordered credit types (1-8, distinct) \u2014 the first one whose available balance covers the whole amount is debited. Give this OR credit_type."
+        },
         amount: { type: "number", minimum: 1, description: "Credits to consume (>= 1)." },
         idempotency_key: { type: "string", description: "Unique key for this debit; reusing it replays the first result (no double-charge)." },
         job_id: { type: "string", description: "Optional jobs run_id to link: makes the debit a provisional hold that auto-reverses if the job terminally fails." },
         reason: { type: "string", description: "Optional human-readable reason recorded on the ledger row." }
       },
-      required: ["user_id", "credit_type", "amount", "idempotency_key"]
+      required: ["user_id", "amount", "idempotency_key"]
     },
     method: "POST",
     path: "/v1/payments/credits/consume",
@@ -11888,6 +12584,23 @@ var TOOLS = [
     path: "/v1/payments/webhook-events",
     queryArgs: ["provider", "event_type", "outcome", "environment", "provider_charge_id", "provider_evt_id", "since", "cursor", "limit"]
   },
+  {
+    name: "payments_list_refunds",
+    feature: "payments",
+    description: "List the refunds of ONE charge (charge_id) or read one refund (refund_id) \u2014 one of the two is required \u2014 newest first: refund_id, amount_cents, currency, status (pending until the provider settles it, e.g. a Paddle adjustment awaiting approval; succeeded; failed), provider_refund_id, reason, source (api = issued through POST /v1/payments/refunds, webhook = recorded from the provider's own dashboard) and created_at. Use it to tie a refund_id from a refund call, its 502/422 answer or a payments.refund.failed / payments.charge.refunded event back to the money, and to see whether a refund has landed before ending access. Read-only \u2014 needs payments:read. A thin-client key sees only its own charges' refunds; an unknown parameter is a 422.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        charge_id: { type: "string", maxLength: 200, description: "The vxil charge id (chg_\u2026) whose refunds to list." },
+        refund_id: { type: "string", maxLength: 200, description: "Read one refund by its id (ref_\u2026)." },
+        status: { type: "string", enum: ["pending", "succeeded", "failed"] },
+        limit: { type: "number", default: 50, description: "Page size, clamped 1..100." }
+      }
+    },
+    method: "GET",
+    path: "/v1/payments/refunds",
+    queryArgs: ["charge_id", "refund_id", "status", "limit"]
+  },
   {
     name: "mcp_get_signing_secret",
     description: 'Per-tenant secret your endpoints use to verify the X-Vxil-Mcp-Signature header on custom MCP tool calls (config mcp.customTools). Same recipe as jobs callbacks: t=<unix>,v1=<hmac-sha256-hex over "<toolName>.<tenantId>.<t>.<sha256hex(body)>">, 300s replay window. Needs features:read.',
@@ -12229,6 +12942,15 @@ function markObjectsComplete(b2) {
 function truncationNotes(b2) {
   return Array.isArray(b2.skipped) ? b2.skipped.filter((s) => /: truncated at \d+ rows/.test(s)) : [];
 }
+var EXPORT_EXIT_INCOMPLETE = 4;
+function incompleteTablesMessage(feature, tables, json2) {
+  const list = tables.map((t) => `'${t}'`).join(", ");
+  return `vxil: export ${feature} is INCOMPLETE \u2014 ${list} ${tables.length === 1 ? "was" : "were"} cut at the server row cap` + (json2 ? " (the JSON bundle is capped; `--ndjson` resumes past the cap)" : " and the server gave no resume cursor (an older server, or a table with no primary key)") + ` \u2014 the output holds every row up to the cut \u2014 exit ${EXPORT_EXIT_INCOMPLETE}`;
+}
+function worseExportExit(current, code) {
+  const n = typeof current === "number" ? current : Number(current ?? 0) || 0;
+  return Math.max(n, code);
+}
 
 // src/drift.ts
 function isPlainObject2(v) {
@@ -13187,6 +13909,120 @@ function renderTryReport(result, opts) {
   return lines;
 }
 
+// src/verbHelp.ts
+var SELF_HELP_VERBS = /* @__PURE__ */ new Set(["keys", "account", "members", "api", "migrate"]);
+var VERB_USAGE = {
+  version: "usage: vxil --version  \u2014 print the CLI version",
+  init: "usage: vxil init [--template <id>] [--force]  \u2014 scaffold vxil.config.ts + functions/ + .vxil/ from a Blueprint Gallery template (`vxil templates` lists them)",
+  templates: "usage: vxil templates  \u2014 list the Blueprint Gallery (`vxil init --template <id>` scaffolds one)",
+  quickstart: "usage: vxil quickstart [--features a,b] [--invite <code>] [--env <label>] [--dev [--ttl <h>]] [--no-push]  \u2014 create a project + key + enable features in one call",
+  try: "usage: vxil try  \u2014 a keyless anonymous sandbox backend (no account); self-expires",
+  login: "usage: vxil login [--email <e>] [--password <p>]  \u2014 store a dashboard session in ~/.vxil (bound to the dashboard it came from)",
+  link: "usage: vxil link <slug> [--key <api_key> [--tenant <id>]] [--as dev|<target-name>] [--env <label>] [--mint]  \u2014 bind this repo to a project; --tenant is checked against the key's own tenant and refused when the key's tenant cannot be read",
+  keys: "usage: vxil keys mint|list|revoke|perms \u2026  (run `vxil keys --help`)",
+  account: "usage: vxil account [show]|set|password  (run `vxil account --help`)",
+  logout: "usage: vxil logout [--json]  \u2014 revoke the stored dashboard session where it was obtained and remove it from ~/.vxil (project API keys are untouched)",
+  invites: "usage: vxil invites [list] [--json] \xB7 vxil invites generate [--count <n>] [--json] \xB7 vxil invites accept <token | invite-url> [--json]",
+  members: "usage: vxil members [list]|invite|add|rm|uninvite  (run `vxil members --help`)",
+  projects: "usage: vxil projects [list] [--json] \xB7 projects create <slug> [--name <display>] [--json] \xB7 projects rm <slug> [--yes] [--json]",
+  billing: "usage: vxil billing [status] [--json] \xB7 vxil billing upgrade --tier <free|developer|team|business> [--yes] [--json]   (upgrade also downgrades: --tier free)",
+  files: "usage: vxil files put <path> --user <user_id> [--content-type <type>] [--json] \xB7 vxil files rm <object_id> [--yes] [--json]",
+  webhooks: "usage: vxil webhooks sources add --provider <stripe|paddle|github|slack|revenuecat|generic> --name <n> [--forward-url <https>] \xB7 sources list \xB7 sources rm <source_id> [--yes] \xB7 sources test <source_id> \xB7 vxil webhooks events replay <event_id> \xB7 events runs <event_id>",
+  search: "usage: vxil search sync run <sourceKey> [--sweep] [--json] \xB7 vxil search sync reset <sourceKey> [--purge] [--yes] [--json]",
+  listen: "usage: vxil listen --forward-to <url> [--dev] [--source <id>] [--events <prefix,\u2026>] [--replay-last <n>] [--interval <s>] [--show-runs] [--raw]  \u2014 forward inbound webhook events to a local server",
+  mcp: "usage: vxil mcp install [--client cursor|claude|vscode] [--project] [--print] [--key <api_key>] [--scopes a,b] [--name <server>]",
+  plan: "usage: vxil plan [--dev|--target <name>] [--explain] [--skip-functions]  \u2014 what `vxil push` would change: cms schema, feature config, declared API state, functions (a deployed function the config no longer declares shows as `-`); writes nothing",
+  diff: "usage: vxil diff [--against <target>|--exit-code] [--explain] [--ignore <k,\u2026>] [--strict-secrets] [--strict-api-state] [--api-state] [--json]  \u2014 the CI gate: exit 0 no drift \xB7 1 drift \xB7 2 error",
+  push: "usage: vxil push [--dev|--target <name>|--prod] [--allow-destructive] [--strict] [--server [--resume <apply_id>]] [--no-gen] [--skip-functions] [--yes]  \u2014 apply the config; --allow-destructive also deletes deployed functions and stored AI templates the config no longer declares; --strict exits 1 when anything declared was refused, deferred or left unwired",
+  gen: "usage: vxil gen [--check] [--offline] [--out <f>] [--no-mcp] [--mcp-out <f>]  \u2014 generate vxil.types.ts (+ vxil.mcp.json); --offline keeps an existing API_VERSIONS block; --check compares instead of writing",
+  types: "usage: vxil types  \u2014 alias of `vxil gen` (run `vxil gen --help`)",
+  doctor: "usage: vxil doctor [--dev|--target <name>]  \u2014 preflight: the binding's tenant vs the key's tenant, secrets referenced-vs-stored, per-function hashes, keys (read-only)",
+  architect: 'usage: vxil architect "<describe your app>" [--name <n>] [--out vxil.config.ts]  \u2014 an advisory vxil.config draft',
+  versions: "usage: vxil versions <feature>  \u2014 the feature's config versions",
+  rollback: "usage: vxil rollback <feature> --to <version>",
+  pull: "usage: vxil pull [--dev|--target <name>] [--out <file=vxil.config.ts>] [--force]  \u2014 materialize config + cms schema from the live project",
+  env: "usage: vxil env pull [--dev | --target <name>] [--file <path=.env.local>] [--print] [--no-gitignore]",
+  secrets: "usage: vxil secrets set <feature>/<name> [--value -] \xB7 secrets list [--all-projects] \xB7 secrets rm <feature>/<name> [--yes]  (set reads piped stdin or a hidden prompt)",
+  seed: "usage: vxil seed [--dev|--target <name>]  \u2014 apply the config `seed` block through import bundles",
+  export: "usage: vxil export <feature> [--out <file>] [--ndjson] [--urls [--pace <seconds>]]  \u2014 exit 0 complete \xB7 1 error \xB7 3 download URLs expired before they could be read \xB7 4 incomplete (a table was cut at the server cap with no resume cursor; the file is still written)",
+  import: "usage: vxil import <feature> --file <bundle.json> [--mode merge|replace]",
+  migrate: "usage: vxil migrate plan|schema|data|verify|payments \u2026  (run `vxil migrate --help`)",
+  functions: "usage: vxil functions new|deploy [<name>] [--force]|list|delete|enable|disable [--yes]|invoke ['<json>' | --data '<json>'] [--async]|logs [--tail]|dev <name> [--port <n>] [--trigger <lane>] [--event <file.json>]",
+  cms: "usage: vxil cms status|pull|reindex <collection> [--field <field>]|drop <collection> [--yes]|bulk-rm <collection> --filter '<json>' [--limit <1..100>] [--dry-run] [--yes]",
+  payments: "usage: vxil payments simulate --scenario <refund-pair|cross-platform-unlock|renewal|expiry|past-due-grace|transfer> --user <id> [--tier <t>] [--dev]  \u2014 mock/dev projects only",
+  dev: "usage: vxil dev up [--ttl <h>] [--new] | down [--yes] | seed | reset | branch [<name>] [--ttl <h=24>] [--no-env] [--print] | --list | --rm <name> [--yes] | --watch [--target <name>]",
+  config: "usage: vxil config get <feature> \xB7 vxil config draft show|save [--file <f>]|publish|discard <feature> \xB7 vxil config draft duplicate <feature> --from <version>",
+  users: "usage: vxil users add <id> --email <email> \xB7 users list \xB7 users import <users.json|users.csv> [--json]",
+  send: "usage: vxil send <user_id> <template> --data '<json>'",
+  deliveries: "usage: vxil deliveries [--user <id>] [--status <s>]  \u2014 recent notification deliveries",
+  api: "usage: vxil api <METHOD> <path> ['<json>' | --data '<json>']  (run `vxil api --help` for the operator cheat-sheet)"
+};
+var ALIASES = { "--version": "version", "-v": "version" };
+function wantsHelp(rest2) {
+  return rest2.includes("--help") || rest2.includes("-h");
+}
+function helpRequest(cmd2, rest2) {
+  if (!cmd2 || !wantsHelp(rest2)) return null;
+  const verb = ALIASES[cmd2] ?? cmd2;
+  if (SELF_HELP_VERBS.has(verb)) return { delegate: verb };
+  const usage = VERB_USAGE[verb];
+  return usage === void 0 ? null : { print: usage };
+}
+function normalizeHelpArgv(rest2) {
+  if (rest2.includes("-h") && !rest2.includes("--help")) rest2.push("--help");
+}
+function isGlobalHelp(cmd2) {
+  return cmd2 === void 0 || cmd2 === "help" || cmd2 === "--help" || cmd2 === "-h";
+}
+
+// src/keyTenant.ts
+function knownTenantId(id) {
+  return typeof id === "string" && id.length > 0 && id !== "(unknown)";
+}
+function judgeKeyTenant(bindingTenant, read) {
+  if (!knownTenantId(bindingTenant)) {
+    return { kind: "unknown", reason: "the binding records no tenant id (VXIL_API_KEY with no project binding, or an older link)" };
+  }
+  if (read instanceof Error) return { kind: "unknown", reason: `GET /v1/features failed (${read.message})` };
+  if (read.status !== 200) {
+    const code = read.body?.error?.code;
+    return { kind: "unknown", reason: `GET /v1/features \u2192 ${read.status}${code ? ` ${code}` : ""}` };
+  }
+  const keyTenant = read.body?.meta?.tenant_id;
+  if (!knownTenantId(keyTenant)) return { kind: "unknown", reason: "the server named no tenant for this key (meta.tenant_id absent)" };
+  return keyTenant === bindingTenant ? { kind: "match", keyTenant } : { kind: "mismatch", keyTenant, bindingTenant };
+}
+function keyTenantRefusal(v, t) {
+  const relink = `vxil link ${t.slug ?? "<slug>"} --key <key>${t.as ? ` --as ${t.as}` : ""}`;
+  const fix = t.keySource === "VXIL_API_KEY" ? "unset VXIL_API_KEY (it overrides the binding's key) or point it at the bound tenant's key" : `re-link the slot with the right key: \`${relink}\``;
+  return `${t.where} is bound to tenant ${v.bindingTenant} (labelled ${t.envLabel}), but the key from ${t.keySource} belongs to tenant ${v.keyTenant} (GET /v1/features meta.tenant_id) \u2014 nothing was written. The push promotion gate keys on the slot's label, so a key for another tenant here could write to it ungated. Fix: ${fix}; \`vxil doctor\` shows the binding and the key side by side.`;
+}
+function keyTenantCheck(v) {
+  if (v.kind === "match") return { name: "binding tenant = key tenant", ok: true, detail: `the key belongs to the bound tenant ${v.keyTenant}` };
+  if (v.kind === "mismatch") {
+    return {
+      name: "binding tenant = key tenant",
+      ok: false,
+      detail: `the binding names tenant ${v.bindingTenant} but the key belongs to tenant ${v.keyTenant} \u2014 every write verb refuses this target until it is re-linked`
+    };
+  }
+  return { name: "binding tenant = key tenant", ok: true, warn: true, detail: `not verified: ${v.reason}` };
+}
+
+// src/pushOutcome.ts
+function pushExitCode(p, strict) {
+  const lines = [];
+  for (const h of p.hard) lines.push(`push problem: ${h}`);
+  for (const s of p.strict) lines.push(`${strict ? "push problem (--strict)" : "warning"}: ${s}`);
+  const failing = p.hard.length + (strict ? p.strict.length : 0);
+  if (failing > 0) {
+    lines.push(`push applied, but ${failing} problem(s) remain \u2014 exit 1${!strict && p.strict.length ? ` (${p.strict.length} more would fail under --strict)` : ""}`);
+    return { code: 1, lines };
+  }
+  if (p.strict.length) lines.push(`${p.strict.length} warning(s) \u2014 \`vxil push --strict\` turns them into exit 1 for CI`);
+  return { code: 0, lines };
+}
+
 // src/paymentsCmd.ts
 var SIMULATE_SCENARIOS = [
   "refund-pair",
@@ -13855,7 +14691,7 @@ function inferMapping(source, opts = {}) {
   const cmsNames = [...cmsByName.keys()];
   const loadOrder = topoOrder(cmsNames, source.foreignKeys, profile?.table, warnings);
   if (source.authUsers?.present) {
-    residuals.push(source.authUsers.hasPasswordHash ? "passwords: hashes are NOT imported (auth is scrypt-locked; the foreign-hash import is signal-gated, not built) \u2014 users re-auth via magic-link/OTP/social/reset on first sign-in" : "auth: credentials do not transfer \u2014 users re-auth via their existing OTP/magic-link/social flow post-cutover");
+    residuals.push(source.authUsers.hasPasswordHash ? "passwords: hashes are NOT imported by default \u2014 `vxil migrate data --with-password-hashes` carries them (bcrypt, verified and rehashed at each user's first sign-in); without it users re-auth via magic-link/OTP/social/reset on first sign-in" : "auth: credentials do not transfer \u2014 users re-auth via their existing OTP/magic-link/social flow post-cutover");
   }
   for (const chk of source.checks ?? []) {
     if (!cmsByName.has(lastSeg(chk.table))) continue;
@@ -14438,6 +15274,93 @@ async function loadUsers({ deps, adapter, mapping, state, save, delta = false })
   return result;
 }
 
+// src/migrate/loaders/credentials.ts
+var CREDENTIALS_BATCH_MAX = 500;
+var KEY = "users:credentials";
+function credentialEntry(row2, withHashes) {
+  return {
+    id: row2.id,
+    ...withHashes && row2.password_hash ? { password_hash: row2.password_hash } : {},
+    ...row2.email_verified ? { email_verified: true } : {}
+  };
+}
+async function loadCredentials2({ deps, adapter, state, save, opts, delta = false }) {
+  const result = { table: KEY, read: 0, written: 0, skipped: 0, errors: [], cursor: null };
+  if (!adapter.readCredentials) {
+    result.errors.push("credentials: this source has no credential reader (supabase only today) \u2014 post the hashes yourself with the SDK `auth.users.import()`, or drop --with-password-hashes / --oidc-issuer");
+    return result;
+  }
+  const cursors = cursorsFor(state, delta);
+  const sent = hashesFor(state, KEY);
+  if (cursors[KEY] === null) {
+    deps.log(delta ? "credentials: incremental pass already complete for this --since window \u2014 skipping" : `credentials: already complete \u2014 skipping (\`data --since <time>\` re-reads it)`);
+    return result;
+  }
+  const reasons = /* @__PURE__ */ new Map();
+  let withPassword = 0;
+  for await (const batch of adapter.readCredentials(cursors[KEY] ?? void 0)) {
+    const entries = [];
+    const digests = [];
+    for (const row2 of batch.rows) {
+      result.read++;
+      const entry = credentialEntry(row2, opts.withHashes);
+      const h = rowHash({ ...entry, issuer: opts.oidcIssuer ?? null });
+      if (sent[row2.id] === h) {
+        result.skipped++;
+        continue;
+      }
+      if (entry.password_hash) withPassword++;
+      entries.push(entry);
+      digests.push(h);
+    }
+    if (deps.dryRun) continue;
+    for (let i = 0; i < entries.length; i += CREDENTIALS_BATCH_MAX) {
+      const chunk = entries.slice(i, i + CREDENTIALS_BATCH_MAX);
+      const res = await deps.api("POST", "/v1/auth/users/import", {
+        users: chunk,
+        ...opts.oidcIssuer ? { oidc_issuer: opts.oidcIssuer } : {}
+      });
+      if (res.status !== 200 || res.body.error) {
+        const hint = res.body.error?.code === "capability_not_enabled" ? " \u2014 enable auth (with emailPassword) on this project first" : res.body.error?.code === "server_only" || res.body.error?.code === "insufficient_scope" ? " \u2014 run the migration with a SERVER key holding auth:write" : "";
+        result.errors.push(apiErrorLine(`credentials: POST /v1/auth/users/import (${chunk.length} users) failed`, res) + hint + " \u2014 the cursor was NOT advanced; fix and re-run (the import is idempotent)");
+        result.cursor = cursors[KEY] ?? null;
+        return result;
+      }
+      const data2 = res.body.data ?? {};
+      const taken = (data2.results ?? []).filter((r) => r.status === "skipped" && r.reason === "id_taken").length;
+      if (taken > 0) {
+        result.errors.push(`credentials: ${taken} user id(s) already belong to another vxil project in this environment (user ids are unique across projects) \u2014 most often a rehearsal dev backend that imported the same users. Delete it (\`vxil dev down\`) or the project that holds them, then re-run: the cursor was NOT advanced and the import is idempotent. Left as is, those users would get a new id at sign-up and lose their data.`);
+        result.cursor = cursors[KEY] ?? null;
+        return result;
+      }
+      for (const r of data2.results ?? []) {
+        if (r.status === "skipped") {
+          result.skipped++;
+          reasons.set(r.reason ?? "unknown", (reasons.get(r.reason ?? "unknown") ?? 0) + 1);
+        } else {
+          result.written++;
+        }
+      }
+      for (let j = 0; j < chunk.length; j++) sent[chunk[j].id] = digests[i + j];
+    }
+    cursors[KEY] = batch.nextCursor;
+    save();
+    if (batch.nextCursor === null) break;
+  }
+  if (deps.dryRun) {
+    deps.log(`credentials: DRY-RUN \u2014 would import ${result.read - result.skipped} identit(ies)` + (opts.withHashes ? `, ${withPassword} with a password hash` : " (no hashes \u2014 --with-password-hashes not set)") + (opts.oidcIssuer ? ", each linked to the source issuer for the session hand-over" : "") + "; nothing written");
+  } else {
+    cursors[KEY] = null;
+    save();
+  }
+  if (reasons.size > 0) {
+    const list = [...reasons].map(([r, n]) => `${r}=${n}`).join(" ");
+    deps.log(`credentials: ${[...reasons.values()].reduce((a, b2) => a + b2, 0)} user(s) not imported (${list}) \u2014 they sign in once another way (magic link, OTP, a reset); \`not_registered\` means the users step did not load them`);
+  }
+  result.cursor = deps.dryRun ? cursors[KEY] ?? null : null;
+  return result;
+}
+
 // src/migrate/loaders/schema.ts
 function mappingToCollection(m) {
   const fields = {};
@@ -14587,7 +15510,10 @@ function objectOwner(path, filesOwner) {
   const seg = path.split("/").find((s) => s.length > 0);
   return seg;
 }
-async function loadFiles({ deps, plan, adapter, state, save, filesOwner, fetchImpl, delta = false }) {
+var SHARED_LINK_ASK_MS = 100 * 365 * 24 * 3600 * 1e3;
+var SHARED_LINK_WARN_MS = 365 * 24 * 3600 * 1e3;
+var isUrl = (v) => typeof v === "string" && /^https?:\/\//i.test(v);
+async function loadFiles({ deps, plan, adapter, state, save, filesOwner, fetchImpl, delta = false, fileLinks = "object_id" }) {
   const results = [];
   if (plan.storageBuckets.length === 0) return results;
   if (!adapter.readObjects) {
@@ -14629,6 +15555,31 @@ async function loadFiles({ deps, plan, adapter, state, save, filesOwner, fetchIm
   }
   const resolve8 = filesResolver(state);
   const cursors = cursorsFor(state, delta);
+  const links = fileLinks === "shared-link" ? state.idMap["links:files"] ??= {} : null;
+  const publicObject = /* @__PURE__ */ new Set();
+  if (links) {
+    for (const b2 of plan.storageBuckets) {
+      if (b2.public !== true) continue;
+      for (const oid of Object.values(state.idMap[`files:${b2.name}`] ?? {})) publicObject.add(oid);
+    }
+  }
+  let shortLived = null;
+  const sharedLink = async (objectId) => {
+    const hit = links[objectId];
+    if (hit !== void 0) return { url: hit };
+    const res = await deps.api("POST", `/v1/files/${encodeURIComponent(objectId)}/shared-links`, {
+      expires_at: new Date(Date.now() + SHARED_LINK_ASK_MS).toISOString()
+    });
+    const url = res.body.data?.url;
+    if (res.status !== 201 && res.status !== 200 || typeof url !== "string") {
+      const hint = res.body.error?.code === "shared_links_disabled" ? " \u2014 enable features.files.sharedLinks (and raise its maxTtl) before a shared-link run" : "";
+      return { err: apiErrorLine(`files: shared link for ${objectId} failed`, res) + hint };
+    }
+    const exp = Date.parse(String(res.body.data?.expires_at ?? ""));
+    if (Number.isFinite(exp) && exp - Date.now() < SHARED_LINK_WARN_MS) shortLived ??= String(res.body.data?.expires_at);
+    links[objectId] = url;
+    return { url };
+  };
   for (const mapping of plan.tables) {
     if (mapping.target !== "cms" || !mapping.collection) continue;
     const storageFields = mapping.fields.filter((f) => f.storageObject === true);
@@ -14646,6 +15597,7 @@ async function loadFiles({ deps, plan, adapter, state, save, filesOwner, fetchIm
     const pk = sourcePkColumn(mapping);
     const enc2 = encodeURIComponent(mapping.collection);
     let misses = 0;
+    let privateUrls = 0;
     const columns = [pk, ...storageFields.map((f) => f.source)];
     for await (const batch of adapter.readRows(table, cursors[rk] ?? void 0, { columns })) {
       for (const row2 of batch.rows) {
@@ -14662,12 +15614,33 @@ async function loadFiles({ deps, plan, adapter, state, save, filesOwner, fetchIm
           result.skipped++;
           continue;
         }
-        const h = rowHash(patch);
+        const urlValued = links ? storageFields.filter((f) => patch[f.target] !== void 0 && isUrl(row2[f.source])) : [];
+        const urlFields = urlValued.filter((f) => publicObject.has(patch[f.target])).map((f) => f.target);
+        privateUrls += urlValued.length - urlFields.length;
+        const h = rowHash(urlFields.length ? { ...patch, __shared: urlFields } : patch);
         if (linked[sourceId] === h) {
           result.skipped++;
           continue;
         }
         if (deps.dryRun) continue;
+        let linkErr = null;
+        for (const t of urlFields) {
+          const l = await sharedLink(patch[t]);
+          if ("err" in l) {
+            linkErr = l.err;
+            break;
+          }
+          patch[t] = l.url;
+        }
+        if (linkErr) {
+          result.errors.push(linkErr);
+          save();
+          if (result.errors.length >= ROW_FAILURE_CAP) {
+            result.errors.push(`files relink ${table}: ABORTED after ${ROW_FAILURE_CAP} failure(s) \u2014 fix and re-run (the '${rk}' cursor resumes)`);
+            return results;
+          }
+          continue;
+        }
         const res = await deps.api("PATCH", `/v1/cms/items/${enc2}/${encodeURIComponent(itm)}`, { data: patch });
         if (res.status !== 200) {
           result.errors.push(apiErrorLine(`files relink ${table} row '${sourceId}' (item ${itm})`, res));
@@ -14690,6 +15663,13 @@ async function loadFiles({ deps, plan, adapter, state, save, filesOwner, fetchIm
     if (misses > 0) {
       deps.log(`\u26A0 files relink ${table}: ${misses} storage value(s) had no uploaded object match \u2014 left as the raw source value (check bucket coverage)`);
     }
+    if (privateUrls > 0) {
+      deps.log(`\u26A0 files relink ${table}: ${privateUrls} stored URL(s) point at objects of a bucket that is not public \u2014 they became the object id, not a keyless shared link (a private file never becomes public by migration). Set "public": true on a bucket in migrate/plan.json only if its objects really were public.`);
+    }
+    if (shortLived) {
+      deps.log(`\u26A0 files: shared links expire at ${shortLived} (features.files.sharedLinks.maxTtl) \u2014 stored URLs stop working then; raise maxTtl and re-run, or switch the app to object ids`);
+      shortLived = null;
+    }
     if (!deps.dryRun) {
       cursors[rk] = null;
       save();
@@ -15417,6 +16397,16 @@ async function runData(deps, plan, adapter, opts = {}) {
       delta: delta !== void 0
     }));
   }
+  if (opts.credentials && want("credentials")) {
+    results.push(await loadCredentials2({
+      deps: g.deps,
+      adapter,
+      state: g.state,
+      save: g.save,
+      opts: opts.credentials,
+      delta: delta !== void 0
+    }));
+  }
   const cmsByTable = new Map(plan.tables.filter((t) => t.target === "cms").map((t) => [t.table, t]));
   const cmsWanted = plan.loadOrder.filter((t) => cmsByTable.has(t) && want("cms", t));
   if (cmsWanted.length > 0 && !g.state.schemaPushed && opts.assumeSchema !== true) {
@@ -15472,6 +16462,7 @@ async function runData(deps, plan, adapter, opts = {}) {
       save: g.save,
       delta: delta !== void 0,
       ...opts.filesOwner !== void 0 ? { filesOwner: opts.filesOwner } : {},
+      ...opts.fileLinks ? { fileLinks: opts.fileLinks } : {},
       ...putFetch !== void 0 ? { fetchImpl: putFetch } : {}
     }));
   }
@@ -15603,7 +16594,7 @@ ${notes.length ? `${notes.join("\n")}
 `;
 }
 var STANDING_CAVEATS = [
-  "Passwords: never imported (auth is scrypt-locked; the foreign-hash import is signal-gated, not built) \u2014 users re-auth via magic-link/OTP/social/reset on first sign-in.",
+  "Passwords: imported only with `vxil migrate data --with-password-hashes` (supabase sources: bcrypt, verified and replaced at each user's first sign-in \u2014 no forced re-sign-in); without it, or for a hash it cannot accept, users re-auth once via magic-link/OTP/social/reset.",
   "Push device tokens: vxil has no push provider \u2014 token rows migrate as ordinary owner-scoped cms app data, and sending is a function over egress (the push-notifications blueprint); or skip those tables and let clients re-enroll post-cutover.",
   "Subscriptions / entitlements / tier: NEVER seeded (provider-derived truth) \u2014 rebuild from your live provider webhooks after cutover.",
   "DB triggers / RPCs / pg_cron / row-level access rules: not auto-migrated \u2014 hand-wire as vxil functions (cms-hook/cron/http triggers; cms-hooks are async post-commit, never in-transaction) + per-collection ownerField.",
@@ -15652,7 +16643,7 @@ function formatPlanSummary(plan) {
     out.push(`  vector-search: ${v.table}.${v.column} (${v.dimensions}d) \u2192 '${v.collection}' (text: ${v.textFields.join(", ") || "NONE \u2014 set textFields"})`);
   }
   if (plan.storageBuckets.length) {
-    out.push(`  storage buckets: ${plan.storageBuckets.map((b2) => `${b2.name}${b2.objectCount !== void 0 ? ` (${b2.objectCount})` : ""}`).join(", ")}`);
+    out.push(`  storage buckets: ${plan.storageBuckets.map((b2) => `${b2.name}${b2.objectCount !== void 0 ? ` (${b2.objectCount})` : ""}${b2.public === true ? " [public]" : ""}`).join(", ")}`);
   }
   return out.join("\n");
 }
@@ -15738,7 +16729,7 @@ async function runMigrateSchema(io, opts = {}) {
   if (!apply) io.log("\n(dry-run \u2014 re-run with --apply to create the collections)");
   return result;
 }
-var DATA_STEPS = /* @__PURE__ */ new Set(["users", "cms", "vectors", "files", "payments"]);
+var DATA_STEPS = /* @__PURE__ */ new Set(["users", "credentials", "cms", "vectors", "files", "payments"]);
 async function runMigrateData(io, opts = {}) {
   const plan = readPlanFile(io.cwd);
   const p = migratePaths(io.cwd);
@@ -15750,6 +16741,10 @@ async function runMigrateData(io, opts = {}) {
     throw new Error("--prune deletes only during an incremental pass \u2014 add --since <time>");
   }
   const since = opts.since !== void 0 ? new Date(Date.parse(opts.since)).toISOString() : void 0;
+  if (opts.oidcIssuer !== void 0 && !/^https:\/\/[^\s?#]+$/.test(opts.oidcIssuer)) {
+    throw new Error(`--oidc-issuer '${opts.oidcIssuer}' must be an https URL with no query or fragment (Supabase: https://<ref>.supabase.co/auth/v1)`);
+  }
+  const credentials = opts.withPasswordHashes || opts.oidcIssuer !== void 0 ? { withHashes: opts.withPasswordHashes === true, ...opts.oidcIssuer !== void 0 ? { oidcIssuer: opts.oidcIssuer } : {} } : void 0;
   const tableNames = new Set(plan.tables.map((t) => t.table));
   for (const o of opts.only ?? []) {
     if (!DATA_STEPS.has(o) && !tableNames.has(o)) {
@@ -15776,7 +16771,9 @@ async function runMigrateData(io, opts = {}) {
     ...opts.fetchImpl !== void 0 ? { fetchImpl: opts.fetchImpl } : {},
     ...since !== void 0 ? { since } : {},
     ...opts.prune ? { prune: true } : {},
-    ...specs ? { payments: specs } : {}
+    ...specs ? { payments: specs } : {},
+    ...credentials ? { credentials } : {},
+    ...opts.fileLinks ? { fileLinks: opts.fileLinks } : {}
   });
   io.log(`${execute ? "\nmigrate data" : "\nmigrate data (DRY-RUN \u2014 zero writes)"}${since ? ` \u2014 incremental since ${since}${opts.prune ? " + prune" : ""}` : ""}:`);
   for (const r of results) io.log(formatLoadResult(r));
@@ -16502,7 +17499,7 @@ export default defineConfig({
     "functions": {
       "ask-journal.ts": "// ask-journal.ts \u2014 \"ASK YOUR JOURNAL\" (a vxil function, \xA77.3).\n//\n// Trigger: http \u2014 POST /v1/fn/ask-journal { question, user_id? }. Runs ONE\n// retrieval-augmented call: POST /v1/rag/answer over the `journal` index the\n// on-entry-written function keeps fed. rag retrieves top-k chunks from\n// vector-search, grounds the tenant-owned prompt, generates via the ai feature,\n// and returns the answer WITH citations pointing at the exact entries used \u2014\n// this function is a thin, scoped wrapper (rag:write only).\n//\n// In end-user mode the verified principal is propagated automatically into the\n// scoped token, so retrieval is owner-scoped; in server mode an optional\n// `user_id` rides along for per-user metering.\n\nimport type { HttpFunctionEnvelope } from '@vxil/sdk';\n\n// the caller's JSON body rides the invocation envelope under `payload`\ntype Env = HttpFunctionEnvelope<{ question?: string; user_id?: string }>;\ninterface Citation { chunk_id?: string; doc_id?: string; score?: number }\ninterface AnswerRes { data?: { answer?: string; citations?: Citation[]; usage?: Record<string, unknown> } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const rag = env.scoped_jwts?.rag;\n    if (!rag) return json({ error: 'missing rag scope' }, 403);\n\n    const question = String(env.payload?.question ?? '').trim();\n    if (!question) return json({ error: 'question required', example: { question: 'what made me happy last month?' } }, 400);\n\n    const res = await fetch(`${base}/v1/rag/answer`, {\n      method: 'POST',\n      headers: { authorization: `Bearer ${rag}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        query: question.slice(0, 2000),\n        collection: 'journal', // = rag config defaultCollection; explicit for clarity\n        ...(env.payload?.user_id ? { user_id: env.payload.user_id } : {}),\n      }),\n    });\n    if (!res.ok) {\n      // A missing index is NOT a 404 here: rag's retrieve leg wraps a\n      // vector-search failure as 502 retrieval_failed and attaches the\n      // downstream error under error.upstream (only a 501 passes through),\n      // so detect collection_not_found in the BODY, not the status. The\n      // index is a one-time setup (see the template README).\n      const errBody = (await res.json().catch(() => null)) as\n        { error?: { code?: string; upstream?: { code?: string } } } | null;\n      const code = errBody?.error?.upstream?.code ?? errBody?.error?.code;\n      if (res.status === 404 || code === 'collection_not_found') {\n        return json({ error: 'journal index not found', hint: 'POST /v1/search/collections {\"collection\":\"journal\"} once, then write an entry' }, 404);\n      }\n      return json({ error: 'answer_failed', status: res.status }, 502);\n    }\n\n    const body = (await res.json()) as AnswerRes;\n    return json({\n      answer: body.data?.answer ?? '',\n      // provenance: which entries grounded the answer (doc_id = the entry's item_id)\n      sources: (body.data?.citations ?? []).map((c) => ({ entry_id: c.doc_id, score: c.score })),\n    }, 200);\n  },\n};\n\n// \u2500\u2500 tiny helper \u2500\u2500\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n",
       "on-entry-written.ts": "// on-entry-written.ts \u2014 AI ENRICHMENT ON WRITE (a vxil function, \xA77.3).\n//\n// Trigger: cmsHook \u2014 fires on cms.item.* for `entries`. The hook payload is\n// { event, collection, item_id } \u2014 NOT the row \u2014 so the function RE-FETCHES the\n// entry by id (through the edge, tenant-scoped), then:\n//   1. asks the ai feature (POST /v1/ai/generate, raw-prompt mode) for a\n//      ONE-sentence summary and a ONE-word mood,\n//   2. PATCHes them back onto the entry (merge-patch; the summary-present LATCH\n//      keeps our own write-back from re-enriching \u2014 clear `summary` to redo),\n//   3. ingests title+body into the rag retrieval index (POST /v1/rag/ingest/\n//      journal \u2014 the vector-search passthrough) so ask-journal can ground on it.\n// At-least-once delivery is safe to redeliver: the summary latch skips a\n// re-enrich, the PATCH is idempotent by content, and the ingest converges \u2014\n// vector-search upserts by doc_id, so re-ingesting the same entry re-indexes\n// in place rather than duplicating.\n\nimport type { CmsHookFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CmsHookFunctionEnvelope;\ninterface EntryData { title?: string; body?: string; summary?: string; mood?: string; written_at?: string; user_id?: string }\ninterface Item { data?: { data?: EntryData } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const ai = env.scoped_jwts?.ai;\n    const rag = env.scoped_jwts?.rag;\n    const itemId = env.payload?.item_id;\n    // The platform now filters cms-hook deliveries on the binding's collection/event\n    // server-side (functions.md \xA73); this guard stays as belt-and-braces.\n    if (env.payload?.collection !== 'entries' || !cms || !ai || !rag || !itemId) {\n      return Response.json({ skipped: true });\n    }\n\n    // Re-fetch the entry (the payload carries only the id \u2014 never trust inline fields).\n    const res = await fetch(`${base}/v1/cms/items/entries/${itemId}`, { headers: H(cms) });\n    if (!res.ok) return Response.json({ skipped: true, reason: `fetch ${res.status}` });\n    const entry = ((await res.json()) as Item).data?.data ?? {};\n    if (entry.summary) return Response.json({ skipped: true, reason: 'already enriched' });\n    if (!entry.body) return Response.json({ skipped: true, reason: 'no body yet' });\n\n    // 1. AI enrichment \u2014 two small raw-prompt generations ({ data: { text } }).\n    const text = entry.body.slice(0, 6000);\n    const summary = clip(await generate(base, ai,\n      `Summarize this journal entry in exactly one sentence, first person:\\n\\n${text}`, 80, entry.user_id), 400);\n    const moodRaw = await generate(base, ai,\n      `Answer with ONE lowercase word (e.g. joyful, anxious, calm, tired) naming the dominant mood of this journal entry:\\n\\n${text}`, 8, entry.user_id);\n    const mood = (moodRaw.trim().split(/\\s+/)[0] ?? '').toLowerCase().replace(/[^a-z-]/g, '').slice(0, 24);\n    if (!summary) return Response.json({ skipped: true, reason: 'ai unavailable' });\n\n    // 2. PATCH the derived fields back (merge-patch keys; bumps `version`).\n    const patch = await fetch(`${base}/v1/cms/items/entries/${itemId}`, {\n      method: 'PATCH',\n      headers: H(cms),\n      body: JSON.stringify({ data: { summary, ...(mood ? { mood } : {}) } }),\n    });\n\n    // 3. Ingest into the retrieval index (rag \u2192 vector-search passthrough, 202).\n    // Idempotent by doc_id: vector-search UPSERTs on (collection, doc_id), so a\n    // redelivered hook (or an edited entry) re-indexes in place.\n    const ing = await fetch(`${base}/v1/rag/ingest/journal`, {\n      method: 'POST',\n      headers: H(rag),\n      body: JSON.stringify({\n        doc_id: itemId,\n        ...(entry.user_id ? { user_id: entry.user_id } : {}),\n        text: `${entry.title ?? ''}\\n\\n${entry.body}`,\n        metadata: { ...(mood ? { mood } : {}), ...(entry.written_at ? { written_at: entry.written_at } : {}) },\n      }),\n    });\n    return Response.json({\n      enriched: patch.ok,\n      mood,\n      ingested: ing.ok,\n      // the index is a one-time setup: POST /v1/search/collections {\"collection\":\"journal\"}\n      ...(ing.status === 404 ? { hint: 'create the journal index first (see the template README)' } : {}),\n    });\n  },\n};\n\n// \u2500\u2500 tiny helpers \u2500\u2500\nconst H = (jwt: string) => ({ authorization: `Bearer ${jwt}`, 'content-type': 'application/json' });\n/** One raw-prompt sync generation; '' on any failure (enrichment is best-effort). */\nasync function generate(base: string, jwt: string, prompt: string, maxTokens: number, userId?: string): Promise<string> {\n  const r = await fetch(`${base}/v1/ai/generate`, {\n    method: 'POST',\n    headers: H(jwt),\n    body: JSON.stringify({ prompt, max_tokens: maxTokens, ...(userId ? { user_id: userId } : {}) }),\n  }).catch(() => null);\n  if (!r || !r.ok) return '';\n  return String(((await r.json()) as { data?: { text?: string } }).data?.text ?? '');\n}\nconst clip = (s: string, n: number) => (s.length > n ? s.slice(0, n - 1) + '\u2026' : s);\n",
-      "weekly-digest.ts": "// weekly-digest.ts \u2014 THE WEEKLY DIGEST (a vxil function, \xA77.3).\n//\n// Trigger: cron ('0 8 * * 1' \u2014 Mondays 08:00 UTC, delivered via the jobs\n// schedule the control-plane reconciles per cron binding). Lists the last 7\n// days of entries (written_at rides the t1 index slot, so the $gte range +\n// sort=-written_at are index-served), groups them per writer, and sends each\n// writer ONE notifications digest ({ subject, paragraph } on the built-in\n// 'transactional' template).\n//\n// Delivery notes: notifications resolves user_id against your end users \u2014 a\n// writer with no email fails that ONE send (user_email_missing) and the loop\n// continues. The per-user Idempotency-Key (envelope key + user id) makes the\n// at-least-once cron redelivery never double-send.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CronFunctionEnvelope;\ninterface EntryData { title?: string; mood?: string; user_id?: string; written_at?: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    if (!cms || !notif) return Response.json({ skipped: true, reason: 'missing cms/notifications scope' });\n\n    // 1. the week's entries, newest first (t1-slotted range + sort).\n    const since = new Date(Date.now() - 7 * 24 * 3600 * 1000).toISOString();\n    const filter = encodeURIComponent(JSON.stringify({ written_at: { $gte: since } }));\n    const res = await fetch(`${base}/v1/cms/items/entries?filter=${filter}&sort=-written_at&limit=100`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!res.ok) return Response.json({ skipped: true, reason: `list ${res.status}` });\n    const body = (await res.json()) as { data?: { items?: { id: string; data: EntryData }[] } };\n    const items = body.data?.items ?? [];\n\n    // 2. group per writer.\n    const byUser = new Map<string, EntryData[]>();\n    for (const it of items) {\n      const uid = it.data.user_id;\n      if (!uid) continue;\n      const list = byUser.get(uid) ?? [];\n      list.push(it.data);\n      byUser.set(uid, list);\n    }\n\n    // 3. one digest send per writer (best-effort per user; the loop never aborts).\n    let sent = 0;\n    for (const [uid, entries] of byUser) {\n      const lines = entries\n        .slice(0, 10)\n        .map((e) => `\u2022 ${e.title ?? 'Untitled'}${e.mood ? ` (${e.mood})` : ''}`)\n        .join('\\n');\n      const ok = await fetch(`${base}/v1/notifications/send`, {\n        method: 'POST',\n        headers: {\n          authorization: `Bearer ${notif}`,\n          'content-type': 'application/json',\n          'idempotency-key': `${env.idempotency_key ?? 'weekly-digest'}:${uid}`,\n        },\n        body: JSON.stringify({\n          user_id: uid,\n          template: 'transactional',\n          data: {\n            subject: `Your journal week \u2014 ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`,\n            paragraph: `You wrote ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'} this week:\\n${lines}`,\n          },\n        }),\n      }).then((r) => r.ok).catch(() => false);\n      if (ok) sent += 1;\n    }\n\n    return Response.json({ entries: items.length, writers: byUser.size, sent });\n  },\n};\n"
+      "weekly-digest.ts": "// weekly-digest.ts \u2014 THE WEEKLY DIGEST (a vxil function, \xA77.3).\n//\n// Trigger: cron ('0 8 * * 1' \u2014 Mondays 08:00 UTC, delivered via the jobs\n// schedule the control-plane reconciles per cron binding). Lists the last 7\n// days of entries (written_at rides the t1 index slot, so the $gte range is\n// index-served) \u2014 ALL of them, page by page, up to MAX_PAGES (a bigger week is\n// reported `truncated: true` rather than silently dropping writers) \u2014 groups\n// them per writer, and sends each writer ONE notifications digest\n// ({ subject, paragraph } on the built-in 'transactional' template).\n//\n// Delivery notes: notifications resolves user_id against your end users \u2014 a\n// writer with no email fails that ONE send (user_email_missing) and the loop\n// continues. The per-user Idempotency-Key (envelope key + user id) makes the\n// at-least-once cron redelivery never double-send.\n\n// cron-walk: complete-per-tick \u2014 the week is read to its end each Monday (next_cursor), under MAX_PAGES.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CronFunctionEnvelope;\n/** Pages of 100 entries read per run \u2014 5,000 entries a week. */\nconst MAX_PAGES = 50;\n\ninterface EntryData { title?: string; mood?: string; user_id?: string; written_at?: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    if (!cms || !notif) return Response.json({ skipped: true, reason: 'missing cms/notifications scope' });\n\n    // 1. the week's entries \u2014 every page, not just the first 100 (t1-slotted\n    //    range; the default order pages with a plain item-id cursor).\n    const since = new Date(Date.now() - 7 * 24 * 3600 * 1000).toISOString();\n    const filter = encodeURIComponent(JSON.stringify({ written_at: { $gte: since } }));\n    const items: { item_id: string; data: EntryData }[] = [];\n    let cursor: string | null = null;\n    let truncated = false;\n    for (let page = 0; ; page++) {\n      if (page >= MAX_PAGES) { truncated = true; break; }\n      const res = await fetch(`${base}/v1/cms/items/entries?filter=${filter}&limit=100`\n        + (cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''), {\n        headers: { authorization: `Bearer ${cms}` },\n      });\n      if (!res.ok) return Response.json({ skipped: true, reason: `list ${res.status}` });\n      const body = (await res.json()) as { data?: { items?: { item_id: string; data: EntryData }[]; next_cursor?: string | null } };\n      items.push(...(body.data?.items ?? []));\n      cursor = body.data?.next_cursor ?? null;\n      if (!cursor) break;\n    }\n\n    // 2. group per writer.\n    const byUser = new Map<string, EntryData[]>();\n    for (const it of items) {\n      const uid = it.data.user_id;\n      if (!uid) continue;\n      const list = byUser.get(uid) ?? [];\n      list.push(it.data);\n      byUser.set(uid, list);\n    }\n\n    // 3. one digest send per writer (best-effort per user; the loop never aborts).\n    let sent = 0;\n    for (const [uid, entries] of byUser) {\n      const lines = entries\n        .slice(0, 10)\n        .map((e) => `\u2022 ${e.title ?? 'Untitled'}${e.mood ? ` (${e.mood})` : ''}`)\n        .join('\\n');\n      const ok = await fetch(`${base}/v1/notifications/send`, {\n        method: 'POST',\n        headers: {\n          authorization: `Bearer ${notif}`,\n          'content-type': 'application/json',\n          'idempotency-key': `${env.idempotency_key ?? 'weekly-digest'}:${uid}`,\n        },\n        body: JSON.stringify({\n          user_id: uid,\n          template: 'transactional',\n          data: {\n            subject: `Your journal week \u2014 ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'}`,\n            paragraph: `You wrote ${entries.length} ${entries.length === 1 ? 'entry' : 'entries'} this week:\\n${lines}`,\n          },\n        }),\n      }).then((r) => r.ok).catch(() => false);\n      if (ok) sent += 1;\n    }\n\n    return Response.json({ entries: items.length, writers: byUser.size, sent, truncated });\n  },\n};\n"
     }
   },
   {
@@ -16536,6 +17533,30 @@ export default defineConfig({
       "triage-ticket.ts": "// triage-ticket.ts \u2014 CLASSIFY EVERY NEW TICKET (a vxil function).\n//\n// Trigger: cmsHook on `tickets`. A hook delivery carries ids, not the row\n// ({ event, collection, item_id }), so the function RE-FETCHES the ticket\n// rather than trusting inline fields \u2014 and delivery is at-least-once, so it\n// skips a ticket that already carries a category instead of re-billing a model\n// call on a redelivery.\n//\n// The one model call is a FORCED-LABEL verdict: `POST /v1/ai/classify` takes the\n// label set and returns exactly one of them (plus a confidence and a one-line\n// rationale). That is the difference between a classifier and a chat prompt \u2014\n// the answer cannot be a paragraph, a new label, or an apology.\n\nimport type { CmsHookFunctionEnvelope } from '@vxil/sdk';\n\nconst LABELS = ['billing', 'bug', 'how_to', 'other'];\n\ntype Env = CmsHookFunctionEnvelope;\ninterface TicketData { subject?: string; body?: string; category?: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const ai = env.scoped_jwts?.ai;\n    const itemId = env.payload?.item_id;\n    // The platform now filters cms-hook deliveries on the binding's collection/event\n    // server-side (functions.md \xA73); this guard stays as belt-and-braces.\n    if (!cms || !ai || !itemId || env.payload?.collection !== 'tickets') {\n      return Response.json({ skipped: true, reason: 'not a tickets hook' });\n    }\n    // The cms.item.* subscription also delivers updates \u2014 only triage a create.\n    if (!String(env.payload?.event ?? '').endsWith('.created')) {\n      return Response.json({ skipped: true, event: env.payload?.event });\n    }\n\n    const read = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!read.ok) return Response.json({ skipped: true, reason: `fetch ${read.status}` });\n    const ticket = ((await read.json()) as { data?: { data?: TicketData } }).data?.data ?? {};\n    // Already triaged \u21D2 this is a redelivery. Do nothing (and pay for nothing).\n    if (ticket.category) {\n      return Response.json({ skipped: true, reason: 'already triaged', category: ticket.category });\n    }\n\n    const input = `${ticket.subject ?? ''}\\n\\n${ticket.body ?? ''}`.trim();\n    if (!input) return Response.json({ skipped: true, reason: 'empty ticket' });\n\n    const verdict = await fetch(`${base}/v1/ai/classify`, {\n      method: 'POST',\n      headers: { authorization: `Bearer ${ai}`, 'content-type': 'application/json' },\n      body: JSON.stringify({\n        input,\n        labels: LABELS,\n        rubric:\n          'billing = money, invoices, refunds or subscriptions. '\n          + 'bug = something is broken or behaves incorrectly. '\n          + 'how_to = the customer is asking how to do something. '\n          + 'other = anything else.',\n      }),\n    });\n    if (!verdict.ok) {\n      const detail = await verdict.text();\n      return Response.json(\n        { error: 'classify_failed', status: verdict.status, detail: detail.slice(0, 300) },\n        { status: 502 },\n      );\n    }\n    const v = ((await verdict.json()) as {\n      data?: { label?: string; confidence?: number; rationale?: string };\n    }).data ?? {};\n    const label = LABELS.includes(String(v.label)) ? String(v.label) : 'other';\n\n    const patch = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      method: 'PATCH',\n      headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n      body: JSON.stringify({ data: { category: label, state: 'open' } }),\n    });\n\n    return Response.json({\n      item_id: itemId,\n      category: label,\n      confidence: v.confidence ?? null,\n      rationale: v.rationale ?? null,\n      written: patch.ok,\n    });\n  },\n};\n"
     }
   },
+  {
+    "id": "fal-media",
+    "title": "AI Media Studio (fal.ai images \xB7 Veo video \xB7 credits)",
+    "vertical": "ai",
+    "summary": "Generate images and Veo video through fal.ai's queue API with NO vendor adapter \u2014 the generation lane's generic completion options carry fal's webhook in the query string, read its OK/ERROR words and settle on the image list or the video \u2014 while the credits for each render are held up front and refunded automatically when fal fails.",
+    "collections": [
+      "renders"
+    ],
+    "features": [
+      "jobs",
+      "payments",
+      "cms",
+      "functions"
+    ],
+    "hasFunctions": true,
+    "byoKeys": [
+      "fal_key"
+    ],
+    "configSrc": "import { defineConfig } from '@vxil/config';\n\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// \"AI Media Studio\" \u2014 images and video from fal.ai, with credits that cannot\n// leak. One function starts a render; vxil does the rest:\n//\n//   start-render (your function, end-user mode)\n//     \u2192 writes a `renders` row the user owns\n//     \u2192 POST /v1/jobs/generation: a fal QUEUE job, credits HELD for it\n//   vxil's generation lane\n//     \u2192 calls fal with your key, the signed callback in `?fal_webhook=`\n//     \u2192 fal POSTs back `{ status: 'OK' | 'ERROR', payload }`\n//     \u2192 status_map reads OK/ERROR, result_path picks the images / the video\n//     \u2192 the `renders` row gets generation_status + result\n//     \u2192 credits COMMIT on success, REFUND on failure or timeout\n//\n// No fal adapter exists in vxil and none is needed: the three generic options\n// (`completion.callback.query_param`, `completion.status_map`,\n// `completion.result_path`) describe any \"POST the job, we call your webhook\"\n// vendor. The platform owns the part a function cannot \u2014 the held credits,\n// the timeout and the refund.\n//\n// The credits half is a payments INTEGRATION on the deterministic `mock`\n// provider \u2014 no provider account needed to try it. \"Credits\" are usage units,\n// not money; vxil is never in the flow of funds.\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nexport default defineConfig({\n  env: 'staging',\n\n  features: {\n    jobs: {\n      enabled: true,\n      generation: {\n        maxConcurrent: 10,\n        // fal images finish in seconds, an 8 s Veo clip in a few minutes \u2014\n        // a run fal never calls back about fails (and refunds) at 15 minutes\n        defaultTimeoutMs: 900_000,\n        maxTimeoutMs: 1_800_000,\n        pollMaxAttempts: 30,\n        // a video costs 10 credits; one run may never hold more than 20\n        maxReserveCredits: 20,\n        // \u2026nor may all of this project's in-flight renders together hold more than 2,000\n        maxOutstandingReserveCredits: 2_000,\n      },\n    },\n\n    payments: {\n      enabled: true,\n      provider: 'mock',\n      defaults: { currency: 'usd' },\n      ledger: {\n        productMap: {\n          media_pack_100: { creditType: 'media_credits', amount: 100, period: 'once' },\n        },\n        // subscription tiers: a monthly top-up for subscribers\n        tierMap: {\n          studio: {\n            entitlements: ['render'],\n            quotas: {},\n            rank: 10,\n            grants: [{ creditType: 'media_credits', amount: 300, period: 'monthly' }],\n          },\n        },\n        // a render that fails or times out gives its held credits back\n        autoRefundOnJobFailure: true,\n      },\n    },\n\n    cms: {\n      // a render row is live the moment it is written\n      draftPublish: false,\n      // in end-user mode a collection with no owner is server-only \u2014 renders\n      // declares one, so a signed-in user sees only their own renders\n      strictEndUserScope: true,\n      // Lane-A hook (cms.md \xA77): the dedupe key IS owner + ':' + request_key,\n      // server-enforced \u2014 so one user's request_key can never collide with, or\n      // block, another user's (a body naming another owner is a 400 anyway).\n      hooks: {\n        render_dedupe_key: {\n          collection: 'renders',\n          event: 'beforeWrite',\n          kind: 'validate',\n          expr: \"item.dedupe_key == concat(item.owner, ':', item.request_key)\",\n          message: \"dedupe_key must be owner + ':' + request_key\",\n        },\n      },\n    },\n    functions: { enabled: true },\n  },\n\n  cms: {\n    collections: {\n      renders: {\n        singular: 'render',\n        ownerField: 'owner',\n        fields: {\n          // THE DEDUPE ANCHOR \u2014 owner + ':' + the client's own request_key\n          // (the hook above enforces the composition), so the key is per user.\n          // A retried start (a double tap, a timeout) hits 409 instead of\n          // paying twice, and start-render re-drives a start that never got\n          // its run.\n          dedupe_key: { type: 'string', required: true, unique: true, indexSlot: 's1' },\n          request_key: { type: 'string', required: true },\n          owner: { type: 'string', indexSlot: 's2' },\n          kind: { type: 'string', required: true, indexSlot: 's3', validation: { enum: ['image', 'video'] } },\n          // written by vxil's status mirror: pending \u2192 processing \u2192 completed | failed\n          generation_status: { type: 'string', indexSlot: 's4' },\n          credits: { type: 'int', indexSlot: 'n1' },\n          created_at: { type: 'datetime', indexSlot: 't1' },\n          prompt: { type: 'text', required: true },\n          run_id: { type: 'text' },\n          // written by vxil's status mirror on completion: the value at\n          // `result_path` \u2014 fal's `images` list, or its `video` object\n          result: { type: 'json' },\n        },\n      },\n    },\n  },\n\n  functions: {\n    // Starts ONE render for the signed-in user. Invoke it in END-USER mode (with\n    // the user's session): the held credits are forced onto that user, and the\n    // row is theirs.\n    'start-render': {\n      entry: './functions/start-render.ts',\n      trigger: { kind: 'http' },\n      scopes: ['cms:read', 'cms:write', 'jobs:write'],\n      // your fal API key; it rides the provider call's Authorization header\n      secrets: ['secret:fal_key'],\n      // the function itself never calls fal \u2014 vxil's generation lane does\n      egressAllow: [],\n      // `vxil gen` types vx.fn['start-render'] from this\n      signature: {\n        input: { kind: 'string', prompt: 'string', request_key: 'string' },\n        output:\n          '{ item_id: string; run_id: string; credits: number }'\n          + ' | { duplicate: true; request_key: string; item_id: string; run_id: string | null; generation_status: string }',\n      },\n    },\n  },\n\n  secrets: {\n    fal_key: {\n      feature: 'functions',\n      description: 'your fal.ai API key (the \"Key \u2026\" credential) \u2014 vxil never holds a fal account of its own',\n    },\n  },\n});\n",
+    "readme": "# AI Media Studio \u2014 fal.ai images and Veo video, with credits that cannot leak\n\n```bash\nvxil init my-studio --template fal-media\ncd my-studio\nprintf '%s' \"$FAL_KEY\" | vxil secrets set functions/fal_key\nvxil push\n```\n\nOne function starts a render; vxil carries it to the end. You bring a fal.ai key; vxil holds the\nuser's credits while fal works, writes the image or the video onto the user's `renders` row when\nfal calls back, and gives the credits back when fal fails or never answers.\n\n**What this blueprint teaches that the others do not:** a third-party *queue* API \u2014 \"POST the job,\nwe call your webhook\" \u2014 completed through the generation lane's **generic completion options**,\nwith no vendor adapter in vxil and no long call held open in a function:\n\n| option | what it does | fal's case |\n|---|---|---|\n| `completion.callback.query_param` | puts vxil's signed callback URL in the provider URL's query string, and sends `provider.body` exactly as written | fal reads its webhook from `?fal_webhook=` and the model input from the body |\n| `completion.status_map` | up to 8 of the provider's own status words \u2192 `completed` \xB7 `failed` \xB7 `processing` | fal's webhook says `OK` or `ERROR` \u2014 words vxil's built-in list would read as \"still working\" until the run timed out |\n| `completion.result_path` | the value the run settles with, written to your record as `result` | `payload.images` (a list of `{ url, width, height, \u2026 }`) or `payload.video` (`{ url, \u2026 }`) |\n\nThe same three options fit any vendor that calls you back (a transcode API, a render farm, a\nlong-running inference host) \u2014 change the URL, the words and the path.\n\n## What you get\n\n- **`renders`** \u2014 one row per request, owned by the user who started it (`strictEndUserScope`, so a\n  signed-in user reads only their own renders). `dedupe_key` (the owner + `:` + the client's\n  `request_key`, the composition enforced by a `beforeWrite` hook) is unique, so keys are **per user**: a\n  double tap or a retried start is a `409` the function reads back. A row that already has its run is a\n  duplicate; a row with no run (the first start died, or lost its enqueue answer, between the row and\n  the enqueue) is **re-driven** \u2014 the same `dedupe_key` is the generation run's `idempotency_key`, so\n  jobs hands back the existing run and fal is never asked twice.\n- **`start-render`** (http function, end-user mode) \u2014 writes the row, then enqueues ONE generation run:\n  fal's queue URL, your key in `Authorization: Key \u2026`, the three options above, a status mirror onto\n  the row, and `reserve_credits` for the render's cost (image 1, video 10 `media_credits`).\n- **credits** \u2014 a payments integration on the `mock` provider (no provider account needed). The hold is\n  taken *before* the run is queued; a user without the credits gets `402` at once and nothing is held.\n  Success commits the hold; a fal `ERROR`, a run fal never calls back about (the timeout: 5 min for an\n  image, 15 for a video) or a cancel refunds it (`ledger.autoRefundOnJobFailure`).\n\n## Run it\n\nGive a user some credits from your server (or sell `media_pack_100` through your payments provider):\n\n```bash\ncurl -s -X POST \"https://api.vxil.com/v1/payments/credits/grant\" \\\n  -H \"authorization: Bearer $KEY\" -H 'content-type: application/json' \\\n  -H 'idempotency-key: welcome-u1' \\\n  -d '{\"user_id\":\"<the user id>\",\"credit_type\":\"media_credits\",\"amount\":25,\"source\":\"welcome\"}'\n```\n\nStart a render **with the user's session** (end-user mode \u2014 the held credits are forced onto that\nuser, and a function cannot hold credits for anyone else):\n\n```ts\nimport { Vxil } from '@vxil/sdk';\n\n// after `vxil gen`, vx.fn['start-render'] is typed from the function's declared signature\nconst vx = new Vxil({ apiKey: process.env.VXIL_PUBLISHABLE_KEY!, endUserToken: process.env.USER_SESSION! });\nconst started = await vx.fn['start-render']({ kind: 'image', prompt: 'a red fox in the snow', request_key: 'fox-1' });\n// \u2192 { item_id, run_id, credits: 1 }\n//   (or { duplicate: true, request_key, item_id, run_id, generation_status } on a retry)\n```\n\nThen read the row \u2014 or subscribe to its changes \u2014 until `generation_status` is `completed`:\n\n```ts\nif ('item_id' in started) {\n  const row = await vx.from('renders').get(started.item_id);\n  // row.generation_status \u2192 'completed'\n  // row.result \u2192 [{ url: 'https://fal.media/files/\u2026png', width: 1024, height: 1024, \u2026 }]\n}\n```\n\nEvery run ends with `job.generation.completed` or `job.generation.failed` (`generation_id` = the row's\n`item_id`, `correlation_id` = its `request_key`), so a function bound to `job.generation.` can react \u2014\nsend a push, thumbnail the image \u2014 without a lookup table of its own.\n\n## How it fails, and what the user sees\n\n| what happened | the run | the row | the credits |\n|---|---|---|---|\n| fal answered `OK` | `completed` | `generation_status: completed`, `result` set | committed |\n| fal answered `ERROR` (its `error` text is the run's `last_error_msg`; `job.generation.failed` carries `error_class: 'ProviderFailed'`) | `failed` | `generation_status: failed` | refunded |\n| fal never called back | `failed` (`GenerationExpired`) at the timeout | `failed` | refunded |\n| the start call to fal failed with a 5xx / network fault | retried with backoff; terminal after the attempts | `processing` \u2192 the outcome above | held until then |\n| the user had too few credits | ended at once (`ReserveInsufficient`), never queued | `failed` (the function marks it); that `request_key` is spent \u2014 retry after a top-up with a new one | nothing held |\n| too many renders in flight, or a jobs-side fault | not created (the function answers the caller `429` with the wait in `retry_after`, or `502`) | `pending`, no run \u2014 calling start-render again with the **same** `request_key` re-drives it | nothing held |\n\n## Evidence\n\n- **Executed** (vxil's own int tests, `workers/jobs-v1/src/generation-completion-options.int.test.ts`):\n  the `?fal_webhook=` callback URL is signed and verifies, the provider receives exactly the model input,\n  `OK` settles completed with `payload.images` mirrored as `result` and the hold committed, `ERROR`\n  settles failed with the hold refunded, a progress ping stays processing.\n- **Read in fal's documentation, not executed against fal from vxil** \u2014 the queue base\n  `https://queue.fal.run/<model>`, the `fal_webhook` query parameter, the webhook body\n  `{ request_id, status: 'OK' | 'ERROR', payload, error }`, and the model ids `fal-ai/flux/dev` and\n  `fal-ai/veo3` with their inputs. Check the model page for each model's exact input fields before you\n  ship, and keep `num_images` / `duration` to what your model accepts.\n\n## Your key, and where it lives\n\n`fal_key` is a function secret; `start-render` reads it at invoke time and puts it in the generation\nrun's provider headers, which vxil stores with the run (your project only) for as long as the jobs\nretention keeps the run, and sends to fal on the start call. It is **never returned by a read**:\n`GET /v1/jobs/runs/{run_id}` (and the dashboard and MCP reads built on it) shows the header names of a\ngeneration run with every value as `[redacted]`. Rotate it with `vxil secrets set functions/fal_key`;\nruns already queued keep the key they were started with.\n",
+    "functions": {
+      "start-render.ts": "// start-render.ts \u2014 start ONE fal.ai render for the signed-in user (a vxil\n// function, http trigger, END-USER mode).\n//\n//   POST /v1/fn/start-render   (with the user's session)\n//   { \"kind\": \"image\" | \"video\", \"prompt\": \"\u2026\", \"request_key\": \"<your idempotency key>\" }\n//   \u2192 202 { item_id, run_id, credits }      a new render, credits held\n//   \u2192 200 { duplicate: true, request_key, item_id, run_id, generation_status }\n//                                           this user's request_key already started one\n//\n// What happens after the 202 is vxil's, not this function's:\n//   \u2022 the generation lane POSTs fal's QUEUE API with your key and the signed\n//     callback URL in `?fal_webhook=` (completion.callback.query_param);\n//   \u2022 fal calls back `{ status: 'OK' | 'ERROR', payload, error? }` \u2014 status_map\n//     turns its words into completed / failed;\n//   \u2022 result_path picks `payload.images` (or `payload.video`), and the status\n//     mirror writes it onto this render's `result` with generation_status;\n//   \u2022 the held credits commit on completed and are REFUNDED on failed, on a\n//     run fal never calls back about (the timeout), and on a cancel.\n// Every run ends with job.generation.completed or job.generation.failed\n// (generation_id = the render's item_id, correlation_id = its request_key) if\n// you want to react to it in another function.\n//\n// DELIVERY IS AT-LEAST-ONCE and users double-tap: the row's `dedupe_key`\n// (owner + ':' + request_key \u2014 PER USER, so one user's key can never block\n// another's) is declared unique, so a second start with the same key is a\n// 409. On a 409 we read THIS user's row: a row that already has its run is a\n// duplicate; a row with no run (the first start died, or its enqueue answer\n// was lost, between the row and the enqueue) is RE-DRIVEN \u2014 the generation\n// run carries the same dedupe_key as its idempotency_key, so jobs hands back\n// the existing run instead of enqueueing a second fal job.\n\nimport type { HttpFunctionEnvelope } from '@vxil/sdk';\n\ntype Input = { kind?: string; prompt?: string; request_key?: string };\ntype Env = HttpFunctionEnvelope<Input>;\ntype RenderRow = { item_id: string; data: { kind?: string; prompt?: string; run_id?: string; generation_status?: string } };\n\n/** fal model ids (https://fal.ai/models) \u2014 swap freely; both are queue APIs. */\nconst MODELS = {\n  image: { url: 'https://queue.fal.run/fal-ai/flux/dev', credits: 1, resultPath: 'payload.images' },\n  video: { url: 'https://queue.fal.run/fal-ai/veo3', credits: 10, resultPath: 'payload.video' },\n} as const;\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const jobs = env.scoped_jwts?.jobs;\n    const falKey = env.secrets?.fal_key;\n    if (!cms || !jobs) return Response.json({ error: 'missing cms/jobs scope' }, { status: 403 });\n    if (!falKey) return Response.json({ error: 'store your fal key: vxil secrets set functions/fal_key' }, { status: 500 });\n    // the held credits are FORCED onto the verified end-user \u2014 a function\n    // cannot hold credits against a user it does not act for\n    const user = env.end_user?.id;\n    if (!user) return Response.json({ error: 'invoke start-render with the user\\'s session (end-user mode)' }, { status: 401 });\n\n    const kind = env.payload?.kind === 'video' ? 'video' : env.payload?.kind === 'image' ? 'image' : null;\n    const prompt = typeof env.payload?.prompt === 'string' ? env.payload.prompt.trim().slice(0, 2_000) : '';\n    const requestKey = typeof env.payload?.request_key === 'string' ? env.payload.request_key.slice(0, 120) : '';\n    if (!kind || !prompt || !requestKey) {\n      return Response.json({ error: 'need { kind: image|video, prompt, request_key }' }, { status: 422 });\n    }\n    const dedupeKey = `${user}:${requestKey}`;\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n\n    // 1. the render row (owned by the user \u2014 cms forces `owner` in end-user mode;\n    //    the render_dedupe_key hook checks dedupe_key = owner + ':' + request_key)\n    const created = await fetch(`${base}/v1/cms/items/renders`, {\n      method: 'POST',\n      headers: H,\n      body: JSON.stringify({\n        data: {\n          dedupe_key: dedupeKey, request_key: requestKey, owner: user, kind, prompt,\n          credits: MODELS[kind].credits, generation_status: 'pending', created_at: new Date().toISOString(),\n        },\n      }),\n    });\n    if (created.status === 409) {\n      // THIS user's row for this key (the read is owner-scoped in end-user mode)\n      const filter = encodeURIComponent(JSON.stringify({ dedupe_key: dedupeKey }));\n      const found = await fetch(`${base}/v1/cms/items/renders?filter=${filter}&limit=1`, { headers: H });\n      const row = found.ok ? ((await found.json()) as { data?: { items?: RenderRow[] } }).data?.items?.[0] : undefined;\n      if (!row) return Response.json({ error: `render lookup: ${found.status}` }, { status: 502 });\n      if (row.data.run_id || row.data.generation_status === 'failed') {\n        return Response.json({\n          duplicate: true, request_key: requestKey, item_id: row.item_id,\n          run_id: row.data.run_id ?? null, generation_status: row.data.generation_status ?? 'pending',\n        });\n      }\n      // a start that never got its run: re-drive it (jobs dedupes on dedupe_key)\n      const rowKind = row.data.kind === 'video' ? 'video' : 'image';\n      return startRun(base, H, jobs, falKey, user, dedupeKey, requestKey, row.item_id, rowKind, row.data.prompt ?? prompt);\n    }\n    if (!created.ok) return Response.json({ error: `render row: ${created.status}` }, { status: 502 });\n    const itemId = ((await created.json()) as { data: { item_id: string } }).data.item_id;\n    return startRun(base, H, jobs, falKey, user, dedupeKey, requestKey, itemId, kind, prompt);\n  },\n};\n\n/** 2. the fal queue job, babysat by vxil, credits held for it. Idempotent on\n *  `dedupeKey`: a re-drive gets the run that already exists. */\nasync function startRun(\n  base: string, H: Record<string, string>, jobs: string, falKey: string, user: string,\n  dedupeKey: string, requestKey: string, itemId: string, kind: 'image' | 'video', prompt: string,\n): Promise<Response> {\n  const model = MODELS[kind];\n  const enq = await fetch(`${base}/v1/jobs/generation`, {\n    method: 'POST',\n    headers: { authorization: `Bearer ${jobs}`, 'content-type': 'application/json' },\n    body: JSON.stringify({\n      job_name: `fal.${kind}`,\n      // the body is EXACTLY fal's model input (query-string callbacks send\n      // provider.body as-is \u2014 no payload / callback_url keys merged in)\n      provider: {\n        url: model.url,\n        method: 'POST',\n        headers: { authorization: `Key ${falKey}` },\n        body: kind === 'image' ? { prompt, num_images: 1 } : { prompt, duration: '8s' },\n      },\n      completion: {\n        mode: 'webhook',\n        status_path: 'status',\n        callback: { query_param: 'fal_webhook' },\n        status_map: { OK: 'completed', ERROR: 'failed' },\n        result_path: model.resultPath,\n      },\n      status_mirror: { feature: 'cms', collection: 'renders', record_id: itemId, column: 'generation_status' },\n      reserve_credits: { amount: model.credits, user_id: user, credit_type: 'media_credits', reason: `fal ${kind}` },\n      timeout: { after_ms: kind === 'image' ? 300_000 : 900_000 },\n      // rides job.generation.* as generation_id / correlation_id\n      payload: { generation_id: itemId, correlation_id: requestKey },\n      idempotency_key: dedupeKey,\n    }),\n  });\n  if (enq.status === 402) {\n    // not enough credits: the run already ENDED (job.generation.failed,\n    // ReserveInsufficient) and nothing was held \u2014 mark the row and say so.\n    // This key is spent; a new attempt (after a top-up) uses a new request_key.\n    await markFailed(base, H, itemId);\n    return Response.json({ error: 'insufficient_credits', item_id: itemId }, { status: 402 });\n  }\n  if (!enq.ok) {\n    // 429 (too many in flight) / 5xx: NO run is promised \u2014 leave the row\n    // pending with no run, so a retry with the SAME request_key re-drives it\n    return Response.json(\n      { error: `generation enqueue: ${enq.status}`, item_id: itemId, retry_after: enq.headers.get('retry-after') },\n      { status: enq.status === 429 ? 429 : 502 },\n    );\n  }\n  const runId = ((await enq.json()) as { data: { run_id: string } }).data.run_id;\n  await fetch(`${base}/v1/cms/items/renders/${encodeURIComponent(itemId)}`, {\n    method: 'PATCH',\n    headers: H,\n    body: JSON.stringify({ data: { run_id: runId } }),\n  });\n  return Response.json({ item_id: itemId, run_id: runId, credits: model.credits }, { status: 202 });\n}\n\nasync function markFailed(base: string, H: Record<string, string>, itemId: string): Promise<void> {\n  await fetch(`${base}/v1/cms/items/renders/${encodeURIComponent(itemId)}`, {\n    method: 'PATCH',\n    headers: H,\n    body: JSON.stringify({ data: { generation_status: 'failed' } }),\n  });\n}\n"
+    }
+  },
   {
     "id": "storefront",
     "title": "Storefront / E-commerce",
@@ -16777,7 +17798,8 @@ export default defineConfig({
     'abandoned-cart': {
       entry: './functions/abandoned-cart.ts',
       trigger: { kind: 'cron', schedule: '0 * * * *' },
-      scopes: ['cms:read', 'notifications:send'],
+      // cms:write \u2014 the sweep PATCHes each nudged cart to \`abandoned\` (out of the filter)
+      scopes: ['cms:read', 'cms:write', 'notifications:send'],
     },
   },
 
@@ -16800,9 +17822,9 @@ export default defineConfig({
   },
 });
 `,
-    "readme": "# Storefront / E-commerce template\n\nA single-seller e-commerce backend \u2014 catalog, variants, owner-scoped carts, coupons, moderated\nreviews, and an exactly-once checkout \u2014 declared in one typed `vxil.config.ts` plus four functions.\nPayments run as a payments integration with **your own Stripe account**: vxil is never in the flow of funds.\n\n**What it provisions:**\n- `products` / `variants` \u2014 the catalog; `variants.stock` is the oversell-safe inventory counter;\n  `variants.price_ref` holds the provider price id (e.g. a Stripe Price) the hosted checkout charges by.\n  Both are **`public: true`** \u2014 the shopfront (grid + product-detail variants) reads keyless (see below);\n  the transactional collections (`carts`/`orders`/`coupons`) are **not** public.\n- `carts` / `cart_items` \u2014 owner-scoped carts per shopper (guest checkout via anonymous auth);\n  each line snapshots `unit_price_cents` + `price_ref` at add-to-cart.\n- `orders` \u2014 unique `number` + unique `cart_ref`, with a state-machine hook guarding status transitions.\n- `coupons` / `coupon_redemptions` \u2014 codes plus one row per redemption; cap redemption writes\n  with a write-body `guards[]` under one `lock` (the cms \xA710 pattern \u2014 shown in the config, not wired into `checkout.ts`).\n- `reviews` \u2014 owner-scoped, 1\u20135 rating enforced by a hook, moderated via draft/publish.\n- Features: `cms`, `auth`, `payments` (Stripe, BYO keys), `notifications`, `functions`; four functions \u2014\n  `checkout` (the saga), `price-cart` (pricing engine), `on-order-paid` (receipt + fulfillment webhook),\n  `abandoned-cart` (hourly cron nudge).\n\n**Apply it:**\n\n```bash\nvxil init --template storefront\nvxil quickstart\nvxil secrets set stripe_secret && vxil secrets set stripe_webhook\nvxil push\nvxil seed   # demo products + the WELCOME10 coupon\nvxil gen\n```\n\n**What to learn from this:**\n1. **The checkout saga** (`functions/checkout.ts`) \u2014 reserve inventory \u2192 create the order \u2192 open the\n   payment, compensating on any failure. All-or-nothing across features, no cross-feature ACID needed.\n   Invoke `checkout`/`price-cart` from YOUR backend (server key): with `strictEndUserScope` on, an\n   end-user-mode invocation is correctly denied on the shared collections they touch\n   (`cart_items`/`variants`/`coupons`) \u2014 inventory is tenant-wide by design.\n2. **Oversell-safety** \u2014 `variants.stock` with `validation: { min: 0 }` makes `PATCH { $inc: { stock: -qty } }`\n   a single-statement conditional decrement: exactly one winner under N concurrent buyers.\n3. **Exactly-once placement** \u2014 `orders.cart_ref` is declared `unique: true` in the config (carried by\n   `vxil push`, `cms.md` \xA79.3), so N racing checkouts of one cart yield exactly one order \u2014 the rest see\n   the `409 unique_violation` and `checkout.ts` answers `already_placed` (idempotent).\n\n```typescript\n// browse the live catalog with a server key (typed SDK)\nconst { items } = await vx.from('products').query({\n  filter: { $status: 'published' },\n  sort: '-price_cents',\n  limit: 25,\n});\n```\n\n4. **The public shopfront \u2014 keyless** (vxil.com/docs/guide/04-data-with-cms). `products` and `variants` are\n   `public: true`, so a static/JAMstack storefront renders the grid and product-detail pages with **no API\n   key** \u2014 the edge forces `status = 'published'` and edge-caches the response. Only the write path (cart,\n   checkout, admin) needs a key; the transactional collections are never public.\n\n```ts\nimport { listCmsPublic } from 'https://vxil.com/sdk.mjs';\n// the public grid \u2014 NO api key\nconst { items } = await listCmsPublic('ten_your_tenant_id', 'products', { sort: '-price_cents', limit: 24 });\n// a product's sellable variants (price, availability, provider price_ref)\nconst variants = await listCmsPublic('ten_your_tenant_id', 'variants', { filter: { product: productId } });\n```\n\n**Reader UI (optional):** drop [`@vxil/react/comments`](../../packages/react) onto a product page\nfor the `reviews` thread + a file uploader (enable the `comments` feature) \u2014 a pure client-side component\nover the shipped API. It installs via npm into a bundled app (no served `.mjs`).\n\n**Go deeper:** [`examples/ecommerce`](../../examples/ecommerce) is the fully-annotated deep version of this\nblueprint; vxil.com/docs/guide/04-data-with-cms (**public delivery**), vxil.com/docs/guide/07-validation-and-hooks (hooks), vxil.com/docs/api (`$inc`, `lock`/`guards[]` on the item write routes),\nvxil.com/docs/guide/06-feature-catalog (payments),\nvxil.com/docs/guide/08-running-your-code-functions, and `templates/catalog/` (a content-only\npublic product grid).\n",
+    "readme": "# Storefront / E-commerce template\n\nA single-seller e-commerce backend \u2014 catalog, variants, owner-scoped carts, coupons, moderated\nreviews, and an exactly-once checkout \u2014 declared in one typed `vxil.config.ts` plus four functions.\nPayments run as a payments integration with **your own Stripe account**: vxil is never in the flow of funds.\n\n**What it provisions:**\n- `products` / `variants` \u2014 the catalog; `variants.stock` is the oversell-safe inventory counter;\n  `variants.price_ref` holds the provider price id (e.g. a Stripe Price) the hosted checkout charges by.\n  Both are **`public: true`** \u2014 the shopfront (grid + product-detail variants) reads keyless (see below);\n  the transactional collections (`carts`/`orders`/`coupons`) are **not** public.\n- `carts` / `cart_items` \u2014 owner-scoped carts per shopper (guest checkout via anonymous auth);\n  each line snapshots `unit_price_cents` + `price_ref` at add-to-cart.\n- `orders` \u2014 unique `number` + unique `cart_ref`, with a state-machine hook guarding status transitions.\n- `coupons` / `coupon_redemptions` \u2014 codes plus one row per redemption; cap redemption writes\n  with a write-body `guards[]` under one `lock` (the cms \xA710 pattern \u2014 shown in the config, not wired into `checkout.ts`).\n- `reviews` \u2014 owner-scoped, 1\u20135 rating enforced by a hook, moderated via draft/publish.\n- Features: `cms`, `auth`, `payments` (Stripe, BYO keys), `notifications`, `functions`; four functions \u2014\n  `checkout` (the saga), `price-cart` (pricing engine), `on-order-paid` (receipt + fulfillment webhook),\n  `abandoned-cart` (hourly cron nudge \u2014 one per abandonment: a nudged cart is marked `abandoned`).\n\n**Apply it:**\n\n```bash\nvxil init --template storefront\nvxil quickstart\nvxil secrets set stripe_secret && vxil secrets set stripe_webhook\nvxil push\nvxil seed   # demo products + the WELCOME10 coupon\nvxil gen\n```\n\n**What to learn from this:**\n1. **The checkout saga** (`functions/checkout.ts`) \u2014 reserve inventory \u2192 create the order \u2192 open the\n   payment, compensating on any failure. All-or-nothing across features, no cross-feature ACID needed.\n   Invoke `checkout`/`price-cart` from YOUR backend (server key): with `strictEndUserScope` on, an\n   end-user-mode invocation is correctly denied on the shared collections they touch\n   (`cart_items`/`variants`/`coupons`) \u2014 inventory is tenant-wide by design.\n2. **Oversell-safety** \u2014 `variants.stock` with `validation: { min: 0 }` makes `PATCH { $inc: { stock: -qty } }`\n   a single-statement conditional decrement: exactly one winner under N concurrent buyers.\n3. **Exactly-once placement** \u2014 `orders.cart_ref` is declared `unique: true` in the config (carried by\n   `vxil push`, `cms.md` \xA79.3), so N racing checkouts of one cart yield exactly one order \u2014 the rest see\n   the `409 unique_violation` and `checkout.ts` answers `already_placed` (idempotent).\n\n```typescript\n// browse the live catalog with a server key (typed SDK)\nconst { items } = await vx.from('products').query({\n  filter: { $status: 'published' },\n  sort: '-price_cents',\n  limit: 25,\n});\n```\n\n4. **The public shopfront \u2014 keyless** (vxil.com/docs/guide/04-data-with-cms). `products` and `variants` are\n   `public: true`, so a static/JAMstack storefront renders the grid and product-detail pages with **no API\n   key** \u2014 the edge forces `status = 'published'` and edge-caches the response. Only the write path (cart,\n   checkout, admin) needs a key; the transactional collections are never public.\n\n```ts\nimport { listCmsPublic } from 'https://vxil.com/sdk.mjs';\n// the public grid \u2014 NO api key\nconst { items } = await listCmsPublic('ten_your_tenant_id', 'products', { sort: '-price_cents', limit: 24 });\n// a product's sellable variants (price, availability, provider price_ref)\nconst variants = await listCmsPublic('ten_your_tenant_id', 'variants', { filter: { product: productId } });\n```\n\n**Reader UI (optional):** drop [`@vxil/react/comments`](../../packages/react) onto a product page\nfor the `reviews` thread + a file uploader (enable the `comments` feature) \u2014 a pure client-side component\nover the shipped API. It installs via npm into a bundled app (no served `.mjs`).\n\n**Go deeper:** [`examples/ecommerce`](../../examples/ecommerce) is the fully-annotated deep version of this\nblueprint; vxil.com/docs/guide/04-data-with-cms (**public delivery**), vxil.com/docs/guide/07-validation-and-hooks (hooks), vxil.com/docs/api (`$inc`, `lock`/`guards[]` on the item write routes),\nvxil.com/docs/guide/06-feature-catalog (payments),\nvxil.com/docs/guide/08-running-your-code-functions, and `templates/catalog/` (a content-only\npublic product grid).\n",
     "functions": {
-      "abandoned-cart.ts": "// abandoned-cart.ts \u2014 RETENTION CRON (a vxil function, \xA77.3).\n//\n// Trigger: cron `0 * * * *` (hourly). Sweep open carts that went stale (last_activity\n// older than 1h) using the slot-indexed range filter, and nudge the shopper. This is the\n// jobs-cron pattern \u2014 no new primitive, just a scheduled function.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CronFunctionEnvelope;\ninterface Cart { status: string; last_activity: string; end_user?: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n\n    // carts still `open` whose last_activity is > 1h ago (t1 range filter, index-served)\n    const cutoff = new Date(Date.now() - 60 * 60 * 1000).toISOString();\n    const filter = enc({ status: 'open', last_activity: { $lt: cutoff } });\n    const res = await fetch(`${base}/v1/cms/items/carts?filter=${filter}&limit=100`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    const body = (await res.json()) as { data?: { items?: { item_id: string; data: Cart }[] } };\n    const carts = body.data?.items ?? [];\n\n    // POST /v1/notifications/send is { user_id, template, data } \u2014 `transactional` is the\n    // shipped generic template (requires data.subject + data.paragraph, notifications.md \xA77).\n    let nudged = 0;\n    for (const c of carts) {\n      if (!notif || !c.data.end_user) continue;\n      await fetch(`${base}/v1/notifications/send`, {\n        method: 'POST',\n        headers: { authorization: `Bearer ${notif}`, 'content-type': 'application/json' },\n        body: JSON.stringify({\n          user_id: c.data.end_user,\n          template: 'transactional',\n          data: {\n            subject: 'You left items in your cart',\n            paragraph: `Your cart (${c.item_id}) is still waiting \u2014 come back and finish checkout any time.`,\n          },\n        }),\n      });\n      nudged++;\n    }\n    return Response.json({ scanned: carts.length, nudged });\n  },\n};\n\nconst enc = (o: unknown) => encodeURIComponent(JSON.stringify(o));\n",
+      "abandoned-cart.ts": "// abandoned-cart.ts \u2014 RETENTION CRON (a vxil function, \xA77.3).\n//\n// Trigger: cron `0 * * * *` (hourly). Sweep open carts that went stale (last_activity\n// older than 1h) using the slot-indexed range filter, and nudge the shopper. This is the\n// jobs-cron pattern \u2014 no new primitive, just a scheduled function.\n//\n// ONE nudge per abandonment: after the send, the cart is marked `abandoned`, which takes\n// it out of the `status: 'open'` filter \u2014 so the next tick reads the NEXT stale carts\n// instead of the same 100 again (and a shopper is not nudged every hour forever). Your\n// app sets `status` back to `open` (with a fresh `last_activity`) when the shopper\n// touches the cart again; a later abandonment is nudged again. The Idempotency-Key\n// (cart id + last_activity) keeps a redelivered tick, or a failed mark, from\n// sending the same nudge twice.\n\n// cron-walk: drains-filter \u2014 a nudged cart is marked `abandoned` and leaves the `status: 'open'` filter.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CronFunctionEnvelope;\ninterface Cart { status: string; last_activity: string; end_user?: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n\n    // carts still `open` whose last_activity is > 1h ago (t1 range filter, index-served)\n    const cutoff = new Date(Date.now() - 60 * 60 * 1000).toISOString();\n    const filter = enc({ status: 'open', last_activity: { $lt: cutoff } });\n    const res = await fetch(`${base}/v1/cms/items/carts?filter=${filter}&limit=100`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!res.ok) return Response.json({ error: `query ${res.status}` }, { status: 502 });\n    const body = (await res.json()) as { data?: { items?: { item_id: string; data: Cart }[] } };\n    const carts = body.data?.items ?? [];\n\n    // POST /v1/notifications/send is { user_id, template, data } \u2014 `transactional` is the\n    // shipped generic template (requires data.subject + data.paragraph, notifications.md \xA77).\n    let nudged = 0;\n    let markFailed = 0;\n    for (const c of carts) {\n      if (!notif || !c.data.end_user) continue;\n      const sent = await fetch(`${base}/v1/notifications/send`, {\n        method: 'POST',\n        headers: {\n          authorization: `Bearer ${notif}`,\n          'content-type': 'application/json',\n          'idempotency-key': `abandoned-cart:${c.item_id}:${c.data.last_activity}`,\n        },\n        body: JSON.stringify({\n          user_id: c.data.end_user,\n          template: 'transactional',\n          data: {\n            subject: 'You left items in your cart',\n            paragraph: `Your cart (${c.item_id}) is still waiting \u2014 come back and finish checkout any time.`,\n          },\n        }),\n      }).then((r) => r.ok).catch(() => false);\n      if (!sent) continue; // left open: the next tick tries again (same Idempotency-Key)\n      nudged++;\n      // Out of the filter: the next tick reads the next stale carts, not these again.\n      // The mark needs `cms:write` (declared in vxil.config.ts). A refused mark is\n      // COUNTED, never swallowed: the cart stays open, so the next tick re-reads it\n      // (the Idempotency-Key keeps the nudge from going out twice) \u2014 and a run that\n      // reports `mark_failed > 0` answers 500, so it is SEEN (`functions.run.failed`).\n      const marked = await fetch(`${base}/v1/cms/items/carts/${c.item_id}`, {\n        method: 'PATCH',\n        headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n        body: JSON.stringify({ data: { status: 'abandoned' } }),\n      }).then((r) => r.ok).catch(() => false);\n      if (!marked) markFailed++;\n    }\n    return Response.json({ scanned: carts.length, nudged, mark_failed: markFailed }, { status: markFailed > 0 ? 500 : 200 });\n  },\n};\n\nconst enc = (o: unknown) => encodeURIComponent(JSON.stringify(o));\n",
       "checkout.ts": "// checkout.ts \u2014 THE CHECKOUT SAGA (a vxil function, \xA77.3).\n//\n// The hard part of e-commerce: \"reserve N SKUs + capture payment + create the order,\n// all-or-nothing\" \u2014 which is the deliberately-REJECTED cross-feature-ACID case. The\n// doctrinal (and incumbent-identical) answer is a reserve\u2192settle\u2192reverse SAGA, and it\n// is exactly-once under any concurrency. Shopify+Stripe do the same thing (Stripe is a\n// physically separate system reconciled by webhook); nothing here is a platform gap.\n//\n// Invoke it SERVER-SIDE (your backend POSTs /v1/fn/checkout with a server key):\n// under cms.strictEndUserScope an end-user-mode invocation is correctly denied on\n// the shared collections this saga touches (cart_items/variants) \u2014 inventory is a\n// tenant-wide surface, so the reserve step is server work by design.\n//\n// Steps:\n//   1. read the cart (owner + currency) + its lines (cms:read)\n//   2. RESERVE each line: PATCH variant {$inc:{stock:-qty}} \u2014 validation.min:0 makes it a\n//      single-statement oversell-safe decrement (409 inc_out_of_bounds if insufficient).\n//      On any failure \u2192 COMPENSATE (re-$inc the ones already reserved) \u2192 409 out_of_stock.\n//   3. create the ORDER with a unique cart_ref \u2192 EXACTLY-ONCE (409 on a racing duplicate).\n//   4. open a payments checkout-session (mode:payment, Idempotency-Key = order number).\n//   5. return { order_id, checkout_url }. Capture completes async \u2192 functions/on-order-paid.ts.\n//      (Not shipped here: if payment never completes, schedule a jobs `deliver_after`\n//      release that re-$inc's the reserve.)\n\nimport type { HttpFunctionEnvelope } from '@vxil/sdk';\n\n// the caller's JSON body rides the invocation envelope under `payload`\ntype Env = HttpFunctionEnvelope<{ cart_id?: string; success_url?: string; cancel_url?: string }>;\ninterface Line { variant: string; qty: number; unit_price_cents: number; price_ref: string }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const pay = env.scoped_jwts?.payments;\n    if (!cms || !pay) return json({ error: 'missing cms/payments scope' }, 403);\n    const { cart_id, success_url, cancel_url } = env.payload ?? {};\n    if (!cart_id) return json({ error: 'cart_id required' }, 400);\n\n    const H = (jwt: string) => ({ authorization: `Bearer ${jwt}`, 'content-type': 'application/json' });\n\n    // 1. read the cart (its end_user owner + currency), then its lines\n    const cartRes = await fetch(`${base}/v1/cms/items/carts/${cart_id}`, { headers: { authorization: `Bearer ${cms}` } });\n    if (!cartRes.ok) return json({ error: 'cart_not_found' }, 404);\n    const cart = ((await cartRes.json()) as { data?: { data?: { end_user?: string; currency?: string } } }).data?.data ?? {};\n    const shopper = env.end_user?.id ?? cart.end_user;\n    if (!shopper) return json({ error: 'cart has no owner (end_user)' }, 400);\n    const lines = await get<Line>(`${base}/v1/cms/items/cart_items?filter=${enc({ cart: cart_id })}&limit=100`, cms);\n    if (lines.length === 0) return json({ error: 'empty cart' }, 400);\n\n    // 2. RESERVE inventory line-by-line (oversell-safe $inc). Track for compensation.\n    const reserved: Line[] = [];\n    for (const ln of lines) {\n      const r = await fetch(`${base}/v1/cms/items/variants/${ln.variant}`, {\n        method: 'PATCH', headers: H(cms), body: JSON.stringify({ $inc: { stock: -ln.qty } }),\n      });\n      if (!r.ok) {\n        // compensate everything reserved so far, then fail cleanly\n        await Promise.all(reserved.map((p) =>\n          fetch(`${base}/v1/cms/items/variants/${p.variant}`, {\n            method: 'PATCH', headers: H(cms), body: JSON.stringify({ $inc: { stock: p.qty } }),\n          })));\n        return json({ error: 'out_of_stock', variant: ln.variant }, 409);\n      }\n      reserved.push(ln);\n    }\n\n    // 3. create the ORDER \u2014 unique cart_ref makes placement exactly-once under concurrency.\n    const total = lines.reduce((s, l) => s + l.unit_price_cents * l.qty, 0);\n    const number = `ORD-${cart_id.slice(0, 8)}`;\n    const orderRes = await fetch(`${base}/v1/cms/items/orders`, {\n      method: 'POST', headers: H(cms),\n      body: JSON.stringify({\n        data: {\n          number, cart_ref: cart_id, status: 'pending', end_user: shopper,\n          total_cents: total, placed_at: new Date().toISOString(), lines,\n        },\n      }),\n    });\n    if (orderRes.status === 409) {\n      // a concurrent checkout already placed this cart \u2192 idempotent: report it placed\n      return json({ status: 'already_placed', number }, 200);\n    }\n    if (!orderRes.ok) {\n      await Promise.all(reserved.map((p) =>\n        fetch(`${base}/v1/cms/items/variants/${p.variant}`, {\n          method: 'PATCH', headers: H(cms), body: JSON.stringify({ $inc: { stock: p.qty } }),\n        })));\n      return json({ error: 'order_create_failed' }, 502);\n    }\n    const order = (await orderRes.json()) as { data?: { item_id?: string } };\n\n    // 4. open the hosted payment (one-time). Idempotency-Key = order number \u21D2 safe to retry.\n    // The documented checkout-sessions contract (payments.md \xA73): user_id + line_items\n    // [{ price_ref, quantity, amount_cents?, currency? }] + mode + success/cancel URLs.\n    // price_ref is the PROVIDER's price id (a Stripe Price) snapshot on the cart line \u2014\n    // Stripe's adapter charges by price id; amount_cents/currency serve amount-based\n    // providers (PayPal payment mode). NOTE: the shipped Stripe adapter charges\n    // line_items[0] only \u2014 for multi-line carts on Stripe, collapse to one provider\n    // line (or one order-total price) before opening the session.\n    const currency = cart.currency ?? 'usd';\n    const sess = await fetch(`${base}/v1/payments/checkout-sessions`, {\n      method: 'POST',\n      headers: { ...H(pay), 'idempotency-key': number },\n      body: JSON.stringify({\n        user_id: shopper,\n        mode: 'payment',\n        line_items: lines.map((l) => ({ price_ref: l.price_ref, quantity: l.qty, amount_cents: l.unit_price_cents, currency })),\n        success_url: success_url ?? 'https://storefront.example/checkout/success',\n        cancel_url: cancel_url ?? 'https://storefront.example/checkout/cancel',\n      }),\n    });\n    if (!sess.ok) {\n      // the order stays placed (pending) \u2014 surface the payment error so the caller can\n      // retry the session (same Idempotency-Key) after fixing price_refs / provider keys.\n      return json({ order_id: order.data?.item_id, number, error: 'payment_session_failed' }, 502);\n    }\n    const s = (await sess.json()) as { data?: { url?: string } };\n\n    return json({ order_id: order.data?.item_id, number, checkout_url: s.data?.url }, 201);\n  },\n};\n\n// \u2500\u2500 tiny helpers (the vxil REST envelope is { data: { items }, meta }; items carry item_id) \u2500\u2500\nasync function get<T>(url: string, jwt: string): Promise<T[]> {\n  const res = await fetch(url, { headers: { authorization: `Bearer ${jwt}` } });\n  const body = (await res.json()) as { data?: { items?: { item_id: string; data: T }[] } };\n  return (body.data?.items ?? []).map((i) => ({ id: i.item_id, ...i.data } as T));\n}\nconst enc = (o: unknown) => encodeURIComponent(JSON.stringify(o));\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n",
       "on-order-paid.ts": "// on-order-paid.ts \u2014 SETTLEMENT SIDE-EFFECTS (a vxil function, \xA77.3).\n//\n// Trigger: cmsHook \u2014 fires on cms.item.updated for `orders`. When the order flips to\n// `paid` \u2014 YOUR payment-success handler PATCHes it (e.g. a function subscribed to the\n// payments `payments.charge.succeeded` event via a webhooks-out subscription on the\n// `payments.` prefix, or your backend after the hosted checkout returns); the\n// order_transition hook validates the flip \u2014 fan out the side-effects:\n// email the receipt (notifications) and POST the fulfillment webhook to the tenant's\n// 3PL/warehouse over the egress allowlist. Delivery is at-least-once with retry/DLQ \u2014\n// identical semantics to Shopify Flow / a Stripe webhook fan-out.\n//\n// The cms-hook payload is { event, collection, item_id } \u2014 NOT the row \u2014 so the\n// function RE-FETCHES the order by id (through the edge, tenant-scoped). notifications:send\n// is a legitimate function scope (allowed by the deploy; https://vxil.com/docs/guide/08-running-your-code-functions).\n//\n// (Inventory was already reserved atomically at checkout, so there is no decrement here \u2014\n// the reservation simply becomes permanent. A payment FAILURE path compensates instead.)\n\nimport type { CmsHookFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CmsHookFunctionEnvelope;\ninterface OrderData { number?: string; status?: string; total_cents?: number; end_user?: string }\ninterface Item { data?: { data?: OrderData } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    const itemId = env.payload?.item_id;\n    // The platform now filters cms-hook deliveries on the binding's collection/event\n    // server-side (functions.md \xA73); this guard stays as belt-and-braces.\n    if (env.payload?.collection !== 'orders' || !cms || !itemId) return Response.json({ skipped: true });\n\n    // Re-fetch the order (the payload carries only the id) and act only on pending\u2192paid.\n    const res = await fetch(`${base}/v1/cms/items/orders/${itemId}`, { headers: { authorization: `Bearer ${cms}` } });\n    if (!res.ok) return Response.json({ skipped: true, reason: `fetch ${res.status}` });\n    const order = ((await res.json()) as Item).data?.data ?? {};\n    if (order.status !== 'paid') return Response.json({ skipped: true, status: order.status });\n\n    // 1. receipt email (in-app inbox + email via the configured provider).\n    if (notif && order.end_user) {\n      await fetch(`${base}/v1/notifications/send`, {\n        method: 'POST',\n        headers: { authorization: `Bearer ${notif}`, 'content-type': 'application/json' },\n        body: JSON.stringify({\n          user_id: order.end_user,\n          template: 'transactional',\n          data: { subject: `Receipt for order ${order.number}`, paragraph: `Thanks! Your order ${order.number} totalling ${order.total_cents} cents is confirmed.` },\n        }),\n      }).catch(() => { /* the jobs/webhooks retry+DLQ engine owns durability */ });\n    }\n\n    // 2. fulfillment webhook to the tenant's warehouse (egress-guarded to fulfillment.example.com).\n    await fetch('https://fulfillment.example.com/orders', {\n      method: 'POST',\n      headers: { 'content-type': 'application/json' },\n      body: JSON.stringify({ number: order.number, total_cents: order.total_cents }),\n    }).catch(() => { /* best-effort here */ });\n\n    return Response.json({ settled: order.number });\n  },\n};\n",
       "price-cart.ts": "// price-cart.ts \u2014 THE PRICING ENGINE (a vxil function, \xA77.3).\n//\n// This is the module people assume needs a \"promotions feature\". It does NOT \u2014 and it\n// deliberately is NOT a cms lifecycle hook: hooks are single-row and cross-row aggregation\n// is forbidden by design (hooks.ts), so a hook can't sum a cart, apply BOGO across items,\n// or evaluate cart-level thresholds. That is arbitrary domain logic \u2192 a FUNCTION with full\n// JS expressiveness (exactly how Shopify Functions / Scripts run tenant discount code) \u2192 [B].\n//\n// It reads the cart lines + coupon (cms:read) and returns the priced cart. Like checkout,\n// invoke it SERVER-SIDE: under cms.strictEndUserScope the shared collections it reads\n// (cart_items/coupons) are correctly denied to an end-user-mode invocation. checkout.ts\n// recomputes its total from the same server-held snapshots \u2014 never trust a client total;\n// to honor promotions at capture time, apply this function's output there the same way.\n\nimport type { HttpFunctionEnvelope } from '@vxil/sdk';\n\n// the caller's JSON body rides the invocation envelope under `payload`\ntype Env = HttpFunctionEnvelope<{ cart_id?: string; coupon_code?: string }>;\ninterface Line { variant: string; qty: number; unit_price_cents: number }\ninterface Coupon { code: string; kind: string; value: number; max_uses: number }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n    const { cart_id, coupon_code } = env.payload ?? {};\n    if (!cart_id) return Response.json({ error: 'cart_id required' }, { status: 400 });\n\n    const lines = await get<Line>(`${base}/v1/cms/items/cart_items?filter=${enc({ cart: cart_id })}&limit=100`, cms);\n\n    // subtotal (cross-row sum \u2014 the thing a hook can't do)\n    const subtotal = lines.reduce((s, l) => s + l.unit_price_cents * l.qty, 0);\n\n    // \u2500\u2500 arbitrary promotion rules, plain JS \u2500\u2500\n    let discount = 0;\n    const applied: string[] = [];\n\n    // BOGO on any 2+ identical lines: cheapest unit free per pair\n    for (const l of lines) {\n      if (l.qty >= 2) { discount += Math.floor(l.qty / 2) * l.unit_price_cents; applied.push('bogo'); }\n    }\n\n    // tiered cart threshold: 5% over $100, 10% over $250\n    if (subtotal >= 25000) { discount += Math.round(subtotal * 0.10); applied.push('tier-10'); }\n    else if (subtotal >= 10000) { discount += Math.round(subtotal * 0.05); applied.push('tier-5'); }\n\n    // coupon (percent or fixed) \u2014 stacks on top, capped so total never goes below 0\n    if (coupon_code) {\n      const [c] = await get<Coupon>(`${base}/v1/cms/items/coupons?filter=${enc({ code: coupon_code })}&limit=1`, cms);\n      if (c) {\n        discount += c.kind === 'percent' ? Math.round(subtotal * (c.value / 100)) : c.value;\n        applied.push(`coupon:${c.code}`);\n      }\n    }\n\n    const total = Math.max(0, subtotal - discount);\n    return Response.json({ subtotal_cents: subtotal, discount_cents: subtotal - total, total_cents: total, applied });\n  },\n};\n\nasync function get<T>(url: string, jwt: string): Promise<T[]> {\n  const res = await fetch(url, { headers: { authorization: `Bearer ${jwt}` } });\n  const body = (await res.json()) as { data?: { items?: { item_id: string; data: T }[] } };\n  return (body.data?.items ?? []).map((i) => ({ id: i.item_id, ...i.data } as T));\n}\nconst enc = (o: unknown) => encodeURIComponent(JSON.stringify(o));\n"
@@ -17086,7 +18108,7 @@ export default defineConfig({
     "readme": "# Helpdesk / Support Ticketing template\n\nA support-ticketing backend \u2014 requester-owned tickets with a hook-enforced status state machine,\nthreaded conversation messages, an acknowledgement send on every new ticket, and an hourly\nSLA-escalation cron \u2014 declared end-to-end in one typed `vxil.config.ts`.\n\n**What it provisions:**\n- `tickets` \u2014 subject, `status` (state machine below), priority, `requester` (the **owner field**),\n  `opened_at`, `sla_due`, body. Every queue-driving field is slot-indexed for filter/sort.\n- `ticket_messages` \u2014 the conversation thread: `ticket` relation, author, body, `sent_at`.\n- Features: `cms` + `auth` (email/password end-users) + `notifications` (mock provider) + `functions`.\n- Functions: `on-ticket-created` (cmsHook \u2192 acknowledgement send) and `sla-sweep` (hourly cron).\n\n**Apply it:**\n\n```bash\nvxil init --template helpdesk\nvxil quickstart\nvxil push\nvxil gen\n```\n\n**What to learn from this:**\n- **A status state machine in a Lane-A hook** \u2014 the `beforeUpdate` validate allows only\n  `open\u2192pending|resolved`, `pending\u2192open|resolved`, `resolved\u2192closed`; any other transition is a\n  clean 422, atomically, in the write itself (vxil.com/docs/guide/07-validation-and-hooks).\n- **SLA automation as a cron function** \u2014 `sla-sweep` queries breached tickets with the \xA73 filter DSL\n  (`status $in` + `sla_due $lt`, slot-indexed) and PATCHes `priority: 'urgent'`; the `$ne: 'urgent'`\n  term makes re-runs idempotent.\n- **Requester-scoped end-user access** \u2014 `tickets.ownerField = 'requester'`: a signed-in requester\n  sees and edits only their **own** tickets (vxil.com/docs/guide/04-data-with-cms); server keys see the queue.\n\n```ts\nconst { item_id } = await vx.from('tickets').create({\n  subject: 'Cannot sign in on mobile', status: 'open', priority: 'normal',\n  requester: 'user_demo', opened_at: new Date().toISOString(),\n  sla_due: new Date(Date.now() + 8 * 3600e3).toISOString(), body: 'Steps to reproduce\u2026',\n});\n\n// the agent queue, most-overdue first (slot-indexed \u2192 typed filter/sort, index-served)\nconst { items } = await vx.from('tickets').query({\n  filter: { status: { $in: ['open', 'pending'] } }, sort: 'sla_due', limit: 25,\n});\n```\n\n**Go deeper:** vxil.com/docs/guide/04-data-with-cms (query DSL \xB7 owner-scoping) \xB7 vxil.com/docs/guide/07-validation-and-hooks \xB7\nvxil.com/docs/guide/08-running-your-code-functions \xB7 vxil.com/docs/guide/06-feature-catalog (notifications) \xB7 `examples/ecommerce/`.\n\n**Own the shape.** The config is yours after `init` \u2014 nothing is locked.\n",
     "functions": {
       "on-ticket-created.ts": "// on-ticket-created.ts \u2014 the ACKNOWLEDGEMENT hook (a vxil function, \xA77.3).\n//\n// Trigger: cmsHook \u2014 fires on cms.item.* for `tickets`. On a CREATE, send the\n// requester an acknowledgement through notifications. The cms-hook payload is\n// { event, collection, item_id } \u2014 NOT the row \u2014 so the function RE-FETCHES the\n// ticket by id (through the edge, tenant-scoped) rather than trusting inline fields.\n// Delivery is at-least-once: the envelope idempotency_key rides the send as its\n// Idempotency-Key header, so a redelivered hook never double-sends.\n\nimport type { CmsHookFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CmsHookFunctionEnvelope;\ninterface TicketData { subject?: string; status?: string; requester?: string; sla_due?: string }\ninterface Item { data?: { data?: TicketData } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const notif = env.scoped_jwts?.notifications;\n    const itemId = env.payload?.item_id;\n    // The platform now filters cms-hook deliveries on the binding's collection/event\n    // server-side (functions.md \xA73); this guard stays as belt-and-braces.\n    if (env.payload?.collection !== 'tickets' || !cms || !notif || !itemId) {\n      return Response.json({ skipped: true });\n    }\n    // acknowledge only the CREATE (the cms.item.* subscription also delivers updates)\n    if (!String(env.payload?.event ?? '').endsWith('.created')) {\n      return Response.json({ skipped: true, event: env.payload?.event });\n    }\n\n    // Re-fetch the ticket (the payload carries only the id).\n    const res = await fetch(`${base}/v1/cms/items/tickets/${itemId}`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!res.ok) return Response.json({ skipped: true, reason: `fetch ${res.status}` });\n    const ticket = ((await res.json()) as Item).data?.data ?? {};\n    if (!ticket.requester) return Response.json({ skipped: true, reason: 'no requester' });\n\n    // Acknowledge to the requester (email/inbox via the configured provider).\n    const send = await fetch(`${base}/v1/notifications/send`, {\n      method: 'POST',\n      headers: {\n        authorization: `Bearer ${notif}`,\n        'content-type': 'application/json',\n        ...(env.idempotency_key ? { 'idempotency-key': env.idempotency_key } : {}),\n      },\n      body: JSON.stringify({\n        user_id: ticket.requester,\n        template: 'transactional',\n        data: {\n          subject: `We got your ticket: ${ticket.subject ?? itemId}`,\n          paragraph:\n            `Your ticket is ${ticket.status ?? 'open'} and in our queue` +\n            `${ticket.sla_due ? ` (response due by ${ticket.sla_due})` : ''}. ` +\n            'Reply in the app to add details.',\n        },\n      }),\n    });\n    return Response.json({ acknowledged: itemId, delivery: send.status });\n  },\n};\n",
-      "sla-sweep.ts": "// sla-sweep.ts \u2014 SLA ESCALATION CRON (a vxil function, \xA77.3).\n//\n// Trigger: cron `0 * * * *` (hourly). Sweep tickets whose sla_due has passed and\n// that are still open/pending \u2014 the cms filter DSL (vxil.com/docs/guide/04-data-with-cms):\n// `status $in` on the s2 slot, `sla_due $lt` on the t2 slot, `priority $ne` on\n// s3 \u2014 all index-served. Each breach is escalated with a PATCH to priority\n// 'urgent'; the $ne term makes re-runs idempotent (an escalated ticket falls out\n// of the filter). The Lane-A state-machine hook still runs on every PATCH; a\n// priority-only write keeps item.status == before.status, so it always passes.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CronFunctionEnvelope;\ninterface Ticket { id: string; data: { subject?: string; priority?: string } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n\n    // breached = still open/pending, past its sla_due, not yet urgent\n    const filter = enc({\n      status: { $in: ['open', 'pending'] },\n      sla_due: { $lt: new Date().toISOString() },\n      priority: { $ne: 'urgent' },\n    });\n    const res = await fetch(`${base}/v1/cms/items/tickets?filter=${filter}&limit=100`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!res.ok) return Response.json({ error: `query ${res.status}` }, { status: 502 });\n    const body = (await res.json()) as { data?: { items?: Ticket[] } };\n    const breached = body.data?.items ?? [];\n\n    let escalated = 0;\n    for (const t of breached) {\n      const r = await fetch(`${base}/v1/cms/items/tickets/${t.id}`, {\n        method: 'PATCH',\n        headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n        body: JSON.stringify({ data: { priority: 'urgent' } }),\n      });\n      if (r.ok) escalated++;\n    }\n    return Response.json({ scanned: breached.length, escalated });\n  },\n};\n\n// \u2500\u2500 tiny helper (the vxil REST list envelope is { data: { items } }) \u2500\u2500\nconst enc = (o: unknown) => encodeURIComponent(JSON.stringify(o));\n"
+      "sla-sweep.ts": "// sla-sweep.ts \u2014 SLA ESCALATION CRON (a vxil function, \xA77.3).\n//\n// Trigger: cron `0 * * * *` (hourly). Sweep tickets whose sla_due has passed and\n// that are still open/pending \u2014 the cms filter DSL (vxil.com/docs/guide/04-data-with-cms):\n// `status $in` on the s2 slot, `sla_due $lt` on the t2 slot, `priority $ne` on\n// s3 \u2014 all index-served. Each breach is escalated with a PATCH to priority\n// 'urgent'; the $ne term makes re-runs idempotent (an escalated ticket falls out\n// of the filter). The Lane-A state-machine hook still runs on every PATCH; a\n// priority-only write keeps item.status == before.status, so it always passes.\n\n// cron-walk: drains-filter \u2014 an escalated ticket gets priority 'urgent' and leaves the `$ne` filter.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CronFunctionEnvelope;\ninterface Ticket { item_id: string; data: { subject?: string; priority?: string } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n\n    // breached = still open/pending, past its sla_due, not yet urgent\n    const filter = enc({\n      status: { $in: ['open', 'pending'] },\n      sla_due: { $lt: new Date().toISOString() },\n      priority: { $ne: 'urgent' },\n    });\n    const res = await fetch(`${base}/v1/cms/items/tickets?filter=${filter}&limit=100`, {\n      headers: { authorization: `Bearer ${cms}` },\n    });\n    if (!res.ok) return Response.json({ error: `query ${res.status}` }, { status: 502 });\n    const body = (await res.json()) as { data?: { items?: Ticket[] } };\n    const breached = body.data?.items ?? [];\n\n    let escalated = 0;\n    for (const t of breached) {\n      const r = await fetch(`${base}/v1/cms/items/tickets/${t.item_id}`, {\n        method: 'PATCH',\n        headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n        body: JSON.stringify({ data: { priority: 'urgent' } }),\n      });\n      if (r.ok) escalated++;\n    }\n    return Response.json({ scanned: breached.length, escalated });\n  },\n};\n\n// \u2500\u2500 tiny helper (the vxil REST list envelope is { data: { items } }) \u2500\u2500\nconst enc = (o: unknown) => encodeURIComponent(JSON.stringify(o));\n"
     }
   },
   {
@@ -17204,7 +18226,7 @@ export default defineConfig({
     "configSrc": "import { defineConfig } from '@vxil/config';\n\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// \"IoT Fleet\" \u2014 device fleet telemetry + alerting, declared end-to-end in ONE\n// typed file. A BLUEPRINT composing shipped building blocks \u2014\n//   \u2022 cms       \u2192 devices \u2192 readings / alerts (resolved by relation)\n//   \u2022 functions \u2192 the typed HTTP ingest endpoint + the daily aggregate rollup\n//   \u2022 webhooks  \u2192 fan alert writes out to the tenant's ops endpoint (outbound\n//                 subscriptions over the audit_event stream \u2014 webhooks.md \xA72)\n// Cross-row writes (create the reading + heartbeat the device + raise a\n// threshold alert) are exactly why ingest is a FUNCTION, not a Lane-A hook \u2014\n// hooks are pure single-row expressions. Everything here is DATA the tenant\n// owns and edits after `vxil init`.\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nexport default defineConfig({\n  env: 'staging',\n\n  features: {\n    cms: {\n      hooks: {\n        // Every reading needs a metric name \u2014 a pure function of the row (Lane-A validate).\n        reading_metric: {\n          collection: 'readings',\n          event: 'beforeWrite',\n          kind: 'validate',\n          expr: 'len(item.metric) > 0',\n          message: 'a reading needs a metric name',\n        },\n      },\n      // The DECLARATIVE rollup alternative to functions/daily-rollup.ts: a\n      // `readModels` config entry (cms.md \xA712.4) can materialize the same\n      // per-device aggregate on cron into a dedicated rollup collection. This\n      // blueprint keeps the imperative function so you can read the endpoint\n      // it rides on (POST /v1/cms/items/readings/aggregate, \xA712.2).\n    },\n\n    // Outbound subscriptions are RUNTIME rows, not config keys:\n    //   POST /v1/webhooks/subscriptions { target_url, event_prefixes: ['cms.item.'] }\n    // fans every cms write (including new alert rows) to your ops endpoint as a\n    // signed jobs callback \u2014 verify X-Vxil-Jobs-Signature, filter for alerts.\n    webhooks: {},\n\n    functions: { enabled: true }, // the \xA77.3 crossing: opt-in, egress-guarded\n  },\n\n  // \u2500\u2500 Schema-as-code: the cms collections (\u22648 index slots each: s1\u2013s4/n1\u2013n2/t1\u2013t2) \u2500\u2500\n  cms: {\n    collections: {\n      devices: {\n        singular: 'device',\n        fields: {\n          serial: { type: 'string', required: true, indexSlot: 's1', unique: true },\n          model: { type: 'string', indexSlot: 's2' },\n          site: { type: 'string', indexSlot: 's3' },\n          status: { type: 'string', indexSlot: 's4', validation: { enum: ['active', 'maintenance', 'retired'] } },\n          last_seen: { type: 'datetime', indexSlot: 't1' }, // heartbeat, PATCHed by ingest-reading\n          battery_pct: { type: 'int', indexSlot: 'n1', validation: { min: 0, max: 100 } },\n        },\n      },\n      readings: {\n        singular: 'reading',\n        fields: {\n          device: { type: 'relation', relationTo: 'devices', required: true, indexSlot: 's1' },\n          metric: { type: 'string', required: true, indexSlot: 's2' }, // e.g. battery_pct, temp_c\n          value: { type: 'float', required: true, indexSlot: 'n1' }, // n-slot \u2192 min/max/avg aggregates\n          recorded_at: { type: 'datetime', indexSlot: 't1' }, // t-slot \u2192 the 24h aggregate window\n        },\n      },\n      alerts: {\n        singular: 'alert',\n        fields: {\n          device: { type: 'relation', relationTo: 'devices', required: true, indexSlot: 's1' },\n          kind: { type: 'string', required: true, indexSlot: 's2' }, // low_battery | daily_rollup | \u2026\n          severity: { type: 'string', indexSlot: 's3', validation: { enum: ['info', 'warning', 'critical'] } },\n          raised_at: { type: 'datetime', indexSlot: 't1' },\n          note: { type: 'text' },\n        },\n      },\n    },\n  },\n\n  // \u2500\u2500 The domain logic that ISN'T config: tenant functions (functions.md) \u2500\u2500\n  functions: {\n    // The typed device endpoint: POST /v1/fn/ingest-reading { device_id, metric, value }\n    // \u2192 create the reading + heartbeat the device + threshold-alert, in one call.\n    // The alert write is deduped with a `lock` + `guard` WRITE BODY (cms.md \xA710):\n    // at most ONE live low_battery alert per device \u2014 never a config key.\n    'ingest-reading': {\n      entry: './functions/ingest-reading.ts',\n      trigger: { kind: 'http' },\n      scopes: ['cms:read', 'cms:write'],\n      egressAllow: [], // pure vxil-internal; no external egress needed\n    },\n    // The daily rollup: ONE bounded \xA712.2 aggregate call (per-device min/max/avg\n    // over the last 24h of battery_pct readings) \u2192 one info summary row per device\n    // per UTC day (lock+guard-deduped \u2014 cron delivery is at-least-once).\n    'daily-rollup': {\n      entry: './functions/daily-rollup.ts',\n      trigger: { kind: 'cron', schedule: '0 6 * * *' },\n      scopes: ['cms:read', 'cms:write'],\n      egressAllow: [],\n    },\n  },\n\n  seed: {\n    cms: [\n      {\n        collection: 'devices',\n        items: [\n          { serial: 'SN-0001', model: 'env-sensor-2', site: 'plant-a', status: 'active', battery_pct: 87 },\n          { serial: 'SN-0002', model: 'env-sensor-2', site: 'plant-b', status: 'active', battery_pct: 42 },\n        ],\n      },\n    ],\n  },\n});\n",
     "readme": '# IoT Fleet / Telemetry template\n\nA device-fleet backend \u2014 devices, telemetry readings, and alerts \u2014 declared end-to-end in one typed\n`vxil.config.ts`, with the domain logic that isn\'t config (ingest, thresholds, rollups) as two tenant\nfunctions.\n\n**What it provisions:**\n- `devices` \u2014 unique serial, model, site, lifecycle status, `last_seen` heartbeat, `battery_pct`.\n- `readings` \u2014 `device` relation, metric name, float `value` (n-slot \u2192 aggregates), `recorded_at` (t-slot \u2192 windows).\n- `alerts` \u2014 `device` relation, kind, severity, `raised_at`, free-text note.\n- Features: `cms` (+ a Lane-A validate hook), `webhooks` (outbound fan-out), `functions`\n  (`ingest-reading` on http, `daily-rollup` on a daily cron).\n\n**Apply it:**\n\n```bash\nvxil init --template iot-fleet\nvxil quickstart   # or `vxil link` an existing tenant\nvxil push\nvxil gen\n```\n\n**What to learn from this:**\n- **HTTP ingest functions as typed device endpoints** \u2014 `functions/ingest-reading.ts` turns one\n  `POST /v1/fn/ingest-reading` (the key needs the `functions:invoke` scope) into three cross-row\n  writes: create the reading, PATCH the device heartbeat, raise a threshold alert. Cross-row work\n  is exactly why this is a function, not a hook.\n- **Guard-deduped threshold alerting** \u2014 the alert POST carries `lock` + `guard` in the WRITE BODY\n  (vxil.com/docs/api: the item write routes): at most one live `low_battery` alert per device, race-safe. Deleting\n  the alert row resolves it and frees the guard.\n- **Bounded aggregates for rollups** \u2014 `functions/daily-rollup.ts` calls\n  `POST /v1/cms/items/readings/aggregate` (\xA712.2: \u2264500 groups over a \u226450k scan) for per-device\n  daily min/max/avg. Cron delivery is at-least-once, so each summary write is itself lock+guard-deduped\n  to one per (device, day); the declarative sibling is a `readModels` config entry (\xA712.4).\n- **Webhook fan-out of alerts** \u2014 `POST /v1/webhooks/subscriptions` with\n  `{ "target_url": "https://ops.example.com/hook", "event_prefixes": ["cms.item."] }` delivers every\n  cms write (including new alerts) as a signed jobs callback \u2014 verify `X-Vxil-Jobs-Signature`.\n\n```bash\ncurl -X POST https://api.vxil.com/v1/fn/ingest-reading \\\n  -H "Authorization: Bearer $VXIL_KEY" -H "Content-Type: application/json" \\\n  -d \'{"device_id":"itm_...","metric":"battery_pct","value":12}\'\n```\n\nTyped SDK query for the ops dashboard: `vx.from(\'devices\').query({ filter: { battery_pct: { $lt: 20 } }, sort: \'-last_seen\' })`.\n\n**Go deeper:** vxil.com/docs/api (lock/guard, aggregates, read-models),\nvxil.com/docs/guide/08-running-your-code-functions, vxil.com/docs/guide/06-feature-catalog (webhooks), and `examples/ecommerce/` for a larger\nfunction saga. The config is yours after `init` \u2014 nothing is locked.\n',
     "functions": {
-      "daily-rollup.ts": "// daily-rollup.ts \u2014 BOUNDED AGGREGATES FOR ROLLUPS (a vxil function, cron trigger).\n//\n// Runs daily (cron 0 6 * * *). ONE call to the real group-by aggregate endpoint \u2014\n// POST /v1/cms/items/readings/aggregate (cms.md \xA712.2) \u2014 computes per-device\n// min/max/avg/count of battery_pct over the last 24h (grouped by the slot-bound\n// `device` relation; hard-bounded server-side: \u2264500 groups over a \u226450k-row scan,\n// else a clean 422 window_too_large), then writes one `daily_rollup` info row into\n// `alerts` per device. Cron delivery is at-least-once and cms does NOT dedupe on\n// the Idempotency-Key header, so exactly-once-per-day is enforced with the \xA710\n// lock+guard WRITE BODY: at most ONE daily_rollup per (device, UTC day) \u2014 a\n// redelivered run cleanly 409s. The DECLARATIVE alternative is a `readModels`\n// config entry materializing on cron (cms.md \xA712.4).\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CronFunctionEnvelope;\ninterface Group { key: { device?: string }; count: number; min?: number; max?: number; avg?: number }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return json({ error: 'missing cms scope' }, 403);\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n    const now = new Date().toISOString();\n\n    // 1. the bounded aggregate: min/max/avg need `value` on an n-slot (n1);\n    //    the 24h window rides the t-slot (t1) on `recorded_at`.\n    const agg = await fetch(`${base}/v1/cms/items/readings/aggregate`, {\n      method: 'POST', headers: H,\n      body: JSON.stringify({\n        aggregates: [\n          { fn: 'min', field: 'value', as: 'min' },\n          { fn: 'max', field: 'value', as: 'max' },\n          { fn: 'avg', field: 'value', as: 'avg' },\n          { fn: 'count' },\n        ],\n        groupBy: ['device'],\n        filter: { metric: 'battery_pct', $status: 'published' },\n        window: { field: 'recorded_at', sinceDays: 1 },\n        limit: 500,\n      }),\n    });\n    if (!agg.ok) return json({ error: 'aggregate_failed', status: agg.status }, 502);\n    const groups = ((await agg.json()) as { data?: { groups?: Group[] } }).data?.groups ?? [];\n\n    // 2. one published summary row per (device, UTC day) \u2014 the guard counts today's\n    //    live daily_rollup rows for the device under the lock, so a redelivered\n    //    cron run 409s instead of duplicating (cms.md \xA710).\n    const day = now.slice(0, 10);\n    let written = 0;\n    for (const g of groups) {\n      if (!g.key.device) continue;\n      const r = await fetch(`${base}/v1/cms/items/alerts`, {\n        method: 'POST',\n        headers: env.idempotency_key ? { ...H, 'idempotency-key': `${env.idempotency_key}:${g.key.device}` } : H,\n        body: JSON.stringify({\n          status: 'published',\n          lock: `rollup:${g.key.device}`,\n          guard: {\n            filter: { device: g.key.device, kind: 'daily_rollup', raised_at: { $gte: `${day}T00:00:00.000Z` } },\n            max: 1,\n          },\n          data: {\n            device: g.key.device, kind: 'daily_rollup', severity: 'info', raised_at: now,\n            note: `battery_pct last 24h \u2014 min ${g.min} \xB7 max ${g.max} \xB7 avg ${round1(g.avg)} over ${g.count} readings`,\n          },\n        }),\n      });\n      if (r.ok) written += 1;\n    }\n    return json({ devices: groups.length, written }, 200);\n  },\n};\n\nconst json = (o: unknown, status: number) => Response.json(o, { status });\nconst round1 = (n?: number) => (typeof n === 'number' ? Math.round(n * 10) / 10 : n);\n",
+      "daily-rollup.ts": "// daily-rollup.ts \u2014 BOUNDED AGGREGATES FOR ROLLUPS (a vxil function, cron trigger).\n//\n// Runs daily (cron 0 6 * * *). ONE call to the real group-by aggregate endpoint \u2014\n// POST /v1/cms/items/readings/aggregate (cms.md \xA712.2) \u2014 computes per-device\n// min/max/avg/count of battery_pct over the last 24h (grouped by the slot-bound\n// `device` relation; hard-bounded server-side: \u2264500 groups over a \u226450k-row scan,\n// else a clean 422 window_too_large), then writes one `daily_rollup` info row into\n// `alerts` per device. Cron delivery is at-least-once and cms does NOT dedupe on\n// the Idempotency-Key header, so exactly-once-per-day is enforced with the \xA710\n// lock+guard WRITE BODY: at most ONE daily_rollup per (device, UTC day) \u2014 a\n// redelivered run cleanly 409s. The DECLARATIVE alternative is a `readModels`\n// config entry materializing on cron (cms.md \xA712.4).\n\n// cron-walk: single-read \u2014 one bounded server-side aggregate is the whole job; nothing to page.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = CronFunctionEnvelope;\ninterface Group { key: { device?: string }; count: number; min?: number; max?: number; avg?: number }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return json({ error: 'missing cms scope' }, 403);\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n    const now = new Date().toISOString();\n\n    // 1. the bounded aggregate: min/max/avg need `value` on an n-slot (n1);\n    //    the 24h window rides the t-slot (t1) on `recorded_at`.\n    const agg = await fetch(`${base}/v1/cms/items/readings/aggregate`, {\n      method: 'POST', headers: H,\n      body: JSON.stringify({\n        aggregates: [\n          { fn: 'min', field: 'value', as: 'min' },\n          { fn: 'max', field: 'value', as: 'max' },\n          { fn: 'avg', field: 'value', as: 'avg' },\n          { fn: 'count' },\n        ],\n        groupBy: ['device'],\n        filter: { metric: 'battery_pct', $status: 'published' },\n        window: { field: 'recorded_at', sinceDays: 1 },\n        limit: 500,\n      }),\n    });\n    if (!agg.ok) return json({ error: 'aggregate_failed', status: agg.status }, 502);\n    const groups = ((await agg.json()) as { data?: { groups?: Group[] } }).data?.groups ?? [];\n\n    // 2. one published summary row per (device, UTC day) \u2014 the guard counts today's\n    //    live daily_rollup rows for the device under the lock, so a redelivered\n    //    cron run 409s instead of duplicating (cms.md \xA710).\n    const day = now.slice(0, 10);\n    let written = 0;\n    for (const g of groups) {\n      if (!g.key.device) continue;\n      const r = await fetch(`${base}/v1/cms/items/alerts`, {\n        method: 'POST',\n        headers: env.idempotency_key ? { ...H, 'idempotency-key': `${env.idempotency_key}:${g.key.device}` } : H,\n        body: JSON.stringify({\n          status: 'published',\n          lock: `rollup:${g.key.device}`,\n          guard: {\n            filter: { device: g.key.device, kind: 'daily_rollup', raised_at: { $gte: `${day}T00:00:00.000Z` } },\n            max: 1,\n          },\n          data: {\n            device: g.key.device, kind: 'daily_rollup', severity: 'info', raised_at: now,\n            note: `battery_pct last 24h \u2014 min ${g.min} \xB7 max ${g.max} \xB7 avg ${round1(g.avg)} over ${g.count} readings`,\n          },\n        }),\n      });\n      if (r.ok) written += 1;\n    }\n    return json({ devices: groups.length, written }, 200);\n  },\n};\n\nconst json = (o: unknown, status: number) => Response.json(o, { status });\nconst round1 = (n?: number) => (typeof n === 'number' ? Math.round(n * 10) / 10 : n);\n",
       "ingest-reading.ts": "// ingest-reading.ts \u2014 THE TYPED DEVICE ENDPOINT (a vxil function, http trigger).\n//\n// POST /v1/fn/ingest-reading with { device_id, metric, value } \u2014 one call from a\n// device (or gateway) does the three cross-row writes no Lane-A hook may do:\n//   1. create the `readings` row (published, so the daily aggregate window sees it;\n//      the envelope idempotency key is passed through as the write's Idempotency-Key\n//      header \u2014 the platform convention, functions.md \xA76e)\n//   2. PATCH the device: last_seen = now (+ battery_pct when the metric carries it)\n//   3. THRESHOLD ALERTING: battery below 15 \u2192 create a low_battery alert, deduped\n//      by a lock+guard WRITE BODY (at most ONE live alert per device \u2014 cms.md \xA710).\n//      The guard is the dedupe that matters \u2014 a retried reading create is telemetry noise.\n// Resolve an alert by deleting its row; that frees the guard for the next one.\n\nimport type { HttpFunctionEnvelope } from '@vxil/sdk';\n\n// the caller's JSON body rides the invocation envelope under `payload` (functions.md \xA72)\ntype Env = HttpFunctionEnvelope<{ device_id?: string; metric?: string; value?: number }>;\ninterface Created { data?: { item_id?: string } } // cms responses are { data: {\u2026}, meta }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return json({ error: 'missing cms scope' }, 403);\n    const { device_id, metric } = env.payload ?? {};\n    const value = Number(env.payload?.value);\n    if (!device_id || !metric || !Number.isFinite(value)) {\n      return json({ error: 'device_id, metric and numeric value required' }, 400);\n    }\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n    const now = new Date().toISOString();\n\n    // 0. the device must exist (404 from cms = unknown or deleted device)\n    const dev = await fetch(`${base}/v1/cms/items/devices/${device_id}`, { headers: H });\n    if (!dev.ok) return json({ error: 'unknown_device' }, 404);\n\n    // 1. create the reading \u2014 published so the daily aggregate window sees it\n    const rd = await fetch(`${base}/v1/cms/items/readings`, {\n      method: 'POST',\n      headers: env.idempotency_key ? { ...H, 'idempotency-key': env.idempotency_key } : H,\n      body: JSON.stringify({\n        status: 'published',\n        data: { device: device_id, metric, value, recorded_at: now },\n      }),\n    });\n    if (!rd.ok) return json({ error: 'reading_create_failed', status: rd.status }, 502);\n    const reading = ((await rd.json()) as Created).data ?? {};\n\n    // 2. heartbeat the device (merge-patch; battery only when this metric carries it)\n    const patch: Record<string, unknown> = { last_seen: now };\n    if (metric === 'battery_pct') patch.battery_pct = Math.max(0, Math.min(100, Math.round(value)));\n    await fetch(`${base}/v1/cms/items/devices/${device_id}`, {\n      method: 'PATCH', headers: H, body: JSON.stringify({ data: patch }),\n    });\n\n    // 3. threshold alert \u2014 `guard` counts live rows under the ONE advisory `lock`,\n    //    so N racing low-battery ingests raise exactly one alert (the rest 409).\n    let alert_id: string | undefined;\n    if (metric === 'battery_pct' && value < 15) {\n      const al = await fetch(`${base}/v1/cms/items/alerts`, {\n        method: 'POST', headers: H,\n        body: JSON.stringify({\n          status: 'published',\n          lock: `dev:${device_id}:low_battery`,\n          guard: { filter: { device: device_id, kind: 'low_battery' }, max: 1 },\n          data: { device: device_id, kind: 'low_battery', severity: 'warning', raised_at: now, note: `battery at ${value}%` },\n        }),\n      });\n      if (al.ok) alert_id = ((await al.json()) as Created).data?.item_id;\n      // 409 guard_failed \u2192 an open low_battery alert already exists; nothing to do.\n    }\n\n    return json({ reading_id: reading.item_id, alert_id }, 201);\n  },\n};\n\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n"
     }
   },
@@ -17212,9 +18234,12 @@ export default defineConfig({
     "id": "push-notifications",
     "title": "Push notifications",
     "vertical": "mobile",
-    "summary": "The part of push that actually breaks: the device registry. A cms collection with a unique token and an owner field, a function that re-owns a token instead of duplicating it when the handset changes hands, a per-device localized sender, and a nightly receipts cron that deletes the dead tokens your push service has already given up on.",
+    "summary": "The supported Expo path on vxil. The part of push that actually breaks is the device registry: a cms collection with a unique token and an owner field, a function that re-owns a token instead of duplicating it when the handset changes hands (from your backend at once, from the app through a claim and a server-mode hook), clean-up when a user is erased or deleted, a per-device localized sender with an hourly reminder ladder that honours opt-out and quiet hours, and a receipts cron that walks the whole registry and deletes the dead tokens your push service has already given up on.",
     "collections": [
-      "push_tokens"
+      "push_tokens",
+      "push_token_claims",
+      "push_prefs",
+      "push_state"
     ],
     "features": [
       "cms",
@@ -17222,174 +18247,12 @@ export default defineConfig({
     ],
     "hasFunctions": true,
     "byoKeys": [],
-    "configSrc": "import { defineConfig } from '@vxil/config';\n\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// \"Push notifications\" \u2014 DEVICE TOKENS DONE PROPERLY.\n//\n// Sending a push is the easy part: one HTTPS POST to your push service. What\n// actually breaks in production is the REGISTRY \u2014 the mapping from a user to\n// the devices they are currently holding. Tokens rotate, phones get sold, users\n// sign out and a colleague signs in on the same handset, and a token that once\n// belonged to Alice starts delivering Alice's notifications to Bob. That is a\n// privacy incident, not a bug.\n//\n// So this blueprint is a registry with three invariants and a small amount of\n// sending bolted on:\n//   1. ONE TOKEN, ONE USER \u2014 `token` is `unique`, enforced by the platform.\n//   2. RE-OWN ON CHANGE \u2014 a token that reappears under a different user is\n//      REASSIGNED, never duplicated.\n//   3. PRUNE STALE \u2014 the push service tells you when a token is dead; a cron\n//      collects those receipts and deletes the rows, so your registry shrinks.\n//\n//   \u2022 cms       \u2192 `push_tokens`: owner-scoped, `token` unique\n//   \u2022 functions \u2192 `register-token` (the registry), `send-push` (fan-out to the\n//                 push service through the egress allowlist), `prune-receipts`\n//                 (the daily garbage collector)\n//\n// Written against Expo's push service because it fronts BOTH APNs and FCM with\n// one token format. Swapping in raw FCM or APNs is a change to two constants\n// and the message body \u2014 see README.md.\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nexport default defineConfig({\n  env: 'staging',\n\n  features: {\n    cms: {\n      // Fail-safe: a verified end-user may only touch collections that declare\n      // an ownerField. `push_tokens` does, so a signed-in device can read and\n      // refresh its OWN rows and structurally cannot enumerate anyone else's.\n      strictEndUserScope: true,\n      hooks: {\n        // A row with no token is a row that can never receive anything.\n        token_present: {\n          collection: 'push_tokens',\n          event: 'beforeWrite',\n          kind: 'validate',\n          expr: 'len(item.token) > 0',\n          message: 'a push token is required',\n        },\n      },\n    },\n    functions: { enabled: true },\n  },\n\n  cms: {\n    collections: {\n      push_tokens: {\n        singular: 'push_token',\n        // Owner-scoped: an end-user session sees only its own devices.\n        ownerField: 'end_user',\n        fields: {\n          // \u2605 INVARIANT 1. `unique` is the TOP-LEVEL field attribute (there is no\n          // `validation.unique`). The platform backs it with a claims table, so a\n          // second registration of the same token is a 409 `unique_violation` \u2014\n          // atomically, under concurrency, without a read-then-write race.\n          // NOTE: a unique value is capped at 256 characters. Expo tokens\n          // (`ExponentPushToken[\u2026]`) and APNs device tokens are far inside that;\n          // if you switch to raw FCM registration tokens, store a hash here and\n          // keep the full token in an unindexed `text` field.\n          token: { type: 'string', required: true, indexSlot: 's1', unique: true },\n          end_user: { type: 'string', required: true, indexSlot: 's2' }, // the owner\n          platform: { type: 'string', indexSlot: 's3', validation: { enum: ['ios', 'android', 'web'] } },\n          // The device's language, captured at registration \u2014 this is what makes\n          // a localized push possible without a second lookup per device.\n          locale: { type: 'string', indexSlot: 's4' }, // 'en', 'ar', 'fr', \u2026\n          // The receipt id returned by the LAST send. `prune-receipts` trades it\n          // for a verdict and deletes the row when the service says the device\n          // is gone.\n          receipt_id: { type: 'string' },\n          // Consecutive delivery failures \u2014 a soft signal for your own dashboards\n          // (the authoritative kill signal is the receipt, not this counter).\n          failures: { type: 'int', indexSlot: 'n1', validation: { min: 0 } },\n          last_seen: { type: 'datetime', indexSlot: 't1' }, // last registration/refresh\n          checked_at: { type: 'datetime', indexSlot: 't2' }, // last receipt check\n          last_error: { type: 'text' },\n        },\n      },\n    },\n  },\n\n  functions: {\n    // THE REGISTRY. POST /v1/fn/register-token { token, user_id, platform, locale }.\n    // Call it from your app's authenticated backend (server mode) \u2014 that is where\n    // the re-own path lives, because reassigning a token away from another user\n    // needs tenant-wide read, which an end-user-mode invocation deliberately does\n    // not have. See README.md \xA7\"Why register-token is a server call\".\n    'register-token': {\n      entry: './functions/register-token.ts',\n      trigger: { kind: 'http' },\n      scopes: ['cms:read', 'cms:write'],\n      egressAllow: [], // pure vxil-internal\n    },\n\n    // THE SENDER. POST /v1/fn/send-push { user_ids, messages, data? } \u2014 resolves\n    // each user's live devices, picks the message for each device's locale, and\n    // posts to the push service in batches.\n    'send-push': {\n      entry: './functions/send-push.ts',\n      trigger: { kind: 'http' },\n      scopes: ['cms:read', 'cms:write'],\n      // Deny-by-default egress. `exp.host` is Expo's push host; `api.expo.dev`\n      // is its newer alias. For raw FCM use 'fcm.googleapis.com'; for APNs,\n      // 'api.push.apple.com' (and see README.md on the token-auth swap).\n      egressAllow: ['exp.host', 'api.expo.dev'],\n      // NO `secrets` here on purpose. Expo's push API needs no credential in its\n      // default configuration, and secret resolution is FAIL-CLOSED: a declared\n      // `secret:<name>` ref with no stored value makes every invocation\n      // `409 secret_missing` before your code runs. Declare a secret only once\n      // you will actually set it \u2014 see README.md \xA7\"If your push service needs a key\".\n    },\n\n    // \u2605 INVARIANT 3. THE GARBAGE COLLECTOR. A push service accepts a send and\n    // only later tells you the device was gone \u2014 that verdict arrives as a\n    // RECEIPT, not as the send response. This cron trades yesterday's receipt\n    // ids for verdicts and deletes the rows the service declared dead.\n    'prune-receipts': {\n      entry: './functions/prune-receipts.ts',\n      trigger: { kind: 'cron', schedule: '30 3 * * *' },\n      scopes: ['cms:read', 'cms:write'],\n      egressAllow: ['exp.host', 'api.expo.dev'],\n    },\n  },\n});\n",
-    "readme": "# Push notifications (mobile)\n\nSending a push is the easy part: one HTTPS POST to your push service. What breaks in production is the\n**registry** \u2014 the mapping from a user to the devices they are currently holding.\n\nTokens rotate. Phones get sold. A user signs out and a colleague signs in on the same handset. Unless\nsomething reassigns that token, the previous owner's notifications keep arriving on someone else's lock\nscreen \u2014 a privacy incident, not a bug. And nobody collects delivery **receipts**, so the registry only\never grows: dead tokens are re-sent to forever and delivery rates look worse than they are.\n\nThis blueprint is that registry, with three invariants, plus a small amount of sending.\n\n```bash\nvxil init --template push-notifications\nvxil quickstart                   # or `vxil link <slug>` for an existing backend\nvxil push                         # the push_tokens collection + three functions\n```\n\n## The three invariants\n\n| # | Invariant | Where it is enforced |\n|---|---|---|\n| **1** | **One token, one user** | `token: { unique: true }` \u2014 the *top-level* field attribute, backed by a claims table. A second registration of the same token is a `409 unique_violation`, atomically, with no read-then-write race. |\n| **2** | **Re-own on change** | `functions/register-token.ts` \u2014 on that 409 it looks the row up and **PATCHes the owner** with `If-Match`. Reassign, never duplicate. |\n| **3** | **Prune stale** | `functions/prune-receipts.ts` \u2014 a nightly cron trades yesterday's receipt ids for verdicts and **deletes** every row the service reports as `DeviceNotRegistered`. |\n\nThere is no `validation: { unique: true }` \u2014 that key does not exist and would be silently ignored.\nUniqueness is the top-level `unique` attribute, on scalar field types only.\n\n## The registry\n\n```ts\npush_tokens: {\n  ownerField: 'end_user',        // a signed-in device sees only its own rows\n  fields: {\n    token:    { type: 'string', required: true, indexSlot: 's1', unique: true },\n    end_user: { type: 'string', required: true, indexSlot: 's2' },\n    platform: { type: 'string', indexSlot: 's3' },  // ios | android | web\n    locale:   { type: 'string', indexSlot: 's4' },  // 'en', 'ar', 'pt-BR', \u2026\n    receipt_id: { type: 'string' },                 // the last send's pending verdict\n    failures:   { type: 'int', indexSlot: 'n1' },\n    last_seen:  { type: 'datetime', indexSlot: 't1' },\n    checked_at: { type: 'datetime', indexSlot: 't2' },\n    last_error: { type: 'text' },\n  },\n}\n```\n\n`strictEndUserScope: true` is on, so a verified end-user session may only touch collections that declare\nan `ownerField`. `push_tokens` does \u2014 a device can refresh **its own** rows and structurally cannot\nenumerate anyone else's.\n\n> **The 256-character cap.** A unique value is capped at 256 characters. Expo tokens\n> (`ExponentPushToken[\u2026]`) and APNs device tokens are far inside it. If you switch to raw **FCM\n> registration tokens**, store a hash in `token` and keep the full value in an unindexed `text` field \u2014\n> otherwise long tokens are rejected at write time.\n\n## Why `register-token` is a server call\n\n`POST /v1/fn/register-token { token, user_id, platform?, locale? }`\n\nInvariant 2 needs to reassign a token **away from another user**, which needs a tenant-wide read. A\nfunction invoked with a verified end-user session gets **owner-scoped** callback tokens \u2014 the platform\nstamps the principal onto every scoped token the function mints downstream \u2014 so in end-user mode the\nother user's row is simply invisible. That is the fail-safe working, not a gap.\n\nSo: call `register-token` from your app's authenticated backend. If you do invoke it in end-user mode,\ntwo things happen, both deliberate:\n\n- the **verified** `end_user.id` overrides any `user_id` in the body \u2014 a client can never register a\n  token against someone else's account;\n- the cross-owner hand-off returns `409 token_owned_by_another_user` instead of silently doing nothing.\n\nResponses: `201 {action:'created'}`, `200 {action:'reowned', previous_owner}`, `200 {action:'refreshed'}`.\n\n## Sending \u2014 localized per device, not per user\n\n`POST /v1/fn/send-push`\n\n```json\n{\n  \"user_ids\": [\"usr_a\", \"usr_b\"],\n  \"messages\": {\n    \"default\": { \"title\": \"You're in\", \"body\": \"Pro is active on this device.\" },\n    \"ar\":      { \"title\": \"\u062A\u0645 \u0627\u0644\u062A\u0641\u0639\u064A\u0644\", \"body\": \"\u0623\u0635\u0628\u062D \u0627\u0634\u062A\u0631\u0627\u0643 Pro \u0645\u0641\u0639\u0651\u0644\u0627\u064B.\" },\n    \"fr\":      { \"title\": \"C'est actif\", \"body\": \"Pro est activ\xE9 sur cet appareil.\" }\n  },\n  \"data\": { \"screen\": \"billing\" }\n}\n```\n\nOne person can carry an English phone and an Arabic tablet. Because `locale` lives on the **token row**,\neach device gets the right copy with no extra lookup \u2014 exact match (`pt-BR`), then the base language\n(`pt`), then `default`.\n\nThe response distinguishes the two failure kinds, because they call for opposite actions:\n\n- an **immediate** `DeviceNotRegistered` \u2192 the token is dead now; the row is deleted;\n- anything else (rate limits, a message too big, a transient fault) \u2192 counted in `failures`, device kept.\n  Deleting a device because one message was malformed is how a registry loses real users.\n- an **accepted** message returns a *receipt id*, not a delivery. That id is parked on the row, and the\n  real verdict is collected by the cron below.\n\n## The receipts cron \u2014 the loop almost nobody closes\n\n`prune-receipts` runs at `30 3 * * *`: it pages `push_tokens`, collects the rows carrying a `receipt_id`,\nasks the push service for those receipts in batches, and acts \u2014 `ok` clears the id, `DeviceNotRegistered`\ndeletes the row, anything else counts a failure and keeps the device. A receipt that is not ready yet is\nsimply absent from the response, which is not an error; it is checked again tomorrow.\n\nEverything is bounded: at most 2 000 rows and a handful of outbound calls per tick. A larger registry is\npruned over several nights, which is fine \u2014 a dead token costs one wasted message a day, not correctness.\n\n> **A paging detail worth stealing.** The cron pages with `?cursor=` and **no** `?sort=`. cms cursor\n> pagination works with the default sort only; pairing `?cursor=` with a `?sort=` is a clean `422`, and\n> `next_cursor` is not emitted for a custom sort at all. When you need to walk *everything*, take the\n> default order.\n\n## Example: post-purchase push on `payments.entitlement.changed`\n\nThe payments feature writes `payments.entitlement.changed` to your audit stream on every entitlement\ntransition, carrying `end_user_id`, the previous and new tier, `status`, `until`, `reason` and\n`environment`. Turning that into \"your Pro plan is live, in the language of the device\" is a wiring\nexercise, not new code \u2014 there are two shapes, both using the same `send-push` call:\n\n**(a) Subscribe and call in.** Outbound subscriptions are runtime rows, not config:\n\n```bash\ncurl -X POST https://api.vxil.com/v1/webhooks/subscriptions \\\n  -H \"authorization: Bearer $VXIL_API_KEY\" -H 'content-type: application/json' \\\n  -d '{\"target_url\":\"https://your-app.example.com/hooks/vxil\",\"event_prefixes\":[\"payments.entitlement.\"]}'\n```\n\nYour endpoint verifies the signed delivery, then calls `send-push` with a key holding\n`functions:invoke`:\n\n```ts\n// inside your webhook receiver \u2014 event.payload.end_user_id / .tier are the fields above\nawait fetch('https://api.vxil.com/v1/fn/send-push', {\n  method: 'POST',\n  headers: { authorization: `Bearer ${process.env.VXIL_API_KEY}`, 'content-type': 'application/json' },\n  body: JSON.stringify({\n    user_ids: [event.payload.end_user_id],\n    messages: {\n      default: { title: 'You\\'re in', body: `${event.payload.tier} is active on this device.` },\n      ar: { title: '\u062A\u0645 \u0627\u0644\u062A\u0641\u0639\u064A\u0644', body: `\u062A\u0645 \u062A\u0641\u0639\u064A\u0644 ${event.payload.tier} \u0639\u0644\u0649 \u0647\u0630\u0627 \u0627\u0644\u062C\u0647\u0627\u0632.` },\n    },\n    data: { screen: 'billing', tier: event.payload.tier },\n  }),\n});\n```\n\n**(b) Drain the audit stream on a cron.** If you would rather keep everything inside your backend, the\nwatermark-plus-allow-list pattern in [`templates/alerts-to-slack`](../alerts-to-slack) reads the same\nevents with `GET /v1/audit/export?after_id=\u2026` and needs no public endpoint at all. Same events, no\ninbound surface.\n\nWhichever you pick, send on the **`from_tier \u2192 tier` crossing**, not on every event: entitlement snapshots\nare refolded on redelivery, and \"Pro is active\" three times is how an app gets its notifications muted.\n\n## Swapping the push service\n\nThe blueprint targets Expo because it fronts **both** APNs and FCM with one token format. To swap:\n\n| Service | `PUSH_URL` | `egressAllow` | Also change |\n|---|---|---|---|\n| Expo (default) | `https://exp.host/--/api/v2/push/send` | `exp.host`, `api.expo.dev` | \u2014 |\n| FCM (HTTP v1) | the HTTP v1 send method under `https://fcm.googleapis.com/v1/projects/<id>/` \u2014 the exact URL is in `functions/send-push.ts` | `fcm.googleapis.com` | one message per request; an OAuth bearer; the `message.notification` body shape; hash long tokens (see the 256-char cap above) |\n| APNs | `https://api.push.apple.com/3/device/<token>` | `api.push.apple.com` | one request per device; a JWT `authorization`; an `apns-topic` header; the `aps` payload shape |\n\n### If your push service needs a key\n\nAdd the ref to the function and set the value:\n\n```ts\n'send-push': { /* \u2026 */ secrets: ['secret:push_api_key'] }\n```\n```bash\nprintf '%s' \"$KEY\" | vxil secrets set functions/push_api_key\n```\n\nIt resolves per invocation as `envelope.secrets.push_api_key`, so **rotating it needs no redeploy**. One\nwarning: resolution is **fail-closed**. A declared `secret:<name>` ref with no stored value makes every\ninvocation `409 secret_missing` before your code runs \u2014 which is why this blueprint declares no secrets\nat all by default. Declare one only when you will actually set it.\n\n## What to learn from this\n\n- **The hard part of push is ownership, not delivery.** A `unique` field plus one re-own path is the\n  whole difference between a registry that stays correct and one that leaks notifications between users.\n- **A verified principal beats a body field, always.** The platform hands the function `end_user.id`; the\n  request body is a suggestion.\n- **Delete on the verdict, not on the error.** `DeviceNotRegistered` is the only signal that justifies\n  removing a device. Everything else is about the message.\n\n**Pairs with:** [`templates/alerts-to-slack`](../alerts-to-slack) for the audit-stream drain used in\nexample (b).\n",
+    "configSrc": "import { defineConfig } from '@vxil/config';\n\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// \"Push notifications\" \u2014 DEVICE TOKENS DONE PROPERLY.\n//\n// Sending a push is the easy part: one HTTPS POST to your push service. What\n// actually breaks in production is the REGISTRY \u2014 the mapping from a user to\n// the devices they are currently holding. Tokens rotate, phones get sold, users\n// sign out and a colleague signs in on the same handset, and a token that once\n// belonged to Alice starts delivering Alice's notifications to Bob. That is a\n// privacy incident, not a bug.\n//\n// So this blueprint is a registry with three invariants and a small amount of\n// sending bolted on \u2014 and it is THE supported Expo path on vxil (guide 17):\n//   1. ONE TOKEN, ONE USER \u2014 `token` is `unique`, enforced by the platform.\n//   2. RE-OWN ON CHANGE \u2014 a token that reappears under a different user is\n//      REASSIGNED, never duplicated. From your backend (server mode) that is\n//      immediate; from the app itself (end-user mode, which cannot see another\n//      user's row) it is ASYNC: a claim row + a server-mode cmsHook.\n//   3. PRUNE STALE \u2014 the push service tells you when a token is dead; a cron\n//      collects those receipts and deletes the rows, so your registry shrinks.\n//      It walks the WHOLE registry over successive ticks (a persisted cursor).\n// Plus the two things every consumer app ends up writing:\n//   \u2022 ERASURE \u2014 a user erased under GDPR (auth.user.erased / user.erased) or\n//     deleted (user.deleted) loses every device row, claim and preferences\n//     row \u2014 never on session.revoked, which fires on every refresh.\n//   \u2022 A REMINDER LADDER \u2014 an hourly cron nudging inactive users (1 d, 3 d, 7 d),\n//     honouring each user's opt-out and quiet hours in THEIR time zone.\n//\n//   \u2022 cms       \u2192 `push_tokens` (owner-scoped, `token` unique), `push_token_claims`\n//                 (an app's async re-own request), `push_prefs` (reminders,\n//                 time zone, quiet hours, last activity), `push_state` (cursors)\n//   \u2022 functions \u2192 `register-token` (the registry: http + the claim cmsHook + the\n//                 erasure webhooks), `send-push` (http send + the hourly ladder\n//                 cron), `prune-receipts` (the receipts cron)\n//\n// Three functions and two crons (the fastest hourly) on purpose: that is inside\n// the Free plan's function limits for staging and development projects (guide\n// 12 has the per-plan table), so the whole kit runs on a free project while\n// you build the app. Every tick is bounded and resumable, so a tick the plan\n// sheds is harmless: the next one picks up where the last stopped.\n//\n// Written against Expo's push service because it fronts BOTH APNs and FCM with\n// one token format. Swapping in raw FCM or APNs is a change to two constants\n// and the message body \u2014 see README.md.\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nexport default defineConfig({\n  env: 'staging',\n\n  features: {\n    cms: {\n      // Fail-safe: a verified end-user may only touch collections that declare\n      // an ownerField. `push_tokens` does, so a signed-in device can read and\n      // refresh its OWN rows and structurally cannot enumerate anyone else's.\n      strictEndUserScope: true,\n      hooks: {\n        // A row with no token is a row that can never receive anything.\n        token_present: {\n          collection: 'push_tokens',\n          event: 'beforeWrite',\n          kind: 'validate',\n          expr: 'len(item.token) > 0',\n          message: 'a push token is required',\n        },\n        // The ladder walk filters on `ladder_step < 3` (a slot compare, which\n        // never matches an absent value), so every prefs row carries one: a\n        // write that leaves it out gets 0.\n        ladder_step_default: {\n          collection: 'push_prefs',\n          event: 'beforeWrite',\n          kind: 'derive',\n          field: 'ladder_step',\n          expr: 'coalesce(item.ladder_step, 0)',\n        },\n      },\n    },\n    functions: { enabled: true },\n  },\n\n  cms: {\n    collections: {\n      push_tokens: {\n        singular: 'push_token',\n        // Owner-scoped: an end-user session sees only its own devices.\n        ownerField: 'end_user',\n        fields: {\n          // \u2605 INVARIANT 1. `unique` is the TOP-LEVEL field attribute (there is no\n          // `validation.unique`). The platform backs it with a claims table, so a\n          // second registration of the same token is a 409 `unique_violation` \u2014\n          // atomically, under concurrency, without a read-then-write race.\n          // NOTE: a unique value is capped at 256 characters. Expo tokens\n          // (`ExponentPushToken[\u2026]`) and APNs device tokens are far inside that;\n          // if you switch to raw FCM registration tokens, store a hash here and\n          // keep the full token in an unindexed `text` field.\n          token: { type: 'string', required: true, indexSlot: 's1', unique: true },\n          end_user: { type: 'string', required: true, indexSlot: 's2' }, // the owner\n          platform: { type: 'string', indexSlot: 's3', validation: { enum: ['ios', 'android', 'web'] } },\n          // The device's language, captured at registration \u2014 this is what makes\n          // a localized push possible without a second lookup per device.\n          locale: { type: 'string', indexSlot: 's4' }, // 'en', 'ar', 'fr', \u2026\n          // The receipt id returned by the LAST send. `prune-receipts` trades it\n          // for a verdict and deletes the row when the service says the device\n          // is gone.\n          receipt_id: { type: 'string' },\n          // When that receipt id was parked. The push service keeps a receipt\n          // for a limited time; past RECEIPT_MAX_AGE the id is cleared as\n          // unknowable instead of being asked about forever.\n          receipt_at: { type: 'datetime' },\n          // Consecutive delivery failures \u2014 a soft signal for your own dashboards\n          // (the authoritative kill signal is the receipt, not this counter).\n          failures: { type: 'int', indexSlot: 'n1', validation: { min: 0 } },\n          last_seen: { type: 'datetime', indexSlot: 't1' }, // last registration/refresh\n          checked_at: { type: 'datetime', indexSlot: 't2' }, // last receipt check\n          last_error: { type: 'text' },\n        },\n      },\n\n      // \u2605 INVARIANT 2, the app's half. An end-user session cannot see \u2014 let\n      // alone re-own \u2014 a row that belongs to someone else, so when the app\n      // registers a token another user holds, `register-token` files a CLAIM\n      // here (owned by the caller) and answers 202. The `register-token`\n      // cmsHook binding then runs in SERVER mode, moves the token, and deletes\n      // the claim. Usually done within seconds.\n      push_token_claims: {\n        singular: 'push_token_claim',\n        ownerField: 'end_user',\n        fields: {\n          token: { type: 'string', required: true, indexSlot: 's1' },\n          end_user: { type: 'string', required: true, indexSlot: 's2' },\n          platform: { type: 'string', indexSlot: 's3', validation: { enum: ['ios', 'android', 'web'] } },\n          locale: { type: 'string', indexSlot: 's4' },\n        },\n      },\n\n      // The reminder ladder's per-user state. Owner-scoped: the app reads and\n      // writes its OWN row (opt out, set quiet hours, stamp `last_active` and\n      // reset `ladder_step` to 0 whenever the app comes to the foreground).\n      push_prefs: {\n        singular: 'push_pref',\n        ownerField: 'end_user',\n        fields: {\n          end_user: { type: 'string', required: true, indexSlot: 's1', unique: true },\n          // IANA zone ('Asia/Riyadh'); quiet hours are evaluated in it. An\n          // unknown zone is treated as UTC.\n          timezone: { type: 'string', indexSlot: 's2' },\n          // false = no reminders at all (absent = reminders on).\n          reminders: { type: 'bool' },\n          // Local hours [quiet_start, quiet_end) during which nothing is sent;\n          // the window may wrap midnight (22 \u2192 8). Equal values = no quiet hours.\n          quiet_start: { type: 'int', validation: { min: 0, max: 23 } },\n          quiet_end: { type: 'int', validation: { min: 0, max: 23 } },\n          last_active: { type: 'datetime', indexSlot: 't1' },\n          // The next rung (0..3) since `last_active` (the app resets it to 0; the\n          // `ladder_step_default` derive writes 0 when a write leaves it out).\n          ladder_step: { type: 'int', indexSlot: 'n1', validation: { min: 0 } },\n          last_reminded_at: { type: 'datetime', indexSlot: 't2' },\n        },\n      },\n\n      // Where each cron left off (`key` = the job). No ownerField, so with\n      // `strictEndUserScope` an end-user session cannot touch it at all.\n      push_state: {\n        singular: 'push_state',\n        fields: {\n          key: { type: 'string', required: true, indexSlot: 's1', unique: true },\n          // the last item id walked; '' = start again from the newest row\n          cursor: { type: 'string' },\n          updated_at: { type: 'datetime', indexSlot: 't1' },\n        },\n      },\n    },\n  },\n\n  functions: {\n    // THE REGISTRY \u2014 one bundle, five front doors (a function is code + a SET\n    // of trigger bindings):\n    //   \u2022 http     POST /v1/fn/register-token { token, user_id?, platform?, locale? }\n    //              server mode (your backend) re-owns at once; end-user mode\n    //              (the app) files a claim for a token someone else holds \u2192 202.\n    //   \u2022 cmsHook  a new `push_token_claims` row \u2192 re-own it in SERVER mode,\n    //              delete the claim. `retry` re-delivers a failed attempt.\n    //   \u2022 webhook  `auth.user.erased` (the auth erase), `user.erased` (the\n    //              admin erase) and `user.deleted` (the admin delete) \u2192 delete\n    //              every device row, claim and preferences row of that user.\n    //              NOT `auth.session.revoked`: that fires on every refresh-token\n    //              rotation, and would sign devices out of push at random.\n    'register-token': {\n      entry: './functions/register-token.ts',\n      trigger: { kind: 'http' },\n      triggers: [\n        { kind: 'cmsHook', collection: 'push_token_claims', event: 'beforeCreate', retry: { maxAttempts: 3 } },\n        { kind: 'webhook', source: 'auth.user.erased', retry: { maxAttempts: 3 } },\n        { kind: 'webhook', source: 'user.erased', retry: { maxAttempts: 3 } },\n        { kind: 'webhook', source: 'user.deleted', retry: { maxAttempts: 3 } },\n      ],\n      scopes: ['cms:read', 'cms:write'],\n      egressAllow: [], // pure vxil-internal\n    },\n\n    // THE SENDER \u2014 two front doors:\n    //   \u2022 http  POST /v1/fn/send-push { user_ids, messages, data? } \u2014 resolves\n    //           each user's live devices, picks the message for each device's\n    //           locale, and posts to the push service in batches.\n    //   \u2022 cron  hourly: THE REMINDER LADDER. Users inactive 1 d / 3 d / 7 d get\n    //           at most one nudge per step (a user found already a week idle gets\n    //           only the 7-day one), never during their quiet hours, never after\n    //           opting out. Each step is claimed (If-Match) BEFORE the send, so\n    //           an overlapping tick can never send it twice.\n    'send-push': {\n      entry: './functions/send-push.ts',\n      trigger: { kind: 'http' },\n      triggers: [{ kind: 'cron', schedule: '0 * * * *' }],\n      scopes: ['cms:read', 'cms:write'],\n      // Deny-by-default egress. `exp.host` is Expo's push host; `api.expo.dev`\n      // is its newer alias. For raw FCM use 'fcm.googleapis.com'; for APNs,\n      // 'api.push.apple.com' (and see README.md on the token-auth swap).\n      egressAllow: ['exp.host', 'api.expo.dev'],\n      // NO `secrets` here on purpose. Expo's push API needs no credential in its\n      // default configuration, and secret resolution is FAIL-CLOSED: a declared\n      // `secret:<name>` ref with no stored value makes every invocation\n      // `409 secret_missing` before your code runs. Declare a secret only once\n      // you will actually set it \u2014 see README.md \xA7\"If your push service needs a key\".\n    },\n\n    // \u2605 INVARIANT 3. THE GARBAGE COLLECTOR. A push service accepts a send and\n    // only later tells you the device was gone \u2014 that verdict arrives as a\n    // RECEIPT, not as the send response. Every 6 hours this cron trades parked\n    // receipt ids for verdicts and deletes the rows the service declared dead.\n    // It resumes where the last tick stopped (`push_state`), so a registry of\n    // any size is walked end to end.\n    'prune-receipts': {\n      entry: './functions/prune-receipts.ts',\n      trigger: { kind: 'cron', schedule: '30 */6 * * *' },\n      scopes: ['cms:read', 'cms:write'],\n      egressAllow: ['exp.host', 'api.expo.dev'],\n    },\n  },\n});\n",
+    "readme": "# Push notifications (mobile)\n\nSending a push is the easy part: one HTTPS POST to your push service. What breaks in production is the\n**registry** \u2014 the mapping from a user to the devices they are currently holding.\n\nTokens rotate. Phones get sold. A user signs out and a colleague signs in on the same handset. Unless\nsomething reassigns that token, the previous owner's notifications keep arriving on someone else's lock\nscreen \u2014 a privacy incident, not a bug. And nobody collects delivery **receipts**, so the registry only\never grows: dead tokens are re-sent to forever and delivery rates look worse than they are.\n\nThis blueprint is that registry, with three invariants, plus the sending, the erasure clean-up and the\nre-engagement ladder every consumer app ends up writing. It is **the supported Expo path on vxil** \u2014\nvxil holds no push credential and runs no push service; your functions call Expo (which fronts APNs and\nFCM) through the egress allowlist. The whole mobile picture is in\n[guide 17 \u2014 vxil for Expo apps](../../docs/guide/17-mobile-apps-with-expo.md).\n\n```bash\nvxil init --template push-notifications\nvxil quickstart                   # or `vxil link <slug>` for an existing backend\nvxil push                         # four collections + three functions (two of them crons)\n```\n\nThree functions and two crons (the fastest hourly) on purpose: that is inside the Free plan's function\nlimits for staging and development projects (the per-plan table is in guide 12), so a free project runs\nall of it while you build the app. Every cron tick is bounded and resumable, so a tick the plan sheds is\nharmless \u2014 the next one picks up where the last stopped.\n\n## The three invariants\n\n| # | Invariant | Where it is enforced |\n|---|---|---|\n| **1** | **One token, one user** | `token: { unique: true }` \u2014 the *top-level* field attribute, backed by a claims table. A second registration of the same token is a `409 unique_violation`, atomically, with no read-then-write race. |\n| **2** | **Re-own on change** | `functions/register-token.ts` \u2014 on that 409 it looks the row up and **PATCHes the owner** with `If-Match`. Reassign, never duplicate. From the app itself (end-user mode) the move is **async**: a claim row + a server-mode `cmsHook` (below). |\n| **3** | **Prune stale** | `functions/prune-receipts.ts` \u2014 a cron every 6 hours trades parked receipt ids for verdicts and **deletes** every row the service reports as `DeviceNotRegistered`. It resumes where the last tick stopped, so the **whole** registry is walked, whatever its size. |\n\nThere is no `validation: { unique: true }` \u2014 that key does not exist and would be silently ignored.\nUniqueness is the top-level `unique` attribute, on scalar field types only.\n\n## The registry\n\n```ts\npush_tokens: {\n  ownerField: 'end_user',        // a signed-in device sees only its own rows\n  fields: {\n    token:    { type: 'string', required: true, indexSlot: 's1', unique: true },\n    end_user: { type: 'string', required: true, indexSlot: 's2' },\n    platform: { type: 'string', indexSlot: 's3' },  // ios | android | web\n    locale:   { type: 'string', indexSlot: 's4' },  // 'en', 'ar', 'pt-BR', \u2026\n    receipt_id: { type: 'string' },                 // the last send's pending verdict\n    receipt_at: { type: 'datetime' },               // when it was parked (48 h \u2192 cleared)\n    failures:   { type: 'int', indexSlot: 'n1' },\n    last_seen:  { type: 'datetime', indexSlot: 't1' },\n    checked_at: { type: 'datetime', indexSlot: 't2' },\n    last_error: { type: 'text' },\n  },\n}\n```\n\nBeside it: `push_token_claims` (the app's async re-own requests, owner-scoped), `push_prefs` (one row per\nuser for the reminder ladder, owner-scoped, `end_user` unique) and `push_state` (each cron's cursor \u2014 no\n`ownerField`, so no end-user session can touch it).\n\n`strictEndUserScope: true` is on, so a verified end-user session may only touch collections that declare\nan `ownerField`. `push_tokens` does \u2014 a device can refresh **its own** rows and structurally cannot\nenumerate anyone else's.\n\n> **The 256-character cap.** A unique value is capped at 256 characters. Expo tokens\n> (`ExponentPushToken[\u2026]`) and APNs device tokens are far inside it. If you switch to raw **FCM\n> registration tokens**, store a hash in `token` and keep the full value in an unindexed `text` field \u2014\n> otherwise long tokens are rejected at write time.\n\n## Registering \u2014 from your backend or from the app\n\n`POST /v1/fn/register-token { token, user_id?, platform?, locale? }`\n\nInvariant 2 needs to reassign a token **away from another user**, which needs a tenant-wide read. A\nfunction invoked with a verified end-user session gets **owner-scoped** callback tokens \u2014 the platform\nstamps the principal onto every scoped token the function mints downstream \u2014 so in end-user mode the\nother user's row is simply invisible. That is the fail-safe working, not a gap. So there are two paths:\n\n| Called from | `user_id` | A token another user holds | Response |\n|---|---|---|---|\n| **your backend** (server key) | from the body | re-owned at once (`If-Match`) | `200 {action:'reowned', previous_owner}` |\n| **the app** (end-user session) | the **verified** session id \u2014 a body `user_id` is ignored | a **claim** row in `push_token_claims`, owned by the caller | `202 {action:'reown_queued', claim_id}` |\n\nEither way a new token is `201 {action:'created'}` and an unchanged owner is `200 {action:'refreshed'}`.\n\n**The async re-own.** `register-token` declares a second binding,\n`{ kind: 'cmsHook', collection: 'push_token_claims', event: 'beforeCreate', retry: { maxAttempts: 3 } }`.\nA platform-delivered hook carries **no** end-user, so it runs in server mode: it re-reads the claim,\nre-owns the token row for the claimant (or creates it, if the old holder deleted it meanwhile), and\ndeletes the claim. It usually lands within seconds; a failed attempt answers non-2xx and the `retry`\nre-delivers it, and every step is idempotent (a claim that is already gone is done).\n\n**What a claim can and cannot do.** A claim can only name its caller as the new owner (the platform\nstamps the verified owner on the row), and a push token is a bearer credential only the device itself is\nhanded by the OS. Claiming a token you do not hold moves **your** notifications to that device \u2014 no data\nreaches you. The trade-off to know about is availability: a signed-in user who somehow learned another\nuser's Expo token could move that device away from its owner, who then stops receiving pushes (security\nalerts included) until their app starts again and re-registers it. Tokens are not shown to other users\nby anything in this kit, so that needs the token to have leaked. If your app treats pushes as critical,\nadd a `validate` hook on `push_token_claims` that caps open claims, or have the app re-register on every\nforeground (it is idempotent \u2014 `200 {action:'refreshed'}` costs one write).\n\n**Sign-out.** A device that signs out should stop receiving the old user's pushes before anyone else\nsigns in: delete the device's own row from the app (`DELETE /v1/cms/items/push_tokens/{item_id}` with\nthe session \u2014 an owner may delete its own rows), or just let the next sign-in re-own it.\n\n## Erasure and deletion \u2014 `auth.user.erased`, not `session.revoked`\n\n`register-token` also binds `{ kind: 'webhook', source: 'auth.user.erased' }`,\n`{ kind: 'webhook', source: 'user.erased' }` (the admin `DELETE /v1/users/{id}?erase=true`) and\n`{ kind: 'webhook', source: 'user.deleted' }` (the admin delete without erase). That user loses every\n`push_tokens` row, pending claim and their `push_prefs` row (time zone, quiet hours, activity) \u2014 device\ntokens and preferences are personal data, vxil's erasure scrubs its own tables, not your collections,\nand a deleted account must stop receiving reminder nudges.\n\nA **merge or rekey** (`auth.user.merged` / `auth.user.rekeyed` \u2014 a guest becoming a registered user)\nneeds no binding: the app's next start registers its token under the new id, which re-owns the device.\nThe old id's prefs row goes quiet on its own (it has no devices left to nudge).\n\nDo **not** clean up on `auth.session.revoked`: it fires on every refresh-token rotation as well as on\nsign-out, so a cleanup bound to it would unregister devices at random.\n\n## Sending \u2014 localized per device, not per user\n\n`POST /v1/fn/send-push`\n\n```json\n{\n  \"user_ids\": [\"usr_a\", \"usr_b\"],\n  \"messages\": {\n    \"default\": { \"title\": \"You're in\", \"body\": \"Pro is active on this device.\" },\n    \"ar\":      { \"title\": \"\u062A\u0645 \u0627\u0644\u062A\u0641\u0639\u064A\u0644\", \"body\": \"\u0623\u0635\u0628\u062D \u0627\u0634\u062A\u0631\u0627\u0643 Pro \u0645\u0641\u0639\u0651\u0644\u0627\u064B.\" },\n    \"fr\":      { \"title\": \"C'est actif\", \"body\": \"Pro est activ\xE9 sur cet appareil.\" }\n  },\n  \"data\": { \"screen\": \"billing\" }\n}\n```\n\nOne person can carry an English phone and an Arabic tablet. Because `locale` lives on the **token row**,\neach device gets the right copy with no extra lookup \u2014 exact match (`pt-BR`), then the base language\n(`pt`), then `default`.\n\nThe response distinguishes the two failure kinds, because they call for opposite actions:\n\n- an **immediate** `DeviceNotRegistered` \u2192 the token is dead now; the row is deleted;\n- anything else (rate limits, a message too big, a transient fault) \u2192 counted in `failures`, device kept.\n  Deleting a device because one message was malformed is how a registry loses real users.\n- an **accepted** message returns a *receipt id*, not a delivery. That id is parked on the row, and the\n  real verdict is collected by the cron below.\n\n## The receipts cron \u2014 the loop almost nobody closes\n\n`prune-receipts` runs at `30 */6 * * *`. It resumes the walk of `push_tokens` where the previous tick\nstopped (its cursor lives in `push_state`), collects the rows carrying a `receipt_id`, asks the push\nservice for those receipts in batches, and acts \u2014 `ok` clears the id, `DeviceNotRegistered` deletes the\nrow, anything else counts a failure and keeps the device. A receipt that is not ready yet is simply\nabsent from the response, which is not an error; it is asked again on the next walk. A receipt id parked\nfor more than 48 hours with no answer is cleared \u2014 the service no longer keeps it, and asking forever\nwould pin the row.\n\nEverything is bounded: one tick reads at most 2,000 rows and acts on at most 300, so its outbound calls\nstay in the low hundreds. Because the cursor persists, a registry of **any** size is walked end to end\nover successive ticks; when the walk reaches the oldest row the cursor resets and the next tick starts\nagain from the newest (rows registered during a walk are covered by the next one).\n\n> **A paging detail worth stealing.** The cron pages with `?cursor=` and **no** `?sort=`. In the\n> default order (newest first) the cursor is a plain item id, so it stays valid across ticks \u2014 persist it\n> and the walk resumes exactly where it stopped.\n\n**Never clears a newer receipt.** Each clear is a `PATCH` with `If-Match` on the row version the walk\nread. If `send-push` parked a newer receipt id on the same device in between, the clear is refused and\ncounted as `raced`; the newer id is checked on the next walk.\n\n## The reminder ladder \u2014 re-engagement that respects the user\n\n`send-push` has a second binding, `{ kind: 'cron', schedule: '0 * * * *' }`. Every hour it nudges users\nwho stopped opening the app: once after **1 day**, once after **3**, once after **7** \u2014 then silence until\nthey come back. The copy lives in the `LADDER` constant at the top of `functions/send-push.ts` (per\nlocale, picked per device like any send).\n\nIt reads `push_prefs`, a row per user **the app writes itself** (owner-scoped):\n\n| Field | Meaning |\n|---|---|\n| `reminders` | `false` = never. Absent = on. |\n| `timezone` | IANA zone (`Asia/Riyadh`); quiet hours are evaluated in it. Unknown = UTC. |\n| `quiet_start`, `quiet_end` | local hours `[start, end)` with nothing sent; may wrap midnight (`22` \u2192 `8`). Equal = none. |\n| `last_active` | stamp it whenever the app comes to the foreground\u2026 |\n| `ladder_step` | \u2026and reset this to `0` at the same time. The cron advances it. Left out on a write, a `derive` hook stores `0`. |\n\n```ts\n// in the app, on AppState 'active' (end-user session)\nawait vx.from('push_prefs').patch(prefsId, { last_active: new Date().toISOString(), ladder_step: 0 });\n```\n\nThree guarantees:\n\n- **Only idle users are read.** The walk filters on `last_active` and `ladder_step < 3` (both indexed),\n  so active users and users who finished the ladder cost nothing; it resumes where the last tick stopped\n  (`push_state`), reading at most 2,000 rows and nudging at most 100 users per tick. Users who opted out\n  are still read (an absent `reminders` means on, which a filter cannot express) and skipped.\n- **Never twice, never a burst.** Each step is claimed on the prefs row with `If-Match` **before** the\n  send \u2014 two overlapping ticks cannot both send it. A send that fails after the claim is a missed nudge,\n  never a duplicate one. When several rungs are due at once (the kit added to a live app, reminders\n  turned back on, a cron that was held), only the **highest** is sent and the ones below are skipped; and\n  a rung waits its own gap after the previous nudge (`last_reminded_at`), so the 3-day and 7-day nudges\n  stay two and four days after the one before.\n- **Never at night.** A user inside their quiet hours is skipped and picked up by a later tick once the\n  window has passed (the next one, unless the walk spans more than one tick).\n\n## Example: post-purchase push on `payments.entitlement.changed`\n\nThe payments feature writes `payments.entitlement.changed` to your audit stream on every entitlement\ntransition, carrying `end_user_id`, the previous and new tier, `status`, `until`, `reason` and\n`environment`. Turning that into \"your Pro plan is live, in the language of the device\" is a wiring\nexercise, not new code \u2014 there are two shapes, both using the same `send-push` call:\n\n**(a) Subscribe and call in.** Outbound subscriptions are runtime rows, not config:\n\n```bash\ncurl -X POST https://api.vxil.com/v1/webhooks/subscriptions \\\n  -H \"authorization: Bearer $VXIL_API_KEY\" -H 'content-type: application/json' \\\n  -d '{\"target_url\":\"https://your-app.example.com/hooks/vxil\",\"event_prefixes\":[\"payments.entitlement.\"]}'\n```\n\nYour endpoint verifies the signed delivery, then calls `send-push` with a key holding\n`functions:invoke`:\n\n```ts\n// inside your webhook receiver \u2014 event.payload.end_user_id / .tier are the fields above\nawait fetch('https://api.vxil.com/v1/fn/send-push', {\n  method: 'POST',\n  headers: { authorization: `Bearer ${process.env.VXIL_API_KEY}`, 'content-type': 'application/json' },\n  body: JSON.stringify({\n    user_ids: [event.payload.end_user_id],\n    messages: {\n      default: { title: 'You\\'re in', body: `${event.payload.tier} is active on this device.` },\n      ar: { title: '\u062A\u0645 \u0627\u0644\u062A\u0641\u0639\u064A\u0644', body: `\u062A\u0645 \u062A\u0641\u0639\u064A\u0644 ${event.payload.tier} \u0639\u0644\u0649 \u0647\u0630\u0627 \u0627\u0644\u062C\u0647\u0627\u0632.` },\n    },\n    data: { screen: 'billing', tier: event.payload.tier },\n  }),\n});\n```\n\n**(b) Drain the audit stream on a cron.** If you would rather keep everything inside your backend, the\nwatermark-plus-allow-list pattern in [`templates/alerts-to-slack`](../alerts-to-slack) reads the same\nevents with `GET /v1/audit/export?after_id=\u2026` and needs no public endpoint at all. Same events, no\ninbound surface.\n\nWhichever you pick, send on the **`from_tier \u2192 tier` crossing**, not on every event: entitlement snapshots\nare refolded on redelivery, and \"Pro is active\" three times is how an app gets its notifications muted.\n\n## Swapping the push service\n\nThe blueprint targets Expo because it fronts **both** APNs and FCM with one token format. To swap:\n\n| Service | `PUSH_URL` | `egressAllow` | Also change |\n|---|---|---|---|\n| Expo (default) | `https://exp.host/--/api/v2/push/send` | `exp.host`, `api.expo.dev` | \u2014 |\n| FCM (HTTP v1) | the HTTP v1 send method under `https://fcm.googleapis.com/v1/projects/<id>/` \u2014 the exact URL is in `functions/send-push.ts` | `fcm.googleapis.com` | one message per request; an OAuth bearer; the `message.notification` body shape; hash long tokens (see the 256-char cap above) |\n| APNs | `https://api.push.apple.com/3/device/<token>` | `api.push.apple.com` | one request per device; a JWT `authorization`; an `apns-topic` header; the `aps` payload shape |\n\n### If your push service needs a key\n\nAdd the ref to the function and set the value:\n\n```ts\n'send-push': { /* \u2026 */ secrets: ['secret:push_api_key'] }\n```\n```bash\nprintf '%s' \"$KEY\" | vxil secrets set functions/push_api_key\n```\n\nIt resolves per invocation as `envelope.secrets.push_api_key`, so **rotating it needs no redeploy**. One\nwarning: resolution is **fail-closed**. A declared `secret:<name>` ref with no stored value makes every\ninvocation `409 secret_missing` before your code runs \u2014 which is why this blueprint declares no secrets\nat all by default. Declare one only when you will actually set it.\n\n## What to learn from this\n\n- **The hard part of push is ownership, not delivery.** A `unique` field plus one re-own path is the\n  whole difference between a registry that stays correct and one that leaks notifications between users.\n- **A verified principal beats a body field, always.** The platform hands the function `end_user.id`; the\n  request body is a suggestion.\n- **Delete on the verdict, not on the error.** `DeviceNotRegistered` is the only signal that justifies\n  removing a device. Everything else is about the message.\n- **What an end-user cannot do, a server-mode hook can \u2014 on the user's request.** The claim row is the\n  request; the `cmsHook` is the authority. No backend of your own is needed for it.\n- **A cron that cannot finish in one tick must remember where it stopped.** Restarting from the top of\n  a newest-first list means the oldest rows are never reached.\n- **One function, several front doors.** `triggers: [...]` puts an http door, a hook and a cron on the\n  same bundle \u2014 the code that owns a job keeps all of its entry points.\n\n**Pairs with:** [`templates/alerts-to-slack`](../alerts-to-slack) for the audit-stream drain used in\nexample (b).\n",
     "functions": {
-      "prune-receipts.ts": "// prune-receipts.ts \u2014 THE GARBAGE COLLECTOR (a vxil function, cron trigger).\n//\n// Trigger: cron `30 3 * * *`.\n//\n// A push service accepts a message and answers \"ok\" long before it knows whether\n// the device still exists. The real verdict arrives later, as a RECEIPT keyed by\n// the id the send returned. Almost nobody collects them, which is why push\n// registries only ever grow: dead tokens are re-sent to forever, quota is spent\n// on handsets that were wiped a year ago, and delivery rates look worse than\n// they are.\n//\n// This cron closes that loop:\n//   1. page through `push_tokens`, collecting rows that carry a `receipt_id`,\n//   2. ask the push service for those receipts, in batches,\n//   3. `DeviceNotRegistered` \u2192 DELETE the row (\u2605 invariant 3),\n//      any other error \u2192 count it and keep the device,\n//      ok \u2192 clear the receipt id; there is nothing left to check.\n//\n// Everything here is bounded: one cron tick reads at most MAX_ROWS rows and\n// makes at most MAX_ROWS / RECEIPT_BATCH outbound calls. A registry larger than\n// that is simply pruned over several nights, which is fine \u2014 a dead token costs\n// one wasted message a day, not correctness.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\nconst RECEIPTS_URL = 'https://exp.host/--/api/v2/push/getReceipts';\n/** Receipt ids per request. */\nconst RECEIPT_BATCH = 300;\n/** Token rows examined per cron tick. */\nconst MAX_ROWS = 2000;\n/** cms page size \u2014 100 is the default `maxPageSize` for the cms feature. */\nconst PAGE = 100;\n\ntype Env = CronFunctionEnvelope;\ninterface TokenRow {\n  item_id: string;\n  data: { token?: string; receipt_id?: string; failures?: number };\n}\ninterface Receipt { status?: string; message?: string; details?: { error?: string } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n\n    // \u2500\u2500 1. Collect pending receipts. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    const pending = new Map<string, TokenRow>(); // receipt_id \u2192 row\n    let cursor: string | null = null;\n    let scanned = 0;\n    while (scanned < MAX_ROWS) {\n      // NOTE: no `sort=` here on purpose. cms cursor pagination works with the\n      // DEFAULT sort only \u2014 pairing `?cursor=` with a `?sort=` is a clean 422\n      // (`cursor pagination works with the default sort only`), and `next_cursor`\n      // is not even emitted for a custom sort. Paging beats ordering here.\n      const url = `${base}/v1/cms/items/push_tokens?limit=${PAGE}`\n        + (cursor ? `&cursor=${encodeURIComponent(cursor)}` : '');\n      const res = await fetch(url, { headers: H });\n      if (!res.ok) return Response.json({ error: 'list_failed', status: res.status }, { status: 502 });\n      const body = (await res.json()) as { data?: { items?: TokenRow[]; next_cursor?: string | null } };\n      const items = body.data?.items ?? [];\n      for (const it of items) {\n        scanned++;\n        if (it.data.receipt_id) pending.set(it.data.receipt_id, it);\n      }\n      cursor = body.data?.next_cursor ?? null;\n      if (!cursor || items.length === 0) break;\n    }\n    if (pending.size === 0) return Response.json({ scanned, checked: 0, pruned: 0 });\n\n    // \u2500\u2500 2 + 3. Ask for verdicts and act on them. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    const ids = [...pending.keys()];\n    let checked = 0;\n    let pruned = 0;\n    let cleared = 0;\n    const errors: string[] = [];\n\n    for (let i = 0; i < ids.length; i += RECEIPT_BATCH) {\n      const slice = ids.slice(i, i + RECEIPT_BATCH);\n      const res = await fetch(RECEIPTS_URL, {\n        method: 'POST',\n        headers: { 'content-type': 'application/json', accept: 'application/json' },\n        body: JSON.stringify({ ids: slice }),\n      }).catch(() => null);\n      if (!res || !res.ok) {\n        errors.push(`receipts request returned ${res?.status ?? 'network error'}`);\n        continue;\n      }\n      // Receipts come back keyed by id \u2014 a receipt that is not ready yet is\n      // simply ABSENT, which is not an error: it is checked again tomorrow.\n      const map = (((await res.json().catch(() => ({}))) as { data?: Record<string, Receipt> }).data) ?? {};\n      for (const id of slice) {\n        const receipt = map[id];\n        if (!receipt) continue; // not ready \u2014 leave the receipt_id in place\n        const row = pending.get(id)!;\n        checked++;\n        if (receipt.status === 'ok') {\n          // Delivered. Nothing more to check for this device.\n          await patch(base, H, row.item_id, { receipt_id: '', failures: 0, checked_at: iso() });\n          cleared++;\n          continue;\n        }\n        const reason = receipt.details?.error ?? receipt.message ?? 'unknown';\n        if (reason === 'DeviceNotRegistered') {\n          // \u2605 INVARIANT 3. The device is gone \u2014 the row goes with it. This is\n          // also the ONLY safe automatic delete: every other error is transient\n          // or about the message, not about the device's existence.\n          await fetch(`${base}/v1/cms/items/push_tokens/${row.item_id}`, { method: 'DELETE', headers: H })\n            .catch(() => null);\n          pruned++;\n          continue;\n        }\n        await patch(base, H, row.item_id, {\n          receipt_id: '',\n          failures: (row.data.failures ?? 0) + 1,\n          last_error: String(reason).slice(0, 300),\n          checked_at: iso(),\n        });\n        errors.push(reason);\n      }\n    }\n\n    return Response.json({ scanned, pending: pending.size, checked, pruned, cleared, errors: errors.slice(0, 10) });\n  },\n};\n\nasync function patch(base: string, H: Record<string, string>, itemId: string, data: Record<string, unknown>) {\n  await fetch(`${base}/v1/cms/items/push_tokens/${itemId}`, {\n    method: 'PATCH', headers: H, body: JSON.stringify({ data }),\n  }).catch(() => null);\n}\nconst iso = () => new Date().toISOString();\n",
-      "register-token.ts": "// register-token.ts \u2014 THE DEVICE REGISTRY (a vxil function, http trigger).\n//\n// POST /v1/fn/register-token { token, user_id, platform?, locale? }\n//\n// Call it every time your app starts and every time the OS hands you a new push\n// token. It is idempotent, and it enforces the two registry invariants:\n//\n//   1. ONE TOKEN, ONE USER. `token` is declared `unique`, so the platform \u2014\n//      not this code \u2014 decides who wins a race. Two devices registering the\n//      same token at the same instant produce exactly one row; the loser sees\n//      409 `unique_violation`.\n//   2. RE-OWN ON CHANGE. A token that comes back under a DIFFERENT user is\n//      REASSIGNED, not duplicated. This is the case that matters: a resold\n//      phone, a shared tablet, a sign-out/sign-in on the same handset. Without\n//      it, the previous owner's notifications keep arriving on someone else's\n//      lock screen.\n//\n// IDENTITY. If the call carries a verified end-user session, `envelope.end_user`\n// is populated by the platform and THAT id wins \u2014 a body field can never\n// impersonate a signed-in user. In server mode (your backend, a server key)\n// there is no verified principal and `user_id` from the body is used, which is\n// why the re-own path lives here: see README.md.\n\nimport type { HttpFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = HttpFunctionEnvelope<{ token?: string; user_id?: string; platform?: string; locale?: string }>;\ninterface TokenRow { item_id: string; version?: number; data: { token?: string; end_user?: string } }\n\nconst PLATFORMS = new Set(['ios', 'android', 'web']);\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return json({ error: 'missing cms scope' }, 403);\n\n    const p = env.payload ?? {};\n    const token = typeof p.token === 'string' ? p.token.trim() : '';\n    // A VERIFIED principal always beats the body. Never trust a client-supplied\n    // user id when the platform has already told you who is calling.\n    const owner = env.end_user?.id ?? (typeof p.user_id === 'string' ? p.user_id.trim() : '');\n    if (!token) return json({ error: 'token is required' }, 400);\n    if (!owner) return json({ error: 'user_id is required (or invoke with an end-user session)' }, 400);\n    // The unique claim is capped at 256 chars; refuse early with a clear message\n    // rather than letting the write fail deep in the stack.\n    if (token.length > 256) return json({ error: 'token longer than 256 characters \u2014 store a hash instead' }, 400);\n\n    const now = new Date().toISOString();\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n    const data: Record<string, unknown> = {\n      token, end_user: owner, last_seen: now, failures: 0,\n      ...(p.platform && PLATFORMS.has(p.platform) ? { platform: p.platform } : {}),\n      ...(p.locale ? { locale: String(p.locale).slice(0, 16) } : {}),\n    };\n\n    // \u2500\u2500 1. Try to create. The common case is one round-trip. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    const created = await fetch(`${base}/v1/cms/items/push_tokens`, {\n      method: 'POST', headers: H, body: JSON.stringify({ status: 'published', data }),\n    });\n    if (created.ok) {\n      const body = (await created.json()) as { data?: { item_id?: string } };\n      return json({ registered: true, action: 'created', item_id: body.data?.item_id }, 201);\n    }\n    if (created.status !== 409) {\n      return json({ error: 'register_failed', status: created.status }, 502);\n    }\n\n    // \u2500\u2500 2. 409 \u21D2 the token already exists. Find it and decide. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    // In SERVER mode this read is tenant-wide and finds the row whoever owns it.\n    // In end-user mode it is owner-scoped, so a row belonging to someone else is\n    // invisible \u2014 that is the fail-safe working as designed, and the reason this\n    // function is documented as a server call.\n    const filter = encodeURIComponent(JSON.stringify({ token }));\n    const found = await fetch(`${base}/v1/cms/items/push_tokens?filter=${filter}&limit=1`, { headers: H });\n    if (!found.ok) return json({ error: 'lookup_failed', status: found.status }, 502);\n    const row = ((await found.json()) as { data?: { items?: TokenRow[] } }).data?.items?.[0];\n    if (!row) {\n      // Unique says it exists, but this caller cannot see it \u21D2 it belongs to\n      // another user and we are owner-scoped. Say so honestly.\n      return json({\n        registered: false,\n        error: 'token_owned_by_another_user',\n        hint: 'invoke register-token in server mode to reassign it',\n      }, 409);\n    }\n\n    const previous = row.data.end_user;\n    // \u2605 INVARIANT 2: re-own (or just refresh, when the owner is unchanged).\n    // If-Match makes the reassignment atomic against a concurrent registration.\n    const patched = await fetch(`${base}/v1/cms/items/push_tokens/${row.item_id}`, {\n      method: 'PATCH',\n      headers: { ...H, ...(row.version !== undefined ? { 'if-match': String(row.version) } : {}) },\n      body: JSON.stringify({ data: { ...data, last_error: '' } }),\n    });\n    if (!patched.ok) {\n      // 409 version_conflict = a concurrent registration already moved it. The\n      // registry is still correct; the caller can simply retry.\n      return json({ registered: false, error: 'conflict', status: patched.status }, 409);\n    }\n    return json({\n      registered: true,\n      action: previous && previous !== owner ? 'reowned' : 'refreshed',\n      item_id: row.item_id,\n      ...(previous && previous !== owner ? { previous_owner: previous } : {}),\n    }, 200);\n  },\n};\n\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n",
-      "send-push.ts": `// send-push.ts \u2014 THE SENDER (a vxil function, http trigger).
-//
-// POST /v1/fn/send-push
-//   {
-//     "user_ids": ["usr_a", "usr_b"],
-//     "messages": {                       // keyed by locale; "default" is required
-//       "default": { "title": "You're in", "body": "Pro is active on this device." },
-//       "ar":      { "title": "\u062A\u0645 \u0627\u0644\u062A\u0641\u0639\u064A\u0644", "body": "\u0623\u0635\u0628\u062D \u0627\u0634\u062A\u0631\u0627\u0643 Pro \u0645\u0641\u0639\u0651\u0644\u0627\u064B." },
-//       "fr":      { "title": "C'est actif", "body": "Pro est activ\xE9 sur cet appareil." }
-//     },
-//     "data": { "screen": "billing" }     // optional payload handed to your app
-//   }
-//
-// It resolves each user's live devices, picks the copy for THAT DEVICE'S locale
-// (captured at registration), and posts to the push service in batches.
-//
-// LOCALIZATION IS PER DEVICE, NOT PER USER. One person can carry an English
-// phone and an Arabic tablet. Because \`locale\` lives on the token row, the right
-// copy goes to each device with no extra lookup.
-//
-// Two failure kinds, handled differently:
-//   \u2022 an IMMEDIATE per-message error (\`DeviceNotRegistered\`) \u2014 the token is dead
-//     right now; delete the row.
-//   \u2022 an accepted message \u2014 the service returns a RECEIPT id, and the real
-//     verdict arrives later. Store the id; \`prune-receipts\` collects it.
-
-// Expo's push endpoint. For raw FCM: 'https://fcm.googleapis.com/v1/projects/<id>/messages:send'
-// (and an OAuth bearer). For APNs: 'https://api.push.apple.com/3/device/<token>'
-// (one request per device, a JWT \`authorization\`, and an \`apns-topic\` header).
-// Whichever you pick, its HOST must be in the function's \`egressAllow\`.
-
-import type { HttpFunctionEnvelope } from '@vxil/sdk';
-
-const PUSH_URL = 'https://exp.host/--/api/v2/push/send';
-/** Expo accepts up to 100 messages in one request. */
-const BATCH = 100;
-/** Devices resolved per invocation \u2014 a guardrail, not a limit of the platform. */
-const MAX_DEVICES = 1000;
-
-type Env = HttpFunctionEnvelope<{
-  user_ids?: string[];
-  messages?: Record<string, { title?: string; body?: string }>;
-  data?: Record<string, unknown>;
-}>;
-interface TokenRow {
-  item_id: string;
-  version?: number;
-  data: { token?: string; end_user?: string; locale?: string; failures?: number };
-}
-/** One entry of Expo's response array, positionally matched to the request. */
-interface Ticket { status?: string; id?: string; message?: string; details?: { error?: string } }
-
-export default {
-  async fetch(req: Request): Promise<Response> {
-    const env = (await req.json().catch(() => ({}))) as Env;
-    const base = env.vxil_base ?? 'https://api.vxil.com';
-    const cms = env.scoped_jwts?.cms;
-    if (!cms) return json({ error: 'missing cms scope' }, 403);
-
-    const p = env.payload ?? {};
-    const userIds = Array.isArray(p.user_ids) ? p.user_ids.filter((u) => typeof u === 'string' && u) : [];
-    const messages = p.messages ?? {};
-    if (userIds.length === 0) return json({ error: 'user_ids is required' }, 400);
-    if (!messages.default?.title && !messages.default?.body) {
-      return json({ error: 'messages.default { title, body } is required' }, 400);
-    }
-
-    const H = { authorization: \`Bearer \${cms}\`, 'content-type': 'application/json' };
-
-    // \u2500\u2500 1. Resolve devices. One filtered read per user (owner-scoped by value,
-    //    not by principal \u2014 this runs in server mode). \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-    const devices: TokenRow[] = [];
-    for (const uid of userIds) {
-      if (devices.length >= MAX_DEVICES) break;
-      const filter = encodeURIComponent(JSON.stringify({ end_user: uid }));
-      const res = await fetch(\`\${base}/v1/cms/items/push_tokens?filter=\${filter}&limit=50\`, { headers: H });
-      if (!res.ok) continue;
-      const items = ((await res.json()) as { data?: { items?: TokenRow[] } }).data?.items ?? [];
-      for (const it of items) if (it.data.token) devices.push(it);
-    }
-    if (devices.length === 0) return json({ sent: 0, devices: 0, note: 'no registered devices' }, 200);
-
-    // \u2500\u2500 2. Build one message per device, in that device's language. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-    const outgoing = devices.map((d) => {
-      const copy = pick(messages, d.data.locale);
-      return {
-        to: d.data.token!,
-        ...(copy.title ? { title: copy.title } : {}),
-        ...(copy.body ? { body: copy.body } : {}),
-        ...(p.data ? { data: p.data } : {}),
-        sound: 'default',
-      };
-    });
-
-    // \u2500\u2500 3. Send in batches; reconcile each ticket back to its device by index. \u2500
-    let accepted = 0;
-    let dropped = 0;
-    const errors: string[] = [];
-    for (let i = 0; i < outgoing.length; i += BATCH) {
-      const slice = outgoing.slice(i, i + BATCH);
-      const res = await fetch(PUSH_URL, {
-        method: 'POST',
-        headers: { 'content-type': 'application/json', accept: 'application/json' },
-        body: JSON.stringify(slice),
-      }).catch(() => null);
-      if (!res || !res.ok) {
-        errors.push(\`push service returned \${res?.status ?? 'network error'} for batch \${i / BATCH}\`);
-        continue;
-      }
-      const tickets = (((await res.json().catch(() => ({}))) as { data?: Ticket[] }).data) ?? [];
-      for (let k = 0; k < slice.length; k++) {
-        const device = devices[i + k]!;
-        const ticket = tickets[k];
-        if (ticket?.status === 'ok' && ticket.id) {
-          // Accepted, verdict pending. Park the receipt id for prune-receipts.
-          accepted++;
-          await patch(base, H, device, { receipt_id: ticket.id, failures: 0, last_error: '' });
-          continue;
-        }
-        const reason = ticket?.details?.error ?? ticket?.message ?? 'unknown';
-        if (reason === 'DeviceNotRegistered') {
-          // Definitive: this token will never deliver again. \u2605 INVARIANT 3.
-          await del(base, H, device);
-          dropped++;
-          continue;
-        }
-        // Anything else (MessageTooBig, MessageRateExceeded, a transient fault)
-        // is NOT a reason to delete a device. Count it and move on.
-        await patch(base, H, device, {
-          failures: (device.data.failures ?? 0) + 1,
-          last_error: String(reason).slice(0, 300),
-        });
-        errors.push(reason);
-      }
-    }
-
-    return json({ devices: devices.length, accepted, dropped, errors: errors.slice(0, 10) }, 200);
-  },
-};
-
-/** Locale match: exact ('pt-BR'), then the base language ('pt'), then default. */
-function pick(
-  messages: Record<string, { title?: string; body?: string }>,
-  locale: string | undefined,
-): { title?: string; body?: string } {
-  if (locale) {
-    if (messages[locale]) return messages[locale]!;
-    const bare = locale.split('-')[0]!;
-    if (messages[bare]) return messages[bare]!;
-  }
-  return messages.default ?? {};
-}
-
-async function patch(base: string, H: Record<string, string>, d: TokenRow, data: Record<string, unknown>) {
-  await fetch(\`\${base}/v1/cms/items/push_tokens/\${d.item_id}\`, {
-    method: 'PATCH', headers: H, body: JSON.stringify({ data }),
-  }).catch(() => null);
-}
-async function del(base: string, H: Record<string, string>, d: TokenRow) {
-  await fetch(\`\${base}/v1/cms/items/push_tokens/\${d.item_id}\`, { method: 'DELETE', headers: H }).catch(() => null);
-}
-const json = (o: unknown, status: number) => Response.json(o, { status });
-`
+      "prune-receipts.ts": "// prune-receipts.ts \u2014 THE GARBAGE COLLECTOR (a vxil function, cron trigger).\n//\n// Trigger: cron `30 */6 * * *` (every 6 hours).\n//\n// A push service accepts a message and answers \"ok\" long before it knows whether\n// the device still exists. The real verdict arrives later, as a RECEIPT keyed by\n// the id the send returned. Almost nobody collects them, which is why push\n// registries only ever grow: dead tokens are re-sent to forever, quota is spent\n// on handsets that were wiped a year ago, and delivery rates look worse than\n// they are.\n//\n// This cron closes that loop:\n//   1. resume the walk of `push_tokens` where the previous tick stopped (the\n//      cursor lives in `push_state`), collecting rows that carry a `receipt_id`,\n//   2. ask the push service for those receipts, in batches,\n//   3. `DeviceNotRegistered` \u2192 DELETE the row (\u2605 invariant 3),\n//      any other error \u2192 count it and keep the device,\n//      ok \u2192 clear the receipt id; there is nothing left to check,\n//      no receipt and older than RECEIPT_MAX_AGE_H \u2192 clear it (the service no\n//      longer has it; asking forever would pin the row),\n//      Every clear is a PATCH with If-Match on the row version that was read:\n//      if `send-push` parked a NEWER receipt id on the device meanwhile, the\n//      clear is refused (409) and the newer id stays for the next walk,\n//   4. save the cursor \u2014 or '' when the walk reached the oldest row, so the\n//      next tick starts again from the newest.\n//\n// Everything is bounded: one tick reads at most MAX_ROWS rows and acts on at\n// most MAX_ACTIONS of them, so its outbound calls stay in the low hundreds.\n// Because the cursor persists, a registry of ANY size is walked end to end over\n// successive ticks \u2014 MAX_ROWS \xD7 4 ticks a day. (The walk follows the default\n// newest-first order; rows registered while a walk is in progress are covered\n// by the next walk.)\n\n// cron-walk: persisted-cursor \u2014 the walk's cursor lives in `push_state` and is saved with If-Match.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\nconst RECEIPTS_URL = 'https://exp.host/--/api/v2/push/getReceipts';\n/** Receipt ids per request. */\nconst RECEIPT_BATCH = 300;\n/** Token rows examined per cron tick. */\nconst MAX_ROWS = 2000;\n/** Rows with a pending receipt acted on per tick (each costs one PATCH or DELETE). */\nconst MAX_ACTIONS = 300;\n/** A receipt id parked longer than this is cleared as unknowable. */\nconst RECEIPT_MAX_AGE_H = 48;\n/** cms page size \u2014 100 is the default `maxPageSize` for the cms feature. */\nconst PAGE = 100;\n/** This cron's row in `push_state`. */\nconst STATE_KEY = 'prune-receipts';\n\ntype Env = CronFunctionEnvelope;\ninterface TokenRow {\n  item_id: string;\n  version?: number;\n  data: { token?: string; receipt_id?: string; receipt_at?: string; failures?: number };\n}\ninterface Receipt { status?: string; message?: string; details?: { error?: string } }\ninterface StateRow { item_id: string; version?: number; data: { cursor?: string } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n\n    // \u2500\u2500 1. Resume the walk; collect pending receipts. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    const state = await readState(base, H, STATE_KEY);\n    if (state === 'error') return Response.json({ error: 'state_read_failed' }, { status: 502 });\n    const startedAt = state?.data.cursor || null;\n    const pending = new Map<string, TokenRow>(); // receipt_id \u2192 row\n    let cursor: string | null = startedAt;\n    let scanned = 0;\n    let wrapped = false;\n    while (scanned < MAX_ROWS && pending.size < MAX_ACTIONS) {\n      // NOTE: no `sort=` here on purpose. In the DEFAULT order (newest first)\n      // a cursor is a plain item id, which is what we persist between ticks\n      // and resume `item_id <` from. Paging beats ordering here.\n      const url = `${base}/v1/cms/items/push_tokens?limit=${PAGE}`\n        + (cursor ? `&cursor=${encodeURIComponent(cursor)}` : '');\n      const res = await fetch(url, { headers: H });\n      if (!res.ok) return Response.json({ error: 'list_failed', status: res.status }, { status: 502 });\n      const body = (await res.json()) as { data?: { items?: TokenRow[]; next_cursor?: string | null } };\n      const items = body.data?.items ?? [];\n      let stoppedEarly = false;\n      for (const it of items) {\n        scanned++;\n        if (it.data.receipt_id) pending.set(it.data.receipt_id, it);\n        cursor = it.item_id; // resume AFTER the last row actually looked at\n        if (pending.size >= MAX_ACTIONS || scanned >= MAX_ROWS) { stoppedEarly = true; break; }\n      }\n      if (stoppedEarly) break;\n      if (!body.data?.next_cursor || items.length === 0) { wrapped = true; break; }\n      cursor = body.data.next_cursor;\n    }\n    // Reached the oldest row \u2192 the next tick starts again from the newest.\n    const nextCursor = wrapped ? '' : (cursor ?? '');\n\n    // \u2500\u2500 2 + 3. Ask for verdicts and act on them. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n    const ids = [...pending.keys()];\n    let checked = 0;\n    let pruned = 0;\n    let cleared = 0;\n    let expired = 0;\n    let raced = 0;\n    const errors: string[] = [];\n    const now = Date.now();\n\n    for (let i = 0; i < ids.length; i += RECEIPT_BATCH) {\n      const slice = ids.slice(i, i + RECEIPT_BATCH);\n      const res = await fetch(RECEIPTS_URL, {\n        method: 'POST',\n        headers: { 'content-type': 'application/json', accept: 'application/json' },\n        body: JSON.stringify({ ids: slice }),\n      }).catch(() => null);\n      if (!res || !res.ok) {\n        errors.push(`receipts request returned ${res?.status ?? 'network error'}`);\n        continue;\n      }\n      // Receipts come back keyed by id \u2014 a receipt that is not ready yet is\n      // simply ABSENT, which is not an error: it is checked again next walk.\n      const map = (((await res.json().catch(() => ({}))) as { data?: Record<string, Receipt> }).data) ?? {};\n      for (const id of slice) {\n        const receipt = map[id];\n        const row = pending.get(id)!;\n        if (!receipt) {\n          // Not ready \u2014 or no longer kept by the service. Past the age bound\n          // the id can never be answered: clear it so the row is not pinned.\n          const at = row.data.receipt_at ? Date.parse(row.data.receipt_at) : NaN;\n          if (Number.isFinite(at) && now - at > RECEIPT_MAX_AGE_H * 3_600_000) {\n            if (await patch(base, H, row, { receipt_id: '', checked_at: iso() })) expired++; else raced++;\n          }\n          continue;\n        }\n        checked++;\n        if (receipt.status === 'ok') {\n          // Delivered. Nothing more to check for this device.\n          if (await patch(base, H, row, { receipt_id: '', failures: 0, checked_at: iso() })) cleared++; else raced++;\n          continue;\n        }\n        const reason = receipt.details?.error ?? receipt.message ?? 'unknown';\n        if (reason === 'DeviceNotRegistered') {\n          // \u2605 INVARIANT 3. The device is gone \u2014 the row goes with it. This is\n          // also the ONLY safe automatic delete: every other error is transient\n          // or about the message, not about the device's existence.\n          await fetch(`${base}/v1/cms/items/push_tokens/${row.item_id}`, { method: 'DELETE', headers: H })\n            .catch(() => null);\n          pruned++;\n          continue;\n        }\n        if (!await patch(base, H, row, {\n          receipt_id: '',\n          failures: (row.data.failures ?? 0) + 1,\n          last_error: String(reason).slice(0, 300),\n          checked_at: iso(),\n        })) raced++;\n        errors.push(reason);\n      }\n    }\n\n    // \u2500\u2500 4. Save where the walk stopped (If-Match: a concurrent tick wins). \u2500\u2500\u2500\u2500\n    const saved = await writeState(base, H, STATE_KEY, state, nextCursor);\n\n    return Response.json({\n      scanned, pending: pending.size, checked, pruned, cleared, expired, raced,\n      resumed_from: startedAt, cursor: nextCursor, wrapped, saved, errors: errors.slice(0, 10),\n    });\n  },\n};\n\n/** Clear/record against the version that was READ. false = the row changed\n *  meanwhile (409: a newer receipt is parked \u2014 leave it) or the write failed. */\nasync function patch(base: string, H: Record<string, string>, row: TokenRow, data: Record<string, unknown>): Promise<boolean> {\n  const res = await fetch(`${base}/v1/cms/items/push_tokens/${row.item_id}`, {\n    method: 'PATCH',\n    headers: { ...H, ...(row.version !== undefined ? { 'if-match': String(row.version) } : {}) },\n    body: JSON.stringify({ data }),\n  }).catch(() => null);\n  return !!res && res.ok;\n}\n\n/** This cron's `push_state` row, null when it does not exist yet. */\nasync function readState(base: string, H: Record<string, string>, key: string): Promise<StateRow | null | 'error'> {\n  const filter = encodeURIComponent(JSON.stringify({ key }));\n  const res = await fetch(`${base}/v1/cms/items/push_state?filter=${filter}&limit=1`, { headers: H });\n  if (!res.ok) return 'error';\n  return ((await res.json()) as { data?: { items?: StateRow[] } }).data?.items?.[0] ?? null;\n}\n\n/** Persist the cursor. First tick creates the row (a racing tick's 409 on the\n *  unique `key` is fine \u2014 that tick saved its own); later ticks PATCH with\n *  If-Match so two overlapping ticks cannot both move it. */\nasync function writeState(\n  base: string, H: Record<string, string>, key: string, state: StateRow | null, cursor: string,\n): Promise<boolean> {\n  const data = { key, cursor, updated_at: iso() };\n  const res = state\n    ? await fetch(`${base}/v1/cms/items/push_state/${state.item_id}`, {\n      method: 'PATCH',\n      headers: { ...H, ...(state.version !== undefined ? { 'if-match': String(state.version) } : {}) },\n      body: JSON.stringify({ data }),\n    }).catch(() => null)\n    : await fetch(`${base}/v1/cms/items/push_state`, {\n      method: 'POST', headers: H, body: JSON.stringify({ status: 'published', data }),\n    }).catch(() => null);\n  return !!res && res.ok;\n}\n\nconst iso = () => new Date().toISOString();\n",
+      "register-token.ts": "// register-token.ts \u2014 THE DEVICE REGISTRY (a vxil function with five bindings).\n//\n//   http     POST /v1/fn/register-token { token, user_id?, platform?, locale? }\n//   cmsHook  a new `push_token_claims` row (the app's async re-own request)\n//   webhook  `auth.user.erased` / `user.erased` / `user.deleted` (forget the user)\n//\n// One bundle, because all three are the same job: keeping \"which user holds\n// which device\" true. The envelope's `trigger` says which door was used.\n//\n// \u2500\u2500 http: register \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// Call it every time your app starts and every time the OS hands you a new push\n// token. It is idempotent, and it enforces the two registry invariants:\n//\n//   1. ONE TOKEN, ONE USER. `token` is declared `unique`, so the platform \u2014\n//      not this code \u2014 decides who wins a race. Two devices registering the\n//      same token at the same instant produce exactly one row; the loser sees\n//      409 `unique_violation`.\n//   2. RE-OWN ON CHANGE. A token that comes back under a DIFFERENT user is\n//      REASSIGNED, not duplicated. This is the case that matters: a resold\n//      phone, a shared tablet, a sign-out/sign-in on the same handset. Without\n//      it, the previous owner's notifications keep arriving on someone else's\n//      lock screen.\n//\n// IDENTITY. If the call carries a verified end-user session, `envelope.end_user`\n// is populated by the platform and THAT id wins \u2014 a body field can never\n// impersonate a signed-in user. In server mode (your backend, a server key)\n// there is no verified principal and `user_id` from the body is used.\n//\n// SERVER MODE re-owns immediately (a tenant-wide read finds the row whoever\n// owns it). END-USER MODE cannot see another user's row \u2014 the owner scope is\n// the fail-safe working \u2014 so the app's call files a CLAIM in\n// `push_token_claims` (owned by the caller) and answers 202\n// `{ action: 'reown_queued' }`; the cmsHook below finishes the move.\n//\n// \u2500\u2500 cmsHook: finish an async re-own \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// Runs in SERVER mode (a platform-delivered hook carries no end-user), so it can\n// read and move any row: re-read the claim, re-own (or create) the token row for\n// the claimant, delete the claim. At-least-once and re-delivered on failure\n// (`retry`), so every step is idempotent: a claim that is already gone is done.\n//\n// \u2500\u2500 webhook: erasure and deletion \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// `auth.user.erased { user_id }`, `user.erased { id }` and `user.deleted { id }`\n// (the admin delete without erase) delete every device row, pending claim and\n// the preferences row of that user \u2014 device tokens, time zone and activity are\n// personal data, and a deleted account must stop getting reminder nudges.\n// Deliberately NOT `auth.session.revoked`: that event fires on every\n// refresh-token rotation, not only on sign-out. A MERGE or REKEY\n// (`auth.user.merged` / `.rekeyed`, guest \u2192 registered) needs nothing here: the\n// app's next start registers its token under the new id, which re-owns it.\n\nimport type { CmsHookFunctionEnvelope, HttpFunctionEnvelope, WebhookFunctionEnvelope } from '@vxil/sdk';\n\ntype RegisterBody = { token?: string; user_id?: string; platform?: string; locale?: string };\ntype Env =\n  | HttpFunctionEnvelope<RegisterBody>\n  | CmsHookFunctionEnvelope\n  | WebhookFunctionEnvelope<{ user_id?: string; id?: string }>;\ninterface TokenRow { item_id: string; version?: number; data: { token?: string; end_user?: string } }\ninterface ClaimRow { item_id: string; data: { token?: string; end_user?: string; platform?: string; locale?: string } }\n\nconst PLATFORMS = new Set(['ios', 'android', 'web']);\n/** Rows deleted per erasure attempt \u2014 a person has a handful of devices; a\n *  bigger set is finished by the next attempt (each deletes the next pages). */\nconst ERASE_MAX = 200;\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return json({ error: 'missing cms scope' }, 403);\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n\n    if (env.trigger === 'cms-hook') return finishClaim(base, H, env);\n    if (env.trigger === 'webhook') return forgetUser(base, H, env);\n    return register(base, H, env as HttpFunctionEnvelope<RegisterBody>);\n  },\n};\n\n// \u2500\u2500 http \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nasync function register(base: string, H: Record<string, string>, env: HttpFunctionEnvelope<RegisterBody>): Promise<Response> {\n  const p = env.payload ?? {};\n  const token = typeof p.token === 'string' ? p.token.trim() : '';\n  // A VERIFIED principal always beats the body. Never trust a client-supplied\n  // user id when the platform has already told you who is calling.\n  const endUser = env.end_user?.id;\n  const owner = endUser ?? (typeof p.user_id === 'string' ? p.user_id.trim() : '');\n  if (!token) return json({ error: 'token is required' }, 400);\n  if (!owner) return json({ error: 'user_id is required (or invoke with an end-user session)' }, 400);\n  // The unique claim is capped at 256 chars; refuse early with a clear message\n  // rather than letting the write fail deep in the stack.\n  if (token.length > 256) return json({ error: 'token longer than 256 characters \u2014 store a hash instead' }, 400);\n\n  const data = tokenData(token, owner, p.platform, p.locale);\n\n  // \u2500\u2500 1. Try to create. The common case is one round-trip. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  const created = await fetch(`${base}/v1/cms/items/push_tokens`, {\n    method: 'POST', headers: H, body: JSON.stringify({ status: 'published', data }),\n  });\n  if (created.ok) {\n    const body = (await created.json()) as { data?: { item_id?: string } };\n    return json({ registered: true, action: 'created', item_id: body.data?.item_id }, 201);\n  }\n  if (created.status !== 409) return json({ error: 'register_failed', status: created.status }, 502);\n\n  // \u2500\u2500 2. 409 \u21D2 the token already exists. Find it and decide. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  // In SERVER mode this read is tenant-wide and finds the row whoever owns it.\n  // In end-user mode it is owner-scoped, so a row belonging to someone else is\n  // invisible \u2014 that is the fail-safe working as designed.\n  const row = await findToken(base, H, token);\n  if (row === 'error') return json({ error: 'lookup_failed' }, 502);\n  if (!row) {\n    if (!endUser) {\n      // Server mode sees every row, so \"exists but not found\" is a race with a\n      // concurrent delete. Retrying the call settles it.\n      return json({ registered: false, error: 'conflict', hint: 'retry the call' }, 409);\n    }\n    // \u2605 The async re-own. File a claim (owned by the caller \u2014 the platform\n    // stamps the verified owner); the server-mode cmsHook moves the token.\n    const claim = await fetch(`${base}/v1/cms/items/push_token_claims`, {\n      method: 'POST', headers: H,\n      body: JSON.stringify({ status: 'published', data: claimData(token, owner, p.platform, p.locale) }),\n    });\n    if (!claim.ok) return json({ error: 'claim_failed', status: claim.status }, 502);\n    const c = (await claim.json()) as { data?: { item_id?: string } };\n    return json({ registered: false, action: 'reown_queued', claim_id: c.data?.item_id }, 202);\n  }\n\n  const moved = await reown(base, H, row, data);\n  if (!moved.ok) {\n    // 409 version_conflict = a concurrent registration already moved it. The\n    // registry is still correct; the caller can simply retry.\n    return json({ registered: false, error: 'conflict', status: moved.status }, 409);\n  }\n  const previous = row.data.end_user;\n  return json({\n    registered: true,\n    action: previous && previous !== owner ? 'reowned' : 'refreshed',\n    item_id: row.item_id,\n    ...(previous && previous !== owner ? { previous_owner: previous } : {}),\n  }, 200);\n}\n\n// \u2500\u2500 cmsHook \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nasync function finishClaim(base: string, H: Record<string, string>, env: CmsHookFunctionEnvelope): Promise<Response> {\n  const { collection, item_id: claimId } = env.payload ?? ({} as CmsHookFunctionEnvelope['payload']);\n  // The platform filters on the binding's collection; this guard is belt and braces.\n  if (collection !== 'push_token_claims' || !claimId) return json({ skipped: true }, 200);\n\n  const got = await fetch(`${base}/v1/cms/items/push_token_claims/${claimId}`, { headers: H });\n  if (got.status === 404) return json({ done: true, reason: 'claim already handled' }, 200);\n  if (!got.ok) return json({ error: 'claim_read_failed', status: got.status }, 502); // non-2xx \u2192 another attempt (maxAttempts: 3)\n  const claim = ((await got.json()) as { data?: ClaimRow }).data;\n  const token = claim?.data.token;\n  const owner = claim?.data.end_user;\n  if (!token || !owner) {\n    await deleteItem(base, H, 'push_token_claims', claimId);\n    return json({ done: true, reason: 'empty claim dropped' }, 200);\n  }\n\n  const data = tokenData(token, owner, claim.data.platform, claim.data.locale);\n  const row = await findToken(base, H, token);\n  if (row === 'error') return json({ error: 'lookup_failed' }, 502); // non-2xx \u2192 another attempt (maxAttempts: 3)\n  let action: string;\n  if (!row) {\n    // The holder deleted it in the meantime: the claimant simply registers it.\n    const created = await fetch(`${base}/v1/cms/items/push_tokens`, {\n      method: 'POST', headers: H, body: JSON.stringify({ status: 'published', data }),\n    });\n    // 409 = it was registered again concurrently; the next delivery re-reads.\n    if (!created.ok) return json({ error: 'create_failed', status: created.status }, 502);\n    action = 'created';\n  } else {\n    const moved = await reown(base, H, row, data);\n    if (!moved.ok) return json({ error: 'reown_failed', status: moved.status }, 502); // another attempt re-reads (maxAttempts: 3)\n    action = row.data.end_user === owner ? 'refreshed' : 'reowned';\n  }\n  await deleteItem(base, H, 'push_token_claims', claimId);\n  return json({ done: true, action, claim_id: claimId }, 200);\n}\n\n// \u2500\u2500 webhook \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nasync function forgetUser(\n  base: string, H: Record<string, string>, env: WebhookFunctionEnvelope<{ user_id?: string; id?: string }>,\n): Promise<Response> {\n  const event = env.payload?.event;\n  const d = env.payload?.data;\n  const fields = d && !('truncated' in d) ? d : null;\n  // auth.user.erased carries `user_id`; the admin erase and delete carry `id`.\n  const userId = event === 'auth.user.erased' ? fields?.user_id\n    : event === 'user.erased' || event === 'user.deleted' ? fields?.id : undefined;\n  if (typeof userId !== 'string' || !userId) return json({ skipped: true, event }, 200);\n\n  let deleted = 0;\n  let failed = 0;\n  for (const coll of ['push_tokens', 'push_token_claims', 'push_prefs']) {\n    const filter = encodeURIComponent(JSON.stringify({ end_user: userId }));\n    while (deleted + failed < ERASE_MAX) {\n      // Always the FIRST page: what was deleted is gone, so the next read\n      // returns the next rows. A row that refuses to delete ends the loop.\n      const res = await fetch(`${base}/v1/cms/items/${coll}?filter=${filter}&limit=50`, { headers: H });\n      if (!res.ok) return json({ error: 'list_failed', status: res.status, deleted }, 502); // non-2xx \u2192 another attempt (maxAttempts: 3)\n      const items = ((await res.json()) as { data?: { items?: Array<{ item_id: string }> } }).data?.items ?? [];\n      if (items.length === 0) break;\n      let progress = 0;\n      for (const it of items) {\n        if (await deleteItem(base, H, coll, it.item_id)) { deleted++; progress++; } else failed++;\n      }\n      if (progress === 0) break;\n    }\n  }\n  // A failed delete \u2014 or a set larger than one attempt's ERASE_MAX \u2014 answers\n  // non-2xx: the binding declares maxAttempts: 3, so the jobs ladder hands it\n  // back for another attempt, which deletes the rest.\n  const unfinished = failed > 0 || deleted >= ERASE_MAX;\n  return json({ user_id: userId, deleted, failed, done: !unfinished }, unfinished ? 502 : 200);\n}\n\n// \u2500\u2500 helpers \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nfunction tokenData(token: string, owner: string, platform: unknown, locale: unknown): Record<string, unknown> {\n  return {\n    token, end_user: owner, last_seen: new Date().toISOString(), failures: 0, last_error: '',\n    ...(typeof platform === 'string' && PLATFORMS.has(platform) ? { platform } : {}),\n    ...(typeof locale === 'string' && locale ? { locale: locale.slice(0, 16) } : {}),\n  };\n}\n\nfunction claimData(token: string, owner: string, platform: unknown, locale: unknown): Record<string, unknown> {\n  return {\n    token, end_user: owner,\n    ...(typeof platform === 'string' && PLATFORMS.has(platform) ? { platform } : {}),\n    ...(typeof locale === 'string' && locale ? { locale: locale.slice(0, 16) } : {}),\n  };\n}\n\nasync function findToken(base: string, H: Record<string, string>, token: string): Promise<TokenRow | null | 'error'> {\n  const filter = encodeURIComponent(JSON.stringify({ token }));\n  const found = await fetch(`${base}/v1/cms/items/push_tokens?filter=${filter}&limit=1`, { headers: H });\n  if (!found.ok) return 'error';\n  return ((await found.json()) as { data?: { items?: TokenRow[] } }).data?.items?.[0] ?? null;\n}\n\n/** \u2605 INVARIANT 2: re-own (or just refresh, when the owner is unchanged).\n *  If-Match makes the reassignment atomic against a concurrent registration. */\nfunction reown(base: string, H: Record<string, string>, row: TokenRow, data: Record<string, unknown>): Promise<Response> {\n  return fetch(`${base}/v1/cms/items/push_tokens/${row.item_id}`, {\n    method: 'PATCH',\n    headers: { ...H, ...(row.version !== undefined ? { 'if-match': String(row.version) } : {}) },\n    body: JSON.stringify({ data }),\n  });\n}\n\n/** true when the row is gone afterwards (a 404 counts: someone else deleted it). */\nasync function deleteItem(base: string, H: Record<string, string>, coll: string, itemId: string): Promise<boolean> {\n  const res = await fetch(`${base}/v1/cms/items/${coll}/${itemId}`, { method: 'DELETE', headers: H }).catch(() => null);\n  return !!res && (res.ok || res.status === 404);\n}\n\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n",
+      "send-push.ts": "// send-push.ts \u2014 THE SENDER (a vxil function, two bindings).\n//\n//   http  POST /v1/fn/send-push \u2014 send now (below).\n//   cron  `0 * * * *` \u2014 THE REMINDER LADDER (further below).\n//\n// POST /v1/fn/send-push\n//   {\n//     \"user_ids\": [\"usr_a\", \"usr_b\"],\n//     \"messages\": {                       // keyed by locale; \"default\" is required\n//       \"default\": { \"title\": \"You're in\", \"body\": \"Pro is active on this device.\" },\n//       \"ar\":      { \"title\": \"\u062A\u0645 \u0627\u0644\u062A\u0641\u0639\u064A\u0644\", \"body\": \"\u0623\u0635\u0628\u062D \u0627\u0634\u062A\u0631\u0627\u0643 Pro \u0645\u0641\u0639\u0651\u0644\u0627\u064B.\" },\n//       \"fr\":      { \"title\": \"C'est actif\", \"body\": \"Pro est activ\xE9 sur cet appareil.\" }\n//     },\n//     \"data\": { \"screen\": \"billing\" }     // optional payload handed to your app\n//   }\n//\n// It resolves each user's live devices, picks the copy for THAT DEVICE'S locale\n// (captured at registration), and posts to the push service in batches.\n//\n// LOCALIZATION IS PER DEVICE, NOT PER USER. One person can carry an English\n// phone and an Arabic tablet. Because `locale` lives on the token row, the right\n// copy goes to each device with no extra lookup.\n//\n// Two failure kinds, handled differently:\n//   \u2022 an IMMEDIATE per-message error (`DeviceNotRegistered`) \u2014 the token is dead\n//     right now; delete the row.\n//   \u2022 an accepted message \u2014 the service returns a RECEIPT id, and the real\n//     verdict arrives later. Store the id (and when); `prune-receipts` collects it.\n//\n// \u2500\u2500 The reminder ladder (cron, hourly) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// Re-engagement for users who stopped opening the app: one nudge after 1 day\n// of inactivity, one after 3, one after 7 \u2014 then silence until they come back.\n// Per user, from `push_prefs` (the app writes its own row):\n//   \u2022 `reminders: false` \u2192 never;\n//   \u2022 quiet hours [quiet_start, quiet_end) in the user's `timezone` \u2192 not now\n//     (the next hourly tick after the window sends it);\n//   \u2022 `last_active` + `ladder_step` decide the step; the APP resets\n//     `ladder_step` to 0 when it comes to the foreground.\n// ONE nudge per tick at most, and never a catch-up burst: when several rungs\n// are due at once (a user already idle for a week when the ladder first sees\n// them \u2014 the kit added to a live app, reminders turned back on, a held cron),\n// only the HIGHEST due rung is sent and the steps below it are skipped. And a\n// rung waits its own gap after the previous nudge (`last_reminded_at`), so\n// 1 d \u2192 3 d \u2192 7 d stay 2 and 4 days apart even when a step went out late.\n// Each step is CLAIMED with If-Match on the prefs row BEFORE the send, so two\n// overlapping ticks can never send it twice (a send that then fails is a\n// missed nudge, never a duplicate one). The walk only reads users inactive for\n// at least the first step and not yet through the ladder (`ladder_step` below\n// its length \u2014 a `derive` hook writes 0 when the app leaves it out), and\n// resumes where the last tick stopped (the cursor lives in `push_state`), so\n// it covers any number of users over successive ticks: MAX_LADDER_ROWS read and\n// MAX_REMINDERS sent per tick. A skipped tick is harmless \u2014 the next resumes.\n\n// Expo's push endpoint. For raw FCM: 'https://fcm.googleapis.com/v1/projects/<id>/messages:send'\n// (and an OAuth bearer). For APNs: 'https://api.push.apple.com/3/device/<token>'\n// (one request per device, a JWT `authorization`, and an `apns-topic` header).\n// Whichever you pick, its HOST must be in the function's `egressAllow`.\n\n// cron-walk: persisted-cursor \u2014 the ladder walk's cursor lives in `push_state` and is saved with If-Match.\n\nimport type { CronFunctionEnvelope, HttpFunctionEnvelope } from '@vxil/sdk';\n\nconst PUSH_URL = 'https://exp.host/--/api/v2/push/send';\n/** Expo accepts up to 100 messages in one request. */\nconst BATCH = 100;\n/** cms page size \u2014 100 is the default `maxPageSize` for the cms feature. */\nconst PAGE = 100;\n/** Devices resolved per invocation \u2014 a guardrail, not a limit of the platform. */\nconst MAX_DEVICES = 1000;\n\n/** The ladder: hours of inactivity \u2192 the nudge, per locale ('default' required).\n *  Edit the copy; keep the hours ascending. */\nconst LADDER: ReadonlyArray<{ afterHours: number; messages: Messages }> = [\n  { afterHours: 24, messages: {\n    default: { title: 'Pick up where you left off', body: 'Your streak is waiting for you.' },\n    ar: { title: '\u0623\u0643\u0645\u0644 \u0645\u0646 \u062D\u064A\u062B \u062A\u0648\u0642\u0641\u062A', body: '\u0633\u0644\u0633\u0644\u062A\u0643 \u0628\u0627\u0646\u062A\u0638\u0627\u0631\u0643.' },\n  } },\n  { afterHours: 72, messages: {\n    default: { title: 'We saved your progress', body: 'It only takes a minute to get back on track.' },\n    ar: { title: '\u062D\u0641\u0638\u0646\u0627 \u062A\u0642\u062F\u0645\u0643', body: '\u062F\u0642\u064A\u0642\u0629 \u0648\u0627\u062D\u062F\u0629 \u062A\u0643\u0641\u064A \u0644\u0644\u0639\u0648\u062F\u0629.' },\n  } },\n  { afterHours: 168, messages: {\n    default: { title: 'Still there?', body: 'Here is what you missed this week.' },\n    ar: { title: '\u0647\u0644 \u0645\u0627 \u0632\u0644\u062A \u0647\u0646\u0627\u061F', body: '\u0625\u0644\u064A\u0643 \u0645\u0627 \u0641\u0627\u062A\u0643 \u0647\u0630\u0627 \u0627\u0644\u0623\u0633\u0628\u0648\u0639.' },\n  } },\n];\n/** `push_prefs` rows read per tick. */\nconst MAX_LADDER_ROWS = 2000;\n/** Users nudged per tick (each costs a claim PATCH, a device read and receipt PATCHes). */\nconst MAX_REMINDERS = 100;\n/** This cron's row in `push_state`. */\nconst LADDER_STATE_KEY = 'reminder-ladder';\n\ntype Copy = { title?: string; body?: string };\ntype Messages = Record<string, Copy>;\ntype Env = CronFunctionEnvelope | HttpFunctionEnvelope<{\n  user_ids?: string[];\n  messages?: Messages;\n  data?: Record<string, unknown>;\n}>;\ninterface TokenRow {\n  item_id: string;\n  version?: number;\n  data: { token?: string; end_user?: string; locale?: string; failures?: number };\n}\n/** One entry of Expo's response array, positionally matched to the request. */\ninterface Ticket { status?: string; id?: string; message?: string; details?: { error?: string } }\ninterface PrefRow {\n  item_id: string;\n  version?: number;\n  data: {\n    end_user?: string; timezone?: string; reminders?: boolean; quiet_start?: number; quiet_end?: number;\n    last_active?: string; ladder_step?: number; last_reminded_at?: string;\n  };\n}\ninterface StateRow { item_id: string; version?: number; data: { cursor?: string } }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return json({ error: 'missing cms scope' }, 403);\n    const H = { authorization: `Bearer ${cms}`, 'content-type': 'application/json' };\n    if (env.trigger === 'cron') return ladder(base, H);\n\n    const p = (env as Exclude<Env, CronFunctionEnvelope>).payload ?? {};\n    const userIds = Array.isArray(p.user_ids) ? p.user_ids.filter((u) => typeof u === 'string' && u) : [];\n    const messages = p.messages ?? {};\n    if (userIds.length === 0) return json({ error: 'user_ids is required' }, 400);\n    if (!messages.default?.title && !messages.default?.body) {\n      return json({ error: 'messages.default { title, body } is required' }, 400);\n    }\n    const devices = await resolveDevices(base, H, userIds);\n    if (devices.length === 0) return json({ sent: 0, devices: 0, note: 'no registered devices' }, 200);\n    const out = await sendTo(base, H, devices.map((d) => ({ device: d, messages })), p.data);\n    return json({ devices: devices.length, ...out }, 200);\n  },\n};\n\n/** \u2500\u2500 1. Resolve devices. One filtered read per user (owner-scoped by value,\n *  not by principal \u2014 this runs in server mode). */\nasync function resolveDevices(base: string, H: Record<string, string>, userIds: string[]): Promise<TokenRow[]> {\n  const devices: TokenRow[] = [];\n  for (const uid of userIds) {\n    if (devices.length >= MAX_DEVICES) break;\n    const filter = encodeURIComponent(JSON.stringify({ end_user: uid }));\n    const res = await fetch(`${base}/v1/cms/items/push_tokens?filter=${filter}&limit=50`, { headers: H });\n    if (!res.ok) continue;\n    const items = ((await res.json()) as { data?: { items?: TokenRow[] } }).data?.items ?? [];\n    for (const it of items) if (it.data.token) devices.push(it);\n  }\n  return devices;\n}\n\n/** \u2500\u2500 2 + 3. One message per device in that device's language; send in\n *  batches; reconcile each ticket back to its device by index. */\nasync function sendTo(\n  base: string, H: Record<string, string>,\n  targets: Array<{ device: TokenRow; messages: Messages }>, data?: Record<string, unknown>,\n): Promise<{ accepted: number; dropped: number; errors: string[] }> {\n  const outgoing = targets.map(({ device, messages }) => {\n    const copy = pick(messages, device.data.locale);\n    return {\n      to: device.data.token!,\n      ...(copy.title ? { title: copy.title } : {}),\n      ...(copy.body ? { body: copy.body } : {}),\n      ...(data ? { data } : {}),\n      sound: 'default',\n    };\n  });\n  let accepted = 0;\n  let dropped = 0;\n  const errors: string[] = [];\n  for (let i = 0; i < outgoing.length; i += BATCH) {\n    const slice = outgoing.slice(i, i + BATCH);\n    const res = await fetch(PUSH_URL, {\n      method: 'POST',\n      headers: { 'content-type': 'application/json', accept: 'application/json' },\n      body: JSON.stringify(slice),\n    }).catch(() => null);\n    if (!res || !res.ok) {\n      errors.push(`push service returned ${res?.status ?? 'network error'} for batch ${i / BATCH}`);\n      continue;\n    }\n    const tickets = (((await res.json().catch(() => ({}))) as { data?: Ticket[] }).data) ?? [];\n    for (let k = 0; k < slice.length; k++) {\n      const device = targets[i + k]!.device;\n      const ticket = tickets[k];\n      if (ticket?.status === 'ok' && ticket.id) {\n        // Accepted, verdict pending. Park the receipt id (and when) for prune-receipts.\n        accepted++;\n        await patch(base, H, device, { receipt_id: ticket.id, receipt_at: new Date().toISOString(), failures: 0, last_error: '' });\n        continue;\n      }\n      const reason = ticket?.details?.error ?? ticket?.message ?? 'unknown';\n      if (reason === 'DeviceNotRegistered') {\n        // Definitive: this token will never deliver again. \u2605 INVARIANT 3.\n        await del(base, H, device);\n        dropped++;\n        continue;\n      }\n      // Anything else (MessageTooBig, MessageRateExceeded, a transient fault)\n      // is NOT a reason to delete a device. Count it and move on.\n      await patch(base, H, device, {\n        failures: (device.data.failures ?? 0) + 1,\n        last_error: String(reason).slice(0, 300),\n      });\n      errors.push(reason);\n    }\n  }\n  return { accepted, dropped, errors: errors.slice(0, 10) };\n}\n\n// \u2500\u2500 The reminder ladder \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nasync function ladder(base: string, H: Record<string, string>): Promise<Response> {\n  const now = new Date();\n  const state = await readState(base, H, LADDER_STATE_KEY);\n  if (state === 'error') return json({ error: 'state_read_failed' }, 502);\n  const startedAt = state?.data.cursor || null;\n  // Only users idle for at least the first step, with a rung still ahead of\n  // them, can be due: both terms ride slot indexes (`last_active` t1,\n  // `ladder_step` n1), so active users and finished ladders are never read.\n  const idleSince = new Date(now.getTime() - LADDER[0]!.afterHours * 3_600_000).toISOString();\n  const filter = encodeURIComponent(JSON.stringify({\n    last_active: { $lt: idleSince }, ladder_step: { $lt: LADDER.length },\n  }));\n\n  const due: Array<{ row: PrefRow; step: number }> = [];\n  let cursor: string | null = startedAt;\n  let scanned = 0;\n  let wrapped = false;\n  let quiet = 0;\n  scan: while (scanned < MAX_LADDER_ROWS) {\n    const res = await fetch(`${base}/v1/cms/items/push_prefs?filter=${filter}&limit=${PAGE}`\n      + (cursor ? `&cursor=${encodeURIComponent(cursor)}` : ''), { headers: H });\n    if (!res.ok) return json({ error: 'list_failed', status: res.status }, 502);\n    const body = (await res.json()) as { data?: { items?: PrefRow[]; next_cursor?: string | null } };\n    const items = body.data?.items ?? [];\n    for (const it of items) {\n      scanned++;\n      cursor = it.item_id;\n      const step = dueStep(it.data, now);\n      if (step !== null) {\n        if (inQuietHours(it.data, now)) quiet++; // left for a later tick: the cursor wraps back to it\n        else due.push({ row: it, step });\n      }\n      if (due.length >= MAX_REMINDERS || scanned >= MAX_LADDER_ROWS) break scan;\n    }\n    if (!body.data?.next_cursor || items.length === 0) { wrapped = true; break; }\n    cursor = body.data.next_cursor;\n  }\n  const nextCursor = wrapped ? '' : (cursor ?? '');\n\n  // Claim each step FIRST (If-Match): a concurrent tick that claimed it wins,\n  // and this one skips the user \u2014 never a double nudge.\n  const targets: Array<{ device: TokenRow; messages: Messages }> = [];\n  let claimed = 0;\n  for (const { row, step } of due) {\n    const res = await fetch(`${base}/v1/cms/items/push_prefs/${row.item_id}`, {\n      method: 'PATCH',\n      headers: { ...H, ...(row.version !== undefined ? { 'if-match': String(row.version) } : {}) },\n      body: JSON.stringify({ data: { ladder_step: step + 1, last_reminded_at: now.toISOString() } }),\n    }).catch(() => null);\n    if (!res || !res.ok) continue;\n    claimed++;\n    for (const device of await resolveDevices(base, H, [row.data.end_user!])) {\n      targets.push({ device, messages: LADDER[step]!.messages });\n    }\n  }\n  const sent = targets.length > 0\n    ? await sendTo(base, H, targets, { reason: 'reminder' })\n    : { accepted: 0, dropped: 0, errors: [] as string[] };\n  const saved = await writeState(base, H, LADDER_STATE_KEY, state, nextCursor);\n  return json({\n    ladder: true, scanned, due: due.length, quiet, claimed, devices: targets.length, ...sent,\n    resumed_from: startedAt, cursor: nextCursor, wrapped, saved,\n  }, 200);\n}\n\n/** The ladder step due for this user now, or null. Exported for tests.\n *  The HIGHEST rung whose idle threshold is met (the claim then moves\n *  `ladder_step` past it, so the rungs below are skipped, never sent late), and\n *  only once that rung's gap since the previous nudge has passed. */\nexport function dueStep(p: PrefRow['data'], now: Date): number | null {\n  if (p.reminders === false || !p.end_user || !p.last_active) return null;\n  const idleH = (now.getTime() - Date.parse(p.last_active)) / 3_600_000;\n  if (!Number.isFinite(idleH)) return null;\n  const from = Math.max(0, Math.trunc(p.ladder_step ?? 0));\n  let step: number | null = null;\n  for (let r = from; r < LADDER.length; r++) if (idleH >= LADDER[r]!.afterHours) step = r;\n  if (step === null) return null;\n  if (step > 0 && p.last_reminded_at) {\n    const sinceH = (now.getTime() - Date.parse(p.last_reminded_at)) / 3_600_000;\n    const gapH = LADDER[step]!.afterHours - LADDER[step - 1]!.afterHours;\n    if (Number.isFinite(sinceH) && sinceH < gapH) return null;\n  }\n  return step;\n}\n\n/** Is it inside the user's quiet hours [quiet_start, quiet_end) in THEIR zone?\n *  The window may wrap midnight; equal or missing bounds mean none. An unknown\n *  zone is evaluated in UTC. Exported for tests. */\nexport function inQuietHours(p: PrefRow['data'], now: Date): boolean {\n  const start = p.quiet_start;\n  const end = p.quiet_end;\n  if (typeof start !== 'number' || typeof end !== 'number' || start === end) return false;\n  const h = localHour(now, p.timezone);\n  return start < end ? h >= start && h < end : h >= start || h < end;\n}\n\n/** One formatter per zone, kept for the isolate's life: building an Intl formatter is the\n *  expensive part, and a tick can test hundreds of users in the same few zones\n *  (CPU per invocation is capped \u2014 50 ms on the Free plan). */\nconst ZONE_FMT = new Map<string, Intl.DateTimeFormat | null>();\nfunction zoneFormatter(tz: string): Intl.DateTimeFormat | null {\n  if (!ZONE_FMT.has(tz)) {\n    let f: Intl.DateTimeFormat | null = null;\n    try { f = new Intl.DateTimeFormat('en-US', { timeZone: tz, hour: 'numeric', hourCycle: 'h23' }); } catch { /* unknown zone */ }\n    if (ZONE_FMT.size < 500) ZONE_FMT.set(tz, f);\n    return f;\n  }\n  return ZONE_FMT.get(tz)!;\n}\n\nfunction localHour(now: Date, tz: string | undefined): number {\n  try {\n    const part = zoneFormatter(tz || 'UTC')?.formatToParts(now).find((x) => x.type === 'hour');\n    const h = Number(part?.value);\n    if (Number.isInteger(h)) return h % 24;\n  } catch { /* unknown zone \u2192 UTC below */ }\n  return now.getUTCHours();\n}\n\nasync function readState(base: string, H: Record<string, string>, key: string): Promise<StateRow | null | 'error'> {\n  const filter = encodeURIComponent(JSON.stringify({ key }));\n  const res = await fetch(`${base}/v1/cms/items/push_state?filter=${filter}&limit=1`, { headers: H });\n  if (!res.ok) return 'error';\n  return ((await res.json()) as { data?: { items?: StateRow[] } }).data?.items?.[0] ?? null;\n}\n\nasync function writeState(\n  base: string, H: Record<string, string>, key: string, state: StateRow | null, cursor: string,\n): Promise<boolean> {\n  const data = { key, cursor, updated_at: new Date().toISOString() };\n  const res = state\n    ? await fetch(`${base}/v1/cms/items/push_state/${state.item_id}`, {\n      method: 'PATCH',\n      headers: { ...H, ...(state.version !== undefined ? { 'if-match': String(state.version) } : {}) },\n      body: JSON.stringify({ data }),\n    }).catch(() => null)\n    : await fetch(`${base}/v1/cms/items/push_state`, {\n      method: 'POST', headers: H, body: JSON.stringify({ status: 'published', data }),\n    }).catch(() => null);\n  return !!res && res.ok;\n}\n\n/** Locale match: exact ('pt-BR'), then the base language ('pt'), then default. */\nfunction pick(messages: Messages, locale: string | undefined): Copy {\n  if (locale) {\n    if (messages[locale]) return messages[locale]!;\n    const bare = locale.split('-')[0]!;\n    if (messages[bare]) return messages[bare]!;\n  }\n  return messages.default ?? {};\n}\n\nasync function patch(base: string, H: Record<string, string>, d: TokenRow, data: Record<string, unknown>) {\n  await fetch(`${base}/v1/cms/items/push_tokens/${d.item_id}`, {\n    method: 'PATCH', headers: H, body: JSON.stringify({ data }),\n  }).catch(() => null);\n}\nasync function del(base: string, H: Record<string, string>, d: TokenRow) {\n  await fetch(`${base}/v1/cms/items/push_tokens/${d.item_id}`, { method: 'DELETE', headers: H }).catch(() => null);\n}\nconst json = (o: unknown, status: number) => Response.json(o, { status });\n"
     }
   },
   {
@@ -17412,7 +18275,7 @@ const json = (o: unknown, status: number) => Response.json(o, { status });
     "configSrc": "import { defineConfig } from '@vxil/config';\n\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// \"Alerts to Slack\" \u2014 failure events \u2192 one chat message per state crossing.\n//\n// There is no vxil \"connectors\" feature and no alert-routing engine, on purpose:\n// every feature already writes its lifecycle to your tenant's audit stream, and\n// a function can read that stream. This blueprint is DISTRIBUTION over that\n// spine \u2014 one cron function, one cms collection as its memory, one BYO webhook:\n//   \u2022 cms       \u2192 `alert_state`: the watermark + per-condition state (ok|stale|\n//                 broken|could_not_check) that makes alerts once-per-crossing\n//   \u2022 functions \u2192 `alerts`: drains the audit stream past the watermark every\n//                 5 minutes, matches an allow-list of failure events, posts\n//                 to Slack (or Discord) through the egress allowlist\n// A permanently-red condition therefore produces ONE message when it turns red,\n// ONE when it recovers, and (optionally) a reminder every REPEAT_AFTER_HOURS.\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nexport default defineConfig({\n  env: 'staging',\n\n  features: {\n    cms: {},\n    functions: { enabled: true },\n  },\n\n  cms: {\n    collections: {\n      // The function's memory. One row per alert KEY (e.g. `payments:ingest:stripe`,\n      // `jobs:dead-letter:notifications.deliver`, `functions:checkout`) plus the\n      // reserved `__cursor__` row that holds the audit-stream watermark.\n      alert_state: {\n        singular: 'alert_state',\n        fields: {\n          key: { type: 'string', required: true, indexSlot: 's1', unique: true }, // unique \u21D2 409 on a racing duplicate\n          state: { type: 'string', indexSlot: 's2' }, // ok | stale | broken | could_not_check\n          level: { type: 'string', indexSlot: 's3' }, // info | warn | error\n          event: { type: 'string' }, // the last audit event name seen for this key\n          detail: { type: 'text' }, // last reason/error text (truncated)\n          cursor: { type: 'string' }, // `__cursor__` row only: last processed audit id\n          last_event_id: { type: 'string' },\n          last_alert_at: { type: 'datetime', indexSlot: 't1' },\n          updated_at: { type: 'datetime', indexSlot: 't2' },\n        },\n      },\n    },\n  },\n\n  functions: {\n    // The whole blueprint is this one function. Cron every 5 minutes; also\n    // invocable by hand (`vxil functions invoke alerts --data '{\"test\":true}'`)\n    // to prove the webhook is wired without touching the watermark.\n    alerts: {\n      entry: './functions/alerts.ts',\n      trigger: { kind: 'cron', schedule: '*/5 * * * *' },\n      scopes: ['cms:read', 'cms:write'],\n      // Two BYO secrets, resolved per invocation and injected as env.secrets.<name>:\n      //   slack_webhook_url \u2014 the Slack incoming-webhook URL (or a Discord webhook,\n      //                       or a Google Chat space webhook)\n      //   vxil_read_key     \u2014 an API key of YOUR tenant holding ONLY `features:read`;\n      //                       the audit stream is not reachable through the\n      //                       function's scoped callback, so the drain reads it with\n      //                       this least-privilege key instead\n      secrets: ['secret:slack_webhook_url', 'secret:vxil_read_key'],\n      // Deny-by-default egress: only the chat host (add 'discord.com' for Discord,\n      // 'chat.googleapis.com' for a Google Chat space webhook).\n      egressAllow: ['hooks.slack.com'],\n    },\n  },\n\n  secrets: {\n    slack_webhook_url: { feature: 'functions', description: 'Slack incoming webhook (or Discord / Google Chat space webhook) URL' },\n    vxil_read_key: { feature: 'functions', description: 'a vxil API key with only features:read \u2014 reads the audit stream' },\n  },\n});\n",
     "readme": "# Alerts to Slack (ops)\n\nFailure events from your backend \u2192 **one Slack (or Discord) message per state crossing**, with a\n\"resolved\" message when the condition clears. No connectors registry, no alert-routing feature \u2014 one\ncron function that drains your tenant's **audit stream** past a watermark, an allow-list of failure\nevents it cares about, and a `cms` collection as its memory so a permanently-red condition never\nspams the channel.\n\n```bash\nvxil init --template alerts-to-slack\nvxil quickstart                       # or `vxil link <slug>` for an existing backend\nprintf '%s' \"$SLACK_URL\" | vxil secrets set functions/slack_webhook_url\nprintf '%s' \"$READ_KEY\"  | vxil secrets set functions/vxil_read_key\nvxil push                             # collection + the `alerts` cron function\nvxil functions invoke alerts --data '{\"test\":true}'   # posts a test message\n```\n\n**The two secrets** (references in the config, values only ever in the encrypted secret store):\n\n| Secret | What it is | Where it comes from |\n|---|---|---|\n| `slack_webhook_url` | a Slack *incoming webhook* URL (or a Discord webhook URL, or a Google Chat *space webhook* URL) | Slack \u2192 Apps \u2192 Incoming Webhooks; Discord \u2192 channel \u2192 Integrations \u2192 Webhooks; Google Chat \u2192 space \u2192 Apps & integrations \u2192 Webhooks |\n| `vxil_read_key` | an API key **of this tenant** holding **only `features:read`** | dashboard \u2192 API keys \u2192 create, tick `features:read` and nothing else |\n\nWhy a key at all? The audit stream (`GET /v1/audit` and its NDJSON export) is a control-plane read that is\n**not** on a function's scoped callback (the callback covers the feature APIs \u2014 cms, payments, jobs\u2026),\nso the drain reads it with the narrowest key that can: read-only, no write scope, revocable in one click.\nFor Discord, add `'discord.com'` to `egressAllow` \u2014 the function sends both Slack's `text` and Discord's\n`content` field, so one message body works on either.\nFor Google Chat, add `'chat.googleapis.com'` to `egressAllow` \u2014 a space webhook takes `text` alone, and the\nfunction sends only that field to that host.\n\n## What it does, every 5 minutes\n\n1. **Watermark.** Reads the `__cursor__` row in `alert_state`. On the very first run it stores the\n   *newest* audit id and stops \u2014 history never becomes an alert storm.\n2. **Drain.** `GET /v1/audit/export?after_id=<cursor>&limit=500` (ascending NDJSON), up to 5 pages a tick.\n3. **Match.** Each row is looked up in `RULES` (the allow-list in `functions/alerts.ts`). Anything not\n   listed is ignored. A match becomes `(key, state, level)` \u2014 e.g. a `payments.webhook_event.failed`\n   row with `provider: stripe, state: broken` \u2192 key `payments:ingest:stripe`, state `broken`.\n4. **Compare + decide.** One `alert_state` row per key. Only a **crossing** posts:\n   - not-ok while the row said ok (or no row yet) \u2192 \u{1F534}/\u{1F7E0} alert\n   - ok while the row said not-ok \u2192 \u{1F7E2} \"RESOLVED\"\n   - same state again \u2192 silence (a \u23F0 reminder after `REPEAT_AFTER_HOURS`, default 24; `0` disables)\n5. **Advance** the watermark with `If-Match` on the cursor row's version. Cron deliveries are\n   at-least-once; if two ticks overlap, the first to move the watermark wins, and the `unique` key plus\n   `If-Match` on every state row mean a racing run gets a 409 and stands down instead of double-posting.\n\n## The events it listens for\n\nEvery name in the table below is an audit event a vxil feature writes **today**. Keys are what collapse\nrepeats: ten dead letters of the same job are one key, one row, one alert.\n\n| Audit event | Level | Key (one row each) | State |\n|---|---|---|---|\n| `payments.webhook_event.failed` | from payload (`error`) | `payments:ingest:<provider>` | from payload (`broken`) |\n| `payments.webhook.rejected` | from payload (`warn`) | `payments:webhook-rejected:<provider>` | from payload (`broken`) |\n| `payments.grant.failed` | from payload (`error`) | `payments:grant:<credit_type>:<source>` | from payload (`broken`) |\n| `payments.subscription.past_due` | warn | `payments:subscription:<end_user_id>` | broken |\n| `payments.subscription.active` | info | `payments:subscription:<end_user_id>` | **ok** \u2192 posts RESOLVED |\n| `payments.charge.disputed` | warn | `payments:disputes:<provider>` | broken |\n| `job.dead_lettered` | error | `jobs:dead-letter:<job_name>` | broken |\n| `job.dead_letter_quota_exceeded` | error | `jobs:dead-letter-quota` | broken |\n| `job.generation.failed` | error | `jobs:generation:<error_class>` | broken |\n| `functions.quarantined` | error | `functions:<name>` | broken |\n| `functions.quarantine.cleared` | info | `functions:<name>` | **ok** \u2192 posts RESOLVED |\n| `functions.deploy.denied` | warn | `functions:deploy-denied` | broken |\n| `notifications.delivery.dead_lettered` | from payload (`error`) | `notifications:dead-letter:<template_id>` | from payload (`broken`) |\n| `webhooks.delivery.dead_lettered` | from payload (`error`) | `webhooks:delivery:<subscription_id>` | from payload (`broken`) |\n| `webhooks.delivery.recovered` | from payload (`info`) | `webhooks:delivery:<subscription_id>` | **ok** \u2192 posts RESOLVED |\n| `webhooks.inbound.rejected` | from payload (`warn`) | `webhooks:inbound:<source_id>:<reason>` | from payload (`broken`) |\n| `jobs.schedule.missed` | from payload (`warn`) | `jobs:schedule:<schedule_id>` | from payload (**`stale`** \u2014 late, not broken) |\n| `jobs.schedule.recovered` | from payload (`info`) | `jobs:schedule:<schedule_id>` | **ok** \u2192 posts RESOLVED |\n| `functions.run.failed` | from payload (`error`) | `functions:run:<name>` | from payload (`broken`) |\n| `functions.run.recovered` | from payload (`info`) | `functions:run:<name>` | **ok** \u2192 posts RESOLVED |\n\n**Levels differ by event, and the table respects that.** The payments failure events and every\nlifecycle failure event (the last nine rows) carry their own `level` and `state` in the payload, so those\nrules defer to the event. The older `job.*` and `functions.quarantine*` events supply both from the rule.\n\n**Five pairs close their own alerts.** `past_due` \u2192 `active`, `quarantined` \u2192 `quarantine.cleared`,\n`webhooks.delivery.dead_lettered` \u2192 `.recovered`, `jobs.schedule.missed` \u2192 `.recovered` and\n`functions.run.failed` \u2192 `.recovered` share a key, so a recovery posts RESOLVED with no extra rule. Events with no natural \"ok\" \u2014 a dead\nletter \u2014 stay red until the reminder window, which is what `REPEAT_AFTER_HOURS` is for.\n\n**The same failure can arrive twice, on purpose.** Notification sends and outbound webhook deliveries\nride the jobs substrate, so a dead letter also arrives as `job.dead_lettered` with `job_name` set to\n`notifications.deliver` / `webhooks.deliver`. The dedicated `*.dead_lettered` events carry the\nfeature-level context (template id, subscription id, target host) that the generic job row lacks; keep\nboth rules, or drop `job.dead_lettered` if you only want the feature-level view.\n\n**Own the table.** `RULES` is data: add an event name, decide its key and level, push.\n\n## The message\n\n```\n\u{1F534} [ERROR] payments ingest (stripe) \u2192 BROKEN \u2014 signature verification failed (at 2026-09-10T06:00:12Z)\n\u{1F534} [ERROR] job dead-lettered: notifications.deliver \u2192 BROKEN (at 2026-09-10T06:03:44Z)\n\u23F0 STILL BROKEN: function quarantined: checkout (since 2026-09-09T06:01:02Z)\n\u{1F7E2} RESOLVED: payments ingest (stripe) is back to ok (was broken)\n```\n\n## What to learn from this\n\n- **The audit stream is the event spine.** Every feature writes its lifecycle there; a webhook\n  subscription fans it out, and a function can drain it. Nothing here needed a new primitive.\n- **Once-per-crossing suppression needs memory \u2014 a cms collection is that memory.** `unique` on `key`\n  and `If-Match` on every write make it correct under the at-least-once cron, not just usually right.\n- **Least privilege has a shape.** The function talks to cms through its scoped callback, reads the\n  audit stream with a `features:read`-only key it holds as a secret, and can reach exactly one external\n  host. Rotate either secret without a redeploy \u2014 refs resolve per invocation.\n\n**Latency:** a failure is posted within one cron interval (5 minutes) of the audit row landing.\n**Pairs with:** `templates/payments-heartbeat/` (the silence detector that emits its own crossings) and\n`templates/push-notifications/`.\n",
     "functions": {
-      "alerts.ts": "// alerts.ts \u2014 FAILURE EVENTS \u2192 ONE CHAT MESSAGE PER STATE CROSSING (a vxil function).\n//\n// Trigger: cron `*/5 * * * *`. Each run:\n//   1. reads the watermark (the `__cursor__` row in `alert_state`; first run = \"now\",\n//      so history never produces an alert storm),\n//   2. drains the tenant audit stream past it \u2014 `GET /v1/audit/export?after_id=\u2026`\n//      (ascending, NDJSON) with the `vxil_read_key` secret (a key holding ONLY\n//      `features:read`; the audit stream is not on the scoped callback),\n//   3. matches each row against RULES (the allow-list below) and turns it into a\n//      (key, state, level) \u2014 e.g. `payments:ingest:stripe` \u2192 `broken`,\n//   4. compares with the stored state for that key (cms, one row per key, `unique`\n//      key \u21D2 a racing run gets a 409 and stands down) and posts ONLY on a crossing:\n//      ok\u2192red = alert, red\u2192ok = \"resolved\", red\u2192red = silence (or a reminder after\n//      REPEAT_AFTER_HOURS),\n//   5. advances the watermark (If-Match on the cursor row's version \u2014 a concurrent\n//      run that already advanced it wins; jobs may deliver a cron tick twice).\n//\n// Manual check: `vxil functions invoke alerts --data '{\"test\":true}'` posts a test\n// message and touches nothing else.\n//\n// Tune the constants; own the RULES table \u2014 it is data, not a routing engine.\n\nimport type { CronFunctionEnvelope, HttpFunctionEnvelope } from '@vxil/sdk';\n\nconst REPEAT_AFTER_HOURS = 24; // remind about a still-red condition this often; 0 = never\nconst MAX_PAGES_PER_RUN = 5; // \xD7 500 audit rows \u2014 bounds one cron tick\nconst MAX_POSTS_PER_RUN = 20; // a burst of distinct failures collapses into one summary line\nconst DETAIL_MAX = 240;\n\ntype Level = 'info' | 'warn' | 'error';\ntype State = 'ok' | 'stale' | 'broken' | 'could_not_check';\ntype Payload = Record<string, unknown>;\n\ninterface Rule {\n  /** A literal level, or 'payload' to take `payload.level` (the payments failure\n   *  events carry one; the jobs/functions ones do not). */\n  level: Level | 'payload';\n  key: (p: Payload) => string; // one state row per key \u2014 this is what suppresses repeats\n  title: (p: Payload) => string;\n  /** A literal state, or omitted to take `payload.state` (falling back to 'broken'). */\n  state?: State;\n}\n\nconst str = (v: unknown, fallback = 'unknown') => (typeof v === 'string' && v ? v : fallback);\n\n/** THE ALLOW-LIST. Every name below is an audit event a vxil feature writes;\n *  anything not listed is ignored by the drain. The KEY is what collapses\n *  repeats: ten dead letters of the same job are one key, one row, one alert.\n *\n *  Every name below is emitted today (2026-09-10). A rule for an event nobody\n *  emits would simply never match \u2014 so if you add one, verify the emitter first.\n */\nconst RULES: Record<string, Rule> = {\n  // \u2500\u2500 payments \u2014 the money path. A silent failure here is lost revenue. \u2500\u2500\u2500\u2500\u2500\u2500\n  // These three carry `level` (info|warn|error) and `state` (ok|stale|broken|\n  // could_not_check) in their payload, so the rule defers to the event.\n  'payments.webhook_event.failed': {\n    level: 'payload', // emitted as error/broken\n    key: (p) => `payments:ingest:${str(p.provider, 'all')}`,\n    title: (p) => `payments ingest (${str(p.provider, 'all providers')})`,\n  },\n  'payments.webhook.rejected': {\n    level: 'payload', // emitted as warn/broken\n    key: (p) => `payments:webhook-rejected:${str(p.provider)}`,\n    title: (p) => `payments webhook rejected (${str(p.provider)})`,\n  },\n  // NOTE: grant.failed carries NO `provider` \u2014 it is keyed on the credit type\n  // and the grant source instead (end_user_id/credit_type/amount/grant_key/\n  // source/error). Keying on a field an event does not carry would collapse\n  // every provider into one bucket named \"unknown\".\n  'payments.grant.failed': {\n    level: 'payload', // emitted as error/broken\n    key: (p) => `payments:grant:${str(p.credit_type, 'credits')}:${str(p.source, 'webhook')}`,\n    title: (p) => `entitlement grant failed (${str(p.credit_type, 'credits')} via ${str(p.source, 'webhook')})`,\n  },\n  // Dunning. `past_due` is the red crossing and `active` is its RESOLVED twin \u2014\n  // the same key, so a recovered subscription closes its own alert. Both are\n  // emitted at level info, so the rule forces the level it wants.\n  'payments.subscription.past_due': {\n    level: 'warn',\n    key: (p) => `payments:subscription:${str(p.end_user_id, 'unknown-user')}`,\n    title: (p) => `subscription past due (user ${str(p.end_user_id)})`,\n    state: 'broken',\n  },\n  'payments.subscription.active': {\n    level: 'info',\n    key: (p) => `payments:subscription:${str(p.end_user_id, 'unknown-user')}`,\n    title: (p) => `subscription past due (user ${str(p.end_user_id)})`,\n    state: 'ok',\n  },\n  // A dispute is a chargeback in progress \u2014 money already collected, now at risk.\n  'payments.charge.disputed': {\n    level: 'warn',\n    key: (p) => `payments:disputes:${str(p.provider)}`,\n    title: (p) => `charge disputed (${str(p.provider)})`,\n    state: 'broken',\n  },\n\n  // \u2500\u2500 jobs \u2014 the delivery substrate. Notification and outbound-webhook sends\n  //    ride jobs, so THEIR dead letters arrive here too, under `job_name`\n  //    ('notifications.deliver', 'webhooks.deliver', 'fn-cron:<name>', \u2026).\n  //    These payloads carry run_id/attempt/job_name and NO level or state, so\n  //    the rule supplies both. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  'job.dead_lettered': {\n    level: 'error',\n    key: (p) => `jobs:dead-letter:${str(p.job_name)}`,\n    title: (p) => `job dead-lettered: ${str(p.job_name)}`,\n    state: 'broken',\n  },\n  'job.dead_letter_quota_exceeded': {\n    level: 'error',\n    key: () => 'jobs:dead-letter-quota',\n    title: () => 'daily dead-letter quota exceeded',\n    state: 'broken',\n  },\n  'job.generation.failed': {\n    level: 'error',\n    key: (p) => `jobs:generation:${str(p.error_class, 'failed')}`,\n    title: (p) => `generation job failed (${str(p.error_class, 'unclassified')})`,\n    state: 'broken',\n  },\n\n  // \u2500\u2500 functions \u2014 the breaker. Consecutive failures quarantine a function;\n  //    clearing the quarantine is the ok crossing on the SAME key, so this pair\n  //    produces exactly one \u{1F534} and one \u{1F7E2}. Payload: name (+ consecutive_failures).\n  'functions.quarantined': {\n    level: 'error',\n    key: (p) => `functions:${str(p.name)}`,\n    title: (p) => `function quarantined: ${str(p.name)}`,\n    state: 'broken',\n  },\n  'functions.quarantine.cleared': {\n    level: 'info',\n    key: (p) => `functions:${str(p.name)}`,\n    title: (p) => `function quarantined: ${str(p.name)}`,\n    state: 'ok',\n  },\n  'functions.deploy.denied': {\n    level: 'warn',\n    key: () => 'functions:deploy-denied',\n    title: (p) => `function deploy denied (needs the ${str(p.required_tier)} tier)`,\n    state: 'broken',\n  },\n\n  // \u2500\u2500 The lifecycle failure events (live since 2026-09-10). Every one of these\n  //    carries `level` + `state` in its payload (the platform's failure-event\n  //    vocabulary gate enforces it), so the rules defer to the event. Each\n  //    failure/recovery pair shares a key, so a recovery posts RESOLVED. \u2500\u2500\u2500\u2500\u2500\u2500\n  'notifications.delivery.dead_lettered': {\n    level: 'payload', // emitted as error/broken; payload: delivery_id, template_id, error_class, attempts\n    key: (p) => `notifications:dead-letter:${str(p.template_id, 'all')}`,\n    title: (p) => `notification delivery dead-lettered (${str(p.template_id, 'all templates')})`,\n  },\n  'webhooks.delivery.dead_lettered': {\n    level: 'payload', // error/broken; payload: subscription_id, target_host, attempts, error_class\n    key: (p) => `webhooks:delivery:${str(p.subscription_id, 'all')}`,\n    title: (p) => `outbound webhook dead-lettered (${str(p.target_host, str(p.subscription_id, 'all subscriptions'))})`,\n  },\n  'webhooks.delivery.recovered': {\n    level: 'payload', // info/ok \u2014 same key as the dead-letter \u2192 RESOLVED\n    key: (p) => `webhooks:delivery:${str(p.subscription_id, 'all')}`,\n    title: (p) => `outbound webhook dead-lettered (${str(p.target_host, str(p.subscription_id, 'all subscriptions'))})`,\n  },\n  'webhooks.inbound.rejected': {\n    level: 'payload', // warn/broken; payload: source_id, provider, reason, fingerprint (never the body)\n    key: (p) => `webhooks:inbound:${str(p.source_id)}:${str(p.reason)}`,\n    title: (p) => `inbound webhook rejected (${str(p.provider, 'source')} ${str(p.source_id)}: ${str(p.reason)})`,\n  },\n  'jobs.schedule.missed': {\n    level: 'payload', // warn/STALE \u2014 a late tick is stale, not broken; payload: schedule_id, job_name, late_seconds\n    key: (p) => `jobs:schedule:${str(p.schedule_id)}`,\n    title: (p) => `scheduled job did not fire on time (${str(p.job_name, str(p.schedule_id))})`,\n  },\n  'jobs.schedule.recovered': {\n    level: 'payload', // info/ok \u2014 same key \u2192 RESOLVED on the next on-time fire\n    key: (p) => `jobs:schedule:${str(p.schedule_id)}`,\n    title: (p) => `scheduled job did not fire on time (${str(p.job_name, str(p.schedule_id))})`,\n  },\n  // A function's cron trigger that produced NO run for 2\xD7 its interval \u2014 the\n  // platform's silent-schedule watch (error/stale), and the recovery on the same\n  // key. Payload: function, schedule_id, cron, last_run_at, expected_by.\n  'functions.schedule.missed': {\n    level: 'payload',\n    key: (p) => `functions:schedule:${str(p.function, str(p.schedule_id))}`,\n    title: (p) => `cron function stopped firing: ${str(p.function, str(p.job_name))} (last run ${str(p.last_run_at, 'never')})`,\n  },\n  'functions.schedule.recovered': {\n    level: 'payload', // info/ok \u2014 same key \u2192 RESOLVED when a run appears again\n    key: (p) => `functions:schedule:${str(p.function, str(p.schedule_id))}`,\n    title: (p) => `cron function stopped firing: ${str(p.function, str(p.job_name))}`,\n  },\n  'functions.run.failed': {\n    level: 'payload', // error/broken; payload: name, trigger, run_id, error_class\n    key: (p) => `functions:run:${str(p.name)}`,\n    title: (p) => `function failing: ${str(p.name)} (${str(p.trigger, 'trigger')})`,\n  },\n  'functions.run.recovered': {\n    level: 'payload', // info/ok \u2014 same key \u2192 RESOLVED\n    key: (p) => `functions:run:${str(p.name)}`,\n    title: (p) => `function failing: ${str(p.name)} (${str(p.trigger, 'trigger')})`,\n  },\n};\n\n// the schedule tick, or a hand invoke (`POST /v1/fn/alerts`) carrying `{ test: true }`\ntype Envelope = CronFunctionEnvelope | HttpFunctionEnvelope<{ test?: boolean }>;\ninterface AuditRow { id: string | number; event: string; payload?: Payload; created_at?: string }\ninterface StateData {\n  key: string; state?: State; level?: Level; event?: string; detail?: string;\n  cursor?: string; last_event_id?: string; last_alert_at?: string; updated_at?: string;\n}\ninterface Item { item_id: string; version?: number; data: StateData }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Envelope;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const hook = env.secrets?.slack_webhook_url;\n    const readKey = env.secrets?.vxil_read_key;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n    if (!hook || !readKey) return Response.json({ error: 'missing secrets' }, { status: 409 });\n\n    // Manual wiring check \u2014 posts, touches nothing else.\n    if (env.payload?.test) {\n      const r = await post(hook, `\u{1F7E2} [INFO] alerts-to-slack is wired (test message)`);\n      return Response.json({ test: true, posted: r.ok, status: r.status });\n    }\n\n    const store = new Store(base, cms);\n\n    // 1. the watermark (first run: start at the newest audit id \u2014 no history storm)\n    const cursorRow = await store.byKey('__cursor__');\n    if (!cursorRow) {\n      const head = await newestAuditId(base, readKey);\n      await store.create({ key: '__cursor__', cursor: head, updated_at: iso() });\n      return Response.json({ initialized: true, cursor: head });\n    }\n    let cursor = cursorRow.data.cursor ?? '0';\n    const cursorVersion = cursorRow.version;\n\n    // 2\u20134. drain + evaluate\n    const posts: string[] = [];\n    let scanned = 0;\n    let matched = 0;\n    for (let page = 0; page < MAX_PAGES_PER_RUN; page++) {\n      const { rows, next } = await exportAudit(base, readKey, cursor);\n      for (const row of rows) {\n        scanned++;\n        const rule = RULES[row.event];\n        if (rule) {\n          matched++;\n          const msg = await evaluate(store, rule, row);\n          if (msg) posts.push(msg);\n        }\n        cursor = String(row.id);\n      }\n      if (!next) break;\n      cursor = next;\n    }\n\n    // deliver (bounded)\n    let posted = 0;\n    const lines = posts.slice(0, MAX_POSTS_PER_RUN);\n    if (posts.length > MAX_POSTS_PER_RUN) lines.push(`\u2026 and ${posts.length - MAX_POSTS_PER_RUN} more state changes this tick`);\n    for (const text of lines) {\n      const r = await post(hook, text);\n      if (r.ok) posted++;\n    }\n\n    // 5. advance the watermark \u2014 If-Match: a concurrent run that already moved it wins\n    const advanced = await store.patch(cursorRow.item_id, cursorVersion, { cursor, updated_at: iso() });\n\n    return Response.json({ scanned, matched, alerts: posts.length, posted, cursor, advanced });\n  },\n};\n\n/** Decide, for one matched audit row, whether a message is due; persist the state. */\nasync function evaluate(store: Store, rule: Rule, row: AuditRow): Promise<string | null> {\n  const p = row.payload ?? {};\n  const key = rule.key(p);\n  const next: State = rule.state ?? (isState(p.state) ? p.state : 'broken');\n  const level: Level = rule.level === 'payload' ? (isLevel(p.level) ? p.level : 'error') : rule.level;\n  const title = rule.title(p);\n  const detail = str(p.reason ?? p.error ?? p.message ?? p.last_error_msg, '').slice(0, DETAIL_MAX);\n  const now = iso();\n  const eventId = String(row.id);\n  const base: StateData = { key, state: next, level, event: row.event, detail, last_event_id: eventId, updated_at: now };\n\n  const current = await store.byKey(key);\n  if (!current) {\n    // First sighting. A green first sighting is remembered silently \u2014 nothing was red.\n    if (next === 'ok') { await store.create(base); return null; }\n    const created = await store.create({ ...base, last_alert_at: now });\n    return created ? format(level, next, title, detail, row.created_at) : null; // 409 = a racing run owns it\n  }\n  const prev = current.data.state ?? 'ok';\n  if (prev !== next) {\n    // A CROSSING. If-Match: exactly one concurrent run wins the transition.\n    const ok = await store.patch(current.item_id, current.version, { ...base, last_alert_at: now });\n    if (!ok) return null;\n    return next === 'ok'\n      ? `\u{1F7E2} RESOLVED: ${title} is back to ok (was ${prev})`\n      : format(level, next, title, detail, row.created_at);\n  }\n  // Same state. Red stays quiet \u2014 unless a reminder is due.\n  if (next !== 'ok' && REPEAT_AFTER_HOURS > 0) {\n    const last = Date.parse(current.data.last_alert_at ?? '') || 0;\n    if (Date.now() - last >= REPEAT_AFTER_HOURS * 3600e3) {\n      const ok = await store.patch(current.item_id, current.version, { ...base, last_alert_at: now });\n      return ok ? `\u23F0 STILL ${next.toUpperCase()}: ${title} (since ${current.data.last_alert_at ?? '?'})` : null;\n    }\n  }\n  await store.patch(current.item_id, current.version, base); // keep detail/last_event_id fresh, no post\n  return null;\n}\n\nfunction format(level: Level, state: State, title: string, detail: string, at?: string): string {\n  const dot = level === 'error' ? '\u{1F534}' : level === 'warn' ? '\u{1F7E0}' : '\u{1F535}';\n  return `${dot} [${level.toUpperCase()}] ${title} \u2192 ${state.toUpperCase()}${detail ? ` \u2014 ${detail}` : ''}${at ? ` (at ${at})` : ''}`;\n}\n\n// \u2500\u2500 the audit stream (ascending NDJSON export; `x-vxil-next-after-id` continues it) \u2500\u2500\nasync function exportAudit(base: string, key: string, afterId: string): Promise<{ rows: AuditRow[]; next: string | null }> {\n  const res = await fetch(`${base}/v1/audit/export?after_id=${encodeURIComponent(afterId)}&limit=500`, {\n    headers: { authorization: `Bearer ${key}` },\n  });\n  if (!res.ok) throw new Error(`audit export ${res.status}`);\n  const rows = (await res.text()).split('\\n').filter(Boolean).map((l) => JSON.parse(l) as AuditRow);\n  return { rows, next: res.headers.get('x-vxil-next-after-id') };\n}\nasync function newestAuditId(base: string, key: string): Promise<string> {\n  const res = await fetch(`${base}/v1/audit?limit=1`, { headers: { authorization: `Bearer ${key}` } });\n  if (!res.ok) throw new Error(`audit list ${res.status}`);\n  const body = (await res.json()) as { data?: { events?: AuditRow[] } };\n  return String(body.data?.events?.[0]?.id ?? '0');\n}\n\n// \u2500\u2500 the cms state store (the REST envelope: { data: { items:[{item_id, version, data}] } }) \u2500\u2500\nclass Store {\n  constructor(private base: string, private jwt: string) {}\n  private h() { return { authorization: `Bearer ${this.jwt}`, 'content-type': 'application/json' }; }\n  async byKey(key: string): Promise<Item | null> {\n    const filter = encodeURIComponent(JSON.stringify({ key }));\n    const res = await fetch(`${this.base}/v1/cms/items/alert_state?filter=${filter}&limit=1`, { headers: this.h() });\n    const body = (await res.json()) as { data?: { items?: Item[] } };\n    return body.data?.items?.[0] ?? null;\n  }\n  /** false on 409 (unique key already claimed by a concurrent run) */\n  async create(data: StateData): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/alert_state`, {\n      method: 'POST', headers: this.h(), body: JSON.stringify({ data, status: 'published' }),\n    });\n    return res.ok;\n  }\n  /** false on 409 version_conflict (another run transitioned this key first) */\n  async patch(itemId: string, version: number | undefined, data: Partial<StateData>): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/alert_state/${itemId}`, {\n      method: 'PATCH',\n      headers: { ...this.h(), ...(version !== undefined ? { 'if-match': String(version) } : {}) },\n      body: JSON.stringify({ data }),\n    });\n    return res.ok;\n  }\n}\n\n// \u2500\u2500 the chat webhook: `text` is Slack's field, `content` is Discord's \u2014 send both,\n//    EXCEPT to a Google Chat space webhook (chat.googleapis.com), which takes\n//    `{ text }` alone \u2014 an unknown field can be rejected there, so it is dropped.\nasync function post(url: string, text: string): Promise<{ ok: boolean; status: number }> {\n  let host = '';\n  try { host = new URL(url).hostname; } catch { /* unparseable \u2192 the generic body below */ }\n  const body = host === 'chat.googleapis.com' ? { text } : { text, content: text };\n  const res = await fetch(url, {\n    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),\n  }).catch(() => null);\n  return { ok: Boolean(res?.ok), status: res?.status ?? 0 };\n}\n\nconst iso = () => new Date().toISOString();\nconst isState = (v: unknown): v is State => v === 'ok' || v === 'stale' || v === 'broken' || v === 'could_not_check';\nconst isLevel = (v: unknown): v is Level => v === 'info' || v === 'warn' || v === 'error';\n"
+      "alerts.ts": "// alerts.ts \u2014 FAILURE EVENTS \u2192 ONE CHAT MESSAGE PER STATE CROSSING (a vxil function).\n//\n// Trigger: cron `*/5 * * * *`. Each run:\n//   1. reads the watermark (the `__cursor__` row in `alert_state`; first run = \"now\",\n//      so history never produces an alert storm),\n//   2. drains the tenant audit stream past it \u2014 `GET /v1/audit/export?after_id=\u2026`\n//      (ascending, NDJSON) with the `vxil_read_key` secret (a key holding ONLY\n//      `features:read`; the audit stream is not on the scoped callback),\n//   3. matches each row against RULES (the allow-list below) and turns it into a\n//      (key, state, level) \u2014 e.g. `payments:ingest:stripe` \u2192 `broken`,\n//   4. compares with the stored state for that key (cms, one row per key, `unique`\n//      key \u21D2 a racing run gets a 409 and stands down) and posts ONLY on a crossing:\n//      ok\u2192red = alert, red\u2192ok = \"resolved\", red\u2192red = silence (or a reminder after\n//      REPEAT_AFTER_HOURS),\n//   5. advances the watermark (If-Match on the cursor row's version \u2014 a concurrent\n//      run that already advanced it wins; jobs may deliver a cron tick twice).\n//\n// Manual check: `vxil functions invoke alerts --data '{\"test\":true}'` posts a test\n// message and touches nothing else.\n//\n// Tune the constants; own the RULES table \u2014 it is data, not a routing engine.\n\n// cron-walk: persisted-cursor \u2014 the audit watermark lives in the `__cursor__` row and advances with If-Match.\n\nimport type { CronFunctionEnvelope, HttpFunctionEnvelope } from '@vxil/sdk';\n\nconst REPEAT_AFTER_HOURS = 24; // remind about a still-red condition this often; 0 = never\nconst MAX_PAGES_PER_RUN = 5; // \xD7 500 audit rows \u2014 bounds one cron tick\nconst MAX_POSTS_PER_RUN = 20; // a burst of distinct failures collapses into one summary line\nconst DETAIL_MAX = 240;\n\ntype Level = 'info' | 'warn' | 'error';\ntype State = 'ok' | 'stale' | 'broken' | 'could_not_check';\ntype Payload = Record<string, unknown>;\n\ninterface Rule {\n  /** A literal level, or 'payload' to take `payload.level` (the payments failure\n   *  events carry one; the jobs/functions ones do not). */\n  level: Level | 'payload';\n  key: (p: Payload) => string; // one state row per key \u2014 this is what suppresses repeats\n  title: (p: Payload) => string;\n  /** A literal state, or omitted to take `payload.state` (falling back to 'broken'). */\n  state?: State;\n}\n\nconst str = (v: unknown, fallback = 'unknown') => (typeof v === 'string' && v ? v : fallback);\n\n/** THE ALLOW-LIST. Every name below is an audit event a vxil feature writes;\n *  anything not listed is ignored by the drain. The KEY is what collapses\n *  repeats: ten dead letters of the same job are one key, one row, one alert.\n *\n *  Every name below is emitted today (2026-09-10). A rule for an event nobody\n *  emits would simply never match \u2014 so if you add one, verify the emitter first.\n */\nconst RULES: Record<string, Rule> = {\n  // \u2500\u2500 payments \u2014 the money path. A silent failure here is lost revenue. \u2500\u2500\u2500\u2500\u2500\u2500\n  // These three carry `level` (info|warn|error) and `state` (ok|stale|broken|\n  // could_not_check) in their payload, so the rule defers to the event.\n  'payments.webhook_event.failed': {\n    level: 'payload', // emitted as error/broken\n    key: (p) => `payments:ingest:${str(p.provider, 'all')}`,\n    title: (p) => `payments ingest (${str(p.provider, 'all providers')})`,\n  },\n  'payments.webhook.rejected': {\n    level: 'payload', // emitted as warn/broken\n    key: (p) => `payments:webhook-rejected:${str(p.provider)}`,\n    title: (p) => `payments webhook rejected (${str(p.provider)})`,\n  },\n  // NOTE: grant.failed carries NO `provider` \u2014 it is keyed on the credit type\n  // and the grant source instead (end_user_id/credit_type/amount/grant_key/\n  // source/error). Keying on a field an event does not carry would collapse\n  // every provider into one bucket named \"unknown\".\n  'payments.grant.failed': {\n    level: 'payload', // emitted as error/broken\n    key: (p) => `payments:grant:${str(p.credit_type, 'credits')}:${str(p.source, 'webhook')}`,\n    title: (p) => `entitlement grant failed (${str(p.credit_type, 'credits')} via ${str(p.source, 'webhook')})`,\n  },\n  // Dunning. `past_due` is the red crossing and `active` is its RESOLVED twin \u2014\n  // the same key, so a recovered subscription closes its own alert. Both are\n  // emitted at level info, so the rule forces the level it wants.\n  'payments.subscription.past_due': {\n    level: 'warn',\n    key: (p) => `payments:subscription:${str(p.end_user_id, 'unknown-user')}`,\n    title: (p) => `subscription past due (user ${str(p.end_user_id)})`,\n    state: 'broken',\n  },\n  'payments.subscription.active': {\n    level: 'info',\n    key: (p) => `payments:subscription:${str(p.end_user_id, 'unknown-user')}`,\n    title: (p) => `subscription past due (user ${str(p.end_user_id)})`,\n    state: 'ok',\n  },\n  // A dispute is a chargeback in progress \u2014 money already collected, now at risk.\n  'payments.charge.disputed': {\n    level: 'warn',\n    key: (p) => `payments:disputes:${str(p.provider)}`,\n    title: (p) => `charge disputed (${str(p.provider)})`,\n    state: 'broken',\n  },\n\n  // \u2500\u2500 jobs \u2014 the delivery substrate. Notification and outbound-webhook sends\n  //    ride jobs, so THEIR dead letters arrive here too, under `job_name`\n  //    ('notifications.deliver', 'webhooks.deliver', 'fn-cron:<name>', \u2026).\n  //    These payloads carry run_id/attempt/job_name and NO level or state, so\n  //    the rule supplies both. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n  'job.dead_lettered': {\n    level: 'error',\n    key: (p) => `jobs:dead-letter:${str(p.job_name)}`,\n    title: (p) => `job dead-lettered: ${str(p.job_name)}`,\n    state: 'broken',\n  },\n  'job.dead_letter_quota_exceeded': {\n    level: 'error',\n    key: () => 'jobs:dead-letter-quota',\n    title: () => 'daily dead-letter quota exceeded',\n    state: 'broken',\n  },\n  'job.generation.failed': {\n    level: 'error',\n    key: (p) => `jobs:generation:${str(p.error_class, 'failed')}`,\n    title: (p) => `generation job failed (${str(p.error_class, 'unclassified')})`,\n    state: 'broken',\n  },\n\n  // \u2500\u2500 functions \u2014 the breaker. Consecutive failures quarantine a function;\n  //    clearing the quarantine is the ok crossing on the SAME key, so this pair\n  //    produces exactly one \u{1F534} and one \u{1F7E2}. Payload: name (+ consecutive_failures).\n  'functions.quarantined': {\n    level: 'error',\n    key: (p) => `functions:${str(p.name)}`,\n    title: (p) => `function quarantined: ${str(p.name)}`,\n    state: 'broken',\n  },\n  'functions.quarantine.cleared': {\n    level: 'info',\n    key: (p) => `functions:${str(p.name)}`,\n    title: (p) => `function quarantined: ${str(p.name)}`,\n    state: 'ok',\n  },\n  'functions.deploy.denied': {\n    level: 'warn',\n    key: () => 'functions:deploy-denied',\n    title: (p) => `function deploy denied (needs the ${str(p.required_tier)} tier)`,\n    state: 'broken',\n  },\n\n  // \u2500\u2500 The lifecycle failure events (live since 2026-09-10). Every one of these\n  //    carries `level` + `state` in its payload (the platform's failure-event\n  //    vocabulary gate enforces it), so the rules defer to the event. Each\n  //    failure/recovery pair shares a key, so a recovery posts RESOLVED. \u2500\u2500\u2500\u2500\u2500\u2500\n  'notifications.delivery.dead_lettered': {\n    level: 'payload', // emitted as error/broken; payload: delivery_id, template_id, error_class, attempts\n    key: (p) => `notifications:dead-letter:${str(p.template_id, 'all')}`,\n    title: (p) => `notification delivery dead-lettered (${str(p.template_id, 'all templates')})`,\n  },\n  'webhooks.delivery.dead_lettered': {\n    level: 'payload', // error/broken; payload: subscription_id, target_host, attempts, error_class\n    key: (p) => `webhooks:delivery:${str(p.subscription_id, 'all')}`,\n    title: (p) => `outbound webhook dead-lettered (${str(p.target_host, str(p.subscription_id, 'all subscriptions'))})`,\n  },\n  'webhooks.delivery.recovered': {\n    level: 'payload', // info/ok \u2014 same key as the dead-letter \u2192 RESOLVED\n    key: (p) => `webhooks:delivery:${str(p.subscription_id, 'all')}`,\n    title: (p) => `outbound webhook dead-lettered (${str(p.target_host, str(p.subscription_id, 'all subscriptions'))})`,\n  },\n  'webhooks.inbound.rejected': {\n    level: 'payload', // warn/broken; payload: source_id, provider, reason, fingerprint (never the body)\n    key: (p) => `webhooks:inbound:${str(p.source_id)}:${str(p.reason)}`,\n    title: (p) => `inbound webhook rejected (${str(p.provider, 'source')} ${str(p.source_id)}: ${str(p.reason)})`,\n  },\n  'jobs.schedule.missed': {\n    level: 'payload', // warn/STALE \u2014 a late tick is stale, not broken; payload: schedule_id, job_name, late_seconds\n    key: (p) => `jobs:schedule:${str(p.schedule_id)}`,\n    title: (p) => `scheduled job did not fire on time (${str(p.job_name, str(p.schedule_id))})`,\n  },\n  'jobs.schedule.recovered': {\n    level: 'payload', // info/ok \u2014 same key \u2192 RESOLVED on the next on-time fire\n    key: (p) => `jobs:schedule:${str(p.schedule_id)}`,\n    title: (p) => `scheduled job did not fire on time (${str(p.job_name, str(p.schedule_id))})`,\n  },\n  // A function's cron trigger that produced NO run for 2\xD7 its interval \u2014 the\n  // platform's silent-schedule watch (error/stale), and the recovery on the same\n  // key. Payload: function, schedule_id, cron, last_run_at, expected_by.\n  'functions.schedule.missed': {\n    level: 'payload',\n    key: (p) => `functions:schedule:${str(p.function, str(p.schedule_id))}`,\n    title: (p) => `cron function stopped firing: ${str(p.function, str(p.job_name))} (last run ${str(p.last_run_at, 'never')})`,\n  },\n  'functions.schedule.recovered': {\n    level: 'payload', // info/ok \u2014 same key \u2192 RESOLVED when a run appears again\n    key: (p) => `functions:schedule:${str(p.function, str(p.schedule_id))}`,\n    title: (p) => `cron function stopped firing: ${str(p.function, str(p.job_name))}`,\n  },\n  'functions.run.failed': {\n    level: 'payload', // error/broken; payload: name, trigger, run_id, error_class\n    key: (p) => `functions:run:${str(p.name)}`,\n    title: (p) => `function failing: ${str(p.name)} (${str(p.trigger, 'trigger')})`,\n  },\n  'functions.run.recovered': {\n    level: 'payload', // info/ok \u2014 same key \u2192 RESOLVED\n    key: (p) => `functions:run:${str(p.name)}`,\n    title: (p) => `function failing: ${str(p.name)} (${str(p.trigger, 'trigger')})`,\n  },\n};\n\n// the schedule tick, or a hand invoke (`POST /v1/fn/alerts`) carrying `{ test: true }`\ntype Envelope = CronFunctionEnvelope | HttpFunctionEnvelope<{ test?: boolean }>;\ninterface AuditRow { id: string | number; event: string; payload?: Payload; created_at?: string }\ninterface StateData {\n  key: string; state?: State; level?: Level; event?: string; detail?: string;\n  cursor?: string; last_event_id?: string; last_alert_at?: string; updated_at?: string;\n}\ninterface Item { item_id: string; version?: number; data: StateData }\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Envelope;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const hook = env.secrets?.slack_webhook_url;\n    const readKey = env.secrets?.vxil_read_key;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n    if (!hook || !readKey) return Response.json({ error: 'missing secrets' }, { status: 409 });\n\n    // Manual wiring check \u2014 posts, touches nothing else.\n    if (env.payload?.test) {\n      const r = await post(hook, `\u{1F7E2} [INFO] alerts-to-slack is wired (test message)`);\n      return Response.json({ test: true, posted: r.ok, status: r.status });\n    }\n\n    const store = new Store(base, cms);\n\n    // 1. the watermark (first run: start at the newest audit id \u2014 no history storm)\n    const cursorRow = await store.byKey('__cursor__');\n    if (!cursorRow) {\n      const head = await newestAuditId(base, readKey);\n      await store.create({ key: '__cursor__', cursor: head, updated_at: iso() });\n      return Response.json({ initialized: true, cursor: head });\n    }\n    let cursor = cursorRow.data.cursor ?? '0';\n    const cursorVersion = cursorRow.version;\n\n    // 2\u20134. drain + evaluate\n    const posts: string[] = [];\n    let scanned = 0;\n    let matched = 0;\n    for (let page = 0; page < MAX_PAGES_PER_RUN; page++) {\n      const { rows, next } = await exportAudit(base, readKey, cursor);\n      for (const row of rows) {\n        scanned++;\n        const rule = RULES[row.event];\n        if (rule) {\n          matched++;\n          const msg = await evaluate(store, rule, row);\n          if (msg) posts.push(msg);\n        }\n        cursor = String(row.id);\n      }\n      if (!next) break;\n      cursor = next;\n    }\n\n    // deliver (bounded)\n    let posted = 0;\n    const lines = posts.slice(0, MAX_POSTS_PER_RUN);\n    if (posts.length > MAX_POSTS_PER_RUN) lines.push(`\u2026 and ${posts.length - MAX_POSTS_PER_RUN} more state changes this tick`);\n    for (const text of lines) {\n      const r = await post(hook, text);\n      if (r.ok) posted++;\n    }\n\n    // 5. advance the watermark \u2014 If-Match: a concurrent run that already moved it wins\n    const advanced = await store.patch(cursorRow.item_id, cursorVersion, { cursor, updated_at: iso() });\n\n    return Response.json({ scanned, matched, alerts: posts.length, posted, cursor, advanced });\n  },\n};\n\n/** Decide, for one matched audit row, whether a message is due; persist the state. */\nasync function evaluate(store: Store, rule: Rule, row: AuditRow): Promise<string | null> {\n  const p = row.payload ?? {};\n  const key = rule.key(p);\n  const next: State = rule.state ?? (isState(p.state) ? p.state : 'broken');\n  const level: Level = rule.level === 'payload' ? (isLevel(p.level) ? p.level : 'error') : rule.level;\n  const title = rule.title(p);\n  const detail = str(p.reason ?? p.error ?? p.message ?? p.last_error_msg, '').slice(0, DETAIL_MAX);\n  const now = iso();\n  const eventId = String(row.id);\n  const base: StateData = { key, state: next, level, event: row.event, detail, last_event_id: eventId, updated_at: now };\n\n  const current = await store.byKey(key);\n  if (!current) {\n    // First sighting. A green first sighting is remembered silently \u2014 nothing was red.\n    if (next === 'ok') { await store.create(base); return null; }\n    const created = await store.create({ ...base, last_alert_at: now });\n    return created ? format(level, next, title, detail, row.created_at) : null; // 409 = a racing run owns it\n  }\n  const prev = current.data.state ?? 'ok';\n  if (prev !== next) {\n    // A CROSSING. If-Match: exactly one concurrent run wins the transition.\n    const ok = await store.patch(current.item_id, current.version, { ...base, last_alert_at: now });\n    if (!ok) return null;\n    return next === 'ok'\n      ? `\u{1F7E2} RESOLVED: ${title} is back to ok (was ${prev})`\n      : format(level, next, title, detail, row.created_at);\n  }\n  // Same state. Red stays quiet \u2014 unless a reminder is due.\n  if (next !== 'ok' && REPEAT_AFTER_HOURS > 0) {\n    const last = Date.parse(current.data.last_alert_at ?? '') || 0;\n    if (Date.now() - last >= REPEAT_AFTER_HOURS * 3600e3) {\n      const ok = await store.patch(current.item_id, current.version, { ...base, last_alert_at: now });\n      return ok ? `\u23F0 STILL ${next.toUpperCase()}: ${title} (since ${current.data.last_alert_at ?? '?'})` : null;\n    }\n  }\n  await store.patch(current.item_id, current.version, base); // keep detail/last_event_id fresh, no post\n  return null;\n}\n\nfunction format(level: Level, state: State, title: string, detail: string, at?: string): string {\n  const dot = level === 'error' ? '\u{1F534}' : level === 'warn' ? '\u{1F7E0}' : '\u{1F535}';\n  return `${dot} [${level.toUpperCase()}] ${title} \u2192 ${state.toUpperCase()}${detail ? ` \u2014 ${detail}` : ''}${at ? ` (at ${at})` : ''}`;\n}\n\n// \u2500\u2500 the audit stream (ascending NDJSON export; `x-vxil-next-after-id` continues it) \u2500\u2500\nasync function exportAudit(base: string, key: string, afterId: string): Promise<{ rows: AuditRow[]; next: string | null }> {\n  const res = await fetch(`${base}/v1/audit/export?after_id=${encodeURIComponent(afterId)}&limit=500`, {\n    headers: { authorization: `Bearer ${key}` },\n  });\n  if (!res.ok) throw new Error(`audit export ${res.status}`);\n  const rows = (await res.text()).split('\\n').filter(Boolean).map((l) => JSON.parse(l) as AuditRow);\n  return { rows, next: res.headers.get('x-vxil-next-after-id') };\n}\nasync function newestAuditId(base: string, key: string): Promise<string> {\n  const res = await fetch(`${base}/v1/audit?limit=1`, { headers: { authorization: `Bearer ${key}` } });\n  if (!res.ok) throw new Error(`audit list ${res.status}`);\n  const body = (await res.json()) as { data?: { events?: AuditRow[] } };\n  return String(body.data?.events?.[0]?.id ?? '0');\n}\n\n// \u2500\u2500 the cms state store (the REST envelope: { data: { items:[{item_id, version, data}] } }) \u2500\u2500\nclass Store {\n  constructor(private base: string, private jwt: string) {}\n  private h() { return { authorization: `Bearer ${this.jwt}`, 'content-type': 'application/json' }; }\n  async byKey(key: string): Promise<Item | null> {\n    const filter = encodeURIComponent(JSON.stringify({ key }));\n    const res = await fetch(`${this.base}/v1/cms/items/alert_state?filter=${filter}&limit=1`, { headers: this.h() });\n    const body = (await res.json()) as { data?: { items?: Item[] } };\n    return body.data?.items?.[0] ?? null;\n  }\n  /** false on 409 (unique key already claimed by a concurrent run) */\n  async create(data: StateData): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/alert_state`, {\n      method: 'POST', headers: this.h(), body: JSON.stringify({ data, status: 'published' }),\n    });\n    return res.ok;\n  }\n  /** false on 409 version_conflict (another run transitioned this key first) */\n  async patch(itemId: string, version: number | undefined, data: Partial<StateData>): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/alert_state/${itemId}`, {\n      method: 'PATCH',\n      headers: { ...this.h(), ...(version !== undefined ? { 'if-match': String(version) } : {}) },\n      body: JSON.stringify({ data }),\n    });\n    return res.ok;\n  }\n}\n\n// \u2500\u2500 the chat webhook: `text` is Slack's field, `content` is Discord's \u2014 send both,\n//    EXCEPT to a Google Chat space webhook (chat.googleapis.com), which takes\n//    `{ text }` alone \u2014 an unknown field can be rejected there, so it is dropped.\nasync function post(url: string, text: string): Promise<{ ok: boolean; status: number }> {\n  let host = '';\n  try { host = new URL(url).hostname; } catch { /* unparseable \u2192 the generic body below */ }\n  const body = host === 'chat.googleapis.com' ? { text } : { text, content: text };\n  const res = await fetch(url, {\n    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),\n  }).catch(() => null);\n  return { ok: Boolean(res?.ok), status: res?.status ?? 0 };\n}\n\nconst iso = () => new Date().toISOString();\nconst isState = (v: unknown): v is State => v === 'ok' || v === 'stale' || v === 'broken' || v === 'could_not_check';\nconst isLevel = (v: unknown): v is Level => v === 'info' || v === 'warn' || v === 'error';\n"
     }
   },
   {
@@ -17435,7 +18298,7 @@ const json = (o: unknown, status: number) => Response.json(o, { status });
     "configSrc": "import { defineConfig } from '@vxil/config';\n\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// \"Payments heartbeat\" \u2014 THE SILENT-PROVIDER DETECTOR.\n//\n// Every other payments check answers \"did THIS event fold correctly?\". This one\n// answers the question nobody asks until it is too late: \"has my provider sent\n// me ANYTHING lately?\" A provider that stops posting produces no errors, no\n// failed webhooks, no red dashboard \u2014 just silence, and silence looks exactly\n// like a quiet week. This blueprint turns silence into a signal:\n//   \u2022 payments  \u2192 the webhook-event log (`GET /v1/payments/webhook-events`) is\n//                 already the record of every delivery your integration folded\n//   \u2022 cms       \u2192 `heartbeat_state`: one row per provider, so an alert fires on\n//                 the CROSSING and not once a day forever\n//   \u2022 functions \u2192 `heartbeat`: a daily cron that measures days-since-last-\n//                 processed-event against YOUR OWN cadence and posts to Slack\n//\n// The threshold is not a number somebody picked: it is 3 \xD7 your median\n// inter-event gap, with a 7-day floor. A 100-subscriber app and a 100 000-\n// subscriber app have wildly different \"normal\", and a fixed number of days is\n// wrong for both.\n//\n// \u26A0 THIS IS AN OVERLAY, NOT A FRESH BACKEND. `vxil push` replaces a feature's\n// config wholesale. If you already run the payments feature, copy the\n// `heartbeat_state` collection and the `heartbeat` function into your EXISTING\n// vxil.config.ts rather than pushing this file \u2014 see README.md.\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nexport default defineConfig({\n  env: 'staging',\n\n  features: {\n    cms: {},\n\n    // Your payments INTEGRATION \u2014 your own provider account, your own keys;\n    // vxil folds the lifecycle webhooks into a ledger and an entitlement\n    // snapshot and is never in the flow of funds. Shown here so the file is a\n    // coherent whole; if you already have a payments block, keep YOURS.\n    payments: {\n      provider: 'stripe',\n      stripe: { secretKeyRef: 'stripe_secret', webhookSecretRef: 'stripe_webhook' },\n      defaults: { currency: 'usd' },\n    },\n\n    functions: { enabled: true },\n  },\n\n  cms: {\n    collections: {\n      // The heartbeat's memory: ONE row per provider. `provider` is unique, so\n      // two overlapping cron ticks cannot both create it (the loser gets 409).\n      heartbeat_state: {\n        singular: 'heartbeat_state',\n        fields: {\n          provider: { type: 'string', required: true, indexSlot: 's1', unique: true },\n          state: { type: 'string', indexSlot: 's2' }, // ok | stale | broken | could_not_check\n          detail: { type: 'text' }, // the human sentence that was (or would be) posted\n          days_since: { type: 'float', indexSlot: 'n1' }, // days since the last processed event\n          threshold_days: { type: 'float', indexSlot: 'n2' }, // max(7, 3 \xD7 median gap)\n          last_event_at: { type: 'datetime', indexSlot: 't1' },\n          checked_at: { type: 'datetime', indexSlot: 't2' },\n          last_event_id: { type: 'string', indexSlot: 's3' },\n        },\n      },\n    },\n  },\n\n  functions: {\n    // Once a day is the right cadence for a check measured in DAYS. Also\n    // invocable by hand \u2014 `vxil functions invoke heartbeat` \u2014 which runs the\n    // real check and returns the per-provider verdict as JSON without posting\n    // anything unless a state actually crossed.\n    heartbeat: {\n      entry: './functions/heartbeat.ts',\n      trigger: { kind: 'cron', schedule: '0 7 * * *' },\n      // payments:read = the webhook-event log; cms:* = the state rows. No write\n      // scope on payments: a monitor must never be able to move money-adjacent\n      // records, and this one structurally cannot.\n      scopes: ['payments:read', 'cms:read', 'cms:write'],\n      secrets: ['secret:slack_webhook_url'],\n      egressAllow: ['hooks.slack.com'], // add 'discord.com' for Discord, 'chat.googleapis.com' for Google Chat\n    },\n  },\n\n  secrets: {\n    slack_webhook_url: { feature: 'functions', description: 'Slack incoming webhook (or Discord / Google Chat space webhook) URL' },\n    stripe_secret: { feature: 'payments', description: 'Stripe secret key (BYO \u2014 your own account)' },\n    stripe_webhook: { feature: 'payments', description: 'Stripe webhook signing secret' },\n  },\n});\n",
     "readme": "# Payments heartbeat (ops)\n\nEvery other payments check answers *\"did this event fold correctly?\"*. This one answers the question\nnobody asks until it is too late: **\"has my provider sent me anything lately?\"**\n\nA provider that stops posting produces no errors, no failed webhooks, no red dashboard \u2014 just silence,\nand silence looks exactly like a quiet week. One daily cron function measures **days since the last\nprocessed production event, per provider**, against **your own cadence**, keeps a three-state\n`ok | stale | broken` record in `cms`, and posts to Slack (or Discord, or Google Chat) **once per crossing**.\n\n```bash\nvxil init --template payments-heartbeat\nvxil quickstart                       # or `vxil link <slug>` for an existing backend\nprintf '%s' \"$SLACK_URL\" | vxil secrets set functions/slack_webhook_url\nvxil push                             # the heartbeat_state collection + the cron function\nvxil functions invoke heartbeat       # run the real check now; prints the per-provider verdict\n```\n\n> \u26A0 **This blueprint is an overlay.** `vxil push` writes each feature's config as a whole version, so\n> pushing this file at a backend that already runs payments would replace your payments block with the\n> example one below. If you already have a `payments` integration configured, copy just the\n> **`heartbeat_state` collection** and the **`heartbeat` function** into your existing `vxil.config.ts`\n> and push that. On a fresh backend, push this file as-is and edit the payments block to your provider.\n\n## The threshold is derived, not guessed\n\nA fixed \"alert after 14 days\" is wrong for a 100-subscriber app *and* for a 100 000-subscriber one. So the\nfunction computes it from your own traffic:\n\n```\nthreshold_days = max( 7 , 3 \xD7 median gap between your last 100 processed events )\n```\n\n- **`3 \xD7` the median gap** \u2014 the median, not the mean, because one migration backfill or one Black Friday\n  would inflate a mean for months. Three is the \"this is no longer a quiet week\" multiple.\n- **A 7-day floor** \u2014 a low-volume integration can legitimately go a week without a single lifecycle\n  event, and alerting on that is how a channel gets muted.\n- **Fewer than 5 gaps sampled** \u2192 there is no meaningful cadence yet, so the floor is used on its own.\n- Past **2 \xD7** the threshold, `stale` becomes `broken`. That severity split is this blueprint's choice \u2014\n  tune `BROKEN_MULTIPLE` in `functions/heartbeat.ts`; every constant at the top of that file is policy.\n\n`ALERT_MULTIPLE = 3` and `FLOOR_DAYS = 7` are the numbers the platform's own payments-ingest SLO uses for\nits silent-provider detection SLI, so the blueprint and the platform agree by construction.\n\n## What it reads\n\n```\nGET /v1/payments/webhook-events?provider=<p>&environment=production&outcome=processed&limit=100\n```\n\nwith the function's `payments:read` scope \u2014 the webhook event log your integration already writes for\nevery delivery it folds. Three details in that URL are the whole design:\n\n| Part | Why |\n|---|---|\n| `provider=<p>` | asked **per provider**, in a loop. A global query would be dominated by your chattiest provider, and a quiet one that went silent months ago would never appear in the newest page at all. |\n| `environment=production` | sandbox traffic is developer noise. A provider can be chatty in test mode while production has been silent for a month \u2014 exactly the outage this exists to catch. |\n| `outcome=processed` | not merely *received*. An event that arrived and never folded is a different failure (`payments.webhook_event.failed`, which `templates/alerts-to-slack/` picks up); this function is about arrival. |\n\nA provider that has **never** delivered a processed production event is skipped entirely \u2014 there is no\ncadence to be silent against. Edit `PROVIDERS` in the function to match the ones you actually use.\n\n## States and messages\n\n| State | When | Message |\n|---|---|---|\n| `ok` | `days_since \u2264 threshold` | (silent \u2014 or \u{1F7E2} RESOLVED if it was not ok before) |\n| `stale` | `threshold < days_since \u2264 2 \xD7 threshold` | \u{1F7E0} `[STALE] payments heartbeat \u2014 \u2026` |\n| `broken` | `days_since > 2 \xD7 threshold` | \u{1F534} `[BROKEN] payments heartbeat \u2014 \u2026` |\n| `could_not_check` | the event-log read itself failed (feature disabled, scope missing, network) | \u{1F535} `[CHECK FAILED] \u2026` \u2014 a monitor that cannot see is not a monitor that says \"fine\" |\n\n```\n\u{1F534} [BROKEN] payments heartbeat \u2014 stripe has sent no processed production event for 23.4d \u2014\n   expected one within 7d (median gap 1.2d \xD7 3, floor 7d)\n\u{1F7E2} RESOLVED: stripe is delivering again \u2014 last processed event 0.1d ago (was broken)\n```\n\n## Once per crossing\n\nOne `heartbeat_state` row per provider, `provider` declared `unique`. Cron delivery is at-least-once, so\ntwo ticks can overlap: the unique field means only one can *create* the row (the other gets `409`), and\nevery update carries `If-Match: <version>`, so only one can *transition* it (the other gets `409\nversion_conflict` and stands down). A provider that stays broken for a month costs exactly **one**\nmessage, not thirty \u2014 and the row keeps `days_since` / `threshold_days` / `last_event_at` fresh the\nwhole time, so the dashboard always shows the current measurement even while the channel is quiet.\n\n## The scopes\n\n`payments:read`, `cms:read`, `cms:write` \u2014 and deliberately **no** payments write scope. A monitor should\nnot be able to touch money-adjacent records, and this one structurally cannot: the function's callback\ntoken is minted from exactly these scopes, so there is no write path to reach for.\n\nEgress is deny-by-default: `egressAllow: ['hooks.slack.com']`. Add `'discord.com'` for a Discord webhook \u2014\nthe message body carries both Slack's `text` and Discord's `content`, so one payload works on either.\nAdd `'chat.googleapis.com'` for a Google Chat space webhook \u2014 that host takes `text` alone, and the function\nsends only that field to it.\n\n## What to learn from this\n\n- **A monitor's threshold should come from the system it monitors.** Reading your own median gap turns\n  one alert rule into a rule that fits every tenant.\n- **Absence is the hardest signal.** Nothing emits an event when a provider goes quiet, so the check has\n  to be a *sweep*, not a subscription \u2014 which is what cron functions are for.\n- **`could_not_check` is a real state.** Folding \"I could not look\" into \"everything is fine\" is how\n  monitoring dies silently; giving it its own state is one line and saves an outage.\n\n**Pairs with:** `templates/alerts-to-slack/` \u2014 the same suppression pattern applied to failure *events*\nrather than to silence, so together they cover both halves of the money path. The two ship the same\nSlack/Discord formatter on purpose: each blueprint is a self-contained clone, and every file under a\ntemplate's `functions/` directory must be a declared entry point, so there is nowhere for a shared module\nto live. Copy the file, own the copy.\n",
     "functions": {
-      "heartbeat.ts": "// heartbeat.ts \u2014 THE SILENT-PROVIDER DETECTOR (a vxil function, cron trigger).\n//\n// Trigger: cron `0 7 * * *`. For each provider you list in PROVIDERS:\n//   1. read the newest PROCESSED production webhook events \u2014\n//      `GET /v1/payments/webhook-events?provider=<p>&environment=production\n//       &outcome=processed&limit=100` (newest first),\n//   2. days_since = now \u2212 the newest event's received_at,\n//   3. threshold = max(FLOOR_DAYS, ALERT_MULTIPLE \xD7 the MEDIAN gap between\n//      those events) \u2014 your own cadence, not a number somebody picked,\n//   4. ok | stale | broken (or could_not_check when the read itself failed),\n//   5. compare with the stored row for that provider and post to Slack ONLY on\n//      a crossing; a return to ok posts RESOLVED.\n//\n// Why the median and not the mean: one migration backfill or one Black Friday\n// inflates a mean for months. The median is what \"normal\" actually looks like.\n//\n// Why `?environment=production`: sandbox traffic is developer noise. A provider\n// can be chatty in test mode while production has been silent for a month \u2014\n// that is precisely the outage this function exists to catch.\n//\n// Run it by hand any time: `vxil functions invoke heartbeat`. It performs the\n// real check and returns the per-provider verdict as JSON; it still only posts\n// if a state genuinely crossed.\n\n// \u2500\u2500 Tune these. They are the whole policy. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\n/** Providers to probe. Must be names the payments API accepts. Drop the ones\n *  you do not use \u2014 a provider that has never sent an event is skipped anyway. */\nconst PROVIDERS = ['stripe', 'paddle', 'paypal', 'revenuecat'] as const;\n/** Alert once silence exceeds this multiple of your median inter-event gap. */\nconst ALERT_MULTIPLE = 3;\n/** \u2026but never sooner than this many days, however chatty your integration is.\n *  A low-volume app can legitimately go a week without a single lifecycle event. */\nconst FLOOR_DAYS = 7;\n/** Past this multiple of the threshold, `stale` becomes `broken`. This split is\n *  the blueprint's own choice \u2014 the SLO defines the alert threshold, not the\n *  severity ladder \u2014 so move it wherever your escalation wants it. */\nconst BROKEN_MULTIPLE = 2;\n/** Gaps needed before a median means anything. Below this the floor is used. */\nconst MIN_GAPS_FOR_MEDIAN = 5;\n/** Events sampled per provider (the API caps a page at 100). */\nconst SAMPLE = 100;\n\ntype State = 'ok' | 'stale' | 'broken' | 'could_not_check';\n\ntype Envelope = CronFunctionEnvelope;\ninterface WebhookEvent { event_id: string; provider: string; received_at: string | null }\ninterface StateData {\n  provider: string; state?: State; detail?: string;\n  days_since?: number; threshold_days?: number;\n  last_event_at?: string; checked_at?: string; last_event_id?: string;\n}\ninterface Item { item_id: string; version?: number; data: StateData }\n\ninterface Verdict {\n  provider: string;\n  state: State;\n  detail: string;\n  days_since: number | null;\n  threshold_days: number | null;\n  last_event_at: string | null;\n  last_event_id: string | null;\n}\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Envelope;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const payments = env.scoped_jwts?.payments;\n    const cms = env.scoped_jwts?.cms;\n    const hook = env.secrets?.slack_webhook_url;\n    if (!payments || !cms) return Response.json({ error: 'missing payments:read / cms scope' }, { status: 403 });\n    if (!hook) return Response.json({ error: 'missing secret slack_webhook_url' }, { status: 409 });\n\n    const store = new Store(base, cms);\n    const checked: Verdict[] = [];\n    const crossings: string[] = [];\n\n    for (const provider of PROVIDERS) {\n      const verdict = await check(base, payments, provider);\n      if (!verdict) continue; // never sent an event \u2192 not part of this integration\n      checked.push(verdict);\n      const line = await reconcile(store, verdict);\n      if (line) crossings.push(line);\n    }\n\n    let posted = 0;\n    for (const text of crossings) {\n      const r = await post(hook, text);\n      if (r.ok) posted++;\n    }\n    return Response.json({ checked, crossings: crossings.length, posted });\n  },\n};\n\n/** Measure one provider. `null` = the provider has never delivered a processed\n *  production event, so there is no cadence to be silent against \u2014 the SLO's\n *  \"once the tenant has ever received one\" precondition. */\nasync function check(base: string, jwt: string, provider: string): Promise<Verdict | null> {\n  const url = `${base}/v1/payments/webhook-events`\n    + `?provider=${encodeURIComponent(provider)}&environment=production&outcome=processed&limit=${SAMPLE}`;\n  const res = await fetch(url, { headers: { authorization: `Bearer ${jwt}` } }).catch(() => null);\n  if (!res) {\n    return verdict(provider, 'could_not_check', `could not reach the payments event log for ${provider}`);\n  }\n  if (!res.ok) {\n    // 501 capability_not_enabled / 403 missing scope are configuration, not silence.\n    return verdict(provider, 'could_not_check', `payments event log returned ${res.status} for ${provider}`);\n  }\n  const body = (await res.json().catch(() => ({}))) as { data?: { events?: WebhookEvent[] } };\n  const events = (body.data?.events ?? []).filter((e) => e.received_at);\n  if (events.length === 0) return null;\n\n  // The API orders by received_at DESC, so [0] is the newest.\n  const times = events.map((e) => Date.parse(e.received_at!)).filter(Number.isFinite).sort((a, b) => b - a);\n  if (times.length === 0) return null;\n  const last = times[0]!;\n  const daysSince = round2((Date.now() - last) / 86_400_000);\n\n  const gaps: number[] = [];\n  for (let i = 0; i + 1 < times.length; i++) gaps.push((times[i]! - times[i + 1]!) / 86_400_000);\n  const medianGap = gaps.length >= MIN_GAPS_FOR_MEDIAN ? median(gaps) : null;\n  const threshold = round2(Math.max(FLOOR_DAYS, medianGap === null ? 0 : ALERT_MULTIPLE * medianGap));\n\n  const state: State = daysSince <= threshold ? 'ok'\n    : daysSince <= threshold * BROKEN_MULTIPLE ? 'stale'\n      : 'broken';\n\n  const cadence = medianGap === null\n    ? `only ${gaps.length} gap(s) sampled \u2014 using the ${FLOOR_DAYS}-day floor`\n    : `median gap ${round2(medianGap)}d \xD7 ${ALERT_MULTIPLE}, floor ${FLOOR_DAYS}d`;\n  const detail = state === 'ok'\n    ? `${provider}: last processed event ${daysSince}d ago (threshold ${threshold}d \u2014 ${cadence})`\n    : `${provider} has sent no processed production event for ${daysSince}d \u2014 expected one within ${threshold}d (${cadence})`;\n\n  return {\n    provider, state, detail,\n    days_since: daysSince,\n    threshold_days: threshold,\n    last_event_at: new Date(last).toISOString(),\n    last_event_id: events[0]!.event_id ?? null,\n  };\n}\n\n/** Persist the verdict; return a message ONLY when the state crossed. */\nasync function reconcile(store: Store, v: Verdict): Promise<string | null> {\n  const now = new Date().toISOString();\n  const data: StateData = {\n    provider: v.provider, state: v.state, detail: v.detail, checked_at: now,\n    ...(v.days_since !== null ? { days_since: v.days_since } : {}),\n    ...(v.threshold_days !== null ? { threshold_days: v.threshold_days } : {}),\n    ...(v.last_event_at ? { last_event_at: v.last_event_at } : {}),\n    ...(v.last_event_id ? { last_event_id: v.last_event_id } : {}),\n  };\n\n  const current = await store.byProvider(v.provider);\n  if (!current) {\n    // First run. A healthy first sighting is remembered silently; an unhealthy\n    // one is worth saying out loud immediately \u2014 you were already in the outage.\n    const created = await store.create(data);\n    return created && v.state !== 'ok' ? format(v) : null; // 409 \u21D2 a racing tick owns it\n  }\n\n  const prev = current.data.state ?? 'ok';\n  if (prev === v.state) {\n    // No crossing: refresh the measurement, stay quiet. A permanently-broken\n    // provider therefore costs exactly one message, not one per day.\n    await store.patch(current.item_id, current.version, data);\n    return null;\n  }\n  // A CROSSING. If-Match makes exactly one of two overlapping ticks the winner.\n  const ok = await store.patch(current.item_id, current.version, data);\n  if (!ok) return null;\n  return v.state === 'ok'\n    ? `\u{1F7E2} RESOLVED: ${v.provider} is delivering again \u2014 last processed event ${v.days_since}d ago (was ${prev})`\n    : format(v);\n}\n\nfunction format(v: Verdict): string {\n  const dot = v.state === 'broken' ? '\u{1F534}' : v.state === 'stale' ? '\u{1F7E0}' : '\u{1F535}';\n  const label = v.state === 'could_not_check' ? 'CHECK FAILED' : v.state.toUpperCase();\n  return `${dot} [${label}] payments heartbeat \u2014 ${v.detail}`;\n}\n\n// \u2500\u2500 the cms state store (the REST envelope: { data: { items: [{item_id, version, data}] } }) \u2500\u2500\nclass Store {\n  constructor(private base: string, private jwt: string) {}\n  private h() { return { authorization: `Bearer ${this.jwt}`, 'content-type': 'application/json' }; }\n  async byProvider(provider: string): Promise<Item | null> {\n    const filter = encodeURIComponent(JSON.stringify({ provider }));\n    const res = await fetch(`${this.base}/v1/cms/items/heartbeat_state?filter=${filter}&limit=1`, { headers: this.h() });\n    if (!res.ok) return null;\n    const body = (await res.json()) as { data?: { items?: Item[] } };\n    return body.data?.items?.[0] ?? null;\n  }\n  /** false on 409 \u2014 `provider` is unique, so a concurrent tick already claimed it. */\n  async create(data: StateData): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/heartbeat_state`, {\n      method: 'POST', headers: this.h(), body: JSON.stringify({ status: 'published', data }),\n    });\n    return res.ok;\n  }\n  /** false on 409 version_conflict \u2014 another tick transitioned this provider first. */\n  async patch(itemId: string, version: number | undefined, data: StateData): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/heartbeat_state/${itemId}`, {\n      method: 'PATCH',\n      headers: { ...this.h(), ...(version !== undefined ? { 'if-match': String(version) } : {}) },\n      body: JSON.stringify({ data }),\n    });\n    return res.ok;\n  }\n}\n\n// \u2500\u2500 the chat webhook: `text` is Slack's field, `content` is Discord's \u2014 send both,\n//    EXCEPT to a Google Chat space webhook (chat.googleapis.com), which takes\n//    `{ text }` alone \u2014 an unknown field can be rejected there, so it is dropped.\n//    (Duplicated from templates/alerts-to-slack on purpose: a blueprint is a\n//    self-contained clone, and every file under functions/ must be a declared\n//    entry point, so there is no place for a shared module to live.)\nasync function post(url: string, text: string): Promise<{ ok: boolean; status: number }> {\n  let host = '';\n  try { host = new URL(url).hostname; } catch { /* unparseable \u2192 the generic body below */ }\n  const body = host === 'chat.googleapis.com' ? { text } : { text, content: text };\n  const res = await fetch(url, {\n    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),\n  }).catch(() => null);\n  return { ok: Boolean(res?.ok), status: res?.status ?? 0 };\n}\n\nfunction verdict(provider: string, state: State, detail: string): Verdict {\n  return { provider, state, detail, days_since: null, threshold_days: null, last_event_at: null, last_event_id: null };\n}\nfunction median(xs: number[]): number {\n  const s = [...xs].sort((a, b) => a - b);\n  const mid = s.length >> 1;\n  return s.length % 2 ? s[mid]! : (s[mid - 1]! + s[mid]!) / 2;\n}\nconst round2 = (n: number) => Math.round(n * 100) / 100;\n"
+      "heartbeat.ts": "// heartbeat.ts \u2014 THE SILENT-PROVIDER DETECTOR (a vxil function, cron trigger).\n//\n// Trigger: cron `0 7 * * *`. For each provider you list in PROVIDERS:\n//   1. read the newest PROCESSED production webhook events \u2014\n//      `GET /v1/payments/webhook-events?provider=<p>&environment=production\n//       &outcome=processed&limit=100` (newest first),\n//   2. days_since = now \u2212 the newest event's received_at,\n//   3. threshold = max(FLOOR_DAYS, ALERT_MULTIPLE \xD7 the MEDIAN gap between\n//      those events) \u2014 your own cadence, not a number somebody picked,\n//   4. ok | stale | broken (or could_not_check when the read itself failed),\n//   5. compare with the stored row for that provider and post to Slack ONLY on\n//      a crossing; a return to ok posts RESOLVED.\n//\n// Why the median and not the mean: one migration backfill or one Black Friday\n// inflates a mean for months. The median is what \"normal\" actually looks like.\n//\n// Why `?environment=production`: sandbox traffic is developer noise. A provider\n// can be chatty in test mode while production has been silent for a month \u2014\n// that is precisely the outage this function exists to catch.\n//\n// Run it by hand any time: `vxil functions invoke heartbeat`. It performs the\n// real check and returns the per-provider verdict as JSON; it still only posts\n// if a state genuinely crossed.\n\n// \u2500\u2500 Tune these. They are the whole policy. \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\n// cron-walk: single-read \u2014 a sample of the newest 100 events per provider is the measurement itself.\n\nimport type { CronFunctionEnvelope } from '@vxil/sdk';\n\n/** Providers to probe. Must be names the payments API accepts. Drop the ones\n *  you do not use \u2014 a provider that has never sent an event is skipped anyway. */\nconst PROVIDERS = ['stripe', 'paddle', 'paypal', 'revenuecat'] as const;\n/** Alert once silence exceeds this multiple of your median inter-event gap. */\nconst ALERT_MULTIPLE = 3;\n/** \u2026but never sooner than this many days, however chatty your integration is.\n *  A low-volume app can legitimately go a week without a single lifecycle event. */\nconst FLOOR_DAYS = 7;\n/** Past this multiple of the threshold, `stale` becomes `broken`. This split is\n *  the blueprint's own choice \u2014 the SLO defines the alert threshold, not the\n *  severity ladder \u2014 so move it wherever your escalation wants it. */\nconst BROKEN_MULTIPLE = 2;\n/** Gaps needed before a median means anything. Below this the floor is used. */\nconst MIN_GAPS_FOR_MEDIAN = 5;\n/** Events sampled per provider (the API caps a page at 100). */\nconst SAMPLE = 100;\n\ntype State = 'ok' | 'stale' | 'broken' | 'could_not_check';\n\ntype Envelope = CronFunctionEnvelope;\ninterface WebhookEvent { event_id: string; provider: string; received_at: string | null }\ninterface StateData {\n  provider: string; state?: State; detail?: string;\n  days_since?: number; threshold_days?: number;\n  last_event_at?: string; checked_at?: string; last_event_id?: string;\n}\ninterface Item { item_id: string; version?: number; data: StateData }\n\ninterface Verdict {\n  provider: string;\n  state: State;\n  detail: string;\n  days_since: number | null;\n  threshold_days: number | null;\n  last_event_at: string | null;\n  last_event_id: string | null;\n}\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Envelope;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const payments = env.scoped_jwts?.payments;\n    const cms = env.scoped_jwts?.cms;\n    const hook = env.secrets?.slack_webhook_url;\n    if (!payments || !cms) return Response.json({ error: 'missing payments:read / cms scope' }, { status: 403 });\n    if (!hook) return Response.json({ error: 'missing secret slack_webhook_url' }, { status: 409 });\n\n    const store = new Store(base, cms);\n    const checked: Verdict[] = [];\n    const crossings: string[] = [];\n\n    for (const provider of PROVIDERS) {\n      const verdict = await check(base, payments, provider);\n      if (!verdict) continue; // never sent an event \u2192 not part of this integration\n      checked.push(verdict);\n      const line = await reconcile(store, verdict);\n      if (line) crossings.push(line);\n    }\n\n    let posted = 0;\n    for (const text of crossings) {\n      const r = await post(hook, text);\n      if (r.ok) posted++;\n    }\n    return Response.json({ checked, crossings: crossings.length, posted });\n  },\n};\n\n/** Measure one provider. `null` = the provider has never delivered a processed\n *  production event, so there is no cadence to be silent against \u2014 the SLO's\n *  \"once the tenant has ever received one\" precondition. */\nasync function check(base: string, jwt: string, provider: string): Promise<Verdict | null> {\n  const url = `${base}/v1/payments/webhook-events`\n    + `?provider=${encodeURIComponent(provider)}&environment=production&outcome=processed&limit=${SAMPLE}`;\n  const res = await fetch(url, { headers: { authorization: `Bearer ${jwt}` } }).catch(() => null);\n  if (!res) {\n    return verdict(provider, 'could_not_check', `could not reach the payments event log for ${provider}`);\n  }\n  if (!res.ok) {\n    // 501 capability_not_enabled / 403 missing scope are configuration, not silence.\n    return verdict(provider, 'could_not_check', `payments event log returned ${res.status} for ${provider}`);\n  }\n  const body = (await res.json().catch(() => ({}))) as { data?: { events?: WebhookEvent[] } };\n  const events = (body.data?.events ?? []).filter((e) => e.received_at);\n  if (events.length === 0) return null;\n\n  // The API orders by received_at DESC, so [0] is the newest.\n  const times = events.map((e) => Date.parse(e.received_at!)).filter(Number.isFinite).sort((a, b) => b - a);\n  if (times.length === 0) return null;\n  const last = times[0]!;\n  const daysSince = round2((Date.now() - last) / 86_400_000);\n\n  const gaps: number[] = [];\n  for (let i = 0; i + 1 < times.length; i++) gaps.push((times[i]! - times[i + 1]!) / 86_400_000);\n  const medianGap = gaps.length >= MIN_GAPS_FOR_MEDIAN ? median(gaps) : null;\n  const threshold = round2(Math.max(FLOOR_DAYS, medianGap === null ? 0 : ALERT_MULTIPLE * medianGap));\n\n  const state: State = daysSince <= threshold ? 'ok'\n    : daysSince <= threshold * BROKEN_MULTIPLE ? 'stale'\n      : 'broken';\n\n  const cadence = medianGap === null\n    ? `only ${gaps.length} gap(s) sampled \u2014 using the ${FLOOR_DAYS}-day floor`\n    : `median gap ${round2(medianGap)}d \xD7 ${ALERT_MULTIPLE}, floor ${FLOOR_DAYS}d`;\n  const detail = state === 'ok'\n    ? `${provider}: last processed event ${daysSince}d ago (threshold ${threshold}d \u2014 ${cadence})`\n    : `${provider} has sent no processed production event for ${daysSince}d \u2014 expected one within ${threshold}d (${cadence})`;\n\n  return {\n    provider, state, detail,\n    days_since: daysSince,\n    threshold_days: threshold,\n    last_event_at: new Date(last).toISOString(),\n    last_event_id: events[0]!.event_id ?? null,\n  };\n}\n\n/** Persist the verdict; return a message ONLY when the state crossed. */\nasync function reconcile(store: Store, v: Verdict): Promise<string | null> {\n  const now = new Date().toISOString();\n  const data: StateData = {\n    provider: v.provider, state: v.state, detail: v.detail, checked_at: now,\n    ...(v.days_since !== null ? { days_since: v.days_since } : {}),\n    ...(v.threshold_days !== null ? { threshold_days: v.threshold_days } : {}),\n    ...(v.last_event_at ? { last_event_at: v.last_event_at } : {}),\n    ...(v.last_event_id ? { last_event_id: v.last_event_id } : {}),\n  };\n\n  const current = await store.byProvider(v.provider);\n  if (!current) {\n    // First run. A healthy first sighting is remembered silently; an unhealthy\n    // one is worth saying out loud immediately \u2014 you were already in the outage.\n    const created = await store.create(data);\n    return created && v.state !== 'ok' ? format(v) : null; // 409 \u21D2 a racing tick owns it\n  }\n\n  const prev = current.data.state ?? 'ok';\n  if (prev === v.state) {\n    // No crossing: refresh the measurement, stay quiet. A permanently-broken\n    // provider therefore costs exactly one message, not one per day.\n    await store.patch(current.item_id, current.version, data);\n    return null;\n  }\n  // A CROSSING. If-Match makes exactly one of two overlapping ticks the winner.\n  const ok = await store.patch(current.item_id, current.version, data);\n  if (!ok) return null;\n  return v.state === 'ok'\n    ? `\u{1F7E2} RESOLVED: ${v.provider} is delivering again \u2014 last processed event ${v.days_since}d ago (was ${prev})`\n    : format(v);\n}\n\nfunction format(v: Verdict): string {\n  const dot = v.state === 'broken' ? '\u{1F534}' : v.state === 'stale' ? '\u{1F7E0}' : '\u{1F535}';\n  const label = v.state === 'could_not_check' ? 'CHECK FAILED' : v.state.toUpperCase();\n  return `${dot} [${label}] payments heartbeat \u2014 ${v.detail}`;\n}\n\n// \u2500\u2500 the cms state store (the REST envelope: { data: { items: [{item_id, version, data}] } }) \u2500\u2500\nclass Store {\n  constructor(private base: string, private jwt: string) {}\n  private h() { return { authorization: `Bearer ${this.jwt}`, 'content-type': 'application/json' }; }\n  async byProvider(provider: string): Promise<Item | null> {\n    const filter = encodeURIComponent(JSON.stringify({ provider }));\n    const res = await fetch(`${this.base}/v1/cms/items/heartbeat_state?filter=${filter}&limit=1`, { headers: this.h() });\n    if (!res.ok) return null;\n    const body = (await res.json()) as { data?: { items?: Item[] } };\n    return body.data?.items?.[0] ?? null;\n  }\n  /** false on 409 \u2014 `provider` is unique, so a concurrent tick already claimed it. */\n  async create(data: StateData): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/heartbeat_state`, {\n      method: 'POST', headers: this.h(), body: JSON.stringify({ status: 'published', data }),\n    });\n    return res.ok;\n  }\n  /** false on 409 version_conflict \u2014 another tick transitioned this provider first. */\n  async patch(itemId: string, version: number | undefined, data: StateData): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/heartbeat_state/${itemId}`, {\n      method: 'PATCH',\n      headers: { ...this.h(), ...(version !== undefined ? { 'if-match': String(version) } : {}) },\n      body: JSON.stringify({ data }),\n    });\n    return res.ok;\n  }\n}\n\n// \u2500\u2500 the chat webhook: `text` is Slack's field, `content` is Discord's \u2014 send both,\n//    EXCEPT to a Google Chat space webhook (chat.googleapis.com), which takes\n//    `{ text }` alone \u2014 an unknown field can be rejected there, so it is dropped.\n//    (Duplicated from templates/alerts-to-slack on purpose: a blueprint is a\n//    self-contained clone, and every file under functions/ must be a declared\n//    entry point, so there is no place for a shared module to live.)\nasync function post(url: string, text: string): Promise<{ ok: boolean; status: number }> {\n  let host = '';\n  try { host = new URL(url).hostname; } catch { /* unparseable \u2192 the generic body below */ }\n  const body = host === 'chat.googleapis.com' ? { text } : { text, content: text };\n  const res = await fetch(url, {\n    method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify(body),\n  }).catch(() => null);\n  return { ok: Boolean(res?.ok), status: res?.status ?? 0 };\n}\n\nfunction verdict(provider: string, state: State, detail: string): Verdict {\n  return { provider, state, detail, days_since: null, threshold_days: null, last_event_at: null, last_event_id: null };\n}\nfunction median(xs: number[]): number {\n  const s = [...xs].sort((a, b) => a - b);\n  const mid = s.length >> 1;\n  return s.length % 2 ? s[mid]! : (s[mid - 1]! + s[mid]!) / 2;\n}\nconst round2 = (n: number) => Math.round(n * 100) / 100;\n"
     }
   },
   {
@@ -17460,7 +18323,7 @@ const json = (o: unknown, status: number) => Response.json(o, { status });
     "configSrc": "import { defineConfig } from '@vxil/config';\n\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n// \"Job Runner\" \u2014 the BACKGROUND-WORK blueprint. Four ways work leaves the\n// request path, and what happens when it fails:\n//\n//   \u2022 enqueue        \u2192 one-off work, deduplicated by an idempotency key, and\n//                      optionally deferred (seconds from now, or an exact time)\n//   \u2022 schedules      \u2192 cron, with a LATE schedule reporting itself\n//   \u2022 queue trigger  \u2192 a deployed function that IS the worker\n//   \u2022 generation     \u2192 a long provider call vxil babysits for you, holding\n//                      credits while it runs and releasing them when it ends\n//   \u2022 the spine      \u2192 every failure is an audit event; one cron function turns\n//                      the ones that matter into `incidents` rows\n//\n// The credits half is a payments INTEGRATION with the deterministic `mock`\n// provider, so the whole reserve \u2192 settle \u2192 refund story runs with no provider\n// account at all. \"Credits\" here are usage units, not money.\n// \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\nexport default defineConfig({\n  env: 'staging',\n\n  features: {\n    jobs: {\n      enabled: true,\n      // a failing delivery is retried this many times before it dead-letters\n      retry: { defaultMaxAttempts: 3 },\n      retention: { successfulRunDays: 7, failedRunDays: 30 },\n      // once this many runs have dead-lettered today, a further failing run\n      // skips its remaining retries and dead-letters immediately \u2014 a bound on\n      // the churn ONE pathological target can generate. 0 = unlimited.\n      dlqDailyQuota: 200,\n      concurrency: { maxConcurrent: 5 },\n      schedules: { maxPerTenant: 20 },\n      generation: {\n        maxConcurrent: 5,\n        defaultTimeoutMs: 300_000, // 5 min unless the descriptor says otherwise\n        pollMaxAttempts: 30, // give up after 30 polls \u2192 terminal fail\n        maxReserveCredits: 200, // a single run can never hold more than this\n        maxOutstandingReserveCredits: 5_000, // \u2026nor can all in-flight runs together\n      },\n    },\n\n    // The ledger half. `mock` is the deterministic default provider: no keys,\n    // no account, the entire credits path exercisable end to end. Point it at\n    // your own Stripe/Paddle/PayPal/RevenueCat account when you go live \u2014 vxil\n    // is never in the flow of funds.\n    payments: {\n      enabled: true,\n      provider: 'mock',\n      defaults: { currency: 'usd' },\n      ledger: {\n        // product id \u2192 what buying it grants. Consumed by the provider webhook\n        // reducer; the map is DATA, so adding products never changes the config.\n        productMap: {\n          render_pack_1000: { creditType: 'render_credits', amount: 1000, period: 'once' },\n        },\n        // tier \u2192 what being on it entitles you to, and what it tops up monthly\n        tierMap: {\n          pro: {\n            entitlements: ['render'],\n            quotas: { renders_per_day: 500 },\n            rank: 10,\n            grants: [{ creditType: 'render_credits', amount: 5_000, period: 'monthly' }],\n          },\n        },\n        // a generation that ends in failure gives its held credits back\n        autoRefundOnJobFailure: true,\n      },\n    },\n\n    cms: {},\n    functions: { enabled: true },\n  },\n\n  // \u2500\u2500 Schema-as-code (\u22648 index slots per collection: s1\u2013s4/n1\u2013n2/t1\u2013t2) \u2500\u2500\u2500\u2500\u2500\u2500\n  cms: {\n    collections: {\n      // The work items. One row per requested render.\n      renders: {\n        singular: 'render',\n        fields: {\n          // THE DEDUPE ANCHOR. Queue deliveries are at-least-once, so the\n          // worker may see the same item twice; a unique field turns the second\n          // write into a clean 409 the function treats as \"already done\".\n          request_key: { type: 'string', required: true, unique: true, indexSlot: 's1' },\n          title: { type: 'string', indexSlot: 's2' },\n          state: { type: 'string', indexSlot: 's3' }, // queued | processing | done | failed\n          run_id: { type: 'string', indexSlot: 's4' }, // the jobs run that owns it\n          credits: { type: 'int', indexSlot: 'n1' }, // held for this render\n          created_at: { type: 'datetime', indexSlot: 't1' },\n          notes: { type: 'text' },\n        },\n      },\n\n      // The failure memory. One row per incident KEY, so ten dead letters of\n      // the same job are one row \u2014 plus the reserved `__cursor__` row holding\n      // the audit-stream watermark.\n      incidents: {\n        singular: 'incident',\n        fields: {\n          key: { type: 'string', required: true, unique: true, indexSlot: 's1' },\n          event: { type: 'string', indexSlot: 's2' }, // the audit event that raised it\n          level: { type: 'string', indexSlot: 's3' }, // info | warn | error\n          subject: { type: 'string', indexSlot: 's4' }, // job name / schedule id\n          seen_count: { type: 'int', indexSlot: 'n1' },\n          first_seen: { type: 'datetime', indexSlot: 't1' },\n          last_seen: { type: 'datetime', indexSlot: 't2' },\n          cursor: { type: 'string' }, // `__cursor__` row only: last processed audit id\n          detail: { type: 'text' },\n        },\n      },\n    },\n  },\n\n  functions: {\n    // THE WORKER. A queue-triggered function is invoked by an enqueue, not by a\n    // request \u2014 it has no URL a browser can reach. Delivery is at-least-once,\n    // so it dedupes on `request_key` rather than assuming exactly-once.\n    'process-batch': {\n      entry: './functions/process-batch.ts',\n      trigger: { kind: 'queue', source: 'renders' },\n      scopes: ['cms:read', 'cms:write'],\n      egressAllow: [],\n    },\n\n    // THE FAILURE DRAIN. Every feature writes its lifecycle to your tenant's\n    // audit stream; this reads the stream past a watermark every 5 minutes and\n    // turns the failure events that matter into `incidents` rows.\n    'incident-watch': {\n      entry: './functions/incident-watch.ts',\n      trigger: { kind: 'cron', schedule: '*/5 * * * *' },\n      scopes: ['cms:read', 'cms:write'],\n      // The audit stream is a control-plane read, not one of the feature APIs\n      // the function's scoped callback covers \u2014 so the drain reads it with the\n      // narrowest key that can: one holding ONLY `features:read`.\n      secrets: ['secret:vxil_read_key'],\n      egressAllow: [],\n    },\n  },\n\n  secrets: {\n    vxil_read_key: {\n      feature: 'functions',\n      description: 'a vxil API key of this backend holding ONLY features:read \u2014 reads the audit stream',\n    },\n  },\n\n  seed: {\n    cms: [\n      {\n        collection: 'renders',\n        items: [\n          {\n            request_key: 'seed-0001',\n            title: 'Quarterly report render',\n            state: 'queued',\n            credits: 10,\n            created_at: '2026-04-01T08:00:00Z',\n            notes: 'Seed row so the collection is not empty on first push.',\n          },\n        ],\n      },\n    ],\n  },\n});\n",
     "readme": '# Job Runner (ops)\n\nFour ways work leaves the request path, and one answer for what happens when it fails. If you have\never written a `jobs` table, a worker loop, a retry counter and a "why did this run twice?" post\nmortem, this is that, declared.\n\n```bash\nvxil init --template job-runner\nvxil quickstart                                     # or `vxil link <slug>`\nprintf \'%s\' "$READ_KEY" | vxil secrets set functions/vxil_read_key\nvxil push                                           # collections + both functions\n```\n\n`vxil_read_key` is an API key **of this same backend** holding **only `features:read`** \u2014 the\nincident drain reads the audit stream with it (dashboard \u2192 API keys \u2192 create, tick `features:read`\nand nothing else). Everything else here needs no credentials at all: the payments integration runs\non the deterministic `mock` provider, so the whole credits story works before you have a provider\naccount. "Credits" are usage units you meter, not money and not stored value.\n\n## The four ways work leaves the request path\n\n| | You call | It runs | Use it when |\n|---|---|---|---|\n| **Enqueue** | `POST /v1/jobs/enqueue` | now, or later | one-off work, deduplicated by a key you choose |\n| **Schedule** | `POST /v1/jobs/schedules` | on a 5-field UTC cron | recurring work \u2014 and it tells you when it ran late |\n| **Queue trigger** | `vxil functions invoke <fn> --async` | a deployed function | the worker IS your code, with no URL to expose |\n| **Generation** | `POST /v1/jobs/generation` | a long provider call vxil babysits | a model/render/export that answers in minutes, not milliseconds |\n\nAnd one answer for failure: **every feature writes its lifecycle to your audit stream**, and the\n`incident-watch` cron turns the failures that matter into rows you can query.\n\n## The 10-minute walkthrough\n\n`$KEY` is a server key with `jobs:read jobs:write payments:read payments:write cms:read cms:write\nfunctions:read functions:invoke features:read`.\n\n**1. Enqueue the same thing twice.** The dedupe scope is `(job_name, idempotency_key)`:\n\n```bash\nvxil api POST /v1/jobs/enqueue --data \'{"job_name":"report.email","target_url":"https://hooks.example.com/report","payload":{"report_id":"r_42"},"idempotency_key":"r_42"}\'\n# 202 { "data": { "run_id": "run_\u2026", "state": "queued" } }\n\nvxil api POST /v1/jobs/enqueue --data \'{"job_name":"report.email","target_url":"https://hooks.example.com/report","payload":{"report_id":"r_42"},"idempotency_key":"r_42"}\'\n# 202 { "data": { "run_id": "run_\u2026", "state": "queued", "deduplicated": true } }   \u2190 the SAME run_id\n```\n\nNote where the key goes: **in the body**, as `idempotency_key`. (The `Idempotency-Key` *header* is\nwhat the notifications and payments surfaces read \u2014 jobs reads the field.) The window is 24 hours,\nand it is backstopped in the database, so two racing enqueues cannot both win.\n\n**2. Run it later.** Two mutually exclusive fields \u2014 pick one:\n\n```bash\nvxil api POST /v1/jobs/enqueue --data \'{"job_name":"nudge","target_url":"https://hooks.example.com/nudge","delay_seconds":900}\'\n# 202 { "data": { "run_id": "run_\u2026", "state": "queued", "deliver_after": "\u2026T12:26:12.686Z" } }\n\nvxil api POST /v1/jobs/enqueue --data \'{"job_name":"nudge","target_url":"https://hooks.example.com/nudge","deliver_after":"2026-12-24T09:00:00Z"}\'\n# 202 { "data": { "run_id": "run_\u2026", "state": "delayed", "deliver_after": "2026-12-24T09:00:00.000Z" } }\n```\n\n`state` tells you which machinery is holding it: a short delay rides the queue itself and fires on\nthe second; anything beyond twelve hours is parked as `delayed` and released by a minute-tick\nsweep. The ceiling is 30 days. A `deliver_after` in the past is a 422, not a surprise.\n\n**3. A schedule that reports itself late.**\n\n```bash\nvxil api POST /v1/jobs/schedules --data \'{"job_name":"nightly.rollup","target_url":"https://hooks.example.com/rollup","cron":"0 2 * * *"}\'\n# 201 { "data": { "schedule_id": "sch_\u2026", "next_run_at": "2026-09-12T02:00:00.000Z", "state": "active" } }\n```\n\nFive UTC fields, with `*`, numbers, lists, ranges and steps \u2014 no month or weekday names, no `L`/`W`.\nWhen a tick finally fires more than **twice its own interval** late, the platform writes\n`jobs.schedule.missed` (once per crossing, not once per tick) and `jobs.schedule.recovered` when it\ncatches up. Step 7 turns both into rows.\n\n**4. The worker is your function.** `process-batch` is queue-triggered \u2014 it has no URL a browser can\nreach. Hand it a batch:\n\n```bash\nvxil functions invoke process-batch --async --data \'{"batch_id":"b-1","items":[{"key":"b-1:a","title":"Q3 deck","credits":10},{"key":"b-1:b","title":"Q3 memo","credits":5}]}\'\n# 202 { "data": { "run_id": "run_\u2026", "state": "queued" } }\n\nvxil api GET "/v1/cms/items/renders?filter=%7B%22state%22%3A%22queued%22%7D"\n# 200 \u2026 two new rows, request_key "b-1:a" and "b-1:b"\n```\n\n(`--async` enqueues it; drop the flag to call the same function synchronously and\nread its answer. `--async` needs a linked project \u2014 `vxil quickstart` or `vxil link <slug>`.)\n\nNow send the **exact same batch again**, synchronously so you can read the verdict:\n\n```bash\nvxil functions invoke process-batch --data \'{"batch_id":"b-1","items":[{"key":"b-1:a","title":"Q3 deck","credits":10},{"key":"b-1:b","title":"Q3 memo","credits":5}]}\'\n# { "batch_id": "b-1", "created": 0, "duplicates": 2, "rejected": 0 }\n```\n\nNothing was duplicated, and the function contains no dedupe logic. `request_key` is declared\n`unique`, so the second create is a 409 \u2014 and the function reads a 409 as *already done*. That is\nthe whole strategy: **delivery is at-least-once, so correctness lives in a declared field, not in a\nhope that it runs once.**\n\n**5. Credits: reserve \u2192 settle.** Grant some usage units first (the header is required here \u2014 this\nis the money-shaped surface):\n\n```bash\ncurl -s -X POST "https://api.vxil.com/v1/payments/credits/grant" \\\n  -H "authorization: Bearer $KEY" -H \'content-type: application/json\' \\\n  -H \'idempotency-key: seed-1\' \\\n  -d \'{"user_id":"u_demo","credit_type":"render_credits","amount":100,"source":"seed"}\'\n# 200 { "data": { "balance_after": 100, "ledger_entry_id": null } }\n\nvxil api GET "/v1/payments/credits/balance?user_id=u_demo&credit_type=render_credits"\n# 200 { "data": { "credit_type": "render_credits", "balance": 100, "held": 0, "available": 100, \u2026 } }\n```\n\nNow start a generation that holds ten of them while it runs:\n\n```bash\nvxil api POST /v1/jobs/generation --data \'{\n  "job_name": "render.deck",\n  "provider": { "url": "https://api.your-render-provider.example/v1/renders",\n                "method": "POST",\n                "body": { "format": "pdf" } },\n  "completion": { "mode": "poll",\n                  "status_path": "status",\n                  "poll": { "url": "https://api.your-render-provider.example/v1/renders/latest",\n                            "method": "GET", "interval_ms": 5000 } },\n  "reserve_credits": { "amount": 10, "user_id": "u_demo",\n                       "credit_type": "render_credits", "reason": "deck render" },\n  "timeout": { "after_ms": 120000 },\n  "payload": { "render_id": "b-1:a" }\n}\'\n# 202 { "data": { "run_id": "run_\u2026", "generation_status": "pending", "state": "queued" } }\n```\n\nImmediately, the balance moves \u2014 but only the **held** half:\n\n```bash\nvxil api GET "/v1/payments/credits/balance?user_id=u_demo&credit_type=render_credits"\n# 200 { "data": { "balance": 100, "held": 10, "available": 90, \u2026 } }\n\nvxil api GET "/v1/payments/usage?user_id=u_demo&credit_type=render_credits"\n# 200 { "data": { "user_id": "u_demo", "entries": [\n#   { "kind": "consume", "state": "provisional", "delta": -10, "job_id": "run_\u2026", "source": "deck render", \u2026 },\n#   { "kind": "grant",   "state": "committed",   "delta": 100, \u2026 } ] } }\n```\n\n`state: "provisional"` is the reservation. Nothing has been spent yet \u2014 `balance` is untouched and\n`available` dropped, so the same user cannot start ten more renders on credits they do not have.\n\nWhen the run reaches a terminal state, vxil settles it for you, and the ledger says which way it\nwent:\n\n- **completed** \u2192 the provisional row flips to `committed` and a `settle` row lands with\n  `source: "job:succeeded"`. The credits were spent.\n- **failed / timed out** \u2192 a `reversal` row lands with a **positive** delta and\n  `source: "job:failed"`, the original flips to `reversed`, and `held` returns to zero. The\n  customer was not charged for work that did not happen. That refund is the\n  `ledger.autoRefundOnJobFailure` flag in `vxil.config.ts`; turn it off and a failure still releases\n  the hold but keeps the charge.\n\nTwo ceilings you do not have to remember to set: a single run\'s request is **clamped** to\n`generation.maxReserveCredits` (never rejected, so a bad caller cannot break the flow), and the sum\nof all outstanding holds is refused past `generation.maxOutstandingReserveCredits` with a 429. Both\nhave safe defaults.\n\nPoll mode is exactly what it says: vxil calls your provider once, then re-reads\n`completion.poll.url` every `interval_ms`, reading `status_path` out of the body. Anything it does\nnot recognise counts as *still processing* \u2014 a generation is never silently completed by a typo.\nAfter `pollMaxAttempts` it fails terminally, and the timeout does the same on the wall clock.\n\n**6. Dead letters and replay.** There is no separate dead-letter inbox \u2014 a dead letter is a run in\nthe `dead` state:\n\n```bash\nvxil api GET "/v1/jobs/runs?state=dead&limit=20"\n# 200 { "data": { "runs": [ { "run_id": "run_\u2026", "job_name": "report.email", "state": "dead",\n#                             "attempt_number": 1, "max_attempts": 1,\n#                             "last_error_class": "NonRetryableHttp",\n#                             "last_error_msg": "target returned 404", \u2026 } ] } }\n\nvxil api POST /v1/jobs/runs/run_\u2026/replay\n# 202 { "data": { "run_id": "run_NEW", "replayed_from": "run_\u2026", "state": "queued" } }\n```\n\nReplay takes **no body** and clones the original into a *new* run \u2014 the dead row is evidence and\nstays untouched. Only terminal runs replay; anything still in flight is a `409 not_replayable`.\n\n**7. Failures become rows.** `incident-watch` runs every five minutes. Force it once:\n\n```bash\nvxil functions invoke incident-watch\n# first run:  { "initialized": true, "cursor": "\u2026", "raised": 0 }     \u2190 history never floods you\n# after a dead letter, the next run:\n# { "scanned": 12, "raised": 1, "resolved": 0, "cursor": "\u2026" }\n\nvxil api GET /v1/cms/items/incidents\n# 200 \u2026 { "key": "jobs:dead-letter:report.email", "event": "job.dead_lettered", "level": "error",\n#         "subject": "report.email", "seen_count": 1, "first_seen": "\u2026", "last_seen": "\u2026",\n#         "detail": "run run_\u2026 died after attempt 1" }\n```\n\nTen dead letters of the same job produce **one** row with `seen_count: 10`, because the incident\nkey collapses them. `jobs.schedule.missed` and `jobs.schedule.recovered` share a key, so a schedule\nthat catches up closes its own incident. The `RULES` table in `functions/incident-watch.ts` is the\nallow-list \u2014 plain data. Widen it from the catalog of everything the platform can emit:\n\n```bash\nvxil api GET /v1/webhooks/events/catalog\n# 200 { "data": { "count": 170, "events": [ { "name": "job.dead_lettered", "feature": "jobs",\n#                                             "level": "failure", "payload_keys": [ \u2026 ] } \u2026 ],\n#                 "prefixes": [ { "prefix": "payments.", "count": 21 }, \u2026 ] } }   \u2190 34 prefixes\n```\n\nIf you would rather the same events went to **your own** endpoint than into a collection, subscribe\nto the spine directly \u2014 same events, different consumer:\n\n```bash\nvxil api POST /v1/webhooks/subscriptions --data \'{"target_url":"https://ops.example.com/vxil","event_prefixes":["job.","jobs."]}\'\n```\n\n## What to learn from this\n\n- **Exactly-once is not a delivery guarantee you can buy; it is a field you declare.** `unique` on\n  `request_key`, `idempotency_key` on the enqueue, `foreign_id` elsewhere \u2014 each converts\n  at-least-once delivery into an at-most-once *effect*.\n- **A reservation is not a charge.** Holding credits while long work runs, and releasing them if it\n  fails, is the difference between metering and billing people for your outages. The ledger shows\n  both halves, so you can answer "why was I charged?" from a query.\n- **Failure needs a vocabulary, not a log.** `job.dead_lettered`, `jobs.schedule.missed`,\n  `job.generation.failed` are named events with stable payloads \u2014 that is why a 40-line function can\n  turn them into an incident board, and why the catalog route can tell an agent what exists.\n- **Late is a different failure from broken.** A schedule that fires twice its interval late says so\n  once, and says so again when it recovers. Alerting on every tick teaches people to mute you.\n- **The clamp beats the rejection.** Capping a requested hold, rather than refusing it, keeps a\n  careless caller from breaking the flow while still bounding the blast radius.\n\n**Pairs with:** `templates/alerts-to-slack/` (the same drain, routed to a chat channel instead of a\ncollection) and `templates/payments-heartbeat/` (noticing the failure that is *silence*).\n',
     "functions": {
-      "incident-watch.ts": "// incident-watch.ts \u2014 FAILURE EVENTS \u2192 `incidents` ROWS (a vxil function).\n//\n// Trigger: cron `*/5 * * * *`. Every feature writes its lifecycle to your\n// tenant's AUDIT STREAM \u2014 that stream is the event spine, and this function is\n// one consumer of it. Each run:\n//   1. reads the watermark (the reserved `__cursor__` row in `incidents`; the\n//      first run stores the NEWEST id and stops, so history never floods you),\n//   2. drains `GET /v1/audit/export?after_id=\u2026` (ascending NDJSON) past it,\n//   3. matches each row against RULES \u2014 an allow-list, not a firehose,\n//   4. upserts ONE row per incident key (ten dead letters of the same job are\n//      one row with `seen_count: 10`, not ten rows),\n//   5. advances the watermark with If-Match, so an overlapping tick stands down\n//      instead of double-counting.\n//\n// WHY A KEY: the audit stream is a platform read, not one of the feature APIs\n// the function's scoped callback covers \u2014 so the drain uses the narrowest key\n// that can reach it, one holding ONLY `features:read`, stored as a secret and\n// revocable without a redeploy.\n//\n// To fan the same events out to YOUR OWN https endpoint instead, subscribe:\n//   POST /v1/webhooks/subscriptions { \"target_url\": \"\u2026\", \"event_prefixes\": [\"job.\"] }\n// Both ride the same spine; this one keeps the state inside your backend.\n\nimport type { CronFunctionEnvelope, HttpFunctionEnvelope } from '@vxil/sdk';\n\nconst MAX_PAGES_PER_RUN = 5; // \xD7 500 rows \u2014 bounds one tick\nconst DETAIL_MAX = 240;\n\ntype Level = 'info' | 'warn' | 'error';\ntype Payload = Record<string, unknown>;\ninterface Rule {\n  level: Level;\n  key: (p: Payload) => string;\n  subject: (p: Payload) => string;\n  detail: (p: Payload) => string;\n  /** a healing event: clears the row rather than incrementing it */\n  resolves?: boolean;\n}\n\nconst str = (v: unknown, fallback = 'unknown') => (typeof v === 'string' && v ? v : fallback);\nconst num = (v: unknown) => (typeof v === 'number' ? v : null);\n\n/** THE ALLOW-LIST. Every name below is an audit event the jobs feature writes\n *  today; anything not listed is ignored. Own this table \u2014 it is data, not a\n *  routing engine. `GET /v1/webhooks/events/catalog` lists every event the\n *  platform can emit if you want to widen it. */\nconst RULES: Record<string, Rule> = {\n  // a run exhausted its retries\n  'job.dead_lettered': {\n    level: 'error',\n    key: (p) => `jobs:dead-letter:${str(p.job_name)}`,\n    subject: (p) => str(p.job_name),\n    detail: (p) => `run ${str(p.run_id)} died after attempt ${num(p.attempt) ?? '?'}`,\n  },\n  // the tenant burned its daily dead-letter budget \u2014 a louder, rarer signal\n  'job.dead_letter_quota_exceeded': {\n    level: 'error',\n    key: () => 'jobs:dead-letter-quota',\n    subject: (p) => str(p.job_name),\n    detail: (p) => `daily dead-letter quota spent; run ${str(p.run_id)} skipped its retries`,\n  },\n  // a schedule fired more than 2\xD7 its own interval late\n  'jobs.schedule.missed': {\n    level: 'warn',\n    key: (p) => `jobs:schedule:${str(p.schedule_id)}`,\n    subject: (p) => str(p.job_name),\n    detail: (p) =>\n      `expected ${str(p.expected_at)}, observed ${str(p.observed_at)} `\n      + `(${num(p.late_seconds) ?? '?'}s late on a ${num(p.interval_seconds) ?? '?'}s interval)`,\n  },\n  // \u2026and its healing twin, sharing the SAME key, so recovery closes the row\n  'jobs.schedule.recovered': {\n    level: 'info',\n    key: (p) => `jobs:schedule:${str(p.schedule_id)}`,\n    subject: (p) => str(p.job_name),\n    detail: (p) => `back on time at ${str(p.observed_at)}`,\n    resolves: true,\n  },\n  // a generation run ended in a terminal failure (its held credits are released)\n  'job.generation.failed': {\n    level: 'error',\n    key: (p) => `jobs:generation:${str(p.error_class, 'unclassified')}`,\n    subject: (p) => str(p.error_class, 'unclassified'),\n    detail: (p) => `run ${str(p.run_id)} failed (${str(p.error_class, 'no error class')})`,\n  },\n};\n\ninterface AuditRow { id?: string | number; event?: string; created_at?: string; payload?: Payload }\ninterface Item { item_id: string; version: number; data: Record<string, unknown> }\n// the schedule tick, or a hand invoke (`POST /v1/fn/incident-watch`) carrying `{ dry_run }`\ntype Env = CronFunctionEnvelope | HttpFunctionEnvelope<{ dry_run?: boolean }>;\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const readKey = env.secrets?.vxil_read_key;\n    if (!cms || !readKey) {\n      return Response.json({ error: 'missing cms scope or vxil_read_key secret' }, { status: 503 });\n    }\n    const store = new Store(base, cms);\n\n    // 1. the watermark\n    const cursorRow = await store.byKey('__cursor__');\n    if (!cursorRow) {\n      const newest = await newestAuditId(base, readKey);\n      await store.create({ key: '__cursor__', cursor: newest, last_seen: new Date().toISOString() });\n      return Response.json({ initialized: true, cursor: newest, raised: 0 });\n    }\n    let cursor = String(cursorRow.data.cursor ?? '0');\n\n    // 2. drain\n    const rows: AuditRow[] = [];\n    for (let page = 0; page < MAX_PAGES_PER_RUN; page++) {\n      const { rows: batch, next } = await drain(base, readKey, cursor);\n      rows.push(...batch);\n      if (batch.length > 0) cursor = String(batch[batch.length - 1]!.id ?? cursor);\n      if (!next || batch.length === 0) break;\n      cursor = next;\n    }\n\n    // 3 + 4. match and upsert\n    let raised = 0;\n    let resolved = 0;\n    const now = new Date().toISOString();\n    for (const row of rows) {\n      const rule = RULES[String(row.event ?? '')];\n      if (!rule) continue;\n      const p = row.payload ?? {};\n      const key = rule.key(p);\n      const existing = await store.byKey(key);\n\n      if (rule.resolves) {\n        if (existing) {\n          await store.patch(existing, {\n            level: 'info', event: String(row.event), detail: rule.detail(p).slice(0, DETAIL_MAX),\n            last_seen: now,\n          });\n          resolved++;\n        }\n        continue;\n      }\n      if (existing) {\n        await store.patch(existing, {\n          event: String(row.event),\n          level: rule.level,\n          subject: rule.subject(p),\n          seen_count: Number(existing.data.seen_count ?? 0) + 1,\n          detail: rule.detail(p).slice(0, DETAIL_MAX),\n          last_seen: now,\n        });\n      } else {\n        await store.create({\n          key,\n          event: String(row.event),\n          level: rule.level,\n          subject: rule.subject(p),\n          seen_count: 1,\n          first_seen: now,\n          last_seen: now,\n          detail: rule.detail(p).slice(0, DETAIL_MAX),\n        });\n      }\n      raised++;\n    }\n\n    // 5. advance \u2014 If-Match, so exactly one overlapping run wins\n    if (!env.payload?.dry_run) {\n      await store.patch(cursorRow, { cursor, last_seen: now });\n    }\n    return Response.json({ scanned: rows.length, raised, resolved, cursor });\n  },\n};\n\n// \u2500\u2500 the audit stream (ascending NDJSON; `x-vxil-next-after-id` continues it) \u2500\u2500\nasync function drain(\n  base: string, key: string, afterId: string,\n): Promise<{ rows: AuditRow[]; next: string | null }> {\n  const res = await fetch(\n    `${base}/v1/audit/export?after_id=${encodeURIComponent(afterId)}&limit=500`,\n    { headers: { authorization: `Bearer ${key}` } },\n  );\n  if (!res.ok) throw new Error(`audit export ${res.status}`);\n  const rows = (await res.text()).split('\\n').filter(Boolean).map((l) => JSON.parse(l) as AuditRow);\n  return { rows, next: res.headers.get('x-vxil-next-after-id') };\n}\nasync function newestAuditId(base: string, key: string): Promise<string> {\n  const res = await fetch(`${base}/v1/audit?limit=1`, { headers: { authorization: `Bearer ${key}` } });\n  if (!res.ok) throw new Error(`audit list ${res.status}`);\n  const body = (await res.json()) as { data?: { events?: AuditRow[] } };\n  return String(body.data?.events?.[0]?.id ?? '0');\n}\n\n// \u2500\u2500 the cms store (the REST envelope is { data: { items: [{ item_id, version, data }] } }) \u2500\u2500\nclass Store {\n  constructor(private base: string, private jwt: string) {}\n  private h() {\n    return { authorization: `Bearer ${this.jwt}`, 'content-type': 'application/json' };\n  }\n  async byKey(key: string): Promise<Item | null> {\n    const filter = encodeURIComponent(JSON.stringify({ key }));\n    const res = await fetch(`${this.base}/v1/cms/items/incidents?filter=${filter}&limit=1`, {\n      headers: this.h(),\n    });\n    if (!res.ok) return null;\n    const body = (await res.json()) as { data?: { items?: Item[] } };\n    return body.data?.items?.[0] ?? null;\n  }\n  /** false on 409 \u2014 a concurrent run already claimed this unique key */\n  async create(data: Record<string, unknown>): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/incidents`, {\n      method: 'POST', headers: this.h(), body: JSON.stringify({ data }),\n    });\n    return res.ok;\n  }\n  /** false on 409 \u2014 a concurrent run already moved this row past `version` */\n  async patch(item: Item, data: Record<string, unknown>): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/incidents/${item.item_id}`, {\n      method: 'PATCH',\n      headers: { ...this.h(), 'if-match': String(item.version) },\n      body: JSON.stringify({ data }),\n    });\n    return res.ok;\n  }\n}\n",
+      "incident-watch.ts": "// incident-watch.ts \u2014 FAILURE EVENTS \u2192 `incidents` ROWS (a vxil function).\n//\n// Trigger: cron `*/5 * * * *`. Every feature writes its lifecycle to your\n// tenant's AUDIT STREAM \u2014 that stream is the event spine, and this function is\n// one consumer of it. Each run:\n//   1. reads the watermark (the reserved `__cursor__` row in `incidents`; the\n//      first run stores the NEWEST id and stops, so history never floods you),\n//   2. drains `GET /v1/audit/export?after_id=\u2026` (ascending NDJSON) past it,\n//   3. matches each row against RULES \u2014 an allow-list, not a firehose,\n//   4. upserts ONE row per incident key (ten dead letters of the same job are\n//      one row with `seen_count: 10`, not ten rows),\n//   5. advances the watermark with If-Match, so an overlapping tick stands down\n//      instead of double-counting.\n//\n// WHY A KEY: the audit stream is a platform read, not one of the feature APIs\n// the function's scoped callback covers \u2014 so the drain uses the narrowest key\n// that can reach it, one holding ONLY `features:read`, stored as a secret and\n// revocable without a redeploy.\n//\n// To fan the same events out to YOUR OWN https endpoint instead, subscribe:\n//   POST /v1/webhooks/subscriptions { \"target_url\": \"\u2026\", \"event_prefixes\": [\"job.\"] }\n// Both ride the same spine; this one keeps the state inside your backend.\n\n// cron-walk: persisted-cursor \u2014 the audit watermark lives in the `__cursor__` row and advances with If-Match.\n\nimport type { CronFunctionEnvelope, HttpFunctionEnvelope } from '@vxil/sdk';\n\nconst MAX_PAGES_PER_RUN = 5; // \xD7 500 rows \u2014 bounds one tick\nconst DETAIL_MAX = 240;\n\ntype Level = 'info' | 'warn' | 'error';\ntype Payload = Record<string, unknown>;\ninterface Rule {\n  level: Level;\n  key: (p: Payload) => string;\n  subject: (p: Payload) => string;\n  detail: (p: Payload) => string;\n  /** a healing event: clears the row rather than incrementing it */\n  resolves?: boolean;\n}\n\nconst str = (v: unknown, fallback = 'unknown') => (typeof v === 'string' && v ? v : fallback);\nconst num = (v: unknown) => (typeof v === 'number' ? v : null);\n\n/** THE ALLOW-LIST. Every name below is an audit event the jobs feature writes\n *  today; anything not listed is ignored. Own this table \u2014 it is data, not a\n *  routing engine. `GET /v1/webhooks/events/catalog` lists every event the\n *  platform can emit if you want to widen it. */\nconst RULES: Record<string, Rule> = {\n  // a run exhausted its retries\n  'job.dead_lettered': {\n    level: 'error',\n    key: (p) => `jobs:dead-letter:${str(p.job_name)}`,\n    subject: (p) => str(p.job_name),\n    detail: (p) => `run ${str(p.run_id)} died after attempt ${num(p.attempt) ?? '?'}`,\n  },\n  // the tenant burned its daily dead-letter budget \u2014 a louder, rarer signal\n  'job.dead_letter_quota_exceeded': {\n    level: 'error',\n    key: () => 'jobs:dead-letter-quota',\n    subject: (p) => str(p.job_name),\n    detail: (p) => `daily dead-letter quota spent; run ${str(p.run_id)} skipped its retries`,\n  },\n  // a schedule fired more than 2\xD7 its own interval late\n  'jobs.schedule.missed': {\n    level: 'warn',\n    key: (p) => `jobs:schedule:${str(p.schedule_id)}`,\n    subject: (p) => str(p.job_name),\n    detail: (p) =>\n      `expected ${str(p.expected_at)}, observed ${str(p.observed_at)} `\n      + `(${num(p.late_seconds) ?? '?'}s late on a ${num(p.interval_seconds) ?? '?'}s interval)`,\n  },\n  // \u2026and its healing twin, sharing the SAME key, so recovery closes the row\n  'jobs.schedule.recovered': {\n    level: 'info',\n    key: (p) => `jobs:schedule:${str(p.schedule_id)}`,\n    subject: (p) => str(p.job_name),\n    detail: (p) => `back on time at ${str(p.observed_at)}`,\n    resolves: true,\n  },\n  // a generation run ended in a terminal failure (its held credits are released)\n  'job.generation.failed': {\n    level: 'error',\n    key: (p) => `jobs:generation:${str(p.error_class, 'unclassified')}`,\n    subject: (p) => str(p.error_class, 'unclassified'),\n    detail: (p) => `run ${str(p.run_id)} failed (${str(p.error_class, 'no error class')})`,\n  },\n};\n\ninterface AuditRow { id?: string | number; event?: string; created_at?: string; payload?: Payload }\ninterface Item { item_id: string; version: number; data: Record<string, unknown> }\n// the schedule tick, or a hand invoke (`POST /v1/fn/incident-watch`) carrying `{ dry_run }`\ntype Env = CronFunctionEnvelope | HttpFunctionEnvelope<{ dry_run?: boolean }>;\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    const readKey = env.secrets?.vxil_read_key;\n    if (!cms || !readKey) {\n      return Response.json({ error: 'missing cms scope or vxil_read_key secret' }, { status: 503 });\n    }\n    const store = new Store(base, cms);\n\n    // 1. the watermark\n    const cursorRow = await store.byKey('__cursor__');\n    if (!cursorRow) {\n      const newest = await newestAuditId(base, readKey);\n      await store.create({ key: '__cursor__', cursor: newest, last_seen: new Date().toISOString() });\n      return Response.json({ initialized: true, cursor: newest, raised: 0 });\n    }\n    let cursor = String(cursorRow.data.cursor ?? '0');\n\n    // 2. drain\n    const rows: AuditRow[] = [];\n    for (let page = 0; page < MAX_PAGES_PER_RUN; page++) {\n      const { rows: batch, next } = await drain(base, readKey, cursor);\n      rows.push(...batch);\n      if (batch.length > 0) cursor = String(batch[batch.length - 1]!.id ?? cursor);\n      if (!next || batch.length === 0) break;\n      cursor = next;\n    }\n\n    // 3 + 4. match and upsert\n    let raised = 0;\n    let resolved = 0;\n    const now = new Date().toISOString();\n    for (const row of rows) {\n      const rule = RULES[String(row.event ?? '')];\n      if (!rule) continue;\n      const p = row.payload ?? {};\n      const key = rule.key(p);\n      const existing = await store.byKey(key);\n\n      if (rule.resolves) {\n        if (existing) {\n          await store.patch(existing, {\n            level: 'info', event: String(row.event), detail: rule.detail(p).slice(0, DETAIL_MAX),\n            last_seen: now,\n          });\n          resolved++;\n        }\n        continue;\n      }\n      if (existing) {\n        await store.patch(existing, {\n          event: String(row.event),\n          level: rule.level,\n          subject: rule.subject(p),\n          seen_count: Number(existing.data.seen_count ?? 0) + 1,\n          detail: rule.detail(p).slice(0, DETAIL_MAX),\n          last_seen: now,\n        });\n      } else {\n        await store.create({\n          key,\n          event: String(row.event),\n          level: rule.level,\n          subject: rule.subject(p),\n          seen_count: 1,\n          first_seen: now,\n          last_seen: now,\n          detail: rule.detail(p).slice(0, DETAIL_MAX),\n        });\n      }\n      raised++;\n    }\n\n    // 5. advance \u2014 If-Match, so exactly one overlapping run wins\n    if (!env.payload?.dry_run) {\n      await store.patch(cursorRow, { cursor, last_seen: now });\n    }\n    return Response.json({ scanned: rows.length, raised, resolved, cursor });\n  },\n};\n\n// \u2500\u2500 the audit stream (ascending NDJSON; `x-vxil-next-after-id` continues it) \u2500\u2500\nasync function drain(\n  base: string, key: string, afterId: string,\n): Promise<{ rows: AuditRow[]; next: string | null }> {\n  const res = await fetch(\n    `${base}/v1/audit/export?after_id=${encodeURIComponent(afterId)}&limit=500`,\n    { headers: { authorization: `Bearer ${key}` } },\n  );\n  if (!res.ok) throw new Error(`audit export ${res.status}`);\n  const rows = (await res.text()).split('\\n').filter(Boolean).map((l) => JSON.parse(l) as AuditRow);\n  return { rows, next: res.headers.get('x-vxil-next-after-id') };\n}\nasync function newestAuditId(base: string, key: string): Promise<string> {\n  const res = await fetch(`${base}/v1/audit?limit=1`, { headers: { authorization: `Bearer ${key}` } });\n  if (!res.ok) throw new Error(`audit list ${res.status}`);\n  const body = (await res.json()) as { data?: { events?: AuditRow[] } };\n  return String(body.data?.events?.[0]?.id ?? '0');\n}\n\n// \u2500\u2500 the cms store (the REST envelope is { data: { items: [{ item_id, version, data }] } }) \u2500\u2500\nclass Store {\n  constructor(private base: string, private jwt: string) {}\n  private h() {\n    return { authorization: `Bearer ${this.jwt}`, 'content-type': 'application/json' };\n  }\n  async byKey(key: string): Promise<Item | null> {\n    const filter = encodeURIComponent(JSON.stringify({ key }));\n    const res = await fetch(`${this.base}/v1/cms/items/incidents?filter=${filter}&limit=1`, {\n      headers: this.h(),\n    });\n    if (!res.ok) return null;\n    const body = (await res.json()) as { data?: { items?: Item[] } };\n    return body.data?.items?.[0] ?? null;\n  }\n  /** false on 409 \u2014 a concurrent run already claimed this unique key */\n  async create(data: Record<string, unknown>): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/incidents`, {\n      method: 'POST', headers: this.h(), body: JSON.stringify({ data }),\n    });\n    return res.ok;\n  }\n  /** false on 409 \u2014 a concurrent run already moved this row past `version` */\n  async patch(item: Item, data: Record<string, unknown>): Promise<boolean> {\n    const res = await fetch(`${this.base}/v1/cms/items/incidents/${item.item_id}`, {\n      method: 'PATCH',\n      headers: { ...this.h(), 'if-match': String(item.version) },\n      body: JSON.stringify({ data }),\n    });\n    return res.ok;\n  }\n}\n",
       "process-batch.ts": "// process-batch.ts \u2014 THE WORKER (a vxil function).\n//\n// Trigger: queue. This function has no URL a browser can reach \u2014 it runs because\n// something was ENQUEUED. The envelope it receives is:\n//   { trigger: 'queue', tenant_id, request_id, idempotency_key, vxil_base,\n//     scoped_jwts, secrets, payload }\n// where `payload` is exactly the object you put inside the enqueue body's\n// `payload.payload`, and `idempotency_key` is stable per run.\n//\n// DELIVERY IS AT-LEAST-ONCE. A retry, an overlapping tick, or a replay can hand\n// you the same batch twice, so correctness cannot rest on \"it runs once\". Here\n// the `request_key` field on `renders` is declared `unique`, which turns the\n// second create into a clean 409 \u2014 and a 409 is not an error, it is the answer\n// \"already done\". That is the whole dedupe strategy: one declared field, and a\n// status code you agree to read as success.\n\nimport type { QueueFunctionEnvelope } from '@vxil/sdk';\n\ntype Env = QueueFunctionEnvelope<{ batch_id?: string; items?: Array<{ key?: string; title?: string; credits?: number }> }>;\n\nexport default {\n  async fetch(req: Request): Promise<Response> {\n    const env = (await req.json().catch(() => ({}))) as Env;\n    const base = env.vxil_base ?? 'https://api.vxil.com';\n    const cms = env.scoped_jwts?.cms;\n    if (!cms) return Response.json({ error: 'missing cms scope' }, { status: 403 });\n\n    const batchId = String(env.payload?.batch_id ?? env.idempotency_key ?? 'batch');\n    const items = Array.isArray(env.payload?.items) ? env.payload!.items! : [];\n    if (items.length === 0) return Response.json({ batch_id: batchId, created: 0, duplicates: 0 });\n\n    let created = 0;\n    let duplicates = 0;\n    let rejected = 0;\n\n    for (const [i, item] of items.entries()) {\n      // Derive a stable key per item so the SAME batch always produces the SAME\n      // keys \u2014 that is what makes the redelivery a duplicate rather than a copy.\n      const requestKey = String(item.key ?? `${batchId}:${i}`);\n      const res = await fetch(`${base}/v1/cms/items/renders`, {\n        method: 'POST',\n        headers: { authorization: `Bearer ${cms}`, 'content-type': 'application/json' },\n        body: JSON.stringify({\n          data: {\n            request_key: requestKey,\n            title: String(item.title ?? requestKey),\n            state: 'queued',\n            run_id: env.idempotency_key ?? null,\n            credits: typeof item.credits === 'number' ? item.credits : 0,\n            created_at: new Date().toISOString(),\n          },\n        }),\n      });\n      if (res.ok) created++;\n      else if (res.status === 409) duplicates++; // already processed \u2014 the point of `unique`\n      else rejected++;\n    }\n\n    return Response.json({ batch_id: batchId, created, duplicates, rejected });\n  },\n};\n"
     }
   },
@@ -18031,9 +18894,9 @@ function coerceCsvCell(v, type) {
 }
 
 // src/migrate/adapters/generic-pg.ts
-var IDENT_RE = /^[a-z_][a-z0-9_]*$/i;
-function quoteIdent(name) {
-  if (!IDENT_RE.test(name)) throw new Error(`unsafe identifier '${name}' \u2014 only [A-Za-z_][A-Za-z0-9_]* is readable`);
+var IDENT_RE2 = /^[a-z_][a-z0-9_]*$/i;
+function quoteIdent2(name) {
+  if (!IDENT_RE2.test(name)) throw new Error(`unsafe identifier '${name}' \u2014 only [A-Za-z_][A-Za-z0-9_]* is readable`);
   return `"${name}"`;
 }
 function redactSourceUrl(url) {
@@ -18220,17 +19083,17 @@ var catalogSql = {
   })
 };
 function changedSinceSql(column, n) {
-  return `(${quoteIdent(column)} >= $${n}::timestamptz OR ${quoteIdent(column)} IS NULL)`;
+  return `(${quoteIdent2(column)} >= $${n}::timestamptz OR ${quoteIdent2(column)} IS NULL)`;
 }
 function keysetPageSql(schema, table, columns, pk, after, limit, changedSince) {
-  const cols = columns.map(quoteIdent).join(", ");
-  const from = `${quoteIdent(schema)}.${quoteIdent(table)}`;
+  const cols = columns.map(quoteIdent2).join(", ");
+  const from = `${quoteIdent2(schema)}.${quoteIdent2(table)}`;
   const n = Math.max(1, Math.trunc(limit));
   const conds = [];
   const params = [];
   if (after !== null) {
     params.push(after);
-    conds.push(`${quoteIdent(pk)} > $${params.length}`);
+    conds.push(`${quoteIdent2(pk)} > $${params.length}`);
   }
   if (changedSince) {
     params.push(changedSince.since);
@@ -18238,14 +19101,14 @@ function keysetPageSql(schema, table, columns, pk, after, limit, changedSince) {
   }
   const where = conds.length ? ` WHERE ${conds.join(" AND ")}` : "";
   return {
-    text: `SELECT ${cols} FROM ${from}${where} ORDER BY ${quoteIdent(pk)} ASC LIMIT ${n}`,
+    text: `SELECT ${cols} FROM ${from}${where} ORDER BY ${quoteIdent2(pk)} ASC LIMIT ${n}`,
     params
   };
 }
 function offsetPageSql(schema, table, columns, orderBy, offset, limit, changedSince) {
-  const cols = columns.map(quoteIdent).join(", ");
-  const from = `${quoteIdent(schema)}.${quoteIdent(table)}`;
-  const order = orderBy.map(quoteIdent).join(", ");
+  const cols = columns.map(quoteIdent2).join(", ");
+  const from = `${quoteIdent2(schema)}.${quoteIdent2(table)}`;
+  const order = orderBy.map(quoteIdent2).join(", ");
   const n = Math.max(1, Math.trunc(limit));
   const off = Math.max(0, Math.trunc(offset));
   const where = changedSince ? ` WHERE ${changedSinceSql(changedSince.column, 1)}` : "";
@@ -18276,7 +19139,7 @@ var GenericPgAdapter = class {
   statementTimeoutMs;
   constructor(opts) {
     this.schemas = opts.schemas && opts.schemas.length ? opts.schemas : ["public"];
-    for (const s of this.schemas) quoteIdent(s);
+    for (const s of this.schemas) quoteIdent2(s);
     this.batchSize = opts.batchSize ?? 500;
     this.statementTimeoutMs = Math.trunc(opts.statementTimeoutMs ?? 12e4);
     this.authTable = opts.authTable;
@@ -18350,7 +19213,7 @@ var GenericPgAdapter = class {
     for (const r of tablesR) {
       const schema2 = r.table_schema;
       const name = r.table_name;
-      if (!IDENT_RE.test(name)) {
+      if (!IDENT_RE2.test(name)) {
         warnings.push(`table "${schema2}"."${name}" skipped \u2014 name is not a safe identifier`);
         continue;
       }
@@ -18363,7 +19226,7 @@ var GenericPgAdapter = class {
       const columns = [];
       for (const c of colsByTable.get(key) ?? []) {
         const colName = c.column_name;
-        if (!IDENT_RE.test(colName)) {
+        if (!IDENT_RE2.test(colName)) {
           warnings.push(`${name}.${colName} skipped \u2014 column name is not a safe identifier`);
           continue;
         }
@@ -18591,13 +19454,26 @@ var supabaseSql = {
     text: `SELECT count(*)::bigint AS n FROM auth.users`,
     params: []
   }),
+  /** W14 — the ONE statement that reads a credential: GoTrue's bcrypt
+   *  `encrypted_password` ('' for a user with no password, e.g. OAuth-only)
+   *  plus whether the address was confirmed, keyset on the uuid id. Run only
+   *  under `--with-password-hashes` / `--oidc-issuer`; soft-deleted users are
+   *  not read (`deleted_at` exists on current GoTrue — pass false when absent). */
+  credentialsPage: (after, limit, hasDeletedAt) => {
+    const n = Math.max(1, Math.trunc(limit));
+    const conds = [...after !== null ? ["id > $1::uuid"] : [], ...hasDeletedAt ? ["deleted_at IS NULL"] : []];
+    return {
+      text: `SELECT id::text AS id, encrypted_password, (email_confirmed_at IS NOT NULL) AS email_verified FROM auth.users${conds.length ? ` WHERE ${conds.join(" AND ")}` : ""} ORDER BY id ASC LIMIT ${n}`,
+      params: after !== null ? [after] : []
+    };
+  },
   /** does this database carry the Storage schema? */
   storageProbe: () => ({
     text: `SELECT to_regclass('storage.buckets') IS NOT NULL AS present`,
     params: []
   }),
   buckets: () => ({
-    text: `SELECT name FROM storage.buckets ORDER BY name`,
+    text: `SELECT name, public FROM storage.buckets ORDER BY name`,
     params: []
   }),
   bucketObjectCounts: () => ({
@@ -18652,7 +19528,7 @@ var SupabaseAdapter = class extends GenericPgAdapter {
         schema.buckets = (await this.q(supabaseSql.buckets())).map((r) => {
           const name = r.name;
           const c = counts.get(name);
-          return c !== void 0 ? { name, objectCount: c } : { name };
+          return { name, ...c !== void 0 ? { objectCount: c } : {}, public: r.public === true };
         });
       }
     } catch {
@@ -18681,6 +19557,26 @@ var SupabaseAdapter = class extends GenericPgAdapter {
       after = next.slice(2);
     }
   }
+  /** W14 credential pages (supabaseSql.credentialsPage). The rows hold bcrypt
+   *  hashes: never logged, never written anywhere but the import request. */
+  async *readCredentials(cursor) {
+    const source = await this.introspect();
+    if (!source.authUsers?.present) throw new Error("auth.users not present on this source");
+    const cols = source.authUsers.columns ?? [];
+    if (!cols.includes("encrypted_password")) throw new Error("auth.users has no encrypted_password column \u2014 nothing to import");
+    let after = cursor !== void 0 && cursor !== "" ? cursor : null;
+    for (; ; ) {
+      const rows = await this.q(supabaseSql.credentialsPage(after, this.batchSize, cols.includes("deleted_at")));
+      const out = rows.map((r) => {
+        const h = typeof r.encrypted_password === "string" && r.encrypted_password.length > 0 ? r.encrypted_password : null;
+        return { id: String(r.id), password_hash: h, email_verified: r.email_verified === true };
+      });
+      const next = rows.length === this.batchSize ? String(rows[rows.length - 1].id) : null;
+      yield { rows: out, nextCursor: next };
+      if (next === null) return;
+      after = next;
+    }
+  }
   /** stream one bucket's objects: rows from storage.objects, bytes from the
    *  Storage HTTP API (lazy per object — piped straight into the files PUT).
    *  (No `override` — the base class does not implement the optional
@@ -18823,7 +19719,7 @@ async function prompt(q, opts = {}) {
       stdin.on("data", onData);
     });
   }
-  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const rl = createInterface2({ input: process.stdin, output: process.stderr });
   return await new Promise((res) => rl.question(q, (a) => {
     rl.close();
     res(a.trim());
@@ -18986,7 +19882,38 @@ function requireApi(sel = "prod", opts = {}) {
   const t = resolveTargetOrFail(sel, opts.exitCode ?? 1);
   if (!t.apiKey) fail(noKeyMessage(t), opts.exitCode ?? 1);
   if (opts.write) announceTarget(t, opts.write);
-  return { api: makeApi({ apiKey: t.apiKey, baseUrl: t.baseUrl }), baseUrl: t.baseUrl, slug: t.tenantSlug, target: t };
+  const raw = makeApi({ apiKey: t.apiKey, baseUrl: t.baseUrl });
+  let checked = null;
+  const api = async (method, path, body, headers) => {
+    if (opts.write || method.toUpperCase() !== "GET") {
+      checked ??= assertKeyTenant(t, raw);
+      await checked;
+    }
+    return raw(method, path, body, headers);
+  };
+  return { api, baseUrl: t.baseUrl, slug: t.tenantSlug, target: t };
+}
+function slotWhere(t) {
+  return t.slot === "named" ? `target '${t.slotName}'` : t.slot === "dev" ? "the dev slot" : t.slot === "env" ? "VXIL_API_KEY" : "the primary binding";
+}
+async function assertKeyTenant(t, api, exitCode = 1) {
+  if (!knownTenantId(t.tenantId)) return;
+  let read;
+  try {
+    read = await api("GET", "/v1/features");
+  } catch (e) {
+    read = e;
+  }
+  const v = judgeKeyTenant(t.tenantId, read);
+  if (v.kind === "mismatch") {
+    fail(keyTenantRefusal(v, {
+      where: slotWhere(t),
+      slug: t.tenantSlug,
+      keySource: t.keySource,
+      envLabel: t.envLabel,
+      as: t.slot === "dev" ? "dev" : t.slot === "named" ? t.slotName : void 0
+    }), exitCode);
+  }
 }
 var ExportPageError = class extends Error {
 };
@@ -19097,7 +20024,7 @@ async function exportNdjson(feature, opts = { urls: false, paceMs: 0 }) {
   if (!t.apiKey) fail(noKeyMessage(t));
   const inc = opts.urls ? "&include=urls" : "";
   const pg = exportPager({ baseUrl: t.baseUrl, apiKey: t.apiKey }, opts.paceMs);
-  const out = flag("out");
+  const out = opts.out ?? flag("out");
   const started = Date.now();
   const tally = newDownloadTally();
   let sink = null;
@@ -19109,6 +20036,7 @@ async function exportNdjson(feature, opts = { urls: false, paceMs: 0 }) {
     written += lines.length;
   };
   let resume = [];
+  const unresumable = [];
   try {
     const first = await exportPage(pg, `/v1/export/${feature}?format=ndjson${inc}`, opts.urls);
     sink = openExportSink(out);
@@ -19131,7 +20059,7 @@ async function exportNdjson(feature, opts = { urls: false, paceMs: 0 }) {
     for (let i = 0; i < truncated.length; i++) {
       const tr = truncated[i];
       if (!tr.after) {
-        console.error(`vxil: note \u2014 table '${tr.table}' hit the server row cap and has no resumable primary key; remaining rows not included`);
+        unresumable.push(tr.table);
         continue;
       }
       let after = tr.after;
@@ -19155,6 +20083,102 @@ async function exportNdjson(feature, opts = { urls: false, paceMs: 0 }) {
   sink.commit();
   if (out) console.log(`exported ${feature} \u2192 ${out} (${written} lines)`);
   if (opts.urls) reportDownloads(tally, started, sink.readLive);
+  if (unresumable.length) {
+    console.error(incompleteTablesMessage(feature, unresumable, false));
+    process.exitCode = worseExportExit(process.exitCode, EXPORT_EXIT_INCOMPLETE);
+  }
+}
+async function exportPasswordHashes(feature, outOverride) {
+  if (feature !== "auth") fail("--include-password-hashes applies to `vxil export auth` only");
+  const out = outOverride ?? flag("out");
+  if (!out) fail("--include-password-hashes needs --out <file> (the hashes are never printed to the terminal)");
+  const { t, slug, dash, run } = boundProjectSession();
+  console.error(CREDENTIAL_EXPORT_NOTE);
+  await confirmTyped("export password hashes", `Type the project slug '${slug}' to export its password hashes: `, slug);
+  announceTarget(t, "export auth --include-password-hashes");
+  const path = resolve7(process.cwd(), out);
+  const partial = `${path}.partial`;
+  const fd = openSync(partial, "w", 384);
+  let tenantId = "";
+  try {
+    const r = await run(async (cookie, id) => {
+      tenantId = id;
+      writeFileSync6(fd, credentialsHeader(slug, id) + "\n");
+      return exportCredentialsViaSession(dash, cookie, id, (users) => {
+        if (users.length) writeFileSync6(fd, users.map(credentialLine).join("\n") + "\n");
+      });
+    });
+    closeSync(fd);
+    chmodSync2(partial, 384);
+    renameSync(partial, path);
+    console.log(`exported ${r.users} password hash(es) of '${slug}' (${tenantId}) \u2192 ${out} (mode 0600)`);
+  } catch (e) {
+    try {
+      closeSync(fd);
+    } catch {
+    }
+    let removed = true;
+    try {
+      rmSync2(partial, { force: true });
+    } catch {
+      removed = false;
+    }
+    fail(`${e.message} \u2014 nothing was written to ${out}` + (removed ? " (the partial file was deleted)" : ` \u2014 DELETE ${out}.partial yourself: it holds the hashes read before the failure`));
+  }
+}
+async function exportToPostgres() {
+  const dsn = flag("to-postgres");
+  if (!dsn) fail("usage: vxil export --to-postgres <postgres://\u2026> [--pg-schema <name>] [--urls [--pace <s>]] [--include-password-hashes]");
+  const schema = flag("pg-schema") ?? "vxil";
+  if (!/^[a-z_][a-z0-9_]{0,62}$/.test(schema)) fail(`--pg-schema '${schema}' must be a lower-case SQL identifier`);
+  const urls = hasFlag("urls");
+  const pace = parsePace(flag("pace"));
+  if ("err" in pace) fail(pace.err);
+  const withHashes = hasFlag("include-password-hashes");
+  const dir = mkdtempSync(join4(tmpdir(), "vxil-export-pg-"));
+  chmodSync2(dir, 448);
+  process.once("exit", () => {
+    try {
+      rmSync2(dir, { recursive: true, force: true });
+    } catch {
+    }
+  });
+  let db = null;
+  try {
+    const complete = { users: false, cms: false, files: false };
+    const paths = { users: join4(dir, "users.ndjson"), cms: join4(dir, "cms.ndjson"), files: join4(dir, "files.ndjson") };
+    let worst = 0;
+    for (const f of ["users", "cms", "files"]) {
+      process.exitCode = 0;
+      await exportNdjson(f, { urls: urls && f === "files", paceMs: pace.ms, out: paths[f] });
+      const code = Number(process.exitCode ?? 0);
+      complete[f] = code === 0;
+      worst = Math.max(worst, code);
+    }
+    process.exitCode = worst;
+    let credentials;
+    if (withHashes) {
+      credentials = join4(dir, "credentials.ndjson");
+      await exportPasswordHashes("auth", credentials);
+    }
+    db = openTargetDatabase(dsn);
+    console.error(`vxil export \u2192 your database ${redactSourceUrl(dsn)} (schema "${schema}")`);
+    const report = await loadIntoPostgres(db, schema, {
+      users: paths.users,
+      cms: paths.cms,
+      files: paths.files,
+      ...credentials ? { credentials } : {},
+      complete
+    }, (m) => console.log(m));
+    if (report.skipped.length) console.error(`vxil: ${report.skipped.length} row(s) not loaded:
+  ${report.skipped.slice(0, 20).join("\n  ")}`);
+    if (worst !== 0) console.error(`vxil: an export finished incomplete (exit ${worst}) \u2014 its tables were loaded but nothing was removed from them; re-run to complete`);
+  } catch (e) {
+    fail(`export to your database: ${e.message}`);
+  } finally {
+    await db?.end({ timeout: 5 }).catch(() => void 0);
+    rmSync2(dir, { recursive: true, force: true });
+  }
 }
 async function completeJsonObjects(bundle, t, paceMs, firstPageAt) {
   const cut = objectsCut(bundle);
@@ -19191,6 +20215,9 @@ async function runApply(apply, sel = "prod", opts = {}) {
   const { api, target } = requireApi(sel, apply ? { write: "push" } : gate ? { exitCode: 2 } : {});
   if (!apply) console.error(targetBanner(target, gate ? "diff" : "plan"));
   const report = { drift: 0, ignored: 0, errors: 0 };
+  const pushProblems = { hard: [], strict: [] };
+  const strictPush = apply && hasFlag("strict");
+  const allowDestructive = hasFlag("allow-destructive");
   const compared = newComparedCounts({ apiState: !!opts.apiState });
   const ignore = apply ? [] : loadDriftIgnore();
   const ignoredKeys = [];
@@ -19302,6 +20329,7 @@ ${r.feature} (remote v${r.version}):`);
 ${r.feature}.${r.datum} (declared in config):`);
       if (r.remoteUnavailable) {
         notCompared(r.remoteUnavailable, apply ? "the server did not converge it \u2014 re-run `vxil push`" : `needs ${r.datum === "policies" ? "ratelimits:read" : r.datum === "subscriptions" ? "webhooks:read" : "ai:read"} or admin`);
+        if (apply) pushProblems.strict.push(`${r.feature}.${r.datum} was not converged (unreadable)`);
         continue;
       }
       console.log(formatDeclaredApiState(r, { strict: strictApiState }));
@@ -19309,11 +20337,13 @@ ${r.feature}.${r.datum} (declared in config):`);
       if (r.refused) {
         if (gate) report.errors++;
         else console.error(`vxil: warning \u2014 ${r.feature}.${r.datum} not converged: ${r.refused}`);
+        if (apply) pushProblems.strict.push(`${r.feature}.${r.datum} refused: ${r.refused}`);
         continue;
       }
       if (r.deferred) {
         console.error(`vxil: warning \u2014 ${r.feature}.${r.datum} not converged yet: ${r.deferred}`);
         if (gate) report.errors++;
+        if (apply) pushProblems.strict.push(`${r.feature}.${r.datum} deferred: ${r.deferred}`);
         continue;
       }
       if (apply && (r.summary.created.length || r.summary.updated.length || r.summary.recreated.length || r.summary.deleted.length)) {
@@ -19324,6 +20354,7 @@ ${r.feature}.${r.datum} (declared in config):`);
         if (row2.kind === "ambiguous" || row2.kind === "failed") {
           if (gate) report.errors++;
           else if (apply && row2.kind === "failed") console.error(`vxil: warning \u2014 ${key} was not converged`);
+          if (apply) pushProblems.strict.push(`${key} ${row2.kind === "failed" ? "was not converged" : "is ambiguous"}`);
           continue;
         }
         if (row2.kind === "undeclared" && !strictApiState) {
@@ -19341,8 +20372,29 @@ ${r.feature}.${r.datum} (declared in config):`);
   });
   await runSection("functions", async () => {
     if (!cfg.functions || !Object.keys(cfg.functions).length) {
-      if (cfg.features.functions) {
-        console.log("\nfunctions: features.functions is declared but no functions/ are defined to deploy \u2014 the feature enables per-function on deploy (no feature-level config namespace).");
+      const ownsFunctions = !!cfg.features.functions || !skipFunctions && await backendListsFunctions(api);
+      if (ownsFunctions) {
+        if (cfg.features.functions) {
+          console.log("\nfunctions: features.functions is declared but no functions/ are defined to deploy \u2014 the feature enables per-function on deploy (no feature-level config namespace).");
+        } else {
+          console.log("\nfunctions: vxil.config declares none, but the functions feature is enabled on the target:");
+        }
+        if (!skipFunctions) {
+          const r2 = await planFunctions({ api, functions: {}, cwd, apply, remoteOnly: allowDestructive ? "delete" : "report" });
+          if (r2.remoteUnavailable) {
+            notCompared(r2.remoteUnavailable, "needs functions:read, features:read or admin");
+            return;
+          }
+          if (r2.changes.length) console.log(formatFnChanges(r2.changes));
+          for (const c of r2.changes) count(`function:${c.name}`);
+          compared.functions += r2.changes.length;
+          if (apply && r2.hookReconcile && r2.hookReconcile.failed > 0) {
+            pushProblems.hard.push(`trigger wiring: ${r2.hookReconcile.failed} subscription(s) failed to reconcile \u2014 ${hookReconcileRemedy(void 0)}`);
+          }
+          if (apply && r2.remoteOnlyKept?.length) {
+            pushProblems.strict.push(`deployed but not declared (kept): ${r2.remoteOnlyKept.join(", ")} \u2014 \`vxil push --allow-destructive\` deletes them`);
+          }
+        }
       }
       return;
     }
@@ -19351,7 +20403,7 @@ ${r.feature}.${r.datum} (declared in config):`);
 functions: skipped (--skip-functions) \u2014 ${declaredFns.length} declared function(s) not ${apply ? "deployed" : "compared"}`);
       return;
     }
-    const r = await planFunctions({ api, functions: cfg.functions, cwd, apply });
+    const r = await planFunctions({ api, functions: cfg.functions, cwd, apply, remoteOnly: allowDestructive ? "delete" : "report" });
     console.log("\nfunctions:");
     if (r.remoteUnavailable) {
       notCompared(r.remoteUnavailable, "needs functions:read, features:read or admin");
@@ -19360,6 +20412,7 @@ functions: skipped (--skip-functions) \u2014 ${declaredFns.length} declared func
     console.log(formatFnChanges(r.changes));
     if (apply && r.applied) console.log(`  \u2713 deployed ${r.applied} function(s)`);
     for (const w of r.warnings ?? []) {
+      if (r.hookReconcile?.warning && w.message === r.hookReconcile.warning) continue;
       console.error(`  ! ${w.fn}: ${w.message}`);
     }
     if (apply && r.cmsHookSubscriptions && (r.cmsHookSubscriptions.created || r.cmsHookSubscriptions.deleted)) {
@@ -19369,8 +20422,36 @@ functions: skipped (--skip-functions) \u2014 ${declaredFns.length} declared func
       console.log(`  \u2713 webhook-trigger subscription reconciled (+${r.webhookSubscriptions.created} / -${r.webhookSubscriptions.deleted})`);
     }
     for (const c of r.changes) if (c.kind !== "unchanged") count(`function:${c.name}`);
-    compared.functions += Object.keys(cfg.functions).length;
+    compared.functions += Object.keys(cfg.functions).length + r.changes.filter((c) => c.kind === "remote-only" || c.kind === "delete").length;
+    if (apply && r.hookReconcile && r.hookReconcile.failed > 0) {
+      const why = r.hookReconcile.warning ?? `${r.hookReconcile.failed} trigger subscription(s) could not be written`;
+      console.error(`  ! trigger wiring: ${why}`);
+      pushProblems.hard.push(`trigger wiring: ${r.hookReconcile.failed} subscription(s) failed to reconcile \u2014 a function may be wired to nothing; ${hookReconcileRemedy(declaredFns[0])}`);
+    }
+    if (apply && r.remoteOnlyKept?.length) {
+      pushProblems.strict.push(`deployed but not declared (kept): ${r.remoteOnlyKept.join(", ")} \u2014 \`vxil push --allow-destructive\` deletes them`);
+    }
   });
+  if (!apply) {
+    await runSection("api-majors", async () => {
+      const typesPath = resolve7(cwd, "vxil.types.ts");
+      const pinned = existsSync8(typesPath) ? parseApiVersionsBlock(readFileSync8(typesPath, "utf8")) : null;
+      if (!pinned) return;
+      const fres = await api("GET", "/v1/features");
+      const live = fres.status === 200 ? fres.body.data?.api_versions : void 0;
+      if (!live) {
+        if (fres.status !== 200) notCompared({ route: "GET /v1/features", status: fres.status }, "needs any valid key");
+        return;
+      }
+      const rows = apiMajorDrift(pinned, live);
+      console.log("\napi majors (vxil.types.ts API_VERSIONS vs the backend):");
+      if (!rows.length) console.log(`  (in sync \u2014 ${Object.keys(pinned).length} feature(s) pinned)`);
+      for (const r of rows) {
+        console.log(`  ~ api-major:${r.feature}  pinned [${r.pinned.join(", ")}] \u2192 backend [${r.live.join(", ")}] \u2014 read the changelog, then \`vxil gen\` online to re-pin`);
+        count(`api-major:${r.feature}`);
+      }
+    });
+  }
   const strictSecrets = hasFlag("strict-secrets");
   const informationalKeys = [];
   if (!apply && (gate || explain)) {
@@ -19468,6 +20549,21 @@ vxil diff \u2192 ${report.drift} drift item(s), ${report.ignored} ignored, ${rep
   }
   if (!apply) console.log("\n(run `vxil push` to apply)");
   if (apply && !hasFlag("no-gen")) await runGen(sel);
+  if (apply) {
+    const exitWith = pushExitCode(pushProblems, strictPush);
+    for (const line of exitWith.lines) console.error(`vxil: ${line}`);
+    return exitWith.code;
+  }
+  return 0;
+}
+async function backendListsFunctions(api) {
+  try {
+    const res = await api("GET", "/v1/features");
+    const list = res.status === 200 ? res.body.data?.features : void 0;
+    return Array.isArray(list) && list.includes("functions");
+  } catch {
+    return false;
+  }
 }
 async function runServerApply(sel) {
   const { api, target } = requireApi(sel, { write: "push --server" });
@@ -19480,6 +20576,11 @@ apply ${done2.apply_id}: ${done2.status}`);
     if (done2.status === "running") console.log(`resume with: vxil push --server --resume ${done2.apply_id}`);
     if (done2.status !== "succeeded" && done2.status !== "running") process.exit(1);
     if (done2.status === "succeeded" && !hasFlag("no-gen")) await runGen(sel);
+    const resumed = { hard: [], strict: [] };
+    applyHookProblems(done2, resumed);
+    const exitResumed = pushExitCode(resumed, hasFlag("strict"));
+    for (const line of exitResumed.lines) console.error(`vxil: ${line}`);
+    if (exitResumed.code !== 0) process.exit(exitResumed.code);
     return;
   }
   const loaded = await loadVxilConfig();
@@ -19539,13 +20640,47 @@ apply ${done.apply_id}: ${done.status}`);
   }
   const standing = done.steps.filter((st) => st.kind === "api-state" && st.status === "failed");
   const onlyApiStateFailed = done.steps.every((st) => st.status !== "failed" || st.kind === "api-state");
+  const problems = { hard: [], strict: [] };
   if (done.status === "partial" && standing.length && onlyApiStateFailed && done.failed_step?.kind === "api-state" && done.steps.every((st) => st.status !== "rolled_back")) {
-    for (const st of standing) console.error(`vxil: warning \u2014 ${st.target} not converged: ${st.error ?? ""} (the config stands; fix the cause and re-push)`);
+    for (const st of standing) {
+      console.error(`vxil: warning \u2014 ${st.target} not converged: ${st.error ?? ""} (the config stands; fix the cause and re-push)`);
+      problems.strict.push(`${st.target} not converged: ${st.error ?? ""}`);
+    }
   } else if (done.status !== "succeeded") {
     const f = done.failed_step;
     fail(`apply ${done.status}${f ? ` \u2014 step ${f.seq} (${f.kind} ${f.target}): ${f.error}` : ""} (config/functions were rolled back to their pre-apply versions; cms schema additions were kept)`);
   }
+  applyHookProblems(done, problems);
+  if (!hasFlag("skip-functions") && (fnNames.length || cfg.features.functions || await backendListsFunctions(api))) {
+    const list = await api("GET", "/v1/functions");
+    if (list.status !== 200) {
+      const code = list.body.error?.code;
+      console.error(`vxil: warning \u2014 GET /v1/functions \u2192 ${list.status}${code ? ` ${code}` : ""}: deployed functions the config no longer declares were NOT checked`);
+      problems.strict.push(`functions list unreadable (${list.status}${code ? ` ${code}` : ""}) \u2014 remote-only functions not checked`);
+    } else {
+      const deployed = (list.body.data?.functions ?? []).map((f) => f.name);
+      for (const name of deployed.filter((n) => !fnNames.includes(n)).sort()) {
+        if (hasFlag("allow-destructive")) {
+          const del = await deleteRemoteFunction(api, name);
+          console.log(`  - ${name} [deployed, not in vxil.config] \u2014 ${del.gone ? "already gone" : "deleted (--allow-destructive)"}`);
+          if (del.hook && del.hook.failed > 0) problems.hard.push(`trigger wiring: ${del.hook.failed} subscription(s) failed to reconcile after deleting ${name} \u2014 ${hookReconcileRemedy(fnNames[0])}`);
+        } else {
+          console.log(`  - ${name} [deployed, not in vxil.config] \u2014 kept; \`vxil push --server --allow-destructive\` deletes it`);
+          problems.strict.push(`deployed but not declared (kept): ${name}`);
+        }
+      }
+    }
+  }
   if (!hasFlag("no-gen")) await runGen(sel);
+  const exitWith = pushExitCode(problems, hasFlag("strict"));
+  for (const line of exitWith.lines) console.error(`vxil: ${line}`);
+  if (exitWith.code !== 0) process.exit(exitWith.code);
+}
+function applyHookProblems(done, problems) {
+  const hook = hookReconcileOf(done);
+  if (!hook || hook.failed === 0) return;
+  console.error(`  ! trigger wiring: ${hook.warning ?? `${hook.failed} trigger subscription(s) could not be written`}`);
+  problems.hard.push(`trigger wiring: ${hook.failed} subscription(s) failed to reconcile \u2014 a function may be wired to nothing; re-run \`vxil push --server\` (every executed apply re-runs the reconcile)`);
 }
 async function runSeed(sel, opts = {}) {
   const { api } = requireApi(sel, { write: "seed" });
@@ -19583,6 +20718,8 @@ async function runGen(sel = "prod", opts = {}) {
   let apiVersions;
   if (offline) {
     ({ env, features, collections, functions } = genInputFromConfig(await loadVxilConfig()));
+    const committed = resolve7(process.cwd(), flag("out") ?? "vxil.types.ts");
+    if (existsSync8(committed)) apiVersions = parseApiVersionsBlock(readFileSync8(committed, "utf8")) ?? void 0;
   } else {
     const { api, slug } = requireApi(sel);
     tenant = slug;
@@ -19643,7 +20780,9 @@ async function runGen(sel = "prod", opts = {}) {
 }
 async function runWatch(sel) {
   const cwd = process.cwd();
-  await promotionGate(resolveTargetOrFail(sel), false);
+  const watchTarget = resolveTargetOrFail(sel);
+  if (watchTarget.apiKey) await assertKeyTenant(watchTarget, makeApi({ apiKey: watchTarget.apiKey, baseUrl: watchTarget.baseUrl }));
+  await promotionGate(watchTarget, false);
   console.log("vxil dev --watch: applying on save (Ctrl-C to stop)\u2026");
   const apply = async () => {
     try {
@@ -19734,6 +20873,7 @@ async function runDoctor() {
   if (t?.apiKey) {
     const api = makeApi({ apiKey: t.apiKey, baseUrl: t.baseUrl });
     const fres = await api("GET", "/v1/features");
+    if (knownTenantId(t.tenantId)) checks.push(keyTenantCheck(judgeKeyTenant(t.tenantId, fres)));
     if (fres.status === 200) {
       const live = new Set(fres.body.data?.features ?? []);
       checks.push({ name: "edge reachable", ok: true, detail: `${live.size} features enabled live` });
@@ -19790,7 +20930,10 @@ async function runDoctor() {
         const local = /* @__PURE__ */ new Map();
         for (const [n, def] of Object.entries(cfg.functions)) {
           try {
-            local.set(n, sourceSha12((await bundleFunction(resolve7(process.cwd(), def.entry), { projectRoot: process.cwd() })).source));
+            local.set(n, sourceSha12(
+              (await bundleFunction(resolve7(process.cwd(), def.entry), { projectRoot: process.cwd() })).source,
+              recordedFunctionsRuntime(lres.body.data?.runtime ?? FUNCTIONS_RUNTIME)
+            ));
           } catch (e) {
             checks.push({ name: `function '${n}' bundle`, ok: false, detail: e.message.split("\n")[0] ?? "bundle failed" });
           }
@@ -19920,6 +21063,14 @@ function listTemplates() {
   }
   console.log("\nEach template is a typed vxil.config.ts you clone and OWN \u2014 no platform lock over the shape.");
 }
+{
+  const help = helpRequest(cmd, rest);
+  if (help && "print" in help) {
+    console.log(help.print);
+    process.exit(0);
+  }
+  if (help && "delegate" in help) normalizeHelpArgv(rest);
+}
 try {
   switch (cmd) {
     case "--version":
@@ -19984,7 +21135,8 @@ try {
       if (d.expires_at) console.log(`  dev tenant \u2014 expires ${d.expires_at} (the nightly reaper tears it down; extend by recreating)`);
       if (!hasFlag("no-push")) {
         console.log("\napplying your config (cms schema \u2192 config \u2192 functions) + generating types\u2026");
-        await runApply(true);
+        const pushCode = await runApply(true);
+        if (pushCode !== 0) process.exitCode = pushCode;
       }
       let firstCollection = "your-collection";
       try {
@@ -20458,8 +21610,8 @@ try {
     }
     case "projects": {
       const [sub = "list", arg] = positional(0);
-      const PROJECTS_USAGE = "usage: vxil projects [list] [--json] \xB7 projects create <slug> [--name <display>] [--json] \xB7 projects rm <slug> [--yes] [--json]";
-      if (!["list", "create", "rm"].includes(sub)) fail(PROJECTS_USAGE);
+      const PROJECTS_USAGE = "usage: vxil projects [list] [--json] \xB7 projects create <slug> [--name <display>] [--workload production|staging|development] [--json] \xB7 projects workload <slug> production|staging|development [--json] \xB7 projects rm <slug> [--yes] [--json]";
+      if (!["list", "create", "rm", "workload"].includes(sub)) fail(PROJECTS_USAGE);
       const base2 = accountDashBase();
       const dash = makeDash(base2);
       const host = dashboardOrigin(base2);
@@ -20471,15 +21623,32 @@ try {
         break;
       }
       if (sub === "create") {
-        const p = parseProjectCreate(arg, flag("name"));
+        const p = parseProjectCreate(arg, flag("name"), flag("workload"));
         if ("error" in p) fail(p.error);
         console.error(`vxil projects create ${p.body.slug} \u2192 ${host}`);
         const { project } = await withDashSession(dash, base2, (c) => createProjectViaSession(dash, c, p.body));
         if (jsonOut) console.log(JSON.stringify(project, null, 2));
-        else console.log(`\u2713 created '${project.slug}' (${project.display_name}, ${project.tier}) \u2014 no key and no features yet`);
+        else console.log(`\u2713 created '${project.slug}' (${project.display_name}, ${project.tier}${project.workload ? `, ${project.workload}` : ""}) \u2014 no key and no features yet`);
         console.error(`next: vxil link ${project.slug} --mint && vxil push   (this repo's binding is unchanged)`);
         break;
       }
+      if (sub === "workload") {
+        if (!arg) fail(PROJECTS_USAGE);
+        const w = parseWorkloadArg(positional(0)[2]);
+        if ("error" in w) fail(w.error);
+        const { tenants: tenants2 } = await withDashSession(dash, base2, (c) => listProjectsViaSession(dash, c));
+        const target = tenants2.find((x) => x.slug === arg);
+        if (!target) fail(`no project '${arg}' on this account \u2014 \`vxil projects list\``);
+        console.error(`vxil projects workload ${arg} ${w.workload} \u2192 ${host}`);
+        const { change } = await withDashSession(dash, base2, (c) => setProjectWorkloadViaSession(dash, c, target.id, w.workload));
+        if (jsonOut) console.log(JSON.stringify({ slug: arg, ...change }, null, 2));
+        else {
+          const out = renderWorkloadChange(arg, change);
+          console.log(out.stdout);
+          for (const l of out.stderr) console.error(l);
+        }
+        break;
+      }
       if (!arg) fail(PROJECTS_USAGE);
       const { tenants } = await withDashSession(dash, base2, (c) => listProjectsViaSession(dash, c));
       const victim = tenants.find((x) => x.slug === arg);
@@ -20710,12 +21879,15 @@ ${formatSummary(state)}`);
     case "push": {
       if (hasFlag("prod") && (hasFlag("dev") || flag("target") !== void 0)) fail("--prod cannot be combined with --dev / --target \u2014 pick one target");
       const sel = selector();
-      await promotionGate(resolveTargetOrFail(sel), hasFlag("prod"));
+      const pushTarget = resolveTargetOrFail(sel);
+      if (pushTarget.apiKey) await assertKeyTenant(pushTarget, makeApi({ apiKey: pushTarget.apiKey, baseUrl: pushTarget.baseUrl }));
+      await promotionGate(pushTarget, hasFlag("prod"));
       if (hasFlag("server") || flag("resume") !== void 0) {
         await runServerApply(sel);
         break;
       }
-      await runApply(true, sel);
+      const pushCode = await runApply(true, sel);
+      if (pushCode !== 0) process.exit(pushCode);
       break;
     }
     case "gen":
@@ -20851,7 +22023,7 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
     case "env": {
       const [sub] = positional(0);
       if (sub !== "pull") fail("usage: vxil env pull [--dev | --target <name>] [--file <path=.env.local>] [--print] [--no-gitignore]");
-      runEnvPull(selector());
+      await runEnvPull(selector());
       break;
     }
     case "secrets": {
@@ -20925,8 +22097,16 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
       break;
     }
     case "export": {
+      if (flag("to-postgres") !== void 0) {
+        await exportToPostgres();
+        break;
+      }
       const feature = positional(0)[0];
-      if (!feature) fail("usage: vxil export <feature> [--out <file>] [--ndjson] [--urls [--pace <seconds>]]");
+      if (!feature) fail("usage: vxil export <feature> [--out <file>] [--ndjson] [--urls [--pace <seconds>]] \xB7 vxil export auth --include-password-hashes --out <file> (owner only)");
+      if (hasFlag("include-password-hashes")) {
+        await exportPasswordHashes(feature);
+        break;
+      }
       const urls = hasFlag("urls");
       const pace = parsePace(flag("pace"));
       if ("err" in pace) fail(pace.err);
@@ -20957,7 +22137,8 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
         writeFileSync6(resolve7(process.cwd(), out), json2);
         console.log(`exported ${feature} \u2192 ${out}`);
       } else console.log(json2);
-      for (const note of truncationNotes(bundle)) {
+      const notes = truncationNotes(bundle);
+      for (const note of notes) {
         console.error(`vxil: note \u2014 ${note} (the JSON bundle is capped; \`--ndjson\` resumes past the cap)`);
       }
       if (urls) {
@@ -20965,9 +22146,14 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
         if (Array.isArray(downloads)) reportDownloads(tallyDownloads(newDownloadTally(), downloads), started, false);
         if (unresumable) {
           console.error("vxil: the objects table was cut at the 100-row URL page and the server gave no resume cursor \u2014 this bundle holds only the first 100 objects. Re-run with --ndjson (it resumes page by page).");
-          process.exitCode = 1;
+          process.exitCode = worseExportExit(process.exitCode, EXPORT_EXIT_INCOMPLETE);
         }
       }
+      if (notes.length) {
+        const cut = notes.map((n) => n.split(":")[0]);
+        console.error(incompleteTablesMessage(feature, cut, true));
+        process.exitCode = worseExportExit(process.exitCode, EXPORT_EXIT_INCOMPLETE);
+      }
       break;
     }
     case "import": {
@@ -20994,20 +22180,33 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
         console.log(`scaffolded functions/${name}.ts \u2014 declare it in vxil.config.ts \`functions\` and \`vxil push\``);
       } else if (sub === "list") {
         const { api } = requireApi(selector());
-        printEnvelope(await api("GET", "/v1/functions"));
+        const listRes = await api("GET", "/v1/functions");
+        printEnvelope(listRes);
+        if (listRes.status === 200 && listRes.body?.data?.enabled === false) {
+          console.error("vxil: these functions are PAUSED for the whole project (every invoke answers 404) \u2014 a Free project on the production workload, or a plan downgrade. `vxil projects workload <slug> staging` or an upgrade resumes them.");
+        }
       } else if (sub === "delete") {
         if (!name) fail("usage: vxil functions delete <name>");
         const { api } = requireApi(selector(), { write: `functions delete ${name}` });
-        printEnvelope(await api("DELETE", `/v1/functions/${encodeURIComponent(name)}`));
+        const delRes = await api("DELETE", `/v1/functions/${encodeURIComponent(name)}`);
+        const delHook = delRes.status === 200 ? hookReconcileOf(delRes.body.data) : null;
+        if (delHook && delHook.failed > 0) {
+          console.error(`vxil: ${delHook.warning ?? `${delHook.failed} trigger subscription(s) failed to reconcile`} \u2014 ${hookReconcileRemedy(void 0)}`);
+          process.exitCode = 1;
+        }
+        printEnvelope(delRes);
       } else if (sub === "deploy") {
         const { api } = requireApi(selector(), { write: `functions deploy${name ? ` ${name}` : ""}` });
         const cfg = await loadVxilConfig();
         const fns = cfg.functions ?? {};
         const subset = name ? { [name]: fns[name] } : fns;
         if (name && !fns[name]) fail(`function '${name}' not declared in vxil.config`);
-        const r = await planFunctions({ api, functions: subset, cwd: process.cwd(), apply: true });
+        const r = await planFunctions({ api, functions: subset, cwd: process.cwd(), apply: true, force: hasFlag("force") });
         console.log(formatFnChanges(r.changes));
         console.log(`\u2713 deployed ${r.applied} function(s)`);
+        if (r.hookReconcile && r.hookReconcile.failed > 0) {
+          fail(`${r.hookReconcile.warning ?? `${r.hookReconcile.failed} trigger subscription(s) failed to reconcile \u2014 a function may be wired to nothing`}; ${hookReconcileRemedy(name ?? Object.keys(subset)[0])}`);
+        }
       } else if (sub === "logs") {
         if (!name) fail("usage: vxil functions logs <name> [--since <iso>] [--tail]");
         const { api } = requireApi(selector());
@@ -21156,7 +22355,7 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
         else console.log(`\u2713 soft-deleted ${done.deleted} item(s) from ${where}${done.cascaded ? ` (${done.cascaded} cascaded)` : ""}${done.set_null ? ` (${done.set_null} relation(s) set null)` : ""} \u2014 purged after 30 days${done.truncated ? "; stopped at the page cap, re-run to continue" : ""}`);
         break;
       }
-      const { api } = requireApi(selector());
+      const { api } = requireApi(selector(), sub === "reindex" ? { write: `cms reindex ${positional(1)[0] ?? ""}`.trim() } : {});
       if (sub === "status") {
         printEnvelope(await api("GET", "/v1/cms/collections"));
       } else if (sub === "pull") {
@@ -21298,7 +22497,7 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
   keys perms <key_id> [--allow <a,b> | --clear-allow] [--deny <c> | --clear-deny]  \u2014 a key's MCP tool permissions (admin+)
   account [show] \xB7 account set [--locale <code>] [--display-name <n>] \xB7 account password \xB7 logout \xB7 invites [list] \xB7 invites generate [--count <n>] \xB7 invites accept <token|url>
   members [list] \xB7 members invite <email> --role <r> \xB7 members add <email> --role <r> \xB7 members rm <user_id|email> [--yes] \xB7 members uninvite <email|id> [--yes]  \u2014 the bound project's team (session)
-  projects [list] \xB7 projects create <slug> [--name <n>] \xB7 projects rm <slug> [--yes]  \u2014 the account's projects (rm: owner-only, typed slug, irreversible)
+  projects [list] \xB7 projects create <slug> [--name <n>] [--workload <w>] \xB7 projects workload <slug> production|staging|development \xB7 projects rm <slug> [--yes]  \u2014 the account's projects (workload + rm: owner-only; rm: typed slug, irreversible)
   billing [status] \xB7 billing upgrade --tier <free|developer|team|business> [--yes]  \u2014 prints the hosted checkout URL (never opens a browser); --tier free downgrades
   architect "<describe your app>" \u2014 plain English in, a reviewed vxil.config.ts draft out
   plan [--explain] \xB7 push [--dev|--target <name>|--prod] [--server [--resume <apply_id>]] [--no-gen] [--skip-functions] \xB7 pull \xB7 gen [--check] [--offline] [--out <f>] [--no-mcp] [--mcp-out <f>]
@@ -21320,8 +22519,8 @@ export default defineConfig(${JSON.stringify({ features: featBlocks, cms: { coll
   mcp install [--client cursor|claude|vscode] [--project] [--print] [--key <k>] [--scopes a,b] [--name <server>]  \u2014 connect your editor's agent to this backend's MCP server
   dev branch [<name>] [--ttl <h=24>] [--no-env] [--print] | --list | --rm <name> [--yes]
   config get \xB7 users add|list|import \xB7 send \xB7 deliveries \xB7 api <METHOD> <path> ['<json>' | --data '<json>']
-  global: --json (machine-readable + exit codes)`);
-      process.exit(cmd ? 1 : 0);
+  global: --json (machine-readable + exit codes) \xB7 --help / -h on any verb prints its usage (nothing runs)`);
+      process.exit(isGlobalHelp(cmd) ? 0 : 1);
   }
 } catch (e) {
   fail(e.message);
@@ -21361,9 +22560,14 @@ async function runDev(sub) {
       if (!/no dev tenant bound/.test(e.message)) throw e;
     });
     await runDev("up");
-    await runApply(true, { kind: "dev" });
+    const pushCode = await runApply(true, { kind: "dev" });
     await runSeed({ kind: "dev" }, { optional: true });
-    console.log("\u2713 dev reset complete (torn down \u2192 recreated \u2192 pushed \u2192 seeded)");
+    if (pushCode !== 0) {
+      process.exitCode = pushCode;
+      console.log("\u2713 dev reset complete (torn down \u2192 recreated \u2192 pushed \u2192 seeded) \u2014 the push reported a problem above (exit 1)");
+    } else {
+      console.log("\u2713 dev reset complete (torn down \u2192 recreated \u2192 pushed \u2192 seeded)");
+    }
   } else {
     fail("usage: vxil dev up|down|seed|reset|branch");
   }
@@ -21483,7 +22687,7 @@ async function runDevBranch(dash, base2) {
       console.log(`export VXIL_TENANT_ID=${slot.tenant_id}`);
     }
   }
-  if (!hasFlag("no-env") && !hasFlag("print")) runEnvPull({ kind: "dev" });
+  if (!hasFlag("no-env") && !hasFlag("print")) await runEnvPull({ kind: "dev" });
   console.log("  note: re-run `vxil gen` \u2014 generated types drift across branch schemas.");
 }
 function currentGitBranch() {
@@ -21587,10 +22791,11 @@ async function runConfigDraft(sub, feature) {
   if (jsonOut) console.log(JSON.stringify({ feature, duplicated_from: v.version, manifest: d.manifest }, null, 2));
   else console.log(`\u2713 copied ${feature} v${v.version} into the draft \u2014 NOT live; edit it via \`vxil config draft show ${feature} --json > draft.json\` + \`vxil config draft save ${feature} --file draft.json\`, then publish`);
 }
-function runEnvPull(sel) {
+async function runEnvPull(sel) {
   const t = resolveTargetOrFail(sel);
   if (!t.apiKey) fail(noKeyMessage(t));
   announceTarget(t, "env pull");
+  await assertKeyTenant(t, makeApi({ apiKey: t.apiKey, baseUrl: t.baseUrl }));
   const tenantId = t.tenantId && t.tenantId !== "(unknown)" ? t.tenantId : void 0;
   const updates = envUpdates({
     apiKey: t.apiKey,
@@ -22108,11 +23313,15 @@ function migrateUsage() {
           + migrate/vxil.config.suggested.ts + migrate/RESIDUALS.md
           (credit seeding is opt-in: tables named in migrate/payments.json)
   schema  [--apply]           create the plan's cms + vector-search collections (default: dry-run diff; additive only)
-  data    [--execute] [--only users,cms,vectors,files,payments|<table>,\u2026] [--resume]
+  data    [--execute] [--only users,credentials,cms,vectors,files,payments|<table>,\u2026] [--resume]
           the ordered backfill users \u2192 cms (FK order) \u2192 vectors \u2192 files \u2192 payments-credits
           (DEFAULT DRY-RUN \u2014 zero writes; resumable via migrate/state.json)
           [--since <iso-time> [--prune]]  the incremental pass: re-read, write only what
           changed since then (+ --prune: delete what the source no longer has)
+          live-app migration (supabase): [--with-password-hashes] keep every password (bcrypt,
+          rehashed at each user's first sign-in) \xB7 [--oidc-issuer https://<ref>.supabase.co/auth/v1]
+          link users for the installed-app session hand-over \xB7 [--file-links shared-link] stored
+          public file URLs become stable shared links instead of object ids
   verify  reconcile source vs target counts + re-links + restate the residuals (exit 1 on deltas)
   payments --from-provider stripe|paddle|paypal|revenuecat (--customers <file.csv> | --all) [--dry-run]
           backfill SUBSCRIPTIONS through the server sync leg (the project's own provider keys; resumable via
@@ -22207,9 +23416,17 @@ ${migrateUsage()}`);
     if (sub === "data") {
       const only = flag("only")?.split(",").map((s) => s.trim()).filter(Boolean);
       const since = flag("since");
+      const fileLinks = flag("file-links");
+      if (fileLinks !== void 0 && fileLinks !== "shared-link" && fileLinks !== "object_id") {
+        fail(`--file-links must be shared-link or object_id (got '${fileLinks}')`);
+      }
+      const oidcIssuer = flag("oidc-issuer");
       const results = await runMigrateData({ api, adapter, cwd, log }, {
         execute: hasFlag("execute"),
         resume: hasFlag("resume"),
+        ...hasFlag("with-password-hashes") ? { withPasswordHashes: true } : {},
+        ...oidcIssuer !== void 0 ? { oidcIssuer } : {},
+        ...fileLinks !== void 0 ? { fileLinks } : {},
         ...only?.length ? { only } : {},
         ...hasFlag("assume-schema") ? { assumeSchema: true } : {},
         ...since !== void 0 ? { since } : {},